fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 7 Packages Projects Releases Wiki Activity
Files
a3505f2e6990cf6d33db118f40b62e5f6c2e3a82
agentic-dev/docs/work/README.md
Danijel Martinek 32d20872e3 feat(work): pnpm work prd-ship + auto-flip integration in sandcastle 
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>
2026-05-13 16:51:48 +02:00

1.4 KiB
Raw Blame History

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.