@graypark/ralph-codex 0.4.3 → 0.5.1

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.3",
+  "version": "0.5.1",
   "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

@@ -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"
+```
+
+When Phase 1 completes, the stop hook will automatically:
 
-Generate each Phase as a separate `/ralph-loop:ralph-loop` command:
+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,30 +258,63 @@ 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
 
-If the user includes phrases like "run immediately", "just do it", "바로 실행", "바로 시작", or "--run" in their initial message:
+If the user includes phrases like "run immediately", "just do it", "run it", "바로 실행", "바로 시작", or "--run" in their initial message:
 
 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. For multi-phase: write state file with queue via Bash.
+4. Show the generated command briefly.
+5. Immediately call the Skill tool with skill="ralph-loop:ralph-loop" and the Phase 1 args. Do NOT wait for user confirmation.
 
 ### 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
+
+IMPORTANT: When the user confirms execution, you MUST actually start the loop by calling the Skill tool with skill "ralph-loop:ralph-loop" and the generated args. Do NOT just write a state file or print the command. The Skill tool invocation is what triggers the real loop.
+
+**Pipeline mode (default for "y"):**
+
+1. For multi-phase: write the state file with queue via Bash
+2. Call the Skill tool: skill="ralph-loop:ralph-loop", args="<Phase 1 prompt> --max-iterations N --completion-promise PROMISE"
+3. The stop hook handles phase transitions automatically
+
+**Manual mode ("step"):**
+
+1. Call the Skill tool: skill="ralph-loop:ralph-loop", args="<Phase 1 prompt> --max-iterations N --completion-promise PROMISE"
+2. When Phase 1 completes, ask user before calling Skill tool again for Phase 2
+
+**Single-phase ("y"):**
+
+1. Call the Skill tool: skill="ralph-loop:ralph-loop", args="<prompt> --max-iterations N --completion-promise PROMISE"
+
+After the user says "y", "yes", or similar, you MUST immediately use the Skill tool. Do not just describe what would happen. Do not tell the user to copy-paste. Actually invoke the skill.