spec-workflow ยท diff
v0.1.0 to v0.2.0
80 added, 30 removed. Audit A to A.
---
name: spec-workflow
- description: This skill should be used when the user asks to "build a feature", "create a spec", "start spec-driven development", "run research phase", "generate requirements", "create design", "plan tasks", "implement spec", "check spec status", or needs guidance on the spec-driven development workflow.
- version: 0.1.0
+ description: This skill should be used when the user asks to "build a feature", "create a spec", "start spec-driven development", "run research phase", "generate requirements", "create design", "plan tasks", "implement spec", "check spec status", "triage a feature", "create an epic", "decompose a large feature", or needs guidance on spec-driven development workflow, phase ordering, or epic orchestration.
+ version: 0.2.0
---
- # Spec Workflow Skill
+ # Spec Workflow
- Spec-driven development workflow for building features through research, requirements, design, and task phases.
+ Spec-driven development transforms feature requests into structured specs through sequential phases, then executes them task-by-task.
- ## When to Use
+ ## Decision Tree: Where to Start
- Use these commands when user wants to:
- - Build a new feature or system
- - Create technical specifications
- - Plan development work
- - Track spec progress
- - Execute spec-driven implementation
+ | Situation | Command |
+ |-----------|---------|
+ | New feature, want guidance | `/ralph-specum:start <name> <goal>` |
+ | New feature, skip interviews | `/ralph-specum:start <name> <goal> --quick` |
+ | Large feature needing decomposition | `/ralph-specum:triage <goal>` |
+ | Resume existing spec | `/ralph-specum:start` (auto-detects) |
+ | Jump to specific phase | `/ralph-specum:<phase>` |
- ## Commands
+ ## Single Spec Flow
- ### Starting Work
- - `/ralph-specum:start [name] [goal]` - Start or resume a spec (smart entry point)
- - `/ralph-specum:new <name> [goal]` - Create new spec and begin research
+ ```
+ start/new -> research -> requirements -> design -> tasks -> implement
+ ```
- ### Spec Phases
- - `/ralph-specum:research` - Run research phase
- - `/ralph-specum:requirements` - Generate requirements from research
- - `/ralph-specum:design` - Generate technical design
- - `/ralph-specum:tasks` - Generate implementation tasks
+ Each phase produces a markdown artifact in `./specs/<name>/`. Normal mode pauses for approval between phases. Quick mode runs all phases then auto-starts execution.
- ### Execution
- - `/ralph-specum:implement` - Start autonomous task execution
+ ### Phase Commands
- ### Management
- - `/ralph-specum:status` - Show all specs and progress
- - `/ralph-specum:switch <name>` - Change active spec
- - `/ralph-specum:cancel` - Cancel active execution
+ | Command | Agent | Output | Purpose |
+ |---------|-------|--------|---------|
+ | `/ralph-specum:research` | research-analyst | research.md | Explore feasibility, patterns, context |
+ | `/ralph-specum:requirements` | product-manager | requirements.md | User stories, acceptance criteria |
+ | `/ralph-specum:design` | architect-reviewer | design.md | Architecture, components, interfaces |
+ | `/ralph-specum:tasks` | task-planner | tasks.md | POC-first task breakdown |
+ | `/ralph-specum:implement` | spec-executor | commits | Autonomous task-by-task execution |
- ### Help
- - `/ralph-specum:help` - Show plugin help
+ ## Epic Flow (Multi-Spec)
- ## Phase Flow
+ For features too large for a single spec, use epic triage to decompose into dependency-aware specs.
- See `references/phase-transitions.md` for detailed phase flow documentation.
+ ```
+ triage -> [spec-1, spec-2, spec-3...] -> implement each in order
+ ```
+
+ **Entry points:**
+ - `/ralph-specum:triage <goal>` -- create or resume an epic
+ - `/ralph-specum:start` -- detects active epics, suggests next unblocked spec
+
+ **File structure:**
+ ```
+ specs/
+ _epics/<epic-name>/
+ epic.md # Triage output (vision, specs, dependency graph)
+ research.md # Exploration + validation research
+ .epic-state.json # Progress tracking across specs
+ .progress.md # Learnings and decisions
+ ```
+
+ ## Management Commands
+
+ | Command | Purpose |
+ |---------|---------|
+ | `/ralph-specum:status` | Show all specs and progress |
+ | `/ralph-specum:switch <name>` | Change active spec |
+ | `/ralph-specum:cancel` | Cancel active execution |
+ | `/ralph-specum:refactor` | Update spec files after execution |
+
+ ## Common Workflows
+
+ ### Quick prototype
+ ```bash
+ /ralph-specum:start my-feature "Build X" --quick
+ # Runs all phases automatically, starts execution
+ ```
+
+ ### Guided development
+ ```bash
+ /ralph-specum:start my-feature "Build X"
+ # Interactive interviews at each phase
+ # Review and approve each artifact
+ /ralph-specum:implement
+ ```
+
+ ### Large feature
+ ```bash
+ /ralph-specum:triage "Build entire auth system"
+ # Decomposes into: auth-core, auth-oauth, auth-rbac
+ /ralph-specum:start # Picks next unblocked spec
+ ```
+
+ ## References
+
+ - **`references/phase-transitions.md`** -- Detailed phase flow, state transitions, quick mode behavior, phase skipping