flow-define

{{PREAMBLE}}

Pre-Definition: State Check

Before starting definition:

1. Read .octo/STATE.md to verify Discover phase complete
2. Update STATE.md:
3. current_phase: 2
4. phase_position: "Definition"
5. status: "in_progress"

# 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 "${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: [Available ✓ / Not installed ✗] - Technical requirements analysis
🟡 Gemini CLI: [Available ✓ / Not installed ✗] - Business context and constraints
🧭 Antigravity CLI: [Available ✓ / Not installed ✗] - Additional external-model challenge
🔵 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:

# 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 + available providers)"
     description: "Multiple AI models debate the best approach — may use external provider credits or subscriptions"

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 + available providers)" 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:

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

# Extract user answers from AskUserQuestion results
user_flow="[Answer from question 1]"
approach="[Answer from question 2]"
out_of_scope="[Answer from question 3]"

# Create context file with user vision
create_templated_context \
  "define" \
  "$(echo "$USER_REQUEST" | head -c 50)..." \
  "User wants: $user_flow approach with $approach priority" \
  "$approach" \
  "Implementation of requested feature" \
  "$out_of_scope"

echo "📋 Context captured and saved to .claude-octopus/context/define-context.md"

This context will be used to:

• Scope the multi-AI research (discover phase)
• Focus the requirements definition (define phase)
• Guide implementation decisions (develop phase)
• Validate against user expectations (deliver phase)

DO NOT PROCEED TO STEP 4 until context captured. User vision (UX approach, priorities, out-of-scope items) scopes the multi-AI research — without it, providers research too broadly and the definition misses the user's actual intent.

STEP 4: Execute orchestrate.sh define (MANDATORY - Use Bash Tool)

You MUST execute this command via the Bash tool:

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh define "<user's clarification request>"

CRITICAL: You are PROHIBITED from:

• ❌ Defining requirements directly without calling orchestrate.sh — single-model analysis misses the technical, business, and external-model perspective split that provider fanout supplies, producing requirements with blind spots
• ❌ Using direct analysis instead of orchestrate.sh
• ❌ Claiming you're "simulating" the workflow
• ❌ Proceeding to Step 3 without running this command

You MUST use the Bash tool to invoke orchestrate.sh.

What Users See During Execution (v7.16.0+)

If running in Claude Code v2.1.16+, users will see real-time progress indicators in the task spi