117 lines
4.3 KiB
Markdown
117 lines
4.3 KiB
Markdown
# `.w4c/` — project folder contract
|
|
|
|
Everything W4C needs to treat a repository as a **project** lives here. The
|
|
folder is committed with the repository, so project metadata and seed assets
|
|
travel with the code.
|
|
|
|
```
|
|
.w4c/
|
|
├── project.json # project metadata (source of truth in-repo)
|
|
├── template.json # present only in template repositories
|
|
├── preview.svg # catalog thumbnail for templates
|
|
├── diagrams/
|
|
│ └── architecture.excalidraw.json # Excalidraw scenes
|
|
├── boards/
|
|
│ └── roadmap.json # board columns + seed tasks
|
|
└── workflows/
|
|
└── ci-build.yaml # workflow definitions (same YAML shape as the workflows module)
|
|
```
|
|
|
|
## `project.json`
|
|
|
|
Marks the repository as a project and carries its metadata. A repository
|
|
without this file (or without a server-side project record) is just a
|
|
repository — selecting it optionally creates a project from it.
|
|
|
|
```jsonc
|
|
{
|
|
"schema": 1,
|
|
"name": "Website & Resource Research",
|
|
"description": "Audit an existing website and plan a redesign.",
|
|
"agentId": "w4c-startup", // default agent for project chats
|
|
"tags": ["web", "research"],
|
|
"source": { "template": "wiz4apps/templates.WebsiteResearch" }
|
|
}
|
|
```
|
|
|
|
## `template.json` (templates only)
|
|
|
|
Catalog descriptor for the template picker on the start page: the dialog
|
|
fields the user fills in, the prompt assembled at start, and the list of
|
|
elements to import.
|
|
|
|
```jsonc
|
|
{
|
|
"schema": 1,
|
|
"id": "website-research",
|
|
"title": "Website & Resource Research",
|
|
"description": "…",
|
|
"thumbnail": ".w4c/preview.svg",
|
|
"agentId": "w4c-startup",
|
|
"defaultName": "website-research", // default repository name in the dialog
|
|
"skills": ["project-bootstrap"], // marketplace skills installed + attached on create
|
|
"fields": [
|
|
{ "key": "siteUrl", "label": "Main page URL", "type": "text", "required": true }
|
|
],
|
|
"promptTemplate": "…",
|
|
"elements": [
|
|
{ "kind": "diagram", "name": "Site map & architecture", "path": ".w4c/diagrams/architecture.excalidraw.json" }
|
|
]
|
|
}
|
|
```
|
|
|
|
`fields[].type` is one of `text | textarea | number | select | boolean`.
|
|
`select` fields also declare `options`; other fields may declare `default`
|
|
and `placeholder`. `promptTemplate` supports `{{key}}` interpolation plus the
|
|
service tokens `{{title}}`, `{{repoFullName}}` and `{{elements}}`.
|
|
|
|
If `elements` is omitted, the importer may discover assets by folder
|
|
convention (`diagrams/`, `boards/`, `workflows/`).
|
|
|
|
## Elements
|
|
|
|
| Kind | Folder | Format |
|
|
|------|--------|--------|
|
|
| `diagram` | `diagrams/` | Excalidraw scene JSON (`{"type":"excalidraw", ...}`) |
|
|
| `board` | `boards/` | `{ name, columns[], tasks[] }` |
|
|
| `workflow` | `workflows/` | Workflow YAML (see `w4c-workflows-api` `WorkflowDefinition`) |
|
|
| `widget` | `widgets/` | Widget definition JSON (reserved) |
|
|
|
|
## `boards/roadmap.json` — the build stages
|
|
|
|
The board seed is the canonical **layer → task** list for the project. The
|
|
Startup Creator (`w4c-startup`) reads it on the first turn and materialises one
|
|
board card (repository issue) per entry in the project's own repository, then
|
|
hands the user over to My Boards. A card is only "done" when its acceptance
|
|
criterion has been shown at runtime.
|
|
|
|
```jsonc
|
|
{
|
|
"schema": 1,
|
|
"name": "Project roadmap",
|
|
"columns": [ // the board's real grouping
|
|
{ "id": "high", "name": "High Priority" },
|
|
{ "id": "low", "name": "Low Priority" },
|
|
{ "id": "none", "name": "No Priority" },
|
|
{ "id": "done", "name": "Done" }
|
|
],
|
|
"tasks": [
|
|
{
|
|
"icon": "🗺️", // unicode icon, prefixed to the card title
|
|
"title": "Architecture diagram — architecture, ERD and key flows",
|
|
"column": "high", // target column id
|
|
"labels": ["High Priority"],
|
|
"body": "…goal, deliverables, acceptance criteria, references…"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Keep the layer set complete: plan, design mockups, architecture diagram,
|
|
database & forms, backend/API, frontend code, admin, control panel, workflows,
|
|
deploy and quality. Agent provisioning is deliberately **not** a bootstrap
|
|
stage — creating a specialist agent is a follow-up the user starts on purpose.
|
|
|
|
Element import from a repository is not active yet; the descriptors above are
|
|
the stable contract for when it is.
|