Initial commit

docs/work/README.md

@@ -0,0 +1,26 @@
+# docs/work — the local task system
+
+Filesystem-backed Epic/Story/Task hierarchy used by AI agents and humans alike.
+See `docs/architecture/agent-first-workflow-and-conformance.md` for the full
+design. Until the `work-system-v1` epic ships orchestration tooling, this
+folder is human-driven — agents read the files for context, humans flip
+checkboxes.
+
+## Layout
+
+- `prds/<date>-<slug>.prd.md` — source PRDs
+- `<epic-slug>/_epic.md` — one folder per epic
+- `<epic-slug>/<story-slug>/_story.md` — one folder per story
+- `<epic-slug>/<story-slug>/<task-slug>.task.md` — one file per task
+- `_templates/` — copy-paste templates (added in work-system-v1)
+- `_state.json` — derived index (added in work-system-v1)
+
+## PRD lifecycle
+
+PRD `status` frontmatter field: `draft → in-review → approved → shipped`.
+
+- **draft → in-review** — author flips when ready for review (manual)
+- **in-review → approved** — human reviewer flips on acceptance (manual)
+- **approved → shipped** — auto-flipped by `pnpm work prd-ship <prd-id>` when the seed epic finishes. The state-builder surfaces this signal under `_state.json` → `needs_prd_ship[]` so the orchestrator (or a reviewer running the sandcastle workflow) can act on it.
+
+The decomposer refuses to run on `draft` PRDs. Once approved, the seed epic is generated; once the epic completes, the PRD is automatically flipped to `shipped` along with its commit list.