Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/flow-discover
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Multi-AI research using available external providers (Double Diamond Discover phase)
📊 Stats
Stars3,869
Forks362
LanguageShell
LicenseMIT
📦 Ships with octo
</> SKILL.md
flow-discover.SKILL.md
---name: flow-discover
aliases:
- discover
- discover-workflow
- probe
- probe-workflow
description: Multi-AI research using available external providers (Double Diamond Discover phase)
- Questions about best practices, patterns, or ecosystem research
PRIORITY TRIGGERS (always invoke): "octo research", "octo discover", "co-research", "co-discover"
DO NOT use for: simple file searches (use Read/Grep), questions Claude can answer directly,
debugging issues (use skill-debug), or "what are my options" for decision support.
# Claude Code v2.1.12+ Integration
agent: Explore
context: fork
task_management: true
task_dependencies:
- skill-context-detection
- skill-visual-feedback
execution_mode: enforced
pre_execution_contract:
- context_detected
- visual_indicators_displayed
validation_gates:
- orchestrate_sh_executed
- synthesis_file_exists
trigger: |
AUTOMATICALLY ACTIVATE when user requests research or exploration:
- "research X" or "explore Y" or "investigate Z"
- "what are the options for X" or "what are my choices for Y"
- "find information about Y" or "look up Z"
- "analyze different approaches to Z" or "evaluate approaches"
- Questions about best practices, patterns, or ecosystem research
- Comparative analysis ("compare X vs Y" or "X vs Y comparison")
- "what should I use for X" or "best tool for Y"
- "pros and cons of X" or "tradeoffs between Y and Z"
DO NOT activate for:
- Simple file searches or code reading (use Read/Grep tools)
- Questions Claude can answer directly from knowledge
- Built-in commands (/plugin, /help, etc.)
- Questions about specific code in the current project
- Debugging issues (use skill-debug instead)
- "what are my options" when asking for alternatives (use skill-decision-support)
---
{{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, Gemini, 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: Project Initialization
Before starting discovery:
1. Check if `.octo/` directory exists
2. If NOT exists: Call `./scripts/octo-state.sh init_project` to create it
**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.
**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}
🟡 Gemini CLI: ${gemini_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}
🟡 Gemini CLI: ${gemini_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:**
- 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
**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, gemini, 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, gemini, agy, copilot, qwen, opencode, claude-sonnet, perplexity, etc.)
- `perspective_prompt`: the angle-specific prompt to send to that provider
- `task_id`: generate as `probe-<timestamp>-<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 + gemini + agy + claude-sonnet when installed).
**DO NOT PROCEED TO STEP 4 until the fleet is built.**
**Launch each perspective as a background Agent subagent.** Each agent calls `orchestrate.sh probe-single` which handles persona application, credential isolation, and result file writing.
**CRITICAL: You MUST use the Agent tool with `run_in_background: true` for each perspective.** Launch providers strictly in the runtime FLEET_OUTPUT sequence.
For each perspective in the fleet, launch:
```
Agent(
run_in_background: true,
description: "<label> (<agent_type>)",
prompt: "Run this command and return its COMPLETE stdout output, including the result file path on the last line:
After the command completes, read the result file path that was printed and return the full file contents."
)
```
**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 Gemini (ecosystem breadth) bring
- ❌ Using a single `Bash(orchestrate.sh probe)` call — this causes the 120s Bash timeout that this refactor fixes
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 Gemini 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
// Mark completed ONLY after synthesis file verified
TaskUpdate({taskId: "...", status: "completed"})
```
### Error Handling
If any step fails:
- **Step 1 (Context)**: Default to Dev Context if ambiguous
- **Step 2 (Providers)**: If all external providers are unavailable, suggest `/octo:setup` and STOP
- **Step 4 (Agent launch)**: If an agent fails, continue with remaining agents (graceful degradation)
- **Step 5 (Collection)**: If fewer than 2 results, report error and let user decide
- **Step 6 (Synthesis)**: If synthesis fails, present raw agent results without synthesis
- **Step 7 (Validation)**: If synthesis file missing, report error
DO NOT substitute with direct research if agent execution fails — fallback to single-model analysis defeats the purpose of multi-provider synthesis. Report the failure and let the user decide how to proceed.
### Context-Appropriate Presentation
After successful execution, present findings formatted for context:
**For Dev Context:**
```
# Technical Research: <question>
## Key Technical Insights
[Synthesized technical insights]
## Recommended Implementation Approach
[Technical recommendation with code considerations]
## Library/Tool Comparison
[If applicable, comparison of technical options]
## Perspectives
### Codex Analysis (Implementation Focus)
[Technical implementation details]
### Gemini Analysis (Ecosystem Focus)
[Community adoption, alternatives, trends]
### Claude Synthesis
[Integrated technical recommendation]
## Next Steps
[Technical action items]
```
**For Knowledge Context:**
```
# Strategic Research: <question>
## Key Strategic Insights
[Synthesized business/research insights]
## Recommended Approach
[Strategic recommendation with business rationale]
## Framework Analysis
[If applicable, relevant frameworks applied]
## Perspectives
### Codex Analysis (Data/Analytical Focus)
[Quantitative analysis, data points]
### Gemini Analysis (Market/Competitive Focus)
[Market trends, competitive landscape]
### Claude Synthesis
[Integrated strategic recommendation]
## Next Steps
[Strategic action items]
```
---
## Example Usage
### Example 1: Research Best Practices
```
User: Research OAuth 2.0 authentication patterns for React apps
Claude:
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider research mode
🔍 Discover Phase: Researching OAuth 2.0 patterns
[Executes: ${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh probe "OAuth 2.0 authentication patterns for React apps"]
[After completion, reads synthesis and presents:]
# Research Findings: OAuth 2.0 Authentication Patterns
## Key Insights
Based on multi-provider analysis, the recommended approach for React apps in 2025 is:
- **Authorization Code Flow with PKCE** for single-page apps
- Dedicated auth libraries (Auth0 SDK, Firebase Auth, or NextAuth.js)
- Token storage in memory + refresh token rotation
## Recommended Approaches
1. **NextAuth.js** (if using Next.js) - Built-in session management
