Stats
Actions
Tags
From Super Ralph
Decomposes queries into tasks, writes tests first, implements with sub-agents, self-debugs on failure, learns over time. Activated by 'super ralph' or 'ralph this'.
How this skill is triggered — by the user, by Claude, or both
Slash command
/super-ralph:super-ralphThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Autonomous agentic loop: decompose → test → build → debug → learn → merge.
Autonomous agentic loop: decompose → test → build → debug → learn → merge.
This skill is authored in Claude-native terms and is also intended to run in Codex environments without removing any Claude behavior.
Use this mapping when running outside Claude:
| Claude primitive | Codex-compatible equivalent |
|---|---|
AskUserQuestion | Ask a single plain-text question in chat, include the same options, and wait for a reply before proceeding |
Agent tool dispatch | Run the same role prompt in a fresh Codex session/agent run; parallelize independent work with foreground parallel runs |
run_in_background: true | Do not detach jobs. Keep work in foreground sessions so prompts/approvals and progress stay visible |
If this file says "use AskUserQuestion," treat that as "single interactive question gate" in Codex.
User Query
→ Mode Selection: oneshot (fully autonomous) or brainstorm (interactive) — single AskUserQuestion
→ Environment Detection: detect AI runtime (Claude/Codex) + coding environment → AI_ENVIRONMENT + CODING_ENVIRONMENT + MODEL_CONFIG
→ IF oneshot: Permissions Bootstrap — auto-configure settings file so sub-agents never prompt
→ IF brainstorm: interactive Q&A to explore intent, scope, edge cases (AskUserQuestion loop)
→ IF oneshot: auto-analyze query, infer intent/scope/constraints, write BRAINSTORM_SUMMARY silently
→ Intent Profile: 3 questions or auto-infer (based on MODE) → JUDGE_RUBRIC
→ Tooling: scan skills/agents, recommend or auto-select (based on MODE) → TOOLING_CONFIG
→ Pre-Flight: scope workspace + set MAX_RETRIES (interactive or defaults based on MODE)
→ Decompose: orchestrator breaks query into tasks directly; tags each with complexity + model_tier
→ Per Task (parallel if independent — never use run_in_background):
→ ralph-tester-lightweight: write tests → JUDGE: pass? → retry tester if fail
→ ralph-worker[-lightweight]: implement → JUDGE: pass? → retry worker if fail → run tests
→ Fail MAX_RETRIES/2? → debug.md → ralph-debugger[-lightweight] → JUDGE: pass? → fresh ralph-worker[-lightweight]
→ Fail MAX_RETRIES? → auto-skip + log to learnings
→ Pass → clear debug.md
→ ralph-merger[-lightweight]: combine outputs → JUDGE: pass? → retry merger if fail → deliver
| Agent | File | Role |
|---|---|---|
| ralph-tester | agents/ralph-tester.md | Standard test-first agent (standard / opus) — kept for fallback |
| ralph-tester-lightweight | agents/ralph-tester-lightweight.md | Default test-first agent — used for all tasks (sonnet) |
| ralph-worker | agents/ralph-worker.md | Implements until tests pass, writes debug.md on attempt 3 (standard / opus) |
| ralph-worker-lightweight | agents/ralph-worker-lightweight.md | Same role, uses sonnet for simple tasks |
| ralph-debugger | agents/ralph-debugger.md | Cold analysis of failures, writes fix plan (standard / opus) |
| ralph-debugger-lightweight | agents/ralph-debugger-lightweight.md | Same role, uses sonnet for simple tasks |
| ralph-judge | agents/ralph-judge.md | Universal quality gate — evaluates every sub-agent output (standard / opus) |
| ralph-judge-lightweight | agents/ralph-judge-lightweight.md | Same role, uses sonnet for simple tasks |
| ralph-merger | agents/ralph-merger.md | Combines outputs into cohesive deliverable (standard / opus) |
| ralph-merger-lightweight | agents/ralph-merger-lightweight.md | Same role, uses sonnet for simple tasks |
Note: Planning/decomposition is handled directly by the orchestrator (this skill), not a separate manager or planner agent. The orchestrator already has the brainstorm summary, tooling config, learnings, and codebase context, so an extra control layer would just duplicate work.
Model selection: The orchestrator detects the AI environment (Claude vs Codex) and the coding environment, then assigns each task a complexity tier. The tester is always dispatched as ralph-tester-lightweight; worker/judge/debugger/merger use -lightweight for simple tasks and standard agents for medium/complex tasks.
Note: The ralph-judge agent evaluates every sub-agent's output before the loop continues. If the judge rejects, the same agent is retried with the judge's specific feedback. There is no retry limit on judge rejections — the agent keeps retrying until the judge passes. Each retry is a fresh agent with zero prior context.
After Phase 0, the entire loop runs without any user interaction. No AskUserQuestion calls, no confirmations, no escalations. If something fails after max retries, auto-skip it and log to learnings. The user said "go ahead" — respect that.
The first and possibly only question Super Ralph asks. Determines whether the rest of the setup is interactive or autonomous.
/ralph command)If MODE was already set before this phase (e.g., the user invoked /ralph which pre-sets MODE = oneshot), skip this question entirely and proceed with the pre-set mode. Do NOT ask the mode selection question — the user already chose by using the oneshot command.
If MODE is not pre-set, ask one AskUserQuestion:
question: "How should I approach this?"
header: "Mode"
options:
- label: "Oneshot"
description: "I'll handle everything autonomously — no questions, just deliver"
- label: "Brainstorm"
description: "Let's explore the idea together step by step"
- label: "Chat about this"
description: "Stop — I want to discuss this before deciding"
multiSelect: false
Store the answer as MODE:
MODE = oneshotMODE = brainstorm| MODE | Behavior |
|---|---|
brainstorm | All phases run interactively as documented below (existing behavior, unchanged) |
oneshot | All phases still run, but every AskUserQuestion gate is replaced with autonomous self-decision. No further user interaction until final delivery. |
Oneshot does NOT skip phases. Every phase (Brainstorm, Intent Profile, Tooling, Pre-Flight, Decompose, Execute, Merge) still runs in full. The only difference is that Ralph makes the decisions at each gate instead of asking the user. The pipeline is identical — the decision-maker changes.
When MODE = oneshot, the orchestrator makes these decisions autonomously instead of asking:
| Phase | Default |
|---|---|
| Brainstorm | Analyze query, infer intent/scope/constraints, write BRAINSTORM_SUMMARY |
| Intent Profile | Default to middle tier: solid and correct + my team + weeks to months |
| Tooling | Auto-select recommended toolset based on BRAINSTORM_SUMMARY |
| Pre-Flight | Current directory writable, no read-only, nothing off-limits, MAX_RETRIES=6 |
Before setting up permissions or brainstorming, detect the runtime environment so Ralph can choose the right model tier and tooling expectations. This phase is fully autonomous — no user questions.
Determine whether this session is running in Claude Code or Codex (or another compatible environment). Use the first match from these probes:
# Probe 1: Codex-specific paths / env
[ -d "$HOME/.codex" ] || [ -d ".codex" ] || [ -n "${CODEX_ENV:-}" ] || [ -f ".codex/settings.json" ] && ENV_HINT=codex
# Probe 2: Claude-specific paths / env
[ -d "$HOME/.claude" ] || [ -d ".claude" ] || [ -n "${CLAUDE_CODE_ENV:-}" ] || [ -f ".claude/settings.json" ] && ENV_HINT=claude
Set AI_ENVIRONMENT:
Additive Codex note: In Codex, the probes above may not be available. The orchestrator should still run the same logic; if it cannot determine the environment, default to
claudemodel names and let the Codex runtime map them to its own equivalents, or use the Codex-native model names configured by the user.
Scan the current workspace to identify the project's language, framework, and available tooling. This feeds CODING_ENVIRONMENT into task decomposition and model selection.
Run these probes (first match wins within each category):
# Languages / package managers
find . -maxdepth 2 \( -name "pyproject.toml" -o -name "requirements.txt" -o -name "setup.py" -o -name "Pipfile" \) -print -quit
find . -maxdepth 2 \( -name "package.json" -o -name "package-lock.json" -o -name "yarn.lock" -o -name "pnpm-lock.yaml" -o -name "bun.lockb" \) -print -quit
find . -maxdepth 2 \( -name "Cargo.toml" \) -print -quit
find . -maxdepth 2 \( -name "go.mod" \) -print -quit
find . -maxdepth 2 \( -name "pom.xml" -o -name "build.gradle" -o -name "build.gradle.kts" \) -print -quit
find . -maxdepth 2 \( -name "Gemfile" \) -print -quit
find . -maxdepth 2 \( -name "composer.json" \) -print -quit
# Test runners / build tools (look in common config files)
grep -E "pytest|unittest|jest|vitest|mocha|rspec|cargo test|go test|gradle|mvn" pyproject.toml package.json Cargo.toml go.mod 2>/dev/null || true
Store the result as CODING_ENVIRONMENT:
## Coding Environment
**AI Environment:** [claude | codex]
**Primary Language:** [python | javascript/typescript | rust | go | java | ruby | php | unknown]
**Framework / Runtime:** [django | fastapi | react | node | etc. — or unknown]
**Test Runner:** [pytest | jest | vitest | cargo test | go test | etc. — or unknown]
**Package Manager:** [pip | npm | yarn | pnpm | cargo | etc. — or unknown]
**Build Tool:** [make | webpack | vite | gradle | maven | etc. — or none]
Use CODING_ENVIRONMENT to:
skills_to_use tag (e.g., tag doc-search when third-party APIs are likely).MODEL_CONFIGBased on AI_ENVIRONMENT, define the available model tiers. This config is used during task decomposition to tag each task with the right agent variant.
## Model Config
**AI Environment:** [claude | codex]
**Standard model (complex tasks / quality gates):** opus
**Lightweight model (simple tasks):** sonnet
**Fastest model (trivial tasks, optional):** haiku
Environment-specific mappings:
| AI Environment | Standard | Lightweight | Fastest |
|---|---|---|---|
| Claude | opus | sonnet | haiku |
| Codex | Use Codex default / strongest available | Use Codex fast/cheap model | Use Codex lightest available |
The
standardtier is used for complex tasks and for agents that act as quality gates (ralph-judge, ralph-debugger) when the task is not trivial. Thelightweighttier is used for simple tasks across all agent roles. Thefastesttier is optional — only use it for tasks that are truly trivial (one-line change, config tweak, typo fix) and only if the environment supports it.
Store MODEL_CONFIG and proceed to Phase -1.5 (Permissions Bootstrap) or Phase -1 (Brainstorm) depending on MODE.
This phase only runs when MODE = oneshot. If MODE = brainstorm, skip this entirely — the user keeps normal Claude Code permission prompts.
When running in oneshot mode, sub-agents need to execute without blocking on tool approval prompts. This phase auto-configures the project's settings file so every tool Ralph's agents use is pre-approved.
Use the settings path that matches AI_ENVIRONMENT:
.claude/settings.json.codex/settings.json (if Codex uses a comparable settings file)If the environment cannot be determined, default to .claude/settings.json.
permissions.allow already contains the Ralph entries. If any are missing, merge them in (preserve existing permissions, deduplicate).{
"permissions": {
"allow": [
"Bash(mkdir:*)",
"Bash(find:*)",
"Bash(ls:*)",
"Bash(cat:*)",
"Bash(rm:*)",
"Bash(cp:*)",
"Bash(mv:*)",
"Bash(touch:*)",
"Bash(chmod:*)",
"Bash(cd:*)",
"Bash(pwd:*)",
"Bash(echo:*)",
"Bash(head:*)",
"Bash(tail:*)",
"Bash(wc:*)",
"Bash(diff:*)",
"Bash(sort:*)",
"Bash(uniq:*)",
"Bash(grep:*)",
"Bash(sed:*)",
"Bash(awk:*)",
"Bash(git:*)",
"Bash(python*)",
"Bash(pip*)",
"Bash(node*)",
"Bash(npm*)",
"Bash(npx*)",
"Bash(yarn*)",
"Bash(pnpm*)",
"Bash(bun*)",
"Bash(cargo*)",
"Bash(go *)",
"Bash(make*)",
"Bash(pytest*)",
"Bash(jest*)",
"Bash(vitest*)",
"Bash(mocha*)",
"Bash(ruby*)",
"Bash(bundle*)",
"Bash(rspec*)",
"Bash(swift*)",
"Bash(rustc*)",
"Bash(gcc*)",
"Bash(g++*)",
"Bash(clang*)",
"Bash(java*)",
"Bash(mvn*)",
"Bash(gradle*)",
"Bash(dotnet*)",
"Bash(docker*)",
"Read",
"Edit",
"Write",
"Glob",
"Grep",
"Agent"
]
}
}
Run the setup script if available, otherwise do it inline:
# Option A: script exists in Ralph's install directory
bash "$HOME/super-ralph/scripts/setup-permissions.sh" .
# Option B: inline (if script not found)
# Read existing {claude|.claude|.codex}/settings.json, merge permissions, write back
If doing it inline (no script available), use this approach:
AI_ENVIRONMENT (.claude for Claude, .codex for Codex)mkdir -p <settings-dir><settings-dir>/settings.json if it exists (or start with {"permissions":{"allow":[]}})allow arrayBefore scoping the workspace or planning tasks, explore the user's idea through conversation. The goal is to deeply understand what the user actually wants — not just what they typed.
MODE = brainstorm: run the interactive flow below as documented.MODE = oneshot: this phase still runs in full — Ralph makes the decisions instead of asking the user. Replace every AskUserQuestion with Ralph's own judgment:
BRAINSTORM_SUMMARY autonomously based on your analysis.This phase is interactive. Use AskUserQuestion as prehook gates — one question at a time, each with a "Chat about this" escape hatch that fully stops the workflow. In Codex, ask the same question directly in chat and wait for the response before continuing.
Restate the query — show the user your understanding of what they're asking for in 2-3 sentences. This surfaces misunderstandings early.
Ask clarifying questions — use AskUserQuestion as prehook gates:
question: "[Specific question about the user's intent, scope, or approach]"
header: "Clarify"
options:
- label: "[Most likely answer]"
description: "[What this means for the build]"
- label: "[Alternative interpretation]"
description: "[What this means for the build]"
- label: "[Simpler/narrower version]"
description: "[What this means for the build]"
- label: "Chat about this"
description: "Stop — I want to discuss this before deciding"
multiSelect: false
| Area | Example Questions |
|---|---|
| Intent | "Is this a prototype or production-grade?" |
| Scope | "Should this include X, or is that out of scope?" |
| Edge cases | "What should happen when Y occurs?" |
| Users | "Who will use this — just you, your team, or end users?" |
| Constraints | "Any specific tech stack, libraries, or patterns to use/avoid?" |
| Existing work | "Is this building on something that already exists, or greenfield?" |
## Brainstorm Summary
**Query:** {original user query}
**Intent:** {what the user actually wants, in your words}
### Scope
- {what's in scope}
- {what's explicitly out of scope}
### Key Decisions
- {decision 1 from the Q&A}
- {decision 2 from the Q&A}
### Edge Cases Discussed
- {edge case and agreed handling}
### Constraints
- {any tech/approach constraints from the user}
AskUserQuestion:question: "Here's what I'll build. Does this capture it?"
header: "Confirm"
options:
- label: "Yes, go ahead"
description: "This is right — proceed to workspace setup and autonomous execution"
- label: "Almost — let me adjust"
description: "I'll clarify what needs changing"
- label: "Chat about this"
description: "Stop — I want to discuss this before deciding"
multiSelect: false
If "Almost" → incorporate feedback, update summary, re-confirm. If "Yes" → store the summary as BRAINSTORM_SUMMARY and proceed to Phase -0.75 (Intent Profile).
AskUserQuestion when possible (up to 4 per call)The BRAINSTORM_SUMMARY is used by the orchestrator during task decomposition (Phase 1) alongside learnings, tooling config, and workspace rules. This ensures tasks are decomposed based on the explored, confirmed intent — not just the raw query.
After confirming the brainstorm summary, capture the user's intent profile through 3 direct questions. The answers determine how strictly the judge grades every agent's output — a prototype gets lenient judging on polish, a production system gets strict on everything.
MODE = brainstorm: ask the 3 questions below interactively.MODE = oneshot: this phase still runs in full — Ralph decides the intent profile instead of asking the user. Replace every AskUserQuestion with Ralph's own judgment:
INTENT_PROFILE and JUDGE_RUBRIC from the inferred values.Ask these 3 questions using AskUserQuestion prehook gates. Each includes a "Chat about this" escape hatch.
Question 1 — Priority:
question: "What matters most for this build?"
header: "Priority"
options:
- label: "Just get it working"
description: "Speed over polish — I need something functional fast"
- label: "Solid and correct"
description: "Take the time to handle errors and edge cases properly"
- label: "Ship-ready quality"
description: "Production-grade — clean code, full error handling, security"
- label: "Chat about this"
description: "Stop — I want to discuss this before deciding"
multiSelect: false
Question 2 — Audience:
question: "Who will use what gets built?"
header: "Audience"
options:
- label: "Just me"
description: "Personal tool — I know the quirks, no need for polish"
- label: "My team"
description: "Others will read and maintain this code"
- label: "End users"
description: "Real people will interact with this — UX and reliability matter"
- label: "Chat about this"
description: "Stop — I want to discuss this before deciding"
multiSelect: false
Question 3 — Lifespan:
question: "How long does this need to last?"
header: "Lifespan"
options:
- label: "Throwaway / experiment"
description: "Use it once or twice, then toss it"
- label: "Weeks to months"
description: "Needs to work reliably for a while"
- label: "Long-lived"
description: "This will be maintained and extended over time"
- label: "Chat about this"
description: "Stop — I want to discuss this before deciding"
multiSelect: false
Store the answers as INTENT_PROFILE:
## Intent Profile
**Priority:** [just working | solid and correct | ship-ready]
**Audience:** [just me | my team | end users]
**Lifespan:** [throwaway | weeks to months | long-lived]
Map the intent profile to a JUDGE_RUBRIC — a per-dimension strictness matrix that tells the judge how hard to grade each quality dimension. Use this mapping:
| Dimension | Just working + Just me + Throwaway | Solid + Team + Weeks | Ship-ready + End users + Long-lived |
|---|---|---|---|
| Core functionality | strict | strict | strict |
| Error handling | skip | moderate | strict |
| Edge cases | skip | moderate | strict |
| Code readability | lenient | moderate | strict |
| Security | lenient | moderate | strict |
| Test coverage | happy path only | happy + edges | comprehensive |
| Documentation | skip | inline comments | full docs |
Strictness levels:
Blended profiles: When the 3 answers don't all point to the same tier (e.g., "just get it working" + "end users" + "long-lived"), use the highest tier that any answer maps to for each dimension. User-facing and long-lived code gets strict security even if the user wants speed — that's a safety floor.
Store the result as JUDGE_RUBRIC:
## Judge Rubric
| Dimension | Strictness |
|-----------|------------|
| Core functionality | strict |
| Error handling | [strict/moderate/lenient/skip] |
| Edge cases | [strict/moderate/lenient/skip] |
| Code readability | [strict/moderate/lenient/skip] |
| Security | [strict/moderate/lenient/skip] |
| Test coverage | [comprehensive/happy + edges/happy path only] |
| Documentation | [full docs/inline comments/skip] |
The JUDGE_RUBRIC is injected into every ralph-judge dispatch alongside the task definition and WORKSPACE_RULES. It tells the judge what to care about and how much — adapted to this specific user's intent.
If brainstorming was skipped (dead simple query), default to the middle tier: solid and correct + my team + weeks to months.
After understanding what the user wants to build, figure out what tools will help build it. Scan available skills and agents, match them to the user's goals, and let the user confirm or adjust the toolset.
MODE = brainstorm: scan and present recommendations interactively as documented below.MODE = oneshot: this phase still runs in full — Ralph selects the toolset instead of asking the user. Replace every AskUserQuestion with Ralph's own judgment:
TOOLING_CONFIG and proceed directly to Phase 0.Search for all available skills and agents in the environment:
# Scan for skills
find ~/.claude/skills/ -name "SKILL.md" 2>/dev/null
find .claude/skills/ -name "SKILL.md" 2>/dev/null
find ~/.codex/skills/ -name "SKILL.md" 2>/dev/null
find .codex/skills/ -name "SKILL.md" 2>/dev/null
# Scan for agents
find ~/.claude/agents/ -name "*.md" 2>/dev/null
find .claude/agents/ -name "*.md" 2>/dev/null
find ~/.codex/agents/ -name "*.md" 2>/dev/null
find .codex/agents/ -name "*.md" 2>/dev/null
# Also check for project-local skills
find . -path "*/.claude/skills/*/SKILL.md" 2>/dev/null
find . -path "*/.codex/skills/*/SKILL.md" 2>/dev/null
Read the name and description fields from each discovered skill/agent file. Build an inventory:
AVAILABLE_SKILLS:
- frontend-design: Create distinctive, production-grade frontend interfaces
- system-arch: Plan major architecture changes and evaluate patterns
- claude-api: Build apps with the Claude API or Anthropic SDK
- doc-search: Search third-party API documentation before writing code
- ...
AVAILABLE_AGENTS:
- code-reviewer: Validate work against plan and coding standards
- root-cause-hunter: Drive root-cause analysis for failures
- integration-test-validator: Comprehensive testing validation
- ...
Based on the BRAINSTORM_SUMMARY, identify which skills and agents would be useful. Consider:
| User's Goal | Relevant Tools |
|---|---|
| Building a frontend/UI | frontend-design, landing-page |
| API development | doc-search, claude-api, system-arch |
| Complex architecture | system-arch, validation, debate |
| Refactoring | code-reviewer, integration-test-validator |
| Using third-party APIs | doc-search (auto-fetch docs before coding) |
| Full-stack app | frontend-design, system-arch, doc-search |
Show the matched tools and let the user select which to activate for this run:
question: "Based on what you're building, these skills/agents could help. Which should I use during this run?"
header: "Tooling"
options:
- label: "[Recommended set]"
description: "Use {skill-1}, {skill-2}, {agent-1} — covers {reason}"
- label: "All available"
description: "Activate everything — I'll use whatever helps"
- label: "Just the defaults"
description: "Only use Ralph's 4 built-in agents, no extra skills"
- label: "Chat about this"
description: "Stop — I want to discuss this before deciding"
multiSelect: false
If the user picks "Recommended set" or "All available", also ask if there are specific tools they want to add or exclude:
question: "Anything to add or exclude from the toolset?"
header: "Adjust"
options:
- label: "Looks good — proceed"
description: "Use the selected toolset as-is"
- label: "Add a skill"
description: "I'll name a specific skill or capability to include"
- label: "Remove something"
description: "I'll say what to exclude"
- label: "Chat about this"
description: "Stop — I want to discuss this before deciding"
multiSelect: false
Store the selected toolset as TOOLING_CONFIG:
## Tooling Config
### Active Skills
- {skill-name}: {how it will be used in this run}
- {skill-name}: {how it will be used in this run}
### Active Agents (beyond Ralph defaults)
- {agent-name}: {when to invoke during the run}
### Skill Integration Rules
- {skill-name} → invoke before {phase/step} (e.g., "doc-search → invoke before ralph-worker writes API calls")
- {skill-name} → invoke during {phase/step} (e.g., "frontend-design → invoke when ralph-worker builds UI components")
The config is used by the orchestrator and injected into sub-agent prompts:
TOOLING_CONFIG during task decomposition to tag tasks with skills_to_use (e.g., "Use doc-search to check the Stripe API before implementing payment logic")frontend-design before building a component, invoke doc-search before calling a third-party API).claude/skills/ take priority over global ones.codex/skills/ take priority over global oneslanding-page skill), pre-select it as the recommended optionBefore any agent runs, scope the workspace using AskUserQuestion prehook gates — one question at a time, each with "Chat about this." This is the last interactive phase before full autonomy.
MODE = brainstorm: ask the 4 questions below interactively.MODE = oneshot: this phase still runs in full — Ralph scopes the workspace itself instead of asking the user. Replace every AskUserQuestion with Ralph's own judgment, using these defaults:
WORKSPACE_RULES from these defaults and proceed directly to Phase 1.Question 1 — Writable directories:
question: "Which files/folders should I work in? (I'll create and modify files here)"
header: "Work in"
options:
- label: "Current directory"
description: "Work in the current project root and subdirectories"
- label: "Specific paths"
description: "I'll list the exact directories/files"
- label: "Chat about this"
description: "Stop — I want to discuss this before deciding"
multiSelect: false
Question 2 — Read-only context:
question: "Any files I should read for context but NOT modify?"
header: "Read-only"
options:
- label: "None — figure it out"
description: "Explore the codebase yourself"
- label: "I'll list them"
description: "Specific files/dirs to read but not touch"
- label: "Chat about this"
description: "Stop — I want to discuss this before deciding"
multiSelect: false
Question 3 — Off-limits:
question: "Anything off-limits? (files/folders I must never touch)"
header: "Off-limits"
options:
- label: "Nothing off-limits"
description: "You can work anywhere within the writable scope"
- label: "I'll list exclusions"
description: "Specific paths to avoid"
- label: "Chat about this"
description: "Stop — I want to discuss this before deciding"
multiSelect: false
Question 4 — Retry limit per task:
question: "How many retries per task before giving up?"
header: "Max retries"
options:
- label: "6 (default)"
description: "3 normal attempts + debug analysis + 3 more attempts"
- label: "4"
description: "2 normal attempts + debug analysis + 2 more attempts"
- label: "10"
description: "5 normal attempts + debug analysis + 5 more attempts"
- label: "Chat about this"
description: "Stop — I want to discuss this before deciding"
multiSelect: false
Store the retry limit as MAX_RETRIES. The debug trigger fires at MAX_RETRIES / 2 (halfway). After MAX_RETRIES total attempts, auto-skip.
Store the answers as WORKSPACE_RULES — inject into every sub-agent prompt:
WORKSPACE RULES:
- You may READ and WRITE files in: [writable paths]
- You may READ (not modify): [read-only paths]
- Do NOT touch: [off-limits paths]
- HARD BOUNDARY: You must NEVER access files outside the paths listed above. No reading, writing, or executing commands that touch anything outside the project directory. This is non-negotiable.
- All permissions granted within these boundaries — do not ask for confirmation on any action.
The orchestrator decomposes the query itself — no separate manager/planner agent needed. It already has everything: BRAINSTORM_SUMMARY, INTENT_PROFILE, TOOLING_CONFIG, learnings, codebase context, and WORKSPACE_RULES.
learnings.md — extract relevant past insights (per-task entries + run summaries). If a pattern failed before, don't repeat it.Break the query into the smallest independent tasks possible. Apply these principles:
skills_to_use where relevantOutput a JSON task array:
[
{
"task_id": 1,
"title": "Short descriptive title",
"description": "Detailed description of what to build. Be explicit about behavior, inputs, outputs, and constraints.",
"quality_standard": "What 'excellent' looks like. Be specific. No shortcuts, no TODOs, no stubs. Production-grade or it doesn't count.",
"success_criteria": [
"Specific testable outcome — an assertion, not a wish",
"Another specific testable outcome"
],
"anti_patterns": [
"Don't stub or mock the hard parts",
"Don't skip error handling",
"Don't leave TODOs or placeholder logic"
],
"dependencies": [],
"test_strategy": "What tests to write, what to assert, what framework to use",
"skills_to_use": ["skill-name — when and why to invoke it during this task"],
"complexity": "simple | medium | complex",
"model_tier": "lightweight | standard"
}
]
For each task, assign a complexity and model_tier before dispatching. Use these heuristics:
| Complexity | Signals | Model Tier | Example |
|---|---|---|---|
| simple | Single file or function; no external dependencies/APIs; well-defined success criteria; low ambiguity; no complex architecture or state | lightweight | Add .gitignore, fix a typo, add a small pure helper, update a config value |
| medium | Multiple files or moderate logic; some internal dependencies; clear criteria but requires reasoning about existing code | standard | Refactor a module, add an endpoint with validation, implement a small feature |
| complex | Cross-cutting changes; external APIs; concurrency/security concerns; significant architecture; high ambiguity | standard | Build auth system, design new service, implement distributed rate limiter |
Model tier mapping by role:
| Agent | Simple task (lightweight) | Medium / Complex task (standard) |
|---|---|---|
| ralph-tester | ralph-tester-lightweight | ralph-tester-lightweight (tester is always lightweight) |
| ralph-worker | ralph-worker-lightweight | ralph-worker |
| ralph-judge | ralph-judge-lightweight | ralph-judge |
| ralph-debugger | ralph-debugger-lightweight | ralph-debugger |
| ralph-merger | ralph-merger-lightweight | ralph-merger |
Combination rule: Within a single run, simple tasks dispatch lightweight agents while complex tasks dispatch standard agents. This is the "combination of models" — Ralph does not default every agent to opus. Quality gates (judge/debugger) for simple tasks still use the lightweight tier because the task itself is simple; only escalate to standard if the task complexity warrants it.
Escalation rule: If a lightweight agent other than the tester fails the judge gate repeatedly (more than 2 judge rejections) on a simple task, re-dispatch that step using the standard agent. The task complexity estimate may have been wrong. The tester never escalates — it stays ralph-tester-lightweight regardless of rejections.
"dependencies": [] — don't invent false dependenciesmkdir -p workspace/task-{id}/tests workspace/task-{id}/output
Dispatch independent tasks in parallel by making multiple Agent tool calls in a single message. Tasks with dependencies wait for their dependencies to complete first. Never use run_in_background: true — instead, dispatch multiple foreground agents concurrently. In Codex, use multiple foreground sessions/agents in parallel for independent tasks.
When dispatching an agent, use the agent variant that matches the task's model_tier, with one exception:
ralph-tester-lightweight regardless of task complexity.lightweight → dispatch ralph-worker-lightweight, ralph-judge-lightweight, etc.standard → dispatch ralph-worker, ralph-judge, etc.This lets Ralph run a combination of models in parallel: the tester is always lightweight, while worker/judge/debugger/merger scale with task complexity.
Never set run_in_background: true when dispatching agents via the Agent tool. Background agents cannot prompt the user for tool permission approvals (WebSearch, WebFetch, Bash, etc.), causing tools to be auto-denied and agents to fail silently.
To parallelize: dispatch multiple foreground agents in a single message (multiple Agent tool calls). They run concurrently and can each prompt for tool permissions. Use this for independent tasks with no shared dependencies.
Codex equivalent: run multiple foreground sessions/agents concurrently and avoid detached/background execution.
For each task from the orchestrator. Parallelize independent tasks by dispatching multiple foreground agents in a single message (no shared dependencies). Never use run_in_background.
while true:
Dispatch `ralph-tester-lightweight` with: task definition + WORKSPACE_RULES
+ ralph-tester-learnings.md (agent-specific learnings from past runs)
Tester writes tests to workspace/task-{id}/tests/ and reports the test command.
Dispatch the appropriate judge agent based on task.model_tier:
- `lightweight` → `ralph-judge-lightweight`
- `standard` → `ralph-judge`
with:
agent_type: "tester"
task definition + output location (workspace/task-{id}/tests/) + JUDGE_RUBRIC + WORKSPACE_RULES
if judge passes:
break → proceed to Step 2b
else:
Dispatch fresh `ralph-tester-lightweight` with:
original prompt + "JUDGE REJECTED YOUR PREVIOUS OUTPUT:\n{judge_verdict}\nFix these issues."
(loop until judge passes — no retry limit)
attempt = 0
debug_trigger = MAX_RETRIES / 2 # e.g. 3 if MAX_RETRIES=6
while true:
attempt += 1
if attempt == 1:
failure_context = ""
else:
failure_context = "PREVIOUS ATTEMPT FAILED:\n{last_test_output}\n\nFix the root cause."
if attempt == debug_trigger:
Add to prompt: "This is attempt {debug_trigger}. You MUST write debug.md before exiting."
Dispatch the appropriate worker agent based on task.model_tier:
- `lightweight` → `ralph-worker-lightweight`
- `standard` → `ralph-worker`
with:
task definition + test locations + failure_context + TOOLING_CONFIG + WORKSPACE_RULES
+ ralph-worker-learnings.md (agent-specific learnings from past runs)
+ PREREQUISITE_LEARNINGS (if task has dependencies — from completed prerequisite tasks)
# ── Judge gate (runs BEFORE tests) ──────────────────────────
while true:
Dispatch the appropriate judge agent based on task.model_tier:
- `lightweight` → `ralph-judge-lightweight`
- `standard` → `ralph-judge`
with:
agent_type: "worker"
task definition + output location (workspace/task-{id}/output/) + JUDGE_RUBRIC + WORKSPACE_RULES
if judge passes:
break → proceed to test validation
else:
Dispatch fresh worker agent (same model_tier variant) with:
original prompt + "JUDGE REJECTED YOUR PREVIOUS OUTPUT:\n{judge_verdict}\nFix these issues."
(loop until judge passes — no retry limit)
**Escalation:** If a lightweight worker is rejected more than twice, re-dispatch using the standard `ralph-worker` for that task.
# ── Test validation (runs AFTER judge passes) ───────────────
Run tests via Bash: {test_command}
if tests pass:
break → clear debug.md if it exists
if attempt == debug_trigger and tests still fail:
enter Phase 2c (self-debugging)
if attempt >= MAX_RETRIES:
enter Phase 2c Step 4 (auto-skip)
Run tests via Bash after each worker attempt (only reached if judge already passed):
Immediately after a task passes all tests, the orchestrator writes a learnings entry to learnings.md:
### {date} — Task {id}: {title}
- **Attempts:** {attempt_count}
- **Learnings:**
- {generalizable insight from this task — NOT task-specific details}
- {library gotcha, pattern that worked, or assumption that was wrong}
- **Debug insights:** {root cause if debug mode was used, otherwise "N/A"}
Rules for per-task learnings:
Store the per-task learnings in memory for passing to dependent tasks.
When dispatching a task that has dependencies, include the learnings from completed prerequisite tasks in the prompt. The tester is always ralph-tester-lightweight; use the worker variant based on the dependent task's model_tier:
Dispatch ralph-tester-lightweight + ralph-worker-lightweight/worker with:
task definition + WORKSPACE_RULES + ...
+ PREREQUISITE_LEARNINGS:
"Task 1 (Auth endpoint) learned:
- bcrypt.hashpw() returns bytes, must decode to UTF-8 before storing
- Always use constant-time comparison for password verification"
This gives dependent tasks context from the work that came before them — without polluting independent parallel tasks with irrelevant information.
The worker at attempt MAX_RETRIES/2 writes debug.md with all attempts so far, reasoning, and pattern analysis.
while true:
Dispatch the appropriate debugger agent based on task.model_tier:
- `lightweight` → `ralph-debugger-lightweight`
- `standard` → `ralph-debugger`
with: debug.md + task definition + WORKSPACE_RULES
+ ralph-debugger-learnings.md (agent-specific learnings from past runs)
Debugger reads debug.md cold, identifies root cause, appends fix plan.
Dispatch the appropriate judge agent based on task.model_tier:
- `lightweight` → `ralph-judge-lightweight`
- `standard` → `ralph-judge`
with:
agent_type: "debugger"
task definition + debug.md + JUDGE_RUBRIC + WORKSPACE_RULES
if judge passes:
break → proceed to Step 3
else:
Dispatch fresh debugger agent (same model_tier variant) with:
original prompt + "JUDGE REJECTED YOUR FIX PLAN:\n{judge_verdict}\nRevise it."
(loop until judge passes — no retry limit)
**Escalation:** If a lightweight debugger is rejected more than twice, re-dispatch using the standard `ralph-debugger` for that task.
Dispatch the appropriate fresh worker agent based on task.model_tier:
lightweight → ralph-worker-lightweightstandard → ralph-worker
(attempts MAX_RETRIES/2 + 1 through MAX_RETRIES) with debug.md. Worker follows the fix plan exactly.The worker's output goes through the same judge gate as Step 2b (judge must pass before tests run).
Run tests again:
Do NOT ask the user. The loop is fully autonomous after pre-flight.
learnings.md (include the root cause from debug.md if available)After ALL tasks complete, dispatch the appropriate merger agent:
lightweight → ralph-merger-lightweightstandard → ralph-merger
in the foreground (never background) with:while true:
Dispatch the appropriate merger agent (same rule as above) with: task outputs + notes + WORKSPACE_RULES
Merger combines outputs into workspace/final/, resolves integration issues.
Dispatch the appropriate judge agent:
- If **all** tasks were `lightweight` → `ralph-judge-lightweight`
- If **any** task was `standard` → `ralph-judge`
with:
agent_type: "merger"
task definitions + output location (workspace/final/) + JUDGE_RUBRIC + WORKSPACE_RULES
if judge passes:
break → proceed to Step 3b
else:
Dispatch fresh merger agent (same model tier) with:
original prompt + "JUDGE REJECTED YOUR DELIVERABLE:\n{judge_verdict}\nFix these issues."
(loop until judge passes — no retry limit)
Per-task learnings were already written during Phase 2 (Step 2d). The merger now appends a run summary that ties them together:
## {date} — {original user query (shortened)}
**Result:** {passed}/{total} tasks passed | **Attempts:** {total_attempts} | **Time:** {elapsed}
### Run Summary
- {1-2 sentence overview of what was built and how it went}
### Cross-Task Patterns
- {pattern that emerged across multiple tasks — e.g., "all 3 tasks hit the same bcrypt gotcha"}
- {architectural insight from how the pieces fit together}
### Anti-Patterns to Avoid
- {approach that failed across tasks — only if it's a trap others would fall into}
Rules for the run summary:
## {date} — {query}
**Result:** {N}/{N} passed | **Attempts:** {N} | **Time:** {elapsed}
Clean run — no cross-task patterns to note.
If debug.md was used during the run, clear it:
_Empty — ready for next debug session._
debug.md is a scratch pad. learnings.md is the permanent record.
Produce the summary report and present it to the user. The merged output in workspace/final/ is the deliverable.
npx claudepluginhub ashcastelinocs124/super-ralph --plugin super-ralphProvides a checklist for code reviews covering functionality, security, performance, maintainability, tests, and quality. Use for pull requests, audits, team standards, and developer training.