moflo 4.0.0 → 4.0.2

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

@@ -0,0 +1,122 @@
+# MoFlo Agent Bootstrap Guide
+
+**Purpose:** Quick-start reference for subagents spawned by coordinators. Every subagent should follow this protocol before doing any work.
+
+---
+
+## 1. Search Memory FIRST
+
+**Before reading any files or exploring code, search memory for guidance relevant to your task.**
+
+### Two namespaces to search:
+
+| Namespace | When to search | What it returns |
+|-----------|---------------|-----------------|
+| `guidance` | Understanding patterns, rules, conventions | Guidance docs, coding rules, domain context |
+| `code-map` | Finding where code lives (files, types, services) | Project overviews, directory contents, type locations |
+
+**Search `code-map` BEFORE using Glob/Grep for navigation.** It's faster and returns structured results.
+
+### Option A: MCP Tools (Preferred)
+
+If you have MCP tools available (check for `mcp__claude-flow__*`), use them directly:
+
+| Tool | Purpose |
+|------|---------|
+| `mcp__claude-flow__memory_search` | Semantic search with domain-aware embeddings |
+| `mcp__claude-flow__memory_store` | Store patterns with auto-vectorization |
+| `mcp__claude-flow__hooks_route` | Get agent routing suggestions |
+
+### Option B: CLI via Bash
+
+```bash
+npx moflo memory search --query "[describe your task]" --namespace guidance --limit 5
+```
+
+| Your task involves... | Search namespace | Example query |
+|-----------------------|------------------|---------------|
+| Database/entities | `guidance` | `"database entity migration"` |
+| Frontend components | `guidance` | `"React frontend component"` |
+| API endpoints | `guidance` | `"API route endpoint pattern"` |
+| Authentication | `guidance` | `"auth middleware JWT"` |
+| Unit tests | `guidance` | `"test mock vitest"` |
+| Where is a file/type? | `code-map` | `"service entity location"` |
+| What's in a directory? | `code-map` | `"back-office api routes"` |
+
+Use results with score > 0.3. If no good results, fall back to reading project guidance docs.
+
+---
+
+## 2. Check Project-Specific Bootstrap
+
+**After reading this file, check for a project-specific bootstrap:**
+
+```bash
+# 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.
+
+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 always takes precedence over generic patterns.
+
+---
+
+## 3. Universal Rules
+
+### Memory Protocol
+- Search memory before exploring files
+- Store discoveries back to memory when done
+- Use `patterns` namespace for solutions and gotchas
+- Use `decisions` namespace for architectural choices
+
+### Git/Branches
+- Use conventional commit prefixes: `feat:`, `fix:`, `refactor:`, `test:`, `chore:`
+- Use branch prefixes: `feature/`, `fix/`, `refactor/`
+- Use kebab-case for branch names
+
+### File Organization
+- Never save working files to repository root
+- Keep changes focused (3-10 files)
+- Stay within feature scope
+
+### Build & Test
+- Build and test after code changes
+- Never leave failing tests
+
+---
+
+## 4. Store Discoveries
+
+If you discover something new (pattern, solution, gotcha), store it:
+
+### MCP (Preferred):
+```
+mcp__claude-flow__memory_store
+  namespace: "patterns"
+  key: "brief-descriptive-key"
+  value: "1-2 sentence insight"
+```
+
+### CLI Fallback:
+```bash
+npx moflo memory store --namespace patterns --key "brief-descriptive-key" --value "1-2 sentence insight"
+```
+
+**Store:** Solutions to tricky bugs, patterns that worked, gotchas, workarounds
+**Skip:** Summaries of retrieved guidance, general rules, file locations
+
+---
+
+## 5. When Complete
+
+1. Report findings to coordinator
+2. Store learnings if you discovered something new
+3. Coordinator will mark your task as completed

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.0",
+  "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",