Ralph Orchestrator

<objective> Orchestrate the complete Ralph pipeline for autonomous feature development:

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 Task tool

This skill coordinates these tools while keeping you in control at decision points. </objective>

<essential_principles>

<principle name="CRITICAL_never_implement_directly"> NEVER implement user stories yourself. The orchestrator's ONLY job is to: 1. Run spec-interview, generate-prd, ralph-convert-prd skills 2. Spawn ralph-coder and ralph-tester subagents via the Task tool to execute stories 3. Manage prd.json state, git operations (commit/merge), and progress tracking

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. </principle>

<principle name="CRITICAL_stop_on_errors"> STOP and ask the user for instructions whenever:

• A subagent returns a failed result
• A pre-execution check fails (invalid prd.json, missing files, dirty git state)
• A merge conflict occurs during worktree merge
• Any unexpected error occurs during the pipeline
• You are unsure about any decision

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. </principle>

<principle name="parallel_batch_execution"> Stories with no dependencies between them run in parallel. The orchestrator: 1. Groups independent stories into batches 2. Spawns multiple ralph-coder subagents simultaneously (each in its own worktree) 3. After coders complete, spawns ralph-tester subagents in parallel (in the same worktrees) 4. Merges successful worktree branches to main sequentially 5. Updates prd.json and moves to the next batch

This maximizes throughput while maintaining correct dependency ordering. </principle>

<principle name="two_phase_pipeline"> Each story goes through a two-phase pipeline:

• Phase 1: Code — ralph-coder (or matched project agent) implements production code + docs
• Phase 2: Test — ralph-tester (or matched project agent) writes tests + runs verification

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. </principle>

<principle name="orchestrator_owns_state"> The orchestrator owns all state:

• prd.json — only the orchestrator reads/writes story status. Agents return JSON results, orchestrator updates prd.json. This prevents race conditions during parallel execution.
• Git operations — only the orchestrator commits and merges. Neither coder nor tester commits. Orchestrator commits only after tester confirms all verification passes.
• Worktree lifecycle — orchestrator creates worktrees (via Task isolation), merges branches, and manages cleanup.

</principle>

<principle name="agent_discovery"> The orchestrator prefers existing project/user agents over defaults. At startup: 1. Scan .claude/agents/*.md and ~/.claude/agents/*.md 2. Match agents to storyTypes by description keywords 3. Fall back to ralph-coder/ralph-tester when no better match exists

This lets users configure best-practice agents for their stack, and Ralph automatically uses them. </principle>

<principle name="shared_knowledge"> Both 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:

• Pass accumulated knowledge to subsequent subagent prompts
• Detect actionable discoveries (e.g., manual steps needed, environment issues)
• Make informed routing decisions for upcoming stories

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. </principle>

<principle name="fresh_context_per_story"> Each subagent runs with a fresh context for each story. Memory persists only through:

• Git history (committed code in worktrees)
• tasks/progress.txt (learnings between iterations)
• tasks/prd.json (story status tracking)
• tasks/common_knowledge.md (shared patterns and conventions across stories)
• tasks/test-log.md (test registry across stories)
• tasks/review-notes.md (improvement recommendations across stories)

Never assume agents "remember" previous stories — but they CAN read shared knowledge files. </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="real_verification"> Every story must be verified with real runtime checks — not just that it compiles.

• 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. </principle>

<principle name="quality_gates"> All checks must pass before the orchestrator commits:

• Story-specific verification commands pass (real runtime checks)
• Full test suite passes (unit + integration + e2e) — no regressions allowed
• TypeCheck passes
• UI verified via Playwright (for frontend stories)

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. </principle>

<principle name="status_tracking"> Stories use structured status tracking:

• "pending" → not started
• "in_progress" → being worked on by subagents
• "done" → verified, committed, and merged to main
• "failed" → attempted but verification failed
• "blocked" → dependencies not met

Stories track attempts / maxAttempts to prevent infinite retries on broken stories. </principle>

<principle name="user_control_points"> You approve at each stage: 1. After spec-interview → Review SPEC.md 2. After generate-prd → Review PRD 3. After ralph-convert-prd → Review prd.json stories 4. Before execution → Confirm ready to execute 5. Between batches → View progress (if issues arise)

Don't rush. Bad requirements = wasted iterations. </principle>

</essential_principles>

<prd_json_schema>

{
  "project": "[Project Name]",
  "branchName": "ralph/[feature-name-kebab-case]",
  "description": "[Feature description]",
  "testCommands": {
    "unit": "npm test",
    "integration": "npm run test:integration",
    "e2e": "npx playwright test",
    "typecheck": "npm run typecheck"
  },
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "storyType": "backend | frontend | database | api | infra | test",
      "acceptanceCriteria": ["Specific criterion 1", "Typecheck passes"],
      "verificationCommands": [
        { "command": "npm run typecheck", "expect": "exit_code:0" },
        { "command": "curl -s http://localhost:3000/api/...", "expect": "contains:expected" }
      ],
      "status": "pending",
      "priority": 1,
      "attempts": 0,
      "maxAttempts": 3,
      "notes": "",
      "blockedBy": [],
      "docsToUpdate": ["README.md", "docs/api.md"],
      "completedAt": null,
      "lastAttemptLog": ""
    }
  ]
}

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

</prd_json_schema>

<intake> What would you like to do?

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. </intake>

<routing>

After reading the workflow, follow it exactly. </routing>

<quick_reference>

Key Files:

Agents:

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

</quick_reference>

<workflows_index>

</workflows_index>

<success_criteria> Pipeline is complete when:

• [ ] Requirements gathered through spec-interview (including verification environment)
• [ ] PRD created with verifiable acceptance criteria
• [ ] prd.json has atomic stories with storyType, verificationCommands, and blockedBy
• [ ] All stories have status: "done" in prd.json
• [ ] All verification commands passed (real runtime checks, not just typecheck)
• [ ] Code committed and merged to main via worktree branches

</success_criteria>

Workflow: Check Status

<objective> View current Ralph pipeline progress with detailed status breakdown. </objective>

<process>

<step name="1_check_prd_json"> Story status

# Project info
cat tasks/prd.json | jq '{project: .project, branch: .branchName, description: .description}'

# Story summary (new schema)
echo "=== Story Status ==="
cat tasks/prd.json | jq '.userStories[] | "\(.id): \(.title) - status: \(.status // (if .passes then "done" else "pending" end)) | attempts: \(.attempts // "n/a") / \(.maxAttempts // "n/a")"'

# Status breakdown
echo ""
echo "=== Summary ==="
cat tasks/prd.json | jq '{
  total: (.userStories | length),
  done: ([.userStories[] | select(.status == "done" or .passes == true)] | length),
  pending: ([.userStories[] | select(.status == "pending" or (.passes == false and .status == null))] | length),
  failed: ([.userStories[] | select(.status == "failed")] | length),
  blocked: ([.userStories[] | select(.status == "blocked")] | length),
  in_progress: ([.userStories[] | select(.status == "in_progress")] | length),
  exhausted: ([.userStories[] | select(.status == "failed" and .attempts >= .maxAttempts)] | length)
}'

</step>

<step name="2_check_failures"> Failed and exhausted stories

echo "=== Failed Stories ==="
cat tasks/prd.json | jq '.userStories[] | select(.status == "failed") | {id, title, attempts, maxAttempts, lastAttemptLog}'

echo ""
echo "=== Blocked Stories ==="
cat tasks/prd.json | jq '.userStories[] | select(.status == "blocked" or (.blockedBy | length > 0)) | {id, title, blockedBy}'

</step>

<step name="3_check_progress"> Learnings from iterations

echo "=== Recent Learnings ==="
tail -30 tasks/progress.txt 2>/dev/null || echo "No tasks/progress.txt yet"

</step>

<step name="3b_check_test_log"> Tests created

echo "=== Test Log ==="
tail -40 tasks/test-log.md 2>/dev/null || echo "No tasks/test-log.md yet"

</step>

<step name="3c_check_review_notes"> Review notes and suggestions

echo "=== Review Notes ==="
tail -40 tasks/review-notes.md 2>/dev/null || echo "No tasks/review-notes.md yet"

</step>

<step name="4_check_git"> Recent commits

echo "=== Recent Commits ==="
git log --oneline -10

echo ""
echo "=== Current Branch ==="
git branch --show-current

</step>

<step name="5_next_actions"> Suggest next steps

Based on status:

• If all done: "All stories complete! Review the implementation and consider opening a PR."
• If some failed with attempts remaining: "Would you like to continue Ralph execution? Some stories can be retried."
• If exhausted stories exist: "Some stories exceeded maxAttempts. Review their lastAttemptLog and consider revising the stories or acceptance criteria."
• If blocked stories exist: "Some stories are blocked. Check their blockedBy dependencies."
• If no prd.json: "No tasks/prd.json found. Start with full pipeline or from-prd workflow."

</step>

</process>

<success_criteria>

• [ ] Status displayed with full detail (status, attempts, blockers)
• [ ] Failed/exhausted stories highlighted
• [ ] Next steps suggested based on current state

</success_criteria>

Workflow: Execute Only

<objective> Run Ralph on an existing prd.json file using skill-native subagents with parallel batch execution. </objective>

<process>

<step name="1_verify_prd_json"> Check prd.json exists and is valid

# Verify file exists
ls -la tasks/prd.json

# Check structure and schema version
cat tasks/prd.json | jq '{
  project: .project,
  branch: .branchName,
  total_stories: (.userStories | length),
  has_new_schema: (any(.userStories[]; .status != null)),
  with_verification: ([.userStories[] | select(.verificationCommands != null and (.verificationCommands | length) > 0)] | length)
}'

# Show incomplete stories
cat tasks/prd.json | jq '.userStories[] | select(.status != "done" and .passes != true) | {id, title, status: (.status // "pending"), attempts: (.attempts // 0), storyType}'

If no tasks/prd.json exists, route to full-pipeline or from-prd workflow.

If using old schema (no status field), warn user: "prd.json uses the old schema (boolean passes field). Ralph will auto-migrate stories to the new status-based schema during execution. Consider running ralph-convert-prd again for full verification commands." </step>

<step name="2_review_stories"> Show current status

Display stories to user:

cat tasks/prd.json | jq '.userStories[] | {id, title, status: (.status // (if .passes then "done" else "pending" end)), priority, storyType, attempts: (.attempts // 0), blockedBy: (.blockedBy // [])}'

Ask: "These are the stories Ralph will work on. Incomplete stories will be implemented in priority/dependency order, with independent stories running in parallel. Ready to execute?" </step>

<step name="3_detect_framework"> Detect project framework and build agent routing table

This runs once before execution begins. The orchestrator scans the project to understand its stack.

Framework detection:

• Read package.json → detect React/Next.js/Vue/Express/Nest, test runner (jest/vitest/playwright)
• Read pyproject.toml or setup.py → detect Python/FastAPI/Django, test runner (pytest)
• Read go.mod → detect Go
• Read Cargo.toml → detect Rust
• Read tsconfig.json → confirm TypeScript
• Read playwright.config.ts or playwright.config.js → Playwright available
• Detect ORM: Prisma (prisma/schema.prisma), Drizzle (drizzle.config.ts), SQLAlchemy, etc.

Build a framework_profile object:

{
  "language": "typescript",
  "framework": "next.js (app router)",
  "test_runner": "vitest",
  "e2e_runner": "playwright",
  "orm": "prisma",
  "package_manager": "pnpm"
}

Agent discovery and routing:

Scan available agents:

• Read .claude/agents/*.md (project-level)
• Read ~/.claude/agents/*.md (user-level)
• Parse each agent's name + description

Build routing table — for each storyType, find the best matching agent:

Fallback: If no matching agent found for a storyType, use ralph-coder (for coder role) or ralph-tester (for tester role).

Key: Even when using a project-specific agent (e.g., db-expert), the orchestrator wraps it with Ralph context — the story spec, return format, constraints, framework profile, and progress learnings. </step>

<step name="4_execute_subagent_loop"> Run autonomous implementation via parallel batch subagent loop

CRITICAL: ALL implementation MUST go through ralph-coder/ralph-tester subagents via the Task tool. NEVER write code or modify project files directly.

Ask user for max iterations: "How many story iterations? (default: 10, remaining stories: [N])"

Initialize:

• iterations = 0
• max_iterations = user's answer
• Ensure tasks/progress.txt exists
• Ensure tasks/test-log.md exists
• Ensure tasks/review-notes.md exists
• Ensure tasks/common_knowledge.md exists (shared knowledge base across all stories)

LOOP (while eligible stories exist AND iterations < max_iterations):

a. Read current state

cat tasks/prd.json
cat tasks/common_knowledge.md

Read tasks/common_knowledge.md — this contains patterns, conventions, gotchas, and decisions discovered by previous stories. Use this to:

• Inform agent routing decisions
• Include relevant knowledge in subagent prompts
• Detect if previous stories surfaced issues the orchestrator should act on (e.g., "DB migrations require manual step" → warn user before spawning database stories)

b. Find ALL eligible stories A story is eligible if:

• status == "pending" OR (status == "failed" AND attempts < maxAttempts)
• AND all story IDs in blockedBy array have status == "done"

c. Check termination conditions

• If no eligible stories AND all stories "done" → report COMPLETE, break loop
• If no eligible stories AND remaining are blocked/exhausted → report BLOCKED, show failed stories with lastAttemptLog, break loop

d. Group eligible stories into a PARALLEL BATCH From eligible stories sorted by priority:

• Greedily select stories whose blockedBy sets don't include any other story in the current batch
• Stories with no dependency between them run concurrently

Display batch to user:

BATCH [N]: Running [X] stories in parallel
  - US-001: Add DB schema (coder: db-expert, tester: pytest-writer)
  - US-005: Add export feature (coder: ralph-coder, tester: ralph-tester)

e. Update prd.json for all batch stories For each story in batch: set status = "in_progress", increment attempts

--- PHASE 1: CODE (parallel across batch) ---

f. Spawn coder Tasks IN PARALLEL For each story in the batch, spawn a Task with:

• subagent_type: The matched coder agent name (e.g., "general-purpose")
• isolation: "worktree"
• prompt: Include:
• Full story object (id, title, description, acceptanceCriteria, storyType, docsToUpdate)
• Framework profile
• Relevant progress.txt learnings
• The coder agent instructions (from the matched agent's .md file, or ralph-coder defaults)
• Expected return format (JSON with files_created, files_modified, implementation_notes, needs_attention)
• Constraints: Do NOT commit, do NOT write tests, do NOT touch prd.json

Important Task prompt structure:

You are executing Ralph story {story.id}: {story.title}

## Story Spec
{full story JSON}

## Framework Profile
{framework_profile JSON}

## Progress Learnings
{relevant progress.txt content}

## Common Knowledge
{tasks/common_knowledge.md content — patterns, conventions, gotchas from previous stories}

## Instructions
{coder agent instructions - either from matched agent or ralph-coder.md}

## Constraints
- Do NOT commit any changes
- Do NOT write tests (the tester agent handles this)
- Do NOT modify tasks/prd.json
- Match existing project conventions
- Update docs/ folder with any new features, APIs, or concepts
- Append discoveries to tasks/common_knowledge.md

## Return Format
When done, output ONLY a JSON block:
{expected JSON format — includes docs_updated field}

g. Wait for ALL coder Tasks to complete Collect results from each Task. Parse the JSON output.

h. Handle coder failures If a coder returns status: "failed":

• Update prd.json: set story status = "failed", write lastAttemptLog
• Skip the tester phase for this story
• Log to progress.txt

--- PHASE 2: TEST (parallel across batch) ---

i. Spawn tester Tasks IN PARALLEL For each story where coder succeeded, spawn a Task with:

• subagent_type: The matched tester agent name (e.g., "general-purpose")
• isolation: DO NOT use isolation — tester must run in the SAME worktree as its coder
• Pass the worktree path from the coder's Task result so the tester works on the same files
• Use Bash to cd into the worktree directory, OR pass the worktree path in the prompt
• prompt: Include:
• Full story object (including verificationCommands)
• Coder's result (files_created, files_modified, implementation_notes, needs_attention)
• Framework profile
• Project-level testCommands from prd.json root
• Relevant progress.txt learnings
• Content from tasks/common_knowledge.md (shared knowledge from previous stories)
• The tester agent instructions
• Expected return format
• Constraints: Do NOT commit, do NOT modify production code (except minor bug fixes), do NOT touch prd.json
• Responsibility: Update tasks/test-log.md, tasks/review-notes.md, tasks/common_knowledge.md, and docs/ folder

j. Wait for ALL tester Tasks to complete Collect results from each Task. Parse the JSON output.

--- MERGE & UPDATE ---

k. Process results for each story

If tester returns `status: "done"`: 1. Commit in the worktree:

   cd [worktree_path] && git add -A && git commit -m "feat(US-XXX): [story title]"

2. Merge worktree branch to main (sequentially, one at a time):

   git checkout main && git merge [worktree_branch] --no-edit

3. If merge conflict → mark story as "failed", log conflict details 4. Update prd.json: set status = "done", set completedAt to ISO timestamp

If tester returns `status: "failed"`: 1. Do NOT commit 2. Update prd.json: set status = "failed", write tester's failure_details to lastAttemptLog 3. Log failure to progress.txt

l. Update tracking files

• tasks/prd.json — story statuses (done or failed)
• tasks/progress.txt — append learnings from this batch
• tasks/test-log.md — already updated by tester subagents (verify entries exist)
• tasks/review-notes.md — already updated by tester subagents (verify entries exist)
• tasks/common_knowledge.md — already updated by both coder and tester subagents. Read it now — check for actionable discoveries (warnings, required manual steps, blockers for upcoming stories). If common_knowledge contains info that affects upcoming batches, factor it into routing decisions or warn the user.

m. Display batch summary

BATCH [N] COMPLETE:
  ✓ US-001: Add DB schema — DONE (merged to main)
  ✓ US-005: Add export feature — DONE (merged to main)
  ✗ US-003: Add notifications — FAILED (API endpoint returns 404)

n. Increment iterations iterations += batch_size

End of LOOP

5. Report final status

• If all stories done → "All [N] stories completed successfully!"
• If loop exhausted → "Reached max iterations ([N]). [X] stories remaining. Run again to continue."
• If blocked → "All remaining stories are blocked or exhausted. Review failed stories in prd.json."

STOP and ask the user for instructions if any stories remain incomplete. </step>

</process>

<parallel_execution_example>

prd.json stories:
  US-001: Add DB schema        (blockedBy: [])         → BATCH 1
  US-002: Add API endpoint     (blockedBy: [US-001])    → BATCH 2
  US-003: Add CLI command      (blockedBy: [US-001])    → BATCH 2
  US-004: Add UI dashboard     (blockedBy: [US-002])    → BATCH 3
  US-005: Add export feature   (blockedBy: [])           → BATCH 1

Execution:
  BATCH 1 (2 stories in parallel):
    Phase 1: Task(ralph-coder, US-001, worktree) + Task(ralph-coder, US-005, worktree)
    Phase 2: Task(ralph-tester, US-001) + Task(ralph-tester, US-005)
    Merge: US-001 → main, US-005 → main

  BATCH 2 (2 stories in parallel, after BATCH 1 merged):
    Phase 1: Task(ralph-coder, US-002, worktree) + Task(ralph-coder, US-003, worktree)
    Phase 2: Task(ralph-tester, US-002) + Task(ralph-tester, US-003)
    Merge: US-002 → main, US-003 → main

  BATCH 3 (1 story):
    Phase 1: Task(ralph-coder, US-004, worktree)
    Phase 2: Task(ralph-tester, US-004)
    Merge: US-004 → main

</parallel_execution_example>

<success_criteria>

• [ ] prd.json validated (preferably with new schema)
• [ ] Framework detected and agent routing table built
• [ ] Ralph executed via subagent loop with parallel batches
• [ ] All stories have status: "done" with verification commands passed
• [ ] All worktree branches merged to main
• [ ] progress.txt updated with batch learnings
• [ ] test-log.md updated by tester agents with test registry
• [ ] review-notes.md updated by tester agents with improvement recommendations
• [ ] common_knowledge.md updated by both agents with shared patterns and discoveries
• [ ] docs/ folder updated by agents with new features, APIs, and test documentation

</success_criteria>

Workflow: Continue from PRD

<objective> Convert an existing PRD to prd.json and execute Ralph. </objective>

<process>

<step name="1_locate_prd"> Find the PRD file

Ask user for PRD location if not provided: "Where is your PRD file? (e.g., tasks/prd-feature-name.md)"

Read and review the PRD to understand the feature scope. </step>

<step name="2_convert_to_ralph"> Transform PRD to tasks/prd.json

Invoke the ralph-convert-prd skill:

Use Skill tool: ralph-convert-prd
Arguments: [PRD file path]

User checkpoint: Review tasks/prd.json stories. Ask: "prd.json created with [N] user stories. Please review:

• Are stories atomic (one context window each)?
• Is ordering correct (no forward dependencies)?
• Does each story have real verification commands (curl, Playwright, DB queries)?
• Are blockedBy dependencies correct?

Ready to execute Ralph?" </step>

<step name="3_execute_ralph"> Run autonomous implementation via subagent loop

CRITICAL: ALL implementation MUST go through ralph-coder/ralph-tester subagents via the Task tool. NEVER write code or modify project files directly.

Follow the subagent execution loop defined in workflows/execute-only.md step 3 (framework detection) and step 4 (subagent loop).

This will: 1. Detect project framework and build agent routing table 2. Group independent stories into parallel batches 3. For each batch:

• Phase 1: Spawn ralph-coder Tasks in parallel (one per story, each in a worktree)
• Phase 2: Spawn ralph-tester Tasks in parallel (in same worktrees)
• Merge successful stories to main, update prd.json

4. Continue until all stories done or max iterations reached

After the loop completes:

• All stories done: Report success.
• Max iterations reached: STOP and ask the user for instructions.
• All blocked/exhausted: STOP and show failed stories with `lastAttemptLog`. Ask the user for instructions.

NEVER continue past incomplete execution without user approval. </step>

</process>

<success_criteria>

• [ ] PRD converted to tasks/prd.json with new schema
• [ ] Stories are atomic, ordered, with verificationCommands and blockedBy
• [ ] Ralph executed via subagent loop with parallel batches
• [ ] All stories have status: "done"

</success_criteria>

Workflow: Full Pipeline

<objective> Execute the complete Ralph pipeline from requirements gathering to autonomous implementation. </objective>

<process>

<step name="1_spec_interview"> Gather comprehensive requirements

Invoke the spec-interview skill:

Use Skill tool: spec-interview

This will:

• Ask deep questions about the feature
• Surface hidden assumptions
• Force explicit tradeoffs
• Gather verification environment info (dev server, DB, test runners, ports)
• Output SPEC.md

User checkpoint: Review SPEC.md before proceeding. Ask user: "I've completed the spec interview. Please review SPEC.md. Ready to generate the PRD?" </step>

<step name="2_generate_prd"> Create actionable PRD

Invoke the generate-prd skill:

Use Skill tool: generate-prd
Arguments: Reference SPEC.md for context

This will:

• Ask 3-5 clarifying questions
• Generate structured PRD with user stories
• Save to tasks/prd-[feature-name].md

User checkpoint: Review the PRD. Ask user: "PRD generated at tasks/prd-[feature-name].md. Please review the user stories and acceptance criteria. Ready to convert for Ralph?" </step>

<step name="3_convert_to_ralph"> Transform PRD to prd.json

Invoke the ralph-convert-prd skill:

Use Skill tool: ralph-convert-prd
Arguments: Path to the PRD file

This will:

• Break down into atomic user stories
• Classify each story with storyType (backend, frontend, database, api, infra, test)
• Order by dependency (schema → backend → UI → dashboard)
• Generate verificationCommands with real runtime checks per storyType
• Set blockedBy dependencies between stories
• Add mandatory criteria ("Typecheck passes")
• Output tasks/prd.json

User checkpoint: Review prd.json stories. Ask user: "prd.json created with [N] user stories. Please review:

• Are stories atomic (one context window each)?
• Is ordering correct (no forward dependencies)?
• Does each story have real verification commands (curl, Playwright, DB queries)?
• Are blockedBy dependencies correct?

Ready to execute Ralph?" </step>

<step name="4_pre_execution_check"> Verify prerequisites

Before running Ralph, confirm:

# Verify prd.json is valid and has new schema fields
cat tasks/prd.json | jq '{
  stories: (.userStories | length),
  with_status: ([.userStories[] | select(.status != null)] | length),
  with_verification: ([.userStories[] | select(.verificationCommands != null and (.verificationCommands | length) > 0)] | length),
  with_storyType: ([.userStories[] | select(.storyType != null)] | length)
}'

# Check git status is clean
git status

Verify that ralph-coder and ralph-tester agents are available:

ls -la ~/.claude/agents/ralph-coder.md ~/.claude/agents/ralph-tester.md 2>/dev/null || echo "Using toolkit default agents"

</step>

<step name="5_execute_ralph"> Run autonomous implementation via subagent loop

CRITICAL: ALL implementation MUST go through ralph-coder/ralph-tester subagents via the Task tool. NEVER write code or modify project files directly. You are the orchestrator, NOT the implementer.

Follow the subagent execution loop defined in workflows/execute-only.md step 3 (framework detection) and step 4 (subagent loop).

This will: 1. Detect project framework and build agent routing table 2. Group independent stories into parallel batches 3. For each batch:

• Phase 1: Spawn ralph-coder Tasks in parallel (one per story, each in a worktree)
• Phase 2: Spawn ralph-tester Tasks in parallel (in same worktrees)
• Merge successful stories to main, update prd.json

4. Continue until all stories done or max iterations reached

After the loop completes:

• All stories done: Proceed to step 6.
• Max iterations reached: STOP and inform the user. Show status summary and ask for instructions (increase iterations? review failures? adjust stories?).
• All blocked/exhausted: STOP and inform the user. Show failed stories with their lastAttemptLog and ask for instructions.

NEVER continue past incomplete execution without user approval. </step>

<step name="6_monitor_completion"> Track progress

After execution completes, verify:

# Story status
cat tasks/prd.json | jq '.userStories[] | {id, title, status, attempts}'

# Recent commits
git log --oneline -10

# Learnings
tail -20 tasks/progress.txt

When all stories have status: "done", report completion to user. If any stories remain incomplete, present status and ask for instructions. </step>

</process>

<success_criteria> Full pipeline is complete when:

• [ ] SPEC.md created and reviewed (including verification environment section)
• [ ] PRD created with verifiable acceptance criteria
• [ ] prd.json has atomic stories with storyType, verificationCommands, and blockedBy
• [ ] Ralph executed via subagent loop with parallel batches
• [ ] All stories have status: "done"
• [ ] All verification commands passed (real runtime checks)
• [ ] Code committed and merged to main

</success_criteria>