• .claude/memory-bank/org-context.md

• Create new PRDs via conversational discovery + iterative criticism
• Resume interrupted PRD sessions
• Sync existing PRDs to spec groups
• Amend PRDs with implementation discoveries
• Status check on PRD state

1. Generate PRD ID: Prompt user for a slug (e.g.,

   auth-revamp

   ,

   notifications

   )
2. Create directory:

   mkdir -p .claude/prds/<prd-id>/

3. Dispatch PRD Writer (discovery mode):

   Task: prd-writer
   Prompt: |
     <context>
     Mode: discovery
     PRD ID: <prd-id>
     User request: <original user request>
     Cold start context:
       - tech.context.md: <contents>
       - org-context.md: <contents>
       - Existing PRDs: <list of .claude/prds/*/prd.md>
     Template: .claude/templates/prd-phase1.template.md
     </context>
   
     Conduct a conversational discovery interview with the human.
     Follow D-004 (13 context dimensions), D-005 (cold start), D-006 (conversational),
     D-007 (front-loaded input, natural breakpoints).
   
     After discovery completes, produce a PRD in D-034 format.
     Save to .claude/prds/<prd-id>/prd.md

4. PRD Writer produces draft: Saved to

   .claude/prds/<prd-id>/prd.md

Applicability: MANDATORY for oneoff-spec workflows. SKIP for oneoff-vibe.

• Scan all sections for references to existing services, endpoints, data stores, and external systems
• Extract module/package names, route paths, config keys, and event names mentioned or implied

Task: explore
Prompt: |
  Investigate the codebase for integration surfaces relevant to the PRD at .claude/prds/<prd-id>/prd.md.

  Search for:
  1. Existing API endpoints, routes, or service interfaces that the proposal touches or extends
  2. Shared database tables, schemas, or data models referenced
  3. Configuration and environment variables involved (e.g., in .env files, config modules)
  4. Event systems at boundaries (SSE, WebSocket, pub/sub, message queues)
  5. Import/export relationships with modules the feature touches

  Return a structured Integration Surface Report with:
  - Touched Systems: list of existing systems/services with how they are touched
  - Existing Contracts: API specs, type definitions, schemas already in place
  - Potential Conflicts: areas where the proposed feature may conflict with existing behavior
  - Configuration Dependencies: env vars, feature flags, config files involved
  - Cross-Cutting Concerns: shared state, caching, event systems, logging pipelines

  Return structured findings, not raw code.

Task: prd-writer
Prompt: |
  <context>
  Mode: amendment
  PRD path: .claude/prds/<prd-id>/prd.md
  Pass number: 0 (pre-critique integration surface population)
  Integration Surface Report:
    <structured findings from Explore subagent>
  </context>

  Add the exploration findings to the "Integration Surface" section of the PRD.
  Populate: Touched Systems table, New Boundaries Created, Configuration Dependencies,
  and Cross-Cutting Concerns subsections.

  Do NOT modify any other section of the PRD.
  Save the complete amended PRD to disk.

Applicability: Optional for all workflows. Human chooses whether to provide TAD input. Purpose: Allow humans to front-load architectural decisions before spec authoring, reducing investigation findings downstream.

Would you like to provide technical architecture input before critique begins?

This optional TAD (Technical Architecture Design) phase lets you specify:
  - Key architectural decisions (e.g., database choice, API style, auth strategy)
  - System design constraints (e.g., latency requirements, scaling targets)
  - Technology choices (e.g., framework, language, infrastructure)
  - Integration patterns (e.g., sync vs async, event-driven vs request-response)

This input will be available to the spec-author agent as context, potentially
reducing downstream investigation findings.

[Provide TAD input / Skip TAD]

• Record the TAD input in the PRD under a

  ## Technical Architecture Design

  section
• Dispatch PRD Writer (amendment mode) to integrate the TAD into the PRD:

Task: prd-writer
Prompt: |
  <context>
  Mode: amendment
  PRD path: .claude/prds/<prd-id>/prd.md
  Pass number: 0 (TAD integration)
  TAD Input:
    <human's technical architecture input>
  </context>

  Add the TAD input to the "Technical Architecture Design" section of the PRD.
  Integrate architectural decisions with existing Integration Surface findings.
  Do NOT modify any other section of the PRD.
  Save the complete amended PRD to disk.

• The TAD input will be passed through to spec-author context when

  /spec

  is invoked

Trigger: Runs after the gather-criticize loop exits (after Phase 1.5, before Phase 2). Purpose: Generate preliminary visual artifacts from PRD content.

undefined

• Architecture Overview: .claude/docs/structured/generated/component-c4.mmd
• User Flow Sequences: .claude/docs/structured/generated/flow-*.mmd
• Security Boundaries: .claude/docs/structured/generated/security.mmd

4g. **Proceed to Phase 2** (Critique Loop).

1. Initialize pass counter:

   pass = 1

2. Dispatch 4 critics in parallel (D-001: independence):

   # Dispatch all four in parallel -- DO NOT serialize
   Task: prd-critic (perspective: business)
   Task: prd-critic (perspective: technical)
   Task: prd-critic (perspective: security)
   Task: prd-critic (perspective: edge-case)
   
   Each critic receives ONLY:
     (1) Current PRD document (read from .claude/prds/<prd-id>/prd.md)
     (2) The Decisions Log section from the PRD
     (3) Calibration set from .claude/templates/critic-calibration.md
     (4) Its perspective parameter
   
   DO NOT include findings from any other critic.

3. Collect findings from all four critics
4. Aggregate findings by severity

1. If any Critical or High findings exist:
   • Present as a single batch to the human, sorted by severity (Critical first, then High), then by critic type
   • Human resolves each finding: accept (amend PRD), reject (not a real gap), or defer (out of scope)
2. If any Medium findings exist:
   • Present Medium findings to the human (after Critical/High are resolved)
   • Offer batch shortcut: "Accept all Medium findings" (excludes security-tagged findings)
   • Security-tagged findings at any severity are surfaced separately and require explicit individual confirmation
   • If batch-accepted, log each decision individually in the Decisions Log with specific finding IDs
   • Human resolves each (or uses batch shortcut)
3. Low findings: Summarize in a single block. Do NOT present individually.
4. Dispatch PRD Writer (amendment mode):

   Task: prd-writer
   Prompt: |
     <context>
     Mode: amendment
     PRD path: .claude/prds/<prd-id>/prd.md
     Pass number: <pass>
     Resolutions:
       <list of finding_id, resolution, rationale for each resolved finding>
     </context>
   
     Amend the PRD with all resolutions.
     Update the Decisions Log with structured entries for each finding.
     Save the complete amended PRD to disk.

1. Check exit condition (D-002):
   • If all findings from this pass are Low severity:
     • Present remaining Low findings to the human
     • Ask: "All remaining findings are Low severity. Exit the loop and finalize the PRD? [Y/n]"
     • If human confirms: Exit loop (go to Phase 5)
     • If human rejects: Continue loop (back to step 6 with

       pass += 1

       )
   • If any non-Low findings remain: Continue loop (back to step 6 with

     pass += 1

     )
2. Max pass check (EC-4):
   • If

     pass >= 5

     :
     • Present summary: "After 5 passes, N Medium+ findings remain."
     • Offer options: (1) Resolve remaining findings, (2) Accept current state and proceed, (3) Defer remaining findings
     • Human decides

1. Update org-context: Dispatch PRD Writer to update

   .claude/memory-bank/org-context.md

   with new stable facts discovered during the session
2. Create spec group (optional):
   • Prompt: "Create a spec group from this PRD? [Y/n]"
   • If yes: Create

     .claude/specs/groups/sg-<prd-id>/

     with

     manifest.json

     and

     requirements.md

     extracted from the PRD
3. Report completion:

   PRD complete: .claude/prds/<prd-id>/prd.md
   Passes: <N>
   Findings resolved: <count>
   Decisions Log entries: <count>
   
   Next steps:
     1. Review PRD: .claude/prds/<prd-id>/prd.md
     2. Create spec group: /prd sync <prd-id> (if not already created)
     3. Author spec: /spec sg-<prd-id>

1. Read PRD from

   .claude/prds/<prd-id>/prd.md

2. Determine re-entry point:
   • If PRD has

     <!-- RESUME POINT: ... -->

     comment: resume interview from that point
   • If PRD is complete but has no Decisions Log entries: start critique loop (Phase 2)
   • If PRD has Decisions Log entries: start a new critique pass
3. Continue from the appropriate phase

/prd

1. Read PRD from

   .claude/prds/<prd-id>/prd.md

2. Dispatch

   prd-reader

   agent to extract requirements:

   Task: prd-reader
   Prompt: |
     Read PRD from .claude/prds/<prd-id>/prd.md
     Extract requirements, constraints, assumptions, success criteria
     Convert to EARS format
     Create spec group with requirements.md

3. Create spec group directory:

   .claude/specs/groups/sg-<prd-id>/

4. Generate

   manifest.json

   with PRD link
5. Generate

   requirements.md

   from extracted requirements
6. Set

   prd_version

   and

   prd_content_hash

   in requirements.md YAML frontmatter:

   • prd_version

     : The PRD's version field value

   • prd_content_hash

     : First 8 characters of SHA-256 hex digest computed over the PRD body content (everything after the closing

     ---

     of the YAML frontmatter block; frontmatter itself is excluded)
7. Set

   review_state: DRAFT

/prd sync

requirements.md

1. Read PRD from

   .claude/prds/<prd-id>/prd.md

2. Re-extract requirements from the current PRD
3. Compare newly extracted requirements against existing

   requirements.md

   :
   • Preserved: Manual additions (requirements not present in the PRD but added by the spec author) are kept
   • Flagged: Changed or removed PRD requirements are flagged for human review (not silently deleted)
   • Conflicts: When a manual addition conflicts with a newly extracted PRD requirement (both cover the same concern with different constraints), flag for human review with both versions presented side by side
4. Update

   prd_version

   and

   prd_content_hash

   in frontmatter to reflect the current PRD state

PRD synced: .claude/prds/<prd-id>/prd.md

Created spec group: sg-<prd-id>
  - N requirements extracted
  - requirements.md generated
  - prd_version: <version>
  - prd_content_hash: <8-char hash>

Next steps:
  1. Review requirements: .claude/specs/groups/sg-<prd-id>/requirements.md
  2. Run /spec sg-<prd-id> to create spec

/prd push

1. Read current PRD from

   .claude/prds/<prd-id>/prd.md

2. Read spec group requirements (if linked)
3. Dispatch

   prd-amender

   agent:

   Task: prd-amender
   Prompt: |
     PRD path: .claude/prds/<prd-id>/prd.md
     Spec group: <linked spec group if any>
     Identify implementation discoveries:
       - New requirements discovered
       - Assumptions invalidated
       - Constraints discovered
     Update PRD with amendments
     Update Amendment Log with D-028 format entries

4. Report changes
5. Staleness warning: After the PRD version is incremented, check for linked spec groups:
   • Find spec groups where

     requirements.md

     has

     prd_path

     pointing to this PRD
   • Compare

     prd_version

     in the spec group's

     requirements.md

     to the new PRD version
   • If versions do not match, emit a warning:

     "Spec group sg-XXX requirements.md is based on PRD vX but PRD is now vY. Run

     /prd sync

     to re-extract requirements."

   • Include a diff summary of what changed in the PRD (sections added, modified, or removed)
   • Cosmetic amendments: Even cosmetic changes (wording, formatting) trigger the staleness warning because the version/hash mechanism does not distinguish cosmetic from substantive changes. The diff summary enables the human to quickly judge whether re-sync is needed or the warning can be dismissed.

1. Read PRD from

   .claude/prds/<prd-id>/prd.md

2. Parse frontmatter for version and state
3. Count Decisions Log entries
4. Check for linked spec groups

PRD Status: <prd-id>

  Title: <title from frontmatter>
  Version: <version>
  State: <state>
  Decisions Log: <N> entries
  Last Updated: <date>

  Linked Spec Groups:
    - sg-<id> (review_state: <state>)

• Present to human: "All four critics found no issues. The PRD may be complete."
• Request exit confirmation
• Exit loop if confirmed

• Continue with findings from the remaining critics
• Note the failed critic in the pass summary: "Note: [perspective] critic failed. Will retry on next pass."
• On the next pass, retry the failed critic alongside all others

• Human's judgment takes precedence
• Record the override in the Decisions Log with rationale

• Present summary: "After 5 passes, N Medium+ findings remain: [list]"
• Options: (1) Resolve remaining, (2) Accept current state, (3) Defer to implementation
• Human decides

/prd <prd-id>

• Missing sections: Resume interview
• Complete draft, no critiques: Start critique loop
• Has critique history: Start new critique pass with amended PRD

• Human corrects the assumption
• Org-context.md is updated with the correction at session end

Batch shortcut: "Accept all Medium findings" (excludes security-tagged findings)

• TECH-003: <one-line summary>
• BIZ-002: <one-line summary>
• SEC-002: <one-line summary>
• EDGE-003: <one-line summary>

• accept: Amend the PRD to address this
• reject: Not a real gap (provide rationale)
• defer: Acknowledged but out of scope for this PRD

undefined

1. Recommended action (accept/reject/defer verb)
2. Impact indicator (one-sentence consequence if unaddressed)
3. Finding summary (what was identified)
4. Detail/evidence (collapsed/optional for Medium and Low)

• PRD created at

  .claude/prds/<prd-id>/prd.md

• Frontmatter:

  version: 1.0

  ,

  state: draft

• After loop exits:

  state: reviewed

• Spec group created with

  review_state: DRAFT

• Manifest linked to PRD

• PRD version incremented
• Amendment Log updated
• PRD state set to

  draft

  (agent change, needs human review)