forge-prd

Forge PRD generator (WP3)

A Forge PRD is a structured product-requirements document the Lead writes before a non-trivial build — it forces the scope, acceptance criteria, and test plan to be explicit before agents start touching files. It is rendered to markdown by .claude/forge-bin/forge-prd.cjs, a zero-dependency writer that stores both the markdown and its structured JSON meta under .claude/forge-prd/.

When the Lead generates one

• Before a non-trivial feature/build (new module, new integration, anything touching 3+ files) — not for a 1-2 line fix.
• Typically right after Deep Learn Mode (forge-deeplearn skill) so the PRD's risks/architecture sections are grounded in the real codebase, not guesswork.
• Not needed when the task is a small, well-understood change or a PRD for this exact scope already exists — check .claude/forge-prd/index.jsonl first.

How

1. The Lead produces the PRD content itself — real analysis, not filler — as a JSON object:

   {
     "prd_id": "prd-<short-slug>",
     "title": "…", "project": "…",
     "sections": {
       "goal": "…", "users": ["…"], "problem": "…", "solution": "…", "modules": ["…"],
       "user_stories": ["…"], "mvp_scope": "…", "non_goals": "…", "architecture": "…",
       "risks": ["…"], "test_plan": "…", "roadmap": "…",
       "acceptance_criteria": [
         { "id": "ac-1", "text": "…", "owner": "coder", "required_tests": ["…"] }
       ]
     }
   }
   

   Each section value may be a plain string or an array of strings (rendered as bullets). A section the Lead genuinely has nothing for is simply omitted — it renders honestly as _(not specified)_, never invented.
2. Write it:

   node .claude/forge-bin/forge-prd.cjs write '<prd-json>' --run <run_id> --tickets
   

   • --tickets auto-creates one ticket per acceptance_criteria entry (.claude/forge-tickets/tk-<prd_id>-<n>, status: "open") — these feed the Ticket Board and the review gates the same as any other ticket.
   • --run <run_id> logs prd_generated (and one ticket_created per ticket) to that run's dashboard events.
   • Dry-run a preview without writing anything: node .claude/forge-bin/forge-prd.cjs render '<prd-json>'.