Help us improve
Share bugs, ideas, or general feedback.
From ralph-specum
Generates technical design for active or specified spec from requirements. Coordinates optional interview, delegates to architect-reviewer, reviews artifacts, walkthroughs summary, and finalizes on approval.
npx claudepluginhub tzachbon/smart-ralph --plugin ralph-specumHow this command is triggered — by the user, by Claude, or both
Slash command
/ralph-specum:design spec-nameThis command is limited to the following tools:
The summary Claude sees in its command listing — used to decide when to auto-load this command
# Design Phase Generate technical design for the active spec. Running this command implicitly approves requirements. You are a **coordinator, not an architect** -- delegate ALL work to the `architect-reviewer` subagent. ## Checklist Create a task for each item and complete in order: 1. **Gather context** -- resolve spec, read requirements and research 2. **Interview** -- brainstorming dialogue (skip if `--quick`) 3. **Execute design** -- dispatch architect-reviewer via team 4. **Artifact review** -- spec-reviewer validation loop (only if `--quick`) 5. **Walkthrough & approval** -- displ...
/designerExplores requirements and designs a solution approach, producing an approved specification file for /planner to implement.
/designGuides the user through creating a Technical Design Document following a structured skill chain, with mandatory approval gates at each step.
/techspecInforms users this command is deprecated, directs to /humaninloop:plan for unified technical specification workflow, and stops execution.
/designGenerates technical design document from requirements (topic or path), with architecture diagrams, components, data models, error handling. Investigates codebase, creates frontend mockups if needed, saves to .claude/specs/{topic}/design.md
/interview-specConducts deep iterative interviews with non-obvious questions and proactive research to create comprehensive spec documents for AI implementation.
/designGenerates an architecture and technical specification document from a Phase 1 definition file, covering high-level design, inline ADRs, file manifest, and testing strategy as Phase 2 of the AgentSpec workflow.
Share bugs, ideas, or general feedback.
Generate technical design for the active spec. Running this command implicitly approves requirements. You are a coordinator, not an architect -- delegate ALL work to the architect-reviewer subagent.
Create a task for each item and complete in order:
--quick)--quick)$ARGUMENTS contains a spec name, use ralph_find_spec() to resolve it; otherwise use ralph_resolve_current()requirements.md exists. If not, error: "Requirements not found. Run /ralph-specum:requirements first.".ralph-state.json; clear approval flag: awaitingApproval: falserequirements.md (required), research.md (if exists), .progress.mdCheck if --quick appears in $ARGUMENTS. If present, skip to Step 3.
Parse Intent Classification and all prior interview responses to skip already-answered questions.
Intent-Based Question Counts:
Apply adaptive dialogue from ${CLAUDE_PLUGIN_ROOT}/skills/interview-framework/SKILL.md. Ask context-driven questions one at a time.
Design Exploration Territory (hints, not a script):
After dialogue, propose 2-3 architectural approaches. Examples (illustrative only):
Append to .progress.md under "Interview Responses":
### Design Interview (from design.md)
- [Topic 1]: [response]
- Chosen approach: [name] -- [brief description]
Pass combined context to delegation prompt as "Interview Context".
Follow the full team lifecycle:
TeamDelete() before anything else. This releases whatever team the session is currently leading (could be from any prior phase). Errors mean no team was active -- harmless, proceed.TeamCreate(team_name: "design-$spec")TaskCreate(subject: "Generate technical design for $spec", activeForm: "Generating design")Task(subagent_type: architect-reviewer, team_name: "design-$spec", name: "architect-1") — delegate with requirements, research, and interview context. Instruct to design architecture with mermaid diagrams, component responsibilities, technical decisions with rationale, file structure, error handling, test strategy. Output to ./specs/$spec/design.md.SendMessage(type: "shutdown_request", recipient: "architect-1")./specs/$spec/design.md.TeamDelete().Fallback: If TeamCreate fails with "already leading" error, call TeamDelete() and retry TeamCreate once. If still fails, fall back to direct Task(subagent_type: architect-reviewer) call.
If NOT --quick, skip to Step 5.
Invoke spec-reviewer via Task tool. Follow the standard review loop:
Review delegation: Include full design.md content, iteration count, prior findings. Upstream: research.md + requirements.md.
Revision delegation: Re-invoke architect-reviewer with reviewer feedback and requirements.md upstream context. Focus on specific issues.
Error handling: Reviewer no signal = REVIEW_PASS. Agent failure = retry once, then use original.
Read ./specs/$spec/design.md and display:
Design complete for '$spec'.
Output: $PWD/specs/$spec/design.md
## What I Designed
**Approach**: [1-2 sentences from Overview]
**Components**:
- [Component A]: [brief purpose]
- [Component B]: [brief purpose]
**Key Decisions**:
- [Decision 1]: [choice made]
- [Decision 2]: [choice made]
**Files**: [X] to create, [Y] to modify
If --quick, skip to Step 6.
Ask ONE question: "How do you want to proceed?" with these options via AskUserQuestion:
If "Approve": proceed to Step 6. If "Run review": Invoke spec-reviewer via Task tool with full design.md content (upstream: research.md + requirements.md). Display findings table. If REVIEW_PASS, note it. If REVIEW_FAIL, show feedback. Then loop back to this same 3-choice question (user decides next action). If "Request changes" or "Other":
.ralph-state.json (preserve all existing fields):
jq '. + {"phase": "design", "awaitingApproval": true}' \
"$SPEC_PATH/.ralph-state.json" > "$SPEC_PATH/.ralph-state.json.tmp" && \
mv "$SPEC_PATH/.ralph-state.json.tmp" "$SPEC_PATH/.ralph-state.json"
.progress.md: mark requirements as implicitly approved, set current phaseRead commitSpec from .ralph-state.json. If true:
git add ./specs/$spec/design.md
git commit -m "spec($spec): add technical design"
git push -u origin $(git branch --show-current)
If commit or push fails, display warning but continue.
(Does not apply in --quick mode.)
-> Next: Run /ralph-specum:tasks/ralph-specum:tasks