metaswarm — Hooks and Automation

hooks.json

Two Claude Code lifecycle hooks defined:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh",
            "async": false
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh",
            "async": false
          }
        ]
      }
    ]
  }
}

SessionStart fires on startup|resume|clear|compact triggers. PreCompact fires before every context compaction with empty matcher (always). Both call the same session-start.sh script.

session-start.sh

Platform-aware context priming script:

• Detects which tool is active (Claude Code, Codex, Gemini)
• Runs bd prime if BEADS is installed (primes relevant knowledge base entries into context)
• Loads BEADS status (active issues, blocked tasks)
• Outputs session context summary for the agent

Critical use: The PreCompact hook ensures knowledge is re-primed before the context window is compacted. This prevents the agent from losing project knowledge when context fills up.

BEADS-Driven Automation

While not hook-based, BEADS provides automation for task state:

bd prime --files "src/**" --keywords "auth" --work-type implementation
  # Selective knowledge priming — loads only matching JSONL entries

bd ready     # Show tasks ready to work
bd list      # All tasks
bd stats     # Project statistics
bd doctor    # System health check

Coverage Enforcement Automation

.coverage-thresholds.json enforces blocking gates:

{
  "enforcement": {
    "command": "pnpm test:coverage",
    "blockPRCreation": true,
    "blockTaskCompletion": true
  }
}

Agents MUST run coverage check and verify 100% before proceeding. This is instruction-enforced (in skill definitions), not tool-hook-enforced.

PR Shepherd Automation

/pr-shepherd skill provides autonomous PR lifecycle management:

• Monitors CI status (polling gh pr checks)
• Handles review comments automatically
• Resolves conversation threads
• Attempts re-runs on flaky test failures
• Escalates to human after N failures

Self-Reflect Automation

/self-reflect (triggered after PR merge) runs the self-learning pipeline:

1. Reads PR review comments (human + automated)
2. Reads build/test failure logs
3. Extracts patterns, gotchas, anti-patterns
4. Writes structured JSONL entries to knowledge/
5. Optionally generates proposals for new skills or updated rubrics

No PostToolUse Hooks

metaswarm does NOT use:

• PostToolUse hooks for validation
• PreToolUse hooks for interception
• Stop hooks for completion verification

All quality gates are skill-driven (agent instructions), not hook-enforced. The single exception is the PreCompact hook for context priming.

Gemini CLI / Codex CLI Hooks

For Gemini CLI: gemini-extension.json points to GEMINI.md as context. No Gemini hook system. For Codex CLI: .codex/install.sh handles setup. No Codex hook definitions.

metaswarm — Workflow and Phases

9-Phase Workflow

Phase 1: Research

• Researcher Agent explores codebase
• Reads existing architecture, relevant files, tests
• Outputs research summary to Issue Orchestrator

Phase 2: Plan

• Architect Agent drafts implementation plan
• Decomposed into Work Units (WUs) with DoD items, file scopes, dependency graph
• Plan submitted to Plan Review Gate (3 adversarial reviewers: Feasibility, Completeness, Scope)
• All 3 must PASS before proceeding

Phase 3: Design Review Gate

For complex features (especially those from /brainstorm):

• 5 specialist agents spawn in parallel:
  1. Architect (technical architecture)
  2. Product Manager (use case, user benefit)
  3. Designer (UX/API design)
  4. Security Design (threat modeling)
  5. CTO (TDD readiness)
• All 5 must PASS. If any FAIL: iterate (max 3 iterations), then human escalation
• Approval gate: HARD STOP — no code until Design Review Gate passes

Phase 4: Work Unit Decomposition

• Issue Orchestrator creates BEADS epic
• Decomposes plan into individual Work Units
• Each WU has: DoD items list, file scope, dependencies, estimated complexity
• Dependency graph determines execution order (serial vs parallel WUs)

Phase 5: Orchestrated Execution (per WU)

The 4-phase inner loop runs for each Work Unit:

IMPLEMENT

• Coder Agent implements WU to spec (DoD items as contract)
• Optional: delegate to Codex CLI or Gemini CLI via external-tools skill

VALIDATE

• Orchestrator runs tests ITSELF (never trusts Coder self-report)
• pnpm test:coverage → checks against .coverage-thresholds.json
• Required: 100% lines, branches, functions, statements
• Failure: return to IMPLEMENT (max 3 iterations)

ADVERSARIAL REVIEW

• Fresh Task() spawned (never a persistent teammate)
• Cross-model where possible (writer's model ≠ reviewer's model)
• Reviewer checks DoD compliance with file:line evidence
• Failure: return to IMPLEMENT

COMMIT

• Orchestrator writes commit message
• Pushes to feature branch

Phase 6: Final Comprehensive Review

• Cross-unit integration review
• Code Review Agent + Security Auditor review full set of changes
• Checks for cross-WU integration issues not visible within single WU

Phase 7: PR Creation

• Release Engineer Agent creates PR
• PR description includes DoD checklist, test coverage, design doc link
• BLOCKED if coverage below threshold

Phase 8: PR Shepherd

• PR Shepherd Agent monitors CI
• Handles review comments automatically
• Resolves conversation threads
• Auto-reruns flaky tests
• Escalates after N failures

Phase 9: Closure & Learning

• /self-reflect runs after merge
• Extracts patterns, gotchas, decisions from PR review comments + test failures
• Writes JSONL entries to knowledge/
• May propose new skills or updated rubrics
• BEADS epic closed, dependencies resolved

Smart Routing

/start-task auto-routes:

• Simple task (bug fix, copy change) → direct implementation without full 9-phase workflow
• Complex feature → full 9-phase workflow
• Question → direct answer (no workflow overhead)

Approval Gates

1. Plan Review Gate (Phase 2): 3-reviewer adversarial plan review — HARD STOP
2. Design Review Gate (Phase 3): 5-parallel-reviewer design review — HARD STOP
3. Coverage Gate (Phase 5, VALIDATE): 100% coverage required — blocks PR creation
4. Human escalation (Phases 3+5): after 3 failed iterations in any gate

Resumability

BEADS task state persists to git. If a session is interrupted:

• bd list shows current state
• bd prime re-primes knowledge for context recovery
• PreCompact hook re-primes before context window is compacted
• Plan documents written to disk survive context loss

metaswarm — State and Memory

BEADS (bd CLI) — Primary State Backend

BEADS by Steve Yegge is the core state mechanism. All task state lives in BEADS (git-native, no external service):

bd ready          # Tasks ready to work
bd list           # All tasks
bd stats          # Project statistics
bd doctor         # System health check
bd start <id>     # Start working on a task
bd prime --files "src/**" --keywords "auth" --work-type implementation
                  # Selective knowledge priming

BEADS stores task data in git — survives context compaction, session interrupts, and tool restarts. Dependency graph between tasks is maintained in BEADS.

Knowledge Base

knowledge/ directory: JSONL-format fact store.

Entry Schema (from knowledge/schema.md)

{
  "type": "pattern|gotcha|decision|anti-pattern|lesson",
  "content": "The fact itself",
  "files": ["src/auth/**"],
  "keywords": ["authentication", "JWT"],
  "work_type": "implementation|review|planning",
  "date": "2026-05-16",
  "pr": "#123",
  "source": "pr-review|test-failure|user-correction|manual"
}

Selective Retrieval

bd prime --files "src/api/auth/**" --keywords "authentication" --work-type implementation
# Only loads JSONL entries matching these filters
# Knowledge base can grow to thousands of entries without context overflow
# Agents get the 5 critical gotchas for the files they're about to touch

Self-Improvement Loop

After every PR merge, /self-reflect writes new entries:

1. PR review comments → patterns, anti-patterns
2. Build/test failures → gotchas, lessons
3. Architectural decisions → decisions, rationale
4. User corrections → preferred approaches
5. Repeated user instructions → skill/command proposals

Session Priming (Hooks)

SessionStart hook (startup|resume|clear|compact):

• session-start.sh runs bd prime on startup
• Loads active issues, blocked tasks
• Injects current BEADS state summary

PreCompact hook (always, before context compaction):

• Same session-start.sh
• Critical: re-primes knowledge before the LLM's context window is compacted
• Prevents knowledge loss during long sessions

Plan and Design Documents

Plans written to disk (not just in agent context):

• PLAN.md — implementation plan (architect output)
• docs/designs/ — design documents from brainstorming
• These survive context compaction and session interrupts

Note: The Plan subagent type has read-only file access by design. Orchestrators must write plan files themselves after receiving plan text from Architect subagent.

CLAUDE.md / AGENTS.md / GEMINI.md

Three tool-specific context files in project root (populated by /setup):

• CLAUDE.md — injected automatically by Claude Code on every session
• AGENTS.md — Codex CLI project context
• GEMINI.md — Gemini CLI extension context

These contain project-specific metaswarm configuration, BEADS setup status, and active workflow state.

.coverage-thresholds.json

Persisted coverage requirement — read by orchestrators before PR creation:

{ "thresholds": { "lines": 100, "branches": 100, "functions": 100, "statements": 100 } }

No Vector Store / No Embeddings

Knowledge retrieval is file-system grep + BEADS filter — no vector search, no semantic embeddings. Selective retrieval is metadata-based (files, keywords, work_type).

Git as Audit Log

All task history lives in git:

• BEADS issues in git
• Knowledge base JSONL in git
• Plan docs in git
• All commits from execution phases on feature branch
• PR merge as closure event

No separate audit log format. Git history IS the audit trail.

metaswarm — UI & CLI Surface

metaswarm CLI (Installer)

metaswarm npm binary at cli/metaswarm.js:

npx metaswarm init

This is a cross-platform installer, not a runtime CLI. It:

• Detects installed AI tools (Claude Code, Codex CLI, Gemini CLI)
• Installs metaswarm for all detected tools
• Copies context files (CLAUDE.md, AGENTS.md, GEMINI.md) to project root
• Sets up hooks/hooks.json for Claude Code

Not used after initial setup. Subsequent updates via /update or /metaswarm-update-version commands.

Claude Code Interface

9 Claude Code slash commands:

Gemini CLI Interface

12 TOML-defined commands, invoked as /metaswarm:<command>:

/metaswarm:start-task
/metaswarm:brainstorm
/metaswarm:prime
/metaswarm:setup
/metaswarm:self-reflect
... (12 total)

Codex CLI Interface

$start, $setup and other $ prefixed commands.

BEADS (bd) CLI

BEADS is a prerequisite CLI, not part of metaswarm:

bd ready        # What's next
bd list         # All tasks
bd prime ...    # Knowledge priming
bd doctor       # Health check

No Web Dashboard

metaswarm has no local web server, no dashboard UI, no browser interface.

No Dedicated TUI

The framework relies on the host tool's (Claude Code / Gemini / Codex) terminal interface.

Visual Review

visual-review skill uses Playwright to capture screenshots:

# Invoked via skill, not a separate UI:
# npx playwright install chromium  (one-time setup)
# Agent runs screenshot capture and analyzes result

Not a dashboard — it's a skill-driven tool call.

Installation Methods

# 1. Claude Code plugin (recommended)
claude plugin marketplace add dsifry/metaswarm-marketplace
claude plugin install metaswarm

# 2. Gemini CLI extension
gemini extensions install https://github.com/dsifry/metaswarm.git

# 3. Codex CLI plugin
codex plugin marketplace add dsifry/metaswarm-marketplace
# Then via /plugins UI in Codex

# 4. Cross-platform installer
npx metaswarm init

Update Mechanism

# In Claude Code:
/update              # Update metaswarm
/metaswarm-update-version   # Update metaswarm version (framework-level)

# Or: re-run npx metaswarm init

Platform Detection

lib/ contains platform detection scripts used by session-start.sh and cli/metaswarm.js to identify which AI tool is active and route accordingly.

metaswarm — Install and Config

Prerequisites

• One of: Claude Code, Gemini CLI, or Codex CLI
• Node.js 18+
• bd (BEADS CLI) v0.40+ — recommended for task tracking and knowledge priming
• gh (GitHub CLI) — recommended for PR automation
• Playwright (optional, for visual-review skill): npx playwright install chromium

Installation

Claude Code (Recommended)

claude plugin marketplace add dsifry/metaswarm-marketplace
claude plugin install metaswarm

Then run /setup in Claude Code to configure project context files.

Gemini CLI

gemini extensions install https://github.com/dsifry/metaswarm.git

Then run /metaswarm:setup in your project.

Codex CLI

codex plugin marketplace add dsifry/metaswarm-marketplace
codex
# Open /plugins → select metaswarm marketplace → install

Then run $setup.

Cross-Platform (All Tools)

npx metaswarm init

Detects installed CLIs and installs for all of them simultaneously.

Legacy: npm direct

npm install -g metaswarm

Use /migrate command to transition from npm to plugin installation.

Project Setup (/setup)

Interactive setup that creates:

project-root/
├── CLAUDE.md       — Claude Code project context (metaswarm config appended)
├── AGENTS.md       — Codex CLI project context
├── GEMINI.md       — Gemini CLI extension context
├── .coverage-thresholds.json — Coverage enforcement config (100% all metrics)
└── knowledge/      — Empty JSONL knowledge base (grows over time)

Also configures BEADS in the project if bd CLI is installed.

Configuration Files

CLAUDE.md (project root)

Contains:

• metaswarm project instructions
• BEADS status / active issues summary
• Project-specific coding standards
• Agent coordination preferences

.coverage-thresholds.json

{
  "thresholds": { "lines": 100, "branches": 100, "functions": 100, "statements": 100 },
  "enforcement": {
    "command": "pnpm test:coverage",
    "blockPRCreation": true,
    "blockTaskCompletion": true
  }
}

Modify values per-project (100% is default, not mandatory).

hooks/hooks.json (installed by Claude Code plugin)

SessionStart + PreCompact → session-start.sh (not user-edited).

knowledge/ directory

JSONL fact store, empty at install, grows via /self-reflect over time.

Update

# In Claude Code:
/update
# or:
/metaswarm-update-version

# Cross-platform:
npx metaswarm init   # Re-runs installer, updates in place

Migration from npm to Plugin

/migrate    # In Claude Code — converts npm-installed metaswarm to plugin

Preserves knowledge base and CLAUDE.md content during migration.

BEADS Setup

# Install BEADS (separate project by Steve Yegge)
# See: https://github.com/steveyegge/beads

# After install:
bd doctor       # Verify setup
bd init         # Initialize in project

metaswarm's /setup checks for BEADS and guides through setup if missing.

Gemini CLI Context

gemini-extension.json in metaswarm root:

{
  "name": "metaswarm",
  "version": "0.11.0",
  "contextFileName": "GEMINI.md"
}

Gemini CLI reads GEMINI.md from the project root as extension context.