npm - @graypark/ralph-codex - Versions diffs - 0.7.2 → 0.8.1 - Mend

@graypark/ralph-codex 0.7.2 → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md +191 -170
package/package.json +1 -1
package/skills/ralph-interview/SKILL.md +3 -0

package/README.md CHANGED Viewed

@@ -1,15 +1,101 @@
-# 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" />
+  <img src="https://img.shields.io/badge/tests-32%20passing-brightgreen.svg?style=flat-square" alt="tests" />
+</p>
+<p align="center">
+  <b>Iterative AI development loops with PRD-driven task tracking, multi-agent orchestration, and interactive command generation.</b>
+  <br/>
+  <sub>Based on <a href="https://ghuntley.com/ralph/">Geoffrey Huntley's Ralph Wiggum technique</a></sub>
+</p>
+---
+## Why ralph-codex?
+AI coding agents struggle with:
+| Problem                  | What happens                                               |
+| ------------------------ | ---------------------------------------------------------- |
+| **Context rot**          | Long conversations accumulate noise, agent gets confused   |
+| **No checkpoints**       | All-or-nothing execution — can't resume after interruption |
+| **Lost learnings**       | Previous iterations' insights overwritten by new context   |
+| **Completion ambiguity** | Agent says "done" but tests still fail                     |
+ralph-codex solves this:
+- **Fresh context per iteration** — Each cycle reads PRD + progress from disk, no degradation
+- **Git-enforced safety** — Atomic commits per story, rollback at any point
+- **Append-only learnings** — `progress.txt` accumulates knowledge across iterations
+- **Test-verified completion** — Agent can only exit when `<promise>COMPLETE</promise>` is genuinely true
 ## 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 +105,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 +113,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 +134,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:
+### `/ralph-loop` — Direct Loop
-```
-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
+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:
-Phase 2 — Merge & Plan:
-└── Ralph Loop: Read all reports → create prioritized fix plan
+| 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                       |
-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
+## Multi-Agent Orchestration
+For tasks spanning multiple services or requiring broad exploration:
-Phase 4 — Integration:
-└── Ralph Loop: Merge branches → run full test suite → fix conflicts
 ```
+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
-The `/ralph-interview` skill generates this automatically when it detects multi-service scope.
+Phase 2 — Sequential Fix (ralph-loop):
+└── Read merged findings → implement fixes story by story
+```
-## Updating
+The interview automatically evaluates parallelism potential using a scoring matrix.
-To update to the latest version:
+## Updating
 ```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 +287,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 CHANGED Viewed

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

@@ -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