moflo 4.3.0 → 4.5.0

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

@@ -0,0 +1,348 @@
+# 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 |
+
+---
+
+## 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)
+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__claude-flow__swarm_init` (`topology: "hierarchical", maxAgents: 8, strategy: "specialized"`)
+- Hive-mind: `mcp__claude-flow__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:
+
+```javascript
+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
+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__claude-flow__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 This Pattern
+
+| Scenario | Use Integration? |
+|----------|-----------------|
+| Swarm or hive-mind explicitly requested | **YES** - always |
+| Complex task (5+ subtasks expected) | **YES** |
+| Simple bug fix (single agent sufficient) | Optional |
+| Non-coding tasks (analysis, help) | **NO** |
+| Direct execution requested | **NO** |
+
+---
+
+## Anti-Drift Configuration
+
+**Use these settings to prevent agent drift:**
+
+**MCP (Preferred):** `mcp__claude-flow__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__claude-flow__*`) 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__claude-flow__memory_search` - Semantic search
+- `mcp__claude-flow__memory_store` - Pattern storage
+- `mcp__claude-flow__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

package/.claude/helpers/hook-handler.cjs

@@ -127,7 +127,8 @@ const handlers = {
         session.start && session.start();
       }
     } else {
-      console.log('[OK] Session restored: session-' + Date.now());
+      console.log('No session to restore');
+      console.log('Session started: session-' + Date.now());
     }
     if (intelligence && intelligence.init) {
       try {
@@ -137,6 +138,87 @@ const handlers = {
         }
       } catch (e) { /* non-fatal */ }
     }
+
+    // Auto-index guidance, code map, and patterns on session start
+    try {
+      var projectDir = path.resolve(path.dirname(helpersDir), '..');
+      var cp = require('child_process');
+
+      // Read moflo.yaml auto_index flags (default: both true)
+      var autoGuidance = true;
+      var autoCodeMap = true;
+      var mofloConfigPath = path.join(projectDir, 'moflo.yaml');
+      var mofloJsonPath = path.join(projectDir, 'moflo.config.json');
+
+      if (fs.existsSync(mofloConfigPath)) {
+        try {
+          var content = fs.readFileSync(mofloConfigPath, 'utf-8');
+          if (/auto_index:\s*\n\s+guidance:\s*false/i.test(content)) autoGuidance = false;
+          if (/auto_index:\s*\n(?:\s+guidance:\s*\w+\n)?\s+code_map:\s*false/i.test(content)) autoCodeMap = false;
+        } catch (e) { /* ignore */ }
+      } else if (fs.existsSync(mofloJsonPath)) {
+        try {
+          var config = JSON.parse(fs.readFileSync(mofloJsonPath, 'utf-8'));
+          var ai = config.auto_index || config.autoIndex || {};
+          if (ai.guidance === false) autoGuidance = false;
+          if (ai.code_map === false || ai.codeMap === false) autoCodeMap = false;
+        } catch (e) { /* ignore */ }
+      }
+
+      // Helper: find a moflo bin script by filename
+      function findMofloScript(scriptName) {
+        var candidates = [
+          path.join(projectDir, 'bin', scriptName),
+          path.join(projectDir, 'node_modules', 'moflo', 'bin', scriptName),
+        ];
+        for (var i = 0; i < candidates.length; i++) {
+          if (fs.existsSync(candidates[i])) return candidates[i];
+        }
+        try {
+          var resolved = require.resolve('moflo/bin/' + scriptName, { paths: [projectDir] });
+          if (fs.existsSync(resolved)) return resolved;
+        } catch (e) { /* not installed */ }
+        return null;
+      }
+
+      function spawnBackground(script, extraArgs) {
+        var args = [script].concat(extraArgs || []);
+        cp.spawn('node', args, {
+          stdio: 'ignore',
+          cwd: projectDir,
+          detached: true,
+          windowsHide: true
+        }).unref();
+      }
+
+      // 1. Index guidance docs (with embeddings for semantic search)
+      if (autoGuidance) {
+        var guidanceScript = findMofloScript('index-guidance.mjs');
+        if (guidanceScript) spawnBackground(guidanceScript);
+      }
+
+      // 2. Generate code map (structural index of source files)
+      if (autoCodeMap) {
+        var codeMapScript = findMofloScript('generate-code-map.mjs');
+        if (codeMapScript) spawnBackground(codeMapScript);
+      }
+
+      // 3. Start learning service (pattern research on codebase)
+      var learnScript = findMofloScript('../.claude/helpers/learning-service.mjs');
+      if (!learnScript) learnScript = findMofloScript('learning-service.mjs');
+      // Also check the .claude/helpers location directly
+      if (!learnScript) {
+        var localLearn = path.join(projectDir, '.claude', 'helpers', 'learning-service.mjs');
+        if (fs.existsSync(localLearn)) learnScript = localLearn;
+      }
+      // Check inside node_modules/moflo/.claude/helpers
+      if (!learnScript) {
+        var nmLearn = path.join(projectDir, 'node_modules', 'moflo', '.claude', 'helpers', 'learning-service.mjs');
+        if (fs.existsSync(nmLearn)) learnScript = nmLearn;
+      }
+      if (learnScript) spawnBackground(learnScript);
+
+    } catch (e) { /* non-fatal: session-start indexing is best-effort */ }
   },
 
   'session-end': () => {