moflo 4.6.7 → 4.6.9

package/.claude/helpers/auto-memory-hook.mjs

@@ -348,6 +348,10 @@ async function doStatus() {
 
 const command = process.argv[2] || 'status';
 
+// Suppress unhandled rejection warnings from dynamic import() failures
+// which can cause non-zero exit codes even when caught
+process.on('unhandledRejection', () => {});
+
 try {
   switch (command) {
     case 'import': await doImport(); break;
@@ -361,3 +365,5 @@ try {
   // Hooks must never crash Claude Code - fail silently
   dim(`Error (non-critical): ${err.message}`);
 }
+// Ensure clean exit for Claude Code hooks
+process.exit(0);

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

@@ -66,9 +66,11 @@ async function main() {
     try { hookInput = JSON.parse(stdinData); } catch (e) { /* ignore parse errors */ }
   }
 
-  // Merge stdin data into prompt resolution: prefer stdin fields, then env, then argv
+  // Merge stdin data into prompt resolution: prefer stdin fields, then env vars.
+  // NEVER fall back to argv args — shell glob expansion of braces in bash output
+  // creates junk files (#1342). Use env vars or stdin only.
   const prompt = hookInput.prompt || hookInput.command || hookInput.toolInput
-    || process.env.PROMPT || process.env.TOOL_INPUT_command || args.join(' ') || '';
+    || process.env.PROMPT || process.env.TOOL_INPUT_command || '';
 
 const handlers = {
   'route': () => {
@@ -308,4 +310,7 @@ if (command && handlers[command]) {
 
 main().catch(function(e) {
   console.log('[WARN] Hook handler error: ' + e.message);
+}).finally(function() {
+  // Ensure clean exit for Claude Code hooks
+  process.exit(0);
 });

package/.claude/helpers/intelligence.cjs

@@ -65,7 +65,8 @@ function bootstrapFromMemoryFiles() {
         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);
+            var parentDir = items[j].parentPath || items[j].path || candidates[i];
+            var fp = path.join(parentDir, items[j].name);
             files.push(fp);
           }
         }
@@ -96,15 +97,24 @@ function bootstrapFromMemoryFiles() {
 
 function loadEntries() {
   var store = readJSON(STORE_PATH);
-  if (store && store.entries && store.entries.length > 0) {
-    return store.entries.map(function(e, i) {
+  // Support both formats: flat array or { entries: [...] }
+  var entries = null;
+  if (store) {
+    if (Array.isArray(store) && store.length > 0) {
+      entries = store;
+    } else if (store.entries && store.entries.length > 0) {
+      entries = store.entries;
+    }
+  }
+  if (entries) {
+    return 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 || "",
+        sourceFile: e.sourceFile || (e.metadata && e.metadata.sourceFile) || "",
         words: tokenize((e.content || e.value || "") + " " + (e.summary || e.key || "")),
       };
     });

package/.claude/helpers/statusline.cjs

@@ -109,10 +109,24 @@ const c = {
   brightWhite: '\x1b[1;37m',
 };
 
+// Abbreviate path: ~ for home, shorten intermediate dirs
+function abbreviatePath(fullPath) {
+  const home = os.homedir();
+  let p = fullPath;
+  // Replace home dir with ~
+  if (p.startsWith(home)) {
+    p = '~' + p.slice(home.length);
+  }
+  // Normalize separators
+  p = p.replace(/\\/g, '/');
+  return p;
+}
+
 // Safe execSync with strict timeout (returns empty string on failure)
 function safeExec(cmd, timeoutMs = 2000) {
   try {
     return execSync(cmd, {
+      cwd: CWD,
       encoding: 'utf-8',
       timeout: timeoutMs,
       stdio: ['pipe', 'pipe', 'pipe'],
@@ -193,7 +207,9 @@ function getModelName() {
     const claudeConfig = readJSON(path.join(os.homedir(), '.claude.json'));
     if (claudeConfig?.projects) {
       for (const [projectPath, projectConfig] of Object.entries(claudeConfig.projects)) {
-        if (CWD === projectPath || CWD.startsWith(projectPath + '/')) {
+        const normCwd = CWD.replace(/\\/g, '/');
+        const normProject = projectPath.replace(/\\/g, '/');
+        if (normCwd === normProject || normCwd.startsWith(normProject + '/')) {
           const usage = projectConfig.lastModelUsage;
           if (usage) {
             const ids = Object.keys(usage);
@@ -666,7 +682,7 @@ function generateDashboard() {
 
   // Header: branding + dir + git
   let header = `${c.bold}${c.brightPurple}\u258A ${SL_CONFIG.branding}${c.reset}`;
-  if (SL_CONFIG.show_dir) header += `  ${c.brightWhite}${path.basename(CWD)}${c.reset}`;
+  if (SL_CONFIG.show_dir) header += `  ${c.brightWhite}${abbreviatePath(CWD)}${c.reset}`;
   if (SL_CONFIG.show_git && git.gitBranch) {
     header += `  ${c.brightBlue}\u23C7 ${git.gitBranch}${c.reset}`;
     const changes = git.modified + git.staged + git.untracked;
@@ -737,7 +753,7 @@ function generateCompactDashboard() {
 
   // Header: branding + dir + git + session
   let header = `${c.bold}${c.brightPurple}\u258A ${SL_CONFIG.branding}${c.reset}`;
-  if (SL_CONFIG.show_dir) header += `  ${c.brightWhite}${path.basename(CWD)}${c.reset}`;
+  if (SL_CONFIG.show_dir) header += `  ${c.brightWhite}${abbreviatePath(CWD)}${c.reset}`;
   if (SL_CONFIG.show_git && git.gitBranch) {
     header += `  ${c.brightBlue}\u23C7 ${git.gitBranch}${c.reset}`;
     const changes = git.modified + git.staged + git.untracked;

package/.claude/skills/flo/SKILL.md

@@ -0,0 +1,432 @@
+---
+name: flo
+description: MoFlo ticket workflow - analyze and execute GitHub issues
+arguments: "[options] <issue-number>"
+---
+
+# /flo - MoFlo Ticket Workflow
+
+Research, enhance, and execute GitHub issues automatically.
+
+**Arguments:** $ARGUMENTS
+
+## Usage
+
+```
+/flo <issue-number>                   # Full workflow with SWARM (default)
+/flo -e <issue-number>                # Enhance only: research and update ticket, then STOP
+/flo --enhance <issue-number>         # Same as -e
+/flo -r <issue-number>                # Research only: analyze issue, output findings
+/flo --research <issue-number>        # Same as -r
+```
+
+Also available as `/fl` (shorthand alias).
+
+### Execution Mode (how work is done)
+
+```
+/flo 123                              # SWARM mode (default) - multi-agent coordination
+/flo -sw 123                          # SWARM mode (explicit)
+/flo --swarm 123                      # Same as -sw
+/flo -hv 123                          # HIVE-MIND mode - consensus-based coordination
+/flo --hive 123                       # Same as -hv
+/flo -n 123                           # NAKED mode - single Claude, no agents
+/flo --naked 123                      # Same as -n
+```
+
+### Epic Handling
+
+```
+/flo 42                               # If #42 is an epic, processes all stories sequentially
+```
+
+**Epic Detection:** An issue is automatically detected as an epic if ANY of these are true:
+- Has a label matching: `epic`, `tracking`, `parent`, or `umbrella` (case-insensitive)
+- Body contains `## Stories` or `## Tasks` sections
+- Body has checklist-linked issues: `- [ ] #123`
+- Body has numbered issue references: `1. #123`
+- The issue has GitHub sub-issues (via `subIssues` API field)
+
+**Sequential Processing:** When an epic is selected:
+1. List all child stories/tasks (from checklist or linked issues)
+2. Process each story **one at a time** in order
+3. Each story goes through the full workflow (research -> enhance -> implement -> test -> PR)
+4. After each story's PR is created, move to the next story
+5. Continue until all stories are complete
+
+### Combined Examples
+
+```
+/flo 123                              # Swarm + full workflow (default) - includes ALL tests
+/flo 42                               # If #42 is epic, processes stories sequentially
+/flo -e 123                           # Swarm + enhance only (no implementation)
+/flo -hv -e 123                       # Hive-mind + enhance only
+/flo -n -r 123                        # Naked + research only
+/flo --swarm --enhance 123            # Explicit swarm + enhance only
+/flo -n 123                           # Naked + full workflow (still runs all tests)
+```
+
+## SWARM IS MANDATORY BY DEFAULT
+
+Even if a task "looks simple", you MUST use swarm coordination unless
+the user explicitly passes -n/--naked. "Simple" is a trap. Tasks have
+hidden complexity. Swarm catches it.
+
+THE ONLY WAY TO SKIP SWARM: User passes -n or --naked explicitly.
+
+## COMPREHENSIVE TESTING REQUIREMENT
+
+ALL tests MUST pass BEFORE PR creation - NO EXCEPTIONS.
+- Unit Tests: MANDATORY for all new/modified code
+- Integration Tests: MANDATORY for API endpoints and services
+- E2E Tests: MANDATORY for user-facing features
+PR CANNOT BE CREATED until all relevant tests pass.
+
+## Workflow Overview
+
+```
+Research -> Enhance -> Execute -> Testing -> Simplify -> PR+Done
+
+Research:    Fetch issue, search memory, read guidance, find files
+Enhance:     Update GitHub issue with tech analysis, affected files, impl plan
+Execute:     Assign self, create branch, implement changes
+Testing:     Unit + Integration + E2E tests (ALL MUST PASS - gate)
+Simplify:    Run /simplify on changed code (gate - must run before PR)
+PR+Done:     Create PR, update issue status, store learnings
+```
+
+### Workflow Gates
+
+| Gate | Requirement | Blocked Action |
+|------|-------------|----------------|
+| **Testing Gate** | Unit + Integration + E2E must pass | PR creation |
+| **Simplification Gate** | /simplify must run on changed files | PR creation |
+
+### Execution Mode (applies to all phases)
+
+| Mode | Description |
+|------|-------------|
+| **SWARM** (default) | Multi-agent via Task tool: researcher, coder, tester, reviewer |
+| **HIVE-MIND** (-hv) | Consensus-based coordination for architecture decisions |
+| **NAKED** (-n) | Single Claude, no agent spawning. Only when user explicitly requests. |
+
+## Phase 1: Research (-r or default first step)
+
+### 1.1 Fetch Issue Details
+```bash
+gh issue view <issue-number> --json number,title,body,labels,state,assignees,comments,milestone
+```
+
+### 1.2 Check Enhancement Status
+Look for `## Implementation Plan` marker in issue body.
+- **If present**: Issue already enhanced, skip to execute or confirm
+- **If absent**: Proceed with research and enhancement
+
+### 1.3 Search Memory FIRST
+ALWAYS search memory BEFORE reading guidance or docs files.
+Memory has file paths, context, and patterns - often all you need.
+Only read guidance files if memory search returns zero relevant results.
+
+```bash
+npx flo memory search --query "<issue title keywords>" --namespace patterns
+npx flo memory search --query "<domain keywords>" --namespace guidance
+```
+
+Or via MCP: `mcp__claude-flow__memory_search`
+
+### 1.4 Read Guidance Docs (ONLY if memory insufficient)
+**Only if memory search returned < 3 relevant results**, read guidance files:
+- Bug -> testing patterns, error handling
+- Feature -> domain model, architecture
+- UI -> frontend patterns, components
+
+### 1.5 Research Codebase
+Use Task tool with Explore agent to find:
+- Affected files and their current state
+- Related code and dependencies
+- Existing patterns to follow
+- Test coverage gaps
+
+## Phase 2: Enhance (-e includes research + enhancement)
+
+### 2.1 Build Enhancement
+Compile research into structured enhancement:
+
+**Technical Analysis** - Root cause (bugs) or approach (features), impact, risk factors
+
+**Affected Files** - Files to modify (with line numbers), new files, deletions
+
+**Implementation Plan** - Numbered steps with clear actions, dependencies, decision points
+
+**Test Plan** - Unit tests to add/update, integration tests needed, manual testing checklist
+
+**Estimates** - Complexity (Low/Medium/High), scope (# files, # new tests)
+
+### 2.2 Update GitHub Issue
+```bash
+gh issue edit <issue-number> --body "<original body + Technical Analysis + Affected Files + Implementation Plan + Test Plan + Estimates>"
+```
+
+### 2.3 Add Enhancement Comment
+```bash
+gh issue comment <issue-number> --body "Issue enhanced with implementation plan. Ready for execution."
+```
+
+## Phase 3: Execute (default, runs automatically after enhance)
+
+### 3.1 Assign Issue and Update Status
+```bash
+gh issue edit <issue-number> --add-assignee @me
+gh issue edit <issue-number> --add-label "in-progress"
+```
+
+### 3.2 Create Branch
+```bash
+git checkout main && git pull origin main
+git checkout -b <type>/<issue-number>-<short-desc>
+```
+Types: `feature/`, `fix/`, `refactor/`, `docs/`
+
+### 3.3 Implement
+Follow the implementation plan from the enhanced issue. No prompts - execute all steps.
+
+## Phase 4: Testing (MANDATORY GATE)
+
+This is NOT optional. ALL applicable test types must pass for the change type.
+WORKFLOW STOPS HERE until tests pass. No shortcuts. No exceptions.
+
+### 4.1 Write and Run Tests
+Write unit, integration, and E2E tests as appropriate for the change type.
+Use the project's existing test runner and patterns.
+
+### 4.2 Test Auto-Fix Loop
+If any tests fail, enter the auto-fix loop (max 3 retries OR 10 minutes):
+1. Run all tests
+2. If ALL pass -> proceed to simplification
+3. If ANY fail: analyze failure, fix test or implementation code, retry
+4. If retries exhausted -> STOP and report to user
+
+## Phase 4.5: Code Simplification (MANDATORY)
+
+The built-in /simplify command reviews ALL changed code for:
+- Reuse opportunities and code quality
+- Efficiency improvements
+- Consistency with existing codebase patterns
+- Preserves ALL functionality - no behavior changes
+
+If /simplify makes changes -> re-run tests to confirm nothing broke.
+If re-tests fail -> revert changes, proceed with original code.
+
+## Phase 5: Commit and PR (only after tests pass)
+
+### 5.1 Commit
+```bash
+git add <specific files>
+git commit -m "type(scope): description
+
+Closes #<issue-number>
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+```
+
+### 5.2 Create PR
+```bash
+git push -u origin <branch-name>
+gh pr create --title "type(scope): description" --body "## Summary
+<brief description>
+
+## Changes
+<bullet list>
+
+## Testing
+- [x] Unit tests pass
+- [x] Integration tests pass
+- [x] E2E tests pass
+- [ ] Manual testing done
+
+Closes #<issue-number>"
+```
+
+### 5.3 Update Issue Status
+```bash
+gh issue edit <issue-number> --remove-label "in-progress" --add-label "ready-for-review"
+gh issue comment <issue-number> --body "PR created: <pr-url>"
+```
+
+## Epic Handling
+
+### Detecting Epics
+
+An issue is an **epic** if:
+1. It has the `epic` label, OR
+2. Its body contains `## Stories` or `## Tasks` sections, OR
+3. It has linked child issues (via `- [ ] #123` checklist format)
+
+### Epic Processing Flow
+
+1. DETECT EPIC - Check labels, parse body for ## Stories / ## Tasks, extract issue references
+2. LIST ALL STORIES - Extract from checklist, order top-to-bottom as listed
+3. SEQUENTIAL PROCESSING - For each story: run full /flo workflow, wait for PR, update checklist
+4. COMPLETION - All stories have PRs, epic marked as ready-for-review
+
+ONE STORY AT A TIME - NO PARALLEL STORY EXECUTION.
+Each story must complete (PR created) before starting next.
+
+### Epic Detection Code
+
+```javascript
+function isEpic(issue) {
+  // Label-based detection (case-insensitive)
+  const epicLabels = ['epic', 'tracking', 'parent', 'umbrella'];
+  if (issue.labels?.some(l => epicLabels.includes(l.name.toLowerCase()))) return true;
+  // Section-based detection
+  if (issue.body?.includes('## Stories') || issue.body?.includes('## Tasks')) return true;
+  // Checklist-linked issues: - [ ] #123 or - [x] #123
+  if (/- \[[ x]\] #\d+/.test(issue.body)) return true;
+  // Numbered issue references: 1. #123
+  if (/\d+\.\s+#\d+/.test(issue.body)) return true;
+  // GitHub sub-issues API
+  if (issue.subIssues?.length > 0) return true;
+  return false;
+}
+
+function extractStories(epicBody) {
+  const stories = [];
+  // Checklist format: - [ ] #123
+  const checklistPattern = /- \[[ ]\] #(\d+)/g;
+  let match;
+  while ((match = checklistPattern.exec(epicBody)) !== null) {
+    stories.push(parseInt(match[1]));
+  }
+  // Numbered format: 1. #123
+  if (stories.length === 0) {
+    const numberedPattern = /\d+\.\s+#(\d+)/g;
+    while ((match = numberedPattern.exec(epicBody)) !== null) {
+      stories.push(parseInt(match[1]));
+    }
+  }
+  return stories;
+}
+```
+
+## Parse Arguments
+
+```javascript
+const args = "$ARGUMENTS".trim().split(/\s+/);
+let workflowMode = "full";    // full, enhance, research
+let execMode = "swarm";       // swarm (default), hive, naked
+let issueNumber = null;
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+
+  // Workflow mode (what to do)
+  if (arg === "-e" || arg === "--enhance") {
+    workflowMode = "enhance";
+  } else if (arg === "-r" || arg === "--research") {
+    workflowMode = "research";
+  }
+
+  // Execution mode (how to do it)
+  else if (arg === "-sw" || arg === "--swarm") {
+    execMode = "swarm";
+  } else if (arg === "-hv" || arg === "--hive") {
+    execMode = "hive";
+  } else if (arg === "-n" || arg === "--naked") {
+    execMode = "naked";
+  }
+
+  // Issue number
+  else if (/^\d+$/.test(arg)) {
+    issueNumber = arg;
+  }
+}
+
+if (!issueNumber) {
+  throw new Error("Issue number required. Usage: /flo <issue-number>");
+}
+
+// Log execution mode to prevent silent skipping
+console.log("Execution mode: " + execMode.toUpperCase());
+if (execMode === "swarm") {
+  console.log("SWARM MODE: Will spawn agents via Task tool. Do NOT skip this.");
+}
+console.log("TESTING: Unit + Integration + E2E tests REQUIRED before PR.");
+console.log("SIMPLIFY: /simplify command runs on changed code before PR.");
+```
+
+## Execution Flow
+
+### Workflow Modes (what to do)
+
+| Mode | Command | Steps | Stops After |
+|------|---------|-------|-------------|
+| **Full** (default) | `/flo 123` | Research -> Enhance -> Implement -> Test -> Simplify -> PR | PR created |
+| **Epic** | `/flo 42` (epic) | For each story: Full workflow sequentially | All story PRs created |
+| **Enhance** | `/flo -e 123` | Research -> Enhance | Issue updated |
+| **Research** | `/flo -r 123` | Research | Findings output |
+
+### Execution Modes (how to do it)
+
+| Mode | Flag | Description | When to Use |
+|------|------|-------------|-------------|
+| **Swarm** (DEFAULT) | `-sw`, `--swarm` | Multi-agent via Task tool | Always, unless explicitly overridden |
+| **Hive-Mind** | `-hv`, `--hive` | Consensus-based coordination | Architecture decisions, tradeoffs |
+| **Naked** | `-n`, `--naked` | Single Claude, no agents | User explicitly wants simple mode |
+
+## Execution Mode Details
+
+### SWARM Mode (Default) - ALWAYS USE UNLESS TOLD OTHERWISE
+
+You MUST use the Task tool to spawn agents. No exceptions.
+
+**Swarm spawns these agents via Task tool:**
+- `researcher` - Analyzes issue, searches memory, finds patterns
+- `coder` - Implements changes following plan
+- `tester` - Writes and runs tests
+- `/simplify` - Built-in command that reviews changed code before PR
+- `reviewer` - Reviews code before PR
+
+**Swarm execution pattern:**
+```javascript
+// 1. Create task list FIRST
+TaskCreate({ subject: "Research issue #123", ... })
+TaskCreate({ subject: "Implement changes", ... })
+TaskCreate({ subject: "Test implementation", ... })
+TaskCreate({ subject: "Run /simplify on changed files", ... })
+TaskCreate({ subject: "Review and PR", ... })
+
+// 2. Init swarm
+Bash("npx flo swarm init --topology hierarchical --max-agents 8 --strategy specialized")
+
+// 3. Spawn agents with Task tool (run_in_background: true)
+Task({ prompt: "...", subagent_type: "researcher", run_in_background: true })
+Task({ prompt: "...", subagent_type: "coder", run_in_background: true })
+
+// 4. Wait for results, synthesize, continue
+```
+
+### HIVE-MIND Mode (-hv, --hive)
+
+Use for consensus-based decisions:
+- Architecture choices
+- Approach tradeoffs
+- Design decisions with multiple valid options
+
+### NAKED Mode (-n, --naked)
+
+**Only when user explicitly requests.** Single Claude execution without agents.
+- Still uses Task tool for tracking
+- Still creates tasks for visibility
+- Just doesn't spawn multiple agents
+
+---
+
+**Full mode executes without prompts.** It will:
+1. Research the issue and codebase
+2. Enhance the GitHub issue with implementation plan
+3. Assign issue to self, add "in-progress" label
+4. Create branch, implement, test
+5. Run /simplify on changed code, re-test if changes made
+6. Commit, create PR, update issue status
+7. Store learnings

package/README.md

@@ -10,6 +10,30 @@ MoFlo adds automatic code and guidance cataloging along with memory gating on to
 
 Install it as a dev dependency and run `flo init`.
 
+## Opinionated Defaults
+
+MoFlo makes deliberate choices so you don't have to:
+
+- **Fully self-contained** — No external services, no cloud dependencies, no API keys. Everything runs locally on your machine.
+- **Node.js runtime** — Targets Node.js specifically. All scripts, hooks, and tooling are JavaScript/TypeScript. No Python, no Rust binaries, no native compilation.
+- **sql.js (WASM)** — The memory database uses sql.js, a pure WebAssembly build of SQLite. No native `better-sqlite3` bindings to compile, no platform-specific build steps. Works identically on Windows, macOS, and Linux.
+- **Simplified embeddings pipeline** — 384-dimensional neural embeddings via Transformers.js (MiniLM-L6-v2, WASM). Same model and precision as the upstream multi-provider pipeline, but simpler — two scripts instead of an abstraction layer. Runs locally, no API calls.
+- **Full learning stack wired up OOTB** — The following are all configured and functional from `flo init`, no manual setup:
+  - **SONA** (Self-Optimizing Neural Architecture) — learns from task trajectories via `@ruvector/sona` (Rust/NAPI)
+  - **MicroLoRA** — rank-2 LoRA weight adaptations at ~1µs per adapt via `@ruvector/learning-wasm` (WASM)
+  - **EWC++** (Elastic Weight Consolidation) — prevents catastrophic forgetting across sessions
+  - **HNSW Vector Search** — fast nearest-neighbor search via `@ruvector/core` VectorDb
+  - **Semantic Routing** — maps tasks to agents via `@ruvector/router` SemanticRouter
+  - **Trajectory Persistence** — outcomes stored in `routing-outcomes.json`, survive across sessions
+  - All WASM/NAPI-based, no GPU, no API keys, no external services.
+- **Memory-first workflow** — Claude must search what it already knows before exploring files. Enforced by hooks, not just instructions.
+- **Task registration before agents** — Sub-agents can't spawn until work is tracked. Prevents runaway agent proliferation.
+- **Learned routing** — Task outcomes feed back into the routing system automatically. No manual configuration needed — it gets smarter with use.
+- **Incremental indexing** — Guidance and code map indexes run on every session start but skip unchanged files. Fast after the first run.
+- **AI client agnostic** — Works with any MCP-capable AI client. We develop and test with Claude Code, but the MCP tools, memory system, and hooks are client-independent.
+- **GitHub-oriented** — The `/flo` skill, PR workflows, and issue tracking are built around GitHub. With Claude's help, you can adapt them to your own issue tracker and source control system.
+- **Cross-platform** — Forward-slash path normalization, no `sh -c` shell commands, `windowsHide` on all spawn calls.
+
 ## Features
 
 | Feature | What It Does |
@@ -102,6 +126,8 @@ Both indexes run automatically at session start after this, so you only need to
 
 ## Commands
 
+You don't need to run these for normal use — `flo init` sets everything up, and the hooks handle memory, routing, and learning automatically. These commands are here for manual setup, debugging, and tweaking.
+
 ### Memory
 
 ```bash
@@ -165,6 +191,36 @@ feature:
 
 Stories are resolved via topological sort (respecting `depends_on`), then executed sequentially by spawning `claude -p "/flo <issue>"`.
 
+### The `/flo` Skill
+
+Inside your AI client, the `/flo` (or `/fl`) slash command drives GitHub issue workflows. Quick reference:
+
+```
+/flo <issue>                  # Full workflow (research → implement → test → PR)
+/flo -e <issue>               # Enhance only (research and update ticket, then stop)
+/flo -r <issue>               # Research only (analyze issue, output findings)
+/flo -sw <issue>              # Swarm mode (default, multi-agent coordination)
+/flo -hv <issue>              # Hive-mind mode (consensus-based coordination)
+/flo -n <issue>               # Naked mode (single agent, no swarm)
+/flo <epic-issue>             # Detects epics, processes stories sequentially
+```
+
+For full options and details, type `/flo` with no arguments — your AI client will display the complete skill documentation. Also available as `/fl`.
+
+#### Epic handling
+
+When you pass an issue number, `/flo` automatically checks if it's an epic — no extra flag needed. An issue is treated as an epic if any of these are true:
+
+- It has a label matching `epic`, `tracking`, `parent`, or `umbrella` (case-insensitive)
+- Its body contains a `## Stories` or `## Tasks` section
+- Its body has checklist-linked issues: `- [ ] #101`
+- Its body has numbered issue references: `1. #101`
+- The issue has GitHub sub-issues (via the API)
+
+When an epic is detected, `/flo` processes each child story sequentially — full workflow per story (research → implement → test → PR), one at a time, in the order listed. The `-e`, `-r`, `-n`, `-sw`, and `-hv` flags still apply and get passed through to each story.
+
+Stories are extracted from markdown checklists (`- [ ] #101`) or numbered lists (`1. #101`), processed top-to-bottom.
+
 ### System
 
 ```bash
@@ -297,6 +353,27 @@ When you route a task (`flo hooks route --task "..."` or via MCP), MoFlo runs se
 
 Routing outcomes are stored in `.claude-flow/routing-outcomes.json` and persist across sessions. You can inspect them with `flo hooks patterns` or transfer them between projects with `flo hooks transfer`.
 
+### What Ships Out of the Box
+
+`flo init` wires up the following systems automatically — no configuration needed:
+
+| System | What It Does | Technology |
+|--------|-------------|------------|
+| **Semantic Memory** | Store and search knowledge with 384-dim embeddings | sql.js (WASM SQLite) + Transformers.js (MiniLM-L6-v2) |
+| **HNSW Vector Search** | Fast nearest-neighbor search across all stored knowledge | `@ruvector/core` VectorDb |
+| **Semantic Routing** | Match tasks to agent types using vector similarity | `@ruvector/router` SemanticRouter |
+| **SONA Learning** | Learn from task trajectories — what agent handled what, and whether it succeeded | `@ruvector/sona` SonaEngine (Rust/NAPI) |
+| **MicroLoRA Adaptation** | Rank-2 LoRA weight updates from successful patterns (~1µs per adapt) | `@ruvector/learning-wasm` |
+| **EWC++ Consolidation** | Prevent catastrophic forgetting — new learning doesn't overwrite old patterns | Built into hooks-tools |
+| **Workflow Gates** | Memory-first and task-registration enforcement via Claude Code hooks | `.claude/settings.json` hooks |
+| **Context Tracking** | Monitor context window depletion (FRESH → CRITICAL) | Session interaction counter |
+| **Guidance Indexing** | Chunk and embed your project docs on session start | `flo-index` bin script |
+| **Code Map** | Index source file structure (types, exports, functions) on session start | `flo-codemap` bin script |
+| **Learned Routing** | Task outcomes feed back into routing — gets smarter over time | `routing-outcomes.json` persistence |
+| **Status Line** | Live dashboard showing git, swarm, memory, and MCP status | `statusline.cjs` hook |
+
+All of these run locally with zero external dependencies. The SONA, MicroLoRA, and HNSW components are WASM/NAPI binaries that ship with the npm package — no compilation, no GPU, no API keys.
+
 ### The Two-Layer Task System
 
 MoFlo doesn't replace your AI client's task system — it wraps it. Your client (Claude Code, Cursor, or any MCP-capable tool) handles spawning agents and running code. MoFlo adds a coordination layer on top that handles memory, routing, and learning.

package/bin/index-guidance.mjs

@@ -98,6 +98,13 @@ function loadGuidanceDirs() {
     dirs.push({ path: bundledGuidanceDir, prefix: 'moflo-bundled', absolute: true });
   }
 
+  // 3. Include CLAUDE.md from project root if it exists
+  //    This is the primary project instruction file for Claude-enabled projects
+  const claudeMdPath = resolve(projectRoot, 'CLAUDE.md');
+  if (existsSync(claudeMdPath)) {
+    dirs.push({ path: projectRoot, prefix: 'project-root', absolute: true, fileFilter: ['CLAUDE.md'] });
+  }
+
   return dirs;
 }
 
@@ -635,7 +642,10 @@ function indexDirectory(db, dirConfig) {
     return results;
   }
 
-  const files = readdirSync(dirPath).filter(f => f.endsWith('.md'));
+  const allMdFiles = readdirSync(dirPath).filter(f => f.endsWith('.md'));
+  const files = dirConfig.fileFilter
+    ? allMdFiles.filter(f => dirConfig.fileFilter.includes(f))
+    : allMdFiles;
 
   for (const file of files) {
     const filePath = resolve(dirPath, file);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.6.7",
+  "version": "4.6.9",
   "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",
@@ -59,6 +59,7 @@
     "moflo:security": "npm run security:audit && npm run security:test"
   },
   "dependencies": {
+    "@ruvector/learning-wasm": "^0.1.29",
     "semver": "^7.6.0",
     "sql.js": "^1.12.0",
     "zod": "^3.22.4"

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

@@ -1,6 +1,6 @@
 {
   "name": "@moflo/cli",
-  "version": "4.6.6",
+  "version": "4.6.9",
   "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",