ai-swarm

A structured AI agent swarm framework for engineering teams. Provides a complete pipeline for spec-driven, audited, gate-controlled software development using AI agents.

What this is

A methodology + tooling layer that sits on top of any AI coding assistant. Instead of one agent doing everything, multiple specialized agents handle discrete pipeline stages with hard gates between them.

Pipeline:

audit → spec → implement → drift-detect → review → adversarial-review → gatekeeper → [human gate] → merge → integrator → technical-writer → release-manager

Each stage is handled by a different agent role. Agents cannot skip stages. Human gates are mechanical (lockfiles) and cannot be bypassed.

Structure

packages/
  swarm/              — Core framework: dispatch, hydration, templates, scripts
  swarm-cli/          — create-swarm scaffolding CLI
  agent-substrate/    — Canonical agent config, templates, routing policy
    templates/        — AGENTS.md, CLAUDE.md, .claude/settings.json
    routing/          — Model routing table + schema
    skills/           — Reusable agent skills (seeded empty)
    bin/              — agent-substrate sync CLI
.ai-swarm/
  specs/              — Tracked spec files (one per worktree)

The .ai-swarm/ directory (except specs/) is a gitignored sync artifact — generated by create-swarm or agent-substrate sync, not copied manually.

Quick start

1. Scaffold the swarm into your project

pnpm dlx @marcelle-labs/swarm-cli

This detects your project structure, writes ai-swarm.config.json, and scaffolds the .ai-swarm/ directory with agent templates, scripts, audit templates, and reference docs.

2. Sync canonical agent config

pnpm dlx @marcelle-labs/agent-substrate sync

Renders canonical agent config files (AGENTS.md, CLAUDE.md, .claude/settings.json) into your repo with version and checksum stamps. Use --dry-run to preview.

3. Customize for your project

Architecture fence — define your import boundaries:

.ai-swarm/docs/reference/architecture-fence.txt

Deferred work — list items explicitly NOT to implement yet:

.ai-swarm/docs/reference/deferred-work.md

Meta canon §6 — add your architecture invariants:

.ai-swarm/meta-canon.md  (§6 Architecture Invariants)

4. Install worktree hooks (optional)

bash .ai-swarm/scripts/install-worktree-hooks.sh

5. Wire your AI assistant

Agent config files (AGENTS.md, CLAUDE.md) are rendered by agent-substrate sync. For Claude Code agent role files:

cp .ai-swarm/agents/swarm-conductor.md .claude/agents/swarm-conductor.md
# ...repeat for other agents you want active

Agent roles

Agent	When to invoke	What it does
swarm-conductor	Start of every session	Reads state, decides next action, dispatches work
swarm-auditor	Before any spec	Establishes ground truth via grep (Phase 1) + external research (Phase 2)
swarm-spec-writer	After audit	Writes shell-verifiable specs with REQ-NNN requirements
swarm-implementer	After spec	Executes spec in isolated worktree
swarm-drift-detector	After implementation	Checks spec compliance (5 checks)
swarm-reviewer	After drift detection	Surface-level review and finding triage
swarm-adversarial-reviewer	After reviewer	Semantic compliance, adversarial scenarios
swarm-gatekeeper	After review	Runs full test suite
swarm-integrator	After merge	Archives spec, cleans worktree, logs metrics
swarm-researcher	Standalone	Bootstraps project knowledge
swarm-devsecops	Security/CI work	Ratchet enforcement, security audits
swarm-technical-writer	After merge	CHANGELOG, retrospective capture
swarm-release-manager	Before releases	Pre-release gate verification
swarm-master-coordinator	Multi-swarm	Cross-swarm dependency management

Invoking the pipeline

The canonical invocation is through the conductor:

Run swarm pipeline for @.ai-swarm/specs/my-task.md

The conductor handles all dispatch, gate management, and state transitions.

State management

All state lives in .ai-swarm/state/current.json. Only swarm-state.sh writes to it.

# Check current state
bash .ai-swarm/scripts/swarm-state.sh status

# See what to do next
bash .ai-swarm/scripts/swarm-state.sh next

# Open/close gates
bash .ai-swarm/scripts/swarm-state.sh gate-open <spec-id> <gate-number>
bash .ai-swarm/scripts/swarm-state.sh gate-close <spec-id> <gate-number>

Branch model

• main — release-tagged only, never commit directly
• dev — integration branch, all worktree PRs merge here
• task/<spec-id> — one per active spec, lives in .worktrees/<spec-id>

Worktrees are ALWAYS created off dev. PRs ALWAYS target dev. The release manager handles dev → main promotion.

Spec format

Specs live in .ai-swarm/specs/<spec-id>.md. Minimum required sections:

# Spec: <title>
Branch: task/<spec-id>
Base: dev

## Requirements
- REQ-001: <shell-verifiable requirement>
  Verify: `<bash command that exits 0 on pass>`

## DO NOT
- <explicit exclusions>

## Phase 1: <name>
### Task 1.1
...

## Rollback
...

See swarm-spec-writer agent for the full format including pre-implementation audit table and deferred work check.

Audit-first pattern

No implementation starts without an audit. Every audit runs two phases:

1. Phase 1 (internal): grep-based ground truth — symbol existence, caller/callee analysis, ratchet baseline, architecture fence check
2. Phase 2 (external): fires only for thin/exploratory specs — external assumption citation using audit-templates/external-dependency-enumeration.md

See meta-canon.md §2 for the full protocol.

Anti-patterns to avoid

The 8 named anti-patterns are defined in packages/swarm/templates/docs/reference/anti-patterns.md (rendered into .ai-swarm/ by create-swarm). The critical ones:

• AP-1: Graceful empty returns that mask missing capability
• AP-2: Inlined constants that should route through a service layer
• AP-3: Silent error swallowing in catch blocks
• AP-7: Committing to a gated branch

Adapting to your project

The framework is designed to be project-agnostic. Project-specific content belongs in:

• ai-swarm.config.json — build/lint/test commands, package manager, observability
• .ai-swarm/docs/reference/architecture-fence.txt — your import boundaries (rendered from packages/swarm/templates/)
• .ai-swarm/docs/reference/deferred-work.md — your deferred items (rendered from packages/swarm/templates/)
• meta-canon.md §6 — your architecture invariants (rendered from packages/swarm/templates/meta-canon.md)
• Agent files — do not add project-specific logic; keep agents generic and add amendments

See meta-canon.md §8 Extractability Covenant for the full contract.

Requirements

• Git 2.x (for git worktree)
• gh CLI (for PR creation)
• jq (for workspace-intel.sh)
• An AI assistant that supports custom agent/system prompt files