claude-flow-guidance-implementation 0.1.0

package/.claude/commands/sparc/swarm-coordinator.md

@@ -0,0 +1,54 @@
+# SPARC Swarm Coordinator Mode
+
+## Purpose
+Specialized swarm management with batch coordination capabilities.
+
+## Activation
+
+### Option 1: Using MCP Tools (Preferred in Claude Code)
+```javascript
+mcp__claude-flow__sparc_mode {
+  mode: "swarm-coordinator",
+  task_description: "manage development swarm",
+  options: {
+    topology: "hierarchical",
+    max_agents: 10
+  }
+}
+```
+
+### Option 2: Using NPX CLI (Fallback when MCP not available)
+```bash
+# Use when running from terminal or MCP tools unavailable
+npx claude-flow sparc run swarm-coordinator "manage development swarm"
+
+# For alpha features
+npx claude-flow@alpha sparc run swarm-coordinator "manage development swarm"
+```
+
+### Option 3: Local Installation
+```bash
+# If claude-flow is installed locally
+./claude-flow sparc run swarm-coordinator "manage development swarm"
+```
+
+## Core Capabilities
+- Swarm initialization
+- Agent management
+- Task distribution
+- Load balancing
+- Result collection
+
+## Coordination Modes
+- Hierarchical swarms
+- Mesh networks
+- Pipeline coordination
+- Adaptive strategies
+- Hybrid approaches
+
+## Management Features
+- Dynamic scaling
+- Resource optimization
+- Failure recovery
+- Performance monitoring
+- Quality assurance

package/.claude/commands/sparc/tdd.md

@@ -0,0 +1,54 @@
+# SPARC TDD Mode
+
+## Purpose
+Test-driven development with TodoWrite planning and comprehensive testing.
+
+## Activation
+
+### Option 1: Using MCP Tools (Preferred in Claude Code)
+```javascript
+mcp__claude-flow__sparc_mode {
+  mode: "tdd",
+  task_description: "shopping cart feature",
+  options: {
+    coverage_target: 90,
+    test_framework: "jest"
+  }
+}
+```
+
+### Option 2: Using NPX CLI (Fallback when MCP not available)
+```bash
+# Use when running from terminal or MCP tools unavailable
+npx claude-flow sparc run tdd "shopping cart feature"
+
+# For alpha features
+npx claude-flow@alpha sparc run tdd "shopping cart feature"
+```
+
+### Option 3: Local Installation
+```bash
+# If claude-flow is installed locally
+./claude-flow sparc run tdd "shopping cart feature"
+```
+
+## Core Capabilities
+- Test-first development
+- Red-green-refactor cycle
+- Test suite design
+- Coverage optimization
+- Continuous testing
+
+## TDD Workflow
+1. Write failing tests
+2. Implement minimum code
+3. Make tests pass
+4. Refactor code
+5. Repeat cycle
+
+## Testing Strategies
+- Unit testing
+- Integration testing
+- End-to-end testing
+- Performance testing
+- Security testing

package/.claude/commands/sparc/tester.md

@@ -0,0 +1,54 @@
+# SPARC Tester Mode
+
+## Purpose
+Comprehensive testing with parallel execution capabilities.
+
+## Activation
+
+### Option 1: Using MCP Tools (Preferred in Claude Code)
+```javascript
+mcp__claude-flow__sparc_mode {
+  mode: "tester",
+  task_description: "full regression suite",
+  options: {
+    parallel: true,
+    coverage: true
+  }
+}
+```
+
+### Option 2: Using NPX CLI (Fallback when MCP not available)
+```bash
+# Use when running from terminal or MCP tools unavailable
+npx claude-flow sparc run tester "full regression suite"
+
+# For alpha features
+npx claude-flow@alpha sparc run tester "full regression suite"
+```
+
+### Option 3: Local Installation
+```bash
+# If claude-flow is installed locally
+./claude-flow sparc run tester "full regression suite"
+```
+
+## Core Capabilities
+- Test planning
+- Test execution
+- Bug detection
+- Coverage analysis
+- Report generation
+
+## Test Types
+- Unit tests
+- Integration tests
+- E2E tests
+- Performance tests
+- Security tests
+
+## Parallel Features
+- Concurrent test runs
+- Distributed testing
+- Load testing
+- Cross-browser testing
+- Multi-environment validation

package/.claude/commands/sparc/tutorial.md

@@ -0,0 +1,79 @@
+---
+name: sparc-tutorial
+description: 📘 SPARC Tutorial - You are the SPARC onboarding and education assistant. Your job is to guide users through the full...
+---
+
+# 📘 SPARC Tutorial
+
+## Role Definition
+You are the SPARC onboarding and education assistant. Your job is to guide users through the full SPARC development process using structured thinking models. You help users understand how to navigate complex projects using the specialized SPARC modes and properly formulate tasks using new_task.
+
+## Custom Instructions
+You teach developers how to apply the SPARC methodology through actionable examples and mental models.
+
+## Available Tools
+- **read**: File reading and viewing
+
+## Usage
+
+### Option 1: Using MCP Tools (Preferred in Claude Code)
+```javascript
+mcp__claude-flow__sparc_mode {
+  mode: "tutorial",
+  task_description: "guide me through SPARC methodology",
+  options: {
+    namespace: "tutorial",
+    non_interactive: false
+  }
+}
+```
+
+### Option 2: Using NPX CLI (Fallback when MCP not available)
+```bash
+# Use when running from terminal or MCP tools unavailable
+npx claude-flow sparc run tutorial "guide me through SPARC methodology"
+
+# For alpha features
+npx claude-flow@alpha sparc run tutorial "guide me through SPARC methodology"
+
+# With namespace
+npx claude-flow sparc run tutorial "your task" --namespace tutorial
+
+# Non-interactive mode
+npx claude-flow sparc run tutorial "your task" --non-interactive
+```
+
+### Option 3: Local Installation
+```bash
+# If claude-flow is installed locally
+./claude-flow sparc run tutorial "guide me through SPARC methodology"
+```
+
+## Memory Integration
+
+### Using MCP Tools (Preferred)
+```javascript
+// Store mode-specific context
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "tutorial_context",
+  value: "important decisions",
+  namespace: "tutorial"
+}
+
+// Query previous work
+mcp__claude-flow__memory_search {
+  pattern: "tutorial",
+  namespace: "tutorial",
+  limit: 5
+}
+```
+
+### Using NPX CLI (Fallback)
+```bash
+# Store mode-specific context
+npx claude-flow memory store "tutorial_context" "important decisions" --namespace tutorial
+
+# Query previous work
+npx claude-flow memory query "tutorial" --limit 5
+```

package/.claude/commands/sparc/workflow-manager.md

@@ -0,0 +1,54 @@
+# SPARC Workflow Manager Mode
+
+## Purpose
+Process automation with TodoWrite planning and Task execution.
+
+## Activation
+
+### Option 1: Using MCP Tools (Preferred in Claude Code)
+```javascript
+mcp__claude-flow__sparc_mode {
+  mode: "workflow-manager",
+  task_description: "automate deployment",
+  options: {
+    pipeline: "ci-cd",
+    rollback_enabled: true
+  }
+}
+```
+
+### Option 2: Using NPX CLI (Fallback when MCP not available)
+```bash
+# Use when running from terminal or MCP tools unavailable
+npx claude-flow sparc run workflow-manager "automate deployment"
+
+# For alpha features
+npx claude-flow@alpha sparc run workflow-manager "automate deployment"
+```
+
+### Option 3: Local Installation
+```bash
+# If claude-flow is installed locally
+./claude-flow sparc run workflow-manager "automate deployment"
+```
+
+## Core Capabilities
+- Workflow design
+- Process automation
+- Pipeline creation
+- Event handling
+- State management
+
+## Workflow Patterns
+- Sequential flows
+- Parallel branches
+- Conditional logic
+- Loop iterations
+- Error handling
+
+## Automation Features
+- Trigger management
+- Task scheduling
+- Progress tracking
+- Result validation
+- Rollback capability

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

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * Claude Flow Hook Handler (Cross-Platform)
+ * Dispatches hook events to the appropriate helper modules.
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+const helpersDir = __dirname;
+
+function safeRequire(modulePath) {
+  try {
+    if (fs.existsSync(modulePath)) {
+      const origLog = console.log;
+      const origError = console.error;
+      console.log = () => {};
+      console.error = () => {};
+      try {
+        const mod = require(modulePath);
+        return mod;
+      } finally {
+        console.log = origLog;
+        console.error = origError;
+      }
+    }
+  } catch (e) {
+    // silently fail
+  }
+  return null;
+}
+
+const router = safeRequire(path.join(helpersDir, 'router.js'));
+const session = safeRequire(path.join(helpersDir, 'session.js'));
+const memory = safeRequire(path.join(helpersDir, 'memory.js'));
+const intelligence = safeRequire(path.join(helpersDir, 'intelligence.cjs'));
+
+const [,, command, ...args] = process.argv;
+const prompt = process.env.PROMPT || process.env.TOOL_INPUT_command || args.join(' ') || '';
+
+const handlers = {
+  'route': () => {
+    if (intelligence && intelligence.getContext) {
+      try {
+        const ctx = intelligence.getContext(prompt);
+        if (ctx) console.log(ctx);
+      } catch (e) { /* non-fatal */ }
+    }
+    if (router && router.routeTask) {
+      const result = router.routeTask(prompt);
+      var output = [];
+      output.push('[INFO] Routing task: ' + (prompt.substring(0, 80) || '(no prompt)'));
+      output.push('');
+      output.push('+------------------- Primary Recommendation -------------------+');
+      output.push('| Agent: ' + result.agent.padEnd(53) + '|');
+      output.push('| Confidence: ' + (result.confidence * 100).toFixed(1) + '%' + ' '.repeat(44) + '|');
+      output.push('| Reason: ' + result.reason.substring(0, 53).padEnd(53) + '|');
+      output.push('+--------------------------------------------------------------+');
+      console.log(output.join('\n'));
+    } else {
+      console.log('[INFO] Router not available, using default routing');
+    }
+  },
+
+  'pre-bash': () => {
+    var cmd = prompt.toLowerCase();
+    var dangerous = ['rm -rf /', 'format c:', 'del /s /q c:\\', ':(){:|:&};:'];
+    for (var i = 0; i < dangerous.length; i++) {
+      if (cmd.includes(dangerous[i])) {
+        console.error('[BLOCKED] Dangerous command detected: ' + dangerous[i]);
+        process.exit(1);
+      }
+    }
+    console.log('[OK] Command validated');
+  },
+
+  'post-edit': () => {
+    if (session && session.metric) {
+      try { session.metric('edits'); } catch (e) { /* no active session */ }
+    }
+    if (intelligence && intelligence.recordEdit) {
+      try {
+        var file = process.env.TOOL_INPUT_file_path || args[0] || '';
+        intelligence.recordEdit(file);
+      } catch (e) { /* non-fatal */ }
+    }
+    console.log('[OK] Edit recorded');
+  },
+
+  'session-restore': () => {
+    if (session) {
+      var existing = session.restore && session.restore();
+      if (!existing) {
+        session.start && session.start();
+      }
+    } else {
+      console.log('[OK] Session restored: session-' + Date.now());
+    }
+    if (intelligence && intelligence.init) {
+      try {
+        var result = intelligence.init();
+        if (result && result.nodes > 0) {
+          console.log('[INTELLIGENCE] Loaded ' + result.nodes + ' patterns, ' + result.edges + ' edges');
+        }
+      } catch (e) { /* non-fatal */ }
+    }
+  },
+
+  'session-end': () => {
+    if (intelligence && intelligence.consolidate) {
+      try {
+        var result = intelligence.consolidate();
+        if (result && result.entries > 0) {
+          var msg = '[INTELLIGENCE] Consolidated: ' + result.entries + ' entries, ' + result.edges + ' edges';
+          if (result.newEntries > 0) msg += ', ' + result.newEntries + ' new';
+          msg += ', PageRank recomputed';
+          console.log(msg);
+        }
+      } catch (e) { /* non-fatal */ }
+    }
+    if (session && session.end) {
+      session.end();
+    } else {
+      console.log('[OK] Session ended');
+    }
+  },
+
+  'pre-task': () => {
+    if (session && session.metric) {
+      try { session.metric('tasks'); } catch (e) { /* no active session */ }
+    }
+    if (router && router.routeTask && prompt) {
+      var result = router.routeTask(prompt);
+      console.log('[INFO] Task routed to: ' + result.agent + ' (confidence: ' + result.confidence + ')');
+    } else {
+      console.log('[OK] Task started');
+    }
+  },
+
+  'post-task': () => {
+    if (intelligence && intelligence.feedback) {
+      try {
+        intelligence.feedback(true);
+      } catch (e) { /* non-fatal */ }
+    }
+    console.log('[OK] Task completed');
+  },
+
+  'stats': () => {
+    if (intelligence && intelligence.stats) {
+      intelligence.stats(args.includes('--json'));
+    } else {
+      console.log('[WARN] Intelligence module not available. Run session-restore first.');
+    }
+  },
+};
+
+if (command && handlers[command]) {
+  try {
+    handlers[command]();
+  } catch (e) {
+    console.log('[WARN] Hook ' + command + ' encountered an error: ' + e.message);
+  }
+} else if (command) {
+  console.log('[OK] Hook: ' + command);
+} else {
+  console.log('Usage: hook-handler.cjs <route|pre-bash|post-edit|session-restore|session-end|pre-task|post-task|stats>');
+}

package/.claude/helpers/intelligence.cjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * Intelligence Layer Stub (ADR-050)
+ * Minimal fallback — full version is copied from package source.
+ * Provides: init, getContext, recordEdit, feedback, consolidate
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DATA_DIR = path.join(process.cwd(), '.claude-flow', 'data');
+const STORE_PATH = path.join(DATA_DIR, 'auto-memory-store.json');
+const RANKED_PATH = path.join(DATA_DIR, 'ranked-context.json');
+const PENDING_PATH = path.join(DATA_DIR, 'pending-insights.jsonl');
+const SESSION_DIR = path.join(process.cwd(), '.claude-flow', 'sessions');
+const SESSION_FILE = path.join(SESSION_DIR, 'current.json');
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function readJSON(p) {
+  try { return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, "utf-8")) : null; }
+  catch { return null; }
+}
+
+function writeJSON(p, data) {
+  ensureDir(path.dirname(p));
+  fs.writeFileSync(p, JSON.stringify(data, null, 2), "utf-8");
+}
+
+// Read session context key
+function sessionGet(key) {
+  var session = readJSON(SESSION_FILE);
+  if (!session) return null;
+  return key ? (session.context || {})[key] : session.context;
+}
+
+// Write session context key
+function sessionSet(key, value) {
+  var session = readJSON(SESSION_FILE);
+  if (!session) return;
+  if (!session.context) session.context = {};
+  session.context[key] = value;
+  writeJSON(SESSION_FILE, session);
+}
+
+// Tokenize text into words
+function tokenize(text) {
+  if (!text) return [];
+  return text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter(function(w) { return w.length > 2; });
+}
+
+// Bootstrap entries from MEMORY.md files when store is empty
+function bootstrapFromMemoryFiles() {
+  var entries = [];
+  var candidates = [
+    path.join(os.homedir(), ".claude", "projects"),
+    path.join(process.cwd(), ".claude-flow", "memory"),
+    path.join(process.cwd(), ".claude", "memory"),
+  ];
+  for (var i = 0; i < candidates.length; i++) {
+    try {
+      if (!fs.existsSync(candidates[i])) continue;
+      var files = [];
+      try {
+        var items = fs.readdirSync(candidates[i], { withFileTypes: true, recursive: true });
+        for (var j = 0; j < items.length; j++) {
+          if (items[j].name === "MEMORY.md") {
+            var fp = items[j].path ? path.join(items[j].path, items[j].name) : path.join(candidates[i], items[j].name);
+            files.push(fp);
+          }
+        }
+      } catch (e) { continue; }
+      for (var k = 0; k < files.length; k++) {
+        try {
+          var content = fs.readFileSync(files[k], "utf-8");
+          var sections = content.split(/^##\s+/m).filter(function(s) { return s.trim().length > 20; });
+          for (var s = 0; s < sections.length; s++) {
+            var lines2 = sections[s].split("\n");
+            var title = lines2[0] ? lines2[0].trim() : "section-" + s;
+            entries.push({
+              id: "mem-" + entries.length,
+              content: sections[s].substring(0, 500),
+              summary: title.substring(0, 100),
+              category: "memory",
+              confidence: 0.5,
+              sourceFile: files[k],
+              words: tokenize(sections[s].substring(0, 500)),
+            });
+          }
+        } catch (e) { /* skip */ }
+      }
+    } catch (e) { /* skip */ }
+  }
+  return entries;
+}
+
+// Load entries from auto-memory-store or bootstrap from MEMORY.md
+function loadEntries() {
+  var store = readJSON(STORE_PATH);
+  if (store && store.entries && store.entries.length > 0) {
+    return store.entries.map(function(e, i) {
+      return {
+        id: e.id || ("entry-" + i),
+        content: e.content || e.value || "",
+        summary: e.summary || e.key || "",
+        category: e.category || e.namespace || "default",
+        confidence: e.confidence || 0.5,
+        sourceFile: e.sourceFile || "",
+        words: tokenize((e.content || e.value || "") + " " + (e.summary || e.key || "")),
+      };
+    });
+  }
+  return bootstrapFromMemoryFiles();
+}
+
+// Simple keyword match score
+function matchScore(promptWords, entryWords) {
+  if (!promptWords.length || !entryWords.length) return 0;
+  var entrySet = {};
+  for (var i = 0; i < entryWords.length; i++) entrySet[entryWords[i]] = true;
+  var overlap = 0;
+  for (var j = 0; j < promptWords.length; j++) {
+    if (entrySet[promptWords[j]]) overlap++;
+  }
+  var union = Object.keys(entrySet).length + promptWords.length - overlap;
+  return union > 0 ? overlap / union : 0;
+}
+
+var cachedEntries = null;
+
+module.exports = {
+  init: function() {
+    cachedEntries = loadEntries();
+    var ranked = cachedEntries.map(function(e) {
+      return { id: e.id, content: e.content, summary: e.summary, category: e.category, confidence: e.confidence, words: e.words };
+    });
+    writeJSON(RANKED_PATH, { version: 1, computedAt: Date.now(), entries: ranked });
+    return { nodes: cachedEntries.length, edges: 0 };
+  },
+
+  getContext: function(prompt) {
+    if (!prompt) return null;
+    var ranked = readJSON(RANKED_PATH);
+    var entries = (ranked && ranked.entries) || (cachedEntries || []);
+    if (!entries.length) return null;
+    var promptWords = tokenize(prompt);
+    if (!promptWords.length) return null;
+    var scored = entries.map(function(e) {
+      return { entry: e, score: matchScore(promptWords, e.words || tokenize(e.content + " " + e.summary)) };
+    }).filter(function(s) { return s.score > 0.05; });
+    scored.sort(function(a, b) { return b.score - a.score; });
+    var top = scored.slice(0, 5);
+    if (!top.length) return null;
+    var prevMatched = sessionGet("lastMatchedPatterns");
+    var matchedIds = top.map(function(s) { return s.entry.id; });
+    sessionSet("lastMatchedPatterns", matchedIds);
+    if (prevMatched && Array.isArray(prevMatched)) {
+      var newSet = {};
+      for (var i = 0; i < matchedIds.length; i++) newSet[matchedIds[i]] = true;
+    }
+    var lines2 = ["[INTELLIGENCE] Relevant patterns for this task:"];
+    for (var j = 0; j < top.length; j++) {
+      var e = top[j];
+      var conf = e.entry.confidence || 0.5;
+      var summary = (e.entry.summary || e.entry.content || "").substring(0, 80);
+      lines2.push("  * (" + conf.toFixed(2) + ") " + summary);
+    }
+    return lines2.join("\n");
+  },
+
+  recordEdit: function(file) {
+    if (!file) return;
+    ensureDir(DATA_DIR);
+    var line = JSON.stringify({ type: "edit", file: file, timestamp: Date.now() }) + "\n";
+    fs.appendFileSync(PENDING_PATH, line, "utf-8");
+  },
+
+  feedback: function(success) {
+    // Stub: no-op in minimal version
+  },
+
+  consolidate: function() {
+    var count = 0;
+    if (fs.existsSync(PENDING_PATH)) {
+      try {
+        var content = fs.readFileSync(PENDING_PATH, "utf-8").trim();
+        count = content ? content.split("\n").length : 0;
+        fs.writeFileSync(PENDING_PATH, "", "utf-8");
+      } catch (e) { /* skip */ }
+    }
+    return { entries: count, edges: 0, newEntries: 0 };
+  },
+};