@graypark/ralph-codex 0.6.0 → 0.7.1

package/package.json

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

@@ -1,22 +1,22 @@
 ---
 name: ralph-interview
-description: "Interactive interview that generates optimized /ralph-loop commands with PRD-based phase tracking"
+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 PRD + progress file pair and a single ralph-loop 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, activate the loop, and start working immediately.
 
 ## Core Principles
 
-- **PRD-driven**: All phases and items live in `.ralph/prd.md`. The loop prompt reads it each iteration.
-- **Progress tracking**: `.ralph/progress.md` tracks what's done. Each iteration reads it to decide what's next.
-- **Self-correcting loops**: Every prompt embeds "modify, verify, retry on failure" cycles.
+- **PRD-driven**: All phases and items live in prd.json. The loop reads it each iteration.
+- **Progress tracking**: progress.txt tracks what is done. Each iteration reads it to decide what is 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**: No subjective criteria. Use test passes, linter clears, etc.
-- **Parallel when possible**: Use the ralph-orchestrator patterns for independent work streams.
+- **Parallel when possible**: Use ralph-orchestrator patterns for independent work streams.
 
 ## Interview Process
 
@@ -76,202 +76,201 @@ Evaluate the task against the ralph-orchestrator decision matrix:
 | TDD-based feature implementation               | 15-30      |
 | Full refactor / migration                      | 30-50      |
 
-**Rule of thumb:** `item_count x 2 + 5` as baseline.
-
-## PRD + Progress Pattern
-
-This is the core mechanism for multi-phase work. Instead of embedding all phases in one prompt or chaining state files, generate two files that the loop reads each iteration.
-
-### .ralph/prd.md
-
-Contains all phases and work items:
-
-```markdown
-# PRD: [Task Title]
-
-## Phase 1: [Phase Name]
-
-- [ ] Item 1 description
-- [ ] Item 2 description
-- [ ] Item 3 description
-
-## Phase 2: [Phase Name]
-
-- [ ] Item 4 description
-- [ ] Item 5 description
-
-## Completion Criteria
-
-- [Objective condition 1]
-- [Objective condition 2]
-- [Verification command] passes
+**Rule of thumb:** `story_count x 2 + 5` as baseline.
+
+## PRD Format: prd.json (ralph-skills compatible)
+
+Generate PRDs in the **prd.json** format used by ralph-skills. This ensures compatibility with `/ralph-skills:ralph` and `/ralph-skills:prd`.
+
+### 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/progress.md
+### Story Sizing Rules
 
-Updated by the loop after each completed item:
+Each story MUST be completable in ONE iteration (one context window):
 
-```markdown
-# Progress
+- **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 cannot describe the change in 2-3 sentences, split it
 
-## Completed
+### Story Ordering
 
-- [x] Item 1 — commit abc1234
-- [x] Item 2 — commit def5678
+Stories execute in priority order. Dependencies first:
 
-## Current Phase
+1. Schema/database changes
+2. Backend logic / server actions
+3. UI components that use the backend
+4. Aggregation views / dashboards
 
-Phase 1: [Phase Name]
+### Acceptance Criteria Rules
 
-## Blocked
+- 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"
 
-(none)
+### progress.txt
 
-## Next
+An append-only log file that tracks iteration history:
 
-Item 3
 ```
+## Codebase Patterns
+- [Reusable patterns discovered during iteration]
 
-### The Loop Prompt
-
-The ralph-loop prompt is always the same structure:
+---
 
-```
-/ralph-loop:ralph-loop "## Instructions
-1. Read .ralph/prd.md for the full task plan
-2. Read .ralph/progress.md for current status
-3. Pick the next incomplete item (first unchecked item in current phase)
-4. If current phase is complete, advance to next phase and update progress
-5. Implement the item
-6. Run verification: [command]
-7. On failure: read error, fix, retry (max 3 times per item)
-8. On success: update .ralph/progress.md (mark item done, note commit hash)
-9. git add -A && git commit -m '[convention]: [item description]'
-10. If ALL items in ALL phases are done and verification passes, output <promise>TADA</promise>
-
-## When Stuck
-After 3 retries on any item:
-- Add it to Blocked section in .ralph/progress.md with error details
-- Move to next item
-- Document in .ralph/progress.md
-
-## References
-[list of reference files]
-
-## Verification
-[verification command]" --max-iterations [N] --completion-promise "TADA"
+## [Date] - US-001
+- What was implemented
+- Files changed
+- **Learnings for future iterations:**
+  - Patterns discovered
+  - Gotchas encountered
+---
 ```
 
-### Why This Works
+The `## Codebase Patterns` section at the top is read first by each iteration to avoid repeating mistakes.
 
-- **Resumable**: Stop anytime. Progress is on disk. Restart the same command and it picks up where it left off.
-- **Inspectable**: Open `.ralph/progress.md` to see exactly what's done and what's next.
-- **Phase transitions are natural**: The agent reads the PRD, sees Phase 1 is done, moves to Phase 2.
-- **No state file conflicts**: The ralph-loop state file only manages the loop itself, not the task.
-- **Fresh context each iteration**: Agent re-reads PRD and progress, no context rot.
+## Compatibility with Existing Skills
 
-## Output Format
+### ralph-skills:prd (marketplace)
 
-Structure the final output as:
+- 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
 
-1. **Task summary** — One paragraph describing the overall work.
-2. **PRD preview** — Show the .ralph/prd.md content.
-3. **Loop command** — The single ralph-loop command to run.
-4. **Execution prompt** — Ask how to proceed.
+### ralph-skills:ralph (marketplace)
 
-### Example Output
-
-```
-## Task Summary
-Fix 3 P1 + 7 P2 responsive issues based on the audit report.
+- 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
 
-## PRD (.ralph/prd.md)
-# PRD: Responsive Fixes
-## Phase 1: P1 Critical
-- [ ] Fix header overflow on mobile
-- [ ] Fix nav collapse breakpoint
-- [ ] Fix card grid stacking
+### Official ralph-loop plugin (claude-plugins-official)
 
-## Phase 2: P2 Important
-- [ ] Adjust sidebar width at 768px
-...
-
-## Command
-` ` `
-/ralph-loop:ralph-loop "..." --max-iterations 25 --completion-promise "TADA"
-` ` `
-
----
-**Ready to run?**
-- **y** → Write PRD + progress files and start the loop
-- **n** → Files and command are above, set up manually
-- **edit** → Tell me what to change
-```
+- If the official plugin is installed, this interview works with its stop hook
+- PRD and progress files work with either stop hook
 
 ## 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 prompt without verification**: At least one automated check is mandatory.
 - **No missing escape hatch**: Every prompt MUST have a "When Stuck" section.
-- **No oversized single Phase**: Do not put more than 8 independent items in one Phase. Split them.
-- **Always generate .ralph/prd.md and .ralph/progress.md**: These are mandatory for multi-phase tasks.
+- **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]      -> /ralph-interview "build X feature"
+[Assistant] -> Interview questions (1 round, skip if context is sufficient)
 [User]      -> Answers
-[Assistant] -> Generates PRD + command + asks "Ready to run?"
+[Assistant] -> Shows PRD briefly, asks "Ready?"
 [User]      -> "y"
-[Assistant] -> Writes .ralph/ files via Bash, then invokes ralph-loop skill
+[Assistant] -> Writes files + activates loop + starts US-001 IN THE SAME RESPONSE
 ```
 
-### Quick-Run Flow
+### Quick-Run
 
 If the user includes "run immediately", "just do it", "run it", "바로 실행", "바로 시작", or "--run":
+Skip the "Ready?" prompt. Go straight to activation after showing the PRD briefly.
 
-1. Conduct the interview (skip if enough context).
-2. Generate PRD + command. Show briefly.
-3. Write .ralph/prd.md and .ralph/progress.md via Bash tool.
-4. Invoke ralph-loop skill immediately. Do NOT stop after step 3.
-
-### Execution — MANDATORY SKILL INVOCATION
+## Activation Sequence
 
-When the user confirms with "y", "yes", "run", etc., you MUST:
+When the user confirms (or quick-run), execute ALL of these steps in a SINGLE response. Do NOT stop between steps.
 
-1. Create .ralph/ directory and write prd.md + progress.md via Bash tool
-2. Actually invoke the ralph-loop skill to start the loop
+### Step 1: Write prd.json via Bash
 
-WRONG (do NOT do this):
+```bash
+cat > prd.json << 'EOF'
+{ ... generated PRD ... }
+EOF
+```
 
-- Printing the command as text and stopping
-- Writing files and saying "ready" or "set up"
-- Telling the user to copy-paste
+### Step 2: Write progress.txt via Bash
 
-RIGHT (you MUST do this):
+```bash
+cat > progress.txt << 'EOF'
+## Codebase Patterns
+(none yet)
+EOF
+```
 
-- Write the .ralph/ files via Bash
-- Then invoke ralph-loop skill so the loop actually starts
+### Step 3: Activate the stop hook via Bash
 
-#### How to invoke ralph-loop
+Write the ralph-loop state file that makes the stop hook intercept session exits:
 
-**Claude Code**: Use the Skill tool:
+```bash
+mkdir -p .claude
+cat > .claude/ralph-loop.local.md << 'EOF'
+---
+active: true
+iteration: 1
+session_id:
+max_iterations: <N>
+completion_promise: "COMPLETE"
+started_at: "<now>"
+---
 
-```
-Skill tool call:
-  skill: "ralph-loop:ralph-loop"
-  args: "<prompt>" --max-iterations <N> --completion-promise "TADA"
+Read prd.json for task plan. Read progress.txt for status (Codebase Patterns first).
+Check correct branch from branchName. If not on it, create from main.
+Pick highest priority story where passes is false.
+Implement that ONE story.
+Run verification: <command>.
+On failure: fix and retry, max 3 times.
+On success: commit 'feat: [Story ID] - [Title]'.
+Update prd.json: set passes to true. Append to progress.txt with learnings.
+If ALL stories pass: <promise>COMPLETE</promise>.
+When stuck: set notes in prd.json, skip to next story.
+EOF
 ```
 
-**Codex CLI**: Reference the skill via markdown link:
+### Step 4: START WORKING ON US-001 IMMEDIATELY
 
-```
-[$ralph-loop](~/.codex/skills/ralph-loop/SKILL.md) "<prompt>" --max-iterations <N> --completion-promise "TADA"
-```
+This is the critical step. After writing files, you MUST begin actual work in the SAME response:
+
+1. Read the prd.json you just wrote
+2. Create/checkout the branch from branchName
+3. Pick the first story (US-001)
+4. Implement it — write real code, make real changes
+5. Run the verification command
+6. Commit the changes
+7. Update prd.json (set passes: true)
+8. Append to progress.txt
+
+Do NOT:
+
+- Say "loop is now active" and stop
+- Say "starting work on US-001" and stop
+- Print a summary and wait for user input
+- Ask if the user wants to proceed
 
-Note: On Windows use `%USERPROFILE%\.codex\skills\ralph-loop\SKILL.md`. If CODEX_HOME is set, use that.
+DO:
 
-If you do not actually invoke the skill, the loop will not start.
+- Actually write code
+- Actually run tests
+- Actually commit
+- The stop hook will handle continuation to US-002 when you finish