| name | ralph-loop |
| description | Run Ralph against either the full repo queue or tasks linked to one design doc, with injected task/spec/queue context for Codex or Claude runtimes. |
| argument-hint | [--all-tasks | --design-doc <name>] [--runtime codex|claude] |
Ralph Loop
Use when the user wants to dispatch work through scripts/ralph.sh and needs to choose between the global queue and a single design-doc slice.
Modes
- Global queue:
./scripts/ralph.sh --all-tasks
- Design-doc scope:
./scripts/ralph.sh --design-doc <name>
If neither flag is passed, Ralph defaults to the global queue. Use --design-doc <name> when the user wants the current task selection and injected queue snapshot limited to tasks linked to that design doc.
What Ralph Injects
For every dispatched task, Ralph writes and injects:
- current task JSON
- linked design-doc markdown for the current task
- all tasks in the current Ralph scope
In --all-tasks mode, that queue snapshot is the repo-wide task list.
In --design-doc <name> mode, that queue snapshot is filtered to tasks whose linkedDocs include that design doc.
Required Setup
Attach specs to tasks explicitly before running Ralph in design-doc mode:
tx doc attach <task-id> <prd-doc> --type implements
tx doc attach <task-id> <design-doc> --type references
Ralph scopes by the linked design doc name, not by filename guesses.
Practical Commands
Run against the full queue:
./scripts/ralph.sh --runtime codex --all-tasks
./scripts/ralph.sh --runtime claude --all-tasks
Run against one design doc:
./scripts/ralph.sh --runtime codex --design-doc auth-flow-design
./scripts/ralph.sh --runtime claude --design-doc auth-flow-design
Expectations During Execution
- Ralph may create follow-up tasks with
tx add and subtasks with tx add ... --parent <task-id>.
- Ralph may reorder work with
tx update <id> --score <n> or tx bulk score <n> <id...>.
- If a non-trivial task is missing its paired PRD/design docs, create docs follow-up work or block the task before large implementation proceeds.
Verification
After changing Ralph behavior, prefer these tests:
bunx --bun vitest run test/integration/ralph-script.test.ts test/integration/ralph-context-bundle-e2e.test.ts
