ralph-loop
Runs tasks through local scripts (Ralph) with injected design-doc context and queue state.
Install
mkdir -p .claude/skills/ralph-loop-jamesaphoenix && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/13591" && unzip -o skill.zip -d .claude/skills/ralph-loop-jamesaphoenix && rm skill.zipInstalls to .claude/skills/ralph-loop-jamesaphoenix
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
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.Key capabilities
- →Dispatch tasks using `scripts/ralph.sh`
- →Scope task processing to either the full repo queue or a single design document
- →Inject current task JSON into the runtime
- →Inject linked design-doc markdown for the current task
- →Inject a snapshot of all tasks in the current Ralph scope
How it works
The skill executes `scripts/ralph.sh` to process tasks, either from the global queue or scoped to a design document. It injects task-specific JSON, linked design-doc markdown, and a queue snapshot into the runtime for each dispatched task.
Inputs & outputs
When to use ralph-loop
- →Dispatch tasks in design-doc mode
- →Run full repo queue tasks
- →Automate task workflow execution
About this skill
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 addand subtasks withtx add ... --parent <task-id>. - Ralph may reorder work with
tx update <id> --score <n>ortx 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
When not to use it
- →When the user does not want to dispatch work through `scripts/ralph.sh`
- →When tasks are not explicitly attached to design documents for design-doc mode
- →When the user wants to merge PRs directly
Limitations
- →Ralph scopes by the linked design doc name, not by filename guesses
- →If a non-trivial task is missing its paired PRD/design docs, follow-up work or blocking is needed
- →Ralph may create follow-up tasks with `tx add` and subtasks with `tx add ... --parent <task-id>`
How it compares
This skill automates the dispatching of tasks through a `ralph.sh` script with specific scoping and context injection, providing a structured workflow for task management compared to manual task execution.
Compared to similar skills
ralph-loop side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| ralph-loop (this skill) | 0 | 4mo | Review | Intermediate |
| bazel-build-optimization | 14 | 2mo | No flags | Advanced |
| github-workflow-automation | 11 | 2mo | Review | Advanced |
| wolf-scripts-core | 5 | 9mo | Review | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by jamesaphoenix
View all by jamesaphoenix →You might also like
bazel-build-optimization
wshobson
Optimize Bazel builds for large-scale monorepos. Use when configuring Bazel, implementing remote execution, or optimizing build performance for enterprise codebases.
github-workflow-automation
ruvnet
Advanced GitHub Actions workflow automation with AI swarm coordination, intelligent CI/CD pipelines, and comprehensive repository management
wolf-scripts-core
Nice-Wolf-Studio
Core automation scripts for archetype selection, evidence validation, quality scoring, and safe bash execution
github-actions-templates
wshobson
Create production-ready GitHub Actions workflows for automated testing, building, and deploying applications. Use when setting up CI/CD with GitHub Actions, automating development workflows, or creating reusable workflow templates.
bash-defensive-patterns
wshobson
Master defensive Bash programming techniques for production-grade scripts. Use when writing robust shell scripts, CI/CD pipelines, or system utilities requiring fault tolerance and safety.
hooks-automation
ruvnet
Automated coordination, formatting, and learning from Claude Code operations using intelligent hooks with MCP integration. Includes pre$post task hooks, session management, Git integration, memory coordination, and neural pattern training for enhanced development workflows.