flow-discover

{{PREAMBLE}}

## Compaction-Resistant Contract

- Dispatch MUST go through background agents that call `${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh probe-single`; direct single-model research is not a valid substitute.
- Use the dynamic fleet from `build-fleet.sh`; the plugin can route across Codex, Gemini, Copilot, Qwen, OpenCode, Ollama, Perplexity, OpenRouter, Cursor Agent, and Claude depending on local availability.
- Before synthesis, run `${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh agent-summary` and use only providers reported as `ok`, `degraded`, or `timeout` with usable output.
- For `standard` and `deep` research, require at least 2 usable provider outputs unless fewer providers are installed; failed/rejected providers are reported as gaps, not cited as evidence.

## Pre-Discovery: Project Initialization

Before starting discovery:
1. Check if `.octo/` directory exists
2. If NOT exists: Call `./scripts/octo-state.sh init_project` to create it
3. Update `.octo/STATE.md`:
   - current_phase: 1
   - phase_position: "Discovery"
   - status: "in_progress"

```bash
# Check and initialize .octo/ state
if [[ ! -d ".octo" ]]; then
  echo "📁 Initializing .octo/ project state..."
  "${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" init_project
fi

# Update state for Discovery phase
"${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" update_state \
  --phase 1 \
  --position "Discovery" \
  --status "in_progress"
```

---

## Native Plan Mode Compatibility (v7.23.0+)

**IMPORTANT:** claude-octopus workflows are designed to persist across context clearing.

### Detecting Native Plan Mode

Check if native plan mode is active:

```bash
# Check for native plan mode markers
if [[ -n "${PLAN_MODE_ACTIVE}" ]] || claude-code plan status 2>/dev/null | grep -q "active"; then
    echo "⚠️  Native plan mode detected"
    echo ""
    echo "   Claude Octopus uses file-based state (.claude-octopus/)"
    echo "   State will persist across plan mode context clears"
    echo "   Multi-AI orchestration will continue normally"
    echo ""
fi
```

### State Persistence Across Context Clearing

**How it works:**
- Native plan mode may clear Claude's memory via `ExitPlanMode`
- claude-octopus state persists in `.claude-octopus/state.json`
- Each workflow phase reads prior state at startup
- Context is automatically restored from files

**No action required** - state management handles this automatically via STEP 3 in the execution contract.

---

## ⚠️ EXECUTION CONTRACT (MANDATORY - CANNOT SKIP)

This skill uses **ENFORCED execution mode**. You MUST follow this exact sequence.

### STEP 1: Detect Work Context (MANDATORY)

Analyze the user's prompt and project to determine context:

**Knowledge Context Indicators**:
- Business/strategy terms: "market", "ROI", "stakeholders", "strategy", "competitive", "business case"
- Research terms: "literature", "synthesis", "academic", "papers", "personas", "interviews"
- Deliverable terms: "presentation", "report", "PRD", "proposal", "executive summary"

**Dev Context Indicators**:
- Technical terms: "API", "endpoint", "database", "function", "implementation", "library"
- Action terms: "implement", "debug", "refactor", "build", "deploy", "code"

**Also check**: Does project have `package.json`, `Cargo.toml`, etc.? (suggests Dev Context)

**Capture context_type = "Dev" or "Knowledge"**

**DO NOT PROCEED TO STEP 2 until context determined.** Context type (Dev vs Knowledge) determines which provider prompts to use — wrong context produces irrelevant research that wastes provider credits.

---

### STEP 2: Display Visual Indicators (MANDATORY - BLOCKING)

**MANDATORY: You MUST use the Bash tool to run this provider check BEFORE displaying the banner. Do NOT skip it. Do NOT assume availability.**

```bash
bash "${HOME}/.claude-octopus/plugin/scripts/helpers/check-providers.sh"
```

**Use the ACTUAL results below. PROHIBITED: Showing only "🔵 Claude: Available ✓" without listing all providers.**

If `OCTO_ALLOWED_PROVIDERS` is set, treat it as the source of truth for which providers may participate. Providers filtered out by that allowlist are intentionally reported as unavailable; do not invoke or recommend them in the workflow.


**Display this banner BEFORE orchestrate.sh execution:**

**For Dev Context:**
```
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider research mode
🔍 [Dev] Discover Phase: [Brief description of technical research]

Provider Availability:
🔴 Codex CLI: ${codex_status}
🟡 Gemini CLI: ${gemini_status}
🟣 Perplexity: ${perplexity_status}
🔵 Claude: Available ✓ (Strategic synthesis)

💰 Estimated Cost: $0.01-0.08
⏱️  Estimated Time: 2-5 minutes
```

**For Knowledge Context:**
```
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider research mode
🔍 [Knowledge] Discover Phase: [Brief description of strategic research]

Provider Availability:
🔴 Codex CLI: ${codex_status}
🟡 Gemini CLI: ${gemini_status}
🟣 Perplexity: ${perplexity_status}
🔵 Claude: Available ✓ (Strategic synthesis)

💰 Estimated Cost: $0.01-0.08
⏱️  Estimated Time: 2-5 minutes
```

**DO NOT PROCEED TO STEP 3 until banner displayed.** The banner shows users which providers will run and what costs they'll incur — starting API calls without this visibility violates cost transparency.

---

### STEP 3: Read Prior State (MANDATORY - State Management)

**Before executing the workflow, read any prior context:**

```bash
# Initialize state if needed
"${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" init_state

# Set current workflow
"${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" set_current_workflow "flow-discover" "discover"

# Get prior decisions (if any)
prior_decisions=$("${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" get_decisions "all")

# Get context from previous phases
prior_context=$("${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" read_state | jq -r '.context')

# Display what you found (if any)
if [[ "$prior_decisions" != "[