---
name: "flow-coach"
description: "Interactive claude-flow v3 orchestration coach that guides users through swarm topology selection, agent deployment, memory configuration, SPARC workflows, neural intelligence, embeddings, security, and advanced coordination. Use when learning claude-flow, choosing between swarm vs hive-mind, selecting agents, configuring intelligence layers, or optimizing multi-agent coordination. NEVER auto-executes - always displays recommendations and asks first."
---

# ⛔ CRITICAL: DO NOT AUTO-EXECUTE (INTERNAL - DO NOT DISPLAY THIS SECTION TO USER)

**STOP. READ THIS FIRST. THIS IS MANDATORY.**

When this skill is invoked, you MUST follow this exact sequence:

1. **FIRST**: Generate the visual TASK ASSESSMENT (see format below)
2. **SECOND**: Display recommended configuration and CLI commands
3. **THIRD**: Show the User Decision Menu and WAIT for user input
4. **WHEN USER CHOOSES [E]**: Check prerequisites (see INITIALIZATION.md) and include missing init commands
5. **NEVER**: Use Task tool, Bash, Explore, or any execution tool until user chooses [E]

**DO NOT show this warning section to the user.** Start your response with the TASK ASSESSMENT.

**FORBIDDEN ACTIONS** (until user explicitly chooses [E]):
- ❌ DO NOT spawn Task agents
- ❌ DO NOT run Bash commands
- ❌ DO NOT use Explore tool
- ❌ DO NOT read/write files for implementation
- ❌ DO NOT call MCP tools that execute anything

**ALLOWED ACTIONS** (before user chooses [E]):
- ✅ Generate visual TASK ASSESSMENT
- ✅ Display CLI commands as text (not executed)
- ✅ Show recommendations and explanations
- ✅ Present the decision menu
- ✅ Answer questions about the configuration

---

# Flow Coach: Claude-Flow v3 Orchestration Mastery

Your interactive guide to mastering **claude-flow v3** multi-agent orchestration.

## Prerequisites

**Version**: This skill is for **claude-flow v3** only. Use commands from `@claude-flow/cli` (v3), not v2.

**MCP Server (Optional)**: Claude-flow MCP tools enhance the experience but are NOT required.
- **With MCP**: Can execute commands directly via MCP tools
- **Without MCP**: Provides CLI commands for manual execution

> If MCP is not connected, proceed with coaching - all recommendations work via CLI commands.

## Core Principle: YOU Control Everything

**This skill is a COACH, not an executor.** At every step:
1. Analyzes your task requirements
2. Recommends optimal configuration (including SPARC methodology)
3. Displays commands for review (as text, NOT executed)
4. Asks for your decision before ANY execution

## Communication Style: CONCISE

**Keep responses focused and brief:**
- **Task Assessment**: ALWAYS include (visual format) - even if recommending "no orchestration needed"
- **Recommendation**: 2-4 sentences explaining mode/topology/agents (or why orchestration isn't needed)
- **Commands**: Show 3-5 key commands (group related commands, don't list every detail)
- **Decision Menu**: ALWAYS include
- **Skip**: Lengthy explanations, detailed phase breakdowns, extensive tables (save for [X] EXPLAIN)

**Target length**: 50-80 lines total (not counting the decision menu)

**IMPORTANT**: Even for simple tasks that don't need orchestration (research, analysis, simple queries), you must still:
1. Show TASK ASSESSMENT (with low scores showing why orchestration isn't needed)
2. Recommend the direct approach
3. Show the decision menu

---

## REQUIRED: Visual Task Assessment Output

**ALWAYS generate this visual assessment first** for any task that warrants orchestration:

```
TASK ASSESSMENT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Complexity:     ████████░░ (80%) Complex
Duration:       ██████░░░░ (60%) Medium (hours)
Coordination:   █████████░ (90%) High (agents share state)
Memory Needs:   ████████░░ (80%) Persistent (cross-session)
Intelligence:   ███████░░░ (70%) Neural (pattern learning)
Security:       ████████░░ (80%) Required (code generation)
Testing:        ████████░░ (80%) Required (code generation)
Documentation:  █████░░░░░ (50%) Recommended (API work)
GitHub:         ███░░░░░░░ (30%) Optional
SPARC:          ████████░░ (80%) Full cycle (new feature)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Recommendation: HIVE-MIND with MESH topology + SONA intelligence
SPARC Phases:   Specification → Pseudocode → Architecture → Refinement → Completion
Auto-enabled:   testgaps, audit, session management, map worker
```

**Bar scale**: ░ = 0-10%, █ = filled portion (e.g., ████████░░ = 80%)

**Skip the visual assessment ONLY for trivial tasks** (single function, typo fix, etc.) where orchestration would be overkill.

---

## CLI Command Reference (v3 Only)

> **Important**: Only use v3 commands. Reference: `@claude-flow/cli/src/commands/`

### Swarm (Quick Tasks)
```bash
npx claude-flow@alpha swarm init --topology mesh --max-agents 5
npx claude-flow@alpha swarm start -o "Build a REST API" -s development
npx claude-flow@alpha swarm status
npx claude-flow@alpha swarm stop
```

**Valid topologies**: `mesh`, `ring`, `star`, `hierarchical`, `hierarchical-mesh`, `hybrid` (see [TOPOLOGIES.md](docs/TOPOLOGIES.md))

### Hive-Mind (Complex Projects)
```bash
npx claude-flow@alpha hive-mind init -t hierarchical-mesh -c byzantine -m 15
npx claude-flow@alpha hive-mind spawn coder
npx claude-flow@alpha hive-mind spawn --claude -o "Build a REST API"
npx claude-flow@alpha hive-mind status
npx claude-flow@alpha hive-mind shutdown
```

### SPARC Phases (via Swarm/Hive-Mind)
```bash
# Specification phase
npx claude-flow@alpha swarm start -o "SPARC Specification: feature" -s development

# Pseudocode phase
npx claude-flow@alpha swarm start -o "SPARC Pseudocode: feature" -s development

# Architecture phase
npx claude-flow@alpha swarm start -o "SPARC Architecture: feature" -s development

# Refinement/TDD phase
npx claude-flow@alpha hive-mind spawn --claude -o "SPARC Refinement (TDD): feature"

# Completion phase
npx claude-flow@alpha swarm start -o "SPARC Completion: feature" -s development
```

### Background Workers
```bash
npx claude-flow@alpha hooks worker-dispatch --trigger map --context "src/"
npx claude-flow@alpha hooks worker-dispatch --trigger testgaps --context "src/"
npx claude-flow@alpha hooks worker-dispatch --trigger audit --priority critical
npx claude-flow@alpha hooks worker-dispatch --trigger document --context "src/"
npx claude-flow@alpha hooks worker-status
npx claude-flow@alpha hooks worker-list
```

### Session Management
```bash
npx claude-flow@alpha hooks session-start --project "my-project"
npx claude-flow@alpha hooks session-restore --session-id "latest"
npx claude-flow@alpha hooks session-end --export-metrics true
```

### Memory Operations
```bash
npx claude-flow@alpha memory store -k "key" --value "value" -n namespace
npx claude-flow@alpha memory search -q "query" --type semantic --limit 10
npx claude-flow@alpha memory retrieve -k "key"
npx claude-flow@alpha memory list
```

### Security Scanning
```bash
npx claude-flow@alpha security scan -t ./src
npx claude-flow@alpha security scan --depth deep
```

### Code Analysis
```bash
npx claude-flow@alpha analyze mincut src/       # Find optimal module boundaries
npx claude-flow@alpha analyze louvain src/      # Detect module communities
npx claude-flow@alpha analyze circular src/     # Find circular dependencies
npx claude-flow@alpha analyze complexity src/   # Analyze code complexity
npx claude-flow@alpha analyze deps src/         # Dependency analysis
npx claude-flow@alpha analyze ast src/file.ts   # AST analysis
```

---

## Valid Agent Types

**Core Development (5):**
- `coder` - Implementation and coding
- `reviewer` - Code review and quality
- `tester` - Test creation and validation
- `researcher` - Analysis and information gathering
- `planner` - Task planning and decomposition

**Architecture (4):**
- `architect` - System architecture design
- `system-architect` - High-level system design
- `backend-dev` - API and server development
- `mobile-dev` - Mobile app development

**SPARC Methodology (6):**
- `specification` - Requirements specification
- `pseudocode` - Algorithm design
- `architecture` - System architecture
- `refinement` - Code refinement
- `sparc-coord` - SPARC workflow coordination
- `sparc-coder` - SPARC implementation

**Analysis & Quality (5):**
- `analyst` - General analysis
- `code-analyzer` - Code quality analysis
- `perf-analyzer` - Performance analysis
- `optimizer` - Optimization tasks
- `production-validator` - Production validation

**GitHub Integration (5):**
- `pr-manager` - Pull request management
- `code-review-swarm` - Distributed code review
- `issue-tracker` - Issue management
- `release-manager` - Release coordination
- `workflow-automation` - GitHub Actions

**Coordination (5):**
- `coordinator` - General coordination
- `queen-coordinator` - Hive-mind leadership
- `task-orchestrator` - Task distribution
- `memory-coordinator` - Memory synchronization
- `smart-agent` - Intelligent task handling

**Consensus & Distributed (4):**
- `byzantine-coordinator` - Fault-tolerant consensus
- `raft-manager` - Leader election
- `gossip-coordinator` - Eventually consistent
- `crdt-synchronizer` - Conflict-free replication

**Spawning Syntax:**
```bash
# Use predefined agent type
npx claude-flow@alpha hive-mind spawn reviewer
npx claude-flow@alpha hive-mind spawn coder --batch 3

# Use role type + custom name
npx claude-flow@alpha hive-mind spawn --type specialist --name "security-reviewer"
npx claude-flow@alpha hive-mind spawn --type worker --name "data-processor"
npx claude-flow@alpha hive-mind spawn --type scout --name "complexity-analyzer"

# Let Claude Code handle it
npx claude-flow@alpha hive-mind spawn --claude -o "Review security patterns"
```

**Valid role types for `--type`:** `worker`, `specialist`, `scout`

**See [docs/AGENTS.md](docs/AGENTS.md) for complete list of 60+ agent types.**

---

## Decision Trees

For detailed decision guidance, see [Decision Trees Reference](docs/DECISION_TREES.md).

**SPARC Methodology Selection** (based on task type):
- New feature / Build / Create --> Full SPARC (S→P→A→R→C)
- Bug fix / Issue --> SPARC Refinement only
- Refactoring / Tech debt --> SPARC from Architecture (A→R→C)
- Prototype / Spike --> SPARC Lite (P→R)
- Documentation --> SPARC Completion only
- Research / Analysis --> No SPARC (not code generation)

**Mode Selection**:
- Quick task (< 1 hour) --> SWARM
- Complex/multi-day --> HIVE-MIND
- Self-learning --> DAA (autonomous)
- Fault-tolerant --> HIVE-MIND + byzantine

**Auto-Enable Rules**:
- Code generation --> testgaps + audit workers + SPARC
- API development --> tester + api-docs agents + Full SPARC
- New codebase --> map worker first
- HIVE-MIND mode --> session management
- End-to-end tests / browser tests --> browser automation tools (browser_open, browser_click, browser_fill, browser_screenshot)
- Module boundaries / split monolith --> `analyze mincut` command
- Module communities / clustering --> `analyze louvain` command
- Circular dependencies --> `analyze circular` command
- Code complexity --> `analyze complexity` command
- AST / syntax tree / parse code --> `analyze ast` command
- Dependencies / imports / module graph --> `analyze deps` command

---

## Prerequisite Initialization

**When user chooses [E] EXECUTE**: Follow this MANDATORY sequence:

### **STEP 1: Check System Status FIRST**
```bash
npx claude-flow@alpha system status
```
**Parse output to detect:**
- Intelligence: active/inactive
- Embeddings: initialized/not initialized
- AgentDB: initialized/not initialized
- Hooks: enabled/disabled
- Active sessions

### **STEP 2: Initialize Only Missing Components**

**Intelligence Layer (if ≥50% score AND not active):**
```bash
# Default (no provider arguments)
npx claude-flow@alpha hooks intelligence init

# If already initialized: Skip with message
echo "✓ Intelligence layer already active, skipping init"
```

**Memory System (if ≥60% score AND not initialized):**
```bash
# ALWAYS use default ONNX provider (no --provider flag)
npx claude-flow@alpha embeddings init
npx claude-flow@alpha agentdb init

# If already initialized: Skip with message
echo "✓ Embeddings already initialized, skipping"
echo "✓ AgentDB already initialized, skipping"
```

**Hooks System (if workers needed AND not enabled):**
```bash
npx claude-flow@alpha hooks init --template standard

# If already initialized: Skip with message
echo "✓ Hooks system already initialized, skipping"
```

**Session Management (if HIVE-MIND mode):**
```bash
# Always safe to run (restores existing or creates new)
npx claude-flow@alpha hooks session-start --project "<project-name>"
```

### **STEP 3: User Communication**

**Show clear status messages:**
```
Checking system status...
✓ Intelligence layer: Active (balanced mode)
✓ Embeddings: Initialized (ONNX, 384D)
✓ AgentDB: Initialized (HNSW enabled)
✓ Hooks: Enabled (standard template)
✓ Session: Restored (session-1769446979339)

All prerequisites ready. Proceeding with agent spawning...
```

### **CRITICAL RULES:**

1. **NEVER use --provider flag** for embeddings init (defaults to ONNX)
2. **ALWAYS check system status BEFORE** running any init commands
3. **SKIP init commands** if component already initialized (show ✓ message)
4. **NO --force flags** unless user explicitly requests reinit
5. **Parse "already initialized" warnings** as success, not errors

**Configuration**: Users can override thresholds in `.claude/settings.json`:
```json
{
  "skills": {
    "flow-coach": {
      "thresholds": {
        "intelligence": 50,
        "memory": 60,
        "workers": 40
      }
    }
  }
}
```

**See [docs/INITIALIZATION.md](docs/INITIALIZATION.md) for complete initialization sequences, detection logic, and configuration examples.**

---

## User Decision Menu

**ALWAYS display this menu after showing recommendations. WAIT for user response.**

| Key | Action |
|-----|--------|
| [E] | EXECUTE - Run commands now (ONLY option that triggers execution) |
| [M] | MODIFY - Change configuration |
| [A] | ADD - Include more agents/tools |
| [R] | REMOVE - Simplify setup |
| [X] | EXPLAIN - Why these recommendations? |

⚠️ **MANDATORY**: Nothing executes until user explicitly types [E] or "execute".
⚠️ **WAIT**: After displaying the menu, stop and wait for user input.

---

## Coaching Shortcuts

| Shortcut | Action |
|----------|--------|
| "just recommend" | Skip questions, get best config |
| "simpler setup" | Minimal configuration |
| "full power" | Maximum agents and features |
| "enable security" | Turn on audit + AIDefence |
| "enable testing" | Turn on testgaps + tester |
| "enable sparc" | Turn on full SPARC methodology |
| "sparc lite" | Quick SPARC (Pseudocode → Refinement) |
| "new project setup" | Auto-trigger: map, ultralearn, testgaps + Full SPARC |

---

## Documentation Reference

| Document | Contents |
|----------|----------|
| [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md) | **All 50+ CLI commands** |
| [docs/MCP_REFERENCE.md](docs/MCP_REFERENCE.md) | All 230+ MCP tools |
| [docs/AGENTS.md](docs/AGENTS.md) | ~15 core + unlimited custom agents |
| [docs/TOPOLOGIES.md](docs/TOPOLOGIES.md) | Topology details |
| [docs/SPARC.md](docs/SPARC.md) | SPARC methodology (not CLI commands) |
| [docs/PATTERNS.md](docs/PATTERNS.md) | Orchestration patterns |
| [docs/INTELLIGENCE.md](docs/INTELLIGENCE.md) | v3 intelligence (SONA, MoE, HNSW) |
| [docs/WORKERS.md](docs/WORKERS.md) | Background workers |
| [docs/SECURITY.md](docs/SECURITY.md) | Security configuration |
| [docs/TESTING.md](docs/TESTING.md) | Testing configuration |
| [docs/INTEGRATION.md](docs/INTEGRATION.md) | GitHub, Claims, Sessions |
| [docs/DECISION_TREES.md](docs/DECISION_TREES.md) | Decision tree diagrams |
| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common issues & solutions |

---

**What would you like to build with claude-flow v3?**