design

Design Phase

Generate technical design for the active spec after explicit requirements artifact approval. You are a coordinator, not an architect -- delegate ALL work to the architect-reviewer subagent.

Read ${CLAUDE_PLUGIN_ROOT}/references/normal-mode-gates.md before gathering context.

Checklist

Create a task for each item and complete in order:

1. Gather context -- resolve spec, read requirements and research
2. Interview gate -- critical frontier and approval, or authorized quick bypass
3. Execute design -- dispatch architect-reviewer via team
4. Artifact review -- automatic spec-reviewer loop in authorized quick mode
5. Walkthrough & approval -- display summary, get user approval
6. Finalize -- update state, commit, stop

Step 1: Gather Context

1. If $ARGUMENTS contains a spec name, use ralph_find_spec() to resolve it; otherwise use ralph_resolve_current(). Store the resolved spec directory as SPEC_PATH.
2. If no active spec, error: "No active spec. Run /ralph-specum:new first."
3. Check the resolved spec directory exists
4. Check requirements.md exists. If not, error: "Requirements not found. Run /ralph-specum:requirements first."
5. Read .ralph-state.json, reject simultaneous exact --quick and --interactive, and normalize persistent mode with phase_gate.py mode.
6. When normalized quickMode is false, require explicit requirements artifact approval before clearing its approval flag. Exact quick mode continues with the validated file.
7. Clear the approval flag through the locked helper while preserving every other field:

   python3 "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/locked-state.py" merge \
     --state "$SPEC_PATH/.ralph-state.json" \
     --set "awaitingApproval=false"
   

8. Read context: requirements.md (required), research.md (if exists), .progress.md.
9. Run any missing applicable skill discovery pass. When research exists, pass 2 must be present.
10. Run prototype record selection before design generation:

python3 "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/prototype-records.py" select-downstream --base-path "$SPEC_PATH" --state "$SPEC_PATH/.ralph-state.json" --target design --target 'transition:requirements->design' --path requirements.md --path design.md

1. Use only valid, gateApproved: true, non-superseded prototype evidence that affects design. Exclude skipped, failed, inconclusive, malformed, superseded, and explicitly excluded records.
2. If selection reports an activePrototypes blocker for the design transition, stop before Step 2 and report the active prototype ID, blocker reason, and resume command.
3. If selection reports stale requirements, research, design, or task indexes that affect this design generation, stop and route to the earliest stale phase or task. Do not generate design from stale artifacts.
4. Read the matching targetDecisions entries. Proven unrelated work may continue only when each entry has proofAvailable: true and eligible: true; this proves no active blocker, stale input, or approved transfer path overlaps design. Missing or unavailable proof blocks conservatively.