moflo 4.8.16 → 4.8.17

package/.claude/guidance/shipped/task-swarm-integration.md

@@ -1,441 +1,441 @@
-# Task & Swarm Integration Pattern
-
-**Purpose:** Integrate native Claude Code tasks with moflo swarm coordination for visible progress tracking and structured agent orchestration.
-
----
-
-## Architecture Overview
-
-```
-+-----------------------------------------------------------------+
-|  NATIVE TASKS (User-Visible Layer)                              |
-|  TaskCreate -> TaskList -> TaskUpdate -> TaskGet                |
-|  Shows: what needs doing, status, dependencies, progress        |
-+-------------------------------+---------------------------------+
-                                | coordinates
-+-------------------------------v---------------------------------+
-|  MOFLO (Orchestration Layer)                                    |
-|  Swarm/Hive-Mind spawns agents, routes tasks, coordinates       |
-|  Memory stores patterns for cross-session learning              |
-+-----------------------------------------------------------------+
-```
-
-| Layer | System | Purpose |
-|-------|--------|---------|
-| **What** | Native Tasks | Track work items, dependencies, status, visible to user |
-| **How** | Moflo | Agent coordination, memory, consensus, routing |
-
----
-
-## Agent Role Icons
-
-Use these icons in `subject` and `activeForm` when creating tasks so the user can visually identify which agent is doing what. This is required for all TaskCreate calls tied to agent work.
-
-| Icon | Agent Role | activeForm Example |
-|------|------------|-------------------|
-| 🔍 | researcher | 🔍 Researching codebase |
-| 🏗️ | system-architect | 🏗️ Designing architecture |
-| 💻 | coder | 💻 Writing code |
-| 🧪 | tester | 🧪 Writing tests |
-| 👀 | reviewer | 👀 Reviewing code |
-| 🛡️ | security-architect | 🛡️ Security audit |
-| ⚡ | performance-engineer | ⚡ Optimizing performance |
-| 📚 | api-docs | 📚 Documenting API |
-| 📋 | planner | 📋 Planning tasks |
-| 🤝 | consensus (hive-mind) | 🤝 Evaluating tradeoffs |
-| 🔬 | analyzer | 🔬 Analyzing code |
-
----
-
-## Integration Protocol
-
-### Step 0: Pre-Swarm Validation (Soft Check)
-
-**Before initializing swarm/hive-mind, verify tasks exist for the current work:**
-
-```javascript
-TaskList()  // Check current task state
-```
-
-| TaskList Result | Action |
-|-----------------|--------|
-| Empty | Create task list (Step 1) before proceeding |
-| Has unrelated/stale tasks | Create new tasks for current work |
-| Has relevant tasks for current work | Proceed to swarm init (Step 3) |
-
-This is a **soft reminder**, not a hard blocker. The goal is user visibility into swarm progress.
-
----
-
-### Step 1: Create Task List BEFORE Spawning Agents
-
-When initializing swarm or hive-mind, create the task structure first:
-
-```javascript
-// 1. Create parent/coordinator task
-TaskCreate({
-  subject: "Implement [feature/fix description]",
-  description: "Coordinating work for [task]. Subtasks track agent progress.",
-  activeForm: "Coordinating implementation"
-})
-
-// 2. Create subtasks for each agent role (in same message for parallel creation)
-//    Use role icons so the user can visually track agent progress at a glance.
-TaskCreate({
-  subject: "🔍 Research requirements and codebase patterns",
-  description: "Researcher agent: Analyze requirements, find relevant code, document patterns.",
-  activeForm: "🔍 Researching codebase"
-})
-TaskCreate({
-  subject: "🏗️ Design implementation approach",
-  description: "Architect agent: Design solution, document decisions.",
-  activeForm: "🏗️ Designing architecture"
-})
-TaskCreate({
-  subject: "💻 Implement the solution",
-  description: "Coder agent: Write code following patterns and standards.",
-  activeForm: "💻 Writing code"
-})
-TaskCreate({
-  subject: "🧪 Write unit tests",
-  description: "Tester agent: Create tests that verify the implementation.",
-  activeForm: "🧪 Writing tests"
-})
-TaskCreate({
-  subject: "👀 Review code quality and security",
-  description: "Reviewer agent: Check for issues, security, best practices.",
-  activeForm: "👀 Reviewing code"
-})
-```
-
-### Step 2: Set Up Dependencies
-
-After creating tasks, establish the execution order:
-
-```javascript
-// Get task IDs from TaskList
-TaskList()
-
-// Set dependencies (research blocks architecture, architecture blocks coding, etc.)
-TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })  // Architect blocked by Researcher
-TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })  // Coder blocked by Architect
-TaskUpdate({ taskId: "4", addBlockedBy: ["3"] })  // Tester blocked by Coder
-TaskUpdate({ taskId: "5", addBlockedBy: ["3"] })  // Reviewer blocked by Coder
-TaskUpdate({ taskId: "0", addBlockedBy: ["4", "5"] })  // Coordinator blocked by Tester & Reviewer
-```
-
-### Step 3: Initialize Moflo Coordination
-
-**MCP (Preferred):**
-- Swarm: `mcp__moflo__swarm_init` (`topology: "hierarchical", maxAgents: 8, strategy: "specialized"`)
-- Hive-mind: `mcp__moflo__hive-mind_init` (`topology: "hierarchical-mesh", consensus: "byzantine"`)
-
-**CLI Fallback:**
-```bash
-npx flo swarm init --topology hierarchical --max-agents 8 --strategy specialized
-npx flo hive-mind init --topology hierarchical-mesh --consensus byzantine
-```
-
-### Step 4: Spawn Agents with Task References
-
-Include task IDs in agent prompts so they update status.
-TaskCreate was already called in Step 1 — tasks are visible before agents spawn.
-
-```javascript
-// TaskCreate already done in Step 1 above
-Task({
-  prompt: `FIRST: Search memory, then read .claude/guidance/agent-bootstrap.md
-
-YOUR TASK (ID: 1): Research requirements and codebase patterns
-- Analyze feature requirements
-- Search codebase for relevant patterns
-- Document findings in memory
-
-WHEN STARTING: The coordinator has marked your task in_progress.
-WHEN COMPLETE: Report findings. Coordinator will mark task completed.`,
-  subagent_type: "researcher",
-  description: "🔍 Research phase",
-  run_in_background: true
-})
-```
-
-### Step 5: Update Tasks as Agents Progress
-
-The coordinator (Claude Code) updates task status based on agent activity:
-
-```javascript
-// When spawning an agent, mark its task in_progress
-TaskUpdate({ taskId: "1", status: "in_progress" })
-
-// When agent returns results, mark completed
-TaskUpdate({ taskId: "1", status: "completed" })
-
-// Check what's unblocked and proceed
-TaskList()  // Shows task 2 is now unblocked
-```
-
----
-
-## Task Templates by Work Type
-
-### Bug Fix (4-5 tasks)
-
-| Task | Agent | Dependencies |
-|------|-------|--------------|
-| 🔍 Investigate bug and root cause | researcher | - |
-| 💻 Implement fix | coder | researcher |
-| 🧪 Write regression tests | tester | coder |
-| 👀 Review fix | reviewer | coder |
-
-### Feature Implementation (5-6 tasks)
-
-| Task | Agent | Dependencies |
-|------|-------|--------------|
-| 🔍 Research requirements | researcher | - |
-| 🏗️ Design implementation | system-architect | researcher |
-| 💻 Implement feature | coder | architect |
-| 🧪 Write unit tests | tester | coder |
-| 👀 Review code | reviewer | coder |
-| 🧪 Integration testing | tester | reviewer |
-
-### Architectural Decision (Hive-Mind) (3-4 tasks)
-
-| Task | Agent | Dependencies |
-|------|-------|--------------|
-| 🔍 Analyze options | researcher | - |
-| 🤝 Evaluate tradeoffs | multiple (consensus) | researcher |
-| 📚 Document decision | api-docs | consensus |
-| 📋 Create implementation plan | planner | decision |
-
----
-
-## Coordinator Responsibilities
-
-The coordinator (Claude Code main process) must:
-
-1. **Create tasks before spawning agents** - Tasks provide the visible work breakdown
-2. **Update status when agents start** - Mark `in_progress` when spawning
-3. **Update status when agents complete** - Mark `completed` when results return
-4. **Monitor dependencies** - Use `TaskList` to see what's unblocked
-5. **Synthesize results** - Review all agent outputs before proceeding
-6. **Store learnings** - After completion, store patterns in memory
-
----
-
-## Example: Full Integration Flow
-
-```javascript
-// USER: Work on feature X with swarm
-
-// STEP 1: Create task structure (role icons for visual tracking)
-TaskCreate({ subject: "Implement feature X", description: "...", activeForm: "Coordinating" })
-TaskCreate({ subject: "🔍 Research patterns", description: "...", activeForm: "🔍 Researching" })
-TaskCreate({ subject: "💻 Implement solution", description: "...", activeForm: "💻 Implementing" })
-TaskCreate({ subject: "🧪 Write unit tests", description: "...", activeForm: "🧪 Writing tests" })
-TaskCreate({ subject: "👀 Review changes", description: "...", activeForm: "👀 Reviewing" })
-
-// STEP 2: Set dependencies
-TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
-TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })
-TaskUpdate({ taskId: "4", addBlockedBy: ["2"] })
-TaskUpdate({ taskId: "0", addBlockedBy: ["3", "4"] })
-
-// STEP 3: Initialize swarm (MCP preferred, CLI fallback)
-// MCP: mcp__moflo__swarm_init (topology: "hierarchical", maxAgents: 8, strategy: "specialized")
-Bash("npx flo swarm init --topology hierarchical --max-agents 8 --strategy specialized")
-
-// STEP 4: Spawn agents (mark tasks in_progress as spawned)
-TaskUpdate({ taskId: "1", status: "in_progress" })
-Task({ prompt: "...", subagent_type: "researcher", run_in_background: true })
-
-// ... agents work ...
-
-// STEP 5: As agents return, update tasks
-TaskUpdate({ taskId: "1", status: "completed" })
-TaskUpdate({ taskId: "2", status: "in_progress" })
-// ... continue workflow
-```
-
----
-
-## Benefits
-
-| Benefit | Description |
-|---------|-------------|
-| **Visibility** | User sees clear task breakdown and progress |
-| **Dependencies** | Blocked tasks show what's waiting |
-| **Traceability** | Each task maps to an agent's work |
-| **Persistence** | Task state survives conversation turns |
-| **Coordination** | Moflo handles agent orchestration |
-| **Learning** | Memory stores patterns for future tasks |
-
----
-
-## When to Use TaskCreate (With or Without Swarm)
-
-### Decision Checklist
-
-Before spawning any agent via `Task`, run through this checklist:
-
-| # | Question | If YES |
-|---|----------|--------|
-| 1 | Is this a swarm / hive-mind? | **TaskCreate required** — full integration protocol (Steps 1-5 above) |
-| 2 | Are you spawning 2+ background agents? | **TaskCreate required** — one per agent, with role icons |
-| 3 | Is this a single background agent (`run_in_background: true`)? | **TaskCreate required** — user needs visibility while it runs |
-| 4 | Will the agent touch 3+ files or take multiple steps? | **TaskCreate required** — even if foreground, the user benefits from status tracking |
-| 5 | Is this a single foreground agent for a focused task? | **TaskCreate optional** — user is already waiting inline for the result |
-| 6 | Is this a quick research/exploration agent? | **Skip TaskCreate** — result returns fast, no tracking needed |
-
-### Quick Rules
-
-- **Background agent = always TaskCreate.** The user can't see what's happening otherwise.
-- **Multiple agents = always TaskCreate for each.** Even without swarm coordination.
-- **Foreground + simple = skip.** Don't add ceremony to a 10-second lookup.
-- **When in doubt, create it.** A TaskCreate costs nothing; an invisible agent frustrates the user.
-
-### Non-Swarm Example (2 background agents, no swarm init)
-
-```javascript
-// Create visible tasks FIRST
-TaskCreate({
-  subject: "🔍 Investigate failing tests",
-  description: "Research agent: find root cause of test failures",
-  activeForm: "🔍 Investigating test failures"
-})
-TaskCreate({
-  subject: "💻 Fix authentication endpoint",
-  description: "Coder agent: implement the fix based on findings",
-  activeForm: "💻 Fixing auth endpoint"
-})
-
-// Then spawn agents
-Task({
-  prompt: "Investigate why booking-public-routes tests are failing...",
-  subagent_type: "researcher",
-  description: "🔍 Investigate test failures",
-  run_in_background: true
-})
-Task({
-  prompt: "Fix the authentication endpoint based on research findings...",
-  subagent_type: "coder",
-  description: "💻 Fix auth endpoint",
-  run_in_background: true
-})
-```
-
-### Single Background Agent (still needs TaskCreate)
-
-```javascript
-TaskCreate({
-  subject: "🧪 Write tests for booking routes",
-  description: "Tester agent: comprehensive test coverage",
-  activeForm: "🧪 Writing booking route tests"
-})
-
-Task({
-  prompt: "Write comprehensive tests for booking-public-routes...",
-  subagent_type: "tester",
-  description: "🧪 Write booking tests",
-  run_in_background: true
-})
-```
-
-### Foreground Agent (TaskCreate optional — skip for simple tasks)
-
-```javascript
-// Simple lookup — no TaskCreate needed
-Task({
-  prompt: "Find all files that import the AuthService",
-  subagent_type: "Explore",
-  description: "🔍 Find AuthService imports"
-})
-```
-
----
-
-## Anti-Drift Configuration
-
-**Use these settings to prevent agent drift:**
-
-**MCP (Preferred):** `mcp__moflo__swarm_init`
-- Small teams: `topology: "hierarchical", maxAgents: 8, strategy: "specialized"`
-- Large teams: `topology: "hierarchical-mesh", maxAgents: 15, strategy: "specialized"`
-
-**CLI Fallback:**
-```bash
-npx flo swarm init --topology hierarchical --max-agents 8 --strategy specialized
-npx flo swarm init --topology hierarchical-mesh --max-agents 15 --strategy specialized
-```
-
-**Valid Topologies:**
-- `hierarchical` - Queen controls workers directly (anti-drift for small teams)
-- `hierarchical-mesh` - Queen + peer communication (recommended for 10+ agents)
-- `mesh` - Fully connected peer network
-- `ring` - Circular communication pattern
-- `star` - Central coordinator with spokes
-- `hybrid` - Dynamic topology switching
-
-**Anti-Drift Guidelines:**
-- **hierarchical**: Coordinator catches divergence
-- **max-agents 6-8**: Smaller team = less drift
-- **specialized**: Clear roles, no overlap
-- **consensus**: raft (leader maintains state)
-
----
-
-## Subagent Context Rules
-
-**Subagents DO inherit CLAUDE.md context** when spawned via Task tool. They automatically receive:
-- Memory-first protocol instructions
-- MCP tool access (`mcp__moflo__*`) when configured
-- Project guidance and coding rules
-
-**Best practices for subagent prompts:**
-- Include relevant context (file paths, error messages, specific requirements)
-- Provide specific paths if known, don't let agents guess with broad globs
-- Trust that they know the memory-first protocol
-
-**MCP Tools Available to Subagents:**
-- `mcp__moflo__memory_search` - Semantic search
-- `mcp__moflo__memory_store` - Pattern storage
-- `mcp__moflo__hooks_route` - Task routing
-
----
-
-## Critical Execution Rules
-
-### CLI + Task Tool in SAME Message
-**When spawning swarm, Claude Code MUST in ONE message:**
-1. Call CLI tools via Bash to initialize coordination
-2. **IMMEDIATELY** call Task tool to spawn agents
-3. Both CLI and Task calls must be in the SAME response
-
-**CLI coordinates, Task tool agents do the actual work!**
-
-### Spawn and Wait Pattern
-
-**After spawning background agents:**
-1. **TELL USER** - "I've spawned X agents working in parallel on: [list tasks]"
-2. **STOP** - Do not continue with more tool calls
-3. **WAIT** - Let the background agents complete their work
-4. **RESPOND** - When agents return results, review and synthesize
-
-### DO NOT:
-- Continuously check swarm status
-- Poll TaskOutput repeatedly
-- Add more tool calls after spawning
-- Ask "should I check on the agents?"
-
-### DO:
-- Spawn all agents in ONE message
-- Tell user what's happening
-- Wait for agent results to arrive
-- Synthesize results when they return
-
----
-
-## See Also
-
-- `.claude/guidance/agent-bootstrap.md` - Subagent bootstrap guide
-- `.claude/guidance/memory-strategy.md` - Memory architecture and search
-- `.claude/guidance/moflo.md` - Full CLI/MCP reference
+# Task & Swarm Integration Pattern
+
+**Purpose:** Integrate native Claude Code tasks with moflo swarm coordination for visible progress tracking and structured agent orchestration.
+
+---
+
+## Architecture Overview
+
+```
++-----------------------------------------------------------------+
+|  NATIVE TASKS (User-Visible Layer)                              |
+|  TaskCreate -> TaskList -> TaskUpdate -> TaskGet                |
+|  Shows: what needs doing, status, dependencies, progress        |
++-------------------------------+---------------------------------+
+                                | coordinates
++-------------------------------v---------------------------------+
+|  MOFLO (Orchestration Layer)                                    |
+|  Swarm/Hive-Mind spawns agents, routes tasks, coordinates       |
+|  Memory stores patterns for cross-session learning              |
++-----------------------------------------------------------------+
+```
+
+| Layer | System | Purpose |
+|-------|--------|---------|
+| **What** | Native Tasks | Track work items, dependencies, status, visible to user |
+| **How** | Moflo | Agent coordination, memory, consensus, routing |
+
+---
+
+## Agent Role Icons
+
+Use these icons in `subject` and `activeForm` when creating tasks so the user can visually identify which agent is doing what. This is required for all TaskCreate calls tied to agent work.
+
+| Icon | Agent Role | activeForm Example |
+|------|------------|-------------------|
+| 🔍 | researcher | 🔍 Researching codebase |
+| 🏗️ | system-architect | 🏗️ Designing architecture |
+| 💻 | coder | 💻 Writing code |
+| 🧪 | tester | 🧪 Writing tests |
+| 👀 | reviewer | 👀 Reviewing code |
+| 🛡️ | security-architect | 🛡️ Security audit |
+| ⚡ | performance-engineer | ⚡ Optimizing performance |
+| 📚 | api-docs | 📚 Documenting API |
+| 📋 | planner | 📋 Planning tasks |
+| 🤝 | consensus (hive-mind) | 🤝 Evaluating tradeoffs |
+| 🔬 | analyzer | 🔬 Analyzing code |
+
+---
+
+## Integration Protocol
+
+### Step 0: Pre-Swarm Validation (Soft Check)
+
+**Before initializing swarm/hive-mind, verify tasks exist for the current work:**
+
+```javascript
+TaskList()  // Check current task state
+```
+
+| TaskList Result | Action |
+|-----------------|--------|
+| Empty | Create task list (Step 1) before proceeding |
+| Has unrelated/stale tasks | Create new tasks for current work |
+| Has relevant tasks for current work | Proceed to swarm init (Step 3) |
+
+This is a **soft reminder**, not a hard blocker. The goal is user visibility into swarm progress.
+
+---
+
+### Step 1: Create Task List BEFORE Spawning Agents
+
+When initializing swarm or hive-mind, create the task structure first:
+
+```javascript
+// 1. Create parent/coordinator task
+TaskCreate({
+  subject: "Implement [feature/fix description]",
+  description: "Coordinating work for [task]. Subtasks track agent progress.",
+  activeForm: "Coordinating implementation"
+})
+
+// 2. Create subtasks for each agent role (in same message for parallel creation)
+//    Use role icons so the user can visually track agent progress at a glance.
+TaskCreate({
+  subject: "🔍 Research requirements and codebase patterns",
+  description: "Researcher agent: Analyze requirements, find relevant code, document patterns.",
+  activeForm: "🔍 Researching codebase"
+})
+TaskCreate({
+  subject: "🏗️ Design implementation approach",
+  description: "Architect agent: Design solution, document decisions.",
+  activeForm: "🏗️ Designing architecture"
+})
+TaskCreate({
+  subject: "💻 Implement the solution",
+  description: "Coder agent: Write code following patterns and standards.",
+  activeForm: "💻 Writing code"
+})
+TaskCreate({
+  subject: "🧪 Write unit tests",
+  description: "Tester agent: Create tests that verify the implementation.",
+  activeForm: "🧪 Writing tests"
+})
+TaskCreate({
+  subject: "👀 Review code quality and security",
+  description: "Reviewer agent: Check for issues, security, best practices.",
+  activeForm: "👀 Reviewing code"
+})
+```
+
+### Step 2: Set Up Dependencies
+
+After creating tasks, establish the execution order:
+
+```javascript
+// Get task IDs from TaskList
+TaskList()
+
+// Set dependencies (research blocks architecture, architecture blocks coding, etc.)
+TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })  // Architect blocked by Researcher
+TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })  // Coder blocked by Architect
+TaskUpdate({ taskId: "4", addBlockedBy: ["3"] })  // Tester blocked by Coder
+TaskUpdate({ taskId: "5", addBlockedBy: ["3"] })  // Reviewer blocked by Coder
+TaskUpdate({ taskId: "0", addBlockedBy: ["4", "5"] })  // Coordinator blocked by Tester & Reviewer
+```
+
+### Step 3: Initialize Moflo Coordination
+
+**MCP (Preferred):**
+- Swarm: `mcp__moflo__swarm_init` (`topology: "hierarchical", maxAgents: 8, strategy: "specialized"`)
+- Hive-mind: `mcp__moflo__hive-mind_init` (`topology: "hierarchical-mesh", consensus: "byzantine"`)
+
+**CLI Fallback:**
+```bash
+npx flo swarm init --topology hierarchical --max-agents 8 --strategy specialized
+npx flo hive-mind init --topology hierarchical-mesh --consensus byzantine
+```
+
+### Step 4: Spawn Agents with Task References
+
+Include task IDs in agent prompts so they update status.
+TaskCreate was already called in Step 1 — tasks are visible before agents spawn.
+
+```javascript
+// TaskCreate already done in Step 1 above
+Task({
+  prompt: `FIRST: Search memory, then read .claude/guidance/agent-bootstrap.md
+
+YOUR TASK (ID: 1): Research requirements and codebase patterns
+- Analyze feature requirements
+- Search codebase for relevant patterns
+- Document findings in memory
+
+WHEN STARTING: The coordinator has marked your task in_progress.
+WHEN COMPLETE: Report findings. Coordinator will mark task completed.`,
+  subagent_type: "researcher",
+  description: "🔍 Research phase",
+  run_in_background: true
+})
+```
+
+### Step 5: Update Tasks as Agents Progress
+
+The coordinator (Claude Code) updates task status based on agent activity:
+
+```javascript
+// When spawning an agent, mark its task in_progress
+TaskUpdate({ taskId: "1", status: "in_progress" })
+
+// When agent returns results, mark completed
+TaskUpdate({ taskId: "1", status: "completed" })
+
+// Check what's unblocked and proceed
+TaskList()  // Shows task 2 is now unblocked
+```
+
+---
+
+## Task Templates by Work Type
+
+### Bug Fix (4-5 tasks)
+
+| Task | Agent | Dependencies |
+|------|-------|--------------|
+| 🔍 Investigate bug and root cause | researcher | - |
+| 💻 Implement fix | coder | researcher |
+| 🧪 Write regression tests | tester | coder |
+| 👀 Review fix | reviewer | coder |
+
+### Feature Implementation (5-6 tasks)
+
+| Task | Agent | Dependencies |
+|------|-------|--------------|
+| 🔍 Research requirements | researcher | - |
+| 🏗️ Design implementation | system-architect | researcher |
+| 💻 Implement feature | coder | architect |
+| 🧪 Write unit tests | tester | coder |
+| 👀 Review code | reviewer | coder |
+| 🧪 Integration testing | tester | reviewer |
+
+### Architectural Decision (Hive-Mind) (3-4 tasks)
+
+| Task | Agent | Dependencies |
+|------|-------|--------------|
+| 🔍 Analyze options | researcher | - |
+| 🤝 Evaluate tradeoffs | multiple (consensus) | researcher |
+| 📚 Document decision | api-docs | consensus |
+| 📋 Create implementation plan | planner | decision |
+
+---
+
+## Coordinator Responsibilities
+
+The coordinator (Claude Code main process) must:
+
+1. **Create tasks before spawning agents** - Tasks provide the visible work breakdown
+2. **Update status when agents start** - Mark `in_progress` when spawning
+3. **Update status when agents complete** - Mark `completed` when results return
+4. **Monitor dependencies** - Use `TaskList` to see what's unblocked
+5. **Synthesize results** - Review all agent outputs before proceeding
+6. **Store learnings** - After completion, store patterns in memory
+
+---
+
+## Example: Full Integration Flow
+
+```javascript
+// USER: Work on feature X with swarm
+
+// STEP 1: Create task structure (role icons for visual tracking)
+TaskCreate({ subject: "Implement feature X", description: "...", activeForm: "Coordinating" })
+TaskCreate({ subject: "🔍 Research patterns", description: "...", activeForm: "🔍 Researching" })
+TaskCreate({ subject: "💻 Implement solution", description: "...", activeForm: "💻 Implementing" })
+TaskCreate({ subject: "🧪 Write unit tests", description: "...", activeForm: "🧪 Writing tests" })
+TaskCreate({ subject: "👀 Review changes", description: "...", activeForm: "👀 Reviewing" })
+
+// STEP 2: Set dependencies
+TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
+TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })
+TaskUpdate({ taskId: "4", addBlockedBy: ["2"] })
+TaskUpdate({ taskId: "0", addBlockedBy: ["3", "4"] })
+
+// STEP 3: Initialize swarm (MCP preferred, CLI fallback)
+// MCP: mcp__moflo__swarm_init (topology: "hierarchical", maxAgents: 8, strategy: "specialized")
+Bash("npx flo swarm init --topology hierarchical --max-agents 8 --strategy specialized")
+
+// STEP 4: Spawn agents (mark tasks in_progress as spawned)
+TaskUpdate({ taskId: "1", status: "in_progress" })
+Task({ prompt: "...", subagent_type: "researcher", run_in_background: true })
+
+// ... agents work ...
+
+// STEP 5: As agents return, update tasks
+TaskUpdate({ taskId: "1", status: "completed" })
+TaskUpdate({ taskId: "2", status: "in_progress" })
+// ... continue workflow
+```
+
+---
+
+## Benefits
+
+| Benefit | Description |
+|---------|-------------|
+| **Visibility** | User sees clear task breakdown and progress |
+| **Dependencies** | Blocked tasks show what's waiting |
+| **Traceability** | Each task maps to an agent's work |
+| **Persistence** | Task state survives conversation turns |
+| **Coordination** | Moflo handles agent orchestration |
+| **Learning** | Memory stores patterns for future tasks |
+
+---
+
+## When to Use TaskCreate (With or Without Swarm)
+
+### Decision Checklist
+
+Before spawning any agent via `Task`, run through this checklist:
+
+| # | Question | If YES |
+|---|----------|--------|
+| 1 | Is this a swarm / hive-mind? | **TaskCreate required** — full integration protocol (Steps 1-5 above) |
+| 2 | Are you spawning 2+ background agents? | **TaskCreate required** — one per agent, with role icons |
+| 3 | Is this a single background agent (`run_in_background: true`)? | **TaskCreate required** — user needs visibility while it runs |
+| 4 | Will the agent touch 3+ files or take multiple steps? | **TaskCreate required** — even if foreground, the user benefits from status tracking |
+| 5 | Is this a single foreground agent for a focused task? | **TaskCreate optional** — user is already waiting inline for the result |
+| 6 | Is this a quick research/exploration agent? | **Skip TaskCreate** — result returns fast, no tracking needed |
+
+### Quick Rules
+
+- **Background agent = always TaskCreate.** The user can't see what's happening otherwise.
+- **Multiple agents = always TaskCreate for each.** Even without swarm coordination.
+- **Foreground + simple = skip.** Don't add ceremony to a 10-second lookup.
+- **When in doubt, create it.** A TaskCreate costs nothing; an invisible agent frustrates the user.
+
+### Non-Swarm Example (2 background agents, no swarm init)
+
+```javascript
+// Create visible tasks FIRST
+TaskCreate({
+  subject: "🔍 Investigate failing tests",
+  description: "Research agent: find root cause of test failures",
+  activeForm: "🔍 Investigating test failures"
+})
+TaskCreate({
+  subject: "💻 Fix authentication endpoint",
+  description: "Coder agent: implement the fix based on findings",
+  activeForm: "💻 Fixing auth endpoint"
+})
+
+// Then spawn agents
+Task({
+  prompt: "Investigate why booking-public-routes tests are failing...",
+  subagent_type: "researcher",
+  description: "🔍 Investigate test failures",
+  run_in_background: true
+})
+Task({
+  prompt: "Fix the authentication endpoint based on research findings...",
+  subagent_type: "coder",
+  description: "💻 Fix auth endpoint",
+  run_in_background: true
+})
+```
+
+### Single Background Agent (still needs TaskCreate)
+
+```javascript
+TaskCreate({
+  subject: "🧪 Write tests for booking routes",
+  description: "Tester agent: comprehensive test coverage",
+  activeForm: "🧪 Writing booking route tests"
+})
+
+Task({
+  prompt: "Write comprehensive tests for booking-public-routes...",
+  subagent_type: "tester",
+  description: "🧪 Write booking tests",
+  run_in_background: true
+})
+```
+
+### Foreground Agent (TaskCreate optional — skip for simple tasks)
+
+```javascript
+// Simple lookup — no TaskCreate needed
+Task({
+  prompt: "Find all files that import the AuthService",
+  subagent_type: "Explore",
+  description: "🔍 Find AuthService imports"
+})
+```
+
+---
+
+## Anti-Drift Configuration
+
+**Use these settings to prevent agent drift:**
+
+**MCP (Preferred):** `mcp__moflo__swarm_init`
+- Small teams: `topology: "hierarchical", maxAgents: 8, strategy: "specialized"`
+- Large teams: `topology: "hierarchical-mesh", maxAgents: 15, strategy: "specialized"`
+
+**CLI Fallback:**
+```bash
+npx flo swarm init --topology hierarchical --max-agents 8 --strategy specialized
+npx flo swarm init --topology hierarchical-mesh --max-agents 15 --strategy specialized
+```
+
+**Valid Topologies:**
+- `hierarchical` - Queen controls workers directly (anti-drift for small teams)
+- `hierarchical-mesh` - Queen + peer communication (recommended for 10+ agents)
+- `mesh` - Fully connected peer network
+- `ring` - Circular communication pattern
+- `star` - Central coordinator with spokes
+- `hybrid` - Dynamic topology switching
+
+**Anti-Drift Guidelines:**
+- **hierarchical**: Coordinator catches divergence
+- **max-agents 6-8**: Smaller team = less drift
+- **specialized**: Clear roles, no overlap
+- **consensus**: raft (leader maintains state)
+
+---
+
+## Subagent Context Rules
+
+**Subagents DO inherit CLAUDE.md context** when spawned via Task tool. They automatically receive:
+- Memory-first protocol instructions
+- MCP tool access (`mcp__moflo__*`) when configured
+- Project guidance and coding rules
+
+**Best practices for subagent prompts:**
+- Include relevant context (file paths, error messages, specific requirements)
+- Provide specific paths if known, don't let agents guess with broad globs
+- Trust that they know the memory-first protocol
+
+**MCP Tools Available to Subagents:**
+- `mcp__moflo__memory_search` - Semantic search
+- `mcp__moflo__memory_store` - Pattern storage
+- `mcp__moflo__hooks_route` - Task routing
+
+---
+
+## Critical Execution Rules
+
+### CLI + Task Tool in SAME Message
+**When spawning swarm, Claude Code MUST in ONE message:**
+1. Call CLI tools via Bash to initialize coordination
+2. **IMMEDIATELY** call Task tool to spawn agents
+3. Both CLI and Task calls must be in the SAME response
+
+**CLI coordinates, Task tool agents do the actual work!**
+
+### Spawn and Wait Pattern
+
+**After spawning background agents:**
+1. **TELL USER** - "I've spawned X agents working in parallel on: [list tasks]"
+2. **STOP** - Do not continue with more tool calls
+3. **WAIT** - Let the background agents complete their work
+4. **RESPOND** - When agents return results, review and synthesize
+
+### DO NOT:
+- Continuously check swarm status
+- Poll TaskOutput repeatedly
+- Add more tool calls after spawning
+- Ask "should I check on the agents?"
+
+### DO:
+- Spawn all agents in ONE message
+- Tell user what's happening
+- Wait for agent results to arrive
+- Synthesize results when they return
+
+---
+
+## See Also
+
+- `.claude/guidance/agent-bootstrap.md` - Subagent bootstrap guide
+- `.claude/guidance/memory-strategy.md` - Memory architecture and search
+- `.claude/guidance/moflo.md` - Full CLI/MCP reference