super-ralph

Category: Tools & Productivity | Uploader: ashcastelinocs124 | Downloads: 0 | Version: v1.0（Latest）
Autonomous agentic loop that decomposes any user query into tasks, writes tests first, implements with fresh sub-agents, self-debugs on failure, and learns over time. Use when the user says "super ralph", "ralph this", "break this down and build it", or wants autonomous multi-task execution with quality enforcement.
Changelog: Source: GitHub https://github.com/ashcastelinocs124/super-ralph
Directory Structure

Current level: tree/main/skills/super-ralph/
📄 SKILL.md 40.7 KB
SKILL.md

---
name: super-ralph
description: Autonomous agentic loop that decomposes any user query into tasks, writes tests first, implements with fresh sub-agents, self-debugs on failure, and learns over time. Use when the user says "super ralph", "ralph this", "break this down and build it", or wants autonomous multi-task execution with quality enforcement.
---

# Super Ralph

Autonomous agentic loop: decompose → test → build → debug → learn → merge.

## Runtime Compatibility (Additive)

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.

## Quick Reference

```
User Query
  → Mode Selection: oneshot (fully autonomous) or brainstorm (interactive) — single AskUserQuestion
  → IF oneshot: Permissions Bootstrap — auto-configure .claude/settings.json 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 (no separate manager/planner agent)
  → Per Task (parallel if independent — never use run_in_background):
      → ralph-tester: write tests → JUDGE: pass? → retry tester if fail
      → ralph-worker: implement → JUDGE: pass? → retry worker if fail → run tests
      → Fail MAX_RETRIES/2? → debug.md → ralph-debugger → JUDGE: pass? → fresh ralph-worker
      → Fail MAX_RETRIES? → auto-skip + log to learnings
      → Pass → clear debug.md
  → ralph-merger: combine outputs → JUDGE: pass? → retry merger if fail → deliver
```

## Agents

| Agent | File | Role |
|-------|------|------|
| ralph-tester | `agents/ralph-tester.md` | Writes strict tests before implementation |
| ralph-worker | `agents/ralph-worker.md` | Implements until tests pass, writes debug.md on attempt 3 |
| ralph-debugger | `agents/ralph-debugger.md` | Cold analysis of failures, writes fix plan |
| ralph-judge | `agents/ralph-judge.md` | Universal quality gate — evaluates every sub-agent's output against task criteria |
| ralph-merger | `agents/ralph-merger.md` | Combines outputs into cohesive deliverable |

**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.

**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.

---

## IMPORTANT: Fully Autonomous After Pre-Flight

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.

---

## Phase -2: Mode Selection (BLOCKING — very first prehook)

The first and possibly only question Super Ralph asks. Determines whether the rest of the setup is interactive or autonomous.

### Pre-set MODE (from `/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.

### How it works

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`:
- **"Oneshot"** → `MODE = oneshot`
- **"Brainstorm"** → `MODE = brainstorm`
- **"Chat about this"** → stop completely, do not set MODE, respond to the user and wait. Resume only when they explicitly say to continue.

### What MODE controls

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

### CRITICAL: Oneshot runs the FULL loop

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.

### Oneshot defaults

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 |

---

## Phase -1.5: Permissions Bootstrap (ONESHOT ONLY — silent, runs immediately after mode selection)

**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 `.claude/settings.json` so every tool Ralph's agents use is pre-approved.

### How it works

1. **Check** if `.claude/settings.json` exists in the current working directory.
2. **If it doesn't exist**, create it with the full permissions block below.
3. **If it exists**, read it and check whether `permissions.allow` already contains the Ralph entries. If any are missing, merge them in (preserve existing permissions, deduplicate).
4. **Never remove** existing user permissions — only add what's missing.

### Required permissions

```json
{
  "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"
    ]
  }
}
```

### Implementation

Run the setup script if available, otherwise do it inline:

```bash
# 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/settings.json, merge permissions, write back
```

If doing it inline (no script available), use this approach:
1. `mkdir -p .claude`
2. Read `.claude/settings.json` if it exists (or start with `{"permissions":{"allow":[]}}`)
3. For each permission in the list above, check if it's already present
4. Append any missing permissions to the `allow` array
5. Write the updated JSON back

### Rules

- **Only runs in oneshot mode** — brainstorm users keep normal permission prompts
- **No user prompt** — this is invisible setup, not a question gate
- **No destructive changes** — only add permissions, never remove existing ones
- **Idempotent** — safe to run multiple times, produces the same result
- **Proceed immediately** to Phase -1 after completing

---

## Phase -1: Brainstorm (BLOCKING — prehook-style interactive Q&A)

Before 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 gate

- **If `MODE = brainstorm`:** run the interactive flow below as documented.
- **If `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:
  1. Analyze the user's query to infer intent, scope, constraints, edge cases, and users.
  2. Write the `BRAINSTORM_SUMMARY` autonomously based on your analysis.
  3. Do NOT show the summary or ask for confirmation — proceed directly to Phase -0.75.
  4. If the query is ambiguous, make reasonable assumptions and document them in the summary's "Key Decisions" section.

**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.

### Prehook Rules (apply to ALL setup phases: Brainstorm, Tooling, Pre-Flight)

- **One question at a time** — never batch multiple unrelated questions
- **Every question MUST include a "Chat about this" option** that fully stops the workflow
- **If "Chat about this" is selected:** stop completely, read what the user says, and respond. Do NOT continue the setup. Resume only when they explicitly say to.
- **Never skip a question** — even if you think you know the answer
- **Never proceed past a phase** until the user explicitly approves

### How it works

1. **Restate the query** — show the user your understanding of what they're asking for in 2-3 sentences. This surfaces misunderstandings early.

2. **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
```

3. **Explore iteratively** — after each answer, ask follow-up questions if new ambiguities surface. Cover these areas:

| 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?" |

4. **Produce a brainstorm summary** — when you have enough clarity, write a summary:

```markdown
## 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}
```

5. **Confirm the summary** — show the summary to the user with one final `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).

### Rules

- Ask **2-5 questions total** — enough to remove ambiguity, not so many it feels like an interrogation
- Batch related questions into a single `AskUserQuestion` when possible (up to 4 per call)
- Don't ask questions the user already answered in their original query
- Don't ask about workspace scope here — that's Phase 0's job
- If the query is dead simple and unambiguous (e.g., "add a .gitignore"), skip brainstorming entirely

### Passing the summary forward

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.

---

## Phase -0.75: Intent Profile (BLOCKING — after brainstorm, before tooling)

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 gate

- **If `MODE = brainstorm`:** ask the 3 questions below interactively.
- **If `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:
  1. Infer priority, audience, and lifespan from the query and BRAINSTORM_SUMMARY.
  2. When ambiguous, default to the middle tier: **solid and correct + my team + weeks to months**.
  3. Build the `INTENT_PROFILE` and `JUDGE_RUBRIC` from the inferred values.
  4. Proceed directly to Phase -0.5.

### How it works

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

### Building the INTENT_PROFILE

Store the answers as `INTENT_PROFILE`:

```markdown
## Intent Profile

**Priority:** [just working | solid and correct | ship-ready]
**Audience:** [just me | my team | end users]
**Lifespan:** [throwaway | weeks to months | long-lived]
```

### Generating the JUDGE_RUBRIC

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:**
- **strict** — judge FAILS output that doesn't meet this dimension
- **moderate** — judge NOTES issues but passes if core functionality is solid
- **lenient** — judge ignores this dimension unless it's egregiously bad
- **skip** — judge does not evaluate this dimension at all

**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`:

```markdown
## 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] |
```

### Passing forward

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.

### Skip condition

If brainstorming was skipped (dead simple query), default to the middle tier: **solid and correct + my team + weeks to months**.

---

## Phase -0.5: Tooling Discovery (BLOCKING — after intent profile, before pre-flight)

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 gate

- **If `MODE = brainstorm`:** scan and present recommendations interactively as documented below.
- **If `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:
  1. Run the scan (Step 1) as normal.
  2. Run the matching (Step 2) as normal.
  3. Auto-select the recommended toolset — equivalent to the user picking "Recommended set" and then "Looks good — proceed."
  4. Build `TOOLING_CONFIG` and proceed directly to Phase 0.

### How it works

#### Step 1: Scan available skills and agents

Search for all available skills and agents in the environment:

```bash
# 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
- ...
```

#### Step 2: Match tools to the user's goals

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

#### Step 3: Present recommendations to user

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

#### Step 4: Build TOOLING_CONFIG

Store the selected toolset as `TOOLING_CONFIG`:

```markdown
## 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")
```

### How TOOLING_CONFIG is used

The config is used by the orchestrator and injected into sub-agent prompts:

- **Orchestrator** uses `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")
- **ralph-worker** gets the skill integration rules so it knows when to invoke skills during implementation (e.g., invoke `frontend-design` before building a component, invoke `doc-search` before calling a third-party API)
- **ralph-merger** gets the list so it can note which tools were used in the summary report

### Rules

- Don't overwhelm the user — recommend 2-4 tools max, not every skill in the system
- If no extra skills are relevant (e.g., the task is pure backend with standard libraries), say so and suggest "Just the defaults"
- Skills that the user's project already has in its local `.claude/skills/` take priority over global ones
- Skills that the user's project already has in its local `.codex/skills/` take priority over global ones
- If a skill would clearly help but isn't installed, mention it: "You don't have a {X} skill, but it might help here. Want to skip it or create one?"
- If the brainstorm summary makes the tooling obvious (e.g., "build a landing page" → `landing-page` skill), pre-select it as the recommended option

---

## Phase 0: Pre-Flight Scoping (BLOCKING — prehook-style workspace setup)

Before 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 gate

- **If `MODE = brainstorm`:** ask the 4 questions below interactively.
- **If `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:
  1. **Writable directories:** Current directory and subdirectories.
  2. **Read-only context:** None — figure it out.
  3. **Off-limits:** Nothing off-limits.
  4. **MAX_RETRIES:** 6 (3 normal + debug + 3 more).
  5. Build `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.
```

---

## Phase 1: Plan & Decompose (orchestrator does this directly)

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.

### Step 1: Gather context

1. Read `learnings.md` — extract relevant past insights (per-task entries + run summaries). If a pattern failed before, don't repeat it.
2. Read the scoped codebase files to understand existing patterns and conventions.

### Step 2: Decompose into tasks

Break the query into the smallest independent tasks possible. Apply these principles:

- **Set the bar HIGH** — every task must produce work worth shipping
- **Be specific, not vague** — "handles edge cases" is useless. "Returns 404 with JSON error body when resource not found" is testable.
- **Prevent laziness upfront** — anti-patterns tell the worker what NOT to do before they start cutting corners
- **Smallest independent units** — if a task can be split further without creating artificial dependencies, split it
- **Reference available skills** — use TOOLING_CONFIG to tag tasks with `skills_to_use` where relevant

Output a JSON task array:

```json
[
  {
    "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"]
  }
]
```

### Quality rules for decomposition

- Success criteria must be **assertions** — things a test can verify, not feelings
- Anti-patterns should target the **most common lazy shortcuts** for this specific task
- If a task touches existing code, specify which files and what the expected behavior change is
- If a task has no dependencies, say `"dependencies": []` — don't invent false dependencies
- Each task should be completable by a single agent in one session
- If you're unsure whether something should be one task or two, make it two

### Step 3: Set up workspace

```bash
mkdir -p workspace/task-{id}/tests workspace/task-{id}/output
```

### Step 4: Dispatch tasks

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.

---

## CRITICAL: Agent Dispatch Rule

**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.

---

## Phase 2: Per-Task Execution Loop

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`.

### Step 2a: Test Agent + Judge Gate

```
while true:
    Dispatch ralph-tester 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 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 with:
          original prompt + "JUDGE REJECTED YOUR PREVIOUS OUTPUT:\n{judge_verdict}\nFix these issues."
        (loop until judge passes — no retry limit)
```

### Step 2b: Worker Agent (with judge gate + test validation + retry loop)

```
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 fresh 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 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 ralph-worker with:
              original prompt + "JUDGE REJECTED YOUR PREVIOUS OUTPUT:\n{judge_verdict}\nFix these issues."
            (loop until judge passes — no retry limit)

    # ── 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)
```

### Step 2c: Test Validator

Run tests via Bash after each worker attempt (only reached if judge already passed):
- **Pass** → clear debug.md, proceed to Step 2d
- **Fail** → increment attempt counter, retry worker with failure output

### Step 2d: Per-Task Learnings (after task passes)

Immediately after a task passes all tests, the orchestrator writes a learnings entry to `learnings.md`:

```markdown
### {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:**
- Only write **general insights** that would help future runs — not "I implemented X using Y"
- If the task passed on attempt 1 with no issues, write: "Clean pass — no notable learnings."
- If debug mode was used, always include the root cause as a learning
- Keep each entry to 2-5 bullet points max

**Store the per-task learnings in memory** for passing to dependent tasks.

### Step 2e: Inject Learnings into Dependent Tasks

When dispatching a task that has dependencies, include the learnings from completed prerequisite tasks in the prompt:

```
Dispatch ralph-tester/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.

---

## Phase 2c: Self-Debugging (after MAX_RETRIES/2 failed attempts)

### Step 1: debug.md already written
The worker at attempt `MAX_RETRIES/2` writes `debug.md` with all attempts so far, reasoning, and pattern analysis.

### Step 2: Fresh Debug Agent + Judge Gate

```
while true:
    Dispatch 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 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 ralph-debugger with:
          original prompt + "JUDGE REJECTED YOUR FIX PLAN:\n{judge_verdict}\nRevise it."
        (loop until judge passes — no retry limit)
```

### Step 3: Fresh Worker follows fix plan (with judge gate)
Dispatch fresh **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:
- **Pass** → clear debug.md, continue to next task
- **Fail after attempt MAX_RETRIES** → auto-skip (Step 4)

### Step 4: Auto-Skip (MAX_RETRIES reached, still failing)

**Do NOT ask the user.** The loop is fully autonomous after pre-flight.

1. Mark the task as **FAILED**
2. Write a per-task learnings entry to `learnings.md` (include the root cause from debug.md if available)
3. Keep the task's failure trail (attempts, debug analysis) in memory for the merger
4. Continue with remaining tasks — do not stop the loop

---

## Phase 3: Merge, Learn & Deliver

After ALL tasks complete, dispatch **ralph-merger** in the **foreground** (never background) with:
- All task titles, statuses, attempt counts, and output directories
- Per-task notes: what worked, what failed, debug insights (passed in prompt, not in learnings.md)
- WORKSPACE_RULES

### Step 3a: Merge outputs + Judge Gate

```
while true:
    Dispatch ralph-merger with: task outputs + notes + WORKSPACE_RULES

    Merger combines outputs into workspace/final/, resolves integration issues.

    Dispatch 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 ralph-merger with:
          original prompt + "JUDGE REJECTED YOUR DELIVERABLE:\n{judge_verdict}\nFix these issues."
        (loop until judge passes — no retry limit)
```

### Step 3b: Write Run Summary to learnings.md

Per-task learnings were already written during Phase 2 (Step 2d). The merger now appends a **run summary** that ties them together:

```markdown
## {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:**
- This is a **summary**, not a repeat of per-task learnings — add cross-cutting insights only
- Include timing so future runs can estimate duration for similar queries
- If all tasks passed cleanly on first attempt, keep it minimal:
  ```markdown
  ## {date} — {query}
  **Result:** {N}/{N} passed | **Attempts:** {N} | **Time:** {elapsed}
  Clean run — no cross-task patterns to note.
  ```
- The per-task entries (written in Step 2d) provide the detail; this provides the big picture

### Step 3c: Clear debug.md

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.

### Step 3d: Summary report

Produce the summary report and present it to the user. The merged output in `workspace/final/` is the deliverable.
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
super-ralph

Directory Structure

SKILL.md

Report

Notice
