Ralph Orchestrator

1. spec-interview → Gather comprehensive requirements through guided discovery
2. generate-prd → Create actionable Product Requirements Document
3. ralph-convert-prd → Transform PRD into atomic user stories (prd.json)
4. Subagent execution → Spawn ralph-coder/ralph-tester subagents via Agent 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

1. Full pipeline - Start from scratch (spec → PRD → prd.json → execute)
2. Continue from PRD - Already have PRD, convert and execute
3. Execute only - Already have prd.json, run Ralph
4. Check status - View current prd.json progress

Wait for response before proceeding.

After reading the workflow, follow it exactly.

Key Files:

Agents:

Execution model:

BATCH 1 (independent stories):
  Phase 1: Agent(ralph-coder, US-001, isolation:worktree) + Agent(ralph-coder, US-005, isolation:worktree)  ← parallel
  Phase 2: Agent(ralph-tester, US-001, cd worktree) + Agent(ralph-tester, US-005, cd worktree)            ← parallel
  Merge: US-001 → main, US-005 → main, cleanup worktrees                                                  ← sequential

BATCH 2 (stories that depended on BATCH 1):
  Phase 1: Agent(ralph-coder, US-002, isolation:worktree) + Agent(ralph-coder, US-003, isolation:worktree)
  Phase 2: Agent(ralph-tester, US-002, cd worktree) + Agent(ralph-tester, US-003, cd worktree)
  Merge: US-002 → main, US-003 → main, cleanup worktrees

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