oh-my-codex-cli 0.1.0

package/.agent/skills/ralph/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: ralph
+description: Self-referential loop until task completion with architect verification
+---
+
+# Ralph Skill
+
+> Codex invocation: use `$ralph ...` or `ralph: ...`
+
+
+[RALPH + ULTRAWORK - ITERATION {{ITERATION}}/{{MAX}}]
+
+Your previous attempt did not output the completion promise. Continue working on the task.
+
+## Native Subagent Protocol (Codex)
+
+Codex supports native subagents. Delegate with `spawn_agent`, coordinate with `send_input`, collect via `wait`, and clean up with `close_agent`.
+
+Required per-iteration output:
+```
+[ANALYST] Requirements + risks
+[ARCHITECT] Approach + file list
+[EXECUTOR] What changed + why
+[REVIEWER] Verify criteria + tests
+```
+
+## PRD MODE (OPTIONAL)
+
+If the user provides the `--prd` flag, initialize a PRD (Product Requirements Document) BEFORE starting the ralph loop.
+
+### Detecting PRD Mode
+
+Check if `{{PROMPT}}` contains the flag pattern: `--prd` or `--PRD`
+
+### PRD Initialization Workflow
+
+When `--prd` flag detected:
+
+1. **Create PRD File Structure** (`.omc/prd.json` and `.omc/progress.txt`)
+2. **Parse the task** (everything after `--prd` flag)
+3. **Break down into user stories** with this structure:
+
+```json
+{
+  "project": "[Project Name]",
+  "branchName": "ralph/[feature-name]",
+  "description": "[Feature description]",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "[Short title]",
+      "description": "As a [user], I want to [action] so that [benefit].",
+      "acceptanceCriteria": ["Criterion 1", "Typecheck passes"],
+      "priority": 1,
+      "passes": false
+    }
+  ]
+}
+```
+
+4. **Create progress.txt**:
+
+```
+# Ralph Progress Log
+Started: [ISO timestamp]
+
+## Codebase Patterns
+(No patterns discovered yet)
+
+---
+```
+
+5. **Guidelines for PRD creation**:
+   - Right-sized stories: Each completable in one focused session
+   - Verifiable criteria: Include "Typecheck passes", "Tests pass"
+   - Independent stories: Minimize dependencies
+   - Priority order: Foundational work (DB, types) before UI
+
+6. **After PRD created**: Proceed to normal ralph loop execution using the user stories as your task list
+
+### Example Usage
+
+User input: `--prd build a todo app with React and TypeScript`
+
+Your workflow:
+1. Detect `--prd` flag
+2. Extract task: "build a todo app with React and TypeScript"
+3. Create `.omc/prd.json` with user stories
+4. Create `.omc/progress.txt`
+5. Begin ralph loop using user stories as task breakdown
+
+## ULTRAWORK MODE (AUTO-ACTIVATED)
+
+Ralph automatically activates Ultrawork for maximum parallel execution. You MUST follow these rules:
+
+### Parallel Execution Rules
+- **PARALLEL**: Fire independent calls simultaneously - NEVER wait sequentially
+- **BACKGROUND FIRST**: Use background worker execution for long operations (10+ concurrent)
+- **DELEGATE**: Route tasks to specialist agents immediately
+
+### Smart Model Routing (SAVE TOKENS)
+
+| Task Complexity | Tier | Examples |
+|-----------------|------|----------|
+| Simple lookups | LOW (haiku) | "What does this function return?", "Find where X is defined" |
+| Standard work | MEDIUM (sonnet) | "Add error handling", "Implement this feature" |
+| Complex analysis | HIGH (opus) | "Debug this race condition", "Refactor auth module" |
+
+### Available Agents by Tier
+
+| Domain | LOW (Haiku) | MEDIUM (Sonnet) | HIGH (Opus) |
+|--------|-------------|-----------------|-------------|
+| **Analysis** | `architect-low` | `architect-medium` | `architect` |
+| **Execution** | `executor-low` | `executor` | `executor-high` |
+| **Search** | `explore` | `explore-medium` | - |
+| **Research** | `researcher-low` | `researcher` | - |
+| **Frontend** | `designer-low` | `designer` | `designer-high` |
+| **Docs** | `writer` | - | - |
+| **Visual** | - | `vision` | - |
+| **Planning** | - | - | `planner` |
+| **Critique** | - | - | `critic` |
+| **Pre-Planning** | - | - | `analyst` |
+| **Testing** | - | `qa-tester` | - |
+| **Security** | `security-reviewer-low` | - | `security-reviewer` |
+| **Build** | `build-fixer-low` | `build-fixer` | - |
+| **TDD** | `tdd-guide-low` | `tdd-guide` | - |
+| **Code Review** | `code-reviewer-low` | - | `code-reviewer` |
+
+**CRITICAL: Always pass `model` parameter explicitly!**
+```
+[ARCHITECT-LOW | haiku] "..."
+[EXECUTOR | sonnet] "..."
+[ARCHITECT | opus] "..."
+```
+
+### Background Execution Rules
+
+**Run in Background** (set `run_in_background: true`):
+- Package installation: npm install, pip install, cargo build
+- Build processes: npm run build, make, tsc
+- Test suites: npm test, pytest, cargo test
+- Docker operations: docker build, docker pull
+
+**Run Blocking** (foreground):
+- Quick status checks: git status, ls, pwd
+- File reads, edits
+- Simple commands
+
+## COMPLETION REQUIREMENTS
+
+Before claiming completion, you MUST:
+1. Verify ALL requirements from the original task are met
+2. Ensure no partial implementations
+3. Check that code compiles/runs without errors
+4. Verify tests pass (if applicable)
+5. TODO LIST: Zero pending/in_progress tasks
+
+## VERIFICATION BEFORE COMPLETION (IRON LAW)
+
+**NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE**
+
+Before outputting the completion promise:
+
+### Steps (MANDATORY)
+1. **IDENTIFY**: What command proves the task is complete?
+2. **RUN**: Execute verification (test, build, lint)
+3. **READ**: Check output - did it actually pass?
+4. **ONLY THEN**: Proceed to Architect verification
+
+### Red Flags (STOP and verify)
+- Using "should", "probably", "seems to"
+- About to output completion without fresh evidence
+- Expressing satisfaction before verification
+
+### Evidence Chain
+1. Fresh test run output showing pass
+2. Fresh build output showing success
+3. lsp_diagnostics showing 0 errors
+4. THEN Architect verification
+5. THEN completion promise
+
+**Skipping verification = Task NOT complete**
+
+## ARCHITECT VERIFICATION (MANDATORY)
+
+When you believe the task is complete:
+1. **First**, spawn Architect to verify your work (ALWAYS pass model explicitly!):
+   ```
+   [ARCHITECT | opus] "Verify this implementation is complete: [describe what you did]"
+   ```
+
+2. **Wait for Architect's assessment**
+
+3. **If Architect approves**: Output `<promise>{{PROMISE}}</promise>`
+4. **If Architect finds issues**: Fix them, then repeat verification
+
+DO NOT output the completion promise without Architect verification.
+
+## ZERO TOLERANCE
+
+- NO Scope Reduction - deliver FULL implementation
+- NO Partial Completion - finish 100%
+- NO Premature Stopping - ALL TODOs must be complete
+- NO TEST DELETION - fix code, not tests
+
+## STATE CLEANUP ON COMPLETION
+
+**IMPORTANT: Delete state files on successful completion - do NOT just set `active: false`**
+
+When outputting the completion promise after Architect verification:
+
+```bash
+# Delete ralph state file (and linked ultrawork if applicable)
+rm -f .omc/state/ralph-state.json
+rm -f .omc/state/ralph-verification.json
+rm -f ~/.codex/ralph-state.json
+
+# If ultrawork was linked, delete it too
+rm -f .omc/state/ultrawork-state.json
+rm -f ~/.codex/ultrawork-state.json
+```
+
+This ensures clean state for future sessions. Stale state files with `active: false` should not be left behind.
+
+## INSTRUCTIONS
+
+- Review your progress so far
+- Continue from where you left off
+- Use parallel execution and background tasks
+- When FULLY complete AND Architect verified:
+  1. Clean up state files (delete ralph-state.json, ultrawork-state.json)
+  2. Output: <promise>{{PROMISE}}</promise>
+- Do not stop until the task is truly done
+
+Original task:
+{{PROMPT}}

package/.agent/skills/ralph-init/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: ralph-init
+description: Initialize a PRD (Product Requirements Document) for structured ralph-loop execution
+---
+
+# Ralph Init Skill
+
+
+## Native Subagent Protocol (Codex)
+
+Codex supports native subagents. Delegate with `spawn_agent`, coordinate with `send_input`, collect via `wait`, and clean up with `close_agent`.
+
+Execution preference:
+1. Use native subagents first for independent workstreams (parallel when possible).
+2. Merge results in main thread and run final verification.
+3. Fallback only when delegation is blocked: use the `[ANALYST]`/`[ARCHITECT]`/`[EXECUTOR]`/`[REVIEWER]` structure in a single response.
+
+Minimal orchestration pattern:
+```text
+spawn_agent -> send_input (optional) -> wait -> close_agent
+```
+
+> Codex invocation: use `$ralph-init ...` or `ralph-init: ...`
+
+
+[RALPH-INIT - PRD CREATION MODE]
+
+## What is PRD?
+
+A PRD (Product Requirements Document) structures your task into discrete user stories for ralph-loop.
+
+## Your Task
+
+Create `.omc/prd.json` and `.omc/progress.txt` based on the task description.
+
+### prd.json Structure
+
+```json
+{
+  "project": "[Project Name]",
+  "branchName": "ralph/[feature-name]",
+  "description": "[Feature description]",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "[Short title]",
+      "description": "As a [user], I want to [action] so that [benefit].",
+      "acceptanceCriteria": ["Criterion 1", "Typecheck passes"],
+      "priority": 1,
+      "passes": false
+    }
+  ]
+}
+```
+
+### progress.txt Structure
+
+```
+# Ralph Progress Log
+Started: [ISO timestamp]
+
+## Codebase Patterns
+(No patterns discovered yet)
+
+---
+```
+
+### Guidelines
+
+1. **Right-sized stories**: Each completable in one focused session
+2. **Verifiable criteria**: Include "Typecheck passes", "Tests pass"
+3. **Independent stories**: Minimize dependencies between stories
+4. **Priority order**: Foundational work (DB, types) before UI
+
+After creating files, report summary and suggest running `$ralph-loop` to start.
+
+Task to break down:
+{{ARGUMENTS}}

package/.agent/skills/ralplan/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: ralplan
+description: Iterative planning with Planner, Architect, and Critic until consensus
+---
+
+# Ralplan Command
+
+
+## Native Subagent Protocol (Codex)
+
+Codex supports native subagents. Delegate with `spawn_agent`, coordinate with `send_input`, collect via `wait`, and clean up with `close_agent`.
+
+Execution preference:
+1. Use native subagents first for independent workstreams (parallel when possible).
+2. Merge results in main thread and run final verification.
+3. Fallback only when delegation is blocked: use the `[ANALYST]`/`[ARCHITECT]`/`[EXECUTOR]`/`[REVIEWER]` structure in a single response.
+
+Minimal orchestration pattern:
+```text
+spawn_agent -> send_input (optional) -> wait -> close_agent
+```
+
+> Codex invocation: use `$ralplan ...` or `ralplan: ...`
+
+
+**This is an alias for `$plan --consensus`**
+
+Ralplan orchestrates three specialized agents—Planner, Architect, and Critic—in an iterative loop until consensus is reached on a comprehensive work plan.
+
+## Usage
+
+```
+$ralplan [task]
+```
+
+## What It Does
+
+Invokes the plan skill with --consensus mode, which:
+1. Creates initial plan with Planner agent
+2. Consults Architect for architectural questions
+3. Reviews with Critic agent
+4. Iterates until Critic approves (max 5 iterations)
+
+## Implementation
+
+When this skill is invoked, immediately invoke the plan skill with consensus mode:
+
+```
+Invoke Skill: plan --consensus {{ARGUMENTS}}
+```
+
+Pass all arguments to the plan skill. The plan skill handles all consensus logic, state management, and iteration.
+
+## See Also
+
+- `$plan` - Base planning skill with all modes
+- `$plan --consensus` - Direct invocation of consensus mode
+- `$cancel` - Cancel active planning session

package/.agent/skills/refactor-clean/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: refactor-clean
+description: Imported from everything-codex command refactor-clean
+---
+
+# Refactor Clean
+
+
+## Native Subagent Protocol (Codex)
+
+Codex supports native subagents. Delegate with `spawn_agent`, coordinate with `send_input`, collect via `wait`, and clean up with `close_agent`.
+
+Execution preference:
+1. Use native subagents first for independent workstreams (parallel when possible).
+2. Merge results in main thread and run final verification.
+3. Fallback only when delegation is blocked: use the `[ANALYST]`/`[ARCHITECT]`/`[EXECUTOR]`/`[REVIEWER]` structure in a single response.
+
+Minimal orchestration pattern:
+```text
+spawn_agent -> send_input (optional) -> wait -> close_agent
+```
+
+Safely identify and remove dead code with test verification:
+
+1. Run dead code analysis tools:
+   - knip: Find unused exports and files
+   - depcheck: Find unused dependencies
+   - ts-prune: Find unused TypeScript exports
+
+2. Generate comprehensive report in .reports/dead-code-analysis.md
+
+3. Categorize findings by severity:
+   - SAFE: Test files, unused utilities
+   - CAUTION: API routes, components
+   - DANGER: Config files, main entry points
+
+4. Propose safe deletions only
+
+5. Before each deletion:
+   - Run full test suite
+   - Verify tests pass
+   - Apply change
+   - Re-run tests
+   - Rollback if tests fail
+
+6. Show summary of cleaned items
+
+Never delete code without running tests first!
+

package/.agent/skills/release/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: release
+description: Automated release workflow for oh-my-codex
+---
+
+# Release Skill
+
+
+## Native Subagent Protocol (Codex)
+
+Codex supports native subagents. Delegate with `spawn_agent`, coordinate with `send_input`, collect via `wait`, and clean up with `close_agent`.
+
+Execution preference:
+1. Use native subagents first for independent workstreams (parallel when possible).
+2. Merge results in main thread and run final verification.
+3. Fallback only when delegation is blocked: use the `[ANALYST]`/`[ARCHITECT]`/`[EXECUTOR]`/`[REVIEWER]` structure in a single response.
+
+Minimal orchestration pattern:
+```text
+spawn_agent -> send_input (optional) -> wait -> close_agent
+```
+
+> Codex invocation: use `$release ...` or `release: ...`
+
+Automate the release process for oh-my-codex.
+
+## Usage
+
+```
+$release <version>
+```
+
+Example: `$release 0.2.0` or `$release patch` or `$release minor`
+
+## Release Checklist
+
+Execute these steps in order:
+
+### 1. Version Bump
+Update version in all locations:
+- `package.json`
+- `README.md`
+- `AGENTS.md`
+- `docs/CODEX.md`
+- `CHANGELOG.md`
+
+### 2. Run Tests (optional)
+```bash
+npm run test:run
+```
+
+### 3. Commit Version Bump
+```bash
+git add -A
+git commit -m "chore: bump version to <version>"
+```
+
+### 4. Create & Push Tag
+```bash
+git tag v<version>
+git push origin main
+git push origin v<version>
+```
+
+### 5. Create GitHub Release
+```bash
+gh release create v<version> --title "v<version> - <title>" --notes "<release notes>"
+```
+
+## Version Files Reference
+
+| File | Field/Line |
+|------|------------|
+| `package.json` | `"version": "X.Y.Z"` |
+| `README.md` | Title/metadata |
+| `AGENTS.md` | Version line |
+| `docs/CODEX.md` | Version mention (if any) |
+| `CHANGELOG.md` | New entry |
+
+## Semantic Versioning
+
+- **patch** (X.Y.Z+1): Bug fixes, minor improvements
+- **minor** (X.Y+1.0): New features, backward compatible
+- **major** (X+1.0.0): Breaking changes