moflo 4.0.1 → 4.0.2

package/.claude/guidance/agent-bootstrap.md

@@ -47,19 +47,25 @@ Use results with score > 0.3. If no good results, fall back to reading project g
 
 ---
 
-## 2. Check Project Guidance
+## 2. Check Project-Specific Bootstrap
 
-If memory search doesn't return useful results, look for project-level guidance:
+**After reading this file, check for a project-specific bootstrap:**
 
 ```bash
-# Check if project has guidance docs
-ls .claude/guidance/ 2>/dev/null
+# Project-specific bootstrap (has domain rules, patterns, templates)
+cat .claude/guidance/agent-bootstrap.md 2>/dev/null | head -10
+```
+
+If `.claude/guidance/agent-bootstrap.md` exists, **read it next**. It contains project-specific rules (entity patterns, multi-tenancy, tech stack conventions) that override generic guidance.
 
-# Check if project has a core index
+If no project bootstrap exists, look for general project guidance:
+
+```bash
+ls .claude/guidance/ 2>/dev/null
 cat .claude/guidance/core.md 2>/dev/null | head -50
 ```
 
-Project guidance takes precedence over generic patterns.
+Project guidance always takes precedence over generic patterns.
 
 ---
 

package/bin/setup-project.mjs

@@ -0,0 +1,201 @@
+#!/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 moflo-setup            # First-time setup
+ *   npx moflo-setup --update   # Refresh bootstrap file after moflo upgrade
+ *   npx moflo-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
+const MARKER_START = '<!-- MOFLO:SUBAGENT-PROTOCOL:START -->';
+const MARKER_END = '<!-- MOFLO:SUBAGENT-PROTOCOL:END -->';
+
+const CLAUDE_MD_SECTION = `${MARKER_START}
+## Subagent Protocol (MoFlo)
+
+All subagents MUST read \`.claude/guidance/moflo-bootstrap.md\` before starting any work.
+It contains the memory-first protocol, discovery storage rules, and universal conventions.
+
+If \`.claude/guidance/agent-bootstrap.md\` also exists, read it next for project-specific rules.
+${MARKER_END}`;
+
+function log(msg) {
+  console.log(`[moflo-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 source = 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 moflo-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 if markers already exist
+  if (content.includes(MARKER_START)) {
+    // Extract existing section and compare
+    const startIdx = content.indexOf(MARKER_START);
+    const endIdx = content.indexOf(MARKER_END);
+
+    if (endIdx > startIdx) {
+      const existingSection = content.substring(startIdx, endIdx + MARKER_END.length);
+      if (existingSection === CLAUDE_MD_SECTION) {
+        log('✅ CLAUDE.md subagent section is current');
+        return true;
+      }
+
+      // Update existing section
+      if (!checkOnly) {
+        const updated = content.substring(0, startIdx) + CLAUDE_MD_SECTION + content.substring(endIdx + MARKER_END.length);
+        writeFileSync(claudeMdPath, updated, 'utf-8');
+        log('📝 Updated CLAUDE.md subagent protocol section');
+      } else {
+        log('⚠️  CLAUDE.md subagent 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,11 +1,12 @@
 {
   "name": "moflo",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "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",
   "bin": {
     "moflo": "./bin/cli.js",
+    "moflo-setup": "./bin/setup-project.mjs",
     "claude-flow": "./bin/cli.js"
   },
   "homepage": "https://github.com/eric-cielo/moflo#readme",