@graypark/ralph-codex 0.4.0 → 0.4.3

package/.claude-plugin/plugin.json

@@ -1,25 +1,9 @@
 {
   "name": "ralph-codex",
-  "description": "Cross-platform Ralph Loop with interactive interview, multi-agent orchestration, and smart command generation. Run AI in self-referential iterative loops until task completion.",
+  "description": "Cross-platform Ralph Loop with interactive interview, multi-agent orchestration, and smart command generation for iterative AI development.",
+  "version": "0.4.1",
   "author": {
     "name": "graypark",
-    "email": "vcz.graypark@gmail.com",
-    "url": "https://github.com/vcz-Gray"
-  },
-  "version": "0.4.0",
-  "repository": "https://github.com/vcz-Gray/ralph-codex",
-  "license": "MIT",
-  "keywords": [
-    "ralph-loop",
-    "iterative-development",
-    "multi-agent",
-    "orchestration",
-    "stop-hook",
-    "cross-platform"
-  ],
-  "engines": {
-    "claude-code": ">=1.0.0",
-    "codex-cli": ">=0.114.0"
-  },
-  "compatibility": ["claude-code", "codex-cli"]
+    "email": "vcz.graypark@gmail.com"
+  }
 }

package/package.json

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

@@ -5,7 +5,7 @@ description: "Interactive interview that generates optimized /ralph-loop command
 
 # Ralph Interview — Command Generator
 
-You are an expert at crafting `/ralph-loop:ralph-loop` commands for Claude Code's Ralph Loop plugin.
+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.
 
 ## Core Principles
@@ -68,7 +68,7 @@ Evaluate the task against the ralph-orchestrator decision matrix:
 - **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 the Agent tool (Claude Code) or experimental multi-agent config (Codex CLI).
+When subagents are recommended, embed subagent spawn instructions directly in the generated ralph-loop prompt using Codex's experimental multi-agent capabilities.
 
 ### Recommended max-iterations
 
@@ -131,7 +131,7 @@ When the orchestrator score is >= 3, embed subagent instructions in the prompt:
 [Task summary]
 
 ## Phase 1 — Parallel Exploration
-Spawn these subagents simultaneously using the Agent tool:
+Spawn these subagents simultaneously:
 
 1. Agent 'scan-frontend' (subagent_type: Explore, run_in_background: true):
    Search src/frontend/** for [pattern]. Write findings to .ralph/reports/frontend.md

package/skills/ralph-orchestrator/SKILL.md

@@ -146,28 +146,71 @@ Execute Phase (Ralph Loop):
 
 ## Subagent Configuration Reference
 
-### Claude Code (Agent tool)
+### Codex CLI (experimental)
+
+Codex spawns subagents via natural language prompts with keywords: "spawn", "parallel", "delegate", "one agent per".
 
 ```
-Agent tool parameters:
-- description: "short task description"
-- prompt: "detailed instructions"
-- subagent_type: "general-purpose" | "Explore" | "Plan" | "coder-fe" | "coder-be" | etc.
-- isolation: "worktree"  (optional — gives agent an isolated repo copy)
-- run_in_background: true  (for parallel execution)
+# Enable in ~/.codex/config.toml
+[agents]
+max_threads = 6          # Max concurrent agent threads (default: 6)
+max_depth = 1            # No grandchild agents (default: 1)
 ```
 
-### Codex CLI (experimental)
+**Custom agent definitions** in `.codex/agents/` (TOML):
 
+```toml
+# .codex/agents/scanner.toml
+name = "scanner"
+description = "Read-only codebase explorer for pattern extraction"
+model = "gpt-5.4-mini"          # Faster model for exploration
+model_reasoning_effort = "low"
+sandbox_mode = "read-only"
+developer_instructions = """
+Scan files for the requested pattern. Report findings with file paths and line numbers.
+Do NOT modify any files.
+"""
 ```
-# Enable multi-agent via config
-[experimental]
-multi_agent = true
 
-# In prompt, instruct Codex to use its built-in agent spawning:
-"Spawn a subagent to explore src/api/** for unused endpoints.
- Write results to .ralph/reports/api-scan.md"
+**Spawning in prompts:**
+
 ```
+"Spawn one agent per service directory to scan for auth issues:
+ 1. scanner on src/frontend/** → .ralph/reports/frontend.md
+ 2. scanner on src/backend/** → .ralph/reports/backend.md
+ 3. scanner on src/auth/** → .ralph/reports/auth.md
+ Wait for all, then summarize findings by severity."
+```
+
+**Batch processing** with `spawn_agents_on_csv`:
+
+```
+# For 100+ similar items, use CSV-driven batch spawning:
+spawn_agents_on_csv:
+  csv_path: .ralph/items.csv
+  instruction: "Review {file_path} for {issue_type}. Return JSON via report_agent_job_result"
+  output_schema: { file: string, severity: string, fix: string }
+  output_csv_path: .ralph/reports/batch-results.csv
+  max_concurrency: 6
+```
+
+### Model Selection Guide (Codex)
+
+| Role                    | Recommended Model   | Reasoning Effort |
+| ----------------------- | ------------------- | ---------------- |
+| Coordinator / main loop | gpt-5.4             | medium           |
+| Explorer / scanner      | gpt-5.4-mini        | low              |
+| Reviewer / security     | gpt-5.4             | high             |
+| Quick iteration / TDD   | gpt-5.3-codex-spark | medium           |
+
+### Key Constraints
+
+| Setting              | Default | Note                                                                    |
+| -------------------- | ------- | ----------------------------------------------------------------------- |
+| `agents.max_threads` | 6       | Hard cap on concurrent agents                                           |
+| `agents.max_depth`   | 1       | No recursive agent spawning                                             |
+| File conflicts       | N/A     | Multiple agents writing same file = conflicts. Use ownership isolation. |
+| Token usage          | Higher  | Each subagent does own inference. Use faster models for workers.        |
 
 ## Report Directory Convention