03-formations

Module 03: Formations

Pre-built team patterns for multi-agent work.

The Concept

A formation is a pre-defined team structure: who does what, who owns which files, and in what order work flows.

Instead of designing a team from scratch every time you need multiple agents, you pick a formation:

"I'm adding a feature" --> feature-impl formation
"I don't know what's broken" --> bug-investigation formation
"I need a code review" --> code-review formation

When to Use Formations

Situation	Approach	Formation
1-3 tasks	Work directly	None
3-8 independent tasks	Background agents	None
6+ coordinated tasks	Team with formation	Pick one below
Tasks share files or have dependencies	Team with formation	Pick one below

Rule of thumb: If agents don't need to share files or coordinate handoffs, use background agents instead of a formation. Formations add coordination overhead.

Formation Catalog

feature-impl (Most Common)

Adding features to an existing project.

Teammates:
  backend    --> src/routes/, src/services/, src/models/
  frontend   --> src/components/, src/pages/, src/hooks/
  integrator --> docker-compose.yml, nginx.conf, API contracts
  tester     --> tests/, __tests__/

Flow:
  Wave 1: (backend + frontend) in parallel
  Wave 2: integrator wires them together
  Wave 3: tester validates everything

bug-investigation

Unknown root cause. Multiple agents explore hypotheses in parallel.

Teammates:
  investigator-1 --> Hypothesis A (e.g., "race condition in cache?")
  investigator-2 --> Hypothesis B (e.g., "schema mismatch?")
  investigator-3 --> Hypothesis C (e.g., "timeout in external API?")

Flow:
  All work in parallel (READ-ONLY recommended)
  Each reports findings
  Lead synthesizes and picks the fix

code-review

Parallel review across multiple quality lenses. All agents are read-only.

Teammates:
  security-reviewer  --> OWASP Top 10, injection, auth flaws
  perf-reviewer      --> N+1 queries, memory leaks, missing indexes
  coverage-reviewer  --> Missing tests, edge cases, error paths

Flow:
  All work in parallel (READ-ONLY)
  Each produces structured findings

new-project

Greenfield setup with architecture-first flow.

Teammates:
  architect   --> Architecture docs, docker-compose, config
  scaffolder  --> Project skeleton, build config, CI
  db-designer --> Database schema, migrations, seed data

Flow:
  Wave 1: architect designs
  Wave 2: (scaffolder + db-designer) implement in parallel

security-review

Focused security audit with fix capability.

Teammates:
  threat-modeler --> Threat model document, attack surface
  scanner        --> Vulnerability scanning, OWASP checks
  fixer          --> Apply fixes for found issues

Flow:
  Wave 1: (threat-modeler + scanner) in parallel
  Wave 2: fixer addresses findings

lightweight-feature

Small features that only touch one layer (backend-only or frontend-only).

Teammates:
  implementer --> Source code
  tester      --> Tests

Flow:
  implementer --> tester (sequential)

single-file

Minimal overhead for tiny changes.

Teammates:
  implementer --> The specific file

Flow:
  Direct work, single agent

File Ownership

The most important concept in formations: each agent owns specific files.

{
  "teammates": {
    "backend": {
      "agent": "implementer",
      "ownership": {
        "directories": ["src/routes/", "src/services/"],
        "files": ["src/config.py"],
        "patterns": ["*.py"]
      }
    },
    "frontend": {
      "agent": "implementer",
      "ownership": {
        "directories": ["src/components/", "src/pages/"],
        "patterns": ["*.tsx", "*.css"]
      }
    }
  }
}

A pre-hook checks the agent's identity against the registry before allowing writes. This prevents the frontend agent from accidentally editing backend files (and vice versa).

Wave Dependencies

Formations define execution order through waves:

Wave 1: [backend, frontend]    -- parallel
         |
         v
Wave 2: [integrator]           -- waits for Wave 1
         |
         v
Wave 3: [tester]               -- waits for Wave 2

Between waves, the lead agent verifies gate criteria before spawning the next wave.

Formation Registry Schema

See formation-registry.schema.json and examples/ for concrete configurations.

Cost Awareness

Formation	Cost vs Direct	Notes
single-file	1.2x	Barely more than direct
lightweight-feature	2-2.5x	2 agents
feature-impl	3.5-5x	4 agents, wave coordination
bug-investigation	2-4x	3+ parallel agents
code-review	2.5-3.5x	3 parallel reviewers
new-project	3-5x	3 agents, wave dependencies

Rule: If direct work takes less than a few hours, skip formations. The coordination overhead of a team often exceeds time saved by parallelization.

CLAUDE.md Snippet

## Multi-Agent Work

When multiple agents work in parallel:
- Each agent owns specific files/directories (see .formation-registry.json)
- Never edit files outside your ownership
- Complete your tasks before the next wave starts
- Include artifact handoffs (files_changed, test_hints) when completing tasks