moflo 4.8.42 → 4.8.44

package/bin/setup-project.mjs

@@ -1,253 +1,253 @@
 #!/usr/bin/env node
-/**
- * MoFlo Project Setup
- *
- * Copies the agent-bootstrap guidance into the consuming project and
- * adds a CLAUDE.md section so subagents automatically follow the protocol.
- *
- * Usage:
- *   npx flo-setup            # First-time setup
- *   npx flo-setup --update   # Refresh bootstrap file after moflo upgrade
- *   npx flo-setup --check    # Check if setup is current
- *
- * What it does:
- *   1. Copies .claude/guidance/agent-bootstrap.md → project's .claude/guidance/moflo-bootstrap.md
- *   2. Appends a subagent protocol section to CLAUDE.md (idempotent, with markers)
- *
- * The project can layer its own .claude/guidance/agent-bootstrap.md on top for
- * project-specific rules (companyId, entity templates, etc.).
- */
-
-import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'node:fs';
-import { dirname, resolve, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const mofloRoot = resolve(__dirname, '..');
-
-const args = process.argv.slice(2);
-const updateOnly = args.includes('--update');
-const checkOnly = args.includes('--check');
-
-// Markers for idempotent CLAUDE.md updates — keep in sync with claudemd-generator.ts
-const MARKER_START = '<!-- MOFLO:INJECTED:START -->';
-const MARKER_END = '<!-- MOFLO:INJECTED:END -->';
-// Legacy markers to detect and replace
-const LEGACY_STARTS = ['<!-- MOFLO:SUBAGENT-PROTOCOL:START -->', '<!-- MOFLO:START -->'];
-const LEGACY_ENDS = ['<!-- MOFLO:SUBAGENT-PROTOCOL:END -->', '<!-- MOFLO:END -->'];
-
-// Minimal injection — just enough for Claude to work with moflo.
-// All detailed docs live in .claude/guidance/shipped/moflo.md.
-const CLAUDE_MD_SECTION = `${MARKER_START}
-## MoFlo — AI Agent Orchestration
-
-This project uses [MoFlo](https://github.com/eric-cielo/moflo) for AI-assisted development workflows.
-
-### FIRST ACTION ON EVERY PROMPT: Search Memory
-
-Your first tool call for every new user prompt MUST be a memory search. Do this BEFORE Glob, Grep, Read, or any file exploration.
-
-\`\`\`
-mcp__moflo__memory_search — query: "<task description>", namespace: "guidance" or "patterns" or "code-map"
-\`\`\`
-
-Search \`guidance\` and \`patterns\` namespaces on every prompt. Search \`code-map\` when navigating the codebase.
-When the user asks you to remember something: \`mcp__moflo__memory_store\` with namespace \`knowledge\`.
-
-### Workflow Gates (enforced automatically)
-
-- **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/task-icons.md\`
-
-### MCP Tools (preferred over CLI)
-
-| Tool | Purpose |
-|------|---------|
-| \`mcp__moflo__memory_search\` | Semantic search across indexed knowledge |
-| \`mcp__moflo__memory_store\` | Store patterns and decisions |
-| \`mcp__moflo__hooks_route\` | Route task to optimal agent type |
-| \`mcp__moflo__hooks_pre-task\` | Record task start |
-| \`mcp__moflo__hooks_post-task\` | Record task completion for learning |
-
-### CLI Fallback
-
-\`\`\`bash
-npx flo-search "[query]" --namespace guidance   # Semantic search
-npx flo doctor --fix                             # Health check
-\`\`\`
-
-### Full Reference
-
-For CLI commands, hooks, agents, swarm config, memory commands, and moflo.yaml options, see:
-\`.claude/guidance/shipped/moflo.md\`
-${MARKER_END}`;
-
-function log(msg) {
-  console.log(`[flo-setup] ${msg}`);
-}
-
-function findProjectRoot() {
-  // Walk up from cwd looking for package.json that depends on moflo
-  let dir = process.cwd();
-  const root = resolve(dir, '/');
-
-  while (dir !== root) {
-    const pkgPath = join(dir, 'package.json');
-    if (existsSync(pkgPath)) {
-      try {
-        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-        if (deps && deps.moflo) {
-          return dir;
-        }
-      } catch { /* ignore parse errors */ }
-    }
-    dir = dirname(dir);
-  }
-
-  // Fallback: use cwd if it has a package.json
-  if (existsSync(join(process.cwd(), 'package.json'))) {
-    return process.cwd();
-  }
-
-  return null;
-}
-
-function copyBootstrap(projectRoot) {
-  const shippedSource = join(mofloRoot, '.claude', 'guidance', 'shipped', 'agent-bootstrap.md');
-  const source = existsSync(shippedSource)
-    ? shippedSource
-    : join(mofloRoot, '.claude', 'guidance', 'agent-bootstrap.md');
-  const targetDir = join(projectRoot, '.claude', 'guidance');
-  const target = join(targetDir, 'moflo-bootstrap.md');
-
-  if (!existsSync(source)) {
-    log('❌ Source bootstrap not found in moflo package');
-    return false;
-  }
-
-  // Read source content and prepend auto-generated notice
-  const content = readFileSync(source, 'utf-8');
-  const header = `<!-- AUTO-GENERATED by flo-setup. Do not edit — changes will be overwritten. -->
-<!-- Source: node_modules/moflo/.claude/guidance/agent-bootstrap.md -->
-<!-- To customize, create .claude/guidance/agent-bootstrap.md for project-specific rules. -->
-
-`;
-
-  mkdirSync(targetDir, { recursive: true });
-
-  // Check if file exists and is current
-  if (existsSync(target)) {
-    const existing = readFileSync(target, 'utf-8');
-    const newContent = header + content;
-    if (existing === newContent) {
-      log('✅ moflo-bootstrap.md is current');
-      return true;
-    }
-    log('📝 Updating moflo-bootstrap.md');
-  } else {
-    log('📝 Creating .claude/guidance/moflo-bootstrap.md');
-  }
-
-  if (!checkOnly) {
-    writeFileSync(target, header + content, 'utf-8');
-  }
-  return true;
-}
-
-function updateClaudeMd(projectRoot) {
-  const claudeMdPath = join(projectRoot, 'CLAUDE.md');
-
-  if (!existsSync(claudeMdPath)) {
-    if (checkOnly) {
-      log('⚠️  No CLAUDE.md found');
-      return false;
-    }
-    log('📝 Creating CLAUDE.md with subagent protocol section');
-    writeFileSync(claudeMdPath, `# Project Configuration\n\n${CLAUDE_MD_SECTION}\n`, 'utf-8');
-    return true;
-  }
-
-  const content = readFileSync(claudeMdPath, 'utf-8');
-
-  // Check for current or legacy markers and replace
-  const allStarts = [MARKER_START, ...LEGACY_STARTS];
-  const allEnds = [MARKER_END, ...LEGACY_ENDS];
-
-  for (let i = 0; i < allStarts.length; i++) {
-    if (content.includes(allStarts[i])) {
-      const startIdx = content.indexOf(allStarts[i]);
-      const endIdx = content.indexOf(allEnds[i]);
-
-      if (endIdx > startIdx) {
-        // If current markers and content matches, we're up to date
-        if (i === 0) {
-          const existingSection = content.substring(startIdx, endIdx + allEnds[i].length);
-          if (existingSection === CLAUDE_MD_SECTION) {
-            log('✅ CLAUDE.md moflo section is current');
-            return true;
-          }
-        }
-
-        // Replace (current or legacy) with new section
-        if (!checkOnly) {
-          const updated = content.substring(0, startIdx) + CLAUDE_MD_SECTION + content.substring(endIdx + allEnds[i].length);
-          writeFileSync(claudeMdPath, updated, 'utf-8');
-          log(i === 0 ? '📝 Updated CLAUDE.md moflo section' : '📝 Replaced legacy CLAUDE.md section with minimal moflo injection');
-        } else {
-          log('⚠️  CLAUDE.md moflo section needs update');
-        }
-        return true;
-      }
-    }
-  }
-
-  if (updateOnly) {
-    log('⚠️  CLAUDE.md has no moflo section (run without --update to add)');
-    return false;
-  }
-
-  if (checkOnly) {
-    log('⚠️  CLAUDE.md missing subagent protocol section');
-    return false;
-  }
-
-  // Append section to end of CLAUDE.md
-  const separator = content.endsWith('\n') ? '\n' : '\n\n';
-  writeFileSync(claudeMdPath, content + separator + CLAUDE_MD_SECTION + '\n', 'utf-8');
-  log('📝 Added subagent protocol section to CLAUDE.md');
-  return true;
-}
-
-function main() {
-  console.log('');
-  console.log('MoFlo Project Setup');
-  console.log('───────────────────');
-
-  const projectRoot = findProjectRoot();
-  if (!projectRoot) {
-    log('❌ Could not find project root (no package.json with moflo dependency)');
-    process.exit(1);
-  }
-
-  log(`Project: ${projectRoot}`);
-  console.log('');
-
-  // Step 1: Copy bootstrap file
-  const bootstrapOk = copyBootstrap(projectRoot);
-
-  // Step 2: Update CLAUDE.md (skip on --update, only refresh the file)
-  const claudeOk = updateOnly ? true : updateClaudeMd(projectRoot);
-
-  console.log('');
-  if (checkOnly) {
-    log(bootstrapOk && claudeOk ? '✅ Setup is current' : '⚠️  Setup needs attention');
-  } else {
-    log('✅ Done. Subagents will now follow the MoFlo bootstrap protocol.');
-  }
-  console.log('');
-}
-
-main();
+/**
+ * MoFlo Project Setup
+ *
+ * Copies the subagents guidance into the consuming project and
+ * adds a CLAUDE.md section so subagents automatically follow the protocol.
+ *
+ * Usage:
+ *   npx flo-setup            # First-time setup
+ *   npx flo-setup --update   # Refresh bootstrap file after moflo upgrade
+ *   npx flo-setup --check    # Check if setup is current
+ *
+ * What it does:
+ *   1. Copies .claude/guidance/subagents.md → project's .claude/guidance/moflo-bootstrap.md
+ *   2. Appends a subagent protocol section to CLAUDE.md (idempotent, with markers)
+ *
+ * The project can layer its own .claude/guidance/subagents.md on top for
+ * project-specific rules (companyId, entity templates, etc.).
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'node:fs';
+import { dirname, resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const mofloRoot = resolve(__dirname, '..');
+
+const args = process.argv.slice(2);
+const updateOnly = args.includes('--update');
+const checkOnly = args.includes('--check');
+
+// Markers for idempotent CLAUDE.md updates — keep in sync with claudemd-generator.ts
+const MARKER_START = '<!-- MOFLO:INJECTED:START -->';
+const MARKER_END = '<!-- MOFLO:INJECTED:END -->';
+// Legacy markers to detect and replace
+const LEGACY_STARTS = ['<!-- MOFLO:SUBAGENT-PROTOCOL:START -->', '<!-- MOFLO:START -->'];
+const LEGACY_ENDS = ['<!-- MOFLO:SUBAGENT-PROTOCOL:END -->', '<!-- MOFLO:END -->'];
+
+// Minimal injection — just enough for Claude to work with moflo.
+// All detailed docs live in .claude/guidance/shipped/moflo.md.
+const CLAUDE_MD_SECTION = `${MARKER_START}
+## MoFlo — AI Agent Orchestration
+
+This project uses [MoFlo](https://github.com/eric-cielo/moflo) for AI-assisted development workflows.
+
+### FIRST ACTION ON EVERY PROMPT: Search Memory
+
+Your first tool call for every new user prompt MUST be a memory search. Do this BEFORE Glob, Grep, Read, or any file exploration.
+
+\`\`\`
+mcp__moflo__memory_search — query: "<task description>", namespace: "guidance" or "patterns" or "code-map"
+\`\`\`
+
+Search \`guidance\` and \`patterns\` namespaces on every prompt. Search \`code-map\` when navigating the codebase.
+When the user asks you to remember something: \`mcp__moflo__memory_store\` with namespace \`knowledge\`.
+
+### Workflow Gates (enforced automatically)
+
+- **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/task-icons.md\`
+
+### MCP Tools (preferred over CLI)
+
+| Tool | Purpose |
+|------|---------|
+| \`mcp__moflo__memory_search\` | Semantic search across indexed knowledge |
+| \`mcp__moflo__memory_store\` | Store patterns and decisions |
+| \`mcp__moflo__hooks_route\` | Route task to optimal agent type |
+| \`mcp__moflo__hooks_pre-task\` | Record task start |
+| \`mcp__moflo__hooks_post-task\` | Record task completion for learning |
+
+### CLI Fallback
+
+\`\`\`bash
+npx flo-search "[query]" --namespace guidance   # Semantic search
+npx flo doctor --fix                             # Health check
+\`\`\`
+
+### Full Reference
+
+For CLI commands, hooks, agents, swarm config, memory commands, and moflo.yaml options, see:
+\`.claude/guidance/shipped/moflo.md\`
+${MARKER_END}`;
+
+function log(msg) {
+  console.log(`[flo-setup] ${msg}`);
+}
+
+function findProjectRoot() {
+  // Walk up from cwd looking for package.json that depends on moflo
+  let dir = process.cwd();
+  const root = resolve(dir, '/');
+
+  while (dir !== root) {
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        if (deps && deps.moflo) {
+          return dir;
+        }
+      } catch { /* ignore parse errors */ }
+    }
+    dir = dirname(dir);
+  }
+
+  // Fallback: use cwd if it has a package.json
+  if (existsSync(join(process.cwd(), 'package.json'))) {
+    return process.cwd();
+  }
+
+  return null;
+}
+
+function copyBootstrap(projectRoot) {
+  const shippedSource = join(mofloRoot, '.claude', 'guidance', 'shipped', 'subagents.md');
+  const source = existsSync(shippedSource)
+    ? shippedSource
+    : join(mofloRoot, '.claude', 'guidance', 'subagents.md');
+  const targetDir = join(projectRoot, '.claude', 'guidance');
+  const target = join(targetDir, 'moflo-bootstrap.md');
+
+  if (!existsSync(source)) {
+    log('❌ Source bootstrap not found in moflo package');
+    return false;
+  }
+
+  // Read source content and prepend auto-generated notice
+  const content = readFileSync(source, 'utf-8');
+  const header = `<!-- AUTO-GENERATED by flo-setup. Do not edit — changes will be overwritten. -->
+<!-- Source: node_modules/moflo/.claude/guidance/subagents.md -->
+<!-- To customize, create .claude/guidance/subagents.md for project-specific rules. -->
+
+`;
+
+  mkdirSync(targetDir, { recursive: true });
+
+  // Check if file exists and is current
+  if (existsSync(target)) {
+    const existing = readFileSync(target, 'utf-8');
+    const newContent = header + content;
+    if (existing === newContent) {
+      log('✅ moflo-bootstrap.md is current');
+      return true;
+    }
+    log('📝 Updating moflo-bootstrap.md');
+  } else {
+    log('📝 Creating .claude/guidance/moflo-bootstrap.md');
+  }
+
+  if (!checkOnly) {
+    writeFileSync(target, header + content, 'utf-8');
+  }
+  return true;
+}
+
+function updateClaudeMd(projectRoot) {
+  const claudeMdPath = join(projectRoot, 'CLAUDE.md');
+
+  if (!existsSync(claudeMdPath)) {
+    if (checkOnly) {
+      log('⚠️  No CLAUDE.md found');
+      return false;
+    }
+    log('📝 Creating CLAUDE.md with subagent protocol section');
+    writeFileSync(claudeMdPath, `# Project Configuration\n\n${CLAUDE_MD_SECTION}\n`, 'utf-8');
+    return true;
+  }
+
+  const content = readFileSync(claudeMdPath, 'utf-8');
+
+  // Check for current or legacy markers and replace
+  const allStarts = [MARKER_START, ...LEGACY_STARTS];
+  const allEnds = [MARKER_END, ...LEGACY_ENDS];
+
+  for (let i = 0; i < allStarts.length; i++) {
+    if (content.includes(allStarts[i])) {
+      const startIdx = content.indexOf(allStarts[i]);
+      const endIdx = content.indexOf(allEnds[i]);
+
+      if (endIdx > startIdx) {
+        // If current markers and content matches, we're up to date
+        if (i === 0) {
+          const existingSection = content.substring(startIdx, endIdx + allEnds[i].length);
+          if (existingSection === CLAUDE_MD_SECTION) {
+            log('✅ CLAUDE.md moflo section is current');
+            return true;
+          }
+        }
+
+        // Replace (current or legacy) with new section
+        if (!checkOnly) {
+          const updated = content.substring(0, startIdx) + CLAUDE_MD_SECTION + content.substring(endIdx + allEnds[i].length);
+          writeFileSync(claudeMdPath, updated, 'utf-8');
+          log(i === 0 ? '📝 Updated CLAUDE.md moflo section' : '📝 Replaced legacy CLAUDE.md section with minimal moflo injection');
+        } else {
+          log('⚠️  CLAUDE.md moflo section needs update');
+        }
+        return true;
+      }
+    }
+  }
+
+  if (updateOnly) {
+    log('⚠️  CLAUDE.md has no moflo section (run without --update to add)');
+    return false;
+  }
+
+  if (checkOnly) {
+    log('⚠️  CLAUDE.md missing subagent protocol section');
+    return false;
+  }
+
+  // Append section to end of CLAUDE.md
+  const separator = content.endsWith('\n') ? '\n' : '\n\n';
+  writeFileSync(claudeMdPath, content + separator + CLAUDE_MD_SECTION + '\n', 'utf-8');
+  log('📝 Added subagent protocol section to CLAUDE.md');
+  return true;
+}
+
+function main() {
+  console.log('');
+  console.log('MoFlo Project Setup');
+  console.log('───────────────────');
+
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    log('❌ Could not find project root (no package.json with moflo dependency)');
+    process.exit(1);
+  }
+
+  log(`Project: ${projectRoot}`);
+  console.log('');
+
+  // Step 1: Copy bootstrap file
+  const bootstrapOk = copyBootstrap(projectRoot);
+
+  // Step 2: Update CLAUDE.md (skip on --update, only refresh the file)
+  const claudeOk = updateOnly ? true : updateClaudeMd(projectRoot);
+
+  console.log('');
+  if (checkOnly) {
+    log(bootstrapOk && claudeOk ? '✅ Setup is current' : '⚠️  Setup needs attention');
+  } else {
+    log('✅ Done. Subagents will now follow the MoFlo bootstrap protocol.');
+  }
+  console.log('');
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.8.42",
+  "version": "4.8.44",
   "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",

package/src/@claude-flow/cli/README.md

@@ -162,11 +162,11 @@ flo gate session-reset           # Reset workflow state
 Sequence multiple GitHub issues through `/flo` workflows using a YAML definition:
 
 ```bash
-flo orc run feature.yaml              # Execute a feature (stories in dependency order)
-flo orc run feature.yaml --dry-run    # Show execution plan without running
-flo orc run feature.yaml --verbose    # Execute with Claude output streaming
-flo orc status my-feature             # Check progress of a feature
-flo orc reset my-feature              # Reset feature state for re-run
+flo epic run feature.yaml              # Execute a feature (stories in dependency order)
+flo epic run feature.yaml --dry-run    # Show execution plan without running
+flo epic run feature.yaml --verbose    # Execute with Claude output streaming
+flo epic status my-feature             # Check progress of a feature
+flo epic reset my-feature              # Reset feature state for re-run
 ```
 
 Feature YAML example:
@@ -409,7 +409,7 @@ Here's how a typical task flows through both layers:
 
 The key insight: **your client handles execution, MoFlo handles knowledge.** Your client is good at spawning agents and running code. MoFlo is good at remembering what happened, routing to the right agent, and ensuring prior knowledge is checked before exploring from scratch.
 
-For complex work, MoFlo structures tasks into waves — a research wave discovers context, then an implementation wave acts on it — with dependencies tracked through both the client's task system and MoFlo's coordination layer. The full integration pattern is documented in `.claude/guidance/task-swarm-integration.md`.
+For complex work, MoFlo structures tasks into waves — a research wave discovers context, then an implementation wave acts on it — with dependencies tracked through both the client's task system and MoFlo's coordination layer. The full integration pattern is documented in `.claude/guidance/moflo-claude-swarm-cohesion.md`.
 
 The `/flo` skill ties both systems together for GitHub issues — driving a full workflow (research → enhance → implement → test → simplify → PR) with your client's agents for execution and MoFlo's memory for continuity.