@graypark/ralph-codex 0.2.1 → 0.4.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "ralph-codex",
+  "description": "Cross-platform Ralph Loop with interactive interview, multi-agent orchestration, and smart command generation. Run AI in self-referential iterative loops until task completion.",
+  "author": {
+    "name": "graypark",
+    "email": "vcz.graypark@gmail.com",
+    "url": "https://github.com/vcz-Gray"
+  },
+  "version": "0.4.0",
+  "repository": "https://github.com/vcz-Gray/ralph-codex",
+  "license": "MIT",
+  "keywords": [
+    "ralph-loop",
+    "iterative-development",
+    "multi-agent",
+    "orchestration",
+    "stop-hook",
+    "cross-platform"
+  ],
+  "engines": {
+    "claude-code": ">=1.0.0",
+    "codex-cli": ">=0.114.0"
+  },
+  "compatibility": ["claude-code", "codex-cli"]
+}

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,158 +29,234 @@ 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            |
-
-## Usage
+| 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                  |
 
-### Start a Ralph Loop
-
-In Codex CLI, use the slash command:
+### What Gets Installed
 
 ```
-/ralph-loop "Build a REST API for todos with CRUD, validation, and tests" --max-iterations 30 --completion-promise "ALL_TESTS_PASS"
+~/.codex/ (or ~/.claude/)
+├── plugins/ralph-codex/          # Core plugin files
+├── hooks.json                    # Stop hook (merged with existing)
+└── skills/
+    ├── 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
 ```
 
-**Parameters:**
+## Commands
 
-| 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     |
+### `/ralph-interview` — Smart Command Generator
 
-### Cancel a Loop
+**The recommended way to start.** Interviews you about your task, evaluates whether subagents would help, then generates an optimized command.
 
 ```
-/cancel-ralph
+/ralph-interview
 ```
 
-### Generate a Command with Interview (NEW)
+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
 
-Don't know how to write a good ralph-loop prompt? Let the interview skill help:
+**Auto-execute:** Add "run immediately" or "바로 실행" to start without confirmation:
 
 ```
-/ralph-interview
+/ralph-interview Refactor the auth module across 3 services, run immediately
 ```
 
-It asks 3–5 targeted questions about your task, then generates an optimized `/ralph-loop` command with proper phases, escape hatches, verification steps, and completion criteria.
+### `/ralph-orchestrator` — Multi-Agent Patterns
 
-### How It Works
+Analyzes your task and recommends the best orchestration strategy:
 
-1. You invoke `/ralph-loop` with a task prompt
-2. Codex works on the task normally
-3. When Codex tries to exit, the **Stop hook** intercepts
-4. The hook checks: max iterations reached? Completion promise found?
-5. If not done, the hook **blocks the exit** and feeds the same prompt back
-6. Codex sees its previous work in files and git history
-7. Codex continues iterating until completion
+| 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               |
 
-### Completion Promise
+**Decision matrix** — the orchestrator scores your task automatically:
 
-To signal task completion, Codex must output the promise phrase wrapped in XML tags:
+```
+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
 
 ```
-<promise>ALL_TESTS_PASS</promise>
+/ralph-loop "Build a REST API" --max-iterations 30 --completion-promise "ALL_TESTS_PASS"
 ```
 
-The promise is only valid when the statement is genuinely true. The loop is designed to prevent false exits.
+| 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
 
-## Prompt Writing Tips
+```
+/cancel-ralph
+```
 
-### 1. Split into Phases
+## How the Loop Works
 
 ```
-/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
+┌─────────────────────────────────────────────┐
+│  /ralph-loop "Build feature X"              │
+│                                             │
+│  ┌──────────┐    ┌──────────┐              │
+│  │  Agent   │───▶│  Works   │              │
+│  │  starts  │    │  on task │              │
+│  └──────────┘    └────┬─────┘              │
+│                       │                     │
+│                       ▼                     │
+│              ┌──────────────┐              │
+│              │ Tries to exit │              │
+│              └───────┬──────┘              │
+│                      │                      │
+│                      ▼                      │
+│            ┌───────────────────┐            │
+│            │    Stop Hook      │            │
+│            │ ┌───────────────┐ │            │
+│            │ │ Max reached?  │─┼──Yes──▶ EXIT
+│            │ │ Promise found?│─┼──Yes──▶ EXIT
+│            │ └───────┬───────┘ │            │
+│            │         No        │            │
+│            │    Block exit +   │            │
+│            │  re-inject prompt │            │
+│            └─────────┬─────────┘            │
+│                      │                      │
+│              ┌──────────────┐              │
+│              │ Sees previous │──── loop ────┘
+│              │ work in files │
+│              └──────────────┘
 ```
 
-### 2. Objective Completion Criteria
+## Multi-Agent Orchestration Example
+
+For a task like "audit and fix auth across frontend, backend, and auth-service":
 
 ```
-/ralph-loop "Implement the auth module. Done when: all tests pass, no TypeScript errors, coverage > 80%." --completion-promise "AUTH_COMPLETE" --max-iterations 25
+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
+
+Phase 2 — Merge & Plan:
+└── Ralph Loop: Read all reports → create prioritized fix plan
+
+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
+
+Phase 4 — Integration:
+└── Ralph Loop: Merge branches → run full test suite → fix conflicts
 ```
 
-### 3. Always Set an Escape Hatch
+The `/ralph-interview` skill generates this automatically when it detects multi-service scope.
 
-Always use `--max-iterations` to prevent infinite loops on impossible tasks.
+## Updating
 
-### 4. Self-Correction Pattern
+To update to the latest version:
 
+```bash
+npx @graypark/ralph-codex --global --force
 ```
-/ralph-loop "Fix the failing CI pipeline. Run tests, read errors, fix code, repeat." --max-iterations 15 --completion-promise "CI_GREEN"
+
+Or if installed via git:
+
+```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
 
-- Plugin files from `~/.codex/plugins/ralph-codex/`
-- Stop hook entry from `~/.codex/hooks.json`
-- Skill files for `/ralph-loop` and `/cancel-ralph`
-- Any active state file
+This package includes a `.claude-plugin/plugin.json` manifest for Claude Code marketplace compatibility. To use as a Claude Code plugin:
+
+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             # Interactive command generator
+│   └── ralph-orchestrator/
+│       └── SKILL.md             # Multi-agent orchestration patterns
 ├── lib/
-│   ├── paths.mjs         # Cross-platform path utilities
-│   └── state.mjs         # Loop state management
+│   ├── 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          |
+| 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
-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.2.1",
+  "version": "0.4.0",
   "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,211 @@
+---
+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)
+```
+
+### Codex CLI (experimental)
+
+```
+# Enable multi-agent via config
+[experimental]
+multi_agent = true
+
+# In prompt, instruct Codex to use its built-in agent spawning:
+"Spawn a subagent to explore src/api/** for unused endpoints.
+ Write results to .ralph/reports/api-scan.md"
+```
+
+## 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