agent-teams

Claude Code Agent Teams - default team-based development with strict TDD pipeline enforcement

Quality

40%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/agent-teams/SKILL.md

Agent Teams Skill

Load with: base.md + code-review.md + security.md + session-management.md

Purpose: Every project initialized with claude-bootstrap runs as a coordinated team of AI agents. This is the default workflow, not optional. Teams enforce a strict TDD pipeline where no step can be skipped.

Setup: Agent definitions go in .claude/agents/ with proper frontmatter (name, description, model, tools, disallowedTools, maxTurns, effort). See agent files for the format.

Core Principle

Every feature follows an immutable pipeline enforced by task dependencies:

┌─────────────────────────────────────────────────────────────────┐
│  STRICT FEATURE PIPELINE (IMMUTABLE)                            │
│  ──────────────────────────────────────────────────────────────  │
│                                                                  │
│  1. SPEC        Write feature specification                      │
│       ↓         (Feature Agent)                                  │
│  2. REVIEW      Quality Agent reviews spec completeness          │
│       ↓         (Quality Agent)                                  │
│  3. TESTS       Write failing tests for all acceptance criteria  │
│       ↓         (Feature Agent)                                  │
│  4. RED VERIFY  Quality Agent confirms ALL tests FAIL            │
│       ↓         (Quality Agent)                                  │
│  5. IMPLEMENT   Write minimum code to pass tests                 │
│       ↓         (Feature Agent)                                  │
│  6. GREEN VERIFY Quality Agent confirms ALL tests PASS + coverage│
│       ↓         (Quality Agent)                                  │
│  7. VALIDATE    Lint + type check + full test suite              │
│       ↓         (Feature Agent)                                  │
│  8. CODE REVIEW Multi-engine review, block on Critical/High      │
│       ↓         (Code Review Agent)                              │
│  9. SECURITY    OWASP scan, secrets detection, dependency audit  │
│       ↓         (Security Agent)                                 │
│  10. BRANCH+PR  Create feature branch, stage files, create PR    │
│                 (Merger Agent)                                    │
│                                                                  │
│  No step can be skipped. Task dependencies enforce ordering.     │
│  Quality Agent verifies RED/GREEN transitions.                   │
│  Code Review + Security Agents gate the merge path.              │
│  Merger Agent handles branching and PR creation.                 │
└─────────────────────────────────────────────────────────────────┘

Default Agent Roster

Every project spawns 5 permanent agents + N feature agents:

┌─────────────────────────────────────────────────────────────────┐
│  DEFAULT TEAM ROSTER                                             │
│  ──────────────────────────────────────────────────────────────  │
│                                                                  │
│  PERMANENT AGENTS (always present)                               │
│  ─────────────────────────────────                               │
│  Team Lead        Orchestration, task breakdown, assignment      │
│                   Uses delegate mode - NEVER writes code         │
│                                                                  │
│  Quality Agent    TDD verification (RED/GREEN phases)            │
│                   Coverage gates (>= 80%)                        │
│                   Spec completeness review                       │
│                                                                  │
│  Security Agent   OWASP scanning, secrets detection              │
│                   Dependency audit, .env validation               │
│                   Blocks on Critical/High                        │
│                                                                  │
│  Code Review Agent  Multi-engine code review                     │
│                     Claude / Codex / Gemini / All                │
│                     Blocks on Critical/High                      │
│                                                                  │
│  Merger Agent     Creates feature branches                       │
│                   Stages feature-specific files only              │
│                   Creates PRs via gh CLI                          │
│                   NEVER merges - only creates PRs                │
│                                                                  │
│  DYNAMIC AGENTS (one per feature)                                │
│  ────────────────────────────────                                │
│  Feature Agent    Implements one feature end-to-end              │
│  (x N features)   Follows strict pipeline above                  │
│                   Uses Ralph loops for implementation             │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Agent	Role	Plan Mode	Can Edit Code
team-lead	Orchestration, task breakdown, assignment	No (delegate mode)	No
quality-agent	TDD verification, coverage gates	Yes	No (read-only)
security-agent	OWASP scanning, secrets detection	Yes	No (read-only)
review-agent	Multi-engine code review	Yes	No (read-only)
merger-agent	Branch creation, PR management	No	No (git only)
feature-{name}	Feature implementation (one per feature)	No	Yes

Team Lead Responsibilities

The Team Lead is the orchestrator. It NEVER writes code.

Read _project_specs/features/*.md to identify all features
Break each feature into the 10-task dependency chain (see below)
Spawn one feature agent per feature
Assign initial tasks (spec-writing) to feature agents
Monitor TaskList continuously for progress and blockers
Handle blocked tasks and reassignment
Coordinate cross-feature dependencies
Send shutdown_request to all agents when all PRs are created
Clean up the team when done

Delegate mode is mandatory. The team lead uses only:

TeamCreate, TaskCreate, TaskUpdate, TaskList, TaskGet
SendMessage (message, broadcast, shutdown_request)
Read, Glob, Grep (for monitoring)

Feature Agent Workflow (MANDATORY)

Each feature agent MUST follow this exact sequence. Task dependencies enforce ordering - a feature agent cannot start step N+1 until step N is marked complete and verified.

Step 1: Write Spec

Create _project_specs/features/{feature-name}.md
Include: description, acceptance criteria, test cases table, dependencies
Follow the atomic TODO format from base.md skill
Mark task complete -> Quality Agent reviews

Step 2: Write Tests (RED Phase)

Write test files based on spec's test cases table
Tests MUST cover ALL acceptance criteria
Import modules that don't exist yet (they will fail)
Mark task complete -> Quality Agent verifies tests EXIST and FAIL

Step 3: Wait for RED Verification

Quality Agent runs tests and verifies ALL new tests fail
If any test passes without implementation -> rewrite tests
Quality Agent marks verification complete -> unlocks implementation

Step 4: Implement (GREEN Phase)

Write minimum code to make all tests pass
Follow simplicity rules from base.md (20 lines/function, 200 lines/file, 3 params)
Use Ralph loops (/ralph-loop) for iterative implementation
Run tests after implementation - ALL must pass
Mark task complete -> Quality Agent verifies tests pass

Step 5: Wait for GREEN Verification

Quality Agent runs full test suite and checks coverage
Coverage must be >= 80%
If tests fail or coverage insufficient -> fix and re-request
Quality Agent marks verification complete -> unlocks validation

Step 6: Validate

Run linter (ESLint / Ruff)
Run type checker (TypeScript / mypy)
Run full test suite with coverage
Fix any issues
Mark task complete -> unlocks code review

Step 7: Wait for Code Review

Code Review Agent runs /code-review on changed files
If Critical or High issues -> fix and re-request review
Code Review Agent marks complete -> unlocks security scan

Step 8: Wait for Security Scan

Security Agent runs security checks
If Critical or High issues -> fix and re-request scan
Security Agent marks complete -> unlocks merge

Step 9: Wait for Branch + PR

Merger Agent creates feature branch, stages files, creates PR
Feature is complete when PR is created

Task Dependency Chain Model

For each feature "X", the team lead creates these 10 tasks with strict ordering:

┌────────────────────────────────────────────────────────────────┐
│  TASK CHAIN FOR FEATURE "X"                                     │
│                                                                  │
│  Task 1:  X-spec                                                │
│           owner: feature-X                                       │
│           blockedBy: (none)                                      │
│           ↓                                                      │
│  Task 2:  X-spec-review                                         │
│           owner: quality-agent                                   │
│           blockedBy: X-spec                                      │
│           ↓                                                      │
│  Task 3:  X-tests                                               │
│           owner: feature-X                                       │
│           blockedBy: X-spec-review                               │
│           ↓                                                      │
│  Task 4:  X-tests-fail-verify                                   │
│           owner: quality-agent                                   │
│           blockedBy: X-tests                                     │
│           ↓                                                      │
│  Task 5:  X-implement                                           │
│           owner: feature-X                                       │
│           blockedBy: X-tests-fail-verify                         │
│           ↓                                                      │
│  Task 6:  X-tests-pass-verify                                   │
│           owner: quality-agent                                   │
│           blockedBy: X-implement                                 │
│           ↓                                                      │
│  Task 7:  X-validate                                            │
│           owner: feature-X                                       │
│           blockedBy: X-tests-pass-verify                         │
│           ↓                                                      │
│  Task 8:  X-code-review                                         │
│           owner: review-agent                                    │
│           blockedBy: X-validate                                  │
│           ↓                                                      │
│  Task 9:  X-security-scan                                       │
│           owner: security-agent                                  │
│           blockedBy: X-code-review                               │
│           ↓                                                      │
│  Task 10: X-branch-pr                                           │
│           owner: merger-agent                                    │
│           blockedBy: X-security-scan                             │
└────────────────────────────────────────────────────────────────┘

Parallel Feature Execution

Multiple features run their chains in parallel. Shared agents process tasks as they unblock:

Feature: auth         Feature: dashboard      Feature: payments
  auth-spec             dash-spec               pay-spec
  auth-spec-review      dash-spec-review        pay-spec-review
  auth-tests            dash-tests              pay-tests
  auth-fail-verify      dash-fail-verify        pay-fail-verify
  auth-implement        dash-implement          pay-implement
  auth-pass-verify      dash-pass-verify        pay-pass-verify
  auth-validate         dash-validate           pay-validate
  auth-code-review      dash-code-review        pay-code-review
  auth-security         dash-security           pay-security
  auth-branch-pr        dash-branch-pr          pay-branch-pr
       |                     |                       |
       v                     v                       v
   [All chains run simultaneously]
   [Quality Agent handles all verify tasks as they unblock]
   [Review Agent handles all review tasks as they unblock]
   [Security Agent handles all scan tasks as they unblock]
   [Merger Agent handles all branch-pr tasks as they unblock]

Inter-Agent Communication

Direct Messages (for targeted work)

Feature Agent -> Quality Agent:  "Tests written for auth, ready for RED verify"
Quality Agent -> Feature Agent:  "All 7 tests fail as expected. Proceed to implement"
Feature Agent -> Review Agent:   "Implementation complete, ready for code review"
Review Agent  -> Feature Agent:  "2 High issues found: [details]. Fix before proceeding"
Security Agent -> Merger Agent:  "Security scan passed for auth feature"
Merger Agent  -> Team Lead:      "PR #42 created for auth feature"

Task List (source of truth for state)

All agents check TaskList after completing work
Quality Agent claims verification tasks automatically
Review Agent claims code-review tasks automatically
Security Agent claims security-scan tasks automatically
Merger Agent claims branch-pr tasks automatically

Broadcast (rare - blocking issues only)

Team Lead -> All: "Blocking dependency found between auth and dashboard"
Security Agent -> All: "Critical vulnerability in shared dependency"

Feature Agent Spawning

The team lead spawns one feature agent per feature:

Read _project_specs/features/*.md
For each feature spec, spawn a feature agent:
- name: feature-{feature-name}
- Uses .claude/agents/feature.md definition
- Spawn prompt includes the feature name and spec location
Create the full 10-task dependency chain for that feature
Assign the spec-writing task to the feature agent

Example

If project has 3 features: auth, dashboard, payments

Spawn: feature-auth, feature-dashboard, feature-payments
Create 30 tasks total (10 per feature)
Each feature agent starts with their spec task
All 3 work in parallel

Branch and PR Strategy

One branch per feature. One PR per feature.

Branch naming:  feature/{feature-name}
PR title:       feat({feature-name}): {short description}
PR body:        Generated from spec + test results + review + security results

The Merger Agent:

git checkout main && git pull origin main
git checkout -b feature/{feature-name}
Stages ONLY files changed for this feature (never git add -A)
Commits with descriptive message including verification results
git push -u origin feature/{feature-name}
gh pr create with full template including:
- Summary from feature spec
- Test results from quality verification
- Code review summary from review agent
- Security scan results from security agent
- Checklist of all pipeline steps completed

Quality Gates

Workflow Enforcement (via task dependencies)

Task dependencies make it structurally impossible to skip steps
A feature agent cannot see "implement" until quality agent completes "tests-fail-verify"
This is the primary enforcement mechanism

Cross-Agent Verification (trust but verify)

Quality agent independently runs tests (doesn't trust feature agent's report)
Security agent independently scans (doesn't trust review agent)
Merger agent verifies all predecessor tasks are complete before branching

Blocking Rules

Quality Agent: blocks if tests don't fail (RED) or don't pass (GREEN) or coverage < 80%
Code Review Agent: blocks on Critical or High severity issues
Security Agent: blocks on Critical or High severity findings
Merger Agent: refuses to branch if any predecessor task is incomplete

Integration with Existing Skills

Existing Skill	How Agent Teams Uses It
base.md	TDD workflow, atomic todos, simplicity rules - all agents follow
code-review.md	Review Agent executes `/code-review` per this skill
security.md	Security Agent follows OWASP patterns from this skill
session-management.md	Each agent maintains its own session state
iterative-development.md	Feature agents use Stop hook TDD loops for implementation
project-tooling.md	Merger Agent uses `gh` CLI for branches and PRs
team-coordination.md	Superseded by agent-teams for automated coordination
icpg.md	Team lead creates ReasonNodes. Feature agents query constraints/risk. Quality agent checks drift. PreToolUse hook injects context. Stop hook auto-records symbols.
code-graph.md	Feature agents use graph for symbol lookup alongside iCPG for intent context

Environment Setup

Required Setting

// settings.json or environment
{
  "env": {
    "agent teams (via .claude/agents/ definitions)": "1"
  }
}

Project Structure (created by /initialize-project)

.claude/
  agents/            # Agent definitions (from agent-teams skill)
    team-lead.md
    quality.md
    security.md
    code-review.md
    merger.md
    feature.md
  skills/
    agent-teams/     # This skill
      SKILL.md
      agents/        # Agent definition templates
    base/
    code-review/
    security/
    ...

Spawning the Team

Automatic (via /initialize-project)

After project setup completes, Phase 6 asks for features and spawns the team automatically.

Manual (via /spawn-team)

For existing projects: run /spawn-team to spawn the team from existing feature specs.

Limitations

Experimental feature - Agent teams require the experimental env var
No nested teams - Teammates cannot spawn sub-teams
One team per session - Clean up before starting a new team
No session resumption - If session dies, re-run /spawn-team (tasks persist)
File conflicts - Features sharing files must be serialized by team lead
Token cost - Each agent is a separate Claude instance (5 + N instances)

Repository: alinaqi/claude-bootstrap
Commit: d4ddb03

Last updated: 4 days ago
Created: 4 days ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.