agent-teams

What this skill does

# 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             │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

| 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

### Ste