- 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)
- Subagent execution → Spawn ralph-coder/ralph-tester subagents via Task tool
This skill coordinates these tools while keeping you in control at decision points.
ALL code implementation MUST happen through subagents — ralph-coder implements production code, ralph-tester writes tests and verifies. You are the orchestrator, NOT the implementer. Do not write code, create files, modify source files, or make any project changes directly.
If you catch yourself about to write code or modify project files: STOP. Spawn a subagent instead.
Do NOT try to fix issues yourself, retry automatically, or continue past errors. Present the error clearly to the user and wait for their instructions.
This maximizes throughput while maintaining correct dependency ordering.
Separation gives each agent a focused context window. The orchestrator wraps ANY agent with Ralph context (story spec, return format, constraints) so even non-Ralph agents integrate seamlessly.
This lets users configure best-practice agents for their stack, and Ralph automatically uses them.
Both agents also update the docs/ folder with documentation about new features, APIs, test setup, and architecture changes. The tasks/test-log.md and tasks/review-notes.md files are updated by tester agents with test registries and improvement recommendations.
Never assume agents "remember" previous stories — but they CAN read shared knowledge files.
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
- API stories: curl endpoints with real data, check response codes and bodies
- UI stories: Playwright e2e tests that navigate and interact with real UI
- Database stories: Run migrations, query DB directly to confirm schema
- Infra stories: Health checks, config validation, service startup
Static checks (typecheck, lint) are baseline. Runtime validation is required.
After each story, the tester runs ALL existing tests (via testCommands in prd.json root) to catch regressions. A story is NOT done until the entire test suite passes.
Stories track attempts / maxAttempts to prevent infinite retries on broken stories.
Don't rush. Bad requirements = wasted iterations.
Expect matchers for verificationCommands:
exit_code:0 — command exits with code 0
exit_code:N — command exits with specific code N
contains:STRING — stdout contains STRING
not_empty — stdout is non-empty
matches:REGEX — stdout matches regex pattern
- 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.
After reading the workflow, follow it exactly.
Key Files:
| File |
Purpose |
| SPEC.md |
Comprehensive requirements from spec-interview |
| tasks/prd-*.md |
Product Requirements Document |
| tasks/prd.json |
Atomic user stories for Ralph |
| tasks/progress.txt |
Learnings between iterations |
| tasks/test-log.md |
Registry of all tests created per story (updated by tester agents) |
| tasks/review-notes.md |
Improvement recommendations after each story (updated by tester agents) |
| tasks/common_knowledge.md |
Shared knowledge base — patterns, conventions, gotchas discovered across stories (updated by both coder and tester agents, read by orchestrator between batches) |
| docs/ |
Project documentation — updated by both coder and tester agents with new features, APIs, test setup, etc. |
Agents:
| Agent |
Role |
Fallback |
| ralph-coder |
Implements production code + docs for one story |
Default coder when no project-specific agent matches |
| ralph-tester |
Writes tests + runs verification for one story |
Default tester when no project-specific agent matches |
| Project agents |
Discovered from .claude/agents/ and ~/.claude/agents/ |
Matched to storyTypes by description keywords |
Execution model:
BATCH 1 (independent stories):
Phase 1: Task(coder, US-001, worktree) + Task(coder, US-005, worktree) ← parallel
Phase 2: Task(tester, US-001) + Task(tester, US-005) ← parallel
Merge: US-001 → main, US-005 → main ← sequential
BATCH 2 (stories that depended on BATCH 1):
Phase 1: Task(coder, US-002, worktree) + Task(coder, US-003, worktree)
Phase 2: Task(tester, US-002) + Task(tester, US-003)
Merge: US-002 → main, US-003 → main
Commands:
# Check story status
cat tasks/prd.json | jq '.userStories[] | {id, title, status, attempts}'
# View learnings
cat tasks/progress.txt
# View test registry
cat tasks/test-log.md
# View review notes
cat tasks/review-notes.md
1---
2name: ralph-orchestrator
3description: Orchestrates the full Ralph autonomous agent pipeline from requirements gathering to execution. Use when building new features, platforms, or complex tasks that need structured development through spec-interview, PRD generation, and autonomous implementation.
4model: claude-opus-4-5
5metadata:
6 source: https://skillmd.com/skills/cfircoo/ralph-orchestrator
7---
8
9<objective>
10Orchestrate the complete Ralph pipeline for autonomous feature development:
11
121. **spec-interview** → Gather comprehensive requirements through guided discovery
132. **generate-prd** → Create actionable Product Requirements Document
143. **ralph-convert-prd** → Transform PRD into atomic user stories (prd.json)
154. **Subagent execution** → Spawn ralph-coder/ralph-tester subagents via Task tool
16
17This skill coordinates these tools while keeping you in control at decision points.
18</objective>
19
20<essential_principles>
21
22<principle name="CRITICAL_never_implement_directly">
23**NEVER implement user stories yourself.** The orchestrator's ONLY job is to:
241. Run spec-interview, generate-prd, ralph-convert-prd skills
252. Spawn ralph-coder and ralph-tester subagents via the Task tool to execute stories
263. Manage prd.json state, git operations (commit/merge), and progress tracking
27
28**ALL code implementation MUST happen through subagents** — ralph-coder implements production code, ralph-tester writes tests and verifies. You are the orchestrator, NOT the implementer. Do not write code, create files, modify source files, or make any project changes directly.
29
30If you catch yourself about to write code or modify project files: **STOP. Spawn a subagent instead.**
31</principle>
32
33<principle name="CRITICAL_stop_on_errors">
34**STOP and ask the user for instructions** whenever:
35- A subagent returns a failed result
36- A pre-execution check fails (invalid prd.json, missing files, dirty git state)
37- A merge conflict occurs during worktree merge
38- Any unexpected error occurs during the pipeline
39- You are unsure about any decision
40
41**Do NOT** try to fix issues yourself, retry automatically, or continue past errors. Present the error clearly to the user and wait for their instructions.
42</principle>
43
44<principle name="parallel_batch_execution">
45Stories with no dependencies between them run in parallel. The orchestrator:
461. Groups independent stories into batches
472. Spawns multiple ralph-coder subagents simultaneously (each in its own worktree)
483. After coders complete, spawns ralph-tester subagents in parallel (in the same worktrees)
494. Merges successful worktree branches to main sequentially
505. Updates prd.json and moves to the next batch
51
52This maximizes throughput while maintaining correct dependency ordering.
53</principle>
54
55<principle name="two_phase_pipeline">
56Each story goes through a two-phase pipeline:
57- **Phase 1: Code** — ralph-coder (or matched project agent) implements production code + docs
58- **Phase 2: Test** — ralph-tester (or matched project agent) writes tests + runs verification
59
60Separation gives each agent a focused context window. The orchestrator wraps ANY agent with Ralph context (story spec, return format, constraints) so even non-Ralph agents integrate seamlessly.
61</principle>
62
63<principle name="orchestrator_owns_state">
64**The orchestrator owns all state:**
65- **prd.json** — only the orchestrator reads/writes story status. Agents return JSON results, orchestrator updates prd.json. This prevents race conditions during parallel execution.
66- **Git operations** — only the orchestrator commits and merges. Neither coder nor tester commits. Orchestrator commits only after tester confirms all verification passes.
67- **Worktree lifecycle** — orchestrator creates worktrees (via Task isolation), merges branches, and manages cleanup.
68</principle>
69
70<principle name="agent_discovery">
71The orchestrator **prefers existing project/user agents** over defaults. At startup:
721. Scan `.claude/agents/*.md` and `~/.claude/agents/*.md`
732. Match agents to storyTypes by description keywords
743. Fall back to ralph-coder/ralph-tester when no better match exists
75
76This lets users configure best-practice agents for their stack, and Ralph automatically uses them.
77</principle>
78
79<principle name="shared_knowledge">
80Both coder and tester agents update `tasks/common_knowledge.md` with patterns, conventions, gotchas, and architectural decisions they discover. The orchestrator reads this file between batches to:
81- Pass accumulated knowledge to subsequent subagent prompts
82- Detect actionable discoveries (e.g., manual steps needed, environment issues)
83- Make informed routing decisions for upcoming stories
84
85Both agents also update the `docs/` folder with documentation about new features, APIs, test setup, and architecture changes. The `tasks/test-log.md` and `tasks/review-notes.md` files are updated by tester agents with test registries and improvement recommendations.
86</principle>
87
88<principle name="fresh_context_per_story">
89Each subagent runs with a fresh context for each story. Memory persists only through:
90- Git history (committed code in worktrees)
91- tasks/progress.txt (learnings between iterations)
92- tasks/prd.json (story status tracking)
93- tasks/common_knowledge.md (shared patterns and conventions across stories)
94- tasks/test-log.md (test registry across stories)
95- tasks/review-notes.md (improvement recommendations across stories)
96
97**Never assume agents "remember" previous stories — but they CAN read shared knowledge files.**
98</principle>
99
100<principle name="atomic_stories">
101Each user story MUST be completable in ONE context window.
102
103**Right-sized:**
104- Add a database column
105- Create a UI component
106- Update a server action
107- Implement a filter
108
109**Too large (will fail):**
110- Build entire dashboard
111- Add authentication system
112- Refactor entire API
113</principle>
114
115<principle name="real_verification">
116Every story must be verified with **real runtime checks** — not just that it compiles.
117
118- **API stories**: curl endpoints with real data, check response codes and bodies
119- **UI stories**: Playwright e2e tests that navigate and interact with real UI
120- **Database stories**: Run migrations, query DB directly to confirm schema
121- **Infra stories**: Health checks, config validation, service startup
122
123Static checks (typecheck, lint) are baseline. Runtime validation is required.
124</principle>
125
126<principle name="quality_gates">
127All checks must pass before the orchestrator commits:
128- Story-specific verification commands pass (real runtime checks)
129- **Full test suite passes** (unit + integration + e2e) — no regressions allowed
130- TypeCheck passes
131- UI verified via Playwright (for frontend stories)
132
133After each story, the tester runs ALL existing tests (via `testCommands` in prd.json root) to catch regressions. A story is NOT done until the entire test suite passes.
134</principle>
135
136<principle name="status_tracking">
137Stories use structured status tracking:
138- `"pending"` → not started
139- `"in_progress"` → being worked on by subagents
140- `"done"` → verified, committed, and merged to main
141- `"failed"` → attempted but verification failed
142- `"blocked"` → dependencies not met
143
144Stories track `attempts` / `maxAttempts` to prevent infinite retries on broken stories.
145</principle>
146
147<principle name="user_control_points">
148You approve at each stage:
1491. After spec-interview → Review SPEC.md
1502. After generate-prd → Review PRD
1513. After ralph-convert-prd → Review prd.json stories
1524. Before execution → Confirm ready to execute
1535. Between batches → View progress (if issues arise)
154
155Don't rush. Bad requirements = wasted iterations.
156</principle>
157
158</essential_principles>
159
160<prd_json_schema>
161```json
162{
163 "project": "[Project Name]",
164 "branchName": "ralph/[feature-name-kebab-case]",
165 "description": "[Feature description]",
166 "testCommands": {
167 "unit": "npm test",
168 "integration": "npm run test:integration",
169 "e2e": "npx playwright test",
170 "typecheck": "npm run typecheck"
171 },
172 "userStories": [
173 {
174 "id": "US-001",
175 "title": "[Story title]",
176 "description": "As a [user], I want [feature] so that [benefit]",
177 "storyType": "backend | frontend | database | api | infra | test",
178 "acceptanceCriteria": ["Specific criterion 1", "Typecheck passes"],
179 "verificationCommands": [
180 { "command": "npm run typecheck", "expect": "exit_code:0" },
181 { "command": "curl -s http://localhost:3000/api/...", "expect": "contains:expected" }
182 ],
183 "status": "pending",
184 "priority": 1,
185 "attempts": 0,
186 "maxAttempts": 3,
187 "notes": "",
188 "blockedBy": [],
189 "docsToUpdate": ["README.md", "docs/api.md"],
190 "completedAt": null,
191 "lastAttemptLog": ""
192 }
193 ]
194}
195```
196
197**Expect matchers for verificationCommands:**
198- `exit_code:0` — command exits with code 0
199- `exit_code:N` — command exits with specific code N
200- `contains:STRING` — stdout contains STRING
201- `not_empty` — stdout is non-empty
202- `matches:REGEX` — stdout matches regex pattern
203</prd_json_schema>
204
205<intake>
206What would you like to do?
207
2081. **Full pipeline** - Start from scratch (spec → PRD → prd.json → execute)
2092. **Continue from PRD** - Already have PRD, convert and execute
2103. **Execute only** - Already have prd.json, run Ralph
2114. **Check status** - View current prd.json progress
212
213**Wait for response before proceeding.**
214</intake>
215
216<routing>
217| Response | Workflow |
218|----------|----------|
219| 1, "full", "start", "new feature" | `workflows/full-pipeline.md` |
220| 2, "continue", "have PRD", "convert" | `workflows/from-prd.md` |
221| 3, "execute", "run ralph", "have prd.json" | `workflows/execute-only.md` |
222| 4, "status", "check", "progress" | `workflows/check-status.md` |
223
224**After reading the workflow, follow it exactly.**
225</routing>
226
227<quick_reference>
228
229**Key Files:**
230| File | Purpose |
231|------|---------|
232| SPEC.md | Comprehensive requirements from spec-interview |
233| tasks/prd-*.md | Product Requirements Document |
234| tasks/prd.json | Atomic user stories for Ralph |
235| tasks/progress.txt | Learnings between iterations |
236| tasks/test-log.md | Registry of all tests created per story (updated by tester agents) |
237| tasks/review-notes.md | Improvement recommendations after each story (updated by tester agents) |
238| tasks/common_knowledge.md | Shared knowledge base — patterns, conventions, gotchas discovered across stories (updated by both coder and tester agents, read by orchestrator between batches) |
239| docs/ | Project documentation — updated by both coder and tester agents with new features, APIs, test setup, etc. |
240
241**Agents:**
242| Agent | Role | Fallback |
243|-------|------|----------|
244| ralph-coder | Implements production code + docs for one story | Default coder when no project-specific agent matches |
245| ralph-tester | Writes tests + runs verification for one story | Default tester when no project-specific agent matches |
246| Project agents | Discovered from .claude/agents/ and ~/.claude/agents/ | Matched to storyTypes by description keywords |
247
248**Execution model:**
249```
250BATCH 1 (independent stories):
251 Phase 1: Task(coder, US-001, worktree) + Task(coder, US-005, worktree) ← parallel
252 Phase 2: Task(tester, US-001) + Task(tester, US-005) ← parallel
253 Merge: US-001 → main, US-005 → main ← sequential
254
255BATCH 2 (stories that depended on BATCH 1):
256 Phase 1: Task(coder, US-002, worktree) + Task(coder, US-003, worktree)
257 Phase 2: Task(tester, US-002) + Task(tester, US-003)
258 Merge: US-002 → main, US-003 → main
259```
260
261**Commands:**
262```bash
263# Check story status
264cat tasks/prd.json | jq '.userStories[] | {id, title, status, attempts}'
265
266# View learnings
267cat tasks/progress.txt
268
269# View test registry
270cat tasks/test-log.md
271
272# View review notes
273cat tasks/review-notes.md
274```
275
276</quick_reference>
277
278<workflows_index>
279| Workflow | Purpose |
280|----------|---------|
281| full-pipeline.md | Complete flow: spec → PRD → prd.json → execute |
282| from-prd.md | Convert existing PRD and execute |
283| execute-only.md | Run Ralph on existing prd.json |
284| check-status.md | View current progress |
285</workflows_index>
286
287<success_criteria>
288Pipeline is complete when:
289- [ ] Requirements gathered through spec-interview (including verification environment)
290- [ ] PRD created with verifiable acceptance criteria
291- [ ] prd.json has atomic stories with storyType, verificationCommands, and blockedBy
292- [ ] All stories have `status: "done"` in prd.json
293- [ ] All verification commands passed (real runtime checks, not just typecheck)
294- [ ] Code committed and merged to main via worktree branches
295</success_criteria>