claudecode-omc 4.3.4

package/scripts/uninstall.sh

@@ -0,0 +1,169 @@
+#!/bin/bash
+# Oh-My-ClaudeCode Uninstaller
+# Completely removes all OMC-installed files and configurations
+
+set -e
+
+BLUE='\033[0;34m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+echo -e "${BLUE}Oh-My-ClaudeCode Uninstaller${NC}"
+echo ""
+
+# Claude Code config directory (always ~/.claude)
+CLAUDE_CONFIG_DIR="$HOME/.claude"
+
+echo "This will remove ALL OMC components from:"
+echo "  $CLAUDE_CONFIG_DIR"
+echo ""
+echo "Components to be removed:"
+echo "  - Agents (architect, document-specialist, explore, etc. + legacy aliases)"
+echo "  - Commands (omc, ultrawork, plan, etc.)"
+echo "  - Skills (ultrawork, git-master, frontend-ui-ux)"
+echo "  - Hooks (keyword-detector, silent-auto-update, stop-continuation)"
+echo "  - Version and state files"
+echo "  - Hook configurations from settings.json"
+echo ""
+if [ -t 0 ]; then
+    read -p "Continue? (y/N) " -n 1 -r
+    echo
+else
+    # Try reading from terminal if script is piped
+    if [ -c /dev/tty ]; then
+        echo -n "Continue? (y/N) " >&2
+        read -n 1 -r < /dev/tty
+        echo
+    else
+        echo "Non-interactive mode detected or terminal not available. Uninstallation cancelled."
+        exit 1
+    fi
+fi
+
+if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+    echo "Cancelled."
+    exit 0
+fi
+
+# Remove agents
+echo -e "${BLUE}Removing agents...${NC}"
+rm -f "$CLAUDE_CONFIG_DIR/agents/architect.md"
+rm -f "$CLAUDE_CONFIG_DIR/agents/document-specialist.md"
+rm -f "$CLAUDE_CONFIG_DIR/agents/explore.md"
+rm -f "$CLAUDE_CONFIG_DIR/agents/designer.md"
+rm -f "$CLAUDE_CONFIG_DIR/agents/writer.md"
+rm -f "$CLAUDE_CONFIG_DIR/agents/vision.md"
+rm -f "$CLAUDE_CONFIG_DIR/agents/critic.md"
+rm -f "$CLAUDE_CONFIG_DIR/agents/analyst.md"
+rm -f "$CLAUDE_CONFIG_DIR/agents/executor.md"
+rm -f "$CLAUDE_CONFIG_DIR/agents/planner.md"
+
+# Remove commands
+echo -e "${BLUE}Removing commands...${NC}"
+rm -f "$CLAUDE_CONFIG_DIR/commands/coordinator.md"
+rm -f "$CLAUDE_CONFIG_DIR/commands/omc.md"
+rm -f "$CLAUDE_CONFIG_DIR/commands/ultrawork.md"
+rm -f "$CLAUDE_CONFIG_DIR/commands/deepsearch.md"
+rm -f "$CLAUDE_CONFIG_DIR/commands/analyze.md"
+rm -f "$CLAUDE_CONFIG_DIR/commands/plan.md"
+rm -f "$CLAUDE_CONFIG_DIR/commands/review.md"
+rm -f "$CLAUDE_CONFIG_DIR/commands/planner.md"
+rm -f "$CLAUDE_CONFIG_DIR/commands/orchestrator.md"
+rm -f "$CLAUDE_CONFIG_DIR/commands/update.md"
+
+# Remove skills
+echo -e "${BLUE}Removing skills...${NC}"
+rm -rf "$CLAUDE_CONFIG_DIR/skills/ultrawork"
+rm -rf "$CLAUDE_CONFIG_DIR/skills/git-master"
+rm -rf "$CLAUDE_CONFIG_DIR/skills/frontend-ui-ux"
+
+# Remove hooks
+echo -e "${BLUE}Removing hooks...${NC}"
+rm -f "$CLAUDE_CONFIG_DIR/hooks/keyword-detector.sh"
+rm -f "$CLAUDE_CONFIG_DIR/hooks/stop-continuation.sh"
+rm -f "$CLAUDE_CONFIG_DIR/hooks/silent-auto-update.sh"
+
+# Remove version, state, and config files
+echo -e "${BLUE}Removing state and config files...${NC}"
+rm -f "$CLAUDE_CONFIG_DIR/.omc-version.json"
+rm -f "$CLAUDE_CONFIG_DIR/.omc-silent-update.json"
+rm -f "$CLAUDE_CONFIG_DIR/.omc-update.log"
+rm -f "$CLAUDE_CONFIG_DIR/.omc-config.json"
+
+# Remove hook configurations from settings.json
+SETTINGS_FILE="$CLAUDE_CONFIG_DIR/settings.json"
+if [ -f "$SETTINGS_FILE" ] && command -v jq &> /dev/null; then
+    echo -e "${BLUE}Removing hook configurations from settings.json...${NC}"
+
+    # Create a backup
+    cp "$SETTINGS_FILE" "$SETTINGS_FILE.bak"
+
+    # Remove OMC-specific hooks from settings.json
+    # This removes hooks that reference omc hook scripts
+    TEMP_SETTINGS=$(mktemp)
+
+    # Use jq to filter out OMC hooks
+    jq '
+      # Remove OMC hooks from UserPromptSubmit
+      if .hooks.UserPromptSubmit then
+        .hooks.UserPromptSubmit |= map(
+          if .hooks then
+            .hooks |= map(select(.command | (contains("keyword-detector.sh") or contains("silent-auto-update.sh") or contains("stop-continuation.sh")) | not))
+          else .
+          end
+        ) | .hooks.UserPromptSubmit |= map(select(.hooks | length > 0))
+      else . end |
+
+      # Remove OMC hooks from Stop
+      if .hooks.Stop then
+        .hooks.Stop |= map(
+          if .hooks then
+            .hooks |= map(select(.command | (contains("keyword-detector.sh") or contains("silent-auto-update.sh") or contains("stop-continuation.sh")) | not))
+          else .
+          end
+        ) | .hooks.Stop |= map(select(.hooks | length > 0))
+      else . end |
+
+      # Clean up empty hooks sections
+      if .hooks.UserPromptSubmit == [] then del(.hooks.UserPromptSubmit) else . end |
+      if .hooks.Stop == [] then del(.hooks.Stop) else . end |
+      if .hooks == {} then del(.hooks) else . end
+    ' "$SETTINGS_FILE" > "$TEMP_SETTINGS" 2>/dev/null
+
+    if [ $? -eq 0 ] && [ -s "$TEMP_SETTINGS" ]; then
+        mv "$TEMP_SETTINGS" "$SETTINGS_FILE"
+        echo -e "${GREEN}✓ Removed OMC hooks from settings.json${NC}"
+        echo -e "${YELLOW}  Backup saved to: $SETTINGS_FILE.bak${NC}"
+    else
+        rm -f "$TEMP_SETTINGS"
+        echo -e "${YELLOW}⚠ Could not modify settings.json automatically${NC}"
+        echo "  Please manually remove OMC hooks from the 'hooks' section"
+    fi
+else
+    if [ -f "$SETTINGS_FILE" ]; then
+        echo -e "${YELLOW}⚠ jq not installed - cannot auto-remove hooks from settings.json${NC}"
+        echo "  Please manually edit $SETTINGS_FILE and remove the following hooks:"
+        echo "    - keyword-detector.sh"
+        echo "    - silent-auto-update.sh"
+        echo "    - stop-continuation.sh"
+    fi
+fi
+
+# Remove .omc directory if it exists (plans, notepads, drafts)
+if [ -d "$CLAUDE_CONFIG_DIR/../.omc" ] || [ -d ".omc" ]; then
+    echo -e "${YELLOW}Note: .omc directory (plans/notepads) was not removed.${NC}"
+    echo "  To remove project plans and notepads, run:"
+    echo "    rm -rf .omc"
+fi
+
+echo ""
+echo -e "${GREEN}Uninstallation complete!${NC}"
+echo ""
+echo -e "${YELLOW}Items NOT removed (manual cleanup if desired):${NC}"
+echo "  - CLAUDE.md: rm $CLAUDE_CONFIG_DIR/CLAUDE.md"
+echo "  - settings.json backup: rm $CLAUDE_CONFIG_DIR/settings.json.bak"
+echo ""
+echo "To verify complete removal, check:"
+echo "  ls -la $CLAUDE_CONFIG_DIR/"

package/scripts/verify-deliverables.mjs

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+
+/**
+ * OMC Deliverable Verification Hook (SubagentStop)
+ *
+ * Checks that completing agents actually produced their expected deliverables.
+ * A task can be marked "completed" with zero output files — this hook catches
+ * that gap by verifying file existence and minimum content.
+ *
+ * Deliverable requirements are loaded from (in priority order):
+ *   1. .omc/deliverables.json (project-specific overrides)
+ *   2. ${CLAUDE_PLUGIN_ROOT}/templates/deliverables.json (OMC defaults)
+ *
+ * This hook is ADVISORY (non-blocking). It returns additionalContext warnings
+ * when deliverables are missing, but never prevents the agent from stopping.
+ *
+ * Hook output:
+ *   - { continue: true, hookSpecificOutput: { additionalContext: "warning" } }
+ *     when deliverables are missing
+ *   - { continue: true, suppressOutput: true } when all checks pass or on error
+ */
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join, normalize, isAbsolute, resolve } from 'node:path';
+import { readStdin } from './lib/stdin.mjs';
+
+/**
+ * Sanitize a file path to prevent directory traversal attacks.
+ * Rejects absolute paths and paths containing '..' segments.
+ */
+function sanitizePath(filePath) {
+  const normalized = normalize(filePath);
+  if (isAbsolute(normalized) || normalized.startsWith('..')) {
+    return null;
+  }
+  return normalized;
+}
+
+/**
+ * Load deliverable requirements from project config or OMC defaults.
+ */
+function loadDeliverableConfig(directory) {
+  // Priority 1: Project-specific overrides
+  const projectConfig = join(directory, '.omc', 'deliverables.json');
+  if (existsSync(projectConfig)) {
+    try {
+      return JSON.parse(readFileSync(projectConfig, 'utf-8'));
+    } catch { /* fall through to defaults */ }
+  }
+
+  // Priority 2: OMC defaults
+  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
+  if (pluginRoot) {
+    const defaultConfig = join(pluginRoot, 'templates', 'deliverables.json');
+    if (existsSync(defaultConfig)) {
+      try {
+        return JSON.parse(readFileSync(defaultConfig, 'utf-8'));
+      } catch { /* fall through */ }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Determine the current team stage from OMC state.
+ */
+function detectStage(directory, sessionId) {
+  // Try session-scoped state first
+  if (sessionId) {
+    const sessionState = join(directory, '.omc', 'state', 'sessions', sessionId, 'team-state.json');
+    if (existsSync(sessionState)) {
+      try {
+        const data = JSON.parse(readFileSync(sessionState, 'utf-8'));
+        return data.current_phase || data.currentPhase || null;
+      } catch { /* fall through */ }
+    }
+  }
+
+  // Fallback to legacy state
+  const legacyState = join(directory, '.omc', 'state', 'team-state.json');
+  if (existsSync(legacyState)) {
+    try {
+      const data = JSON.parse(readFileSync(legacyState, 'utf-8'));
+      return data.current_phase || data.currentPhase || null;
+    } catch { /* fall through */ }
+  }
+
+  return null;
+}
+
+/**
+ * Check if a file exists and meets minimum size requirements.
+ */
+function checkFile(directory, filePath, minSize = 200) {
+  const safePath = sanitizePath(filePath);
+  if (!safePath) return { exists: false, path: filePath, reason: 'invalid path (traversal blocked)' };
+
+  const fullPath = join(directory, safePath);
+  if (!existsSync(fullPath)) {
+    return { exists: false, path: filePath, reason: 'file not found' };
+  }
+
+  try {
+    const stat = statSync(fullPath);
+    if (stat.size < minSize) {
+      return { exists: true, path: filePath, reason: `file too small (${stat.size} bytes, minimum ${minSize})` };
+    }
+  } catch {
+    return { exists: true, path: filePath, reason: 'cannot read file stats' };
+  }
+
+  return null; // passes
+}
+
+/**
+ * Check if a file contains required patterns (e.g., PASS/FAIL verdict).
+ */
+function checkPatterns(directory, filePath, patterns) {
+  if (!patterns || patterns.length === 0) return null;
+
+  const safePath = sanitizePath(filePath);
+  if (!safePath) return null;
+
+  const fullPath = join(directory, safePath);
+  if (!existsSync(fullPath)) return null; // file check handles this
+
+  try {
+    const content = readFileSync(fullPath, 'utf-8');
+    for (const pattern of patterns) {
+      const regex = new RegExp(pattern);
+      if (!regex.test(content)) {
+        return { path: filePath, reason: `missing required pattern: ${pattern}` };
+      }
+    }
+  } catch {
+    return { path: filePath, reason: 'cannot read file for pattern check' };
+  }
+
+  return null; // passes
+}
+
+async function main() {
+  try {
+    const input = await readStdin();
+    const data = JSON.parse(input);
+
+    const directory = data.cwd || data.directory || process.cwd();
+    const sessionId = data.session_id || data.sessionId || '';
+
+    // Load deliverable config
+    const config = loadDeliverableConfig(directory);
+    if (!config) {
+      // No config found — nothing to verify
+      console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+      return;
+    }
+
+    // Detect current stage
+    const stage = detectStage(directory, sessionId);
+    if (!stage) {
+      // No team stage detected — skip verification
+      console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+      return;
+    }
+
+    // Get requirements for this stage
+    const requirements = config[stage];
+    if (!requirements || !requirements.files || requirements.files.length === 0) {
+      // No deliverables required for this stage
+      console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+      return;
+    }
+
+    // Check each required file
+    const issues = [];
+    const minSize = requirements.minSize || 200;
+
+    for (const filePath of requirements.files) {
+      const fileIssue = checkFile(directory, filePath, minSize);
+      if (fileIssue) issues.push(fileIssue);
+
+      // Check required patterns if file exists
+      if (!fileIssue && requirements.requiredPatterns) {
+        const patternIssue = checkPatterns(directory, filePath, requirements.requiredPatterns);
+        if (patternIssue) issues.push(patternIssue);
+      }
+    }
+
+    // Check required sections in files
+    if (requirements.requiredSections) {
+      for (const filePath of requirements.files) {
+        const safePath = sanitizePath(filePath);
+        if (!safePath) continue;
+        const fullPath = join(directory, safePath);
+        if (existsSync(fullPath)) {
+          try {
+            const content = readFileSync(fullPath, 'utf-8');
+            for (const section of requirements.requiredSections) {
+              if (!content.includes(section)) {
+                issues.push({ path: filePath, reason: `missing required section: ${section}` });
+              }
+            }
+          } catch { /* skip */ }
+        }
+      }
+    }
+
+    if (issues.length === 0) {
+      // All checks pass
+      console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+      return;
+    }
+
+    // Build advisory warning
+    const warnings = issues.map(i => `  - ${i.path}: ${i.reason}`).join('\n');
+    const message = `[OMC] Deliverable verification for stage "${stage}":\n` +
+      `${issues.length} issue(s) found:\n${warnings}\n` +
+      `These deliverables may be expected by the next stage.`;
+
+    console.log(JSON.stringify({
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: 'SubagentStop',
+        additionalContext: message,
+      },
+    }));
+  } catch {
+    // On any error, allow the agent to stop (never block on hook failure)
+    console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+  }
+}
+
+main();

package/skills/AGENTS.md

@@ -0,0 +1,199 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-01-28 | Updated: 2026-02-19 -->
+
+# skills
+
+40 skill directories for workflow automation and specialized behaviors (42 runtime skill names including compatibility aliases).
+
+## Purpose
+
+Skills are reusable workflow templates that can be invoked via `/oh-my-claudecode:skill-name`. Each skill provides:
+- Structured prompts for specific workflows
+- Activation triggers (manual or automatic)
+- Integration with execution modes
+
+## Key Files
+
+### Execution Mode Skills
+
+| File | Skill | Purpose |
+|-----------|-------|---------|
+| `autopilot/SKILL.md` | autopilot | Full autonomous execution from idea to working code |
+| `ultrawork/SKILL.md` | ultrawork | Maximum parallel agent execution |
+| `ralph/SKILL.md` | ralph | Persistence until verified complete |
+| `ultrapilot/SKILL.md` | ultrapilot | Parallel autopilot with file ownership |
+| `team/SKILL.md` | team (+ `swarm` alias) | N coordinated agents with task claiming |
+| `pipeline/SKILL.md` | pipeline | Sequential agent chaining |
+| `ultraqa/SKILL.md` | ultraqa | QA cycling until goal met |
+
+### Planning Skills
+
+| File | Skill | Purpose |
+|-----------|-------|---------|
+| `plan/SKILL.md` | plan | Strategic planning with interview workflow |
+| `ralplan/SKILL.md` | ralplan | Iterative planning (Planner+Architect+Critic) |
+| `review/SKILL.md` | review | Review plan with Critic |
+| `analyze/SKILL.md` | analyze | Deep analysis and investigation |
+| `ralph-init/SKILL.md` | ralph-init | Initialize PRD for structured ralph |
+
+### Code Quality Skills
+
+| File | Skill | Purpose |
+|-----------|-------|---------|
+| `code-review/SKILL.md` | code-review | Comprehensive code review |
+| `security-review/SKILL.md` | security-review | Security vulnerability detection |
+| `tdd/SKILL.md` | tdd | Test-driven development workflow |
+| `build-fix/SKILL.md` | build-fix | Fix build and TypeScript errors |
+
+### Exploration Skills
+
+| File | Skill | Purpose |
+|-----------|-------|---------|
+| `deepsearch/SKILL.md` | deepsearch | Thorough codebase search |
+| `deepinit/SKILL.md` | deepinit | Generate hierarchical AGENTS.md |
+| `sciomc/SKILL.md` | sciomc | Parallel scientist orchestration |
+
+### Utility Skills
+
+| File | Skill | Purpose |
+|-----------|-------|---------|
+| `orchestrate/SKILL.md` | orchestrate | Core multi-agent orchestration (always active) |
+| `learner/SKILL.md` | learner | Extract reusable skill from session |
+| `note/SKILL.md` | note | Save notes for compaction resilience |
+| `cancel/SKILL.md` | cancel | Cancel any active OMC mode |
+| `hud/SKILL.md` | hud | Configure HUD display |
+| `doctor/SKILL.md` | doctor | Diagnose installation issues |
+| `omc-setup/SKILL.md` | omc-setup | One-time setup wizard |
+| `mcp-setup/SKILL.md` | mcp-setup | Configure MCP servers |
+| `help/SKILL.md` | help | Usage guide |
+| `skill/SKILL.md` | skill | Manage local skills |
+
+### Domain Skills
+
+| File | Skill | Purpose |
+|-----------|-------|---------|
+| `frontend-ui-ux/SKILL.md` | frontend-ui-ux | Designer-developer aesthetic |
+| `git-master/SKILL.md` | git-master | Git expertise, atomic commits |
+| `project-session-manager/SKILL.md` | project-session-manager (+ `psm` alias) | Isolated dev environments |
+| `writer-memory/SKILL.md` | writer-memory | Agentic memory for writers |
+| `release/SKILL.md` | release | Automated release workflow |
+
+## For AI Agents
+
+### Working In This Directory
+
+#### Skill Template Format
+
+```markdown
+---
+name: skill-name
+description: Brief description
+triggers:
+  - "keyword1"
+  - "keyword2"
+agent: executor  # Optional: which agent to use
+model: sonnet    # Optional: model override
+---
+
+# Skill Name
+
+## Purpose
+What this skill accomplishes.
+
+## Workflow
+1. Step one
+2. Step two
+3. Step three
+
+## Usage
+How to invoke this skill.
+
+## Configuration
+Any configurable options.
+```
+
+#### Skill Invocation
+
+```bash
+# Manual invocation
+/oh-my-claudecode:skill-name
+
+# With arguments
+/oh-my-claudecode:skill-name arg1 arg2
+
+# Auto-detected from keywords
+"autopilot build me a REST API"  # Triggers autopilot skill
+```
+
+#### Creating a New Skill
+
+1. Create `new-skill/SKILL.md` directory and file with YAML frontmatter
+2. Define purpose, workflow, and usage
+3. Add to skill registry (auto-detected from frontmatter)
+4. Optionally add activation triggers
+5. Create corresponding `commands/new-skill.md` file (mirror)
+6. Update `docs/REFERENCE.md` (Skills section, count)
+7. If execution mode skill, also create `src/hooks/new-skill/` hook
+
+### Common Patterns
+
+**Skill chaining:**
+```markdown
+## Workflow
+1. Invoke `explore` agent for context
+2. Invoke `architect` for analysis
+3. Invoke `executor` for implementation
+4. Invoke `qa-tester` for verification
+```
+
+**Conditional behavior:**
+```markdown
+## Workflow
+1. Check if tests exist
+   - If yes: Run tests first
+   - If no: Create test plan
+2. Proceed with implementation
+```
+
+### Testing Requirements
+
+- Skills are verified via integration tests
+- Test skill invocation with `/oh-my-claudecode:skill-name`
+- Verify trigger keywords activate correct skill
+- For git-related skills, follow `templates/rules/git-workflow.md`
+
+## Dependencies
+
+### Internal
+- Loaded by skill bridge (`scripts/build-skill-bridge.mjs`)
+- References agents from `agents/`
+- Uses hooks from `src/hooks/`
+
+### External
+None - pure markdown files.
+
+## Skill Categories
+
+| Category | Skills | Trigger Keywords |
+|----------|--------|------------------|
+| Execution | autopilot, ultrawork, ralph, ultrapilot, swarm, pipeline | "autopilot", "ulw", "ralph", "swarm", "eco" |
+| Planning | plan, ralplan, review, analyze, ralph-init | "plan this", "analyze" |
+| Quality | code-review, security-review, tdd, build-fix | "review", "security", "tdd" |
+| Exploration | deepsearch, deepinit, research | "search", "research" |
+| Utility | learner, note, cancel, hud, doctor, omc-setup, mcp-setup, help | "stop", "cancel" |
+| Domain | frontend-ui-ux, git-master, psm, writer-memory, release | UI context, git context |
+
+## Auto-Activation
+
+Some skills activate automatically based on context:
+
+| Skill | Auto-Trigger Condition |
+|-------|----------------------|
+| autopilot | "autopilot", "build me", "I want a" |
+| ultrawork | "ulw", "ultrawork" |
+| ralph | "ralph", "don't stop until" |
+| frontend-ui-ux | UI/component work detected |
+| git-master | Git operations detected |
+| cancel | "stop", "cancel", "abort" |
+
+<!-- MANUAL: -->

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: `Task(subagent_type="oh-my-claudecode: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, run the 3-step discovery: (1) `ToolSearch("mcp")`, (2) select the full name from results (e.g., `mcp__x__ask_codex`), (3) fall back to the equivalent Claude agent only if step 1 returns empty. Never use `ToolSearch("ask_codex")` as the primary search -- it can return false negatives even when MCP tools are present.
+- Use `ask_codex` with `agent_role: "architect"` as the preferred analysis route
+- Pass `context_files` with all relevant source files for grounded analysis
+- Use `Task(subagent_type="oh-my-claudecode: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}}