moflo 4.8.50 → 4.8.52-rc.0

package/.claude/commands/simplify.md

@@ -0,0 +1,55 @@
+---
+description: Review changed code for reuse, quality, and efficiency, then fix any issues found.
+---
+
+# /simplify — Gate-Compliant Code Review
+
+Review all changed files for reuse opportunities, code quality, and efficiency improvements.
+
+**This command overrides any built-in simplify skill.** Follow these steps exactly.
+
+## Prerequisites (MANDATORY — do these FIRST)
+
+1. **Memory search**: Search for relevant patterns before reviewing
+```
+mcp__moflo__memory_search — query: "code quality patterns", namespace: "patterns"
+```
+
+2. **Create task**: Track the simplification work
+```
+TaskCreate — subject: "🔍 [Reviewer] Simplify changed code", description: "Review changed files for reuse, quality, and efficiency"
+```
+
+## Execution
+
+After prerequisites are satisfied, get the list of changed files:
+
+```bash
+git diff --name-only HEAD~1
+```
+
+Then launch 3 reviewer agents **in parallel** (single message, multiple Agent tool calls).
+
+**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.
+
+### 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"
+```
+
+### Agent 2: Quality Reviewer
+```
+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 3: Efficiency Reviewer
+```
+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"
+```
+
+## Post-Review
+
+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

package/.claude/guidance/shipped/moflo-claude-swarm-cohesion.md

@@ -140,13 +140,12 @@ npx flo hive-mind init --topology hierarchical-mesh --consensus byzantine
 
 Include task IDs in agent prompts so they update status.
 TaskCreate was already called in Step 1 — tasks are visible before agents spawn.
+The `SubagentStart` hook automatically injects the subagent protocol directive — no need to include it in prompts.
 
 ```javascript
 // TaskCreate already done in Step 1 above
 Task({
-  prompt: `FIRST: Search memory, then read .claude/guidance/moflo-subagents.md
-
-YOUR TASK (ID: 1): Research requirements and codebase patterns
+  prompt: `YOUR TASK (ID: 1): Research requirements and codebase patterns
 - Analyze feature requirements
 - Search codebase for relevant patterns
 - Document findings in memory
@@ -385,15 +384,23 @@ npx flo swarm init --topology hierarchical-mesh --max-agents 15 --strategy speci
 
 ## Subagent Context Rules
 
-**Subagents DO inherit CLAUDE.md context** when spawned via Task tool. They automatically receive:
-- Memory-first protocol instructions
+**Subagents automatically receive guidance via the `SubagentStart` hook.** When any subagent spawns, the hook injects a directive telling it to read `.claude/guidance/shipped/moflo-subagents.md` before doing any work. This is centralized — no per-agent configuration needed.
+
+**What subagents receive automatically:**
+- `SubagentStart` hook directive to read subagent protocol guidance
+- CLAUDE.md context (inherited from project)
 - MCP tool access (`mcp__moflo__*`) when configured
-- Project guidance and coding rules
+- Project `.claude/guidance/*.md` files
+
+**Memory-first enforcement for subagents:**
+- Agent spawning is never blocked — the `SubagentStart` hook is advisory
+- When a subagent tries to use Glob, Grep, or Read, the scan/read gates enforce memory-first at the work layer
+- This prevents cascading failures from nested agent spawns
 
 **Best practices for subagent prompts:**
 - Include relevant context (file paths, error messages, specific requirements)
 - Provide specific paths if known, don't let agents guess with broad globs
-- Trust that they know the memory-first protocol
+- Don't repeat the subagent protocol — the `SubagentStart` hook handles it
 
 **MCP Tools Available to Subagents:**
 - `mcp__moflo__memory_search` - Semantic search

package/.claude/guidance/shipped/moflo-core-guidance.md

@@ -76,7 +76,7 @@ On version change, `session-start-launcher.mjs` copies helper scripts from the i
 |--------|--------|-------|
 | `bin/` | `.claude/scripts/` | `hooks.mjs`, `session-start-launcher.mjs`, `index-guidance.mjs`, `build-embeddings.mjs`, `generate-code-map.mjs`, `semantic-search.mjs` |
 | `bin/` | `.claude/helpers/` | `gate.cjs`, `gate-hook.mjs`, `prompt-hook.mjs`, `hook-handler.cjs` |
-| `src/@claude-flow/cli/.claude/helpers/` | `.claude/helpers/` | `auto-memory-hook.mjs`, `statusline.cjs`, `pre-commit`, `post-commit` |
+| `src/packages/cli/.claude/helpers/` | `.claude/helpers/` | `auto-memory-hook.mjs`, `statusline.cjs`, `subagent-start.cjs`, `pre-commit`, `post-commit` |
 
 When adding a new helper script: generate it once, save it to `bin/`, and add it to the appropriate list in `session-start-launcher.mjs`.
 
@@ -118,7 +118,7 @@ MCP tools are the preferred way for Claude to interact with moflo. `flo init` cr
   "mcpServers": {
     "moflo": {
       "command": "node",
-      "args": ["node_modules/moflo/src/@claude-flow/cli/bin/cli.js", "mcp", "start"]
+      "args": ["node_modules/moflo/src/packages/cli/bin/cli.js", "mcp", "start"]
     }
   }
 }
@@ -173,6 +173,7 @@ This gives Claude access to 200+ MCP tools (`mcp__moflo__memory_*`, `mcp__moflo_
 | `embeddings`  | 4           | Vector embeddings (embed, batch, search, init) - 75x faster with agentic-flow |
 | `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)                               |
 
@@ -475,7 +476,7 @@ Configure `.mcp.json` in the project root:
   "mcpServers": {
     "moflo": {
       "command": "node",
-      "args": ["node_modules/moflo/src/@claude-flow/cli/bin/cli.js", "mcp", "start"]
+      "args": ["node_modules/moflo/src/packages/cli/bin/cli.js", "mcp", "start"]
     }
   }
 }
@@ -520,9 +521,11 @@ code_map:
   namespace: code-map
 
 # Workflow gates (enforced via Claude Code hooks)
+# Memory-first is enforced at the scan/read layer (Glob, Grep, Read gates).
+# Agent spawning is never blocked — SubagentStart hook injects guidance directive.
 gates:
-  memory_first: true              # Search memory before Glob/Grep
-  task_create_first: true         # TaskCreate before Agent tool
+  memory_first: true              # Block Glob/Grep/Read until memory is searched
+  task_create_first: true         # Advisory reminder before Agent tool (not blocking)
   context_tracking: true          # Track context bracket (FRESH/MODERATE/DEPLETED/CRITICAL)
 
 # Auto-index on session start
@@ -542,7 +545,7 @@ hooks:
   post_edit: true                 # Record edit outcomes, train neural patterns
   pre_task: true                  # Get agent routing before task spawn
   post_task: true                 # Record task results for learning
-  gate: true                      # Workflow gate enforcement (memory-first, task-create-first)
+  gate: true                      # Workflow gate enforcement (memory-first at scan/read layer)
   route: true                     # Intelligent task routing on each prompt
   stop_hook: true                 # Session-end persistence and metric export
   session_restore: true           # Restore session state on start
@@ -590,7 +593,7 @@ status_line:
 | `auto_index.guidance: false` | Skip guidance indexing on session start |
 | `auto_index.code_map: false` | Skip code map generation on session start |
 | `gates.memory_first: true` | Block Glob/Grep/Read until memory is searched first |
-| `gates.task_create_first: true` | Block Agent/Task tool until TaskCreate is called |
+| `gates.task_create_first: true` | Advisory reminder before Agent tool (not blocking) |
 | `gates.context_tracking: true` | Show FRESH/MODERATE/DEPLETED/CRITICAL context bracket |
 | `hooks.pre_edit: false` | Disable file-edit tracking (skips pre-edit hook) |
 | `hooks.post_edit: false` | Disable edit outcome recording and neural training |

package/.claude/guidance/shipped/moflo-epic-processing.md

@@ -0,0 +1,62 @@
+# Epic Processing
+
+**Purpose:** Configuration and behavioral rules for `flo epic run` and `/flo` epic detection. Reference when processing epics, merging story PRs, or configuring epic behavior.
+
+---
+
+## Configuration (moflo.yaml)
+
+**Add an `epic` section to `moflo.yaml` to control epic behavior.** All settings have sensible defaults.
+
+```yaml
+epic:
+  admin_merge: true              # Use --admin on gh pr merge (bypasses branch protection)
+  default_strategy: single-branch  # single-branch | auto-merge
+```
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `admin_merge` | boolean | `true` | Pass `--admin` to `gh pr merge` in auto-merge strategy. Set `false` if the user lacks admin rights or wants branch protection enforced. |
+| `default_strategy` | string | `single-branch` | Default branching strategy when `--strategy` flag is not passed. Overridden by `--strategy` CLI flag or YAML feature definition. |
+
+---
+
+## Branching Strategies
+
+| Strategy | Branches | PRs | Merge behavior |
+|----------|----------|-----|----------------|
+| `single-branch` (default) | One shared `epic/<number>-<slug>` | One consolidated PR after all stories | No per-story merge |
+| `auto-merge` | Per-story branches | Per-story PRs, each merged before next story | Squash merge with `--admin` (configurable) |
+
+---
+
+## Admin Merge Behavior
+
+**In auto-merge strategy, use `--admin` on `gh pr merge` by default.** This bypasses branch protection rules that would otherwise block automated sequential processing.
+
+| Condition | Action |
+|-----------|--------|
+| `epic.admin_merge: true` (default) | `gh pr merge <number> --squash --delete-branch --admin` |
+| `epic.admin_merge: false` | `gh pr merge <number> --squash --delete-branch` (may fail on protected branches) |
+| Single-branch strategy | No merge during processing; consolidated PR created at end |
+
+**Never stop to ask whether a PR can be merged during epic auto-merge processing.** If the merge fails, log the error and halt the epic — do not prompt the user mid-sequence.
+
+---
+
+## Strategy Resolution Order
+
+The strategy is resolved with this precedence (highest first):
+
+1. `--strategy` CLI flag (`flo epic run 42 --strategy auto-merge`)
+2. `strategy` field in YAML feature definition
+3. `epic.default_strategy` in `moflo.yaml`
+4. Hard-coded fallback: `single-branch`
+
+---
+
+## See Also
+
+- `src/packages/cli/src/commands/epic.ts` — Epic command implementation
+- `src/packages/cli/src/config/moflo-config.ts` — `MofloConfig.epic` interface and defaults
+- `.claude/skills/fl/SKILL.md` — `/flo` skill epic handling section

package/.claude/guidance/shipped/moflo-task-icons.md

@@ -1,16 +1,29 @@
-# Task Icon Convention
+# Task & Agent Icon Convention
 
-**Purpose:** Every `TaskCreate` call MUST use **ICON + [Role]** format in `subject` and `activeForm`. This displays agent identity in the spinner — a key UX signal for end users watching task progress.
+**Purpose:** Every user-visible spinner text MUST use **ICON + [Role]** format. This applies to `TaskCreate` fields AND `Agent` tool `description`. Icons are a core MoFlo UX feature — they let users instantly identify which specialist is working.
 
 ---
 
-## Format
+## Where Icons Are Required
+
+| Tool | Field(s) | Format |
+|------|----------|--------|
+| `TaskCreate` | `subject`, `activeForm` | `ICON [Role] Brief description` |
+| `Agent` | `description` | `ICON [Role] Brief description` |
+
+## TaskCreate Format
 
 ```
 subject:    "ICON [Role] Brief description"
 activeForm: "ICON Verb-ing description"
 ```
 
+## Agent Tool Format
+
+```
+description: "ICON [Role] Brief description"
+```
+
 ## Icon Map
 
 | Agent Type | Icon | Example subject |
@@ -30,9 +43,17 @@ activeForm: "ICON Verb-ing description"
 
 ## Examples
 
-**Wrong:** `subject: "Run infrastructure tests"` (no icon, no role)
+### TaskCreate
+
+**Wrong:** `Run infrastructure tests` ← no icon, no role
+
+**Right:** `🧪 [Tester] Run infrastructure tests` ← icon + role prefix
+
+### Agent Tool
+
+**Wrong:** `description: "Find entity files"` (no icon, no role)
 
-**Right:** `subject: "🧪 [Tester] Run infrastructure tests"` (icon + role prefix)
+**Right:** `description: "🔍 [Explorer] Find entity files"` (icon + role prefix)
 
 ## Why This Matters
 

package/.claude/guidance/shipped/moflo-workflow-engine-architecture.md

@@ -0,0 +1,145 @@
+# Workflow Engine & Messaging Architecture
+
+**Purpose:** Architectural decisions and analysis findings for Epic #100 (Generalized Workflow Engine) and Epic #110 (Messaging Migration). Reference when working on stories #100-#117.
+
+---
+
+## Epic #100: Generalized Workflow Engine
+
+**Ships as part of moflo** — not a separate project. Heavy deps (Playwright, isolated-vm) are optional peer dependencies, same pattern as `@claude-flow/embeddings` requiring `sql.js`.
+
+### Command Pattern for Steps
+
+Every workflow step type implements a `StepCommand` interface with `execute()`, `validate()`, `describeOutputs()`, and optional `rollback()`. Register step commands via a plugin-style `StepCommandRegistry` — follow the existing `PluginRegistry` pattern in `src/packages/plugins/`.
+
+### Workflow Definitions
+
+Workflows are YAML/JSON files in `workflows/` or `.claude/workflows/`. Each declares:
+- `name` and `abbreviation` (short name for `/flo -wf {abbrev}`)
+- Typed `arguments` with `required`, `default`, `enum`, `description`
+- Ordered `steps` with `{stepId.outputKey}` variable interpolation
+
+### MoFlo Integration Levels Per Step
+
+| Level | Capabilities | Default For |
+|-------|-------------|-------------|
+| `none` | No MoFlo access | `bash`, `condition`, `wait` |
+| `memory` | search/store/list | `agent` steps |
+| `hooks` | Above + pre/post task hooks | — |
+| `full` | Above + swarm/hive-mind spawning | — |
+| `recursive` | Above + nested `/flo -wf` invocation | — |
+
+Capabilities only narrow going deeper — a nested workflow cannot escalate beyond its parent.
+
+### Sandboxing Tiers
+
+| Tier | Mechanism | Status |
+|------|-----------|--------|
+| 1 | Capability declarations + enforcement | Build first |
+| 2 | Node `--experimental-permission` for bash steps | Build second |
+| 3 | `isolated-vm` for expression evaluation | Build third |
+| 4 | Linux namespaces (optional) | Defer |
+| 5 | WASM sandbox for community commands | Defer |
+
+### Build Order (no circular dependencies)
+
+| Phase | Stories | Can Start |
+|-------|---------|-----------|
+| 1 | #101 (Interface), #103 (Schema) | Immediately |
+| 2 | #102 (Commands), #106 (Credentials) | After Phase 1 |
+| 3 | #104 (Runner) | After Phase 2 |
+| 4 | #105 (Registry), #108 (Sandboxing T1-2), #107 (Playwright) | After Phase 3 |
+| 5 | #109 (Integration Levels), #117 (Scheduling) | After Phase 4 + Epic #110 |
+
+### Critical Findings
+
+- **Existing `workflow_execute` is a no-op placeholder.** The engine is greenfield.
+- **`js-yaml` already a dependency** — used in `moflo-config.ts` and `epic.ts`.
+- **Plugin registry pattern is directly reusable** for `StepCommandRegistry`.
+- **No cron support exists** — needs `node-cron` dependency for #117.
+- **Retry logic is consumer-side**, not bus-side. Steps implement their own retry.
+
+---
+
+## Epic #110: Messaging Migration to Memory DB
+
+**Migrate inter-agent messaging** from in-memory EventEmitter bus to memory DB namespace. The current bus only works within a single process — spawned subagents cannot participate.
+
+### Session Isolation
+
+All messages scoped by `sessionId`. Queries implicitly filter by current session. `endSession()` expires unhandled messages. `gc()` cleans up abandoned sessions after configurable TTL.
+
+### Build Order
+
+| Phase | Stories |
+|-------|---------|
+| 1 | #111 (Schema + CRUD) |
+| 2 | #112 (Notification/Pub-Sub) |
+| 3 | #113, #114, #115 (parallel) |
+| 4 | #116 (Deprecate old bus — last) |
+
+**Minimum viable to unblock Epic #100:** #111 + #112 only.
+
+### Critical Findings
+
+- **`queen-coordinator.ts` does NOT use MessageBus.** Hive-mind operates via MCP tools. Story #114 is greenfield, not migration.
+- **`unified-coordinator.ts` is coupled to concrete `MessageBus` class**, not `IMessageBus` interface. Must refactor.
+- **Zero existing message bus tests.** Write baseline suite first, then verify both backends pass.
+- **Two competing Message types:** `SwarmMessage` (shared/types.ts) vs `Message` (swarm/types.ts). Story #111 must reconcile.
+- **Memory DB supports namespaces and TTL** but needs queue semantics and metadata indexing added.
+- **`enablePersistence` config flag exists but was never implemented** — now being properly built.
+
+### Interface Incompatibility: Not a Clean Swap
+
+The `MemoryDbMessageBus` adapter (~300 lines) must handle:
+
+| Aspect | Current `IMessageBus` | New `MessageStore` |
+|--------|----------------------|-------------------|
+| Subscribe | Push-based callback | Pull-based `receive()` |
+| Acknowledge | `acknowledge(ack)` | `markRead()` |
+| Timestamps | `Date` objects | `number` (epoch ms) |
+| Sessions | None | `sessionId` required |
+| Channels | None (per-agent queues) | Channel-based routing |
+
+---
+
+## Epic #118: Consolidate Messaging Systems (Pre-req for #110)
+
+**Three messaging systems → one layered broker.** Must complete before Epic #110 migration.
+
+| Story | What | Depends On |
+|-------|------|------------|
+| #119 | Unified Message Type & Extended IMessageBus | — |
+| #120 | SwarmCommunication → MessageBus consumer | #119 |
+| #121 | Hive-Mind → MessageBus + Memory DB write-through | #119, #120 |
+
+**Key decisions:**
+- MessageBus keeps its Deque hot path for delivery (~1000+ msg/sec)
+- Memory DB write-through is fire-and-forget, initially only for hive-mind namespace
+- TTL reaper lives in the broker (60s sweep), not the daemon
+- Daemon can do deeper GC pass but system must not depend on it
+
+**Build order:** Epic #118 → remaining #110 stories (#111, #115, #116) → Epic #100 Phase 5.
+
+---
+
+## Cross-Epic Dependencies
+
+**Most of Epic #100 can proceed without Epic #110.** Only two things are hard-blocked:
+
+| Blocked Story | Needs from #110 | Why |
+|--------------|-----------------|-----|
+| #109 `full` tier | #113 (Swarm Migration) | Swarm spawning needs DB-backed messaging |
+| #109 `recursive` tier | #113 + #114 | Nested workflows with hive-mind need consensus messaging |
+
+Stories #101-#108, #105, #117 have no dependency on Epic #110.
+
+**Epic #118 simplifies #110:** #112 (pub/sub) largely solved, #113 (swarm) done via #120, #114 (hive-mind) done via #121.
+
+---
+
+## See Also
+
+- `.claude/guidance/shipped/moflo-core-guidance.md` — CLI, hooks, swarm, memory reference
+- `.claude/guidance/shipped/moflo-claude-swarm-cohesion.md` — Task & swarm coordination
+- `.claude/guidance/shipped/moflo-subagents.md` — Subagents protocol