flow-define

What this skill does

> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex.
> Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands.
> Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it.
> For host tool equivalents, see `skills/blocks/codex-host-adapter.md`.


{{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 native shell command 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 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 native shell command tool:**

```bash
${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-vs-business perspective split that Codex and Gemini provide, producing requirements with blind spots
- ❌ Using direct analysis instead of orchestrate.sh
- ❌ Claiming you're "simulating" the workflow
- ❌ Proceedi