oh-my-codex 0.1.1

package/skills/deepinit/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: deepinit
+description: Deep codebase initialization with hierarchical AGENTS.md documentation
+---
+
+# Deep Init Skill
+
+Creates comprehensive, hierarchical AGENTS.md documentation across the entire codebase.
+
+## Core Concept
+
+AGENTS.md files serve as **AI-readable documentation** that helps agents understand:
+- What each directory contains
+- How components relate to each other
+- Special instructions for working in that area
+- Dependencies and relationships
+
+## Hierarchical Tagging System
+
+Every AGENTS.md (except root) includes a parent reference tag:
+
+```markdown
+<!-- Parent: ../AGENTS.md -->
+```
+
+This creates a navigable hierarchy:
+```
+/AGENTS.md                          ← Root (no parent tag)
+├── src/AGENTS.md                   ← <!-- Parent: ../AGENTS.md -->
+│   ├── src/components/AGENTS.md    ← <!-- Parent: ../AGENTS.md -->
+│   └── src/utils/AGENTS.md         ← <!-- Parent: ../AGENTS.md -->
+└── docs/AGENTS.md                  ← <!-- Parent: ../AGENTS.md -->
+```
+
+## AGENTS.md Template
+
+```markdown
+<!-- Parent: {relative_path_to_parent}/AGENTS.md -->
+<!-- Generated: {timestamp} | Updated: {timestamp} -->
+
+# {Directory Name}
+
+## Purpose
+{One-paragraph description of what this directory contains and its role}
+
+## Key Files
+{List each significant file with a one-line description}
+
+| File | Description |
+|------|-------------|
+| `file.ts` | Brief description of purpose |
+
+## Subdirectories
+{List each subdirectory with brief purpose}
+
+| Directory | Purpose |
+|-----------|---------|
+| `subdir/` | What it contains (see `subdir/AGENTS.md`) |
+
+## For AI Agents
+
+### Working In This Directory
+{Special instructions for AI agents modifying files here}
+
+### Testing Requirements
+{How to test changes in this directory}
+
+### Common Patterns
+{Code patterns or conventions used here}
+
+## Dependencies
+
+### Internal
+{References to other parts of the codebase this depends on}
+
+### External
+{Key external packages/libraries used}
+
+<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->
+```
+
+## Execution Workflow
+
+### Step 1: Map Directory Structure
+
+```
+spawn_sub_agent(subagent_type="explore", model="haiku",
+  prompt="List all directories recursively. Exclude: node_modules, .git, dist, build, __pycache__, .venv, coverage, .next, .nuxt")
+```
+
+### Step 2: Create Work Plan
+
+Generate todo items for each directory, organized by depth level:
+
+```
+Level 0: / (root)
+Level 1: /src, /docs, /tests
+Level 2: /src/components, /src/utils, /docs/api
+...
+```
+
+### Step 3: Generate Level by Level
+
+**IMPORTANT**: Generate parent levels before child levels to ensure parent references are valid.
+
+For each directory:
+1. Read all files in the directory
+2. Analyze purpose and relationships
+3. Generate AGENTS.md content
+4. Write file with proper parent reference
+
+### Step 4: Compare and Update (if exists)
+
+When AGENTS.md already exists:
+
+1. **Read existing content**
+2. **Identify sections**:
+   - Auto-generated sections (can be updated)
+   - Manual sections (`<!-- MANUAL -->` preserved)
+3. **Compare**:
+   - New files added?
+   - Files removed?
+   - Structure changed?
+4. **Merge**:
+   - Update auto-generated content
+   - Preserve manual annotations
+   - Update timestamp
+
+### Step 5: Validate Hierarchy
+
+After generation, run validation checks:
+
+| Check | How to Verify | Corrective Action |
+|-------|--------------|-------------------|
+| Parent references resolve | Read each AGENTS.md, check `<!-- Parent: -->` path exists | Fix path or remove orphan |
+| No orphaned AGENTS.md | Compare AGENTS.md locations to directory structure | Delete orphaned files |
+| Completeness | List all directories, check for AGENTS.md | Generate missing files |
+| Timestamps current | Check `<!-- Generated: -->` dates | Regenerate outdated files |
+
+Validation script pattern:
+```bash
+# Find all AGENTS.md files
+find . -name "AGENTS.md" -type f
+
+# Check parent references
+grep -r "<!-- Parent:" --include="AGENTS.md" .
+```
+
+## Smart Delegation
+
+| Task | Agent |
+|------|-------|
+| Directory mapping | `explore` |
+| File analysis | `architect-low` |
+| Content generation | `writer` |
+| AGENTS.md writes | `writer` |
+
+## Empty Directory Handling
+
+When encountering empty or near-empty directories:
+
+| Condition | Action |
+|-----------|--------|
+| No files, no subdirectories | **Skip** - do not create AGENTS.md |
+| No files, has subdirectories | Create minimal AGENTS.md with subdirectory listing only |
+| Has only generated files (*.min.js, *.map) | Skip or minimal AGENTS.md |
+| Has only config files | Create AGENTS.md describing configuration purpose |
+
+Example minimal AGENTS.md for directory-only containers:
+```markdown
+<!-- Parent: ../AGENTS.md -->
+# {Directory Name}
+
+## Purpose
+Container directory for organizing related modules.
+
+## Subdirectories
+| Directory | Purpose |
+|-----------|---------|
+| `subdir/` | Description (see `subdir/AGENTS.md`) |
+```
+
+## Parallelization Rules
+
+1. **Same-level directories**: Process in parallel
+2. **Different levels**: Sequential (parent first)
+3. **Large directories**: Spawn dedicated agent per directory
+4. **Small directories**: Batch multiple into one agent
+
+## Quality Standards
+
+### Must Include
+- [ ] Accurate file descriptions
+- [ ] Correct parent references
+- [ ] Subdirectory links
+- [ ] AI agent instructions
+
+### Must Avoid
+- [ ] Generic boilerplate
+- [ ] Incorrect file names
+- [ ] Broken parent references
+- [ ] Missing important files
+
+## Example Output
+
+### Root AGENTS.md
+```markdown
+<!-- Generated: 2024-01-15 | Updated: 2024-01-15 -->
+
+# my-project
+
+## Purpose
+A web application for managing user tasks with real-time collaboration features.
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `package.json` | Project dependencies and scripts |
+| `tsconfig.json` | TypeScript configuration |
+| `.env.example` | Environment variable template |
+
+## Subdirectories
+| Directory | Purpose |
+|-----------|---------|
+| `src/` | Application source code (see `src/AGENTS.md`) |
+| `docs/` | Documentation (see `docs/AGENTS.md`) |
+| `tests/` | Test suites (see `tests/AGENTS.md`) |
+
+## For AI Agents
+
+### Working In This Directory
+- Always install dependencies after modifying the project manifest
+- Use TypeScript strict mode
+- Follow ESLint rules
+
+### Testing Requirements
+- Run tests before committing
+- Ensure >80% coverage
+
+### Common Patterns
+- Use barrel exports (index.ts)
+- Prefer functional components
+
+## Dependencies
+
+### External
+- React 18.x - UI framework
+- TypeScript 5.x - Type safety
+- Vite - Build tool
+
+<!-- MANUAL: Custom project notes can be added below -->
+```
+
+### Nested AGENTS.md
+```markdown
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2024-01-15 | Updated: 2024-01-15 -->
+
+# components
+
+## Purpose
+Reusable React components organized by feature and complexity.
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `index.ts` | Barrel export for all components |
+| `Button.tsx` | Primary button component |
+| `Modal.tsx` | Modal dialog component |
+
+## Subdirectories
+| Directory | Purpose |
+|-----------|---------|
+| `forms/` | Form-related components (see `forms/AGENTS.md`) |
+| `layout/` | Layout components (see `layout/AGENTS.md`) |
+
+## For AI Agents
+
+### Working In This Directory
+- Each component has its own file
+- Use CSS modules for styling
+- Export via index.ts
+
+### Testing Requirements
+- Unit tests in `__tests__/` subdirectory
+- Use React Testing Library
+
+### Common Patterns
+- Props interfaces defined above component
+- Use forwardRef for DOM-exposing components
+
+## Dependencies
+
+### Internal
+- `src/hooks/` - Custom hooks used by components
+- `src/utils/` - Utility functions
+
+### External
+- `clsx` - Conditional class names
+- `lucide-react` - Icons
+
+<!-- MANUAL: -->
+```
+
+## Triggering Update Mode
+
+When running on an existing codebase with AGENTS.md files:
+
+1. Detect existing files first
+2. Read and parse existing content
+3. Analyze current directory state
+4. Generate diff between existing and current
+5. Apply updates while preserving manual sections
+
+## Performance Considerations
+
+- **Cache directory listings** - Don't re-scan same directories
+- **Batch small directories** - Process multiple at once
+- **Skip unchanged** - If directory hasn't changed, skip regeneration
+- **Parallel writes** - Multiple agents writing different files simultaneously

package/skills/deepsearch/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: deepsearch
+description: Thorough codebase search
+---
+
+# Deep Search Mode
+
+[DEEPSEARCH MODE ACTIVATED]
+
+## Objective
+
+Perform thorough search of the codebase for the specified query, pattern, or concept.
+
+## Search Strategy
+
+1. **Broad Search**
+   - Search for exact matches
+   - Search for related terms and variations
+   - Check common locations (components, utils, services, hooks)
+
+2. **Deep Dive**
+   - Read files with matches
+   - Check imports/exports to find connections
+   - Follow the trail (what imports this? what does this import?)
+
+3. **Synthesize**
+   - Map out where the concept is used
+   - Identify the main implementation
+   - Note related functionality
+
+## Output Format
+
+- **Primary Locations** (main implementations)
+- **Related Files** (dependencies, consumers)
+- **Usage Patterns** (how it's used across the codebase)
+- **Key Insights** (patterns, conventions, gotchas)
+
+Focus on being comprehensive but concise. Cite file paths and line numbers.

package/skills/doctor/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: doctor
+description: Diagnose and fix oh-my-codex installation issues
+---
+
+# Doctor Skill
+
+Note: All `~/.claude/...` paths in this guide respect `CLAUDE_CONFIG_DIR` when that environment variable is set.
+
+## Task: Run Installation Diagnostics
+
+You are the OMX Doctor - diagnose and fix installation issues.
+
+### Step 1: Check Plugin Version
+
+```bash
+# Get installed version
+INSTALLED=$(ls ~/.claude/plugins/cache/omc/oh-my-codex/ 2>/dev/null | sort -V | tail -1)
+echo "Installed: $INSTALLED"
+
+# Get latest from npm
+LATEST=$(npm view oh-my-claude-sisyphus version 2>/dev/null)
+echo "Latest: $LATEST"
+```
+
+**Diagnosis**:
+- If no version installed: CRITICAL - plugin not installed
+- If INSTALLED != LATEST: WARN - outdated plugin
+- If multiple versions exist: WARN - stale cache
+
+### Step 2: Check for Legacy Hooks in settings.json
+
+Read `~/.claude/settings.json` and check if there's a `"hooks"` key with entries like:
+- `bash $HOME/.claude/hooks/keyword-detector.sh`
+- `bash $HOME/.claude/hooks/persistent-mode.sh`
+- `bash $HOME/.claude/hooks/session-start.sh`
+
+**Diagnosis**:
+- If found: CRITICAL - legacy hooks causing duplicates
+
+### Step 3: Check for Legacy Bash Hook Scripts
+
+```bash
+ls -la ~/.claude/hooks/*.sh 2>/dev/null
+```
+
+**Diagnosis**:
+- If `keyword-detector.sh`, `persistent-mode.sh`, `session-start.sh`, or `stop-continuation.sh` exist: WARN - legacy scripts (can cause confusion)
+
+### Step 4: Check CLAUDE.md
+
+```bash
+# Check if CLAUDE.md exists
+ls -la ~/.claude/CLAUDE.md 2>/dev/null
+
+# Check for OMX marker
+grep -q "oh-my-codex Multi-Agent System" ~/.claude/CLAUDE.md 2>/dev/null && echo "Has OMX config" || echo "Missing OMX config"
+```
+
+**Diagnosis**:
+- If missing: CRITICAL - CLAUDE.md not configured
+- If missing OMX marker: WARN - outdated CLAUDE.md
+
+### Step 5: Check for Stale Plugin Cache
+
+```bash
+# Count versions in cache
+ls ~/.claude/plugins/cache/omc/oh-my-codex/ 2>/dev/null | wc -l
+```
+
+**Diagnosis**:
+- If > 1 version: WARN - multiple cached versions (cleanup recommended)
+
+### Step 6: Check for Legacy Curl-Installed Content
+
+Check for legacy agents, commands, and skills installed via curl (before plugin system):
+
+```bash
+# Check for legacy agents directory
+ls -la ~/.claude/agents/ 2>/dev/null
+
+# Check for legacy commands directory
+ls -la ~/.claude/commands/ 2>/dev/null
+
+# Check for legacy skills directory
+ls -la ~/.claude/skills/ 2>/dev/null
+```
+
+**Diagnosis**:
+- If `~/.claude/agents/` exists with oh-my-codex-related files: WARN - legacy agents (now provided by plugin)
+- If `~/.claude/commands/` exists with oh-my-codex-related files: WARN - legacy commands (now provided by plugin)
+- If `~/.claude/skills/` exists with oh-my-codex-related files: WARN - legacy skills (now provided by plugin)
+
+Look for files like:
+- `architect.md`, `researcher.md`, `explore.md`, `executor.md`, etc. in agents/
+- `ultrawork.md`, `deepsearch.md`, etc. in commands/
+- Any oh-my-codex-related `.md` files in skills/
+
+---
+
+## Report Format
+
+After running all checks, output a report:
+
+```
+## OMX Doctor Report
+
+### Summary
+[HEALTHY / ISSUES FOUND]
+
+### Checks
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Plugin Version | OK/WARN/CRITICAL | ... |
+| Legacy Hooks (settings.json) | OK/CRITICAL | ... |
+| Legacy Scripts (~/.claude/hooks/) | OK/WARN | ... |
+| CLAUDE.md | OK/WARN/CRITICAL | ... |
+| Plugin Cache | OK/WARN | ... |
+| Legacy Agents (~/.claude/agents/) | OK/WARN | ... |
+| Legacy Commands (~/.claude/commands/) | OK/WARN | ... |
+| Legacy Skills (~/.claude/skills/) | OK/WARN | ... |
+
+### Issues Found
+1. [Issue description]
+2. [Issue description]
+
+### Recommended Fixes
+[List fixes based on issues]
+```
+
+---
+
+## Auto-Fix (if user confirms)
+
+If issues found, ask user: "Would you like me to fix these issues automatically?"
+
+If yes, apply fixes:
+
+### Fix: Legacy Hooks in settings.json
+Remove the `"hooks"` section from `~/.claude/settings.json` (keep other settings intact)
+
+### Fix: Legacy Bash Scripts
+```bash
+rm -f ~/.claude/hooks/keyword-detector.sh
+rm -f ~/.claude/hooks/persistent-mode.sh
+rm -f ~/.claude/hooks/session-start.sh
+rm -f ~/.claude/hooks/stop-continuation.sh
+```
+
+### Fix: Outdated Plugin
+```bash
+rm -rf ~/.claude/plugins/cache/oh-my-codex
+echo "Plugin cache cleared. Restart Codex CLI to fetch latest version."
+```
+
+### Fix: Stale Cache (multiple versions)
+```bash
+# Keep only latest version
+cd ~/.claude/plugins/cache/omc/oh-my-codex/
+ls | sort -V | head -n -1 | xargs rm -rf
+```
+
+### Fix: Missing/Outdated CLAUDE.md
+Fetch latest from GitHub and write to `~/.claude/CLAUDE.md`:
+```
+WebFetch(url: "https://raw.githubusercontent.com/Yeachan-Heo/oh-my-codex/main/docs/CLAUDE.md", prompt: "Return the complete raw markdown content exactly as-is")
+```
+
+### Fix: Legacy Curl-Installed Content
+
+Remove legacy agents, commands, and skills directories (now provided by plugin):
+
+```bash
+# Backup first (optional - ask user)
+# mv ~/.claude/agents ~/.claude/agents.bak
+# mv ~/.claude/commands ~/.claude/commands.bak
+# mv ~/.claude/skills ~/.claude/skills.bak
+
+# Or remove directly
+rm -rf ~/.claude/agents
+rm -rf ~/.claude/commands
+rm -rf ~/.claude/skills
+```
+
+**Note**: Only remove if these contain oh-my-codex-related files. If user has custom agents/commands/skills, warn them and ask before removing.
+
+---
+
+## Post-Fix
+
+After applying fixes, inform user:
+> Fixes applied. **Restart Codex CLI** for changes to take effect.

package/skills/ecomode/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: ecomode
+description: Token-efficient model routing modifier
+---
+
+# Ecomode Skill
+
+Token-efficient model routing. This is a **MODIFIER**, not a standalone execution mode.
+
+## What Ecomode Does
+
+Overrides default model selection to prefer cheaper tiers:
+
+| Default Tier | Ecomode Override |
+|--------------|------------------|
+| HIGH (opus) | MEDIUM (sonnet), HIGH only if essential |
+| MEDIUM (sonnet) | LOW (haiku) first, MEDIUM if fails |
+| LOW (haiku) | LOW (haiku) - no change |
+
+## What Ecomode Does NOT Do
+
+- **Persistence**: Use `ralph` for "don't stop until done"
+- **Parallel Execution**: Use `ultrawork` for parallel agents
+- **Delegation Enforcement**: Always active via core orchestration
+
+## Combining Ecomode with Other Modes
+
+Ecomode is a modifier that combines with execution modes:
+
+| Combination | Effect |
+|-------------|--------|
+| `eco ralph` | Ralph loop with cheaper agents |
+| `eco ultrawork` | Parallel execution with cheaper agents |
+| `eco autopilot` | Full autonomous with cost optimization |
+
+## Ecomode Routing Rules
+
+**ALWAYS prefer lower tiers. Only escalate when task genuinely requires it.**
+
+| Decision | Rule |
+|----------|------|
+| DEFAULT | Start with LOW tier (Haiku) for most tasks |
+| UPGRADE | Escalate to MEDIUM (Sonnet) when LOW tier fails or task requires multi-file reasoning |
+| AVOID | HIGH tier (Opus) - only for planning/critique if essential |
+
+## Agent Selection in Ecomode
+
+**FIRST ACTION:** Before delegating any work, read the agent reference file:
+```
+Read file: docs/shared/agent-tiers.md
+```
+This provides the complete agent tier matrix, MCP tool assignments, and selection guidance.
+
+**Ecomode preference order:**
+
+```
+// PREFERRED - Use for most tasks
+spawn_sub_agent(subagent_type="oh-my-codex:executor-low", model="haiku", prompt="...")
+spawn_sub_agent(subagent_type="oh-my-codex:explore", model="haiku", prompt="...")
+spawn_sub_agent(subagent_type="oh-my-codex:architect-low", model="haiku", prompt="...")
+
+// FALLBACK - Only if LOW fails
+spawn_sub_agent(subagent_type="oh-my-codex:executor", model="sonnet", prompt="...")
+spawn_sub_agent(subagent_type="oh-my-codex:architect-medium", model="sonnet", prompt="...")
+
+// AVOID - Only for planning/critique if essential
+spawn_sub_agent(subagent_type="oh-my-codex:planner", model="opus", prompt="...")
+```
+
+## Delegation Enforcement
+
+Ecomode maintains all delegation rules from core protocol with cost-optimized routing:
+
+| Action | Delegate To | Model |
+|--------|-------------|-------|
+| Code changes | executor-low / executor | haiku / sonnet |
+| Analysis | architect-low | haiku |
+| Search | explore | haiku |
+| Documentation | writer | haiku |
+
+### Background Execution
+Long-running commands (install, build, test) run in background. Maximum 20 concurrent.
+
+## Token Savings Tips
+
+1. **Batch similar tasks** to one agent instead of spawning many
+2. **Use explore (haiku)** for file discovery, not architect
+3. **Prefer executor-low** for simple changes - only upgrade if it fails
+4. **Use writer (haiku)** for all documentation tasks
+5. **Avoid opus agents** unless the task genuinely requires deep reasoning
+
+## Disabling Ecomode
+
+Ecomode can be completely disabled via config. When disabled, all ecomode keywords are ignored.
+
+Set in `~/.claude/.omx-config.json`:
+```json
+{
+  "ecomode": {
+    "enabled": false
+  }
+}
+```
+
+## State Management
+
+Use `omx_state` MCP tools for ecomode lifecycle state.
+
+- **On activation**:
+  `state_write({mode: "ecomode", active: true})`
+- **On deactivation/completion**:
+  `state_write({mode: "ecomode", active: false})`
+- **On cancellation/cleanup**:
+  run `$cancel` (which should call `state_clear(mode="ecomode")`)

package/skills/frontend-ui-ux/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: frontend-ui-ux
+description: Designer-developer for UI/UX work
+---
+
+# Frontend UI/UX Command
+
+Routes to the designer agent or Gemini MCP for frontend work.
+
+## Usage
+
+```
+/frontend-ui-ux <design task>
+```
+
+## Routing
+
+### Preferred: MCP Direct
+Before first MCP tool use, call `ToolSearch("mcp")` to discover deferred MCP tools.
+Use `mcp__g__ask_gemini` with `agent_role: "designer"` for design tasks.
+If ToolSearch finds no MCP tools, use the Claude agent fallback below.
+
+### Fallback: Claude Agent
+```
+spawn_sub_agent(subagent_type="oh-my-codex:designer", model="sonnet", prompt="{{ARGUMENTS}}")
+```
+
+## Capabilities
+- Component design and implementation
+- Responsive layouts
+- Design system consistency
+- Accessibility compliance
+
+Task: {{ARGUMENTS}}