@graypark/ralph-codex 0.4.1 → 0.5.0

package/README.md

@@ -69,6 +69,16 @@ node bin/install.mjs --global
 /ralph-interview Refactor the auth module across 3 services, run immediately
 ```
 
+**Multi-phase pipeline:** When multiple phases are generated, choose how to run:
+
+```
+Ready to run?
+- y    → Pipeline mode: all phases run automatically (1 → 2 → 3)
+- step → Manual mode: run one phase at a time, confirm between each
+- n    → Copy-paste commands yourself
+- edit → Modify the generated commands
+```
+
 ### `/ralph-orchestrator` — Multi-Agent Patterns
 
 Analyzes your task and recommends the best orchestration strategy:

package/lib/state.mjs

@@ -8,6 +8,7 @@ const DEFAULT_STATE = {
   maxIterations: 20,
   currentIteration: 0,
   sessionId: "",
+  queue: [],
 };
 
 export function getStatePath() {

package/lib/stop-hook-core.mjs

@@ -75,7 +75,40 @@ export async function processStopHook(hookInput, readStateFn, writeStateFn) {
     stderr.push(
       `Ralph loop: max iterations (${state.maxIterations}) reached.\n`,
     );
+
+    // On max iterations, also check queue for next phase
+    const queue = Array.isArray(state.queue) ? state.queue : [];
+    if (queue.length > 0) {
+      const next = queue.shift();
+      state.prompt = next.prompt;
+      state.completionPromise = next.completionPromise || "TADA";
+      state.maxIterations = next.maxIterations || 20;
+      state.currentIteration = 0;
+      state.queue = queue;
+      await writeStateFn(state);
+
+      stderr.push(
+        `Ralph loop: advancing to next phase (${queue.length} remaining).\n`,
+      );
+      const reason = [
+        state.prompt,
+        "",
+        "---",
+        `Ralph Loop — new phase started (iteration 1/${state.maxIterations}). Previous phase hit max iterations. Work on the task above.`,
+      ].join("\n");
+      const output = { decision: "block", reason };
+      if (state.completionPromise) {
+        output.systemMessage = `Ralph phase started (${queue.length} more queued) | To complete: output <promise>${state.completionPromise}</promise>`;
+      }
+      return {
+        exitCode: 0,
+        stdout: JSON.stringify(output),
+        stderr: stderr.join(""),
+      };
+    }
+
     state.active = false;
+    state.queue = [];
     await writeStateFn(state);
     return { exitCode: 0, stdout: "", stderr: stderr.join("") };
   }
@@ -91,7 +124,45 @@ export async function processStopHook(hookInput, readStateFn, writeStateFn) {
       stderr.push(
         `Ralph loop: completion promise "${state.completionPromise}" detected.\n`,
       );
+
+      // Check queue for next phase
+      const queue = Array.isArray(state.queue) ? state.queue : [];
+      if (queue.length > 0) {
+        const next = queue.shift();
+        state.prompt = next.prompt;
+        state.completionPromise = next.completionPromise || "TADA";
+        state.maxIterations = next.maxIterations || 20;
+        state.currentIteration = 0;
+        state.queue = queue;
+        await writeStateFn(state);
+
+        const phasesLeft = queue.length;
+        stderr.push(
+          `Ralph loop: advancing to next phase (${phasesLeft} remaining in queue).\n`,
+        );
+
+        const nextIterInfo =
+          state.maxIterations > 0 ? `1/${state.maxIterations}` : "1";
+        const reason = [
+          state.prompt,
+          "",
+          "---",
+          `Ralph Loop — new phase started (iteration ${nextIterInfo}). Work on the task above.`,
+        ].join("\n");
+
+        const output = { decision: "block", reason };
+        if (state.completionPromise) {
+          output.systemMessage = `Ralph phase started (${phasesLeft} more queued) | To complete: output <promise>${state.completionPromise}</promise> (ONLY when TRUE)`;
+        }
+        return {
+          exitCode: 0,
+          stdout: JSON.stringify(output),
+          stderr: stderr.join(""),
+        };
+      }
+
       state.active = false;
+      state.queue = [];
       await writeStateFn(state);
       return { exitCode: 0, stdout: "", stderr: stderr.join("") };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graypark/ralph-codex",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "type": "module",
   "description": "Ralph Loop for Codex CLI & Claude Code — iterative dev loops with multi-agent orchestration, interactive interview, and stop hooks",
   "license": "MIT",

package/skills/ralph-interview/SKILL.md

@@ -5,7 +5,7 @@ description: "Interactive interview that generates optimized /ralph-loop command
 
 # Ralph Interview — Command Generator
 
-You are an expert at crafting `/ralph-loop:ralph-loop` commands for Claude Code's Ralph Loop plugin.
+You are an expert at crafting `/ralph-loop:ralph-loop` commands for the Ralph Loop plugin.
 When the user describes a task, conduct a brief interview to gather missing context, then generate a copy-paste-ready command.
 
 ## Core Principles
@@ -68,7 +68,7 @@ Evaluate the task against the ralph-orchestrator decision matrix:
 - **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).
+When subagents are recommended, embed subagent spawn instructions directly in the generated ralph-loop prompt using Codex's experimental multi-agent capabilities.
 
 ### Recommended max-iterations
 
@@ -131,7 +131,7 @@ When the orchestrator score is >= 3, embed subagent instructions in the prompt:
 [Task summary]
 
 ## Phase 1 — Parallel Exploration
-Spawn these subagents simultaneously using the Agent tool:
+Spawn these subagents simultaneously:
 
 1. Agent 'scan-frontend' (subagent_type: Explore, run_in_background: true):
    Search src/frontend/** for [pattern]. Write findings to .ralph/reports/frontend.md
@@ -154,9 +154,52 @@ Read .ralph/reports/merged.md, then for each item:
 Output <promise>[PROMISE]</promise>" --max-iterations [N] --completion-promise "[PROMISE]"
 ```
 
-### Multi-Phase
+### Multi-Phase (Pipeline Mode — DEFAULT)
+
+When a task requires multiple phases, generate a **single** `/ralph-loop:ralph-loop` command with a `queue` in the state file. The stop hook automatically advances to the next phase when a completion promise is detected.
+
+**How to set up pipeline mode:**
+
+Create the state file at `.codex/ralph-loop.state.json` with a queue:
+
+```json
+{
+  "active": true,
+  "prompt": "Phase 1 prompt here...",
+  "completionPromise": "PHASE1_DONE",
+  "maxIterations": 10,
+  "currentIteration": 0,
+  "sessionId": "",
+  "queue": [
+    {
+      "prompt": "Phase 2 prompt here...",
+      "completionPromise": "PHASE2_DONE",
+      "maxIterations": 20
+    },
+    {
+      "prompt": "Phase 3 prompt here...",
+      "completionPromise": "TADA",
+      "maxIterations": 15
+    }
+  ]
+}
+```
+
+Then start with:
+
+```
+/ralph-loop:ralph-loop "Phase 1 prompt here..." --max-iterations 10 --completion-promise "PHASE1_DONE"
+```
 
-Generate each Phase as a separate `/ralph-loop:ralph-loop` command:
+When Phase 1 completes, the stop hook will automatically:
+
+1. Detect the completion promise
+2. Load Phase 2 from the queue
+3. Re-inject Phase 2's prompt as a new loop — no user intervention needed
+
+### Multi-Phase (Manual Mode)
+
+If the user chooses manual mode, generate each Phase as a separate `/ralph-loop:ralph-loop` command:
 
 - State Phase number and dependencies explicitly.
 - Link prior Phase outputs as references in the next Phase.
@@ -215,9 +258,9 @@ To cancel at any time: `/ralph-loop:cancel-ralph`
 [Assistant] → Asks interview questions (1 round, max 5 questions)
 [User]      → Answers
 [Assistant] → Generates Phase plan + command blocks
-[Assistant] → Asks: "Run Phase 1 now? (y/n)"
-[User]      → "y"
-[Assistant] → Executes the /ralph-loop:ralph-loop command immediately via Skill tool
+[Assistant] → Asks: "Ready to run?" with options
+[User]      → Chooses an option
+[Assistant] → Executes accordingly
 ```
 
 ### Quick-Run Flow
@@ -226,19 +269,45 @@ If the user includes phrases like "run immediately", "just do it", "바로 실
 
 1. Conduct the interview as normal (skip if enough context is provided).
 2. Generate the command blocks.
-3. **Immediately execute Phase 1** without asking for confirmation.
-4. Show the command that was executed so the user can see what's running.
+3. **Set up pipeline state file with queue** and **immediately execute Phase 1** without confirmation.
+4. Show the command and queue that was set up so the user can see what's running.
 
 ### Post-Generation Action
 
 After generating all command blocks, ALWAYS end with this prompt:
 
+**For multi-phase tasks:**
+
 ```
 ---
 **Ready to run?**
-- **y** / **yes** / **실행** → I'll start Phase 1 immediately
+- **y** / **yes** / **실행** → Pipeline mode: run all phases automatically (Phase 1 → 2 → 3, no stops between phases)
+- **step** / **단계별** → Manual mode: run Phase 1 only, I'll ask before each next phase
 - **n** / **no** / **아니오** → Commands are above, copy-paste when ready
 - **edit** / **수정** → Tell me what to change
 ```
 
-When the user confirms, execute the Phase 1 command by invoking the `ralph-loop:ralph-loop` skill with the generated arguments. For multi-phase work, after each Phase completes, prompt to run the next Phase.
+**For single-phase tasks:**
+
+```
+---
+**Ready to run?**
+- **y** / **yes** / **실행** → Start immediately
+- **n** / **no** / **아니오** → Command is above, copy-paste when ready
+- **edit** / **수정** → Tell me what to change
+```
+
+### Execution Modes
+
+**Pipeline mode (default for "y"):**
+
+1. Create the state file with the first phase as active and remaining phases in `queue`
+2. Execute Phase 1 via `/ralph-loop:ralph-loop`
+3. When Phase 1 promise is detected, the stop hook automatically loads Phase 2 from queue
+4. Continues until all phases complete — no user intervention between phases
+
+**Manual mode ("step"):**
+
+1. Execute Phase 1 via `/ralph-loop:ralph-loop`
+2. When Phase 1 completes, prompt the user to confirm before starting Phase 2
+3. Repeat for each phase

package/skills/ralph-orchestrator/SKILL.md

@@ -146,25 +146,6 @@ Execute Phase (Ralph Loop):
 
 ## 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".