moflo 4.12.4-rc.2 → 4.12.4-rc.4

package/.claude/agents/core/coder.md

@@ -195,36 +195,29 @@ src/
 ## MCP Tool Integration
 
 ### Memory Coordination
-```javascript
-// Report implementation status
-mcp__moflo__memory_store {
-    key: "swarm/coder/status",
-  namespace: "coordination",
-  value: JSON.stringify({
-    agent: "coder",
-    status: "implementing",
-    feature: "user authentication",
-    files: ["auth.service.ts", "auth.controller.ts"],
-    timestamp: Date.now()
-  })
-}
 
+Store decisions that outlive this run, in the namespaces named in your operating
+context above. Prose in `value` — it is what gets embedded, so a JSON blob
+retrieves badly; structure goes in `metadata`, stored verbatim.
+
+```javascript
 // Share code decisions
 mcp__moflo__memory_store {
-    key: "swarm/shared/implementation",
-  namespace: "coordination",
-  value: JSON.stringify({
-    type: "code",
+  namespace: "patterns",
+  key: "auth-service-shape",
+  value: "Auth is a singleton service behind a factory so the jwt signer can be swapped in tests; endpoints are /auth/login and /auth/logout on the express router.",
+  metadata: {
     patterns: ["singleton", "factory"],
     dependencies: ["express", "jwt"],
-    api_endpoints: ["/auth/login", "/auth/logout"]
-  })
+    apiEndpoints: ["/auth/login", "/auth/logout"]
+  }
 }
 
-// Check dependencies
-mcp__moflo__memory_retrieve {
-    key: "swarm/shared/dependencies",
-  namespace: "coordination"
+// Look up what an earlier agent established. Semantic search first — reach for
+// memory_retrieve only when you already know the exact key.
+mcp__moflo__memory_search {
+  query: "auth service dependencies",
+  namespace: "patterns"
 }
 ```
 
@@ -232,7 +225,7 @@ mcp__moflo__memory_retrieve {
 ```javascript
 // Track implementation metrics
 mcp__moflo__performance_benchmark {
-  type: "code",
+  suite: "memory",
   iterations: 10
 }
 

package/.claude/agents/core/planner.md

@@ -114,45 +114,67 @@ plan:
 ## MCP Tool Integration
 
 ### Task Orchestration
-```javascript
-// Orchestrate complex tasks
 
-// Share task breakdown
-mcp__moflo__memory_store {
-    key: "swarm/planner/task-breakdown",
-  namespace: "coordination",
-  value: JSON.stringify({
-    main_task: "authentication",
-    subtasks: [
-      {id: "1", task: "Research auth libraries", assignee: "researcher"},
-      {id: "2", task: "Design auth flow", assignee: "architect"},
-      {id: "3", task: "Implement auth service", assignee: "coder"},
-      {id: "4", task: "Write auth tests", assignee: "tester"}
-    ],
-    dependencies: {"3": ["1", "2"], "4": ["3"]}
-  })
+Submit the breakdown to the coordinator. A task ID only exists once the
+coordinator has issued it — storing a breakdown in memory dispatches nothing,
+and polling an ID you invented yourself always comes back empty.
+
+```javascript
+// Submit the whole breakdown in one call. Tasks are load-balanced across
+// available agents; `type` must be one of research | analysis | coding |
+// testing | review | documentation | coordination | consensus | custom.
+mcp__moflo__task_orchestrate {
+  tasks: [
+    { type: "research",      description: "Research auth libraries",  priority: "high" },
+    { type: "analysis",      description: "Design auth flow",         priority: "high" },
+    { type: "coding",        description: "Implement auth service",   priority: "normal" },
+    { type: "testing",       description: "Write auth tests",         priority: "normal" }
+  ]
 }
+// → { success: true, submitted: 4, assigned: 3, queued: 1,
+//     tasks: [ { taskId: "task_...", status: "assigned", ... }, ... ] }
 
-// Monitor task progress
+// Poll an ID the coordinator returned — never one you named yourself.
 mcp__moflo__task_status {
-  taskId: "auth-implementation"
+  taskId: "<taskId from the response above>"
 }
+
+// Or survey everything in flight instead of polling one at a time.
+mcp__moflo__task_list { status: "running,queued" }
 ```
 
+Use `mcp__moflo__task_create` for a single task; it takes the same fields and
+returns the same projection, including the `taskId`.
+
+**Ordering lives on the native Task layer, not here.** `task_create` and
+`task_orchestrate` accept no dependency field — the coordinator load-balances
+what you submit. Express prerequisites with `TaskUpdate({ addBlockedBy: [...] })`
+on the native tasks, per *What → Native Tasks; How → MoFlo orchestration* in
+`.claude/guidance/moflo-claude-swarm-cohesion.md`.
+
 ### Memory Coordination
+
+Live task state belongs to the coordinator — read it with `task_status` /
+`task_list` rather than mirroring it into memory. Store what stays useful after
+this run: a decision and its rationale that a future agent would otherwise have
+to rediscover.
+
 ```javascript
-// Report planning status
+// Prose in `value` — it is what gets embedded, so a JSON blob retrieves badly.
+// Structure goes in `metadata`, which is stored verbatim and not embedded.
 mcp__moflo__memory_store {
-    key: "swarm/planner/status",
-  namespace: "coordination",
-  value: JSON.stringify({
-    agent: "planner",
-    status: "planning",
-    tasks_planned: 12,
-    estimated_hours: 24,
-    timestamp: Date.now()
-  })
+  namespace: "patterns",
+  key: "auth-rollout-sequencing",
+  value: "Auth work is sequenced research → design → implement → test because the library choice determines the flow design; parallelising design against research produced rework twice.",
+  metadata: {
+    plannedTasks: 12,
+    blockedOn: ["library selection"]
+  }
 }
 ```
 
-Remember: A good plan executed now is better than a perfect plan executed never. Focus on creating actionable, practical plans that drive progress. Always coordinate through memory.
+Use the namespaces named in this agent's operating context above — `patterns`
+for reusable approaches, `learnings` for decisions and gotchas. The `swarm-*`
+namespaces are the coordinator's own persistence; do not write to them.
+
+Remember: A good plan executed now is better than a perfect plan executed never. Focus on creating actionable, practical plans that drive progress. Dispatch through the coordinator; use memory for what outlives the run.

package/.claude/agents/core/researcher.md

@@ -119,36 +119,29 @@ read specific-file.ts
 ## MCP Tool Integration
 
 ### Memory Coordination
-```javascript
-// Report research status
-mcp__moflo__memory_store {
-    key: "swarm/researcher/status",
-  namespace: "coordination",
-  value: JSON.stringify({
-    agent: "researcher",
-    status: "analyzing",
-    focus: "authentication system",
-    files_reviewed: 25,
-    timestamp: Date.now()
-  })
-}
 
+Store findings that stay useful after this run, in the namespaces named in your
+operating context above. Prose in `value` — it is what gets embedded, so a JSON
+blob retrieves badly; structure goes in `metadata`, stored verbatim.
+
+```javascript
 // Share research findings
 mcp__moflo__memory_store {
-    key: "swarm/shared/research-findings",
-  namespace: "coordination",
-  value: JSON.stringify({
-    patterns_found: ["MVC", "Repository", "Factory"],
+  namespace: "patterns",
+  key: "auth-stack-survey",
+  value: "Auth here is passport + jwt behind an MVC/repository split; the passport version is two majors behind and there is no rate limiting on the login route.",
+  metadata: {
+    patternsFound: ["MVC", "Repository", "Factory"],
     dependencies: ["express", "passport", "jwt"],
-    potential_issues: ["outdated auth library", "missing rate limiting"],
     recommendations: ["upgrade passport", "add rate limiter"]
-  })
+  }
 }
 
-// Check prior research
+// Check prior research. memory_search is semantic — it takes a `query`, not a
+// key glob. Pivot the query on the bare symbol or topic.
 mcp__moflo__memory_search {
-  pattern: "swarm/shared/research-*",
-  namespace: "coordination",
+  query: "authentication stack",
+  namespace: "patterns",
   limit: 10
 }
 ```
@@ -171,14 +164,14 @@ mcp__moflo__agent_status {
 - Share findings with planner for task decomposition via memory
 - Provide context to coder for implementation through shared memory
 - Supply tester with edge cases and scenarios in memory
-- Document all findings in coordination memory
+- Document findings in the `patterns` namespace so later agents retrieve them
 
 ## Best Practices
 
 1. **Be Thorough**: Check multiple sources and validate findings
 2. **Stay Organized**: Structure research logically and maintain clear notes
 3. **Think Critically**: Question assumptions and verify claims
-4. **Document Everything**: Store all findings in coordination memory
+4. **Document Everything**: Store findings in `patterns` (or `learnings` for decisions and gotchas)
 5. **Iterate**: Refine research based on new discoveries
 6. **Share Early**: Update memory frequently for real-time coordination
 

package/.claude/agents/core/reviewer.md

@@ -269,36 +269,29 @@ npm run complexity-check
 ## MCP Tool Integration
 
 ### Memory Coordination
-```javascript
-// Report review status
-mcp__moflo__memory_store {
-    key: "swarm/reviewer/status",
-  namespace: "coordination",
-  value: JSON.stringify({
-    agent: "reviewer",
-    status: "reviewing",
-    files_reviewed: 12,
-    issues_found: {critical: 2, major: 5, minor: 8},
-    timestamp: Date.now()
-  })
-}
 
+Store findings that outlive this run, in the namespaces named in your operating
+context above. Prose in `value` — it is what gets embedded, so a JSON blob
+retrieves badly; structure goes in `metadata`, stored verbatim.
+
+```javascript
 // Share review findings
 mcp__moflo__memory_store {
-    key: "swarm/shared/review-findings",
-  namespace: "coordination",
-  value: JSON.stringify({
-    security_issues: ["SQL injection in auth.js:45"],
-    performance_issues: ["N+1 queries in user.service.ts"],
-    code_quality: {score: 7.8, coverage: "78%"},
-    action_items: ["Fix SQL injection", "Optimize queries", "Add tests"]
-  })
+  namespace: "patterns",
+  key: "auth-review-findings",
+  value: "Login builds its SQL by string concatenation (auth.js:45) and the user service loads roles per-row inside a loop, so both the injection risk and the N+1 come from the same request path.",
+  metadata: {
+    securityIssues: ["SQL injection in auth.js:45"],
+    performanceIssues: ["N+1 queries in user.service.ts"],
+    actionItems: ["Fix SQL injection", "Batch the role lookup", "Add tests"]
+  }
 }
 
-// Check implementation details
-mcp__moflo__memory_retrieve {
-    key: "swarm/coder/status",
-  namespace: "coordination"
+// Look up what the implementer established. Semantic search first — reach for
+// memory_retrieve only when you already know the exact key.
+mcp__moflo__memory_search {
+  query: "auth service shape",
+  namespace: "patterns"
 }
 ```
 
@@ -311,7 +304,7 @@ mcp__moflo__analyze_diff {
 
 // Scan the diff for prompt-injection and unsafe content
 mcp__moflo__aidefence_scan {
-  content: "<the diff or file under review>"
+  input: "<the diff or file under review>"
 }
 ```
 

package/.claude/agents/core/tester.md

@@ -251,35 +251,30 @@ describe('Security', () => {
 ## MCP Tool Integration
 
 ### Memory Coordination
-```javascript
-// Report test status
-mcp__moflo__memory_store {
-    key: "swarm/tester/status",
-  namespace: "coordination",
-  value: JSON.stringify({
-    agent: "tester",
-    status: "running tests",
-    test_suites: ["unit", "integration", "e2e"],
-    timestamp: Date.now()
-  })
-}
 
-// Share test results
+Store what stays useful after this run, in the namespaces named in your
+operating context above. Prose in `value` — it is what gets embedded, so a JSON
+blob retrieves badly; structure goes in `metadata`, stored verbatim.
+
+```javascript
+// Share what the run revealed, not the raw tally
 mcp__moflo__memory_store {
-    key: "swarm/shared/test-results",
-  namespace: "coordination",
-  value: JSON.stringify({
+  namespace: "patterns",
+  key: "auth-suite-flakiness",
+  value: "The two failing auth tests both assert on token expiry against a real clock, so they fail whenever the suite runs slowly under load — freeze the clock rather than widening the tolerance.",
+  metadata: {
     passed: 145,
     failed: 2,
     coverage: "87%",
     failures: ["auth.test.ts:45", "api.test.ts:123"]
-  })
+  }
 }
 
-// Check implementation status
-mcp__moflo__memory_retrieve {
-    key: "swarm/coder/status",
-  namespace: "coordination"
+// Look up what the implementer established. Semantic search first — reach for
+// memory_retrieve only when you already know the exact key.
+mcp__moflo__memory_search {
+  query: "auth service shape",
+  namespace: "patterns"
 }
 ```
 
@@ -287,7 +282,7 @@ mcp__moflo__memory_retrieve {
 ```javascript
 // Run performance benchmarks
 mcp__moflo__performance_benchmark {
-  type: "test",
+  suite: "all",
   iterations: 100
 }
 

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

@@ -94,6 +94,8 @@ npx flo hive-mind init --topology hierarchical-mesh --consensus byzantine
 
 Include task IDs in agent prompts. The `SubagentStart` hook automatically injects the subagent protocol directive — don't repeat it.
 
+Asking for a swarm is asking for agents: an ambient "don't call the Agent tool unless the user requested it" is satisfied by that request. Registering agents via MCP without dispatching them leaves a swarm that passes every gate and does no parallel work.
+
 ```javascript
 TaskUpdate({ taskId: "1", status: "in_progress" })
 Task({

package/.claude/guidance/shipped/moflo-memory-strategy.md

@@ -35,6 +35,7 @@ Source files (`.claude/guidance/*.md`, `docs/**/*.md`, code, tests) flow through
 | `patterns` | Per-file code patterns (services, routes, exports) | `index-patterns.mjs` |
 | `tests` | Test structure and patterns | `index-tests.mjs` |
 | `learnings` | User-stored patterns from work sessions | `mcp__moflo__memory_store` |
+| `verify` | Per-run `/verify` verdict records, keyed `verify:<slug>` | `/verify` skill Step 5 |
 
 Namespaces are independent indexes. Search defaults to `all`; pass `namespace: "guidance"` to target one.
 

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

@@ -64,7 +64,7 @@ The two review checkpoints are the point: **a spec must be reviewed before its p
 When enforced, `gh pr create` is blocked until the change has been verified end-to-end since the last code edit.
 
 - **On by default (#1294).** Enforced for every `/flo` run; disable per-project with `gates.verify_before_done: false` or per-run with `--no-verify`. On upgrade, consumers with no `verify_before_done` key start enforcing; an explicit value is preserved. Docs-only diffs are exempt, so a pure-docs PR is never blocked.
-- **Satisfy it by running the `/verify` skill** — `/flo` delegates to it. It exercises the change against the plan's (or ticket's) acceptance criteria and records its own outcome to memory (`namespace: learnings, key: verify:<slug>`). It reuses the Tests-phase run rather than repeating it (no double verify).
+- **Satisfy it by running the `/verify` skill** — `/flo` delegates to it. It exercises the change against the plan's (or ticket's) acceptance criteria and records its own outcome to memory (`namespace: verify, key: verify:<slug>`). It reuses the Tests-phase run rather than repeating it (no double verify).
 - **A source edit invalidates a prior verification** — re-run `/verify` after editing. `/ward` and `/quicken` are targeted audits, not the completion gate.
 
 ---