Flow Discover

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}}

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, Antigravity, 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: Optional Project Persistence

Workflow state is stored in the host workspace by default. Only create the project-local .octo/ lifecycle artifacts when the user explicitly opts in by setting OCTOPUS_PROJECT_PERSISTENCE=true.

if [[ "${OCTOPUS_PROJECT_PERSISTENCE:-false}" == "true" ]]; then
  if [[ ! -d ".octo" ]]; then
    echo "📁 Initializing opt-in .octo/ project state..."
    if ! "${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" init_project; then
      echo "Discover incomplete: could not initialize opt-in project state." >&2
      exit 1
    fi
  fi
  if ! "${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" update_state \
      --phase 1 \
      --position "Discovery" \
      --status "in_progress"; then
    echo "Discover incomplete: could not persist in-progress state." >&2
    exit 1
  fi
fi

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:

# 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 "   Resolve Claude Octopus workflow state with: octopus state-path"
    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 workflow state persists in the host workspace, namespaced by project; resolve its exact path with state-manager.sh state_path
• 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 native shell command 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:

For Dev Context:

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

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

💰 Estimated Cost: 0.01-0.08 USD
⏱️  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}
🟡 Antigravity CLI: ${agy_status}
🧭 Antigravity CLI: ${agy_status}
🟣 Perplexity: ${perplexity_status}
🔵 Claude: Available ✓ (Strategic synthesis)

💰 Estimated Cost: 0.01-0.08 USD
⏱️  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:

# 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" != "[]" && "$prior_decisions" != "null" ]]; then
  echo "📋 Building on prior decisions:"
  echo "$prior_decisions" | jq -r '.[] | "  - \(.decision) (\(.phase)): \(.rationale)"'
fi

This provides context from:

• Prior workflow phases (if resuming a session)
• Architectural decisions already made
• User vision captured in earlier phases
• If claude-mem is installed, its MCP tools (search, timeline, get_observations) are available — use them to check for relevant past session context before launching research agents

DO NOT PROCEED TO STEP 4 until state read.

STEP 3.5: Parse Intensity & Build Agent Fleet (MANDATORY)

Parse the breadth and intensity parameters from the skill args. The args string may start with [breadth=light|standard|exhaustive] and/or [intensity=quick|standard|deep]. If only breadth is specified, map light -> quick, standard -> standard, and exhaustive -> deep. If neither is specified, default to "standard" (backward compatible with /octo:embrace which doesn't pass intensity).

Build the fleet dynamically using build-fleet.sh — this is the single source of truth for provider-to-perspective assignment. It detects ALL available providers (codex, agy, copilot, qwen, opencode, ollama, perplexity, openrouter) and assigns perspectives with model family diversity enforcement.

FLEET_OUTPUT=$("${HOME}/.claude-octopus/plugin/scripts/helpers/build-fleet.sh" research "${INTENSITY}" "${PROMPT}" 2>/dev/null)

The output is one line per agent: agent_type|label|perspective_prompt

Parse each line into the fleet array:

• agent_type: the provider to dispatch (codex, agy, copilot, qwen, opencode, claude-sonnet, perplexity, etc.)
• label: human-readable name (e.g., "Problem Analysis", "Ecosystem Overview", "Contrarian Analysis")
• perspective_prompt: the angle-specific prompt to send to that provider
• task_id: generate as probe-${RUN_TIMESTAMP}-${RUN_NONCE}-<index> for each entry

Fleet sizes by intensity:

Model family diversity is enforced automatically — the script prioritizes spreading agents across different model families (OpenAI, Google, Microsoft, Alibaba, Anthropic) to avoid agreement bias from same-family models.

DO NOT hardcode provider assignments. Always use build-fleet.sh output. If the script is unavailable, fall back to the available-provider path (for example codex + agy + claude-sonnet when installed).

DO NOT PROCEED TO STEP 4 until the fleet is built.

Create one durable run identity after building the fleet and before generating task IDs:

RUN_TIMESTAMP="$(date +%s)"
RUN_NONCE="$(od -An -N16 -tx1 /dev/urandom | tr -d '[:space:]')"
RUN_ID="flow-${RUN_TIMESTAMP}-${RUN_NONCE}"

Use probe-${RUN_TIMESTAMP}-${RUN_NONCE}-<index> for every probe task ID. Do not call date again for this run; every probe artifact, the synthesis file, and verification must carry this same identity.

STEP 4: Launch Parallel Agent Subagents (MANDATORY - Use Agent Tool)

Launch each perspective as a background Agent subagent. Each agent calls orchestrate.sh probe-single which handles persona application, credential isolation, result file writing, and durable evidence-run recording. Pass the nonce-bearing $RUN_ID to every child and include $RUN_NONCE in every task ID so parallel runs cannot share result filenames.

CRITICAL: You MUST use the host subagent tool with background execution: true for each perspective. Launch providers strictly in the runtime FLEET_OUTPUT sequence.

For each perspective in the fleet, launch:

Agent(
  background execution: true,
  description: "<label> (<agent_type>)",
  prompt: "Run this command and return its COMPLETE stdout output, including the result file path on the last line:

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh probe-single <agent_type> '<perspective_prompt>' <task_id> '<original_prompt>' --research-run '<run_id>'

After the command completes, read the result file path that was printed and return the full file contents."
)

Replace <run_id> with the current nonce-bearing $RUN_ID value when creating each Agent prompt.

Launch order: Iterate the parsed FLEET_OUTPUT order from build-fleet.sh. Launch all entries from that runtime fleet in parallel when possible; do not reorder by hardcoded provider names.

CRITICAL: You are PROHIBITED from:

• ❌ Researching directly without calling orchestrate.sh probe-single — single-model research misses perspectives that Codex (implementation depth) and Antigravity (ecosystem breadth) bring
• ❌ Using a single Bash(orchestrate.sh probe) call — this causes the 120s Bash timeout that this refactor fixes
• ❌ Using web search instead of orchestrate.sh
• ❌ Claiming you're "simulating" the workflow

STEP 5: Collect Results (MANDATORY - Wait for Background Agents)

Wait for all background agents to complete. You will be automatically notified as each finishes.

Minimum 2 results required (same threshold as synthesize_probe_results()). Graceful degradation rules:

• 0 results -> Report error, show logs, DO NOT proceed
• 1 result -> Warn user, proceed with reduced synthesis quality
• 2+ results -> Proceed normally
• If some agents fail/timeout, proceed with successful results

For each completed agent, collect its output (the result file contents returned by the agent).

Run the status table before synthesis:

"${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" agent-summary

Only cite providers with usable output (ok, degraded, or timeout with partial content). Failed provider output, context-limit errors, and empty outputs are evidence of coverage gaps only.

STEP 6: Synthesize In-Conversation (MANDATORY - Claude Synthesizes)

You (Claude) synthesize the collected results directly in conversation. This replaces the previous direct-provider synthesis call that frequently timed out.

Use this exact structure (structured research report format):

1. Executive Summary — 2-3 sentence overview answering the original question directly
2. Key Findings — Top 3-5 actionable insights, ranked by relevance to the original question
3. Themes & Patterns — Where multiple sources agree, grouped by theme
4. Conflicts & Trade-offs — Where sources disagree, with your reasoned resolution
5. Gaps — What's still unknown and needs more research
6. Priority Matrix — Rank findings by impact (High/Medium/Low) and effort (Low/Medium/High) in a table
7. Recommended Approach — Specific next steps based on findings
8. Sources — List each source with provider attribution and what it contributed
9. Methodology — Brief note on providers used, intensity level, and research approach

Quality rules:

• Every claim MUST cite its source provider or be explicitly marked as [inference]
• Short but specific findings may be MORE valuable than lengthy general analysis
• Minority opinions and dissenting views MUST be preserved — they often contain critical insights
• Concrete examples (code, file paths, commands) outweigh abstract discussion
• Attribute findings to their source provider (🔴 Codex, 🧭 Antigravity, 🔵 Claude Sonnet, 🟣 Perplexity)

Write synthesis to file:

SYNTHESIS_FILE="${HOME}/.claude-octopus/results/probe-synthesis-${RUN_ID}.md"
mkdir -p "$(dirname "$SYNTHESIS_FILE")"

Write the synthesis content to $SYNTHESIS_FILE. The file MUST exist for the validation gate.

Before presenting the synthesis, run the mechanical evidence gate when the durable run is available:

if ! "$HOME/.claude-octopus/plugin/scripts/orchestrate.sh" research-verify \
    "$RUN_ID" "$SYNTHESIS_FILE"; then
  echo "VALIDATION FAILED: Research evidence verification failed"
  exit 1
fi

If verification reports an unfetched source, retain the warning in the report; do not present that claim as independently verified.

STEP 7: Verify, Update State & Present (Only After Steps 1-6 Complete)

Verify synthesis file exists (probe-synthesis-*.md pattern):

# Verify the synthesis file was written (matches probe-synthesis-*.md pattern)
if [[ ! -f "$SYNTHESIS_FILE" ]]; then
  echo "❌ VALIDATION FAILED: No synthesis file found"
  exit 1
fi
echo "✅ VALIDATION PASSED: $SYNTHESIS_FILE"

Update state:

key_findings=$(head -50 "$SYNTHESIS_FILE" | grep -A 3 "## Key Findings\|## Summary" | tail -3 | tr '\n' ' ')

"${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" update_context "discover" "$key_findings"
"${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" update_metrics "phases_completed" "1"
# Track actual providers used (dynamic — from fleet output, not hardcoded)
for _provider in $(echo "$FLEET_OUTPUT" | cut -d'|' -f1 | sort -u); do
  "${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" update_metrics "provider" "$_provider"
done

Present results formatted according to context (Dev vs Knowledge):

For Dev Context:

• Technical research summary
• Recommended implementation approach
• Library/tool comparison (if applicable)
• Perspectives from all providers
• Next steps

For Knowledge Context:

• Strategic research summary
• Recommended approach with business rationale
• Framework analysis (if applicable)
• Perspectives from all providers
• Next steps

Include attribution:

*Multi-AI Research powered by Claude Octopus*
*Providers: available external providers + 🔵 Claude*
*Full synthesis: $SYNTHESIS_FILE*

Discover Workflow - Discovery Phase 🔍

⚠️ MANDATORY: Context Detection & Visual Indicators

BEFORE executing ANY workflow actions, you MUST: