flow-define

{{PREAMBLE}}

## Pre-Definition: State Check

Before starting definition:
1. Read `.octo/STATE.md` to verify Discover phase complete
2. Update STATE.md:
   - current_phase: 2
   - phase_position: "Definition"
   - status: "in_progress"

```bash
# Verify Discover phase is complete
if [[ -f ".octo/STATE.md" ]]; then
  discover_status=$("${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" get_phase_status 1)
  if [[ "$discover_status" != "complete" ]]; then
    echo "⚠️ Warning: Discover phase not marked complete. Consider running discovery first."
  fi
fi

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

---

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

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

### STEP 1: 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:**

```
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider definition mode
🎯 Define Phase: [Brief description of what you're defining/scoping]

Provider Availability:
🔴 Codex CLI: ${codex_status} - Technical requirements analysis
🟡 Gemini CLI: ${gemini_status} - Business context and constraints
🔵 Claude: Available ✓ - Consensus building and synthesis

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

**DO NOT PROCEED TO STEP 2 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 2: 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-define" "define"

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

# Get context from discover phase
discover_context=$("${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" get_context "discover")

# Display what you found (if any)
if [[ "$discover_context" != "null" ]]; then
  echo "📋 Building on discovery findings:"
  echo "  $discover_context"
fi

if [[ "$prior_decisions" != "[]" && "$prior_decisions" != "null" ]]; then
  echo "📋 Respecting prior decisions:"
  echo "$prior_decisions" | jq -r '.[] | "  - \(.decision) (\(.phase)): \(.rationale)"'
fi
```

**This provides context from:**
- Discovery phase research (if completed)
- Prior architectural decisions
- User vision captured earlier
- If **claude-mem** is installed, its MCP tools (`search`, `timeline`, `get_observations`) are available — use them to find past decisions on similar topics

**DO NOT PROCEED TO STEP 3 until state read.**

---

### STEP 3: Phase Discussion - Capture User Vision (MANDATORY - Context Gathering)

**Before executing expensive multi-AI orchestration, capture the user's vision to scope the work effectively.**

**Ask clarifying questions using AskUserQuestion:**

```
Use AskUserQuestion tool to ask:

1. **User Experience**
   Question: "How should users interact with this feature?"
   Header: "User Flow"
   Options:
   - label: "API-first (programmatic access)"
     description: "Build API endpoints first, UI later"
   - label: "UI-first (user-facing interface)"
     description: "Build user interface first, API supports it"
   - label: "Both simultaneously"
     description: "Develop API and UI in parallel"
   - label: "Not applicable"
     description: "This feature doesn't have a user interaction"

2. **Implementation Approach**
   Question: "What technical approach do you prefer?"
   Header: "Approach"
   Options:
   - label: "Fastest to market"
     description: "Prioritize speed, use existing libraries"
   - label: "Most maintainable"
     description: "Focus on clean architecture, may take longer"
   - label: "Best performance"
     description: "Optimize for speed and efficiency"
   - label: "Multi-LLM debate (Claude + Codex + Gemini)"
     description: "Three AI models debate the best approach — uses external API credits"

3. **Scope Boundaries**
   Question: "What's explicitly OUT of scope for this phase?"
   Header: "Out of Scope"
   Options:
   - label: "Testing and QA"
     description: "Focus on implementation, test later"
   - label: "Performance optimization"
     description: "Get it working first, optimize later"
   - label: "Edge cases"
     description: "Handle happy path only initially"
   - label: "Nothing excluded"
     description: "Everything is in scope"
   multiSelect: true
```

**If user selected "Multi-LLM debate (Claude + Codex + Gemini)" for approach:**
Before proceeding with orchestrate.sh, run a Multi-LLM debate to determine the technical approach:
```
/octo:debate --rounds 2 --debate-style collaborative "What is the best technical approach for [feature]? Consider: speed to market, maintainability, performance, and the existing codebase patterns."
```
Use the debate synthesis to set the approach context for the Define phase.

**After gathering answers, create context file:**

```bash
# Source context manager
source "${HOME}/.claude-octopus/plugin/scripts/context-manager.sh"

# Extract user