agent-teams - Claude MCP Skill

# 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.

**Requires:** `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` environment variable.

---

## 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.

1. Read `_project_specs/features/*.md` to identify all features
2. Break each feature into the 10-task dependency chain (see below)
3. Spawn one feature agent per feature
4. Assign initial tasks (spec-writing) to feature agents
5. Monitor TaskList continuously for progress and blockers
6. Handle blocked tasks and reassignment
7. Coordinate cross-feature dependencies
8. Send `shutdown_request` to all agents when all PRs are created
9. 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:

1. Read `_project_specs/features/*.md`
2. 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
3. Create the full 10-task dependency chain for that feature
4. 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:
1. `git checkout main && git pull origin main`
2. `git checkout -b feature/{feature-name}`
3. Stages ONLY files changed for this feature (never `git add -A`)
4. Commits with descriptive message including verification results
5. `git push -u origin feature/{feature-name}`
6. `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 Ralph 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 |

---

## Environment Setup

### Required Setting
```json
// settings.json or environment
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "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)