Danijel Martinek
32d20872e3
Closes the PRD-lifecycle gap surfaced by the user: when sandcastle
finishes an epic's last task, the seed PRD should auto-flip from
approved -> shipped. Builds the mechanism, wires it into the work
CLI + state index + reviewer prompt + docs.
scripts/work/prd-ship.mjs (new):
- parseFrontmatter / serializeFrontmatter — minimal YAML-ish parser
sufficient for PRD frontmatter (scalar + list shapes)
- flipPrdStatus — pure function: takes PRD text, returns new text
with status=shipped + shipped=<date> + optional shipping-commits.
Refuses to flip draft, idempotent fail-soft on already-shipped,
rejects unexpected statuses
- deriveShippingCommits — best-effort git log of the linked epic
folder for the --auto-commits flag
- findPrdPath — id -> path lookup under docs/work/prds/
- runCli — wiring for `pnpm work prd-ship <id> [--commits|--auto-commits]`
scripts/work/prd-ship.test.mjs (new, 17 tests):
- Frontmatter parser handles scalars + lists + missing frontmatter
- flipPrdStatus covers all transitions + refusals + body/key preservation
- findPrdPath + serializeFrontmatter coverage
scripts/work/state-builder.mjs:
- Epic entries gain a `prd` field
- New computeNeedsPrdShip surfaces epics done with PRD status not yet
shipped: state.needs_prd_ship[] with action commands
scripts/work/cli.mjs:
- New subcommand `pnpm work prd-ship <id>`
.sandcastle/reviewer.prompt.md:
- "Epic close-out: PRD status flip" section instructing reviewer to
check _state.json.needs_prd_ship and run the suggested action
- JSON output extends with prd_shipped: "<id>" | null
docs/work/README.md:
- "PRD lifecycle" section documenting the 4 statuses + auto-flip
Future PRDs follow the lifecycle automatically: decomposer refuses
draft, human flips to approved, sandcastle ships the epic, reviewer
runs prd-ship on the final task, PRD lands as shipped with its
commit trail.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
27 lines
1.4 KiB
Markdown
27 lines
1.4 KiB
Markdown
# 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.
|