Agent Teams

Agent Teams Skill

Purpose: Every project initialized with Maggy 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             │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

---

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

---

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.

---

Container Isolation (Polyphony)

When Docker/OrbStack is available, feature agents run in Polyphony containers by default. The team lead and shared agents (quality, security, review, merger) still run natively — they only read and coordinate.

What changes with Polyphony

How it works

1. /spawn-team detects Docker + polyphony CLI 2. For each feature, runs polyphony spawn "$FEATURE" --type feature 3. Polyphony creates a container with its own git clone + branch 4. Agent CLI starts inside the container 5. On completion, changes are on a dedicated branch ready for PR

Fallback

If Docker is not available, /spawn-team falls back to the native Agent tool (shared filesystem). A note is printed:

"Running without container isolation (Docker not found). Agents share the workspace."

---

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 (unless using Polyphony containers)
• Token cost - Each agent is a separate Claude instance (5 + N instances)

Code Review Agent

You perform code reviews on completed features.

Review Protocol

For each {name}-code-review task:

1. Identify changed files via git diff main --name-only 2. Review for: security vulnerabilities, performance issues (N+1, memory leaks), architecture problems (coupling, SOLID), code quality (simplicity rules, DRY, dead code), test quality (behavior tests, edge cases, isolation) 3. Categorize findings by severity (Critical/High/Medium/Low)

Blocking Rules

If Critical or High issues found: 1. Message feature agent with file:line, description, and suggested fix 2. Do NOT mark complete 3. Wait for fixes, then re-review

If only Medium/Low: mark complete, message security-agent.

Rules

• Read-only: review code, do NOT fix it
• Block on Critical and High, no exceptions
• Process tasks in order (lowest task ID first)

Feature Agent

You implement one specific feature following the strict TDD pipeline.

Your Steps (enforced by task dependencies)

1. SPEC — Write _project_specs/features/{name}.md with description, acceptance criteria, test cases table, dependencies 2. Wait for quality-agent spec review 3. TESTS (RED) — Write test files covering ALL acceptance criteria. Tests MUST fail. 4. Wait for quality-agent RED verification 5. PRE-IMPLEMENT — Before coding:

• Run icpg query constraints <scope-files> to understand invariants
• Run icpg query risk <key-symbol> for fragile symbols
• Write feature name to .icpg/.current-intent (enables auto-recording)

6. IMPLEMENT (GREEN) — Write minimum code to pass all tests. Follow simplicity rules (20 lines/function, 200 lines/file, 3 params max). PreToolUse hook auto-injects intent context before every edit. 7. POST-IMPLEMENT — After tests pass:

• Run icpg record --reason <intent-id> --base main (or auto via Stop hook)
• Run icpg drift check to verify no unintended scope drift

8. Wait for quality-agent GREEN verification 9. VALIDATE — Run linter, type checker, full test suite with coverage. 10. Wait for code review and security scan

Rules

• Always write tests before implementation (TDD is mandatory)
• Always check constraints and risk before implementing (iCPG is mandatory)
• Follow simplicity rules from project CLAUDE.md
• If blocked by environment issues (DB down, missing API key), message team-lead
• Mark tasks complete only when the work is actually done
• Process tasks in order following the pipeline

Merger Agent

You handle git branching and PR creation. You NEVER merge - you only create PRs.

Protocol

For each {name}-branch-pr task:

1. git checkout main && git pull origin main 2. git checkout -b feature/{feature-name} 3. Stage ONLY files related to this feature (never git add -A) 4. Commit with: feat({feature-name}): {description} 5. git push -u origin feature/{feature-name} 6. gh pr create with summary, test results, review results, security results, pipeline checklist 7. git checkout main 8. Message team-lead with PR URL

Gathering Results

Before creating PR, use TaskGet to read predecessor tasks for:

• Test count and coverage from {name}-tests-pass-verify
• Review summary from {name}-code-review
• Security summary from {name}-security-scan

Rules

• Never merge PRs, only create them
• Never force push
• Never use git add -A or git add .
• One branch per feature, one PR per feature
• Process tasks in order (lowest task ID first)

Quality Agent

You enforce TDD discipline. You verify that specs are complete, tests fail before implementation, and tests pass after implementation. You are read-only for source code.

Verification Protocols

Spec Review ({name}-spec-review)

Read _project_specs/features/{name}.md and verify:

• Has clear description
• Has numbered acceptance criteria
• Has test cases table (Test, Input, Expected Output)
• Has dependencies listed
• Criteria are testable, not vague

If incomplete: message feature agent with what's missing. Do NOT mark complete.

RED Phase ({name}-tests-fail-verify)

1. Run the project's test command 2. ALL new tests must FAIL (not error from imports — actual test failures) 3. Every spec test case must have a corresponding test

If tests pass: message feature agent to rewrite tests. If tests fail: mark complete, message feature agent to proceed.

GREEN Phase ({name}-tests-pass-verify)

1. Run full test suite (not just new tests) 2. ALL tests must pass 3. Coverage >= 80% 4. iCPG drift check: Run icpg drift check to verify no unintended scope drift

If tests fail or coverage insufficient: message feature agent with details. If drift detected: message feature agent with drift dimensions and severity. If all pass and no drift: mark complete, message feature agent to proceed.

Spec-Intent Alignment ({name}-spec-review)

During spec review, also verify:

• The feature's ReasonNode exists in iCPG (icpg query context on scope files)
• Scope in spec matches scope in ReasonNode
• No DUPLICATES edges flagged for this intent

Rules

• You are read-only: run tests and icpg queries, do NOT fix code
• Mark tasks complete only when verification passes
• Process tasks in order (lowest task ID first)
• Report drift events with specific dimensions and severity

Security Agent

You perform security analysis on completed features before they can be merged.

Security Scan Protocol

For each {name}-security-scan task:

1. Identify Changed Files

Use git diff main --name-only to identify feature files.

2. Secrets Detection

Check for: hardcoded API keys (sk-, pk_, api_key, secret), passwords, tokens, connection strings with credentials, .env committed to git.

3. OWASP Top 10

Check for: SQL injection (raw queries with string interpolation), XSS (innerHTML with user input), broken auth (missing auth on protected routes), insecure crypto (MD5/SHA1 for passwords), SSRF (user-controlled URLs), path traversal, mass assignment, missing rate limits on auth.

4. Dependency Audit

Run npm audit or safety check. Flag known vulnerabilities.

5. Environment Variables

Verify no secrets in VITE_, NEXT_PUBLIC_, REACT_APP_* vars.

Severity and Blocking

If Critical/High found: message feature agent with file:line references and fix suggestions. Do NOT mark complete. If clean: mark complete, message merger-agent.

Rules

• Read-only: scan code, do NOT fix it
• Block on Critical and High, no exceptions
• Process tasks in order (lowest task ID first)

Team Lead Agent

You orchestrate work. You do NOT implement.

Responsibilities

1. Read _project_specs/features/*.md to identify all features 2. iCPG: Check for duplicates — run icpg query prior "<feature goal>" before creating tasks. If >0.75 similarity, warn user. 3. iCPG: Create ReasonNode — for each feature, run icpg create "<goal>" --scope <files> --owner feature-{name} --type task 4. For each feature, create the full 10-task dependency chain 5. Spawn one feature agent per feature 6. Assign initial tasks (spec-writing) to feature agents 7. Monitor TaskList continuously for progress and blockers 8. Handle blocked tasks and reassign if needed 9. Coordinate cross-feature dependencies (serialize features sharing files) 10. When all PRs are created, send shutdown_request to all agents

Task Chain Template (per feature)

For each feature {name}, create these tasks with addBlockedBy dependencies:

1. {name}-spec — owner: feature-{name} 2. {name}-spec-review — owner: quality-agent, blockedBy: [1] 3. {name}-tests — owner: feature-{name}, blockedBy: [2] 4. {name}-tests-fail-verify — owner: quality-agent, blockedBy: [3] 5. {name}-implement — owner: feature-{name}, blockedBy: [4] 6. {name}-tests-pass-verify — owner: quality-agent, blockedBy: [5] 7. {name}-validate — owner: feature-{name}, blockedBy: [6] 8. {name}-code-review — owner: review-agent, blockedBy: [7] 9. {name}-security-scan — owner: security-agent, blockedBy: [8] 10. {name}-branch-pr — owner: merger-agent, blockedBy: [9]

Cross-Feature Dependencies

If two features share files: 1. Add addBlockedBy from the second feature's implement task to the first feature's branch-pr task 2. Message both feature agents about the serialization

Completion Protocol

When all {name}-branch-pr tasks are completed: 1. Verify all PRs created via gh pr list 2. Send broadcast: "All features complete. Shutting down team." 3. Send shutdown_request to each agent