oh-my-codex 0.1.1

package/prompts/writer.md

@@ -0,0 +1,86 @@
+---
+description: "Technical documentation writer for README, API docs, and comments (Haiku)"
+argument-hint: "task description"
+---
+
+<Agent_Prompt>
+  <Role>
+    You are Writer. Your mission is to create clear, accurate technical documentation that developers want to read.
+    You are responsible for README files, API documentation, architecture docs, user guides, and code comments.
+    You are not responsible for implementing features, reviewing code quality, or making architectural decisions.
+  </Role>
+
+  <Why_This_Matters>
+    Inaccurate documentation is worse than no documentation -- it actively misleads. These rules exist because documentation with untested code examples causes frustration, and documentation that doesn't match reality wastes developer time. Every example must work, every command must be verified.
+  </Why_This_Matters>
+
+  <Success_Criteria>
+    - All code examples tested and verified to work
+    - All commands tested and verified to run
+    - Documentation matches existing style and structure
+    - Content is scannable: headers, code blocks, tables, bullet points
+    - A new developer can follow the documentation without getting stuck
+  </Success_Criteria>
+
+  <Constraints>
+    - Document precisely what is requested, nothing more, nothing less.
+    - Verify every code example and command before including it.
+    - Match existing documentation style and conventions.
+    - Use active voice, direct language, no filler words.
+    - If examples cannot be tested, explicitly state this limitation.
+  </Constraints>
+
+  <Investigation_Protocol>
+    1) Parse the request to identify the exact documentation task.
+    2) Explore the codebase to understand what to document (use Glob, Grep, Read in parallel).
+    3) Study existing documentation for style, structure, and conventions.
+    4) Write documentation with verified code examples.
+    5) Test all commands and examples.
+    6) Report what was documented and verification results.
+  </Investigation_Protocol>
+
+  <Tool_Usage>
+    - Use Read/Glob/Grep to explore codebase and existing docs (parallel calls).
+    - Use Write to create documentation files.
+    - Use Edit to update existing documentation.
+    - Use Bash to test commands and verify examples work.
+  </Tool_Usage>
+
+  <Execution_Policy>
+    - Default effort: low (concise, accurate documentation).
+    - Stop when documentation is complete, accurate, and verified.
+  </Execution_Policy>
+
+  <Output_Format>
+    COMPLETED TASK: [exact task description]
+    STATUS: SUCCESS / FAILED / BLOCKED
+
+    FILES CHANGED:
+    - Created: [list]
+    - Modified: [list]
+
+    VERIFICATION:
+    - Code examples tested: X/Y working
+    - Commands verified: X/Y valid
+  </Output_Format>
+
+  <Failure_Modes_To_Avoid>
+    - Untested examples: Including code snippets that don't actually compile or run. Test everything.
+    - Stale documentation: Documenting what the code used to do rather than what it currently does. Read the actual code first.
+    - Scope creep: Documenting adjacent features when asked to document one specific thing. Stay focused.
+    - Wall of text: Dense paragraphs without structure. Use headers, bullets, code blocks, and tables.
+  </Failure_Modes_To_Avoid>
+
+  <Examples>
+    <Good>Task: "Document the auth API." Writer reads the actual auth code, writes API docs with tested curl examples that return real responses, includes error codes from actual error handling, and verifies the installation command works.</Good>
+    <Bad>Task: "Document the auth API." Writer guesses at endpoint paths, invents response formats, includes untested curl examples, and copies parameter names from memory instead of reading the code.</Bad>
+  </Examples>
+
+  <Final_Checklist>
+    - Are all code examples tested and working?
+    - Are all commands verified?
+    - Does the documentation match existing style?
+    - Is the content scannable (headers, code blocks, tables)?
+    - Did I stay within the requested scope?
+  </Final_Checklist>
+</Agent_Prompt>

package/scripts/notify-hook.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+
+/**
+ * oh-my-codex Notification Hook
+ * Codex CLI fires this after each agent turn via the `notify` config.
+ * Receives JSON payload as the last argv argument.
+ *
+ * This hook:
+ * 1. Logs agent turn completions to .omx/logs/
+ * 2. Updates state for active workflow modes
+ * 3. Tracks subagent activity
+ * 4. Triggers desktop notifications if configured
+ */
+
+import { writeFile, appendFile, mkdir, readFile } from 'fs/promises';
+import { join } from 'path';
+import { existsSync } from 'fs';
+
+function asNumber(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return null;
+}
+
+function getSessionTokenUsage(payload) {
+  const usage = payload.usage || payload['usage'] || payload.token_usage || payload['token-usage'] || {};
+
+  const input = asNumber(
+    usage.session_input_tokens
+    ?? usage.input_tokens
+    ?? usage.total_input_tokens
+    ?? payload.session_input_tokens
+    ?? payload.input_tokens
+    ?? payload.total_input_tokens
+  );
+  const output = asNumber(
+    usage.session_output_tokens
+    ?? usage.output_tokens
+    ?? usage.total_output_tokens
+    ?? payload.session_output_tokens
+    ?? payload.output_tokens
+    ?? payload.total_output_tokens
+  );
+  const total = asNumber(
+    usage.session_total_tokens
+    ?? usage.total_tokens
+    ?? payload.session_total_tokens
+    ?? payload.total_tokens
+  );
+
+  if (input === null && output === null && total === null) return null;
+
+  return {
+    input,
+    output,
+    total: total ?? ((input ?? 0) + (output ?? 0)),
+  };
+}
+
+function clampPct(value) {
+  if (!Number.isFinite(value)) return null;
+  if (value < 0) return 0;
+  if (value <= 1) return Math.round(value * 100);
+  if (value > 100) return 100;
+  return Math.round(value);
+}
+
+function extractLimitPct(limit) {
+  if (limit == null) return null;
+  if (typeof limit === 'number' || typeof limit === 'string') return clampPct(asNumber(limit));
+  if (typeof limit !== 'object') return null;
+
+  const directPct = clampPct(asNumber(limit.percent ?? limit.pct ?? limit.usage_percent ?? limit.usagePct));
+  if (directPct !== null) return directPct;
+
+  const used = asNumber(limit.used ?? limit.usage ?? limit.current);
+  const max = asNumber(limit.limit ?? limit.max ?? limit.total);
+  if (used !== null && max !== null && max > 0) {
+    return clampPct((used / max) * 100);
+  }
+
+  const remaining = asNumber(limit.remaining ?? limit.left);
+  if (remaining !== null && max !== null && max > 0) {
+    return clampPct(((max - remaining) / max) * 100);
+  }
+
+  return null;
+}
+
+function getQuotaUsage(payload) {
+  const usage = payload.usage || payload['usage'] || payload.token_usage || payload['token-usage'] || {};
+
+  const fiveHourRaw =
+    usage.five_hour_limit
+    ?? usage.fiveHourLimit
+    ?? usage['5h_limit']
+    ?? payload.five_hour_limit
+    ?? payload.fiveHourLimit
+    ?? payload['5h_limit'];
+  const weeklyRaw =
+    usage.weekly_limit
+    ?? usage.weeklyLimit
+    ?? payload.weekly_limit
+    ?? payload.weeklyLimit;
+
+  const fiveHourLimitPct = extractLimitPct(fiveHourRaw);
+  const weeklyLimitPct = extractLimitPct(weeklyRaw);
+
+  if (fiveHourLimitPct === null && weeklyLimitPct === null) return null;
+  return { fiveHourLimitPct, weeklyLimitPct };
+}
+
+async function main() {
+  const rawPayload = process.argv[process.argv.length - 1];
+  if (!rawPayload || rawPayload.startsWith('-')) {
+    process.exit(0);
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(rawPayload);
+  } catch {
+    process.exit(0);
+  }
+
+  const cwd = payload.cwd || payload['cwd'] || process.cwd();
+  const omxDir = join(cwd, '.omx');
+  const logsDir = join(omxDir, 'logs');
+  const stateDir = join(omxDir, 'state');
+
+  // Ensure directories exist
+  await mkdir(logsDir, { recursive: true }).catch(() => {});
+  await mkdir(stateDir, { recursive: true }).catch(() => {});
+
+  // 1. Log the turn
+  const logEntry = {
+    timestamp: new Date().toISOString(),
+    type: payload.type || 'agent-turn-complete',
+    thread_id: payload['thread-id'] || payload.thread_id,
+    turn_id: payload['turn-id'] || payload.turn_id,
+    input_preview: (payload['input-messages'] || payload.input_messages || [])
+      .map(m => m.slice(0, 100))
+      .join('; '),
+    output_preview: (payload['last-assistant-message'] || payload.last_assistant_message || '')
+      .slice(0, 200),
+  };
+
+  const logFile = join(logsDir, `turns-${new Date().toISOString().split('T')[0]}.jsonl`);
+  await appendFile(logFile, JSON.stringify(logEntry) + '\n').catch(() => {});
+
+  // 2. Update active mode state (increment iteration)
+  try {
+    const stateFiles = await readdir(stateDir);
+    for (const f of stateFiles) {
+      if (!f.endsWith('-state.json')) continue;
+      const statePath = join(stateDir, f);
+      const state = JSON.parse(await readFile(statePath, 'utf-8'));
+      if (state.active) {
+        state.iteration = (state.iteration || 0) + 1;
+        state.last_turn_at = new Date().toISOString();
+        await writeFile(statePath, JSON.stringify(state, null, 2));
+      }
+    }
+  } catch {
+    // Non-critical
+  }
+
+  // 3. Track subagent metrics
+  const metricsPath = join(omxDir, 'metrics.json');
+  try {
+    let metrics = {
+      total_turns: 0,
+      session_turns: 0,
+      last_activity: '',
+      session_input_tokens: 0,
+      session_output_tokens: 0,
+      session_total_tokens: 0,
+    };
+    if (existsSync(metricsPath)) {
+      metrics = { ...metrics, ...JSON.parse(await readFile(metricsPath, 'utf-8')) };
+    }
+
+    const tokenUsage = getSessionTokenUsage(payload);
+    const quotaUsage = getQuotaUsage(payload);
+
+    metrics.total_turns++;
+    metrics.session_turns++;
+    metrics.last_activity = new Date().toISOString();
+
+    if (tokenUsage) {
+      if (tokenUsage.input !== null) metrics.session_input_tokens = tokenUsage.input;
+      if (tokenUsage.output !== null) metrics.session_output_tokens = tokenUsage.output;
+      if (tokenUsage.total !== null) {
+        metrics.session_total_tokens = tokenUsage.total;
+      } else {
+        metrics.session_total_tokens = (metrics.session_input_tokens || 0) + (metrics.session_output_tokens || 0);
+      }
+    } else {
+      metrics.session_total_tokens = (metrics.session_input_tokens || 0) + (metrics.session_output_tokens || 0);
+    }
+
+    if (quotaUsage) {
+      if (quotaUsage.fiveHourLimitPct !== null) metrics.five_hour_limit_pct = quotaUsage.fiveHourLimitPct;
+      if (quotaUsage.weeklyLimitPct !== null) metrics.weekly_limit_pct = quotaUsage.weeklyLimitPct;
+    }
+
+    await writeFile(metricsPath, JSON.stringify(metrics, null, 2));
+  } catch {
+    // Non-critical
+  }
+
+  // 4. Write HUD state summary for `omx hud`
+  const hudStatePath = join(stateDir, 'hud-state.json');
+  try {
+    let hudState = { last_turn_at: '', turn_count: 0 };
+    if (existsSync(hudStatePath)) {
+      hudState = JSON.parse(await readFile(hudStatePath, 'utf-8'));
+    }
+    hudState.last_turn_at = new Date().toISOString();
+    hudState.turn_count = (hudState.turn_count || 0) + 1;
+    hudState.last_agent_output = (payload['last-assistant-message'] || payload.last_assistant_message || '')
+      .slice(0, 100);
+    await writeFile(hudStatePath, JSON.stringify(hudState, null, 2));
+  } catch {
+    // Non-critical
+  }
+}
+
+async function readdir(dir) {
+  const { readdir: rd } = await import('fs/promises');
+  return rd(dir);
+}
+
+main().catch(() => process.exit(0));

package/skills/analyze/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: analyze
+description: Deep analysis and investigation
+---
+
+<Purpose>
+Analyze performs deep investigation of architecture, bugs, performance issues, and dependencies. It routes to the architect agent or Codex MCP for thorough analysis and returns structured findings with evidence.
+</Purpose>
+
+<Use_When>
+- User says "analyze", "investigate", "debug", "why does", or "what's causing"
+- User needs to understand a system's architecture or behavior before making changes
+- User wants root cause analysis of a bug or performance issue
+- User needs dependency analysis or impact assessment for a proposed change
+- A complex question requires reading multiple files and reasoning across them
+</Use_When>
+
+<Do_Not_Use_When>
+- User wants code changes made -- use executor agents or `ralph` instead
+- User wants a full plan with acceptance criteria -- use `plan` skill instead
+- User wants a quick file lookup or symbol search -- use `explore` agent instead
+- User asks a simple factual question that can be answered from one file -- just read and answer directly
+</Do_Not_Use_When>
+
+<Why_This_Exists>
+Deep investigation requires a different approach than quick lookups or code changes. Analysis tasks need broad context gathering, cross-file reasoning, and structured findings. Routing these to the architect agent or Codex ensures the right level of depth without the overhead of a full planning or execution workflow.
+</Why_This_Exists>
+
+<Execution_Policy>
+- Prefer Codex MCP for analysis when available (faster, lower cost)
+- Fall back to architect Claude agent when Codex is unavailable
+- Always provide context files to the analysis tool for grounded reasoning
+- Return structured findings, not just raw observations
+</Execution_Policy>
+
+<Steps>
+1. **Identify the analysis type**: Architecture, bug investigation, performance, or dependency analysis
+2. **Gather relevant context**: Read or identify the key files involved
+3. **Route to analyzer**:
+   - Preferred: `ask_codex` with `agent_role: "architect"` and relevant `context_files`
+   - Fallback: `spawn_sub_agent(subagent_type="oh-my-codex:architect", model="opus", prompt="Analyze: ...")`
+4. **Return structured findings**: Present the analysis with evidence, file references, and actionable recommendations
+</Steps>
+
+<Tool_Usage>
+- Before first MCP tool use, call `ToolSearch("mcp")` to discover deferred MCP tools
+- Use `ask_codex` with `agent_role: "architect"` as the preferred analysis route
+- Pass `context_files` with all relevant source files for grounded analysis
+- Use `spawn_sub_agent(subagent_type="oh-my-codex:architect", model="opus", ...)` as fallback when ToolSearch finds no MCP tools or Codex is unavailable
+- For broad analysis, use `explore` agent first to identify relevant files before routing to architect
+</Tool_Usage>
+
+<Examples>
+<Good>
+User: "analyze why the WebSocket connections drop after 30 seconds"
+Action: Gather WebSocket-related files, route to architect with context, return root cause analysis with specific file:line references and a recommended fix.
+Why good: Clear investigation target, structured output with evidence.
+</Good>
+
+<Good>
+User: "investigate the dependency chain from src/api/routes.ts"
+Action: Use explore agent to map the import graph, then route to architect for impact analysis.
+Why good: Uses explore for fact-gathering, architect for reasoning.
+</Good>
+
+<Bad>
+User: "analyze the auth module"
+Action: Returning "The auth module handles authentication."
+Why bad: Shallow summary without investigation. Should examine the module's structure, patterns, potential issues, and provide specific findings with file references.
+</Bad>
+
+<Bad>
+User: "fix the bug in the parser"
+Action: Running analysis skill.
+Why bad: This is a fix request, not an analysis request. Route to executor or ralph instead.
+</Bad>
+</Examples>
+
+<Escalation_And_Stop_Conditions>
+- If analysis reveals the issue requires code changes, report findings and recommend using `ralph` or executor for the fix
+- If the analysis scope is too broad ("analyze everything"), ask the user to narrow the focus
+- If Codex is unavailable and the architect agent also fails, report what context was gathered and suggest manual investigation paths
+</Escalation_And_Stop_Conditions>
+
+<Final_Checklist>
+- [ ] Analysis addresses the specific question or investigation target
+- [ ] Findings reference specific files and line numbers where applicable
+- [ ] Root causes are identified (not just symptoms) for bug investigations
+- [ ] Actionable recommendations are provided
+- [ ] Analysis distinguishes between confirmed facts and hypotheses
+</Final_Checklist>
+
+Task: {{ARGUMENTS}}

package/skills/autopilot/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: autopilot
+description: Full autonomous execution from idea to working code
+---
+
+<Purpose>
+Autopilot takes a brief product idea and autonomously handles the full lifecycle: requirements analysis, technical design, planning, parallel implementation, QA cycling, and multi-perspective validation. It produces working, verified code from a 2-3 line description.
+</Purpose>
+
+<Use_When>
+- User wants end-to-end autonomous execution from an idea to working code
+- User says "autopilot", "auto pilot", "autonomous", "build me", "create me", "make me", "full auto", "handle it all", or "I want a/an..."
+- Task requires multiple phases: planning, coding, testing, and validation
+- User wants hands-off execution and is willing to let the system run to completion
+</Use_When>
+
+<Do_Not_Use_When>
+- User wants to explore options or brainstorm -- use `plan` skill instead
+- User says "just explain", "draft only", or "what would you suggest" -- respond conversationally
+- User wants a single focused code change -- use `ralph` or delegate to an executor agent
+- User wants to review or critique an existing plan -- use `plan --review`
+- Task is a quick fix or small bug -- use direct executor delegation
+</Do_Not_Use_When>
+
+<Why_This_Exists>
+Most non-trivial software tasks require coordinated phases: understanding requirements, designing a solution, implementing in parallel, testing, and validating quality. Autopilot orchestrates all of these phases automatically so the user can describe what they want and receive working code without managing each step.
+</Why_This_Exists>
+
+<Execution_Policy>
+- Each phase must complete before the next begins
+- Parallel execution is used within phases where possible (Phase 2 and Phase 4)
+- QA cycles repeat up to 5 times; if the same error persists 3 times, stop and report the fundamental issue
+- Validation requires approval from all reviewers; rejected items get fixed and re-validated
+- Cancel with `/cancel` at any time; progress is preserved for resume
+</Execution_Policy>
+
+<Steps>
+1. **Phase 0 - Expansion**: Turn the user's idea into a detailed spec
+   - Analyst (Opus): Extract requirements
+   - Architect (Opus): Create technical specification
+   - Output: `.omx/plans/autopilot-spec.md`
+
+2. **Phase 1 - Planning**: Create an implementation plan from the spec
+   - Architect (Opus): Create plan (direct mode, no interview)
+   - Critic (Opus): Validate plan
+   - Output: `.omx/plans/autopilot-impl.md`
+
+3. **Phase 2 - Execution**: Implement the plan using Ralph + Ultrawork
+   - Executor-low (Haiku): Simple tasks
+   - Executor (Sonnet): Standard tasks
+   - Executor-high (Opus): Complex tasks
+   - Run independent tasks in parallel
+
+4. **Phase 3 - QA**: Cycle until all tests pass (UltraQA mode)
+   - Build, lint, test, fix failures
+   - Repeat up to 5 cycles
+   - Stop early if the same error repeats 3 times (indicates a fundamental issue)
+
+5. **Phase 4 - Validation**: Multi-perspective review in parallel
+   - Architect: Functional completeness
+   - Security-reviewer: Vulnerability check
+   - Code-reviewer: Quality review
+   - All must approve; fix and re-validate on rejection
+
+6. **Phase 5 - Cleanup**: Clear all mode state via OMX MCP tools on successful completion
+   - `state_clear({mode: "autopilot"})`
+   - `state_clear({mode: "ralph"})`
+   - `state_clear({mode: "ultrawork"})`
+   - `state_clear({mode: "ultraqa"})`
+   - Or run `/cancel` for clean exit
+</Steps>
+
+<Tool_Usage>
+- Before first MCP tool use, call `ToolSearch("mcp")` to discover deferred MCP tools
+- Use `ask_codex` with `agent_role: "architect"` for Phase 4 architecture validation
+- Use `ask_codex` with `agent_role: "security-reviewer"` for Phase 4 security review
+- Use `ask_codex` with `agent_role: "code-reviewer"` for Phase 4 quality review
+- Agents form their own analysis first, then consult Codex for cross-validation
+- If ToolSearch finds no MCP tools or Codex is unavailable, proceed without it -- never block on external tools
+</Tool_Usage>
+
+## State Management
+
+Use `omx_state` MCP tools for autopilot lifecycle state.
+
+- **On start**:
+  `state_write({mode: "autopilot", active: true, current_phase: "expansion", started_at: "<now>"})`
+- **On phase transitions**:
+  `state_write({mode: "autopilot", current_phase: "planning"})`
+  `state_write({mode: "autopilot", current_phase: "execution"})`
+  `state_write({mode: "autopilot", current_phase: "qa"})`
+  `state_write({mode: "autopilot", current_phase: "validation"})`
+- **On completion**:
+  `state_write({mode: "autopilot", active: false, current_phase: "complete", completed_at: "<now>"})`
+- **On cancellation/cleanup**:
+  run `$cancel` (which should call `state_clear(mode="autopilot")`)
+
+<Examples>
+<Good>
+User: "autopilot A REST API for a bookstore inventory with CRUD operations using TypeScript"
+Why good: Specific domain (bookstore), clear features (CRUD), technology constraint (TypeScript). Autopilot has enough context to expand into a full spec.
+</Good>
+
+<Good>
+User: "build me a CLI tool that tracks daily habits with streak counting"
+Why good: Clear product concept with a specific feature. The "build me" trigger activates autopilot.
+</Good>
+
+<Bad>
+User: "fix the bug in the login page"
+Why bad: This is a single focused fix, not a multi-phase project. Use direct executor delegation or ralph instead.
+</Bad>
+
+<Bad>
+User: "what are some good approaches for adding caching?"
+Why bad: This is an exploration/brainstorming request. Respond conversationally or use the plan skill.
+</Bad>
+</Examples>
+
+<Escalation_And_Stop_Conditions>
+- Stop and report when the same QA error persists across 3 cycles (fundamental issue requiring human input)
+- Stop and report when validation keeps failing after 3 re-validation rounds
+- Stop when the user says "stop", "cancel", or "abort"
+- If requirements were too vague and expansion produces an unclear spec, pause and ask the user for clarification before proceeding
+</Escalation_And_Stop_Conditions>
+
+<Final_Checklist>
+- [ ] All 5 phases completed (Expansion, Planning, Execution, QA, Validation)
+- [ ] All validators approved in Phase 4
+- [ ] Tests pass (verified with fresh test run output)
+- [ ] Build succeeds (verified with fresh build output)
+- [ ] State files cleaned up
+- [ ] User informed of completion with summary of what was built
+</Final_Checklist>
+
+<Advanced>
+## Configuration
+
+Optional settings in `.claude/settings.json`:
+
+```json
+{
+  "omc": {
+    "autopilot": {
+      "maxIterations": 10,
+      "maxQaCycles": 5,
+      "maxValidationRounds": 3,
+      "pauseAfterExpansion": false,
+      "pauseAfterPlanning": false,
+      "skipQa": false,
+      "skipValidation": false
+    }
+  }
+}
+```
+
+## Resume
+
+If autopilot was cancelled or failed, run `/autopilot` again to resume from where it stopped.
+
+## Best Practices for Input
+
+1. Be specific about the domain -- "bookstore" not "store"
+2. Mention key features -- "with CRUD", "with authentication"
+3. Specify constraints -- "using TypeScript", "with PostgreSQL"
+4. Let it run -- avoid interrupting unless truly needed
+
+## Troubleshooting
+
+**Stuck in a phase?** Check TODO list for blocked tasks, run `state_read({mode: "autopilot"})`, or cancel and resume.
+
+**QA cycles exhausted?** The same error 3 times indicates a fundamental issue. Review the error pattern; manual intervention may be needed.
+
+**Validation keeps failing?** Review the specific issues. Requirements may have been too vague -- cancel and provide more detail.
+</Advanced>