moflo 4.9.10 → 4.9.12

package/.claude/commands/simplify.md

@@ -1,55 +1,103 @@
 ---
-description: Review changed code for reuse, quality, and efficiency, then fix any issues found.
+description: Review changed code for reuse, quality, and efficiency, then fix any issues found. Sizes review effort to the diff and routes the cheapest model that fits.
 ---
 
-# /simplify — Gate-Compliant Code Review
+# /simplify — Adaptive Gate-Compliant Code Review
 
-Review all changed files for reuse opportunities, code quality, and efficiency improvements.
+Review changed code for reuse, quality, and efficiency. **Effort scales with diff size; model is routed for cost.** A 5-line comment trim does not get 3 Opus agents.
 
-**This command overrides any built-in simplify skill.** Follow these steps exactly.
+## Phase 0: Gate prerequisites
 
-## Prerequisites (MANDATORY — do these FIRST)
+These satisfy the memory-first and task-create-first gates. Always do them before any Agent spawn.
 
-1. **Memory search**: Search for relevant patterns before reviewing
-```
-mcp__moflo__memory_search — query: "code quality patterns", namespace: "patterns"
-```
+1. **Memory search** — `mcp__moflo__memory_search — query: "code quality patterns", namespace: "patterns"`
+2. **Task create** — `TaskCreate — subject: "🔍 [Reviewer] Simplify changed code"`
 
-2. **Create task**: Track the simplification work
-```
-TaskCreate — subject: "🔍 [Reviewer] Simplify changed code", description: "Review changed files for reuse, quality, and efficiency"
+## Phase 1: Identify the diff
+
+```bash
+git diff HEAD          # working tree
+git diff main...HEAD   # committed since branch base
 ```
 
-## Execution
+Treat the union as the diff. Note whether `/simplify` already ran on this branch in this session — if so, you are in a **validation pass** (Phase 4 below).
 
-After prerequisites are satisfied, get the list of changed files:
+## Phase 2: Classify the diff
 
-```bash
-git diff --name-only HEAD~1
-```
+Pick the smallest tier the diff genuinely fits.
 
-Then launch 3 reviewer agents **in parallel** (single message, multiple Agent tool calls).
+| Tier | Trigger | Action |
+|------|---------|--------|
+| **TRIVIAL** | ≤10 net LOC, single file, comments/formatting/local renames only | Self-review, zero agents |
+| **SMALL** | ≤200 net LOC, ≤2 files, no API/dependency change | **One agent** (default for most diffs, including critical surface) |
+| **NORMAL** | ≥3 files, OR >200 LOC, OR public API change, OR new/removed dependency, OR cross-cutting refactor | Three parallel agents |
 
-**CRITICAL**: Each agent prompt below includes a mandatory memory search step. This is required because subagents must satisfy the memory-first gate independently before using Glob, Grep, or Read tools. Do NOT remove the memory search from agent prompts.
+Critical-surface files (launcher, hooks, MCP wiring) raise the *care* of the agent prompt — sharper checklist, blast-radius framing — they do **not** automatically escalate to NORMAL. Risk-weighted ≠ headcount-weighted.
+
+## Phase 3: Route the model (skip for TRIVIAL)
+
+Before spawning any Agent, ask the moflo router which model to use:
 
-### Agent 1: Reuse Reviewer
 ```
-Agent — name: "reuse-reviewer", run_in_background: true, subagent_type: "reviewer", prompt: "FIRST ACTION: Run mcp__moflo__memory_search with query 'code reuse patterns' and namespace 'patterns'. You MUST do this before any Glob, Grep, or Read calls. THEN review these changed files for code reuse opportunities. Look for: duplicated logic that could use existing utilities, patterns already solved elsewhere in the codebase, opportunities to extract shared helpers. Files: $CHANGED_FILES"
+mcp__moflo__hooks_model-route — {
+  task: "Review N-line change in <files> for reuse, quality, efficiency",
+  preferCost: true
+}
 ```
 
-### Agent 2: Quality Reviewer
+**Wording rules:** the router's complexity score is keyword-sensitive. Avoid `refactor`, `architect`, `audit`, `system`, `redesign`, `migrate` — those force opus even when scoring suggests sonnet. State LOC count, file count, and "review for reuse, quality, efficiency". Nothing more.
+
+**Hard rule for `/simplify`: opus is never correct.** Code review never needs Opus reasoning, even on critical surface. If the router returns `opus`, downgrade to `sonnet`. On router failure, default to `sonnet`. Comment trims and pure formatting → `haiku`.
+
+## Phase 4: Validation pass (re-run after fixes from a prior simplify)
+
+If `/simplify` already ran on this branch in this session AND the only edits since are fixes the prior pass surfaced, **default to TRIVIAL self-review** regardless of LOC count. The fan-out happened; the fix is small relative to the already-reviewed diff.
+
+Escalate one tier (self-review → SMALL agent) only if the fix introduced a new file, a new exported symbol, a new dependency, or a control-flow change not covered by the original findings. Never escalate a validation pass to NORMAL.
+
+## Phase 5: Run the appropriate review
+
+### TRIVIAL / Validation
+Run the three category checks (reuse / quality / efficiency) yourself in one pass against the diff. Most TRIVIAL diffs are clean — confirm and exit. Budget: ~30 seconds, no Agent.
+
+### SMALL — one agent
 ```
-Agent — name: "quality-reviewer", run_in_background: true, subagent_type: "reviewer", prompt: "FIRST ACTION: Run mcp__moflo__memory_search with query 'code quality patterns' and namespace 'patterns'. You MUST do this before any Glob, Grep, or Read calls. THEN review these changed files for code quality issues. Look for: unclear naming, overly complex logic, missing error handling at system boundaries, potential bugs, consistency with existing patterns. Files: $CHANGED_FILES"
+Agent — {
+  subagent_type: "reviewer",
+  model: "<sonnet (or haiku for trivial-formatting tier from router)>",
+  prompt: "FIRST ACTION: Run mcp__moflo__memory_search with query 'code review patterns' and namespace 'patterns' to satisfy the memory-first gate. THEN review this diff for reuse, quality, and efficiency. <diff inline>. Flag specific issues as file:line + 1-line description. Max 5 file reads. Under 200 words. Skip cosmetic style. Don't suggest cross-cutting refactors of code outside this diff."
+}
 ```
 
-### Agent 3: Efficiency Reviewer
+For critical-surface files, prepend a 1-line risk note (e.g., "This is `bin/session-start-launcher.mjs` — runs in every consumer's session-start hot path; cross-platform + blast-radius matter."). One careful agent, not three.
+
+### NORMAL — three parallel agents
+Launch three agents in a single message, each at the routed model (typically sonnet). Each agent gets the SMALL-tier tool-budget cap.
+
+- **Agent 1 (Reuse):** existing helpers/utilities that should be used; duplicated patterns; functions re-implementing something already in the codebase.
+- **Agent 2 (Quality):** redundant state, parameter sprawl, copy-paste with variation, leaky abstractions, stringly-typed code, nested conditionals 3+ levels, unnecessary comments.
+- **Agent 3 (Efficiency):** unnecessary work, missed concurrency, hot-path bloat, recurring no-op updates, TOCTOU existence checks, unbounded structures, over-broad reads.
+
+Each agent prompt must start with `FIRST ACTION: mcp__moflo__memory_search ... namespace: "patterns"` — subagents must satisfy the memory-first gate independently before Glob/Grep/Read.
+
+## Phase 6: Fix or skip
+
+Aggregate findings. Fix each issue directly that's worth fixing. False positives or out-of-scope: note and skip without arguing.
+
+If fixes were made, re-run tests to confirm nothing broke. If tests fail after a fix, revert it.
+
+After fixes: the next `/simplify` invocation is a **validation pass** (Phase 4). Bundle related fixes into one batch so a single validation pass covers them — don't re-fan-out for cosmetic micro-corrections.
+
+## Phase 7: Optional — record routing outcome
+
+If you spawned an agent, feed back the outcome so the router learns:
+
 ```
-Agent — name: "efficiency-reviewer", run_in_background: true, subagent_type: "reviewer", prompt: "FIRST ACTION: Run mcp__moflo__memory_search with query 'performance optimization patterns' and namespace 'patterns'. You MUST do this before any Glob, Grep, or Read calls. THEN review these changed files for efficiency improvements. Look for: unnecessary allocations, O(n^2) where O(n) is possible, redundant operations, opportunities to batch or cache. Files: $CHANGED_FILES"
+mcp__moflo__hooks_model-outcome — { task: "...", model: "<chosen>", outcome: "success" | "failure" | "escalated" }
 ```
 
-## Post-Review
+`escalated` only when a real miss happened that a higher tier would have caught — never used to retroactively justify opus.
+
+## Briefly summarize
 
-1. Collect findings from all 3 reviewers
-2. Apply fixes that preserve ALL existing functionality — no behavior changes
-3. If fixes were made, re-run tests to confirm nothing broke
-4. If tests fail after fixes, revert the simplification changes
+End with one or two sentences: which tier ran, which model, what was fixed (or "clean — no changes"). No headers, no bullets.

package/.claude/guidance/shipped/moflo-cli-reference.md

@@ -0,0 +1,201 @@
+# Moflo CLI Surface — Commands, Agents, Hooks
+
+**Purpose:** Reference for moflo's CLI command surface, available agents, hooks, and consensus topologies. Use this when picking a command/agent/hook by name; for higher-level workflow guidance see `moflo-core-guidance.md`, and for `moflo.yaml` knobs that gate this surface see `moflo-yaml-reference.md`.
+
+---
+
+## CLI Commands (26 Commands, 140+ Subcommands)
+
+### Core Commands
+
+| Command     | Subcommands | Description                                                              |
+|-------------|-------------|--------------------------------------------------------------------------|
+| `init`      | 4           | Project initialization with wizard, presets, skills, hooks               |
+| `agent`     | 8           | Agent lifecycle (spawn, list, status, stop, metrics, pool, health, logs) |
+| `swarm`     | 6           | Multi-agent swarm coordination and orchestration                         |
+| `memory`    | 11          | sql.js + HNSW vector search, 150x-12,500x faster                         |
+| `mcp`       | 9           | MCP server management and tool execution                                 |
+| `task`      | 6           | Task creation, assignment, and lifecycle                                 |
+| `session`   | 7           | Session state management and persistence                                 |
+| `config`    | 7           | Configuration management and provider setup                              |
+| `status`    | 3           | System status monitoring with watch mode                                 |
+| `workflow`  | 6           | Workflow execution and template management                               |
+| `hooks`     | 17          | Self-learning hooks + 12 background workers                              |
+| `hive-mind` | 6           | Queen-led Byzantine fault-tolerant consensus                             |
+
+### Advanced Commands
+
+| Command       | Subcommands | Description                                                                   |
+|---------------|-------------|-------------------------------------------------------------------------------|
+| `daemon`      | 5           | Background worker daemon (start, stop, status, trigger, enable)               |
+| `neural`      | 5           | Neural pattern training (train, status, patterns, predict, optimize)          |
+| `security`    | 6           | Security scanning (scan, audit, cve, threats, validate, report)               |
+| `performance` | 5           | Performance profiling (benchmark, profile, metrics, optimize, report)         |
+| `providers`   | 5           | AI providers (list, add, remove, test, configure)                             |
+| `plugins`     | 5           | Plugin management (list, install, uninstall, enable, disable)                 |
+| `deployment`  | 5           | Deployment management (deploy, rollback, status, environments, release)       |
+| `embeddings`  | 4           | Vector embeddings (embed, batch, search, init) — fastembed runtime            |
+| `claims`      | 4           | Claims-based authorization (check, grant, revoke, list)                       |
+| `migrate`     | 5           | V2 to V3 migration with rollback support                                      |
+| `epic`        | 3           | Epic orchestrator — run/status/reset with single-branch or auto-merge strategy |
+| `doctor`      | 1           | System diagnostics with health checks                                         |
+| `completions` | 4           | Shell completions (bash, zsh, fish, powershell)                               |
+
+### Quick Examples (MCP Preferred)
+
+| Task | MCP Tool | CLI Fallback |
+|------|----------|-------------|
+| Search memory | `mcp__moflo__memory_search` | `memory search --query "..."` |
+| Spawn agent | `mcp__moflo__agent_spawn` | `agent spawn -t coder --name my-coder` |
+| Init swarm | `mcp__moflo__swarm_init` | `swarm init --v3-mode` |
+| System health | `mcp__moflo__system_health` | `doctor --fix` |
+| Benchmark | `mcp__moflo__performance_benchmark` | `performance benchmark --suite all` |
+
+**CLI-only (no MCP equivalent — setup tasks):**
+```bash
+npx flo init --wizard
+npx flo daemon start
+```
+
+---
+
+## Available Agents (60+ Types)
+
+### Core Development
+`coder`, `reviewer`, `tester`, `planner`, `researcher`
+
+### Specialized Agents
+`security-architect`, `security-auditor`, `memory-specialist`, `performance-engineer`
+
+### Swarm Coordination
+`hierarchical-coordinator`, `mesh-coordinator`, `adaptive-coordinator`, `collective-intelligence-coordinator`, `swarm-memory-manager`
+
+### Consensus & Distributed
+`byzantine-coordinator`, `raft-manager`, `gossip-coordinator`, `consensus-builder`, `crdt-synchronizer`, `quorum-manager`, `security-manager`
+
+### Performance & Optimization
+`perf-analyzer`, `performance-benchmarker`, `task-orchestrator`, `memory-coordinator`, `smart-agent`
+
+### GitHub & Repository
+`github-modes`, `pr-manager`, `code-review-swarm`, `issue-tracker`, `release-manager`, `workflow-automation`, `project-board-sync`, `repo-architect`, `multi-repo-swarm`
+
+### SPARC Methodology
+`sparc-coord`, `sparc-coder`, `specification`, `pseudocode`, `architecture`, `refinement`
+
+### Specialized Development
+`backend-dev`, `mobile-dev`, `ml-developer`, `cicd-engineer`, `api-docs`, `system-architect`, `code-analyzer`, `base-template-generator`
+
+### Testing & Validation
+`tdd-london-swarm`, `production-validator`
+
+### Agent Routing (Anti-Drift)
+
+| Code | Task        | Agents                                          |
+|------|-------------|-------------------------------------------------|
+| 1    | Bug Fix     | coordinator, researcher, coder, tester          |
+| 3    | Feature     | coordinator, architect, coder, tester, reviewer |
+| 5    | Refactor    | coordinator, architect, coder, reviewer         |
+| 7    | Performance | coordinator, perf-engineer, coder               |
+| 9    | Security    | coordinator, security-architect, auditor        |
+| 11   | Docs        | researcher, api-docs                            |
+
+**Codes 1-9: hierarchical/specialized (anti-drift). Code 11: mesh/balanced.**
+
+---
+
+## Hooks System (27 Hooks + 12 Workers)
+
+### All Available Hooks
+
+| Hook               | Description                              | Key Options                                 |
+|--------------------|------------------------------------------|---------------------------------------------|
+| `pre-edit`         | Get context before editing files         | `--file`, `--operation`                     |
+| `post-edit`        | Record editing outcome for learning      | `--file`, `--success`, `--train-neural`     |
+| `pre-command`      | Assess risk before commands              | `--command`, `--validate-safety`            |
+| `post-command`     | Record command execution outcome         | `--command`, `--track-metrics`              |
+| `pre-task`         | Record task start, get agent suggestions | `--description`, `--coordinate-swarm`       |
+| `post-task`        | Record task completion for learning      | `--task-id`, `--success`, `--store-results` |
+| `session-start`    | Start/restore session                    | `--session-id`, `--auto-configure`          |
+| `session-end`      | End session and persist state            | `--generate-summary`, `--export-metrics`    |
+| `session-restore`  | Restore a previous session               | `--session-id`, `--latest`                  |
+| `route`            | Route task to optimal agent              | `--task`, `--context`, `--top-k`            |
+| `explain`          | Explain routing decision                 | `--topic`, `--detailed`                     |
+| `pretrain`         | Bootstrap intelligence from repo         | `--model-type`, `--epochs`                  |
+| `build-agents`     | Generate optimized agent configs         | `--agent-types`, `--focus`                  |
+| `metrics`          | View learning metrics dashboard          | `--v3-dashboard`, `--format`                |
+| `transfer`         | Transfer patterns via IPFS registry      | `store`, `from-project`                     |
+| `intelligence`     | RuVector intelligence system             | `trajectory-*`, `pattern-*`, `stats`        |
+| `worker`           | Background worker management             | `list`, `dispatch`, `status`, `detect`      |
+| `coverage-route`   | Route based on test coverage gaps        | `--task`, `--path`                          |
+| `coverage-suggest` | Suggest coverage improvements            | `--path`                                    |
+| `coverage-gaps`    | List coverage gaps with priorities       | `--format`, `--limit`                       |
+
+### 12 Background Workers
+
+| Worker        | Priority | Description                |
+|---------------|----------|----------------------------|
+| `ultralearn`  | normal   | Deep knowledge acquisition |
+| `optimize`    | high     | Performance optimization   |
+| `consolidate` | low      | Memory consolidation       |
+| `predict`     | normal   | Predictive preloading      |
+| `audit`       | critical | Security analysis          |
+| `map`         | normal   | Codebase mapping           |
+| `preload`     | low      | Resource preloading        |
+| `deepdive`    | normal   | Deep code analysis         |
+| `document`    | normal   | Auto-documentation         |
+| `refactor`    | normal   | Refactoring suggestions    |
+| `benchmark`   | normal   | Performance benchmarking   |
+| `testgaps`    | normal   | Test coverage analysis     |
+
+### Essential Hook Commands (MCP Preferred)
+
+| Hook | MCP Tool | Key Params |
+|------|----------|------------|
+| Pre-task | `mcp__moflo__hooks_pre-task` | `description` |
+| Post-task | `mcp__moflo__hooks_post-task` | `taskId`, `success` |
+| Post-edit | `mcp__moflo__hooks_post-edit` | `file`, `trainNeural` |
+| Session-start | `mcp__moflo__hooks_session-start` | `sessionId` |
+| Session-end | `mcp__moflo__hooks_session-end` | `exportMetrics` |
+| Route | `mcp__moflo__hooks_route` | `task` |
+| Worker-dispatch | `mcp__moflo__hooks_worker-dispatch` | `trigger` |
+
+---
+
+## Hive-Mind Consensus
+
+### Topologies
+
+- `hierarchical` — Queen controls workers directly
+- `mesh` — Fully connected peer network
+- `hierarchical-mesh` — Hybrid (recommended)
+- `adaptive` — Dynamic based on load
+
+### Consensus Strategies
+
+- `byzantine` — BFT (tolerates f < n/3 faulty)
+- `raft` — Leader-based (tolerates f < n/2)
+- `gossip` — Epidemic for eventual consistency
+- `crdt` — Conflict-free replicated data types
+- `quorum` — Configurable quorum-based
+
+---
+
+## RuVector Integration (HNSW Vector Search)
+
+| Feature | Performance | Description |
+|---------|-------------|-------------|
+| **HNSW Index** | 150x–12,500x faster | Hierarchical Navigable Small World search |
+| **MicroLoRA** | <100µs adaptation | Fast model adaptation (508k+ ops/sec) |
+| **FlashAttention** | 2.49x–7.47x speedup | Optimized attention computation |
+| **Int8 Quantization** | 3.92x memory reduction | Compressed weight storage |
+
+---
+
+## See Also
+
+- `.claude/guidance/shipped/moflo-core-guidance.md` — Hub: getting started, MCP setup, troubleshooting, comparison table
+- `.claude/guidance/shipped/moflo-yaml-reference.md` — `moflo.yaml` schema and runtime env-var overrides for the surfaces listed here
+- `.claude/guidance/shipped/moflo-claude-swarm-cohesion.md` — How TaskCreate + swarm coordinators cooperate (uses the agent codes above)
+- `.claude/guidance/shipped/moflo-subagents.md` — Subagent memory-first protocol and store-back rules
+- `.claude/guidance/shipped/moflo-memory-strategy.md` — Memory namespaces, RAG linking, and search query patterns
+- `.claude/guidance/shipped/moflo-memorydb-maintenance.md` — How the namespaces above are populated and refreshed