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`. ```bash 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: ```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 " 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 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 ⏱️ 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 ⏱️ 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" != "[]" && "$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. ```bash 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:** | Intensity | Agents | Behavior | |-----------|--------|----------| | **Quick** | 2 | Two most diverse providers | | **Standard** | 4-5 | Rotates across available providers + Claude for edge cases and codebase analysis | | **Deep** | 6-10 | ALL available providers get unique perspectives (bonus slots for copilot, qwen, opencode, etc.) | **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: ```bash 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: ```bash "${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:** ```bash 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: ```bash 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):** ```bash