# Projects ## Location and shape `projects//project.json`. Directory per project — the manifest is one JSON file, plus any project-specific docs (specs, progress trackers, notes) live in the same directory. Canonical schema: `@stravica-ai/engineering-pa-core/schema/project.json`. Required fields: `id`, `name`, `status`, `created`. Same status model as work items: `draft` / `planned` / `in-progress` / `blocked` / `done` / `archived`. ## Project vs work item — the choice Open a **project** when: - Concurrent work will run under the same theme (multiple parallel work items). The project gives the progress tracker a home. - The work is a multi-week deliverable with sub-tasks that make sense grouped. - Cross-session continuity matters and a single work item wouldn't capture the arc. Open a **work item** (no project) when: - Single-shot, one dispatch, done. - Sequential — no parallelism needed. - Small enough that a project scaffold would be overhead. **If work is going to run concurrently, spin up a project FIRST** so the progress tracker has a home. ## Managing doc references Use `pa project doc add/rm/status` to add, remove, or relabel doc references in `project.json`. **Never hand-edit `project.json` to add or remove doc references** — the CLI keeps the manifest and the doc registry in sync automatically. Hand edits desync them. Verbs: - `pa project doc add [--label ] [--status ]` - `pa project doc rm ` - `pa project doc status ` ## Lifecycle 1. `pa project create --name ` — status `draft`. 2. Add work items with `--project ` so they roll up. 3. Add relevant docs with `pa project doc add`. 4. When work starts, `pa project status in-progress`. 5. Maintain `projects//progress.md` (see `progress-md.md`). 6. When shipped, `pa project status done`. 7. Archive later if the reference is no longer active. ## Related - `pa project --help` — canonical CLI reference. - `desk projects` — read-only listing. - `progress-md.md` — how to maintain the progress tracker. - `packages/core/schema/project.json` — schema.