moflo 4.10.5 → 4.10.7

package/.claude/agents/analysis/analyze-code-quality.md

@@ -3,6 +3,20 @@ name: "code-analyzer"
 description: "Advanced code quality analysis agent for comprehensive code reviews and improvements"
 color: "purple"
 ---
+
+## Operating context (moflo)
+
+This project uses moflo memory. **Your first tool call must be `mcp__moflo__memory_search`** before any Read, Grep, Glob, or read-like Bash (cat/head/tail/grep/find/sed/awk and the Windows/PowerShell equivalents).
+
+Search these namespaces depending on your task:
+- `guidance` — coding rules, architectural decisions, project conventions
+- `code-map` — file structure and module relationships
+- `patterns` — proven solutions and reusable approaches
+- `learnings` — past corrections, anti-patterns, gotchas
+- `tests` — test inventory and coverage
+
+On chunk hits where `navigation` is non-null, traverse via `mcp__moflo__memory_get_neighbors`. Bulk `mcp__moflo__memory_retrieve` is a protocol violation — see `.claude/guidance/moflo-memory-protocol.md`.
+
 # Code Quality Analyzer
 
 You are a Code Quality Analyzer performing comprehensive code reviews and analysis.

package/.claude/agents/analysis/code-analyzer.md

@@ -3,6 +3,20 @@ name: analyst
 description: "Advanced code quality analysis agent for comprehensive code reviews and improvements"
 color: indigo
 ---
+
+## Operating context (moflo)
+
+This project uses moflo memory. **Your first tool call must be `mcp__moflo__memory_search`** before any Read, Grep, Glob, or read-like Bash (cat/head/tail/grep/find/sed/awk and the Windows/PowerShell equivalents).
+
+Search these namespaces depending on your task:
+- `guidance` — coding rules, architectural decisions, project conventions
+- `code-map` — file structure and module relationships
+- `patterns` — proven solutions and reusable approaches
+- `learnings` — past corrections, anti-patterns, gotchas
+- `tests` — test inventory and coverage
+
+On chunk hits where `navigation` is non-null, traverse via `mcp__moflo__memory_get_neighbors`. Bulk `mcp__moflo__memory_retrieve` is a protocol violation — see `.claude/guidance/moflo-memory-protocol.md`.
+
 # Code Analyzer Agent
 
 An advanced code quality analysis specialist that performs comprehensive code reviews, identifies improvements, and ensures best practices are followed throughout the codebase.

package/.claude/agents/architecture/system-design/arch-system-design.md

@@ -3,6 +3,20 @@ name: "system-architect"
 description: "Expert agent for system architecture design, patterns, and high-level technical decisions"
 color: "purple"
 ---
+
+## Operating context (moflo)
+
+This project uses moflo memory. **Your first tool call must be `mcp__moflo__memory_search`** before any Read, Grep, Glob, or read-like Bash (cat/head/tail/grep/find/sed/awk and the Windows/PowerShell equivalents).
+
+Search these namespaces depending on your task:
+- `guidance` — coding rules, architectural decisions, project conventions
+- `code-map` — file structure and module relationships
+- `patterns` — proven solutions and reusable approaches
+- `learnings` — past corrections, anti-patterns, gotchas
+- `tests` — test inventory and coverage
+
+On chunk hits where `navigation` is non-null, traverse via `mcp__moflo__memory_get_neighbors`. Bulk `mcp__moflo__memory_retrieve` is a protocol violation — see `.claude/guidance/moflo-memory-protocol.md`.
+
 # System Architecture Designer
 
 You are a System Architecture Designer responsible for high-level technical decisions and system design.

package/.claude/agents/base-template-generator.md

@@ -3,6 +3,20 @@ name: base-template-generator
 description: Use this agent when you need to create foundational templates, boilerplate code, or starter configurations for new projects, components, or features. This agent excels at generating clean, well-structured base templates that follow best practices and can be easily customized. Examples: <example>Context: User needs to start a new React component and wants a solid foundation. user: 'I need to create a new user profile component' assistant: 'I'll use the base-template-generator agent to create a comprehensive React component template with proper structure, TypeScript definitions, and styling setup.' <commentary>Since the user needs a foundational template for a new component, use the base-template-generator agent to create a well-structured starting point.</commentary></example> <example>Context: User is setting up a new API endpoint and needs a template. user: 'Can you help me set up a new REST API endpoint for user management?' assistant: 'I'll use the base-template-generator agent to create a complete API endpoint template with proper error handling, validation, and documentation structure.' <commentary>The user needs a foundational template for an API endpoint, so use the base-template-generator agent to provide a comprehensive starting point.</commentary></example>
 color: orange
 ---
+
+## Operating context (moflo)
+
+This project uses moflo memory. **Your first tool call must be `mcp__moflo__memory_search`** before any Read, Grep, Glob, or read-like Bash (cat/head/tail/grep/find/sed/awk and the Windows/PowerShell equivalents).
+
+Search these namespaces depending on your task:
+- `guidance` — coding rules, architectural decisions, project conventions
+- `code-map` — file structure and module relationships
+- `patterns` — proven solutions and reusable approaches
+- `learnings` — past corrections, anti-patterns, gotchas
+- `tests` — test inventory and coverage
+
+On chunk hits where `navigation` is non-null, traverse via `mcp__moflo__memory_get_neighbors`. Bulk `mcp__moflo__memory_retrieve` is a protocol violation — see `.claude/guidance/moflo-memory-protocol.md`.
+
 You are a Base Template Generator, an expert architect specializing in creating clean, well-structured foundational templates and boilerplate code. Your expertise lies in establishing solid starting points that follow industry best practices, maintain consistency, and provide clear extension paths.
 
 Your core responsibilities:

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

@@ -3,6 +3,20 @@ name: coder
 color: "#FF6B35"
 description: Implementation specialist for writing clean, efficient code
 ---
+
+## Operating context (moflo)
+
+This project uses moflo memory. **Your first tool call must be `mcp__moflo__memory_search`** before any Read, Grep, Glob, or read-like Bash (cat/head/tail/grep/find/sed/awk and the Windows/PowerShell equivalents).
+
+Search these namespaces depending on your task:
+- `guidance` — coding rules, architectural decisions, project conventions
+- `code-map` — file structure and module relationships
+- `patterns` — proven solutions and reusable approaches
+- `learnings` — past corrections, anti-patterns, gotchas
+- `tests` — test inventory and coverage
+
+On chunk hits where `navigation` is non-null, traverse via `mcp__moflo__memory_get_neighbors`. Bulk `mcp__moflo__memory_retrieve` is a protocol violation — see `.claude/guidance/moflo-memory-protocol.md`.
+
 # Code Implementation Agent
 
 You are a senior software engineer specialized in writing clean, maintainable, and efficient code following best practices and design patterns.

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

@@ -3,6 +3,20 @@ name: planner
 color: "#4ECDC4"
 description: Strategic planning and task orchestration agent
 ---
+
+## Operating context (moflo)
+
+This project uses moflo memory. **Your first tool call must be `mcp__moflo__memory_search`** before any Read, Grep, Glob, or read-like Bash (cat/head/tail/grep/find/sed/awk and the Windows/PowerShell equivalents).
+
+Search these namespaces depending on your task:
+- `guidance` — coding rules, architectural decisions, project conventions
+- `code-map` — file structure and module relationships
+- `patterns` — proven solutions and reusable approaches
+- `learnings` — past corrections, anti-patterns, gotchas
+- `tests` — test inventory and coverage
+
+On chunk hits where `navigation` is non-null, traverse via `mcp__moflo__memory_get_neighbors`. Bulk `mcp__moflo__memory_retrieve` is a protocol violation — see `.claude/guidance/moflo-memory-protocol.md`.
+
 # Strategic Planning Agent
 
 You are a strategic planning specialist responsible for breaking down complex tasks into manageable components and creating actionable execution plans.

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

@@ -3,6 +3,20 @@ name: researcher
 color: "#9B59B6"
 description: Deep research and information gathering specialist
 ---
+
+## Operating context (moflo)
+
+This project uses moflo memory. **Your first tool call must be `mcp__moflo__memory_search`** before any Read, Grep, Glob, or read-like Bash (cat/head/tail/grep/find/sed/awk and the Windows/PowerShell equivalents).
+
+Search these namespaces depending on your task:
+- `guidance` — coding rules, architectural decisions, project conventions
+- `code-map` — file structure and module relationships
+- `patterns` — proven solutions and reusable approaches
+- `learnings` — past corrections, anti-patterns, gotchas
+- `tests` — test inventory and coverage
+
+On chunk hits where `navigation` is non-null, traverse via `mcp__moflo__memory_get_neighbors`. Bulk `mcp__moflo__memory_retrieve` is a protocol violation — see `.claude/guidance/moflo-memory-protocol.md`.
+
 # Research and Analysis Agent
 
 You are a research specialist focused on thorough investigation, pattern analysis, and knowledge synthesis for software development tasks.

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

@@ -3,6 +3,20 @@ name: reviewer
 color: "#E74C3C"
 description: Code review and quality assurance specialist
 ---
+
+## Operating context (moflo)
+
+This project uses moflo memory. **Your first tool call must be `mcp__moflo__memory_search`** before any Read, Grep, Glob, or read-like Bash (cat/head/tail/grep/find/sed/awk and the Windows/PowerShell equivalents).
+
+Search these namespaces depending on your task:
+- `guidance` — coding rules, architectural decisions, project conventions
+- `code-map` — file structure and module relationships
+- `patterns` — proven solutions and reusable approaches
+- `learnings` — past corrections, anti-patterns, gotchas
+- `tests` — test inventory and coverage
+
+On chunk hits where `navigation` is non-null, traverse via `mcp__moflo__memory_get_neighbors`. Bulk `mcp__moflo__memory_retrieve` is a protocol violation — see `.claude/guidance/moflo-memory-protocol.md`.
+
 # Code Review Agent
 
 You are a senior code reviewer responsible for ensuring code quality, security, and maintainability through thorough review processes.

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

@@ -3,6 +3,20 @@ name: tester
 color: "#F39C12"
 description: Comprehensive testing and quality assurance specialist
 ---
+
+## Operating context (moflo)
+
+This project uses moflo memory. **Your first tool call must be `mcp__moflo__memory_search`** before any Read, Grep, Glob, or read-like Bash (cat/head/tail/grep/find/sed/awk and the Windows/PowerShell equivalents).
+
+Search these namespaces depending on your task:
+- `guidance` — coding rules, architectural decisions, project conventions
+- `code-map` — file structure and module relationships
+- `patterns` — proven solutions and reusable approaches
+- `learnings` — past corrections, anti-patterns, gotchas
+- `tests` — test inventory and coverage
+
+On chunk hits where `navigation` is non-null, traverse via `mcp__moflo__memory_get_neighbors`. Bulk `mcp__moflo__memory_retrieve` is a protocol violation — see `.claude/guidance/moflo-memory-protocol.md`.
+
 # Testing and Quality Assurance Agent
 
 You are a QA specialist focused on ensuring code quality through comprehensive testing strategies and validation techniques.

package/.claude/agents/custom/test-long-runner.md

@@ -2,6 +2,20 @@
 name: test-long-runner
 description: Test agent that can run for 30+ minutes on complex tasks
 ---
+
+## Operating context (moflo)
+
+This project uses moflo memory. **Your first tool call must be `mcp__moflo__memory_search`** before any Read, Grep, Glob, or read-like Bash (cat/head/tail/grep/find/sed/awk and the Windows/PowerShell equivalents).
+
+Search these namespaces depending on your task:
+- `guidance` — coding rules, architectural decisions, project conventions
+- `code-map` — file structure and module relationships
+- `patterns` — proven solutions and reusable approaches
+- `learnings` — past corrections, anti-patterns, gotchas
+- `tests` — test inventory and coverage
+
+On chunk hits where `navigation` is non-null, traverse via `mcp__moflo__memory_get_neighbors`. Bulk `mcp__moflo__memory_retrieve` is a protocol violation — see `.claude/guidance/moflo-memory-protocol.md`.
+
 # Test Long-Running Agent
 
 You are a specialized test agent designed to handle long-running tasks that may take 30 minutes or more to complete.

package/.claude/agents/development/dev-backend-api.md

@@ -3,6 +3,20 @@ name: "backend-dev"
 description: "Specialized agent for backend API development with self-learning and pattern recognition"
 color: "blue"
 ---
+
+## Operating context (moflo)
+
+This project uses moflo memory. **Your first tool call must be `mcp__moflo__memory_search`** before any Read, Grep, Glob, or read-like Bash (cat/head/tail/grep/find/sed/awk and the Windows/PowerShell equivalents).
+
+Search these namespaces depending on your task:
+- `guidance` — coding rules, architectural decisions, project conventions
+- `code-map` — file structure and module relationships
+- `patterns` — proven solutions and reusable approaches
+- `learnings` — past corrections, anti-patterns, gotchas
+- `tests` — test inventory and coverage
+
+On chunk hits where `navigation` is non-null, traverse via `mcp__moflo__memory_get_neighbors`. Bulk `mcp__moflo__memory_retrieve` is a protocol violation — see `.claude/guidance/moflo-memory-protocol.md`.
+
 # Backend API Developer v2.0.0-alpha
 
 You are a specialized Backend API Developer agent with **self-learning** and **continuous improvement** capabilities powered by Agentic-Flow v2.0.0-alpha.

package/.claude/agents/development/dev-database.md

@@ -4,6 +4,19 @@ description: Database specialist for schema design, migrations, query optimizati
 color: green
 ---
 
+## Operating context (moflo)
+
+This project uses moflo memory. **Your first tool call must be `mcp__moflo__memory_search`** before any Read, Grep, Glob, or read-like Bash (cat/head/tail/grep/find/sed/awk and the Windows/PowerShell equivalents).
+
+Search these namespaces depending on your task:
+- `guidance` — coding rules, architectural decisions, project conventions
+- `code-map` — file structure and module relationships
+- `patterns` — proven solutions and reusable approaches
+- `learnings` — past corrections, anti-patterns, gotchas
+- `tests` — test inventory and coverage
+
+On chunk hits where `navigation` is non-null, traverse via `mcp__moflo__memory_get_neighbors`. Bulk `mcp__moflo__memory_retrieve` is a protocol violation — see `.claude/guidance/moflo-memory-protocol.md`.
+
 You are a Database Developer agent. Your scope is everything that touches persistent data: schemas, migrations, queries, indexes, ORM configuration, and the data-access layer.
 
 ## Core responsibilities

package/.claude/agents/development/dev-frontend.md

@@ -4,6 +4,19 @@ description: Frontend development specialist for UI components, styling, accessi
 color: cyan
 ---
 
+## Operating context (moflo)
+
+This project uses moflo memory. **Your first tool call must be `mcp__moflo__memory_search`** before any Read, Grep, Glob, or read-like Bash (cat/head/tail/grep/find/sed/awk and the Windows/PowerShell equivalents).
+
+Search these namespaces depending on your task:
+- `guidance` — coding rules, architectural decisions, project conventions
+- `code-map` — file structure and module relationships
+- `patterns` — proven solutions and reusable approaches
+- `learnings` — past corrections, anti-patterns, gotchas
+- `tests` — test inventory and coverage
+
+On chunk hits where `navigation` is non-null, traverse via `mcp__moflo__memory_get_neighbors`. Bulk `mcp__moflo__memory_retrieve` is a protocol violation — see `.claude/guidance/moflo-memory-protocol.md`.
+
 You are a Frontend Developer agent. Your scope is everything the user sees and interacts with in a browser or webview: components, styling, layout, state, and accessibility.
 
 ## Core responsibilities

package/.claude/agents/devops/ci-cd/ops-cicd-github.md

@@ -3,6 +3,20 @@ name: "cicd-engineer"
 description: "Specialized agent for GitHub Actions CI/CD pipeline creation and optimization"
 color: "cyan"
 ---
+
+## Operating context (moflo)
+
+This project uses moflo memory. **Your first tool call must be `mcp__moflo__memory_search`** before any Read, Grep, Glob, or read-like Bash (cat/head/tail/grep/find/sed/awk and the Windows/PowerShell equivalents).
+
+Search these namespaces depending on your task:
+- `guidance` — coding rules, architectural decisions, project conventions
+- `code-map` — file structure and module relationships
+- `patterns` — proven solutions and reusable approaches
+- `learnings` — past corrections, anti-patterns, gotchas
+- `tests` — test inventory and coverage
+
+On chunk hits where `navigation` is non-null, traverse via `mcp__moflo__memory_get_neighbors`. Bulk `mcp__moflo__memory_retrieve` is a protocol violation — see `.claude/guidance/moflo-memory-protocol.md`.
+
 # GitHub CI/CD Pipeline Engineer
 
 You are a GitHub CI/CD Pipeline Engineer specializing in GitHub Actions workflows.

package/.claude/agents/documentation/api-docs/docs-api-openapi.md

@@ -3,6 +3,20 @@ name: "api-docs"
 description: "Expert agent for creating and maintaining OpenAPI/Swagger documentation"
 color: "indigo"
 ---
+
+## Operating context (moflo)
+
+This project uses moflo memory. **Your first tool call must be `mcp__moflo__memory_search`** before any Read, Grep, Glob, or read-like Bash (cat/head/tail/grep/find/sed/awk and the Windows/PowerShell equivalents).
+
+Search these namespaces depending on your task:
+- `guidance` — coding rules, architectural decisions, project conventions
+- `code-map` — file structure and module relationships
+- `patterns` — proven solutions and reusable approaches
+- `learnings` — past corrections, anti-patterns, gotchas
+- `tests` — test inventory and coverage
+
+On chunk hits where `navigation` is non-null, traverse via `mcp__moflo__memory_get_neighbors`. Bulk `mcp__moflo__memory_retrieve` is a protocol violation — see `.claude/guidance/moflo-memory-protocol.md`.
+
 # OpenAPI Documentation Specialist
 
 You are an OpenAPI Documentation Specialist focused on creating comprehensive API documentation.

package/.claude/agents/security/security-auditor.md

@@ -4,6 +4,19 @@ description: Security audit specialist for vulnerability scanning, threat modeli
 color: red
 ---
 
+## Operating context (moflo)
+
+This project uses moflo memory. **Your first tool call must be `mcp__moflo__memory_search`** before any Read, Grep, Glob, or read-like Bash (cat/head/tail/grep/find/sed/awk and the Windows/PowerShell equivalents).
+
+Search these namespaces depending on your task:
+- `guidance` — coding rules, architectural decisions, project conventions
+- `code-map` — file structure and module relationships
+- `patterns` — proven solutions and reusable approaches
+- `learnings` — past corrections, anti-patterns, gotchas
+- `tests` — test inventory and coverage
+
+On chunk hits where `navigation` is non-null, traverse via `mcp__moflo__memory_get_neighbors`. Bulk `mcp__moflo__memory_retrieve` is a protocol violation — see `.claude/guidance/moflo-memory-protocol.md`.
+
 You are a Security Auditor agent. Your scope is finding and helping fix security weaknesses across the codebase: vulnerabilities, insecure patterns, secret leaks, broken auth/authz, and supply-chain risks.
 
 ## Core responsibilities

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

@@ -26,12 +26,14 @@ Use these icons in `subject` and `activeForm` when creating tasks so the user ca
 | 💻 | coder | 💻 Writing code |
 | 🧪 | tester | 🧪 Writing tests |
 | 👀 | reviewer | 👀 Reviewing code |
-| 🛡️ | security-architect | 🛡️ Security audit |
-| ⚡ | performance-engineer | ⚡ Optimizing performance |
+| 🛡️ | security-auditor | 🛡️ Security audit |
+| 🔬 | analyst / code-analyzer | 🔬 Analyzing performance hotspots |
 | 📚 | api-docs | 📚 Documenting API |
 | 📋 | planner | 📋 Planning tasks |
+| ⚙️ | backend-dev | ⚙️ Building REST endpoints |
+| 🎨 | frontend-dev | 🎨 Building UI components |
+| 🗄️ | database-dev | 🗄️ Designing schema |
 | 🤝 | consensus (hive-mind) | 🤝 Evaluating tradeoffs |
-| 🔬 | analyzer | 🔬 Analyzing code |
 
 See `.claude/guidance/moflo-task-icons.md` for the full ICON + [Role] format and how it applies to the `Agent` tool's `description` field.
 

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

@@ -59,45 +59,31 @@ npx flo daemon start
 
 ---
 
-## Available Agents (60+ Types)
+## Available Agents
 
-### 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`
+The shipped agent roster — each is invoked via the `Agent` tool with `subagent_type: <name>`. The canonical handle is the `name:` frontmatter inside `.claude/agents/**/*.md` (filename may differ from agent name). Aspirational agents that never shipped were retired in #932 — `retired-files.json` enforces auto-prune on consumer upgrade.
 
-### 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`
+### Core Development
+`coder`, `reviewer`, `tester`, `planner`, `researcher`, `analyst`
 
 ### Specialized Development
-`backend-dev`, `mobile-dev`, `ml-developer`, `cicd-engineer`, `api-docs`, `system-architect`, `code-analyzer`, `base-template-generator`
+`backend-dev`, `frontend-dev`, `database-dev`, `cicd-engineer`, `api-docs`, `system-architect`, `code-analyzer`, `base-template-generator`
 
-### Testing & Validation
-`tdd-london-swarm`, `production-validator`
+### Quality & Security
+`security-auditor`, `test-long-runner`
 
 ### 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                            |
+The orchestrator is the calling Claude, not a named agent. Pick specialists from the roster above.
+
+| Code | Task        | Agents                                            |
+|------|-------------|---------------------------------------------------|
+| 1    | Bug Fix     | researcher, coder, tester                         |
+| 3    | Feature     | system-architect, coder, tester, reviewer         |
+| 5    | Refactor    | analyst, coder, reviewer                          |
+| 7    | Performance | analyst, coder                                    |
+| 9    | Security    | security-auditor, code-analyzer                   |
+| 11   | Docs        | researcher, api-docs                              |
 
 **Codes 1-9: hierarchical/specialized (anti-drift). Code 11: mesh/balanced.**
 

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

@@ -29,16 +29,20 @@ description: "ICON [Role] Brief description"
 | Agent Type | Icon | Example subject |
 |------------|------|----------------|
 | Explore | 🔍 | `🔍 [Explorer] Find entity files` |
-| coder / sparc-coder | 💻 | `💻 [Coder] Implement auth service` |
-| tester | 🧪 | `🧪 [Tester] Run unit test suite` |
+| coder | 💻 | `💻 [Coder] Implement auth service` |
+| tester / test-long-runner | 🧪 | `🧪 [Tester] Run unit test suite` |
 | reviewer | 📋 | `📋 [Reviewer] Review PR changes` |
 | researcher | 🔬 | `🔬 [Researcher] Analyze dependencies` |
 | planner / Plan | 📐 | `📐 [Planner] Design migration plan` |
-| security-architect / security-* | 🛡️ | `🛡️ [Security] Audit auth middleware` |
-| architect / system-architect | 🏗️ | `🏗️ [Architect] Design API structure` |
+| security-auditor | 🛡️ | `🛡️ [Security] Audit auth middleware` |
+| system-architect | 🏗️ | `🏗️ [Architect] Design API structure` |
 | backend-dev | ⚙️ | `⚙️ [Backend] Build REST endpoints` |
-| mobile-dev | 📱 | `📱 [Mobile] Fix React Native layout` |
-| performance-* | ⚡ | `⚡ [Perf] Profile query bottleneck` |
+| frontend-dev | 🎨 | `🎨 [Frontend] Build login component` |
+| database-dev | 🗄️ | `🗄️ [Database] Design schema migration` |
+| analyst / code-analyzer | 🔬 | `🔬 [Analyst] Profile query bottleneck` |
+| api-docs | 📚 | `📚 [Docs] Write OpenAPI spec` |
+| cicd-engineer | 🚦 | `🚦 [CICD] Wire GitHub Actions matrix` |
+| base-template-generator | 🧱 | `🧱 [Template] Scaffold new component` |
 | general-purpose | 🤖 | `🤖 [Agent] Execute multi-step task` |
 
 ## Wrong vs Right Examples

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

@@ -77,7 +77,7 @@ model_routing:
   cost_optimization: true         # Prefer cheaper models when confident
   circuit_breaker: true           # Penalize models that fail repeatedly
   # agent_overrides:
-  #   security-architect: opus
+  #   security-auditor: opus
   #   researcher: sonnet
 
 # Status line display
@@ -101,9 +101,17 @@ status_line:
 sandbox:
   enabled: false                  # Set to true to wrap bash steps in an OS sandbox
   tier: auto                      # auto | denylist-only | full
+
+# Auto-update on session start (refreshes consumer assets when moflo upgrades)
+auto_update:
+  enabled: true                          # Master toggle for version-change auto-sync
+  scripts: true                          # Sync .claude/scripts/ from moflo bin/
+  helpers: true                          # Sync .claude/helpers/ from moflo source
+  hook_block_drift: warn                 # warn | regenerate | off
+  claudemd_injection_drift: regenerate   # warn | regenerate | off
 ```
 
-If your `moflo.yaml` predates the `sandbox:` block, it is auto-appended on the next session start — you never need to re-run `moflo init` after a version bump.
+If your `moflo.yaml` predates the `sandbox:` or `auto_update:` blocks, they are auto-appended on the next session start — you never need to re-run `moflo init` after a version bump.
 
 ### Key Behaviors
 
@@ -128,6 +136,12 @@ If your `moflo.yaml` predates the `sandbox:` block, it is auto-appended on the n
 | `sandbox.enabled: true` | Wrap bash steps in an OS sandbox (macOS/Linux/WSL) — absolute disable when `false`, regardless of tier |
 | `sandbox.tier: full` | Require OS sandbox; throw at runtime if the platform tool is unavailable |
 | `sandbox.tier: denylist-only` | Keep Layer 1 denylist only; skip OS isolation even when enabled |
+| `auto_update.enabled: false` | Disable all on-session auto-sync (scripts, helpers, drift checks) |
+| `auto_update.hook_block_drift: regenerate` | Auto-repair drift in `.claude/settings.json` hook block on session start (#881) |
+| `auto_update.hook_block_drift: off` | Skip hook-block drift detection entirely |
+| `auto_update.claudemd_injection_drift: regenerate` | Auto-refresh the MoFlo block in `CLAUDE.md` when it drifts from the current generator (#1142, default) |
+| `auto_update.claudemd_injection_drift: warn` | Print a drift notice on session start but leave `CLAUDE.md` unchanged |
+| `auto_update.claudemd_injection_drift: off` | Skip CLAUDE.md injection drift detection entirely |
 
 ---
 

package/.claude/helpers/gate.cjs

@@ -82,6 +82,53 @@ var command = process.argv[2];
 
 var EXEMPT = ['.claude/', '.claude\\', 'CLAUDE.md', 'MEMORY.md', 'workflow-state', 'node_modules', 'moflo.yaml'];
 var DANGEROUS = ['rm -rf /', 'format c:', 'del /s /q c:\\', ':(){:|:&};:', 'mkfs.', '> /dev/sda'];
+
+// #1132 — Bash memory-first gate.
+//
+// CREDIT: the legacy detector that marks the gate satisfied when Claude
+// manually invokes a memory-search CLI (flo-search, the moflo MCP search via
+// shell, etc.). Preserved verbatim from the pre-#1132 behaviour so existing
+// recipes keep crediting the gate.
+var CREDIT_MEMORY_SEARCH_RE = /semantic-search|memory search|memory retrieve|memory-search/;
+// BLOCK: read-like Bash commands that bypass the existing check-before-read /
+// check-before-scan gates by going through the shell. Anchored to the start of
+// the line so subcommands inside pipelines or `npm install grep` don't trip.
+// Covers POSIX read/search tools, Windows cmd `type`, and PowerShell readers.
+var READ_LIKE_BASH_RE = new RegExp([
+  '^\\s*(?:cat|head|tail|less|more|bat|xxd|od|hexdump)\\b',
+  '^\\s*(?:grep|rg|ag|fgrep|egrep|find|fd)\\b',
+  '^\\s*sed\\s+-n\\b',
+  '^\\s*awk\\s+(?!.*<<)',
+  // `type <path>` on Windows. No `$` anchor so a piped form
+  // (`type src\foo.ts | grep x`) still matches and gets blocked. The argument
+  // must contain a slash, backslash, or dot — otherwise it's the shell-builtin
+  // command-lookup form (`type ls`, `type cd`) which the gate has no business
+  // blocking. False-negative trade: extension-less filenames like `type Makefile`
+  // pass through. Acceptable — source files all have extensions, and the
+  // primary risk pattern is leaking past the gate via `type src\foo.ts`.
+  '^\\s*type\\s+\\S*[\\\\/.]',
+  '^\\s*(?:Get-Content|gc|Select-String|sls)\\b',
+].join('|'), 'i');
+// CARVE-OUT: commands that LOOK read-like but are operational. Anchored to the
+// LEADING command — the pipe-filter case (`npm test | grep FAIL`) is already
+// handled by READ_LIKE's `^\s*` anchor never matching the leading `npm`, so
+// there is intentionally no pipe arm here: catching the leading command lets
+// `grep -r TODO src/ | head -5` reach the BLOCK exit (which it must, that's
+// the gap the ticket exists to close). #1132.
+var BASH_CARVE_OUT_RE = new RegExp([
+  '^\\s*(npm|npx|pnpm|yarn|bun|node|deno|tsx|ts-node)\\s',
+  '^\\s*(git|gh|hub)\\s',
+  '^\\s*(docker|kubectl|helm|terraform)\\s',
+  '^\\s*(curl|wget|http|fetch)\\s',
+  '^\\s*(jq|yq|xq)\\s',
+  '^\\s*(echo|printf|true|false|sleep|test|\\[)\\s',
+  '^\\s*cat\\s+(<<|<<<)',
+  '^\\s*cat\\s+[^|]*\\s*>',
+  '^\\s*tee\\b',
+  // Lazy `.+?` instead of `.+\s` to avoid catastrophic backtracking on long
+  // `find` commands that lack a `-delete` / `-exec rm` suffix.
+  '^\\s*find\\s+.+?-(delete|exec\\s+rm)\\b',
+].join('|'));
 var DIRECTIVE_RE = /^(yes|no|yeah|yep|nope|sure|ok|okay|correct|right|exactly|perfect)\b/i;
 var TASK_RE = /\b(fix|bug|error|implement|add|create|build|write|refactor|debug|test|feature|issue|security|optimi)\b/i;
 
@@ -146,6 +193,29 @@ function classifyNamespaceHint(promptText) {
   return '';
 }
 
+// #1132 — command-shape namespace classifier for the bash-BLOCK message.
+// Used when the prompt-derived `lastNamespaceHint` is empty (e.g. subagents,
+// which never see the user prompt) so the block message still routes to a
+// useful namespace rather than the generic "pick one of five" list. Returns a
+// full sentence in the same shape as classifyNamespaceHint so the BLOCK arm
+// can write either source's hint without branching on format.
+//
+// SYNC: duplicated verbatim in src/cli/init/helpers-generator.ts.
+function classifyBashNamespaceHint(cmd) {
+  // Search-like tools — the user is hunting for a symbol/file, code-map wins.
+  if (/^\s*(?:grep|rg|ag|fgrep|egrep|find|fd|Select-String|sls)\b/i.test(cmd)) {
+    return 'Memory namespace hint: use "code-map" for codebase navigation.';
+  }
+  // Reading a .md / RST / TXT, or a well-known doc file — guidance/learnings win.
+  // `.*` (not `\S*`) so flag-prefixed forms like `head -50 README.md` match.
+  // Anchored on the leading reader so a piped `cmd | grep foo.md` doesn't trip.
+  if (/^\s*(?:cat|head|tail|less|more|bat|type|Get-Content|gc)\b.*\.(?:md|mdx|rst|txt)\b/i.test(cmd)
+   || /^\s*(?:cat|head|tail|less|more|bat|type|Get-Content|gc)\b.*\b(?:README|CLAUDE|CHANGELOG|CONTRIBUTING|LICENSE)\b/i.test(cmd)) {
+    return 'Memory namespace hint: search "guidance" and "learnings" for project rules and decisions.';
+  }
+  return '';
+}
+
 // Apply per-prompt state reset shared by `prompt-reminder` (full) and
 // `prompt-state-reset` (defensive safety-net, no emission). Idempotent — both
 // UserPromptSubmit hooks can run it without compounding any field. Caller
@@ -402,11 +472,41 @@ switch (command) {
     break;
   }
   case 'check-bash-memory': {
+    // #1132 — preserve CREDIT side-effect AND add a BLOCK arm for read-like
+    // Bash commands. Wired as PreToolUse[Bash] (was PostToolUse before #1132)
+    // so process.exit(2) actually prevents the read from reaching the shell.
     var cmd = process.env.TOOL_INPUT_command || '';
-    if (/semantic-search|memory search|memory retrieve|memory-search/.test(cmd)) {
+
+    // 1) CREDIT — preserved behavior. A real memory-search invocation flips
+    // the gate flag so subsequent Read/Grep/Glob within this prompt pass.
+    if (CREDIT_MEMORY_SEARCH_RE.test(cmd)) {
       var s = readState();
       if (markMemorySearched(s)) writeState(s);
+      break;
     }
+
+    // 2) BLOCK — new behavior. Cheap regex checks come BEFORE readState() so
+    // the overwhelming majority of Bash invocations (git/npm/curl/echo/etc.)
+    // never touch the filesystem. Order: config flag → command-shape regexes
+    // → state read → memory gate.
+    if (!config.memory_first) break;
+    if (!READ_LIKE_BASH_RE.test(cmd)) break;
+    if (BASH_CARVE_OUT_RE.test(cmd)) break;
+    var s2 = readState();
+    if (!s2.memoryRequired || isMemorySearchedFor(s2)) break;
+    // Hint precedence: prompt-derived classification (set by applyPromptStateReset
+    // from the user prompt text) → command-shape classification (works for
+    // subagents that never saw the user prompt). Either source returns a full
+    // "Memory namespace hint: ..." sentence so the BLOCK message stays uniform.
+    var hint = s2.lastNamespaceHint || classifyBashNamespaceHint(cmd) || '';
+    process.stderr.write(
+      'BLOCKED: Search memory before reading files via Bash.\n' +
+      'Example: mcp__moflo__memory_search { query: "<topic>", namespace: "<one of: guidance | code-map | patterns | learnings | tests>" }\n' +
+      (hint ? hint + '\n' : '') +
+      'On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n' +
+      'Disable per-gate via moflo.yaml: gates: memory_first: false\n'
+    );
+    process.exit(2);
     break;
   }
   case 'check-task-transition': {

package/.claude/helpers/subagent-bootstrap.json

@@ -1,3 +1,3 @@
 {
-  "directive": "MANDATORY FIRST ACTION: Your very first tool call MUST be mcp__moflo__memory_search (any query, any namespace). The memory-first gate WILL BLOCK all Glob, Grep, and Read calls until you do this. After memory search, follow `.claude/guidance/moflo-subagents.md` protocol. When a search hit carries `navigation`, you MUST call mcp__moflo__memory_get_neighbors to traverse — calling mcp__moflo__memory_retrieve on every hit is a protocol violation. See `.claude/guidance/moflo-memory-protocol.md`."
+  "directive": "MANDATORY FIRST ACTION: Your very first tool call MUST be mcp__moflo__memory_search (any query, any namespace). The memory-first gate WILL BLOCK all Glob, Grep, Read, and read-like Bash (cat/head/tail/grep/find/sed/awk and the Windows/PowerShell equivalents) calls until you do this. Pick the namespace by task: `guidance` for rules and conventions, `code-map` for file structure, `patterns` for proven solutions, `learnings` for past corrections, `tests` for test inventory. After memory search, follow `.claude/guidance/moflo-subagents.md` protocol. When a search hit carries `navigation`, you MUST call mcp__moflo__memory_get_neighbors to traverse — calling mcp__moflo__memory_retrieve on every hit is a protocol violation. See `.claude/guidance/moflo-memory-protocol.md`."
 }