@graypark/ralph-codex 0.3.0 → 0.4.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "ralph-codex",
+  "description": "Cross-platform Ralph Loop with interactive interview, multi-agent orchestration, and smart command generation for iterative AI development.",
+  "version": "0.4.1",
+  "author": {
+    "name": "graypark",
+    "email": "vcz.graypark@gmail.com"
+  }
+}

package/README.md

@@ -1,23 +1,25 @@
 # ralph-codex
 
-Ralph Loop for **OpenAI Codex CLI** — self-referential iterative development loops powered by Stop hooks.
+Self-referential iterative development loops for **Codex CLI** and **Claude Code** — with multi-agent orchestration, interactive command generation, and cross-platform stop hooks.
 
-Ralph Loop is a development methodology where an AI agent works on a task in a continuous loop, seeing its own previous work each iteration, until a completion condition is met. This package brings that capability to Codex CLI with full cross-platform support.
+## What is Ralph Loop?
+
+An AI agent works on a task in a continuous loop, seeing its own previous work each iteration, until a completion condition is met. ralph-codex adds smart orchestration on top: automatic phase splitting, parallel subagent spawning, and an interview-driven command generator.
 
 ## Requirements
 
 - **Node.js** 18+
-- **Codex CLI** v0.114+ (experimental hooks engine required)
+- **Codex CLI** v0.114+ or **Claude Code** (any version with plugin support)
 
 ## Installation
 
-### Option 1: npx (recommended)
+### npx (recommended)
 
 ```bash
 npx @graypark/ralph-codex --global
 ```
 
-### Option 2: Clone and install
+### Git clone
 
 ```bash
 git clone https://github.com/vcz-Gray/ralph-codex.git
@@ -27,76 +29,84 @@ node bin/install.mjs --global
 
 ### Options
 
-| Flag        | Description                                |
-| ----------- | ------------------------------------------ |
-| `--global`  | Install to `~/.codex/` (default)           |
-| `--local`   | Install to `.codex/` in current project    |
-| `--dry-run` | Preview changes without modifying anything |
-| `--force`   | Overwrite existing installation            |
+| Flag        | Description                                      |
+| ----------- | ------------------------------------------------ |
+| `--global`  | Install to `~/.codex/` or `~/.claude/` (default) |
+| `--local`   | Install to `.codex/` in current project          |
+| `--dry-run` | Preview changes without modifying anything       |
+| `--force`   | Overwrite existing installation                  |
 
 ### What Gets Installed
 
 ```
-~/.codex/
-├── plugins/ralph-codex/     # Core plugin files
-├── hooks.json               # Stop hook registration (merged)
+~/.codex/ (or ~/.claude/)
+├── plugins/ralph-codex/          # Core plugin files
+├── hooks.json                    # Stop hook (merged with existing)
 └── skills/
-    ├── ralph-loop/          # /ralph-loop command
-    ├── cancel-ralph/        # /cancel-ralph command
-    └── ralph-interview/     # /ralph-interview command
+    ├── ralph-loop/               # /ralph-loop — run loops
+    ├── cancel-ralph/             # /cancel-ralph — stop loops
+    ├── ralph-interview/          # /ralph-interview — generate commands
+    └── ralph-orchestrator/       # /ralph-orchestrator — multi-agent patterns
 ```
 
 ## Commands
 
-### `/ralph-interview` — Generate Optimized Commands
+### `/ralph-interview` — Smart Command Generator
 
-**The easiest way to get started.** This interactive skill interviews you about your task and generates a perfectly structured `/ralph-loop` command.
+**The recommended way to start.** Interviews you about your task, evaluates whether subagents would help, then generates an optimized command.
 
 ```
 /ralph-interview
 ```
 
-**How it works:**
-
-1. Describe your task (e.g., "Add auth to our API")
-2. The interview asks 3–5 targeted questions (scope, success criteria, verification commands, etc.)
-3. It generates a copy-paste-ready `/ralph-loop` command with:
-   - Proper phase separation (analysis vs. implementation)
-   - Self-correcting work cycles (modify → verify → retry)
-   - Escape hatches for when you're stuck
-   - Objective completion criteria
-   - Atomic git commits per work item
+1. Describe your task
+2. Answer 3–5 targeted questions (scope, verification, parallelism potential, etc.)
+3. Get a ready-to-run command with phases, escape hatches, and orchestration
 
-**Auto-execute mode:** Add "run immediately" or "바로 실행" to skip the confirmation step:
+**Auto-execute:** Add "run immediately" or "바로 실행" to start without confirmation:
 
 ```
-/ralph-interview Add pagination to the users API, run immediately
+/ralph-interview Refactor the auth module across 3 services, run immediately
 ```
 
-After generating, it will ask:
+### `/ralph-orchestrator` — Multi-Agent Patterns
+
+Analyzes your task and recommends the best orchestration strategy:
+
+| Pattern                                     | Best For                                          |
+| ------------------------------------------- | ------------------------------------------------- |
+| **Parallel Explore → Sequential Implement** | Large codebase research + targeted fixes          |
+| **Divide by Ownership**                     | Multi-service changes (frontend + backend + auth) |
+| **Fan-Out / Fan-In**                        | Comprehensive audits (security + perf + a11y)     |
+| **Scout-Then-Execute**                      | Unfamiliar codebases                              |
+| **Pipeline with Checkpoints**               | Complex multi-stage transformations               |
+
+**Decision matrix** — the orchestrator scores your task automatically:
 
 ```
-Ready to run?
-- y / yes → Start Phase 1 immediately
-- n / no  → Commands are above, copy-paste when ready
-- edit    → Tell me what to change
+Files span 3+ directories  → +2
+Items are independent       → +2
+Multiple services/repos     → +3
+10+ similar items           → +1
+Need full context           → -2
+Order matters               → -2
+
+Score >= 3 → Parallel subagents
+Score 0–2  → Sequential + optional scout
+Score < 0  → Single loop
 ```
 
 ### `/ralph-loop` — Run a Loop Directly
 
-If you already know how to write a good prompt:
-
 ```
-/ralph-loop "Build a REST API for todos with CRUD, validation, and tests" --max-iterations 30 --completion-promise "ALL_TESTS_PASS"
+/ralph-loop "Build a REST API" --max-iterations 30 --completion-promise "ALL_TESTS_PASS"
 ```
 
-**Parameters:**
-
-| Parameter                   | Default    | Description                             |
-| --------------------------- | ---------- | --------------------------------------- |
-| `PROMPT`                    | (required) | Task description                        |
-| `--max-iterations N`        | 20         | Maximum loop iterations (0 = unlimited) |
-| `--completion-promise TEXT` | "TADA"     | Phrase that signals task completion     |
+| Parameter                   | Default    | Description                    |
+| --------------------------- | ---------- | ------------------------------ |
+| `PROMPT`                    | (required) | Task description               |
+| `--max-iterations N`        | 20         | Max iterations (0 = unlimited) |
+| `--completion-promise TEXT` | "TADA"     | Phrase that signals completion |
 
 ### `/cancel-ralph` — Stop the Loop
 
@@ -111,7 +121,7 @@ If you already know how to write a good prompt:
 │  /ralph-loop "Build feature X"              │
 │                                             │
 │  ┌──────────┐    ┌──────────┐              │
-│  │  Codex   │───▶│  Works   │              │
+│  │  Agent   │───▶│  Works   │              │
 │  │  starts  │    │  on task │              │
 │  └──────────┘    └────┬─────┘              │
 │                       │                     │
@@ -128,131 +138,125 @@ If you already know how to write a good prompt:
 │            │ │ Promise found?│─┼──Yes──▶ EXIT
 │            │ └───────┬───────┘ │            │
 │            │         No        │            │
-│            │         │         │            │
 │            │    Block exit +   │            │
 │            │  re-inject prompt │            │
 │            └─────────┬─────────┘            │
 │                      │                      │
-│                      ▼                      │
 │              ┌──────────────┐              │
-│              │ Codex sees   │              │
-│              │ previous work│──── loop ────┘
+│              │ Sees previous │──── loop ────┘
+│              │ work in files │
 │              └──────────────┘
 ```
 
-### Completion Promise
+## Multi-Agent Orchestration Example
 
-To signal task completion, Codex must output the promise phrase in XML tags:
+For a task like "audit and fix auth across frontend, backend, and auth-service":
 
 ```
-<promise>ALL_TESTS_PASS</promise>
-```
+Phase 1 — Parallel Exploration (3 subagents):
+├── Agent "fe-scan": Search frontend for auth issues → report
+├── Agent "be-scan": Search backend for auth issues → report
+└── Agent "auth-scan": Search auth-service for issues → report
 
-The promise is only valid when the statement is genuinely true. The loop prevents false exits.
+Phase 2 — Merge & Plan:
+└── Ralph Loop: Read all reports → create prioritized fix plan
 
-## Prompt Writing Tips
+Phase 3 — Parallel Implementation:
+├── Agent "fe-dev" (worktree): Fix frontend items
+├── Agent "be-dev" (worktree): Fix backend items
+└── Agent "auth-dev" (worktree): Fix auth-service items
 
-> **Tip:** Use `/ralph-interview` instead of writing prompts manually. It handles all of these patterns for you.
-
-### 1. Split into Phases
-
-```
-/ralph-loop "Phase 1: Set up project scaffold.
-Phase 2: Implement core logic.
-Phase 3: Add tests.
-Output <promise>DONE</promise> when all phases complete." --max-iterations 30
+Phase 4 — Integration:
+└── Ralph Loop: Merge branches → run full test suite → fix conflicts
 ```
 
-### 2. Objective Completion Criteria
+The `/ralph-interview` skill generates this automatically when it detects multi-service scope.
 
-```
-/ralph-loop "Implement the auth module.
-Done when: all tests pass, no TypeScript errors, coverage > 80%." --completion-promise "AUTH_COMPLETE" --max-iterations 25
-```
+## Updating
 
-### 3. Always Set an Escape Hatch
+To update to the latest version:
 
-Always use `--max-iterations` to prevent infinite loops on impossible tasks.
+```bash
+npx @graypark/ralph-codex --global --force
+```
 
-### 4. Self-Correction Pattern
+Or if installed via git:
 
-```
-/ralph-loop "Fix the failing CI pipeline. Run tests, read errors, fix code, repeat." --max-iterations 15 --completion-promise "CI_GREEN"
+```bash
+cd ralph-codex
+git pull
+node bin/install.mjs --global --force
 ```
 
 ## Windows Support
 
-ralph-codex works natively on Windows without WSL or Git Bash:
+Works natively on Windows without WSL or Git Bash:
 
 - All paths use `path.join()` (no hardcoded slashes)
-- The installer copies files instead of symlinks on Windows
+- Installer copies files instead of symlinks on Windows
 - State files use JSON (no Unix-specific formats)
 - Hooks use `node` as the interpreter (cross-platform)
 
-Tested on: Windows 10/11, macOS, Linux (Ubuntu/Debian).
-
 ## Uninstall
 
 ```bash
 npx @graypark/ralph-codex uninstall
-# or
-node bin/uninstall.mjs --global
 ```
 
-This removes:
+## Claude Code Plugin
+
+This package includes a `.claude-plugin/plugin.json` manifest for Claude Code marketplace compatibility. To use as a Claude Code plugin:
 
-- Plugin files from `~/.codex/plugins/ralph-codex/`
-- Stop hook entry from `~/.codex/hooks.json`
-- All skill files (`ralph-loop`, `cancel-ralph`, `ralph-interview`)
-- Any active state file
+1. Clone the repo to your machine
+2. In Claude Code, reference the plugin directory
+3. Skills (`ralph-interview`, `ralph-orchestrator`, etc.) will be auto-discovered
 
 ## Architecture
 
 ```
 ralph-codex/
+├── .claude-plugin/
+│   └── plugin.json              # Claude Code marketplace manifest
 ├── bin/
-│   ├── install.mjs          # Cross-platform installer
-│   └── uninstall.mjs        # Clean uninstaller
+│   ├── install.mjs              # Cross-platform installer
+│   └── uninstall.mjs            # Clean uninstaller
 ├── hooks/
-│   ├── hooks.json            # Hook registration (reference)
-│   └── stop-hook.mjs         # Stop hook — the core loop engine
+│   ├── hooks.json               # Hook registration (reference)
+│   └── stop-hook.mjs            # Stop hook — core loop engine
 ├── commands/
-│   ├── ralph-loop.md         # /ralph-loop slash command
-│   └── cancel-ralph.md       # /cancel-ralph slash command
+│   ├── ralph-loop.md            # /ralph-loop command
+│   └── cancel-ralph.md          # /cancel-ralph command
 ├── skills/
-│   └── ralph-interview/
-│       └── SKILL.md          # /ralph-interview — interactive command generator
+│   ├── ralph-interview/
+│   │   └── SKILL.md             # Interactive command generator
+│   └── ralph-orchestrator/
+│       └── SKILL.md             # Multi-agent orchestration patterns
 ├── lib/
-│   ├── paths.mjs             # Cross-platform path utilities
-│   ├── state.mjs             # Loop state management
-│   └── stop-hook-core.mjs    # Testable stop hook logic
-├── tests/                    # 32 test cases (vitest)
+│   ├── paths.mjs                # Cross-platform path utilities
+│   ├── state.mjs                # Loop state management
+│   └── stop-hook-core.mjs       # Testable stop hook logic
+├── tests/                       # 32 test cases (vitest)
 └── package.json
 ```
 
-## How It Compares to Claude Code's Ralph Loop
+## Comparison
 
-| Feature            | Claude Code (official)                | ralph-codex (this)       |
-| ------------------ | ------------------------------------- | ------------------------ |
-| Runtime            | Bash (sh/perl)                        | Node.js (cross-platform) |
-| State format       | Markdown + YAML frontmatter           | JSON                     |
-| Windows support    | WSL required                          | Native                   |
-| Hook protocol      | `{"decision":"block","reason":"..."}` | Same                     |
-| Transcript parsing | `jq` + `grep`                         | Native Node.js           |
-| Installation       | Plugin marketplace                    | `npx` or manual          |
-| Command generator  | None                                  | `/ralph-interview`       |
+| Feature                | Claude Code (official) | Codex CLI (builtin) | ralph-codex (this)       |
+| ---------------------- | ---------------------- | ------------------- | ------------------------ |
+| Runtime                | Bash (sh/perl)         | Rust                | Node.js (cross-platform) |
+| Windows                | WSL required           | Experimental        | Native                   |
+| Hook protocol          | JSON                   | JSON                | Same                     |
+| Command generator      | None                   | None                | `/ralph-interview`       |
+| Multi-agent            | Manual                 | Experimental        | `/ralph-orchestrator`    |
+| Orchestration patterns | None                   | None                | 5 built-in patterns      |
+| Plugin format          | `.claude-plugin`       | `.codex/skills`     | Both                     |
 
 ## Development
 
 ```bash
-# Install dev dependencies
 npm install
-
-# Run tests (32 cases)
-npm test
-
-# Run tests in watch mode
-npx vitest
+npm test          # 32 test cases
+npx vitest        # watch mode
 ```
 
 ## License

package/bin/install.mjs

@@ -174,7 +174,7 @@ async function installSkills() {
   }
 
   // Standalone skills (ralph-interview, etc.)
-  const standaloneSkills = ["ralph-interview"];
+  const standaloneSkills = ["ralph-interview", "ralph-orchestrator"];
   for (const name of standaloneSkills) {
     const srcDir = join(PROJECT_ROOT, "skills", name);
     const destDir = join(skillsDir, name);

package/bin/uninstall.mjs

@@ -83,7 +83,12 @@ export async function uninstall({ dryRun = false, local = false } = {}) {
   }
 
   // 3. Remove skill directories
-  const skillNames = ["ralph-loop", "cancel-ralph", "ralph-interview"];
+  const skillNames = [
+    "ralph-loop",
+    "cancel-ralph",
+    "ralph-interview",
+    "ralph-orchestrator",
+  ];
   for (const name of skillNames) {
     const skillDir = join(skillsDir, name);
     if (await fileExists(skillDir)) {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@graypark/ralph-codex",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "type": "module",
-  "description": "Ralph Loop for OpenAI Codex CLI — self-referential iterative development loops via Stop hooks",
+  "description": "Ralph Loop for Codex CLI & Claude Code — iterative dev loops with multi-agent orchestration, interactive interview, and stop hooks",
   "license": "MIT",
   "author": "graypark",
   "repository": {
@@ -25,6 +25,7 @@
     "commands/",
     "lib/",
     "skills/",
+    ".claude-plugin/",
     "README.md",
     "LICENSE"
   ],
@@ -42,7 +43,10 @@
     "ai-agent",
     "iterative-development",
     "stop-hook",
-    "cross-platform"
+    "cross-platform",
+    "multi-agent",
+    "orchestration",
+    "claude-code"
   ],
   "devDependencies": {
     "vitest": "^4.1.0"

package/skills/ralph-interview/SKILL.md

@@ -15,6 +15,7 @@ When the user describes a task, conduct a brief interview to gather missing cont
 - **Escape hatches required**: Always specify what to do when stuck after N retries.
 - **Atomic commits**: Instruct a git commit per logical work unit.
 - **Objective completion criteria only**: Never use subjective criteria like "make it good." Use test passes, linter clears, checklist completion, or other verifiable conditions.
+- **Parallel when possible**: Use the ralph-orchestrator patterns to spawn subagents for independent work streams (exploration, multi-service changes, audits).
 
 ## Interview Process
 
@@ -34,6 +35,7 @@ Skip items already covered. Bundle questions — max 3–5 per round, one round
 | **Constraints**           | Must not break existing tests? Library restrictions?                                 |
 | **When stuck**            | User's preferred fallback (document it? skip? suggest alternative?)                  |
 | **Commit strategy**       | Per-item commits? Bulk? Commit message convention?                                   |
+| **Parallelism potential** | Multiple services? Independent file groups? Broad search needed?                     |
 
 ## Phase Design
 
@@ -44,6 +46,30 @@ Skip items already covered. Bundle questions — max 3–5 per round, one round
 - **Dependencies exist** → Prerequisite work in a prior Phase
 - **5 or fewer simple items** → Single Phase is fine
 
+### When to Use Subagents (via ralph-orchestrator)
+
+Evaluate the task against the ralph-orchestrator decision matrix:
+
+| Factor                         | Score |
+| ------------------------------ | ----- |
+| Files span 3+ directories      | +2    |
+| Items are independent          | +2    |
+| Need full context to decide    | -2    |
+| Order matters                  | -2    |
+| 10+ similar items              | +1    |
+| Needs cross-file understanding | -1    |
+| Multiple services/repos        | +3    |
+
+- **Score >= 3** → Use parallel subagents. Pick from orchestrator patterns:
+  - _Parallel Explore → Sequential Implement_ for research-heavy tasks
+  - _Divide by Ownership_ for multi-service changes
+  - _Fan-Out / Fan-In_ for comprehensive audits
+  - _Scout-Then-Execute_ for unfamiliar codebases
+- **Score 0–2** → Sequential loop, optional scout phase
+- **Score < 0** → Single sequential Ralph Loop
+
+When subagents are recommended, embed subagent spawn instructions directly in the generated ralph-loop prompt using the Agent tool (Claude Code) or experimental multi-agent config (Codex CLI).
+
 ### Recommended max-iterations
 
 | Task type                                      | Iterations |
@@ -96,6 +122,38 @@ After [N] retries on any single item:
 Output <promise>[PROMISE]</promise>" --max-iterations [N] --completion-promise "[PROMISE]"
 ```
 
+### With Subagents
+
+When the orchestrator score is >= 3, embed subagent instructions in the prompt:
+
+```
+/ralph-loop:ralph-loop "## Goal
+[Task summary]
+
+## Phase 1 — Parallel Exploration
+Spawn these subagents simultaneously using the Agent tool:
+
+1. Agent 'scan-frontend' (subagent_type: Explore, run_in_background: true):
+   Search src/frontend/** for [pattern]. Write findings to .ralph/reports/frontend.md
+
+2. Agent 'scan-backend' (subagent_type: Explore, run_in_background: true):
+   Search src/backend/** for [pattern]. Write findings to .ralph/reports/backend.md
+
+After ALL agents complete, merge reports into .ralph/reports/merged.md
+
+## Phase 2 — Sequential Implementation
+Read .ralph/reports/merged.md, then for each item:
+1. Apply the fix
+2. Run [verification command]
+3. git commit
+
+## Completion Criteria
+- All items from merged.md addressed
+- [Verification command] passes
+
+Output <promise>[PROMISE]</promise>" --max-iterations [N] --completion-promise "[PROMISE]"
+```
+
 ### Multi-Phase
 
 Generate each Phase as a separate `/ralph-loop:ralph-loop` command:

package/skills/ralph-orchestrator/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: ralph-orchestrator
+description: "Orchestration patterns for ralph-loop: subagent spawning, parallel exploration, and task decomposition strategies"
+---
+
+# Ralph Orchestrator — Multi-Agent Loop Patterns
+
+You are an expert at designing optimal execution strategies for Ralph Loop tasks.
+When asked to orchestrate a task, analyze its structure and recommend the best combination of sequential loops, parallel subagents, and phased execution.
+
+## Core Concept
+
+Not every task should run in a single linear loop. Complex tasks benefit from:
+
+- **Parallel exploration** — spawn subagents to search/analyze independently, then merge results
+- **Divide and conquer** — split work by service/directory/concern with isolated agents
+- **Pipeline stages** — sequential phases where each feeds into the next
+- **Hybrid patterns** — combine parallel research with sequential implementation
+
+## When to Use Subagents
+
+### Use Subagents (Parallel) When:
+
+| Signal                      | Example                                                    |
+| --------------------------- | ---------------------------------------------------------- |
+| **Broad codebase search**   | "Find all API endpoints that lack auth checks"             |
+| **Independent file groups** | Frontend components + backend routes + database migrations |
+| **Multi-service changes**   | auth-service + api-gateway + frontend simultaneously       |
+| **Audit/review tasks**      | Security audit + performance audit + accessibility audit   |
+| **Pattern extraction**      | Scan 50+ files for inconsistent patterns                   |
+
+### Do NOT Use Subagents When:
+
+| Signal                      | Reason                                               |
+| --------------------------- | ---------------------------------------------------- |
+| **Sequential dependencies** | Step 2 needs Step 1's output                         |
+| **Shared mutable state**    | Multiple agents editing the same file = conflicts    |
+| **Small scope (< 5 files)** | Overhead outweighs benefit                           |
+| **Context-heavy tasks**     | Agent needs deep understanding of full codebase flow |
+
+## Orchestration Patterns
+
+### Pattern 1: Parallel Explore → Sequential Implement
+
+Best for: Large codebases where you need to understand before you change.
+
+```
+Phase 1 (Parallel Subagents):
+├── Agent A: Scan src/frontend/** for pattern X → report-frontend.md
+├── Agent B: Scan src/backend/** for pattern X → report-backend.md
+└── Agent C: Scan src/shared/** for pattern X → report-shared.md
+
+Phase 2 (Sequential Loop):
+└── Ralph Loop: Read all reports → implement fixes in priority order
+```
+
+**Prompt pattern for Phase 1:**
+
+```
+## Subagent Tasks (run in parallel)
+Use the Agent tool to spawn these subagents simultaneously:
+
+1. Agent "frontend-scan": Search src/frontend/** for [pattern].
+   Write findings to .ralph/reports/frontend-scan.md
+2. Agent "backend-scan": Search src/backend/** for [pattern].
+   Write findings to .ralph/reports/backend-scan.md
+3. Agent "shared-scan": Search src/shared/** for [pattern].
+   Write findings to .ralph/reports/shared-scan.md
+
+After ALL agents complete, merge reports into .ralph/reports/merged.md
+with a unified priority list.
+```
+
+### Pattern 2: Divide by Ownership
+
+Best for: Multi-service changes where files don't overlap.
+
+```
+Phase 1 (Parallel Implementation):
+├── Agent "fe-dev": Modify src/frontend/** only → commit per item
+├── Agent "be-dev": Modify src/backend/** only → commit per item
+└── Agent "auth-dev": Modify src/auth/** only → commit per item
+
+Phase 2 (Integration Verification):
+└── Ralph Loop: Run full test suite, fix any integration issues
+```
+
+**Prompt pattern:**
+
+```
+## Parallel Work Streams
+Spawn these agents with strict file ownership:
+
+1. Agent "fe-dev" (isolation: worktree):
+   - ONLY touch files in src/frontend/**
+   - Tasks: [frontend items]
+   - Commit each fix individually
+
+2. Agent "be-dev" (isolation: worktree):
+   - ONLY touch files in src/backend/**
+   - Tasks: [backend items]
+   - Commit each fix individually
+
+After all agents complete, merge their branches and run integration tests.
+```
+
+### Pattern 3: Fan-Out / Fan-In Research
+
+Best for: Tasks that need comprehensive analysis before any action.
+
+```
+Fan-Out (Parallel):
+├── Agent 1: Analyze problem from angle A → findings-a.md
+├── Agent 2: Analyze problem from angle B → findings-b.md
+└── Agent 3: Analyze problem from angle C → findings-c.md
+
+Fan-In (Sequential):
+└── Ralph Loop: Synthesize all findings → create action plan → implement
+```
+
+### Pattern 4: Pipeline with Checkpoints
+
+Best for: Complex multi-stage transformations.
+
+```
+Stage 1 (Ralph Loop): Parse + validate input → intermediate.json
+  ↓ checkpoint: verify intermediate.json schema
+Stage 2 (Ralph Loop): Transform data → output draft
+  ↓ checkpoint: run regression tests
+Stage 3 (Parallel Agents): Apply fixes to multiple output files
+  ↓ checkpoint: final integration test
+```
+
+### Pattern 5: Scout-Then-Execute
+
+Best for: Unfamiliar codebases or risky changes.
+
+```
+Scout Phase (Single Agent, read-only):
+└── Agent "scout": Explore codebase, map dependencies, identify risks
+    → .ralph/reports/scout-report.md
+
+Execute Phase (Ralph Loop):
+└── Ralph Loop: Use scout report as reference, implement changes
+```
+
+## Subagent Configuration Reference
+
+### Claude Code (Agent tool)
+
+```
+Agent tool parameters:
+- description: "short task description"
+- prompt: "detailed instructions"
+- subagent_type: "general-purpose" | "Explore" | "Plan" | "coder-fe" | "coder-be" | etc.
+- isolation: "worktree"  (optional — gives agent an isolated repo copy)
+- run_in_background: true  (for parallel execution)
+- model: "sonnet" | "opus" | "haiku"  (optional model override)
+```
+
+**Best practices:**
+
+- Use `subagent_type: "Explore"` for read-only scanning — faster and safer
+- Use `isolation: "worktree"` when agents write to files — prevents merge conflicts
+- Launch parallel agents in a single message with multiple Agent tool calls
+- Use `run_in_background: true` for truly independent work streams
+
+### Codex CLI (experimental)
+
+Codex spawns subagents via natural language prompts with keywords: "spawn", "parallel", "delegate", "one agent per".
+
+```
+# Enable in ~/.codex/config.toml
+[agents]
+max_threads = 6          # Max concurrent agent threads (default: 6)
+max_depth = 1            # No grandchild agents (default: 1)
+```
+
+**Custom agent definitions** in `.codex/agents/` (TOML):
+
+```toml
+# .codex/agents/scanner.toml
+name = "scanner"
+description = "Read-only codebase explorer for pattern extraction"
+model = "gpt-5.4-mini"          # Faster model for exploration
+model_reasoning_effort = "low"
+sandbox_mode = "read-only"
+developer_instructions = """
+Scan files for the requested pattern. Report findings with file paths and line numbers.
+Do NOT modify any files.
+"""
+```
+
+**Spawning in prompts:**
+
+```
+"Spawn one agent per service directory to scan for auth issues:
+ 1. scanner on src/frontend/** → .ralph/reports/frontend.md
+ 2. scanner on src/backend/** → .ralph/reports/backend.md
+ 3. scanner on src/auth/** → .ralph/reports/auth.md
+ Wait for all, then summarize findings by severity."
+```
+
+**Batch processing** with `spawn_agents_on_csv`:
+
+```
+# For 100+ similar items, use CSV-driven batch spawning:
+spawn_agents_on_csv:
+  csv_path: .ralph/items.csv
+  instruction: "Review {file_path} for {issue_type}. Return JSON via report_agent_job_result"
+  output_schema: { file: string, severity: string, fix: string }
+  output_csv_path: .ralph/reports/batch-results.csv
+  max_concurrency: 6
+```
+
+### Model Selection Guide (Codex)
+
+| Role                    | Recommended Model   | Reasoning Effort |
+| ----------------------- | ------------------- | ---------------- |
+| Coordinator / main loop | gpt-5.4             | medium           |
+| Explorer / scanner      | gpt-5.4-mini        | low              |
+| Reviewer / security     | gpt-5.4             | high             |
+| Quick iteration / TDD   | gpt-5.3-codex-spark | medium           |
+
+### Key Constraints
+
+| Setting              | Default | Note                                                                    |
+| -------------------- | ------- | ----------------------------------------------------------------------- |
+| `agents.max_threads` | 6       | Hard cap on concurrent agents                                           |
+| `agents.max_depth`   | 1       | No recursive agent spawning                                             |
+| File conflicts       | N/A     | Multiple agents writing same file = conflicts. Use ownership isolation. |
+| Token usage          | Higher  | Each subagent does own inference. Use faster models for workers.        |
+
+## Report Directory Convention
+
+All subagent outputs should follow this structure:
+
+```
+.ralph/
+└── reports/
+    ├── {agent-name}.md       # Individual agent output
+    ├── merged.md             # Combined findings (created by orchestrator)
+    └── plan.md               # Action plan derived from findings
+```
+
+This directory should be in `.gitignore` — reports are ephemeral working artifacts.
+
+## Decision Matrix
+
+When analyzing a task, use this scoring to decide the orchestration pattern:
+
+| Factor                         | Score | Pattern             |
+| ------------------------------ | ----- | ------------------- |
+| Files span 3+ directories      | +2    | Parallel            |
+| Items are independent          | +2    | Parallel            |
+| Need full context to decide    | -2    | Sequential          |
+| Order matters                  | -2    | Sequential          |
+| 10+ similar items              | +1    | Parallel            |
+| Needs cross-file understanding | -1    | Sequential          |
+| Multiple services/repos        | +3    | Divide by Ownership |
+
+- **Score >= 3**: Recommend parallel subagents
+- **Score 0–2**: Recommend sequential with optional scout phase
+- **Score < 0**: Recommend single sequential Ralph Loop
+
+## Integration with Ralph Interview
+
+When `/ralph-interview` invokes this skill, provide:
+
+1. **Recommended pattern** — which orchestration pattern fits best
+2. **Agent breakdown** — list of subagents with their roles and file boundaries
+3. **Phase structure** — how phases connect and what checkpoints exist
+4. **Prompt snippets** — ready-to-embed subagent instructions for the ralph-loop prompt