@graypark/ralph-codex 0.7.2 → 0.8.0

package/README.md

@@ -1,15 +1,80 @@
-# ralph-codex
+<p align="center">
+  <img src="https://raw.githubusercontent.com/vcz-Gray/ralph-codex/main/assets/ralph-codex-banner.svg" alt="ralph-codex" width="600" />
+</p>
 
-Self-referential iterative development loops for **Codex CLI** and **Claude Code** — with multi-agent orchestration, interactive command generation, and cross-platform stop hooks.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@graypark/ralph-codex"><img src="https://img.shields.io/npm/v/@graypark/ralph-codex.svg?style=flat-square&color=blue" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@graypark/ralph-codex"><img src="https://img.shields.io/npm/dm/@graypark/ralph-codex.svg?style=flat-square&color=green" alt="npm downloads" /></a>
+  <a href="https://github.com/vcz-Gray/ralph-codex/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="license" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg?style=flat-square" alt="node version" />
+  <img src="https://img.shields.io/badge/platform-Codex%20CLI%20%7C%20Claude%20Code-purple.svg?style=flat-square" alt="platform" />
+</p>
+
+<p align="center">
+  <b>Iterative AI development loops with PRD-driven task tracking, multi-agent orchestration, and interactive command generation.</b>
+</p>
+
+---
 
 ## 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.
+An AI agent works on a task in a continuous loop. Each iteration starts with **fresh context** — reading the PRD and progress files to decide what to do next. The agent implements one story, commits, updates progress, and exits. The stop hook intercepts the exit and re-injects the prompt. Repeat until all stories pass.
+
+```
+                    ┌──────────────────────┐
+                    │   /ralph-interview   │
+                    │   Describe your task  │
+                    └──────────┬───────────┘
+                               │
+                    ┌──────────▼───────────┐
+                    │  Generate prd.json   │
+                    │  + progress.txt      │
+                    └──────────┬───────────┘
+                               │
+              ┌────────────────▼────────────────┐
+              │         Ralph Loop              │
+              │                                 │
+              │  1. Read prd.json + progress    │
+              │  2. Pick next story (passes=false)│
+              │  3. Implement + verify          │
+              │  4. Commit + update progress    │
+              │  5. Exit attempt                │
+              │         │                       │
+              │    Stop Hook intercepts         │
+              │    Re-injects prompt             │
+              │         │                       │
+              │    Back to step 1 ──────────────┘
+              │                                 │
+              │  All stories pass?              │
+              │  → <promise>COMPLETE</promise>  │
+              └─────────────────────────────────┘
+```
+
+## Quick Start
+
+```bash
+npx @graypark/ralph-codex --global
+```
+
+Then in your AI coding session:
+
+```
+/ralph-interview Add user authentication with JWT, bcrypt, and login UI
+```
+
+That's it. The interview generates a PRD, activates the loop, and starts implementing story by story.
 
-## Requirements
+## Features
 
-- **Node.js** 18+
-- **Codex CLI** v0.114+ or **Claude Code** (any version with plugin support)
+| Feature                       | Description                                                                |
+| ----------------------------- | -------------------------------------------------------------------------- |
+| **PRD-driven loops**          | `prd.json` + `progress.txt` — resumable, inspectable, git-friendly         |
+| **Interactive interview**     | `/ralph-interview` asks targeted questions, generates optimized commands   |
+| **Multi-agent orchestration** | `/ralph-orchestrator` — 5 patterns for parallel work streams               |
+| **One story per iteration**   | Focused context, clean commits, no context rot                             |
+| **Cross-platform**            | Node.js stop hook — Windows, macOS, Linux without WSL                      |
+| **Ecosystem compatible**      | Works with `ralph-skills:prd`, `ralph-skills:ralph`, official `ralph-loop` |
+| **Stop & resume**             | Stop anytime. Restart the same command — picks up where it left off        |
 
 ## Installation
 
@@ -19,7 +84,7 @@ An AI agent works on a task in a continuous loop, seeing its own previous work e
 npx @graypark/ralph-codex --global
 ```
 
-### Git clone
+### Clone & install
 
 ```bash
 git clone https://github.com/vcz-Gray/ralph-codex.git
@@ -27,19 +92,18 @@ cd ralph-codex
 node bin/install.mjs --global
 ```
 
-### Options
+| Flag        | Description                             |
+| ----------- | --------------------------------------- |
+| `--global`  | Install to `~/.codex/` (default)        |
+| `--local`   | Install to `.codex/` in current project |
+| `--dry-run` | Preview without changes                 |
+| `--force`   | Overwrite existing                      |
 
-| 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
+<details>
+<summary>What gets installed</summary>
 
 ```
-~/.codex/ (or ~/.claude/)
+~/.codex/
 ├── plugins/ralph-codex/          # Core plugin files
 ├── hooks.json                    # Stop hook (merged with existing)
 └── skills/
@@ -49,218 +113,148 @@ node bin/install.mjs --global
     └── ralph-orchestrator/       # /ralph-orchestrator — multi-agent patterns
 ```
 
+</details>
+
 ## Commands
 
-### `/ralph-interview` — Smart Command Generator
+### `/ralph-interview` — The Main Entry Point
 
-**The recommended way to start.** Interviews you about your task, evaluates whether subagents would help, then generates an optimized command.
+Interviews you about your task, generates a PRD with right-sized stories, activates the loop, and starts working immediately.
 
 ```
-/ralph-interview
+/ralph-interview Refactor auth module across frontend and backend
 ```
 
-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:** Add "run immediately" or "바로 실행" to start without confirmation:
+**What happens:**
 
-```
-/ralph-interview Refactor the auth module across 3 services, run immediately
-```
+1. 3-5 targeted questions (scope, verification, parallelism, etc.)
+2. Generates `prd.json` with properly sized and ordered stories
+3. Writes `progress.txt` for iteration tracking
+4. Activates stop hook and starts implementing US-001
 
-**Multi-phase tasks:** The interview generates `.ralph/prd.md` + `.ralph/progress.md` files. The loop reads these each iteration to track phases and items:
+**Quick-run** — skip the "Ready?" prompt:
 
 ```
-.ralph/
-├── prd.md        # All phases and work items
-└── progress.md   # What's done, what's next, what's blocked
+/ralph-interview Add pagination to users API, run immediately
 ```
 
-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:
+Recommends the best execution strategy based on your task structure:
 
-| 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               |
+| Pattern                                 | When to use                              |
+| --------------------------------------- | ---------------------------------------- |
+| Parallel Explore → Sequential Implement | Research across large codebase, then fix |
+| Divide by Ownership                     | Multi-service changes (fe + be + auth)   |
+| Fan-Out / Fan-In                        | Parallel audits (security + perf + a11y) |
+| Scout-Then-Execute                      | Unfamiliar codebase                      |
+| Pipeline with Checkpoints               | Multi-stage transformations              |
 
-**Decision matrix** — the orchestrator scores your task automatically:
-
-```
-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` — Direct Loop
 
-### `/ralph-loop` — Run a Loop Directly
+If you already have a PRD or want to write your own prompt:
 
 ```
-/ralph-loop "Build a REST API" --max-iterations 30 --completion-promise "ALL_TESTS_PASS"
+/ralph-loop "Read prd.json, pick next story, implement, verify, commit" --max-iterations 20 --completion-promise "COMPLETE"
 ```
 
-| 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
+### `/cancel-ralph` — Stop
 
 ```
 /cancel-ralph
 ```
 
-## How the Loop Works
-
-```
-┌─────────────────────────────────────────────┐
-│  /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 │
-│              └──────────────┘
+## PRD Format
+
+ralph-codex uses the **ralph-skills compatible** `prd.json` format:
+
+```json
+{
+  "project": "MyApp",
+  "branchName": "ralph/auth-system",
+  "description": "JWT authentication with login UI",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "Add users table with password hash",
+      "description": "As a developer, I need user storage for auth",
+      "acceptanceCriteria": [
+        "Users table with email, password_hash columns",
+        "Migration runs successfully",
+        "Typecheck passes"
+      ],
+      "priority": 1,
+      "passes": false,
+      "notes": ""
+    }
+  ]
+}
 ```
 
-## Multi-Agent Orchestration Example
+Each story is sized to complete in **one iteration** (one context window). Dependencies are ordered by priority.
 
-For a task like "audit and fix auth across frontend, backend, and auth-service":
+## Ecosystem Compatibility
 
-```
-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
+ralph-codex works seamlessly with existing Ralph tools:
+
+| Tool                         | Compatibility                                                        |
+| ---------------------------- | -------------------------------------------------------------------- |
+| `ralph-skills:prd`           | Same `prd.json` format — generate PRD there, loop here               |
+| `ralph-skills:ralph`         | Same `progress.txt`, same `passes` tracking, same `COMPLETE` promise |
+| Official `ralph-loop` plugin | PRD files work with either stop hook                                 |
+| `snarktank/ralph`            | Compatible PRD structure and iteration pattern                       |
+
+## Multi-Agent Orchestration
 
-Phase 2 — Merge & Plan:
-└── Ralph Loop: Read all reports → create prioritized fix plan
+For tasks spanning multiple services or requiring broad exploration:
 
-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 1 — Parallel Scan (3 agents):
+├── Agent "fe-scan": Search frontend/** for auth gaps
+├── Agent "be-scan": Search backend/** for auth gaps
+└── Agent "db-scan": Review schema for missing constraints
 
-Phase 4 — Integration:
-└── Ralph Loop: Merge branches → run full test suite → fix conflicts
+Phase 2 — Sequential Fix (ralph-loop):
+└── Read merged findings → implement fixes story by story
 ```
 
-The `/ralph-interview` skill generates this automatically when it detects multi-service scope.
+The interview automatically evaluates parallelism potential using a scoring matrix.
 
 ## Updating
 
-To update to the latest version:
-
 ```bash
 npx @graypark/ralph-codex --global --force
 ```
 
-Or if installed via git:
-
-```bash
-cd ralph-codex
-git pull
-node bin/install.mjs --global --force
-```
-
-## Windows Support
-
-Works natively on Windows without WSL or Git Bash:
-
-- All paths use `path.join()` (no hardcoded slashes)
-- Installer copies files instead of symlinks on Windows
-- State files use JSON (no Unix-specific formats)
-- Hooks use `node` as the interpreter (cross-platform)
-
-## Uninstall
+## Uninstalling
 
 ```bash
 npx @graypark/ralph-codex uninstall
 ```
 
-## Claude Code Plugin
-
-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
+├── .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 — core loop engine
+│   └── stop-hook.mjs                 # Core loop engine (Node.js)
 ├── commands/
-│   ├── ralph-loop.md            # /ralph-loop command
-│   └── cancel-ralph.md          # /cancel-ralph 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
+│   ├── ralph-interview/SKILL.md     # Interactive command generator
+│   └── ralph-orchestrator/SKILL.md  # Multi-agent 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)
-└── package.json
+│   ├── paths.mjs                     # Cross-platform paths
+│   ├── state.mjs                     # Loop state management
+│   └── stop-hook-core.mjs           # Testable hook logic
+└── tests/                            # 32 test cases (vitest)
 ```
 
-## Comparison
-
-| 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
@@ -272,3 +266,9 @@ npx vitest        # watch mode
 ## License
 
 MIT
+
+---
+
+<p align="center">
+  Built for <a href="https://github.com/openai/codex">Codex CLI</a> and <a href="https://docs.anthropic.com/en/docs/claude-code">Claude Code</a>
+</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graypark/ralph-codex",
-  "version": "0.7.2",
+  "version": "0.8.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

@@ -181,6 +181,7 @@ The `## Codebase Patterns` section at the top is read first by each iteration to
 - **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.
+- **Always overwrite**: Never ask before overwriting prd.json or progress.txt. Just write them.
 
 ## Conversation Flow
 
@@ -202,6 +203,8 @@ Skip the "Ready?" prompt. Go straight to activation after showing the PRD briefl
 
 When the user confirms (or quick-run), execute ALL of these steps in a SINGLE response. Do NOT stop between steps.
 
+IMPORTANT: Always overwrite existing prd.json and progress.txt without asking. Do NOT check if they exist. Do NOT ask the user for confirmation before overwriting. Do NOT archive old files. Just write them.
+
 ### Step 1: Write prd.json via Bash
 
 ```bash