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. ralph.sh → Execute autonomous implementation loop

This skill coordinates these tools while keeping you in control at decision points.

<essential_principles>

ALL code implementation MUST happen through ralph.sh — the bash script that spawns fresh Claude instances. You are the orchestrator, NOT the implementer. Do not write code, create files, modify source files, or make any project changes directly. Only ralph.sh iterations do that.

If you catch yourself about to write code or modify project files: STOP. Launch ralph.sh 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.

Never assume Ralph “remembers” previous iterations.

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, Ralph runs ALL existing tests (via testCommands in prd.json root) to catch regressions. A story is NOT done until the entire test suite passes. Broken code compounds across iterations — never skip quality checks.

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

Don’t rush. Bad requirements = wasted iterations.

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

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.

<quick_reference>

Key Files:

Commands:

# Run Ralph from your project directory
~/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

# Monitor Ralph in real-time (while running in background)
tail -f tasks/ralph.log

# Check story status (new schema)
cat tasks/prd.json | jq '.userStories[] | {id, title, status, attempts}'

# View learnings
cat tasks/progress.txt

</quick_reference>

<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 quality checks passing </success_criteria>