moflo 4.9.21 → 4.9.22

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

@@ -0,0 +1,43 @@
+---
+name: database-dev
+description: Database specialist for schema design, migrations, query optimization, and data integrity. Use for designing tables and indexes, writing migrations, optimizing slow queries, configuring ORMs, and reviewing data-access patterns.
+color: green
+---
+
+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
+
+1. **Schema design** — normalized tables, well-chosen primary keys, appropriate foreign keys with `ON DELETE` semantics. Denormalize only when there's a measured read pattern that justifies it.
+2. **Migrations** — additive-first (add column, backfill, then enforce). Never drop or rename in a single step on a live table. Always reversible unless explicitly one-way.
+3. **Indexes** — cover the actual query patterns, not speculative ones. Composite indexes match the leading columns of the WHERE/ORDER BY clauses. Audit `EXPLAIN ANALYZE` output for sequential scans on hot queries.
+4. **Queries** — parameterized always (never string-concatenated). Watch for N+1 patterns. Prefer single round-trips with joins or `IN` over loops.
+5. **Transactions** — wrap multi-statement writes in a transaction. Choose isolation levels deliberately.
+6. **ORM patterns** — match the project's existing ORM conventions (Prisma, Drizzle, TypeORM, SQLAlchemy, Active Record, etc.). Don't bypass it for raw SQL unless the ORM truly can't express the query.
+
+## Approach
+
+Before writing migrations or queries:
+- Read the existing schema (or schema files) for the affected tables.
+- Check the existing query patterns in the data-access layer — match conventions.
+- For migrations, check if the project uses a migration runner (Knex, Prisma Migrate, Alembic, Flyway) and follow its file-naming convention.
+
+For performance work:
+- Get an `EXPLAIN ANALYZE` (or equivalent) of the slow query before suggesting an index.
+- Consider whether the slowness is the query plan, table size, lock contention, or N+1 from above.
+- Don't add indexes blindly — every index slows writes.
+
+## Output expectations
+
+- A schema or migration that runs cleanly forward AND back (when reversible).
+- For optimization work: the EXPLAIN diff (before/after), not just "this should be faster".
+- A note on any data-loss risk in the migration (e.g. "this drops column X — back up first").
+
+## Anti-patterns to avoid
+
+- String-interpolated SQL (SQL injection risk).
+- Migrations that drop or rename columns on the same step they're used (breaks rolling deploys).
+- "Just add an index" without measuring.
+- Bypassing the project's ORM for queries the ORM handles fine.
+- Cross-database joins where an in-app join would be safer.
+- Writing a migration that requires downtime without flagging it.

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

@@ -0,0 +1,42 @@
+---
+name: frontend-dev
+description: Frontend development specialist for UI components, styling, accessibility, and client-side state. Use for React/Vue/Svelte component work, CSS/Tailwind layout, responsive design, accessibility audits, and browser-side data flow.
+color: cyan
+---
+
+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
+
+1. **Components** — write composable, focused components in the project's framework (React, Vue, Svelte, etc.). Match the existing component conventions (naming, file layout, prop shapes) before introducing new patterns.
+2. **Styling** — use the project's existing styling approach (CSS modules, Tailwind, styled-components, vanilla CSS). Don't add a new styling system.
+3. **State** — keep state local where possible. Hoist only when sharing is required. Match the project's existing state library (Redux, Zustand, Pinia, Context, etc.) before introducing a new one.
+4. **Accessibility** — semantic HTML first; ARIA only where semantics aren't enough. Verify keyboard navigation, focus management, and screen-reader labels. Run an axe-style audit when touching public-facing UI.
+5. **Responsive layout** — mobile-first. Test at the project's declared breakpoints, not assumed ones.
+6. **Browser performance** — avoid layout thrashing, watch bundle size, lazy-load heavy components, prefer CSS animations over JS where possible.
+
+## Approach
+
+Before writing code:
+- Read 2-3 existing components in the affected area to mirror conventions.
+- Confirm which framework version, styling system, and state library are in use — don't assume.
+- For new patterns (a new modal style, a new form component), check whether one already exists.
+
+While implementing:
+- Keep components small. Extract when a component handles more than one responsibility.
+- Prefer composition over prop drilling.
+- Type props strictly when the project uses TypeScript.
+
+## Output expectations
+
+- Working code that drops into the existing app without new dependencies (unless the user approved one).
+- A short note on accessibility decisions made (e.g. "added aria-label to icon-only button").
+- A note on any test that should be added (component test, visual regression, e2e).
+
+## Anti-patterns to avoid
+
+- Inline styles when the project has a styling system.
+- New state libraries when an existing one fits.
+- Hand-rolled accessibility primitives when the project uses a headless UI library (Radix, Headless UI, etc.).
+- "Mobile-first" lip service that breaks below 768px in practice.
+- Adding `any` to bypass type errors in a TypeScript project.

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

@@ -1,120 +1,8 @@
 ---
 name: "cicd-engineer"
 description: "Specialized agent for GitHub Actions CI/CD pipeline creation and optimization"
-type: "devops"
 color: "cyan"
-version: "1.0.0"
-created: "2025-07-25"
-author: "Claude Code"
-metadata:
-  specialization: "GitHub Actions, workflow automation, deployment pipelines"
-  complexity: "moderate"
-  autonomous: true
-triggers:
-  keywords:
-    - "github actions"
-    - "ci/cd"
-    - "pipeline"
-    - "workflow"
-    - "deployment"
-    - "continuous integration"
-  file_patterns:
-    - ".github/workflows/*.yml"
-    - ".github/workflows/*.yaml"
-    - "**/action.yml"
-    - "**/action.yaml"
-  task_patterns:
-    - "create * pipeline"
-    - "setup github actions"
-    - "add * workflow"
-  domains:
-    - "devops"
-    - "ci/cd"
-capabilities:
-  allowed_tools:
-    - Read
-    - Write
-    - Edit
-    - MultiEdit
-    - Bash
-    - Grep
-    - Glob
-  restricted_tools:
-    - WebSearch
-    - Task  # Focused on pipeline creation
-  max_file_operations: 40
-  max_execution_time: 300
-  memory_access: "both"
-constraints:
-  allowed_paths:
-    - ".github/**"
-    - "scripts/**"
-    - "*.yml"
-    - "*.yaml"
-    - "Dockerfile"
-    - "docker-compose*.yml"
-  forbidden_paths:
-    - ".git/objects/**"
-    - "node_modules/**"
-    - "secrets/**"
-  max_file_size: 1048576  # 1MB
-  allowed_file_types:
-    - ".yml"
-    - ".yaml"
-    - ".sh"
-    - ".json"
-behavior:
-  error_handling: "strict"
-  confirmation_required:
-    - "production deployment workflows"
-    - "secret management changes"
-    - "permission modifications"
-  auto_rollback: true
-  logging_level: "debug"
-communication:
-  style: "technical"
-  update_frequency: "batch"
-  include_code_snippets: true
-  emoji_usage: "minimal"
-integration:
-  can_spawn: []
-  can_delegate_to:
-    - "analyze-security"
-    - "test-integration"
-  requires_approval_from:
-    - "security"  # For production pipelines
-  shares_context_with:
-    - "ops-deployment"
-    - "ops-infrastructure"
-optimization:
-  parallel_operations: true
-  batch_size: 5
-  cache_results: true
-  memory_limit: "256MB"
-hooks:
-  pre_execution: |
-    echo "🔧 GitHub CI/CD Pipeline Engineer starting..."
-    echo "📂 Checking existing workflows..."
-    find .github/workflows -name "*.yml" -o -name "*.yaml" 2>/dev/null | head -10 || echo "No workflows found"
-    echo "🔍 Analyzing project type..."
-    test -f package.json && echo "Node.js project detected"
-    test -f requirements.txt && echo "Python project detected"
-    test -f go.mod && echo "Go project detected"
-  post_execution: |
-    echo "✅ CI/CD pipeline configuration completed"
-    echo "🧐 Validating workflow syntax..."
-    # Simple YAML validation
-    find .github/workflows -name "*.yml" -o -name "*.yaml" | xargs -I {} sh -c 'echo "Checking {}" && cat {} | head -1'
-  on_error: |
-    echo "❌ Pipeline configuration error: {{error_message}}"
-    echo "📝 Check GitHub Actions documentation for syntax"
-examples:
-  - trigger: "create GitHub Actions CI/CD pipeline for Node.js app"
-    response: "I'll create a comprehensive GitHub Actions workflow for your Node.js application including build, test, and deployment stages..."
-  - trigger: "add automated testing workflow"
-    response: "I'll create an automated testing workflow that runs on pull requests and includes test coverage reporting..."
 ---
-
 # 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

@@ -2,118 +2,7 @@
 name: "api-docs"
 description: "Expert agent for creating and maintaining OpenAPI/Swagger documentation"
 color: "indigo"
-type: "documentation"
-version: "1.0.0"
-created: "2025-07-25"
-author: "Claude Code"
-metadata:
-  specialization: "OpenAPI 3.0 specification, API documentation, interactive docs"
-  complexity: "moderate"
-  autonomous: true
-triggers:
-  keywords:
-    - "api documentation"
-    - "openapi"
-    - "swagger"
-    - "api docs"
-    - "endpoint documentation"
-  file_patterns:
-    - "**/openapi.yaml"
-    - "**/swagger.yaml"
-    - "**/api-docs/**"
-    - "**/api.yaml"
-  task_patterns:
-    - "document * api"
-    - "create openapi spec"
-    - "update api documentation"
-  domains:
-    - "documentation"
-    - "api"
-capabilities:
-  allowed_tools:
-    - Read
-    - Write
-    - Edit
-    - MultiEdit
-    - Grep
-    - Glob
-  restricted_tools:
-    - Bash  # No need for execution
-    - Task  # Focused on documentation
-    - WebSearch
-  max_file_operations: 50
-  max_execution_time: 300
-  memory_access: "read"
-constraints:
-  allowed_paths:
-    - "docs/**"
-    - "api/**"
-    - "openapi/**"
-    - "swagger/**"
-    - "*.yaml"
-    - "*.yml"
-    - "*.json"
-  forbidden_paths:
-    - "node_modules/**"
-    - ".git/**"
-    - "secrets/**"
-  max_file_size: 2097152  # 2MB
-  allowed_file_types:
-    - ".yaml"
-    - ".yml"
-    - ".json"
-    - ".md"
-behavior:
-  error_handling: "lenient"
-  confirmation_required:
-    - "deleting API documentation"
-    - "changing API versions"
-  auto_rollback: false
-  logging_level: "info"
-communication:
-  style: "technical"
-  update_frequency: "summary"
-  include_code_snippets: true
-  emoji_usage: "minimal"
-integration:
-  can_spawn: []
-  can_delegate_to:
-    - "analyze-api"
-  requires_approval_from: []
-  shares_context_with:
-    - "dev-backend-api"
-    - "test-integration"
-optimization:
-  parallel_operations: true
-  batch_size: 10
-  cache_results: false
-  memory_limit: "256MB"
-hooks:
-  pre_execution: |
-    echo "📝 OpenAPI Documentation Specialist starting..."
-    echo "🔍 Analyzing API endpoints..."
-    # Look for existing API routes
-    find . -name "*.route.js" -o -name "*.controller.js" -o -name "routes.js" | grep -v node_modules | head -10
-    # Check for existing OpenAPI docs
-    find . -name "openapi.yaml" -o -name "swagger.yaml" -o -name "api.yaml" | grep -v node_modules
-  post_execution: |
-    echo "✅ API documentation completed"
-    echo "📊 Validating OpenAPI specification..."
-    # Check if the spec exists and show basic info
-    if [ -f "openapi.yaml" ]; then
-      echo "OpenAPI spec found at openapi.yaml"
-      grep -E "^(openapi:|info:|paths:)" openapi.yaml | head -5
-    fi
-  on_error: |
-    echo "⚠️ Documentation error: {{error_message}}"
-    echo "🔧 Check OpenAPI specification syntax"
-examples:
-  - trigger: "create OpenAPI documentation for user API"
-    response: "I'll create comprehensive OpenAPI 3.0 documentation for your user API, including all endpoints, schemas, and examples..."
-  - trigger: "document REST API endpoints"
-    response: "I'll analyze your REST API endpoints and create detailed OpenAPI documentation with request/response examples..."
 ---
-
 # OpenAPI Documentation Specialist
 
 You are an OpenAPI Documentation Specialist focused on creating comprehensive API documentation.

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

@@ -0,0 +1,45 @@
+---
+name: security-auditor
+description: Security audit specialist for vulnerability scanning, threat modeling, dependency audits, and secure-coding review. Use for CVE remediation, auth/authz review, input-validation audits, secret-handling review, and pre-release security passes.
+color: red
+---
+
+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
+
+1. **Vulnerability scanning** — review code for OWASP Top 10 patterns: injection (SQL, command, prompt), XSS, insecure deserialization, broken access control, security misconfiguration, sensitive-data exposure, broken auth, SSRF.
+2. **Auth/authz review** — verify authentication is enforced where it should be, authorization checks aren't missed on protected endpoints, session handling is sound, tokens are stored safely.
+3. **Input validation** — verify untrusted input is validated and sanitized at every system boundary (API endpoints, message queues, file uploads, env vars).
+4. **Secret handling** — flag hardcoded secrets, check `.env` patterns, audit how secrets reach code (env vars, secret managers, never plaintext in repos).
+5. **Dependency audit** — check `npm audit` / `pip-audit` / equivalent; flag direct + transitive dependencies with known CVEs; suggest remediation paths.
+6. **Threat modeling** — for new features, identify trust boundaries, abuse cases, and attack surface before implementation.
+
+## Approach
+
+For an audit:
+- Start with the highest-impact entry points (public APIs, file upload, auth flow, payment).
+- Check input validation, then authz, then output sanitization.
+- Run dependency audit tools. Don't trust "no high-severity CVEs" — read the report.
+- Look at how secrets actually flow — not just whether they're in `.env`.
+
+For a specific concern:
+- Reproduce the vulnerability if it's claimed (PoC clarifies).
+- Trace the data flow from untrusted source to sensitive sink.
+- Suggest the minimum fix that closes the gap, not a sweeping refactor.
+
+## Output expectations
+
+- Findings ranked by severity (Critical → High → Medium → Low).
+- Each finding: file:line, what's wrong, what an attacker could do, suggested fix.
+- For dependency CVEs: name the CVE ID, the affected version range, the safe upgrade path.
+- Don't pad with low-severity nits when there are unaddressed criticals.
+
+## Anti-patterns to avoid
+
+- Whitebox-only audits when blackbox testing would catch obvious issues.
+- "Add validation" without specifying *what* validation.
+- Flagging stylistic concerns as security issues.
+- Generic OWASP recitation instead of project-specific findings.
+- Recommending custom crypto over well-tested libraries.
+- Missing the implicit trust boundary (e.g. internal microservice that accepts unvalidated input from another internal service).

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

@@ -74,23 +74,23 @@ TaskCreate({
 
 ## 5. Keep Files Under 500 Lines
 
-**The 500-line cap applies to every `.claude/guidance/**/*.md` file AND every `.claude/skills/*/SKILL.md` entry file.** The same RAG/attention math applies to both:
+**The 500-line cap applies to every `.claude/guidance/**/*.md` file AND every `.claude/skills/*/SKILL.md` entry file AND every `.claude/agents/**/*.md` entry file.** The same RAG/attention math applies to all three:
 
 - RAG chunking splits long files, and chunks lose cross-section context
 - Claude deprioritizes content deep in a long document
 - Competing chunks from the same file dilute search relevance
-- For SKILL.md, the **entire file is loaded into context on every invocation** — every extra line is a per-invocation token cost across all consumers
+- For SKILL.md and agent .md, the **entire file is loaded into context on every invocation** (or on every `Agent({subagent_type})` spawn) — every extra line is a per-invocation token cost across all consumers
 
 If a doc exceeds 500 lines, split by concern. Two patterns:
 
 | Pattern | Where it fits | Example |
 |---------|---------------|---------|
 | **Sibling files** (guidance) | Topical split — each file owns one concern | `moflo-spell-engine.md` + `moflo-spell-runner.md` + `moflo-spell-troubleshooting.md` |
-| **Progressive disclosure** (skills) | Entry SKILL.md links to companions in the same skill directory | `spell-builder/SKILL.md` (entry) + `architecture.md` + `permissions.md` + `preflight.md` (companions) |
+| **Progressive disclosure** (skills, agents) | Entry SKILL.md or agent .md links to companions in the same directory | `spell-builder/SKILL.md` (entry) + `architecture.md` + `permissions.md` + `preflight.md` (companions); `agents/<cat>/<name>.md` (entry, has frontmatter) + `<name>-protocols.md` (companion, no frontmatter) |
 
-Companion files are NOT auto-loaded — Claude reads them only when the SKILL.md entry directs it to. This keeps the per-invocation cost low while preserving the depth.
+Companion files are NOT auto-loaded — Claude reads them only when the entry directs it to. This keeps the per-invocation cost low while preserving the depth.
 
-A gating test (`skill-and-guidance-size-drift.test.ts`) enforces the cap and will fail CI if a guidance doc or SKILL.md entry exceeds 500 lines. Companion files inside a skill directory are exempt because they only load on demand.
+A gating test (`skill-and-guidance-size-drift.test.ts`) enforces the cap and will fail CI if a guidance doc, SKILL.md entry, or agent entry exceeds 500 lines. Companion files (agent .md without YAML frontmatter, or any .md inside a skill directory other than SKILL.md) are exempt because they only load on demand.
 
 ---
 

package/.claude/helpers/gate.cjs

@@ -7,7 +7,7 @@ var cp = require('child_process');
 var PROJECT_DIR = (process.env.CLAUDE_PROJECT_DIR || process.cwd()).replace(/^\/([a-z])\//i, '$1:/');
 var STATE_FILE = path.join(PROJECT_DIR, '.claude', 'workflow-state.json');
 
-var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, simplifySnapshotSha: null, interactionCount: 0, sessionStart: null, lastBlockedAt: null, lastNamespaceHint: '', lastNamespaceHintEmittedBy: {} };
+var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, simplifySnapshotSha: null, interactionCount: 0, sessionStart: null, lastBlockedAt: null, lastNamespaceHint: '', lastNamespaceHintEmittedBy: {}, flMode: null, swarmInitialized: false, hiveInitialized: false };
 
 // Per-actor memory-search tracking (#838). The legacy `memorySearched` boolean
 // is session-wide, so once the parent searches memory, every spawned subagent
@@ -60,7 +60,7 @@ function writeState(s) {
 
 // Load moflo.yaml gate config (defaults: all enabled)
 function loadGateConfig() {
-  var defaults = { memory_first: true, task_create_first: true, context_tracking: true, testing_gate: true, simplify_gate: true, learnings_gate: true };
+  var defaults = { memory_first: true, task_create_first: true, context_tracking: true, testing_gate: true, simplify_gate: true, learnings_gate: true, swarm_invocation_gate: true };
   try {
     var yamlPath = path.join(PROJECT_DIR, 'moflo.yaml');
     if (fs.existsSync(yamlPath)) {
@@ -71,6 +71,7 @@ function loadGateConfig() {
       if (/testing_gate:\s*false/i.test(content)) defaults.testing_gate = false;
       if (/simplify_gate:\s*false/i.test(content)) defaults.simplify_gate = false;
       if (/learnings_gate:\s*false/i.test(content)) defaults.learnings_gate = false;
+      if (/swarm_invocation_gate:\s*false/i.test(content)) defaults.swarm_invocation_gate = false;
     }
   } catch (e) { /* use defaults */ }
   return defaults;
@@ -111,6 +112,21 @@ var NS_NAV_RES = [
   /\b(class|function|method|component|service|entity|module)\b/,
 ];
 
+// Detect whether the current prompt invoked /fl or /flo with a swarm/hive flag (#952).
+// When set, check-before-agent BLOCKS the Agent spawn until the matching MCP init
+// (mcp__moflo__swarm_init or mcp__moflo__hive-mind_init) has been recorded — the user
+// explicitly opted in to the protected coordination surface, so falling back to
+// raw Agent dispatch silently regresses headline moflo product capability.
+//
+// SYNC: duplicated verbatim in src/cli/init/helpers-generator.ts.
+function detectFlMode(promptText) {
+  var p = promptText || '';
+  if (!/^\s*\/(?:fl|flo)\b/i.test(p)) return null;
+  if (/(?:^|\s)(?:-s|--swarm)\b/.test(p)) return 'swarm';
+  if (/(?:^|\s)(?:-h|--hive)\b/.test(p)) return 'hive';
+  return null;
+}
+
 function classifyNamespaceHint(promptText) {
   var lower = (promptText || '').toLowerCase();
   if (NS_TEST_RE.test(lower)) return 'Memory namespace hint: use "tests" for test inventory and coverage lookups.';
@@ -154,6 +170,12 @@ function applyPromptStateReset(state, promptText) {
   // subsequent agents (parent + subagents that spawn their own agents) all
   // see the new classification on their first check-before-agent.
   state.lastNamespaceHintEmittedBy = {};
+  // #952 — derive flMode from the user prompt, and reset the matching init
+  // flag. Each /fl invocation must call its protected MCP init; the previous
+  // prompt's swarm/hive registration does not satisfy this prompt's gate.
+  state.flMode = detectFlMode(promptText);
+  state.swarmInitialized = false;
+  state.hiveInitialized = false;
 }
 // Match npm/yarn/pnpm/bun test, npx vitest|jest|..., bare runners at command-start only,
 // and language-native test commands. The bare-runner arm is anchored so that
@@ -305,6 +327,47 @@ switch (command) {
         writeState(s);
       }
     }
+    // #952 — when /fl was invoked with -s/-h, the protected MCP init must run
+    // BEFORE any Agent spawn. Hard block: the user explicitly opted in to
+    // moflo's coordination surface, so silently dispatching `Agent` calls
+    // without `mcp__moflo__swarm_init` / `mcp__moflo__hive-mind_init` is the
+    // failure mode this gate exists to prevent (CLAUDE.md "⛔ Protected
+    // functionality — swarm + hive-mind"). Other Agent uses remain advisory.
+    if (config.swarm_invocation_gate) {
+      if (s.flMode === 'swarm' && !s.swarmInitialized) {
+        process.stderr.write('BLOCKED: /fl was invoked with -s/--swarm but mcp__moflo__swarm_init has not been called.\n');
+        process.stderr.write('Run mcp__moflo__swarm_init first, then mcp__moflo__agent_spawn for each role, then dispatch Agent.\n');
+        process.stderr.write('See .claude/skills/fl/execution-modes.md "SWARM mode" and CLAUDE.md "⛔ Protected functionality".\n');
+        process.stderr.write('Disable via moflo.yaml: gates: swarm_invocation_gate: false\n');
+        process.exit(2);
+      }
+      if (s.flMode === 'hive' && !s.hiveInitialized) {
+        process.stderr.write('BLOCKED: /fl was invoked with -h/--hive but mcp__moflo__hive-mind_init has not been called.\n');
+        process.stderr.write('Run mcp__moflo__hive-mind_init first, then dispatch Agent or hive-mind workers.\n');
+        process.stderr.write('See .claude/skills/fl/execution-modes.md "HIVE-MIND mode" and CLAUDE.md "⛔ Protected functionality".\n');
+        process.stderr.write('Disable via moflo.yaml: gates: swarm_invocation_gate: false\n');
+        process.exit(2);
+      }
+    }
+    break;
+  }
+  case 'record-swarm-init': {
+    // #952 — wired to mcp__moflo__swarm_init PostToolUse. Marks the gate
+    // satisfied so subsequent Agent spawns under /fl -s pass.
+    var s = readState();
+    if (!s.swarmInitialized) {
+      s.swarmInitialized = true;
+      writeState(s);
+    }
+    break;
+  }
+  case 'record-hive-init': {
+    // #952 — wired to mcp__moflo__hive-mind_init PostToolUse.
+    var s = readState();
+    if (!s.hiveInitialized) {
+      s.hiveInitialized = true;
+      writeState(s);
+    }
     break;
   }
   case 'check-before-scan': {
@@ -508,7 +571,11 @@ switch (command) {
     break;
   }
   case 'session-reset': {
-    writeState({ tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, interactionCount: 0, sessionStart: new Date().toISOString(), lastBlockedAt: null, lastNamespaceHint: '', lastNamespaceHintEmittedBy: {} });
+    // Derive from STATE_DEFAULTS so adding a new state field requires only one
+    // edit (the defaults object) — the literal that used to live here drifted
+    // every time a field was added and is what motivated #952's audit of state
+    // shape consistency.
+    writeState(Object.assign({}, STATE_DEFAULTS, { sessionStart: new Date().toISOString() }));
     break;
   }
   default:

package/.claude/skills/fl/execution-modes.md

@@ -4,7 +4,9 @@ The execution mode chooses how work is carried out across the phases. Pass `-s/-
 
 ## SWARM mode (`-s`, `--swarm`)
 
-Swarm mode spawns agents via the Task tool.
+> **MANDATORY when `-s` is passed.** Your first Execute-phase action MUST be `mcp__moflo__swarm_init`, followed by `mcp__moflo__agent_spawn` for each role. Spawning subagents via `Agent` (or `Task`) without first registering the swarm is a violation of issue #952. The `Agent` PreToolUse gate will BLOCK the call until `swarm_init` runs. Even when you also use `Agent` for parallelism, the moflo swarm IS the registration surface — call it first. See CLAUDE.md "⛔ Protected functionality — swarm + hive-mind".
+
+Swarm mode coordinates agents through the moflo swarm coordinator, then spawns workers via the `Agent` tool.
 
 Roles:
 - `researcher` — analyzes the issue, searches memory, finds patterns
@@ -13,36 +15,57 @@ Roles:
 - `/flo-simplify` — moflo's adaptive code review skill (sized to diff, parallel agents on big changes)
 - `reviewer` — reviews code before PR
 
-Pattern:
+Required pattern:
 ```javascript
 // 1. Create the task list first
-TaskCreate({ subject: "Research issue", ... })
-TaskCreate({ subject: "Implement changes", ... })
-TaskCreate({ subject: "Test implementation", ... })
-TaskCreate({ subject: "Run /flo-simplify on changed files", ... })
-TaskCreate({ subject: "Review and PR", ... })
+TaskCreate({ subject: "📋 [Researcher] Research issue", ... })
+TaskCreate({ subject: "💻 [Coder] Implement changes", ... })
+TaskCreate({ subject: "🧪 [Tester] Test implementation", ... })
+TaskCreate({ subject: "🔍 [Reviewer] Run /flo-simplify on changed files", ... })
+
+// 2. Init the swarm — MANDATORY, gate-enforced
+mcp__moflo__swarm_init({ topology: "hierarchical", maxAgents: 8, strategy: "specialized" })
 
-// 2. Init the swarm
-Bash("flo swarm init --topology hierarchical --max-agents 8 --strategy specialized")
+// 3. Register each agent with the coordinator — MANDATORY
+mcp__moflo__agent_spawn({ type: "researcher", ... })
+mcp__moflo__agent_spawn({ type: "coder", ... })
+mcp__moflo__agent_spawn({ type: "tester", ... })
+mcp__moflo__agent_spawn({ type: "reviewer", ... })
 
-// 3. Spawn agents (run_in_background: true)
-Task({ prompt: "...", subagent_type: "researcher", run_in_background: true })
-Task({ prompt: "...", subagent_type: "coder", run_in_background: true })
+// 4. Now safe to dispatch via Agent tool for parallel execution
+Agent({ prompt: "...", subagent_type: "researcher", run_in_background: true })
+Agent({ prompt: "...", subagent_type: "coder", run_in_background: true })
 
-// 4. Wait for results, synthesize, continue
+// 5. Wait for results, synthesize, continue
 ```
 
 ## HIVE-MIND mode (`-h`, `--hive`)
 
+> **MANDATORY when `-h` is passed.** Your first Execute-phase action MUST be `mcp__moflo__hive-mind_init`. The `Agent` PreToolUse gate will BLOCK any subagent spawn until hive-mind init has run. See CLAUDE.md "⛔ Protected functionality — swarm + hive-mind".
+
 Use for consensus-based decisions:
 - Architecture choices
 - Approach tradeoffs
 - Design decisions with multiple valid options
 
+Required pattern:
+```javascript
+// 1. Init the hive — MANDATORY, gate-enforced
+mcp__moflo__hive-mind_init({ ... })
+
+// 2. Spawn workers + reach consensus via mcp__moflo__hive-mind_consensus
+mcp__moflo__hive-mind_spawn({ ... })
+mcp__moflo__hive-mind_consensus({ ... })
+```
+
 ## NORMAL mode (default)
 
 Single Claude execution without spawning sub-agents.
-- Still uses the Task tool for tracking
+- Still uses TaskCreate for tracking
 - Still creates tasks for visibility
 - Post-task neural learning hooks still fire
-- No agent spawning
+- No agent spawning, no swarm/hive init required
+
+## Why these are MANDATORY
+
+Swarm and hive-mind are headline moflo product surface (CLAUDE.md "⛔ Protected functionality"). When the user explicitly opts in via `-s`/`-h`, the protected MCP surface MUST be exercised — falling back to "Claude-native parallelism" via `Agent` tool calls without coordinator registration is the failure mode that prompted issue #952. The PreToolUse gate enforces this; opt-out is `gates.swarm_invocation_gate: false` in `moflo.yaml`.