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)

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)

Hive-Mind (Complex Projects)

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)

# 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

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

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

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

npx claude-flow@alpha security scan -t ./src
npx claude-flow@alpha security scan --depth deep

Code Analysis

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:

# 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 for complete list of 60+ agent types.

Decision Trees

For detailed decision guidance, see Decision Trees Reference.

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

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):

# 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):

# 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):

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):

# 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:

{
  "skills": {
    "flow-coach": {
      "thresholds": {
        "intelligence": 50,
        "memory": 60,
        "workers": 40
      }
    }
  }
}

See 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.

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

Coaching Shortcuts

Documentation Reference

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