SKILL.md
<objective> Orchestrate the complete Ralph pipeline for autonomous feature development:
- spec-interview → Gather comprehensive requirements through guided discovery
- generate-prd → Create actionable Product Requirements Document
- ralph-convert-prd → Transform PRD into atomic user stories (prd.json)
- ralph.sh → Execute autonomous implementation loop
This skill coordinates these tools while keeping you in control at decision points. </objective>
<essential_principles>
<principle name="freshcontextper_iteration"> Ralph spawns fresh Claude instances for each story. Memory persists only through:
- Git history (committed code)
- progress.txt (learnings between iterations)
- prd.json (story status tracking)
Never assume Ralph "remembers" previous iterations. </principle>
<principle name="atomic_stories"> Each user story MUST be completable in ONE context window.
Right-sized:
- Add a database column
- Create a UI component
- Update a server action
- Implement a filter
Too large (will fail):
- Build entire dashboard
- Add authentication system
- Refactor entire API
</principle>
<principle name="quality_gates"> All checks must pass before Ralph commits:
- TypeCheck passes
- Tests pass
- UI verified in browser (for frontend stories)
Broken code compounds across iterations. Never skip quality checks. </principle>
<principle name="usercontrolpoints"> You approve at each stage:
- After spec-interview → Review SPEC.md
- After generate-prd → Review PRD
- After ralph-convert-prd → Review prd.json stories
- Before ralph.sh → Confirm ready to execute
Don't rush. Bad requirements = wasted iterations. </principle>
</essential_principles>
<intake> What would you like to do?
- Full pipeline - Start from scratch (spec → PRD → prd.json → execute)
- Continue from PRD - Already have PRD, convert and execute
- Execute only - Already have prd.json, run Ralph
- Check status - View current prd.json progress
Wait for response before proceeding. </intake>
<routing>
| Response | Workflow |
|---|---|
| 1, "full", "start", "new feature" | workflows/full-pipeline.md |
| 2, "continue", "have PRD", "convert" | workflows/from-prd.md |
| 3, "execute", "run ralph", "have prd.json" | workflows/execute-only.md |
| 4, "status", "check", "progress" | workflows/check-status.md |
After reading the workflow, follow it exactly. </routing>
<quick_reference>
Key Files:
| File | Purpose |
|---|---|
| SPEC.md | Comprehensive requirements from spec-interview |
| tasks/prd-*.md | Product Requirements Document |
| prd.json | Atomic user stories for Ralph (in project root) |
| progress.txt | Learnings between iterations (in project root) |
| scripts/ralph.sh | Ralph execution script (in this skill folder) |
| scripts/prompt.md | Iteration prompt template |
Commands:
# Run Ralph from your project directory
# (assumes toolkit is at ~/projects/claude-code-toolkit)
~/projects/claude-code-toolkit/skills/ralph-orchestrator/scripts/ralph.sh
# Or create an alias in ~/.bashrc:
alias ralph='~/projects/claude-code-toolkit/skills/ralph-orchestrator/scripts/ralph.sh'
# Run with custom iteration limit
ralph 5
# Check story status
cat prd.json | jq '.userStories[] | {id, title, passes}'
# View learnings
cat progress.txt</quick_reference>
<workflows_index>
| Workflow | Purpose |
|---|---|
| full-pipeline.md | Complete flow: spec → PRD → prd.json → execute |
| from-prd.md | Convert existing PRD and execute |
| execute-only.md | Run Ralph on existing prd.json |
| check-status.md | View current progress |
</workflows_index>
<success_criteria> Pipeline is complete when:
- Requirements gathered through spec-interview
- PRD created with verifiable acceptance criteria
- prd.json has atomic, right-sized stories
- All stories have
passes: truein prd.json - Code committed and quality checks passing
</success_criteria>