Spec Workflow Agent Skill
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.
Install
one command, takes just this skill from the repositorynpx skills add https://github.com/tzachbon/smart-ralph --skill spec-workflowThe instruction itself
11 sections, as written by the authorSpec Workflow
Spec-driven development transforms feature requests into structured specs through sequential phases, then executes them task-by-task.
Decision Tree: Where to Start
| 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> |
Single Spec Flow
start/new -> research -> requirements -> design -> tasks -> implement
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.
Phase Commands
| 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 |
Epic Flow (Multi-Spec)
For features too large for a single spec, use epic triage to decompose into dependency-aware specs.
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
/ralph-specum:start my-feature "Build X" --quick
# Runs all phases automatically, starts execution
Guided development
/ralph-specum:start my-feature "Build X"
# Interactive interviews at each phase
# Review and approve each artifact
/ralph-specum:implement
Large feature
/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
Other skills for the same job
different authors, same section of the catalogue
Creates detailed, sectionized implementation plans through research, stakeholder interviews, and multi-LLM review. Use when planning features that need thorough pre-implementation analysis.
This skill should be used when scientists need help with research problem selection, project ideation, troubleshooting stuck projects, or strategic scientific decisions. Use this skill when users ask to pitch a new research idea, work through a project problem, evaluate project risks, plan research strategy, navigate decision trees, or get help choosing what scientific problem to work on. Typical requests include "I have an idea for a project", "I'm stuck on my research", "help me evaluate this project", "what should I work on", or "I need strategic advice about my research".
Research ideation partner. Generate hypotheses, explore interdisciplinary connections, challenge assumptions, develop methodologies, identify research gaps, for creative scientific problem-solving.
Manage and trigger pre-built Zapier workflows and MCP tool orchestration. Use when user mentions workflows, Zaps, automations, daily digest, research, search, lead tracking, expenses, or asks to "run" any process. Also handles Perplexity-based research and Google Sheets data tracking.
Provide qualitative-first, evidence-traceable developmental review of scholarly works and audit low-stakes research-assessment rubrics with optional local quality controls. Never use for ranking people or consequential decisions.
Guides researchers through structured ideation frameworks to discover high-impact research directions. Use when exploring new problem spaces, pivoting between projects, or seeking novel angles on existing work.
Loop 2 of the Three-Loop Integrated Development System. META-SKILL that dynamically compiles Loop 1 plans into agent+skill execution graphs. Queen Coordinator selects optimal agents from 86-agent registry and assigns skills (when available) or custom instructions. 9-step swarm with theater detection and reality validation. Receives plans from research-driven-planning, feeds to cicd-intelligent-recovery. Use for adaptive, theater-free implementation.
Loop 1 of the Three-Loop Integrated Development System. Research-driven requirements analysis with iterative risk mitigation through 5x pre-mortem cycles using multi-agent consensus. Feeds validated, risk-mitigated plans to parallel-swarm-implementation. Use when starting new features or projects requiring comprehensive planning with <3% failure confidence and evidence-based technology selection.
How to use it
Take tzachbon/spec-workflow from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.