# Agent Teams Protocol — APEX

> **Loaded by:** step-01 (analysis scan) and step-03 (parallel execution)
> **Condition:** NOT economy_mode
> **Purpose:** Reusable protocol for TeamCreate, coordination, and shutdown.

---

## Team Creation (T08)

```yaml
TeamCreate:
  team_name: "apex-{phase}"          # e.g., "apex-analyze", "apex-exec"
  description: "{phase purpose}"      # e.g., "Scan SmartStack project for existing code"
```

Always provide both `team_name` and `description`.

---

## Teammate Spawning (T12)

```yaml
Task:
  subagent_type: "Explore" | "general-purpose"  # See assignment table below
  team_name: "apex-{phase}"          # Must match TeamCreate
  name: "{teammate-name}"            # e.g., "scan-backend", "exec-frontend"
  model: "sonnet" | "opus"           # sonnet for scan, opus for dev (T02/T06)
  mode: "bypassPermissions"
  prompt: "{detailed task prompt}"
```

### Model & Agent Assignment (T02/T03/T06)

| Task Type | subagent_type | Model | Justification |
|-----------|---------------|-------|---------------|
| Scan/read files | Explore | Sonnet | Read-only (Glob, Grep, Read) |
| Read context (PRD, feature.json) | Explore | Sonnet | Read-only extraction |
| Code development | general-purpose | Opus | Full tools via skills/MCP |
| Fix/resolve | general-purpose | Opus | Requires reasoning + editing |

---

## Task List Coordination (T10)

Team lead manages the task list:

```
1. TaskCreate: create task for each work item, assign owner
2. Teammate: TaskUpdate(status: "in_progress") before starting
3. Teammate: TaskUpdate(status: "completed") after finishing
4. Lead: TaskList to monitor progress
```

---

## Communication (T09)

**Default:** Direct messages (DM) between specific agents.

```yaml
SendMessage:
  type: "message"                    # DM, not broadcast
  recipient: "{teammate-name}"       # By name, not UUID
  content: "{message}"
  summary: "{5-10 word preview}"
```

**Broadcast:** ONLY for emergency (all-stop, critical blocker).

```yaml
SendMessage:
  type: "broadcast"                  # Expensive: N teammates = N deliveries
  content: "{urgent message}"
  summary: "{critical issue summary}"
```

---

## Team Decomposition (C01)

### Step-01 Analyze: Split by scan scope

```
scan-backend  : Domain/ + Infrastructure/ + Application/ + Api/
scan-frontend : src/pages/ + src/components/ + src/locales/
scan-context  : .ralph/ + docs/business/
```

### Step-03 Execute: Split by execution layer

```
exec-backend  : Application services + API controllers + Seed data
exec-frontend : Pages + Components + Routes + I18n
```

Each teammate has an **isolated scope** (C02): backend never touches frontend.

---

## Coordination (C03)

### Step-01: Lead aggregates scan results

```
1. Spawn 3 scan teammates
2. Each reports findings via DM to lead
3. Lead merges into unified analysis
```

### Step-03: Lead verifies between layers

```
1. Layer 0: lead executes (domain + infra + migration)
2. Build gate: dotnet build --no-restore → MUST PASS
3. Layer 1: spawn exec-backend + exec-frontend
4. Wait for both to complete
5. Build gate: dotnet build + npm typecheck → MUST PASS
6. Layer 2: lead executes final validation
```

---

## Idle Handling (T13)

Teammates go idle after every turn — this is **normal**.
- Idle does NOT mean done or unavailable
- Sending a message to an idle teammate wakes them up
- Do NOT treat idle as an error

---

## Graceful Shutdown (T11)

After phase completes:

```yaml
# For each teammate:
SendMessage:
  type: "shutdown_request"
  recipient: "{teammate-name}"
  content: "Phase complete, shutting down"

# Teammate responds:
SendMessage:
  type: "shutdown_response"
  request_id: "{from_request}"
  approve: true

# After all confirmations:
TeamDelete
```

---

## Decision Matrix

| Condition | Action |
|-----------|--------|
| economy_mode = true | NO teams, all sequential |
| Only backend work | NO teams, agent principal |
| Only frontend work | NO teams, agent principal |
| Backend + Frontend | Teams: exec-backend + exec-frontend |
| Analysis phase | Teams: scan-backend + scan-frontend + scan-context |
