moflo 4.8.22 → 4.8.24

package/.claude/skills/v3-swarm-coordination/SKILL.md

@@ -0,0 +1,340 @@
+---
+name: "V3 Swarm Coordination"
+description: "15-agent hierarchical mesh coordination for v3 implementation. Orchestrates parallel execution across security, core, and integration domains following 10 ADRs with 14-week timeline."
+---
+
+# V3 Swarm Coordination
+
+## What This Skill Does
+
+Orchestrates the complete 15-agent hierarchical mesh swarm for claude-flow v3 implementation, coordinating parallel execution across domains while maintaining dependencies and timeline adherence.
+
+## Quick Start
+
+```bash
+# Initialize 15-agent v3 swarm
+Task("Swarm initialization", "Initialize hierarchical mesh for v3 implementation", "v3-queen-coordinator")
+
+# Security domain (Phase 1 - Critical priority)
+Task("Security architecture", "Design v3 threat model and security boundaries", "v3-security-architect")
+Task("CVE remediation", "Fix CVE-1, CVE-2, CVE-3 vulnerabilities", "security-auditor")
+Task("Security testing", "Implement TDD security framework", "test-architect")
+
+# Core domain (Phase 2 - Parallel execution)
+Task("Memory unification", "Implement AgentDB 150x improvement", "v3-memory-specialist")
+Task("Integration architecture", "Deep agentic-flow@alpha integration", "v3-integration-architect")
+Task("Performance validation", "Validate 2.49x-7.47x targets", "v3-performance-engineer")
+```
+
+## 15-Agent Swarm Architecture
+
+### Hierarchical Mesh Topology
+```
+                    👑 QUEEN COORDINATOR
+                         (Agent #1)
+                             │
+        ┌────────────────────┼────────────────────┐
+        │                   │                    │
+   🛡️ SECURITY         🧠 CORE              🔗 INTEGRATION
+   (Agents #2-4)       (Agents #5-9)        (Agents #10-12)
+        │                   │                    │
+        └────────────────────┼────────────────────┘
+                             │
+        ┌────────────────────┼────────────────────┐
+        │                   │                    │
+   🧪 QUALITY          ⚡ PERFORMANCE        🚀 DEPLOYMENT
+   (Agent #13)         (Agent #14)          (Agent #15)
+```
+
+### Agent Roster
+| ID | Agent | Domain | Phase | Responsibility |
+|----|-------|--------|-------|----------------|
+| 1 | Queen Coordinator | Orchestration | All | GitHub issues, dependencies, timeline |
+| 2 | Security Architect | Security | Foundation | Threat modeling, CVE planning |
+| 3 | Security Implementer | Security | Foundation | CVE fixes, secure patterns |
+| 4 | Security Tester | Security | Foundation | TDD security testing |
+| 5 | Core Architect | Core | Systems | DDD architecture, coordination |
+| 6 | Core Implementer | Core | Systems | Core module implementation |
+| 7 | Memory Specialist | Core | Systems | AgentDB unification |
+| 8 | Swarm Specialist | Core | Systems | Unified coordination engine |
+| 9 | MCP Specialist | Core | Systems | MCP server optimization |
+| 10 | Integration Architect | Integration | Integration | agentic-flow@alpha deep integration |
+| 11 | CLI/Hooks Developer | Integration | Integration | CLI modernization |
+| 12 | Neural/Learning Dev | Integration | Integration | SONA integration |
+| 13 | TDD Test Engineer | Quality | All | London School TDD |
+| 14 | Performance Engineer | Performance | Optimization | Benchmarking validation |
+| 15 | Release Engineer | Deployment | Release | CI/CD and v3.0.0 release |
+
+## Implementation Phases
+
+### Phase 1: Foundation (Week 1-2)
+**Active Agents**: #1, #2-4, #5-6
+```typescript
+const phase1 = async () => {
+  // Parallel security and architecture foundation
+  await Promise.all([
+    // Security domain (critical priority)
+    Task("Security architecture", "Complete threat model and security boundaries", "v3-security-architect"),
+    Task("CVE-1 fix", "Update vulnerable dependencies", "security-implementer"),
+    Task("CVE-2 fix", "Replace weak password hashing", "security-implementer"),
+    Task("CVE-3 fix", "Remove hardcoded credentials", "security-implementer"),
+    Task("Security testing", "TDD London School security framework", "test-architect"),
+
+    // Core architecture foundation
+    Task("DDD architecture", "Design domain boundaries and structure", "core-architect"),
+    Task("Type modernization", "Update type system for v3", "core-implementer")
+  ]);
+};
+```
+
+### Phase 2: Core Systems (Week 3-6)
+**Active Agents**: #1, #5-9, #13
+```typescript
+const phase2 = async () => {
+  // Parallel core system implementation
+  await Promise.all([
+    Task("Memory unification", "Implement AgentDB with 150x-12,500x improvement", "v3-memory-specialist"),
+    Task("Swarm coordination", "Merge 4 coordination systems into unified engine", "swarm-specialist"),
+    Task("MCP optimization", "Optimize MCP server performance", "mcp-specialist"),
+    Task("Core implementation", "Implement DDD modular architecture", "core-implementer"),
+    Task("TDD core tests", "Comprehensive test coverage for core systems", "test-architect")
+  ]);
+};
+```
+
+### Phase 3: Integration (Week 7-10)
+**Active Agents**: #1, #10-12, #13-14
+```typescript
+const phase3 = async () => {
+  // Parallel integration and optimization
+  await Promise.all([
+    Task("agentic-flow integration", "Eliminate 10,000+ duplicate lines", "v3-integration-architect"),
+    Task("CLI modernization", "Enhance CLI with hooks system", "cli-hooks-developer"),
+    Task("SONA integration", "Implement <0.05ms learning adaptation", "neural-learning-developer"),
+    Task("Performance benchmarking", "Validate 2.49x-7.47x targets", "v3-performance-engineer"),
+    Task("Integration testing", "End-to-end system validation", "test-architect")
+  ]);
+};
+```
+
+### Phase 4: Release (Week 11-14)
+**Active Agents**: All 15
+```typescript
+const phase4 = async () => {
+  // Full swarm final optimization
+  await Promise.all([
+    Task("Performance optimization", "Final optimization pass", "v3-performance-engineer"),
+    Task("Release preparation", "CI/CD pipeline and v3.0.0 release", "release-engineer"),
+    Task("Final testing", "Complete test coverage validation", "test-architect"),
+
+    // All agents: Final polish and optimization
+    ...agents.map(agent =>
+      Task("Final polish", `Agent ${agent.id} final optimization`, agent.name)
+    )
+  ]);
+};
+```
+
+## Coordination Patterns
+
+### Dependency Management
+```typescript
+class DependencyCoordination {
+  private dependencies = new Map([
+    // Security first (no dependencies)
+    [2, []], [3, [2]], [4, [2, 3]],
+
+    // Core depends on security foundation
+    [5, [2]], [6, [5]], [7, [5]], [8, [5, 7]], [9, [5]],
+
+    // Integration depends on core systems
+    [10, [5, 7, 8]], [11, [5, 10]], [12, [7, 10]],
+
+    // Quality and performance cross-cutting
+    [13, [2, 5]], [14, [5, 7, 8, 10]], [15, [13, 14]]
+  ]);
+
+  async coordinateExecution(): Promise<void> {
+    const completed = new Set<number>();
+
+    while (completed.size < 15) {
+      const ready = this.getReadyAgents(completed);
+
+      if (ready.length === 0) {
+        throw new Error('Deadlock detected in dependency chain');
+      }
+
+      // Execute ready agents in parallel
+      await Promise.all(ready.map(agentId => this.executeAgent(agentId)));
+
+      ready.forEach(id => completed.add(id));
+    }
+  }
+}
+```
+
+### GitHub Integration
+```typescript
+class GitHubCoordination {
+  async initializeV3Milestone(): Promise<void> {
+    await gh.createMilestone({
+      title: 'Claude-Flow v3.0.0 Implementation',
+      description: '15-agent swarm implementation of 10 ADRs',
+      dueDate: this.calculate14WeekDeadline()
+    });
+  }
+
+  async createEpicIssues(): Promise<void> {
+    const epics = [
+      { title: 'Security Overhaul (CVE-1,2,3)', agents: [2, 3, 4] },
+      { title: 'Memory Unification (AgentDB)', agents: [7] },
+      { title: 'agentic-flow Integration', agents: [10] },
+      { title: 'Performance Optimization', agents: [14] },
+      { title: 'DDD Architecture', agents: [5, 6] }
+    ];
+
+    for (const epic of epics) {
+      await gh.createIssue({
+        title: epic.title,
+        labels: ['epic', 'v3', ...epic.agents.map(id => `agent-${id}`)],
+        assignees: epic.agents.map(id => this.getAgentGithubUser(id))
+      });
+    }
+  }
+
+  async trackProgress(): Promise<void> {
+    // Hourly progress updates from each agent
+    setInterval(async () => {
+      for (const agent of this.agents) {
+        await this.postAgentProgress(agent);
+      }
+    }, 3600000); // 1 hour
+  }
+}
+```
+
+### Communication Bus
+```typescript
+class SwarmCommunication {
+  private bus = new QuicSwarmBus({
+    maxAgents: 15,
+    messageTimeout: 30000,
+    retryAttempts: 3
+  });
+
+  async broadcastToSecurityDomain(message: SwarmMessage): Promise<void> {
+    await this.bus.broadcast(message, {
+      targetAgents: [2, 3, 4],
+      priority: 'critical'
+    });
+  }
+
+  async coordinateCoreSystems(message: SwarmMessage): Promise<void> {
+    await this.bus.broadcast(message, {
+      targetAgents: [5, 6, 7, 8, 9],
+      priority: 'high'
+    });
+  }
+
+  async notifyIntegrationTeam(message: SwarmMessage): Promise<void> {
+    await this.bus.broadcast(message, {
+      targetAgents: [10, 11, 12],
+      priority: 'medium'
+    });
+  }
+}
+```
+
+## Performance Coordination
+
+### Parallel Efficiency Monitoring
+```typescript
+class EfficiencyMonitor {
+  async measureParallelEfficiency(): Promise<EfficiencyReport> {
+    const agentUtilization = await this.measureAgentUtilization();
+    const coordinationOverhead = await this.measureCoordinationCost();
+
+    return {
+      totalEfficiency: agentUtilization.average,
+      target: 0.85, // >85% utilization
+      achieved: agentUtilization.average > 0.85,
+      bottlenecks: this.identifyBottlenecks(agentUtilization),
+      recommendations: this.generateOptimizations()
+    };
+  }
+}
+```
+
+### Load Balancing
+```typescript
+class SwarmLoadBalancer {
+  async balanceWorkload(): Promise<void> {
+    const workloads = await this.analyzeAgentWorkloads();
+
+    for (const [agentId, load] of workloads.entries()) {
+      if (load > this.getCapacityThreshold(agentId)) {
+        await this.redistributeWork(agentId);
+      }
+    }
+  }
+
+  async redistributeWork(overloadedAgent: number): Promise<void> {
+    const availableAgents = this.getAvailableAgents();
+    const tasks = await this.getAgentTasks(overloadedAgent);
+
+    // Redistribute tasks to available agents
+    for (const task of tasks) {
+      const bestAgent = this.selectOptimalAgent(task, availableAgents);
+      await this.reassignTask(task, bestAgent);
+    }
+  }
+}
+```
+
+## Success Metrics
+
+### Swarm Coordination
+- [ ] **Parallel Efficiency**: >85% agent utilization time
+- [ ] **Dependency Resolution**: Zero deadlocks or blocking issues
+- [ ] **Communication Latency**: <100ms inter-agent messaging
+- [ ] **Timeline Adherence**: 14-week delivery maintained
+- [ ] **GitHub Integration**: <4h automated issue response
+
+### Implementation Targets
+- [ ] **ADR Coverage**: All 10 ADRs implemented successfully
+- [ ] **Performance**: 2.49x-7.47x Flash Attention achieved
+- [ ] **Search**: 150x-12,500x AgentDB improvement validated
+- [ ] **Code Reduction**: <5,000 lines (vs 15,000+)
+- [ ] **Security**: 90/100 security score achieved
+
+## Related V3 Skills
+
+- `v3-security-overhaul` - Security domain coordination
+- `v3-memory-unification` - Memory system coordination
+- `v3-integration-deep` - Integration domain coordination
+- `v3-performance-optimization` - Performance domain coordination
+
+## Usage Examples
+
+### Initialize Complete V3 Swarm
+```bash
+# Queen Coordinator initializes full swarm
+Task("V3 swarm initialization",
+     "Initialize 15-agent hierarchical mesh for complete v3 implementation",
+     "v3-queen-coordinator")
+```
+
+### Phase-based Execution
+```bash
+# Phase 1: Security-first foundation
+npm run v3:phase1:security
+
+# Phase 2: Core systems parallel
+npm run v3:phase2:core-systems
+
+# Phase 3: Integration and optimization
+npm run v3:phase3:integration
+
+# Phase 4: Release preparation
+npm run v3:phase4:release
+```

package/.claude/workflow-state.json

@@ -4,6 +4,6 @@
   "memorySearched": false,
   "sessionStart": "2026-03-23T02:45:57.764Z",
   "memoryRequired": true,
-  "interactionCount": 58,
+  "interactionCount": 59,
   "lastBlockedAt": "2026-03-24T02:39:25.674Z"
 }

package/README.md

@@ -10,6 +10,19 @@
 
 MoFlo makes your AI coding assistant remember what it learns, check what it knows before exploring files, and get smarter over time — all automatically. Install it, run `flo init`, restart your AI client, and everything just works: your docs and code are indexed on session start so the AI can search them instantly, workflow gates prevent the AI from wasting tokens on blind exploration, task outcomes feed back into routing so it picks the right agent type next time, and context depletion warnings tell you when to start a fresh session. No configuration, no API keys, no cloud services — it all runs locally on your machine.
 
+## Quickstart
+
+```bash
+npm install --save-dev moflo
+npx flo init
+```
+
+Restart Claude Code (or your MCP client). That's it — memory, indexing, gates, and routing are all active.
+
+Or — just ask Claude to install MoFlo into your project and initialize it!
+
+To verify everything is running, ask Claude to run `flo doctor` with full diagnostics after restarting. If anything fails, ask Claude to fix it with `flo doctor --fix`.
+
 ## Opinionated Defaults
 
 MoFlo makes deliberate choices so you don't have to:

package/bin/setup-project.mjs

@@ -59,6 +59,8 @@ When the user asks you to remember something: \`mcp__moflo__memory_store\` with
 - **Memory-first**: Must search memory before Glob/Grep/Read
 - **TaskCreate-first**: Must call TaskCreate before spawning Agent tool
 
+- **Task Icons**: \`TaskCreate\` MUST use ICON+[Role] format — see \`.claude/guidance/shipped/task-icons.md\`
+
 ### MCP Tools (preferred over CLI)
 
 | Tool | Purpose |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.8.22",
+  "version": "4.8.24",
   "description": "MoFlo — AI agent orchestration for Claude Code. Forked from ruflo/claude-flow with patches applied to source, plus feature-level orchestration.",
   "main": "dist/index.js",
   "type": "module",
@@ -85,7 +85,7 @@
     "@types/bcrypt": "^5.0.2",
     "@types/node": "^20.19.37",
     "eslint": "^8.0.0",
-    "moflo": "^4.8.14",
+    "moflo": "^4.8.22",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"

package/src/@claude-flow/cli/dist/src/commands/doctor.js

@@ -95,7 +95,19 @@ async function checkConfigFile() {
 // PID + command-line verification (avoids Windows PID-recycling false positives).
 async function checkDaemonStatus() {
     try {
-        const holderPid = getDaemonLockHolder(process.cwd());
+        // Retry up to 5 times with 1s delay — the daemon starts in the background
+        // during session-start and may not have acquired its lock file yet.
+        const MAX_RETRIES = 5;
+        const RETRY_DELAY_MS = 1000;
+        let holderPid = null;
+        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+            holderPid = getDaemonLockHolder(process.cwd());
+            if (holderPid)
+                break;
+            if (attempt < MAX_RETRIES - 1) {
+                await new Promise(resolve => setTimeout(resolve, RETRY_DELAY_MS));
+            }
+        }
         if (holderPid) {
             return { name: 'Daemon Status', status: 'pass', message: `Running (PID: ${holderPid})` };
         }

package/src/@claude-flow/cli/dist/src/commands/init.js

@@ -252,14 +252,9 @@ const initAction = async (ctx) => {
             }
         }
         if (!startDaemon && !startAll) {
-            // Next steps (only if not auto-starting)
-            output.writeln(output.bold('Next steps:'));
-            output.printList([
-                `Restart Claude Code to activate hooks and index guidance/code (recommended)`,
-                `Or run ${output.highlight('claude-flow init --start-all')} to start services and index now`,
-                `Run ${output.highlight('claude-flow daemon start')} to start background workers`,
-                options.components.settings ? `Review ${output.highlight('.claude/settings.json')} for hook configurations` : '',
-            ].filter(Boolean));
+            output.writeln();
+            output.writeln(output.bold('Restart Claude Code to activate MoFlo.'));
+            output.writeln(output.dim(`Edit ${output.highlight('moflo.yaml')} to tweak settings.`));
         }
         if (ctx.flags.format === 'json') {
             output.printJson(result);

package/src/@claude-flow/cli/dist/src/init/claudemd-generator.js

@@ -35,6 +35,8 @@ When the user asks you to remember something: \`mcp__moflo__memory_store\` with
 - **Memory-first**: Must search memory before Glob/Grep/Read
 - **TaskCreate-first**: Must call TaskCreate before spawning Agent tool
 
+- **Task Icons**: \`TaskCreate\` MUST use ICON+[Role] format — see \`.claude/guidance/shipped/task-icons.md\`
+
 ### MCP Tools (preferred over CLI)
 
 | Tool | Purpose |

package/src/@claude-flow/cli/dist/src/init/moflo-init.js

@@ -241,6 +241,8 @@ export async function initMoflo(options) {
     steps.push(updateGitignore(projectRoot));
     // Step 7: .claude/guidance/moflo-bootstrap.md (subagent bootstrap protocol)
     steps.push(syncBootstrapGuidance(projectRoot, force));
+    // Step 8: Sync ALL shipped guidance docs from moflo to project
+    steps.push(...syncAllShippedGuidance(projectRoot, force));
     return { steps };
 }
 // ============================================================================
@@ -645,10 +647,8 @@ function generateClaudeMd(root, force) {
         const allEndMarkers = [MOFLO_MARKER_END, ...LEGACY_MARKERS_END];
         for (let i = 0; i < allStartMarkers.length; i++) {
             if (existing.includes(allStartMarkers[i])) {
-                if (!force && allStartMarkers[i] === MOFLO_MARKER) {
-                    return { name: 'CLAUDE.md', status: 'skipped', detail: 'MoFlo section already present' };
-                }
-                // Remove existing section for replacement
+                // Always strip the existing section so we can re-inject the latest version.
+                // This ensures CLAUDE.md stays current when moflo updates its injected content.
                 const startIdx = existing.indexOf(allStartMarkers[i]);
                 const endIdx = existing.indexOf(allEndMarkers[i]);
                 if (endIdx > startIdx) {
@@ -680,6 +680,7 @@ When the user asks you to remember something: \`mcp__moflo__memory_store\` with
 
 - **Memory-first**: Must search memory before Glob/Grep/Read
 - **TaskCreate-first**: Must call TaskCreate before spawning Agent tool
+- **Task Icons**: \`TaskCreate\` MUST use ICON+[Role] format — see \`.claude/guidance/shipped/task-icons.md\`
 
 ### MCP Tools (preferred over CLI)
 
@@ -846,4 +847,59 @@ function syncBootstrapGuidance(root, force) {
         detail: 'Subagent bootstrap protocol'
     };
 }
+// ============================================================================
+// Step 8: Sync ALL shipped guidance docs
+// Discovers all .md files in moflo/.claude/guidance/shipped/ and copies them
+// to project .claude/guidance/. Skips agent-bootstrap.md (handled by Step 7).
+// ============================================================================
+function syncAllShippedGuidance(root, force) {
+    const guidanceDir = path.join(root, '.claude', 'guidance');
+    let sourceDir;
+    try {
+        sourceDir = path.dirname(fileURLToPath(import.meta.url));
+    }
+    catch {
+        sourceDir = typeof __dirname !== 'undefined' ? __dirname : '';
+    }
+    // Find the shipped guidance directory
+    const shippedCandidates = [
+        path.join(root, 'node_modules', 'moflo', '.claude', 'guidance', 'shipped'),
+        ...(sourceDir ? [path.join(sourceDir, '..', '..', '..', '..', '.claude', 'guidance', 'shipped')] : []),
+    ];
+    const shippedDir = shippedCandidates.find(d => { try {
+        return fs.existsSync(d) && fs.statSync(d).isDirectory();
+    }
+    catch {
+        return false;
+    } });
+    if (!shippedDir) {
+        return [{ name: 'guidance/shipped/*', status: 'skipped', detail: 'Shipped guidance directory not found' }];
+    }
+    // Discover all .md files, skip agent-bootstrap.md (synced separately as moflo-bootstrap.md)
+    const files = fs.readdirSync(shippedDir).filter(f => f.endsWith('.md') && f !== 'agent-bootstrap.md');
+    if (files.length === 0) {
+        return [{ name: 'guidance/shipped/*', status: 'skipped', detail: 'No shipped guidance files found' }];
+    }
+    const results = [];
+    for (const filename of files) {
+        const sourceFile = path.join(shippedDir, filename);
+        const targetFile = path.join(guidanceDir, filename);
+        if (fs.existsSync(targetFile) && !force) {
+            if (!isStale(sourceFile, targetFile)) {
+                results.push({ name: `guidance/${filename}`, status: 'skipped', detail: 'Already up to date' });
+                continue;
+            }
+        }
+        const content = fs.readFileSync(sourceFile, 'utf-8');
+        const header = `<!-- AUTO-GENERATED by moflo init. Do not edit — changes will be overwritten on next init. -->\n<!-- Source: moflo/.claude/guidance/shipped/${filename} -->\n\n`;
+        fs.mkdirSync(guidanceDir, { recursive: true });
+        fs.writeFileSync(targetFile, header + content, 'utf-8');
+        results.push({
+            name: `guidance/${filename}`,
+            status: 'updated',
+            detail: `Shipped guidance synced`,
+        });
+    }
+    return results;
+}
 //# sourceMappingURL=moflo-init.js.map

package/src/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moflo/cli",
-  "version": "4.8.22",
+  "version": "4.8.24",
   "type": "module",
   "description": "MoFlo CLI — AI agent orchestration with specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",