oh-my-claude-sisyphus 3.8.16 → 3.9.0

package/scripts/keyword-detector.mjs

@@ -73,10 +73,20 @@ function extractPrompt(input) {
   }
 }
 
-// Remove code blocks to prevent false positives
-function removeCodeBlocks(text) {
+// Sanitize text to prevent false positives from code blocks, XML tags, URLs, and file paths
+function sanitizeForKeywordDetection(text) {
   return text
+    // 1. Strip XML-style tag blocks: <tag-name ...>...</tag-name> (multi-line, greedy on tag name)
+    .replace(/<(\w[\w-]*)[\s>][\s\S]*?<\/\1>/g, '')
+    // 2. Strip self-closing XML tags: <tag-name />, <tag-name attr="val" />
+    .replace(/<\w[\w-]*(?:\s[^>]*)?\s*\/>/g, '')
+    // 3. Strip URLs: http://... or https://... up to whitespace
+    .replace(/https?:\/\/[^\s)>\]]+/g, '')
+    // 4. Strip file paths: /foo/bar/baz or foo/bar/baz (using lookbehind to avoid consuming leading char)
+    .replace(/(?<=^|[\s"'`(])(?:\/)?(?:[\w.-]+\/)+[\w.-]+/gm, '')
+    // 5. Strip markdown code blocks (existing)
     .replace(/```[\s\S]*?```/g, '')
+    // 6. Strip inline code (existing)
     .replace(/`[^`]+`/g, '');
 }
 
@@ -225,7 +235,7 @@ async function main() {
       return;
     }
 
-    const cleanPrompt = removeCodeBlocks(prompt).toLowerCase();
+    const cleanPrompt = sanitizeForKeywordDetection(prompt).toLowerCase();
 
     // Collect all matching keywords
     const matches = [];

package/skills/deep-executor/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: deep-executor
+description: Deep executor mode for complex goal-oriented tasks
+---
+
+# Deep Executor Skill
+
+Activate autonomous deep work mode for complex tasks.
+
+## Overview
+
+Deep Executor is the autonomous deep worker agent. When activated, it:
+
+1. **Explores First**: Uses its own tools (Glob, Grep, Read, ast_grep_search) to thoroughly understand the problem
+2. **Plans Strategically**: Creates execution plan based on exploration
+3. **Executes Directly**: Does all work itself using Edit, Write, Bash, ast_grep_replace
+4. **Verifies Everything**: Runs builds, tests, and diagnostics before claiming completion
+5. **Completes 100%**: Guarantees full completion with evidence
+
+## Usage
+
+```
+/oh-my-claudecode:deep-executor <your complex task>
+```
+
+Or use magic keywords:
+- "deep-executor: ..."
+- "deep work: ..."
+- "forge: ..."
+
+## When to Use
+
+| Situation | Use Deep Executor? |
+|-----------|-----------------|
+| Complex multi-file refactoring | YES |
+| Unclear implementation path | YES |
+| Need guaranteed completion | YES |
+| Simple single-file fix | NO (use executor) |
+| Quick code search | NO (use explore) |
+| Cost-sensitive work | NO (use ecomode) |
+
+## Activation
+
+This skill spawns the `deep-executor` agent via:
+
+```
+Task(subagent_type="oh-my-claudecode:deep-executor", model="opus", prompt="{{PROMPT}}")
+```
+
+The agent handles all exploration and execution internally. No sub-agents are spawned.

package/skills/ecomode/SKILL.md

@@ -1,141 +1,96 @@
 ---
 name: ecomode
-description: Token-efficient parallel execution mode using Haiku and Sonnet agents
+description: Token-efficient model routing modifier
 ---
 
 # Ecomode Skill
 
-Activates token-efficient parallel execution for pro-plan users who prioritize cost efficiency.
+Token-efficient model routing. This is a **MODIFIER**, not a standalone execution mode.
 
-## When Activated
+## What Ecomode Does
 
-This skill enhances Claude's capabilities by:
+Overrides default model selection to prefer cheaper tiers:
 
-1. **Parallel Execution**: Running multiple agents simultaneously for independent tasks
-2. **Token-Conscious Routing**: Preferring Haiku and Sonnet agents, avoiding Opus
-3. **Background Operations**: Using `run_in_background: true` for long operations
-4. **Persistence Enforcement**: Never stopping until all tasks are verified complete
-5. **Cost Optimization**: Minimizing token usage while maintaining quality
+| 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 |
 
-## Ecomode Routing Rules (CRITICAL)
+## What Ecomode Does NOT Do
 
-**ALWAYS prefer lower tiers. Only escalate when task genuinely requires it.**
-
-| Decision | Rule |
-|----------|------|
-| DEFAULT | Use LOW tier (Haiku) for all tasks |
-| UPGRADE | Use MEDIUM (Sonnet) only when task complexity warrants |
-| AVOID | HIGH tier (Opus) - only use for planning/critique if explicitly essential |
+- **Persistence**: Use `ralph` for "don't stop until done"
+- **Parallel Execution**: Use `ultrawork` for parallel agents
+- **Delegation Enforcement**: Always active via core orchestration
 
-## Smart Model Routing (PREFER LOW TIER)
+## Combining Ecomode with Other Modes
 
-**Choose tier based on task complexity: LOW (haiku) preferred → MEDIUM (sonnet) fallback → HIGH (opus) AVOID**
+Ecomode is a modifier that combines with execution modes:
 
-### Agent Routing Table
+| Combination | Effect |
+|-------------|--------|
+| `eco ralph` | Ralph loop with cheaper agents |
+| `eco ultrawork` | Parallel execution with cheaper agents |
+| `eco autopilot` | Full autonomous with cost optimization |
 
-| Domain | PREFERRED (Haiku) | FALLBACK (Sonnet) | AVOID (Opus) |
-|--------|-------------------|-------------------|--------------|
-| **Analysis** | `architect-low` | `architect-medium` | ~~`architect`~~ |
-| **Execution** | `executor-low` | `executor` | ~~`executor-high`~~ |
-| **Search** | `explore` | `explore-medium` | ~~`explore-high`~~ |
-| **Research** | `researcher-low` | `researcher` | - |
-| **Frontend** | `designer-low` | `designer` | ~~`designer-high`~~ |
-| **Docs** | `writer` | - | - |
-| **Visual** | - | `vision` | - |
-| **Planning** | - | - | `planner` (if essential) |
-| **Critique** | - | - | `critic` (if essential) |
-| **Testing** | - | `qa-tester` | ~~`qa-tester-high`~~ |
-| **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`~~ |
-| **Data Science** | `scientist-low` | `scientist` | ~~`scientist-high`~~ |
+## Ecomode Routing Rules
 
-### Tier Selection Guide (Token-Conscious)
-
-| Task Complexity | Tier | Examples |
-|-----------------|------|----------|
-| Simple lookups | LOW | "What does this function return?", "Find where X is defined" |
-| Standard work | LOW first, MEDIUM if fails | "Add error handling", "Implement this feature" |
-| Complex analysis | MEDIUM | "Debug this issue", "Refactor this module" |
-| Planning only | HIGH (if essential) | "Design architecture for new system" |
+**ALWAYS prefer lower tiers. Only escalate when task genuinely requires it.**
 
-### Routing Examples
+| Decision | Rule |
+|----------|------|
+| DEFAULT | Use LOW tier (Haiku) for all tasks |
+| UPGRADE | Use MEDIUM (Sonnet) only when task complexity warrants |
+| AVOID | HIGH tier (Opus) - only for planning/critique if essential |
 
-**CRITICAL: Always pass `model` parameter explicitly - Claude Code does NOT auto-apply models from agent definitions!**
+## Agent Selection in Ecomode
 
+**FIRST ACTION:** Before delegating any work, read the agent reference file:
 ```
-// Simple question → LOW tier (DEFAULT)
-Task(subagent_type="oh-my-claudecode:architect-low", model="haiku", prompt="What does this function return?")
-
-// Standard implementation → TRY LOW first
-Task(subagent_type="oh-my-claudecode:executor-low", model="haiku", prompt="Add validation to login form")
-
-// If LOW fails, escalate to MEDIUM
-Task(subagent_type="oh-my-claudecode:executor", model="sonnet", prompt="Add error handling to login")
-
-// File lookup → ALWAYS LOW
-Task(subagent_type="oh-my-claudecode:explore", model="haiku", prompt="Find where UserService is defined")
-
-// Only use MEDIUM for complex patterns
-Task(subagent_type="oh-my-claudecode:explore-medium", model="sonnet", prompt="Find all authentication patterns in the codebase")
+Read file: docs/shared/agent-tiers.md
 ```
+This provides the complete agent tier matrix, MCP tool assignments, and selection guidance.
 
-## DELEGATION ENFORCEMENT (CRITICAL)
-
-**YOU ARE AN ORCHESTRATOR, NOT AN IMPLEMENTER.**
-
-| Action | YOU Do | DELEGATE |
-|--------|--------|----------|
-| Read files for context | ✓ | |
-| Track progress (TODO) | ✓ | |
-| Spawn parallel agents | ✓ | |
-| **ANY code change** | ✗ NEVER | executor-low/executor |
-| **UI work** | ✗ NEVER | designer-low/designer |
-| **Docs** | ✗ NEVER | writer |
+**Ecomode preference order:**
 
-**Path Exception**: Only write to `.omc/`, `.claude/`, `CLAUDE.md`, `AGENTS.md`
+```
+// PREFERRED - Use for most tasks
+Task(subagent_type="oh-my-claudecode:executor-low", model="haiku", prompt="...")
+Task(subagent_type="oh-my-claudecode:explore", model="haiku", prompt="...")
+Task(subagent_type="oh-my-claudecode:architect-low", model="haiku", prompt="...")
 
-## Background Execution Rules
+// FALLBACK - Only if LOW fails
+Task(subagent_type="oh-my-claudecode:executor", model="sonnet", prompt="...")
+Task(subagent_type="oh-my-claudecode:architect-medium", model="sonnet", prompt="...")
 
-**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
+// AVOID - Only for planning/critique if essential
+Task(subagent_type="oh-my-claudecode:planner", model="opus", prompt="...")
+```
 
-**Run Blocking** (foreground):
-- Quick status checks: git status, ls, pwd
-- File reads (NOT edits - delegate edits to executor-low)
-- Simple commands
+## Delegation Enforcement
 
-## Verification Checklist
+Ecomode maintains all delegation rules from core protocol with cost-optimized routing:
 
-Before stopping, verify:
-- [ ] TODO LIST: Zero pending/in_progress tasks
-- [ ] FUNCTIONALITY: All requested features work
-- [ ] TESTS: All tests pass (if applicable)
-- [ ] ERRORS: Zero unaddressed errors
+| Action | Delegate To | Model |
+|--------|-------------|-------|
+| Code changes | executor-low / executor | haiku / sonnet |
+| Analysis | architect-low | haiku |
+| Search | explore | haiku |
+| Documentation | writer | haiku |
 
-**If ANY checkbox is unchecked, CONTINUE WORKING.**
+### Background Execution
+Long-running commands (install, build, test) run in background. Maximum 5 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. **Avoid opus agents** unless the task genuinely requires deep reasoning
-5. **Use writer (haiku)** for all documentation tasks
-
-## STATE CLEANUP ON COMPLETION
+4. **Use writer (haiku)** for all documentation tasks
+5. **Avoid opus agents** unless the task genuinely requires deep reasoning
 
-**IMPORTANT: Delete state files on completion - do NOT just set `active: false`**
+## State Management
 
-When ecomode completes (all verification passes):
-
-```bash
-# Delete ecomode state files
-rm -f .omc/state/ecomode-state.json
-```
+Ecomode state is tracked in `.omc/state/ecomode-state.json`.
 
-This ensures clean state for future sessions. Stale state files with `active: false` should not be left behind.
+When work is complete, run `/oh-my-claudecode:cancel` for clean state cleanup.

package/skills/omc-setup/SKILL.md

@@ -146,23 +146,81 @@ mkdir -p .claude && echo ".claude directory ready"
 ### Download Fresh CLAUDE.md
 
 ```bash
+# Define target path
+TARGET_PATH=".claude/CLAUDE.md"
+
 # Extract old version before download
-OLD_VERSION=$(grep -m1 "^# oh-my-claudecode" .claude/CLAUDE.md 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "none")
+OLD_VERSION=$(grep -m1 "^# oh-my-claudecode" "$TARGET_PATH" 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "none")
 
-# Backup existing CLAUDE.md before overwriting (if it exists)
-if [ -f ".claude/CLAUDE.md" ]; then
-  BACKUP_DATE=$(date +%Y-%m-%d)
-  BACKUP_PATH=".claude/CLAUDE.md.backup.${BACKUP_DATE}"
-  cp .claude/CLAUDE.md "$BACKUP_PATH"
+# Backup existing
+if [ -f "$TARGET_PATH" ]; then
+  BACKUP_DATE=$(date +%Y-%m-%d_%H%M%S)
+  BACKUP_PATH="${TARGET_PATH}.backup.${BACKUP_DATE}"
+  cp "$TARGET_PATH" "$BACKUP_PATH"
   echo "Backed up existing CLAUDE.md to $BACKUP_PATH"
 fi
 
-# Download fresh CLAUDE.md from GitHub
-curl -fsSL "https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claudecode/main/docs/CLAUDE.md" -o .claude/CLAUDE.md && \
-echo "Downloaded CLAUDE.md to .claude/CLAUDE.md"
+# Download fresh OMC content to temp file
+TEMP_OMC=$(mktemp /tmp/omc-claude-XXXXXX.md)
+trap 'rm -f "$TEMP_OMC"' EXIT
+curl -fsSL "https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claudecode/main/docs/CLAUDE.md" -o "$TEMP_OMC"
+
+if [ ! -s "$TEMP_OMC" ]; then
+  echo "ERROR: Failed to download CLAUDE.md. Aborting."
+  rm -f "$TEMP_OMC"
+  return 1
+fi
+
+# Strip existing markers from downloaded content (idempotency)
+if grep -q '<!-- OMC:START -->' "$TEMP_OMC"; then
+  # Extract content between markers
+  sed -n '/<!-- OMC:START -->/,/<!-- OMC:END -->/{//!p}' "$TEMP_OMC" > "${TEMP_OMC}.clean"
+  mv "${TEMP_OMC}.clean" "$TEMP_OMC"
+fi
+
+if [ ! -f "$TARGET_PATH" ]; then
+  # Fresh install: wrap in markers
+  {
+    echo '<!-- OMC:START -->'
+    cat "$TEMP_OMC"
+    echo '<!-- OMC:END -->'
+  } > "$TARGET_PATH"
+  rm -f "$TEMP_OMC"
+  echo "Installed CLAUDE.md (fresh)"
+else
+  # Merge: preserve user content outside OMC markers
+  if grep -q '<!-- OMC:START -->' "$TARGET_PATH"; then
+    # Has markers: replace OMC section, keep user content
+    BEFORE_OMC=$(sed -n '1,/<!-- OMC:START -->/{ /<!-- OMC:START -->/!p }' "$TARGET_PATH")
+    AFTER_OMC=$(sed -n '/<!-- OMC:END -->/,${  /<!-- OMC:END -->/!p }' "$TARGET_PATH")
+    {
+      [ -n "$BEFORE_OMC" ] && printf '%s\n' "$BEFORE_OMC"
+      echo '<!-- OMC:START -->'
+      cat "$TEMP_OMC"
+      echo '<!-- OMC:END -->'
+      [ -n "$AFTER_OMC" ] && printf '%s\n' "$AFTER_OMC"
+    } > "${TARGET_PATH}.tmp"
+    mv "${TARGET_PATH}.tmp" "$TARGET_PATH"
+    echo "Updated OMC section (user customizations preserved)"
+  else
+    # No markers: wrap new content in markers, append old content as user section
+    OLD_CONTENT=$(cat "$TARGET_PATH")
+    {
+      echo '<!-- OMC:START -->'
+      cat "$TEMP_OMC"
+      echo '<!-- OMC:END -->'
+      echo ""
+      echo "<!-- User customizations (migrated from previous CLAUDE.md) -->"
+      printf '%s\n' "$OLD_CONTENT"
+    } > "${TARGET_PATH}.tmp"
+    mv "${TARGET_PATH}.tmp" "$TARGET_PATH"
+    echo "Migrated existing CLAUDE.md (added OMC markers, preserved old content)"
+  fi
+  rm -f "$TEMP_OMC"
+fi
 
 # Extract new version and report
-NEW_VERSION=$(grep -m1 "^# oh-my-claudecode" .claude/CLAUDE.md 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "unknown")
+NEW_VERSION=$(grep -m1 "^# oh-my-claudecode" "$TARGET_PATH" 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "unknown")
 if [ "$OLD_VERSION" = "none" ]; then
   echo "Installed CLAUDE.md: $NEW_VERSION"
 elif [ "$OLD_VERSION" = "$NEW_VERSION" ]; then
@@ -227,23 +285,81 @@ Do not continue to HUD setup or other steps.
 ### Download Fresh CLAUDE.md
 
 ```bash
+# Define target path
+TARGET_PATH="$HOME/.claude/CLAUDE.md"
+
 # Extract old version before download
-OLD_VERSION=$(grep -m1 "^# oh-my-claudecode" ~/.claude/CLAUDE.md 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "none")
+OLD_VERSION=$(grep -m1 "^# oh-my-claudecode" "$TARGET_PATH" 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "none")
 
-# Backup existing CLAUDE.md before overwriting (if it exists)
-if [ -f "$HOME/.claude/CLAUDE.md" ]; then
-  BACKUP_DATE=$(date +%Y-%m-%d)
-  BACKUP_PATH="$HOME/.claude/CLAUDE.md.backup.${BACKUP_DATE}"
-  cp "$HOME/.claude/CLAUDE.md" "$BACKUP_PATH"
+# Backup existing
+if [ -f "$TARGET_PATH" ]; then
+  BACKUP_DATE=$(date +%Y-%m-%d_%H%M%S)
+  BACKUP_PATH="${TARGET_PATH}.backup.${BACKUP_DATE}"
+  cp "$TARGET_PATH" "$BACKUP_PATH"
   echo "Backed up existing CLAUDE.md to $BACKUP_PATH"
 fi
 
-# Download fresh CLAUDE.md to global config
-curl -fsSL "https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claudecode/main/docs/CLAUDE.md" -o ~/.claude/CLAUDE.md && \
-echo "Downloaded CLAUDE.md to ~/.claude/CLAUDE.md"
+# Download fresh OMC content to temp file
+TEMP_OMC=$(mktemp /tmp/omc-claude-XXXXXX.md)
+trap 'rm -f "$TEMP_OMC"' EXIT
+curl -fsSL "https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claudecode/main/docs/CLAUDE.md" -o "$TEMP_OMC"
+
+if [ ! -s "$TEMP_OMC" ]; then
+  echo "ERROR: Failed to download CLAUDE.md. Aborting."
+  rm -f "$TEMP_OMC"
+  return 1
+fi
+
+# Strip existing markers from downloaded content (idempotency)
+if grep -q '<!-- OMC:START -->' "$TEMP_OMC"; then
+  # Extract content between markers
+  sed -n '/<!-- OMC:START -->/,/<!-- OMC:END -->/{//!p}' "$TEMP_OMC" > "${TEMP_OMC}.clean"
+  mv "${TEMP_OMC}.clean" "$TEMP_OMC"
+fi
+
+if [ ! -f "$TARGET_PATH" ]; then
+  # Fresh install: wrap in markers
+  {
+    echo '<!-- OMC:START -->'
+    cat "$TEMP_OMC"
+    echo '<!-- OMC:END -->'
+  } > "$TARGET_PATH"
+  rm -f "$TEMP_OMC"
+  echo "Installed CLAUDE.md (fresh)"
+else
+  # Merge: preserve user content outside OMC markers
+  if grep -q '<!-- OMC:START -->' "$TARGET_PATH"; then
+    # Has markers: replace OMC section, keep user content
+    BEFORE_OMC=$(sed -n '1,/<!-- OMC:START -->/{ /<!-- OMC:START -->/!p }' "$TARGET_PATH")
+    AFTER_OMC=$(sed -n '/<!-- OMC:END -->/,${  /<!-- OMC:END -->/!p }' "$TARGET_PATH")
+    {
+      [ -n "$BEFORE_OMC" ] && printf '%s\n' "$BEFORE_OMC"
+      echo '<!-- OMC:START -->'
+      cat "$TEMP_OMC"
+      echo '<!-- OMC:END -->'
+      [ -n "$AFTER_OMC" ] && printf '%s\n' "$AFTER_OMC"
+    } > "${TARGET_PATH}.tmp"
+    mv "${TARGET_PATH}.tmp" "$TARGET_PATH"
+    echo "Updated OMC section (user customizations preserved)"
+  else
+    # No markers: wrap new content in markers, append old content as user section
+    OLD_CONTENT=$(cat "$TARGET_PATH")
+    {
+      echo '<!-- OMC:START -->'
+      cat "$TEMP_OMC"
+      echo '<!-- OMC:END -->'
+      echo ""
+      echo "<!-- User customizations (migrated from previous CLAUDE.md) -->"
+      printf '%s\n' "$OLD_CONTENT"
+    } > "${TARGET_PATH}.tmp"
+    mv "${TARGET_PATH}.tmp" "$TARGET_PATH"
+    echo "Migrated existing CLAUDE.md (added OMC markers, preserved old content)"
+  fi
+  rm -f "$TEMP_OMC"
+fi
 
 # Extract new version and report
-NEW_VERSION=$(grep -m1 "^# oh-my-claudecode" ~/.claude/CLAUDE.md 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "unknown")
+NEW_VERSION=$(grep -m1 "^# oh-my-claudecode" "$TARGET_PATH" 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "unknown")
 if [ "$OLD_VERSION" = "none" ]; then
   echo "Installed CLAUDE.md: $NEW_VERSION"
 elif [ "$OLD_VERSION" = "$NEW_VERSION" ]; then
@@ -456,6 +572,67 @@ All functionality is available through the plugin system:
 
 Skip this step - the plugin provides all features.
 
+## Step 3.8.5: Select Task Management Tool
+
+First, detect available task tools:
+
+```bash
+# Detect beads (bd)
+BD_VERSION=""
+if command -v bd &>/dev/null; then
+  BD_VERSION=$(bd --version 2>/dev/null | head -1 || echo "installed")
+fi
+
+# Detect beads-rust (br)
+BR_VERSION=""
+if command -v br &>/dev/null; then
+  BR_VERSION=$(br --version 2>/dev/null | head -1 || echo "installed")
+fi
+
+# Report findings
+if [ -n "$BD_VERSION" ]; then
+  echo "Found beads (bd): $BD_VERSION"
+fi
+if [ -n "$BR_VERSION" ]; then
+  echo "Found beads-rust (br): $BR_VERSION"
+fi
+if [ -z "$BD_VERSION" ] && [ -z "$BR_VERSION" ]; then
+  echo "No external task tools found. Using built-in Tasks."
+fi
+```
+
+If **neither** beads nor beads-rust is detected, skip this step (default to built-in).
+
+If beads or beads-rust is detected, use AskUserQuestion:
+
+**Question:** "Which task management tool should I use for tracking work?"
+
+**Options:**
+1. **Built-in Tasks (default)** - Use Claude Code's native TaskCreate/TodoWrite. Tasks are session-only.
+2. **Beads (bd)** - Git-backed persistent tasks. Survives across sessions. [Only if detected]
+3. **Beads-Rust (br)** - Lightweight Rust port of beads. [Only if detected]
+
+(Only show options 2/3 if the corresponding tool is detected)
+
+Store the preference:
+
+```bash
+CONFIG_FILE="$HOME/.claude/.omc-config.json"
+mkdir -p "$(dirname "$CONFIG_FILE")"
+
+if [ -f "$CONFIG_FILE" ]; then
+  EXISTING=$(cat "$CONFIG_FILE")
+else
+  EXISTING='{}'
+fi
+
+# USER_CHOICE is "builtin", "beads", or "beads-rust" based on user selection
+echo "$EXISTING" | jq --arg tool "USER_CHOICE" '. + {taskTool: $tool, taskToolConfig: {injectInstructions: true, useMcp: false}}' > "$CONFIG_FILE"
+echo "Task tool set to: USER_CHOICE"
+```
+
+**Note:** The beads context instructions will be injected automatically on the next session start. No restart is needed for config to take effect.
+
 ## Step 4: Verify Plugin Installation
 
 ```bash

package/skills/plan/SKILL.md

@@ -17,6 +17,20 @@ You guide users through planning by:
 
 ## Planning Modes
 
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| interview | Default | Interactive requirements gathering with adaptive exploration |
+| direct | --direct, detailed request | Skip interview, generate plan directly |
+| consensus | --consensus, "ralplan" | Planner → Architect → Critic loop until consensus |
+| review | --review | Critic review of existing plan |
+
+### Review Mode
+
+When `--review` is specified or user says "review this plan":
+1. Read the plan file from `.omc/plans/`
+2. Spawn Critic agent to review
+3. Return verdict (OKAY or REJECT with improvements)
+
 ### Auto-Detection: Interview vs Direct Planning
 
 **Interview Mode** (when request is BROAD):
@@ -53,6 +67,54 @@ Ask clarifying questions about: Goals, Constraints, Context, Risks, Preferences
 
 **When plain text is OK:** Questions needing specific values (port numbers, names) or follow-up clarifications.
 
+## Adaptive Context Gathering (CRITICAL)
+
+Before asking ANY question, classify it:
+
+### Question Classification
+
+| Type | Examples | Action |
+|------|----------|--------|
+| **Codebase Fact** | "What patterns exist?", "Where is X implemented?" | Explore first, DON'T ask user |
+| **User Preference** | "Priority?", "Timeline?", "Risk tolerance?" | Ask user via AskUserQuestion |
+| **Scope Decision** | "Include feature Y?" | Ask user |
+| **Requirement** | "Performance constraints?" | Ask user |
+
+### Adaptive Flow
+
+1. Generate interview question
+2. Classify: Is this a codebase fact or user preference?
+3. If **CODEBASE FACT**:
+   a. Spawn `explore` agent (haiku, 30s timeout)
+   b. Query: focused on the specific fact needed
+   c. Use findings to inform next question or skip question entirely
+4. If **USER PREFERENCE**:
+   a. Use AskUserQuestion tool with options
+   b. Wait for response
+5. Repeat for next question
+
+### Exploration Integration
+
+When context is gathered via explore agent:
+- **DO NOT** ask "What patterns does the codebase use?"
+- **DO** say "I see the codebase uses [pattern X]. Would you like to follow this pattern or try something different?"
+
+### Example Adaptive Interview
+
+**Without Adaptive (BAD):**
+```
+Planner: "Where is authentication implemented in your codebase?"
+User: "Uh, somewhere in src/auth I think?"
+```
+
+**With Adaptive (GOOD):**
+```
+Planner: [spawns explore agent: "find authentication implementation"]
+Planner: [receives: "Auth is in src/auth/ using JWT with passport.js"]
+Planner: "I see you're using JWT authentication with passport.js in src/auth/.
+         For this new feature, should we extend the existing auth or add a separate auth flow?"
+```
+
 **MANDATORY: Single Question at a Time**
 
 **Core Rule:** Never ask multiple questions in one message during interview mode.