@graypark/ralph-codex 0.1.0 → 0.2.0

package/README.md

@@ -20,7 +20,7 @@ npx @graypark/ralph-codex --global
 ### Option 2: Clone and install
 
 ```bash
-git clone https://github.com/Viewcommz/ralph-codex.git
+git clone https://github.com/vcz-Gray/ralph-codex.git
 cd ralph-codex
 node bin/install.mjs --global
 ```
@@ -58,6 +58,16 @@ In Codex CLI, use the slash command:
 /cancel-ralph
 ```
 
+### Generate a Command with Interview (NEW)
+
+Don't know how to write a good ralph-loop prompt? Let the interview skill help:
+
+```
+/ralph-interview
+```
+
+It asks 3–5 targeted questions about your task, then generates an optimized `/ralph-loop` command with proper phases, escape hatches, verification steps, and completion criteria.
+
 ### How It Works
 
 1. You invoke `/ralph-loop` with a task prompt

package/bin/install.mjs

@@ -152,29 +152,40 @@ async function mergeHooksJson() {
 }
 
 async function installSkills() {
-  const skillNames = ["ralph-loop", "cancel-ralph"];
-  for (const name of skillNames) {
+  // Command-based skills (ralph-loop, cancel-ralph)
+  const commandSkills = ["ralph-loop", "cancel-ralph"];
+  for (const name of commandSkills) {
     const skillDir = join(skillsDir, name);
     const skillMd = join(skillDir, "SKILL.md");
-    const commandSrc = join(pluginDir, "commands", `${name}.md`);
 
     log(">", `Install skill: ${name} -> ${skillDir}`);
 
     if (!dryRun) {
       await mkdir(skillDir, { recursive: true });
 
-      // Read the command markdown and convert to SKILL.md format
       const content = await readFile(
         join(PROJECT_ROOT, "commands", `${name}.md`),
         "utf-8",
       );
 
-      // Replace ${RALPH_CODEX_ROOT} placeholder with actual install path
       const resolved = content.replaceAll("${RALPH_CODEX_ROOT}", pluginDir);
-
       await writeFile(skillMd, resolved, "utf-8");
     }
   }
+
+  // Standalone skills (ralph-interview, etc.)
+  const standaloneSkills = ["ralph-interview"];
+  for (const name of standaloneSkills) {
+    const srcDir = join(PROJECT_ROOT, "skills", name);
+    const destDir = join(skillsDir, name);
+
+    log(">", `Install skill: ${name} -> ${destDir}`);
+
+    if (!dryRun) {
+      await mkdir(destDir, { recursive: true });
+      await cp(srcDir, destDir, { recursive: true });
+    }
+  }
 }
 
 async function main() {

package/bin/uninstall.mjs

@@ -83,7 +83,7 @@ export async function uninstall({ dryRun = false, local = false } = {}) {
   }
 
   // 3. Remove skill directories
-  const skillNames = ["ralph-loop", "cancel-ralph"];
+  const skillNames = ["ralph-loop", "cancel-ralph", "ralph-interview"];
   for (const name of skillNames) {
     const skillDir = join(skillsDir, name);
     if (await fileExists(skillDir)) {

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@graypark/ralph-codex",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Ralph Loop for OpenAI Codex CLI — self-referential iterative development loops via Stop hooks",
   "license": "MIT",
   "author": "graypark",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Viewcommz/ralph-codex"
+    "url": "https://github.com/vcz-Gray/ralph-codex"
   },
-  "homepage": "https://github.com/Viewcommz/ralph-codex#readme",
+  "homepage": "https://github.com/vcz-Gray/ralph-codex#readme",
   "bugs": {
-    "url": "https://github.com/Viewcommz/ralph-codex/issues"
+    "url": "https://github.com/vcz-Gray/ralph-codex/issues"
   },
   "publishConfig": {
     "access": "public"
@@ -24,6 +24,7 @@
     "hooks/",
     "commands/",
     "lib/",
+    "skills/",
     "README.md",
     "LICENSE"
   ],

package/skills/ralph-interview/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: ralph-interview
+description: "Interactive interview that generates optimized /ralph-loop commands from task descriptions"
+---
+
+# Ralph Interview — Command Generator
+
+You are an expert at crafting `/ralph-loop:ralph-loop` commands for Claude Code's Ralph Loop plugin.
+When the user describes a task, conduct a brief interview to gather missing context, then generate a copy-paste-ready 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.
+- **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.
+
+## 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.
+
+### Required Information
+
+| Category                  | What to confirm                                                                      |
+| ------------------------- | ------------------------------------------------------------------------------------ |
+| **Scope**                 | Single feature? Multi-file? Full refactor?                                           |
+| **Success criteria**      | What counts as "done"? (tests pass, build succeeds, spec checklist, etc.)            |
+| **Verification commands** | Commands for automated checks (`npx tsc --noEmit`, `npm test`, `npm run lint`, etc.) |
+| **References**            | Existing code, files, or patterns to follow?                                         |
+| **Spec file**             | Is there a spec document? Path?                                                      |
+| **Priority**              | P1/P2 or other priority tiers?                                                       |
+| **Constraints**           | Must not break existing tests? Library restrictions?                                 |
+| **When stuck**            | User's preferred fallback (document it? skip? suggest alternative?)                  |
+| **Commit strategy**       | Per-item commits? Bulk? Commit message convention?                                   |
+
+## Phase Design
+
+### 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
+
+### 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      |
+
+**Rule of thumb:** `item_count × 2 + 5` as baseline. Add weight for complex verification cycles.
+
+## Prompt Template
+
+Every generated command MUST follow this structure:
+
+### Single Phase
+
+```
+/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]
+- ...
+
+## When Stuck
+After [N] retries on any single item:
+- [Fallback: document issue / skip with TODO / suggest alternative]
+
+## Completion Criteria
+- [Objective condition 1]
+- [Objective condition 2]
+- [Verification command] passes
+
+Output <promise>[PROMISE]</promise>" --max-iterations [N] --completion-promise "[PROMISE]"
+```
+
+### Multi-Phase
+
+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.
+- Use distinct completion promises per Phase (e.g., `PHASE1_DONE`, `PHASE2_DONE`, `TADA`).
+
+## 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`
+
+### Example Output
+
+```
+## Task Summary
+Fix 3 P1 + 7 P2 responsive issues based on the audit report.
+
+## 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
+
+### Phase 1 — Pattern Analysis
+` ` `
+/ralph-loop:ralph-loop "..." --max-iterations 5 --completion-promise "PHASE1_DONE"
+` ` `
+
+### Phase 2 — P1 + P2 Fixes
+` ` `
+/ralph-loop:ralph-loop "..." --max-iterations 20 --completion-promise "TADA"
+` ` `
+
+## Execution Order
+1. Run Phase 1 → confirm completion
+2. Run Phase 2
+To cancel at any time: `/ralph-loop:cancel-ralph`
+```
+
+## 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.
+
+## Conversation Flow
+
+```
+[User]      → Describes the task
+[Assistant] → Asks interview questions (1 round, max 5 questions)
+[User]      → Answers
+[Assistant] → Generates Phase plan + command blocks
+[User]      → (optional) Requests changes
+[Assistant] → Delivers revised command blocks
+```