@graypark/ralph-codex 0.5.2 → 0.7.0

package/README.md

@@ -69,16 +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:
+**Multi-phase tasks:** The interview generates `.ralph/prd.md` + `.ralph/progress.md` files. The loop reads these each iteration to track phases and items:
 
 ```
-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/
+├── prd.md        # All phases and work items
+└── progress.md   # What's done, what's next, what's blocked
 ```
 
+The loop naturally transitions between phases by reading progress. Stop anytime — restart the same command and it picks up where it left off.
+
 ### `/ralph-orchestrator` — Multi-Agent Patterns
 
 Analyzes your task and recommends the best orchestration strategy:

package/lib/state.mjs

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

package/lib/stop-hook-core.mjs

@@ -75,40 +75,7 @@ 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("") };
   }
@@ -124,45 +91,7 @@ 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.5.2",
+  "version": "0.7.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

@@ -1,26 +1,27 @@
 ---
 name: ralph-interview
-description: "Interactive interview that generates optimized /ralph-loop commands from task descriptions"
+description: "Interactive interview that generates optimized ralph-loop commands with PRD-based phase tracking. Compatible with ralph-skills prd.json format."
 ---
 
 # Ralph Interview — Command Generator
 
-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.
+You are an expert at crafting 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 PRD + progress file pair and a ralph-loop command.
 
 ## Core Principles
 
-- **Phase separation**: Analysis/research and implementation MUST be separate Phases.
-- **Self-correcting loops**: Every prompt must embed a "modify → verify → retry on failure" cycle.
+- **PRD-driven**: All phases and items live in a PRD file. The loop reads it each iteration.
+- **Progress tracking**: A progress file tracks what's done. Each iteration reads it to decide what's next.
+- **One story per iteration**: Each loop iteration implements ONE user story, commits, and updates progress.
+- **Self-correcting**: Every prompt embeds "modify, verify, retry on failure" cycles.
 - **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).
+- **Objective completion criteria only**: No subjective criteria. Use test passes, linter clears, etc.
+- **Parallel when possible**: Use ralph-orchestrator patterns for independent work streams.
 
 ## Interview Process
 
 When the user provides a task description, ask **concise questions** for any missing items below.
-Skip items already covered. Bundle questions — max 3–5 per round, one round only if possible.
+Skip items already covered. Bundle questions — max 3-5 per round, one round only if possible.
 
 ### Required Information
 
@@ -41,10 +42,10 @@ Skip items already covered. Bundle questions — max 3–5 per round, one round
 
 ### When to Split into Phases
 
-- **Research needed first** → Phase 1: Analysis, Phase 2: Implementation
-- **More than 8 items** → Split by nature (e.g., P1/P2, frontend/backend)
-- **Dependencies exist** → Prerequisite work in a prior Phase
-- **5 or fewer simple items** → Single Phase is fine
+- **Research needed first** -> Phase 1: Analysis, Phase 2: Implementation
+- **More than 8 items** -> Split by nature (e.g., P1/P2, frontend/backend)
+- **Dependencies exist** -> Prerequisite work in a prior Phase
+- **5 or fewer simple items** -> Single Phase is fine
 
 ### When to Use Subagents (via ralph-orchestrator)
 
@@ -60,282 +61,274 @@ Evaluate the task against the ralph-orchestrator decision matrix:
 | 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 Codex's experimental multi-agent capabilities.
+- **Score >= 3**: Recommend parallel subagents within the ralph-loop prompt
+- **Score 0-2**: Sequential loop, optional scout phase
+- **Score < 0**: Single sequential Ralph Loop
 
 ### Recommended max-iterations
 
 | Task type                                      | Iterations |
 | ---------------------------------------------- | ---------- |
-| Research only (file reads, pattern extraction) | 3–5        |
-| Simple fixes, 1–3 items                        | 5–10       |
-| Medium scope, 4–7 items                        | 10–20      |
-| Large scope, 8+ items                          | 20–30      |
-| TDD-based feature implementation               | 15–30      |
-| Full refactor / migration                      | 30–50      |
+| Research only (file reads, pattern extraction) | 3-5        |
+| Simple fixes, 1-3 items                        | 5-10       |
+| Medium scope, 4-7 items                        | 10-20      |
+| Large scope, 8+ items                          | 20-30      |
+| TDD-based feature implementation               | 15-30      |
+| Full refactor / migration                      | 30-50      |
 
-**Rule of thumb:** `item_count × 2 + 5` as baseline. Add weight for complex verification cycles.
+**Rule of thumb:** `story_count x 2 + 5` as baseline.
 
-## Prompt Template
+## PRD Format: prd.json (ralph-skills compatible)
 
-Every generated command MUST follow this structure:
+Generate PRDs in the **prd.json** format used by ralph-skills. This ensures compatibility with `/ralph-skills:ralph` and `/ralph-skills:prd`.
 
-### Single Phase
+### prd.json
 
+```json
+{
+  "project": "[Project Name]",
+  "branchName": "ralph/[feature-name]",
+  "description": "[Feature description]",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "[Story title]",
+      "description": "As a [user], I want [feature] so that [benefit]",
+      "acceptanceCriteria": [
+        "Specific verifiable criterion",
+        "Another criterion",
+        "Typecheck passes"
+      ],
+      "priority": 1,
+      "passes": false,
+      "notes": ""
+    }
+  ]
+}
 ```
-/ralph-loop:ralph-loop "## Goal
-[One-line summary of the task]
 
-## References
-[Files, patterns, or docs to consult. Omit section if none.]
-
-## Work Cycle (repeat for each item)
-1. [How to pick the next incomplete item]
-2. [Specific modification to make]
-3. [Run verification command]
-4. On failure → read the error, fix, go back to step 3. Max N retries.
-5. On pass → [state update action]
-6. git add -A && git commit -m '[convention-compliant message]'
-7. Return to step 1 for the next item.
-
-## Work Items
-- [Item 1]
-- [Item 2]
-- ...
+### Story Sizing Rules
 
-## When Stuck
-After [N] retries on any single item:
-- [Fallback: document issue / skip with TODO / suggest alternative]
+Each story MUST be completable in ONE iteration (one context window):
 
-## Completion Criteria
-- [Objective condition 1]
-- [Objective condition 2]
-- [Verification command] passes
+- **Right-sized**: Add a DB column, create one component, update one endpoint
+- **Too big (split)**: "Build entire dashboard", "Add authentication", "Refactor API"
+- **Rule of thumb**: If you can't describe the change in 2-3 sentences, split it
 
-Output <promise>[PROMISE]</promise>" --max-iterations [N] --completion-promise "[PROMISE]"
-```
+### Story Ordering
+
+Stories execute in priority order. Dependencies first:
+
+1. Schema/database changes
+2. Backend logic / server actions
+3. UI components that use the backend
+4. Aggregation views / dashboards
+
+### Acceptance Criteria Rules
+
+- MUST be verifiable, not vague
+- Always include: `"Typecheck passes"` (or equivalent verification)
+- For UI stories: add `"Verify in browser"` or equivalent
+- Bad: "Works correctly", "Good UX"
+- Good: "Button shows confirmation dialog before deleting", "Filter persists in URL params"
+
+### progress.txt
 
-### With Subagents
+An append-only log file that tracks iteration history:
 
-When the orchestrator score is >= 3, embed subagent instructions in the prompt:
+```
+## Codebase Patterns
+- [Reusable patterns discovered during iteration]
+
+---
 
+## [Date] - US-001
+- What was implemented
+- Files changed
+- **Learnings for future iterations:**
+  - Patterns discovered
+  - Gotchas encountered
+---
 ```
-/ralph-loop:ralph-loop "## Goal
-[Task summary]
 
-## Phase 1 — Parallel Exploration
-Spawn these subagents simultaneously:
+The `## Codebase Patterns` section at the top is read first by each iteration to avoid repeating mistakes.
 
-1. Agent 'scan-frontend' (subagent_type: Explore, run_in_background: true):
-   Search src/frontend/** for [pattern]. Write findings to .ralph/reports/frontend.md
+## The Loop Prompt
 
-2. Agent 'scan-backend' (subagent_type: Explore, run_in_background: true):
-   Search src/backend/** for [pattern]. Write findings to .ralph/reports/backend.md
+The ralph-loop prompt should follow this standard pattern:
 
-After ALL agents complete, merge reports into .ralph/reports/merged.md
+```
+/ralph-loop:ralph-loop "## Instructions
+1. Read prd.json for the full task plan
+2. Read progress.txt for current status (check Codebase Patterns first)
+3. Check you are on the correct branch from branchName. If not, create it from main.
+4. Pick the highest priority story where passes is false
+5. Implement that ONE story
+6. Run verification: [command]
+7. On failure: read error, fix, retry (max 3 times)
+8. On success: commit with message 'feat: [Story ID] - [Story Title]'
+9. Update prd.json to set passes: true for completed story
+10. Append progress to progress.txt with learnings
+11. If ALL stories have passes: true, output <promise>COMPLETE</promise>
 
-## Phase 2 — Sequential Implementation
-Read .ralph/reports/merged.md, then for each item:
-1. Apply the fix
-2. Run [verification command]
-3. git commit
+## When Stuck
+After 3 retries on any story:
+- Set notes field in prd.json with error details
+- Move to next story by priority
+- Document in progress.txt
 
-## Completion Criteria
-- All items from merged.md addressed
-- [Verification command] passes
+## References
+[list of reference files]
 
-Output <promise>[PROMISE]</promise>" --max-iterations [N] --completion-promise "[PROMISE]"
+## Verification
+[verification command]" --max-iterations [N] --completion-promise "COMPLETE"
 ```
 
-### Multi-Phase (Pipeline Mode — DEFAULT)
+### Why This Works
 
-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.
+- **Resumable**: Stop anytime. Progress is in prd.json and progress.txt. Restart and it picks up the next `passes: false` story.
+- **Inspectable**: Open prd.json to see status of every story. Open progress.txt for detailed history.
+- **Compatible**: Works with ralph-skills:ralph, ralph-skills:prd, and the official ralph-loop plugin.
+- **Fresh context each iteration**: Agent re-reads PRD and progress, no context rot.
+- **One story per iteration**: Keeps each iteration focused and within context limits.
 
-**How to set up pipeline mode:**
+## Compatibility with Existing Skills
 
-Create the state file at `.codex/ralph-loop.state.json` with a queue:
+### ralph-skills:prd (marketplace)
 
-```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
-    }
-  ]
-}
-```
+- Our prd.json output uses the EXACT same format
+- User can generate PRD with `/ralph-skills:prd`, then use our interview to generate the loop command
+- Or use our interview to generate both PRD and loop command
 
-Then start with:
+### ralph-skills:ralph (marketplace)
 
-```
-/ralph-loop:ralph-loop "Phase 1 prompt here..." --max-iterations 10 --completion-promise "PHASE1_DONE"
-```
+- Our loop prompt follows the same pattern as ralph-skills prompt.md
+- Same prd.json format, same progress.txt format
+- Same `passes: true/false` tracking, same commit convention
+- Same `<promise>COMPLETE</promise>` completion signal
 
-When Phase 1 completes, the stop hook will automatically:
+### Official ralph-loop plugin (claude-plugins-official)
 
-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
+- Our stop hook (Node.js) and the official stop hook (bash) can conflict if both installed
+- If the official ralph-loop plugin is installed, our interview should generate commands using `/ralph-loop:ralph-loop` (official namespace) instead of ours
+- The PRD and progress files work with either stop hook
 
-### Multi-Phase (Manual Mode)
+### Detection and Adaptation
 
-If the user chooses manual mode, generate each Phase as a separate `/ralph-loop:ralph-loop` command:
+When generating commands, check which ralph-loop is available:
 
-- State Phase number and dependencies explicitly.
-- Link prior Phase outputs as references in the next Phase.
-- Use distinct completion promises per Phase (e.g., `PHASE1_DONE`, `PHASE2_DONE`, `TADA`).
+1. If official `ralph-loop:ralph-loop` is in available skills -> use it
+2. If only our ralph-codex is installed -> use our commands
+3. PRD format is the same regardless of which loop engine is used
 
 ## Output Format
 
 Structure the final output as:
 
 1. **Task summary** — One paragraph describing the overall work.
-2. **Phase rationale** — One line per Phase explaining why it's separated.
-3. **Command blocks** — Copy-paste-ready code blocks.
-4. **Execution order** — Run order and notes between Phases.
-5. **Cancel reminder** — `/ralph-loop:cancel-ralph`
+2. **PRD preview** — Show the prd.json content.
+3. **Story count** — "N stories across M phases"
+4. **Loop command** — The ralph-loop command to run.
+5. **Execution prompt** — Ask how to proceed.
 
 ### Example Output
 
 ```
 ## Task Summary
-Fix 3 P1 + 7 P2 responsive issues based on the audit report.
+Add task priority system with database field, UI badges, and filtering.
 
-## Phase Rationale
-- Phase 1 (analysis): Extract responsive patterns from codebase to create a reference doc
-- Phase 2 (implementation): Apply fixes in P1 → P2 order using the reference
+## PRD (prd.json)
+{
+  "project": "TaskApp",
+  "branchName": "ralph/task-priority",
+  "description": "Task priority system",
+  "userStories": [
+    { "id": "US-001", "title": "Add priority field to tasks table", ... },
+    { "id": "US-002", "title": "Display priority badges", ... },
+    { "id": "US-003", "title": "Add priority selector", ... },
+    { "id": "US-004", "title": "Filter by priority", ... }
+  ]
+}
 
-### Phase 1 — Pattern Analysis
-` ` `
-/ralph-loop:ralph-loop "..." --max-iterations 5 --completion-promise "PHASE1_DONE"
-` ` `
+4 stories, ~10 iterations recommended.
 
-### Phase 2 — P1 + P2 Fixes
+## Command
 ` ` `
-/ralph-loop:ralph-loop "..." --max-iterations 20 --completion-promise "TADA"
+/ralph-loop:ralph-loop "..." --max-iterations 15 --completion-promise "COMPLETE"
 ` ` `
 
-## Execution Order
-1. Run Phase 1 → confirm completion
-2. Run Phase 2
-To cancel at any time: `/ralph-loop:cancel-ralph`
+---
+**Ready to run?**
+- **y** → Write prd.json + progress.txt and start the loop
+- **n** → Files and command are above, set up manually
+- **edit** → Tell me what to change
 ```
 
 ## Rules
 
-- **No subjective completion criteria**: Banned phrases — "works well", "looks clean", "properly done."
-- **No prompt without verification**: At least one automated check (tsc, test, lint, build) is mandatory.
-- **No missing namespace**: Always write `/ralph-loop:ralph-loop` and `/ralph-loop:cancel-ralph`.
-- **No missing escape hatch**: Every Phase MUST have a "When Stuck" section.
-- **No oversized single Phase**: Do not put more than 8 independent items in one Phase. Recommend splitting.
+- **No subjective completion criteria**: Banned phrases: "works well", "looks clean", "properly done."
+- **No prompt without verification**: At least one automated check is mandatory.
+- **No missing escape hatch**: Every prompt MUST have a "When Stuck" section.
+- **No oversized stories**: Each story must be completable in ONE iteration. Split if too big.
+- **Always use prd.json format**: Ensures compatibility with ralph-skills ecosystem.
+- **Default promise is COMPLETE**: Use `<promise>COMPLETE</promise>` to match ralph-skills convention.
 
 ## Conversation Flow
 
 ### Standard Flow
 
 ```
-[User]      → Describes the task
-[Assistant] → Asks interview questions (1 round, max 5 questions)
-[User]      → Answers
-[Assistant] → Generates Phase plan + command blocks
-[Assistant] → Asks: "Ready to run?" with options
-[User]      → Chooses an option
-[Assistant] → Executes accordingly
+[User]      -> Describes the task
+[Assistant] -> Asks interview questions (1 round, max 5 questions)
+[User]      -> Answers
+[Assistant] -> Generates prd.json + command + asks "Ready to run?"
+[User]      -> "y"
+[Assistant] -> Writes prd.json + progress.txt, then invokes ralph-loop skill
 ```
 
 ### Quick-Run Flow
 
-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. Show them briefly.
-3. For multi-phase: write state file with queue via Bash tool.
-4. Make the Skill tool call: skill="ralph-loop:ralph-loop", args=Phase 1 prompt+flags.
-   Do NOT stop after step 3. You MUST proceed to step 4.
+If the user includes "run immediately", "just do it", "run it", "바로 실행", "바로 시작", or "--run":
 
-### Post-Generation Action
+1. Conduct the interview (skip if enough context).
+2. Generate prd.json + command. Show briefly.
+3. Write prd.json and progress.txt via Bash tool.
+4. Invoke ralph-loop skill immediately. Do NOT stop after step 3.
 
-After generating all command blocks, ALWAYS end with this prompt:
+### Execution — MANDATORY SKILL INVOCATION
 
-**For multi-phase tasks:**
-
-```
----
-**Ready to run?**
-- **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 with "y", "yes", "run", etc., you MUST:
 
-**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 — MANDATORY TOOL CALL
-
-When the user confirms with "y", "yes", "step", "run", "바로 실행", etc., you MUST perform an actual Skill tool call. This is NON-NEGOTIABLE.
+1. Write prd.json and initialize progress.txt via Bash tool
+2. Actually invoke the ralph-loop skill to start the loop
 
 WRONG (do NOT do this):
 
-- Printing the /ralph-loop command as text
-- Writing a state file and saying "ready"
+- Printing the command as text and stopping
+- Writing files and saying "ready" or "set up"
 - Telling the user to copy-paste
-- Saying "Phase 1 is set up"
 
 RIGHT (you MUST do this):
 
-- Use the Skill tool to invoke "ralph-loop:ralph-loop" with args
+- Write the files via Bash
+- Then invoke the ralph-loop skill so the loop actually starts
 
-The exact tool call you must make:
+#### How to invoke ralph-loop
+
+**Claude Code**: Use the Skill tool:
 
 ```
-Use the Skill tool with:
+Skill tool call:
   skill: "ralph-loop:ralph-loop"
-  args: "<the full prompt>" --max-iterations <N> --completion-promise "<PROMISE>"
+  args: "<prompt>" --max-iterations <N> --completion-promise "COMPLETE"
 ```
 
-This is the same as if the user had typed `/ralph-loop:ralph-loop "..." --max-iterations N --completion-promise "X"` themselves. You are doing it on their behalf.
-
-**Pipeline mode ("y"):**
-
-1. For multi-phase: first write state file with queue via Bash tool
-2. Then IMMEDIATELY make the Skill tool call for Phase 1
-3. Stop hook handles the rest
-
-**Manual mode ("step"):**
+**Codex CLI**: Reference the skill via markdown link:
 
-1. IMMEDIATELY make the Skill tool call for Phase 1
-2. After it completes, ask before making the next Skill tool call
-
-**Single-phase ("y"):**
+```
+[$ralph-loop](~/.codex/skills/ralph-loop/SKILL.md) "<prompt>" --max-iterations <N> --completion-promise "COMPLETE"
+```
 
-1. IMMEDIATELY make the Skill tool call
+Note: On Windows use `%USERPROFILE%\.codex\skills\ralph-loop\SKILL.md`. If CODEX_HOME is set, use that.
 
-If you do not make the Skill tool call, the loop will not start. Writing a state file alone does nothing.
+If you do not actually invoke the skill, the loop will not start.