Skip to main content
Generalmarkus41

agent-team-topologies

Agent-team topology kits — 5 production-ready team configurations with task decomposition, file ownership, worktree guidance, and quality-gate hooks

Stars
12
Source
markus41/claude
Updated
2026-05-11
Slug
markus41--claude--agent-team-topologies
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/markus41/claude/HEAD/plugins/claude-code-expert/archive/v7.6.0/skills/agent-team-topologies/SKILL.md -o .claude/skills/agent-team-topologies.md

Drops the SKILL.md into .claude/skills/agent-team-topologies.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

Agent-Team Topology Kits

Overview

Agent teams parallelize work that would be serial in a single agent. The right topology depends on:

  • Complexity: How many independent concerns are there?
  • Risk: How many reversibility gates are needed?
  • Speed: Can phases run in parallel or must they sequence?

Use the topology selector below, then follow the kit for your chosen topology.

Topology Selector

Signal Topology Why
Frontend + backend + tests all need changes Frontend-Backend-Test Squad Clear file ownership separation
Need architecture review before implementation Architect-Implementer-Reviewer Trio Design gate before code
Hard bug, multiple hypotheses Competing-Hypotheses Debug Council Parallel root-cause exploration
PR needs security + perf + test review Security-Performance-Test Review Board Parallel review disciplines
Large doc migration or README overhaul Docs Migration Sprint Parallel document processing

Topology 1: Frontend-Backend-Test Squad

Use when: A feature requires coordinated changes across UI, API, and test layers.

Team composition:

  • frontend-agent (Sonnet) — edits src/components/, src/pages/, src/hooks/
  • backend-agent (Sonnet) — edits src/api/, src/services/, src/db/
  • test-agent (Sonnet) — edits src/test/, *.test.ts, *.spec.ts
  • coordinator (Opus, main context) — decomposes, coordinates, merges results

File ownership rules:

  • frontend-agent: ONLY files matching src/components/**, src/pages/**, src/hooks/**
  • backend-agent: ONLY files matching src/api/**, src/services/**, src/db/**
  • test-agent: ONLY files matching **/*.test.*, **/*.spec.*, src/test/**
  • Shared files (types, constants): backend-agent owns, frontend-agent reads

Worktree guidance:

  • Run frontend-agent and backend-agent in separate worktrees (isolation: "worktree") when their changes don't share files
  • Keep test-agent in main worktree until frontend and backend complete — it reads both outputs
  • Merge order: backend → frontend → tests

Coordination protocol:

Phase 1 (parallel): frontend-agent + backend-agent implement their slices
Phase 2 (sequential): test-agent writes tests covering both slices
Phase 3 (main): coordinator reviews, resolves any type conflicts, commits

Quality gate hooks:

  • After Phase 1: Run TypeScript type-check across all changed files
  • After Phase 2: Run test suite; block if any new tests fail
  • Merge condition: All 3 agents report DONE with 0 type errors

Example decomposition:

Feature: Add user profile editing

frontend-agent: ProfileEditForm.tsx, useProfile.ts, profile.css
backend-agent: /api/users/[id].ts, userService.ts, userRepository.ts
test-agent: ProfileEditForm.test.tsx, userService.test.ts, api/users.test.ts

Cost estimate: Medium (3 Sonnet agents + 1 Opus coordinator) — ~$0.05-0.15 per feature

Topology 2: Architect-Implementer-Reviewer Trio

Use when: The task involves design decisions that should be validated before code is written.

Team composition:

  • architect (Opus) — reads codebase, proposes design, writes spec
  • implementer (Sonnet) — executes the spec
  • reviewer (Opus) — reviews against spec and quality criteria

File ownership rules:

  • architect: READ-ONLY. Writes only to .claude/designs/<feature>.md
  • implementer: Writes to all production code files per spec
  • reviewer: READ-ONLY. Writes only to .claude/reviews/<feature>.md

Worktree guidance:

  • architect runs in main context (needs full codebase visibility)
  • implementer runs in a worktree branch (feature/<name>)
  • reviewer runs in main context on the implementer's diff

Coordination protocol:

Phase 1: architect analyzes codebase and writes design spec to .claude/designs/<name>.md
Phase 2: [HUMAN GATE] Review spec before implementation — stop here
Phase 3: implementer reads spec and implements
Phase 4: reviewer reads spec + diff, writes verdict to .claude/reviews/<name>.md
Phase 5: [HUMAN GATE] Review verdict before merge

Design spec format (architect output):

# Design: <feature>

## Goal
<one paragraph>

## Approach
<chosen approach with rationale>

## Alternatives considered
| Option | Why rejected |
|--------|-------------|

## Files to create/modify
| File | Change | Risk |
|------|--------|------|

## Interface contracts
<API signatures, data shapes, event types>

## Acceptance criteria
- [ ] <testable criterion>

Cost estimate: High (2 Opus + 1 Sonnet) — ~$0.20-0.50 per feature. Justified for architectural decisions.

Topology 3: Competing-Hypotheses Debug Council

Use when: A hard bug with multiple plausible root causes. Single-agent debugging gets anchored on the first plausible explanation.

Team composition:

  • hypothesis-a-agent (Sonnet) — investigates first hypothesis
  • hypothesis-b-agent (Sonnet) — investigates second hypothesis
  • hypothesis-c-agent (Sonnet) — investigates third hypothesis
  • synthesis-agent (Opus) — reads all 3 reports, picks winner, proposes fix

File ownership rules:

  • All hypothesis agents: READ-ONLY (no writes during investigation)
  • synthesis-agent: writes fix proposal to .claude/debug/<issue>.md

Worktree guidance:

  • All in main worktree (read-only — no isolation needed)
  • Run all 3 hypothesis agents in parallel for maximum speed

Coordination protocol:

Phase 1 (coordinator): Parse error, form 3 hypotheses, assign one to each agent
Phase 2 (parallel): 3 hypothesis agents independently investigate their hypothesis
Phase 3 (synthesis): synthesis-agent reads all 3 reports, selects most evidence-backed root cause
Phase 4 (coordinator): Present synthesis to user, await approval to fix

Hypothesis agent output format:

HYPOTHESIS: <one sentence>
Evidence FOR:
  - <file:line>: <what it shows>
Evidence AGAINST:
  - <fact that doesn't fit>
Confidence: HIGH / MEDIUM / LOW
If true, fix would be: <description>

Synthesis agent output format:

DEBUG SYNTHESIS

Winning hypothesis: <agent> — <hypothesis>
Confidence: HIGH / MEDIUM / LOW
Key evidence: <2-3 bullet points>

Rejected hypotheses:
  - Hypothesis A: <why eliminated>
  - Hypothesis B: <why eliminated>

PROPOSED FIX:
  File: <path>
  Change: <description>
  Risk: <side effects>

Cost estimate: Low-Medium (3 Sonnet + 1 Opus, all read-only) — ~$0.05-0.10 per bug

Topology 4: Security-Performance-Test Review Board

Use when: A PR or change needs parallel review across multiple disciplines.

Team composition:

  • security-reviewer (Opus) — checks for security vulnerabilities, injection, credentials exposure
  • performance-reviewer (Sonnet) — checks for N+1 queries, bundle size, rendering performance
  • test-coverage-reviewer (Sonnet) — checks for missing tests, flaky patterns, coverage gaps
  • chair (Opus, main context) — aggregates all reviews into final verdict

File ownership rules:

  • All reviewers: READ-ONLY
  • chair: writes aggregated verdict to PR description or .claude/reviews/pr-<n>.md

Worktree guidance:

  • All reviewers in main worktree (read-only, no isolation needed)
  • Run all 3 reviewers in parallel — they're independent

Review scope:

  • security-reviewer: every changed file, git diff, dependency changes
  • performance-reviewer: React components (render count), DB queries, bundle imports
  • test-coverage-reviewer: changed files without corresponding test files, coverage delta

Output format (each reviewer):

REVIEW: <discipline>
Verdict: PASS | REQUEST_CHANGES | BLOCK

BLOCK items:
  - <file:line>: <critical issue>

REQUEST items:
  - <file:line>: <should fix>

SUGGEST items:
  - <file:line>: <optional improvement>

PASS items:
  - <what was checked and found clean>

Chair aggregated verdict:

PR REVIEW BOARD VERDICT
Final verdict: APPROVE | REQUEST_CHANGES | BLOCK

Security: PASS | ⚠️ REQUEST | 🚫 BLOCK
Performance: PASS | ⚠️ REQUEST | 🚫 BLOCK
Test Coverage: PASS | ⚠️ REQUEST | 🚫 BLOCK

Consolidated action items:
  MUST FIX: <list>
  SHOULD FIX: <list>
  CONSIDER: <list>

Cost estimate: Medium (2 Opus + 2 Sonnet, read-only) — ~$0.10-0.20 per PR

Topology 5: Docs Migration Sprint

Use when: Large documentation update — multiple files need rewriting, restructuring, or migrating to a new format.

Team composition:

  • doc-agent-1 (Sonnet) — first batch of documents
  • doc-agent-2 (Sonnet) — second batch of documents
  • doc-agent-3 (Sonnet) — third batch of documents
  • editor-agent (Opus) — reviews consistency, cross-references, tone

File ownership rules:

  • Divide document set equally among doc agents (no overlapping files)
  • editor-agent: read-only until all doc agents complete; then edits for consistency

Worktree guidance:

  • Each doc-agent in its own worktree (prevents file conflicts)
  • Merge worktrees back to main after each doc-agent completes
  • editor-agent runs in main context on merged result

Coordination protocol:

Phase 1 (coordinator): List all docs, divide into 3 batches, generate style guide
Phase 2 (parallel): 3 doc-agents rewrite/migrate their assigned batch
Phase 3 (sequential): Merge all 3 worktrees (resolve conflicts if any)
Phase 4 (serial): editor-agent does consistency pass
Phase 5 (coordinator): Final review

Style guide injection: Coordinator writes .claude/doc-sprint-style.md before launching agents. All agents read it first.

Cost estimate: Low (3 Sonnet + 1 Opus, mostly write) — ~$0.10-0.30 per sprint. Very cost-effective for large doc migrations.

Choosing Between Topologies

Is it a bug?
  └─ Multiple plausible causes? → Competing-Hypotheses Debug Council
  └─ Single obvious area? → debugger subagent (not a topology)

Is it a feature?
  └─ Crosses multiple layers (UI + API + DB)? → Frontend-Backend-Test Squad
  └─ Significant architecture decision? → Architect-Implementer-Reviewer Trio
  └─ Pure implementation with clear spec? → implementer subagent (not a topology)

Is it a review?
  └─ Security + performance + test concerns? → Security-Performance-Test Review Board
  └─ Quick review? → code-reviewer subagent (not a topology)

Is it documentation?
  └─ > 10 documents to update? → Docs Migration Sprint
  └─ Single doc? → doc-writer subagent (not a topology)

When NOT to use an agent team

Avoid agent teams for:

  • Single-file changes — overhead exceeds benefit
  • Exploratory work — single agent with cc-intel is better
  • Tight feedback loops — when back-and-forth is needed, teams have coordination cost
  • Unclear decomposition — if you can't clearly assign file ownership, don't parallelize

Rule of thumb: agent teams are worth it when the parallel work takes > 5 minutes per agent and agents won't block each other.

See Also

  • agent-teams skill — core team patterns, worktree coordination
  • agent-teams-advanced skill — eval-optimizer loop, blackboard council
  • autonomy-profiles skill — how to deploy teams in autonomous mode
  • agents/autonomy-planner.md — task decomposition before team launch