---
applyTo: "**"
---


# Agent Team Protocol

> **Note on naming.** This document uses "team" to mean a group of subagents working within a *single session*, coordinated by a Team Lead via the copilot's delegation tool. Some tools also offer experimental multi-session coordination features (see § "Multi-Session Coordination" at the bottom of this document). The two are different things.

Rules governing multi-agent delegation, phased workflows, and model selection.

## Three-Phase Workflow

Every non-trivial task follows three phases with distinct behaviors:

### Phase 1 — PLAN (Single Agent)
- **Model:** Highest-capability (e.g., Opus) · **Effort:** `xhigh` (Opus 4.7) / `high` (other models)
- Work alone. Do NOT delegate to sub-agents.
- Read the full codebase context, understand architecture, identify risks.
- **Ask clarifying questions** about data model shape, auth strategy, UI layout, and output formats BEFORE producing the plan. (See `clarification-protocol.md` for the full protocol and data model review gate.)
- Produce a concrete plan: files to touch, interfaces to change, test strategy.
- Get user approval before moving to Phase 2.

### Plan Approval Gate

Between Phase 1 (Plan) and Phase 2 (Build), a spec gate applies:

- Plan always writes `specs/<feature-id>/plan.md` with `spec_mode` frontmatter.
- For `full` or `lightweight`: Plan also writes `spec.md`. User approves both before Build.
- For `none`: User approves `plan.md` only. Build proceeds without a spec gate.
- All `[NEEDS CLARIFICATION]` markers in `spec.md` must be resolved before Build starts.

See `spec-workflow.md` for risk classification and required sections.

### Collaboration Gate (Dual Mode)

When `collaboration_mode: dual` in `plan.md` frontmatter **OR** the environment variable `CCT_PEER_REVIEW_ENABLED` is `true`:
- **Plan agent**: run `/review-submit` once (advisory). A FAIL is logged as `plan-consult.md` but does not block Build entry. Proceed to `/phase-complete` regardless of verdict.
- **Build agent**: run `/review-submit` to start the agent-driven review loop. On FAIL, address findings and resubmit. On PASS, proceed to `/phase-complete`. The `build-review.md` artifact must exist with `verdict: PASS` or approved bypass before the session can end.

See `review-loop.md` for the full protocol.

### Phase 2 — BUILD (Team Delegation)
- **Model:** Fast (e.g., Sonnet) · **Effort:** `high`
- **First action — origin alignment gate.** Before decomposing the plan or delegating any sub-agent work, run `scripts/check-origin-alignment.sh <feature-id>`. Exit 0 or 1 proceeds. Exit ≥ 2 halts before delegation and surfaces the three-resolution escalation (rescope / restart / document divergence) — no sub-agent work starts until the user picks A/B/C. See `origin-confirmation.md`.
- Team Lead decomposes the approved plan into discrete tasks.
- Read `specs/<id>/plan.md` frontmatter to determine `spec_mode` gating behavior.
- Delegate each task to the appropriate specialist sub-agent via the Agent tool.
- Each sub-agent works on ONE bounded task with explicit inputs/outputs.
- **Show the delegation plan to the user before executing.** List which agents, what tasks, in what order.
- Team Lead integrates results and resolves conflicts.
- **After each agent returns**: run type checker + dev server before delegating dependent work. (See `phase-workflow.md` § Pre-Build Verification.)

### Phase 3 — REVIEW (Single Agent)
- **Model:** Highest-capability (e.g., Opus) · **Effort:** `xhigh` (Opus 4.7) / `high` (other models)
- Work alone. Do NOT delegate.
- Review all changes holistically: correctness, consistency, style, test coverage.
- Run full test suite, verify no regressions.
- **Check browser console for runtime errors** — type checkers don't catch everything.
- If `collaboration_mode: dual`: verify collaboration artifacts exist with `verdict: PASS` and `blocking_findings_open: 0`.
- Summarize what changed and any remaining concerns.

## Cycle-Transition Handoff

At session start after a cycle has shipped — or right after `/cooldown` writes its report — the Team Lead must lead with the recommended next bet, **not** an open-ended `"What's next?"` prompt. The `cooldown-report` agent already emits the actionable command pair (`/bet <id>` → `/cycle-start <id>`); surface it verbatim. Ask only when there is genuine ambiguity (multiple shaped pitches with no clear ordering, or none at all). Full procedure: `team-lead-efficiency.md` § "Cycle-Transition Handoff (Recommend, Don't Ask)" (issue #25).

## Why Planning Must Not Delegate

Sub-agents only see fragments (one file, one module). Planning requires a holistic view of the entire system: how modules interact, where the boundaries are, what the risk surface looks like. Delegating planning produces fragmented, conflicting plans. Keep planning in one mind.

## Delegation Rules (Build Phase Only)

1. **One task per sub-agent.** Never ask a sub-agent to "implement the feature." Break it down: "Create the order repository interface" or "Add validation to the checkout form."
2. **Explicit context.** Tell each sub-agent which files to read, what interfaces to implement, and what constraints to respect.
3. **No chain delegation.** Sub-agents do not spawn their own sub-agents.
4. **Integrate immediately.** After each sub-agent returns, review its output and verify the build before delegating the next dependent task.
5. **Non-overlapping file ownership.** Every file has exactly one owner per phase. The lead handles shared/cross-cutting code after teammates return. (See `team-lead-efficiency.md`.)
6. **Right-size the team.** 2-3 teammates is the sweet spot. More increases coordination overhead without proportional speedup.

## Session Boundaries

### When to Start a New Session

Start a fresh session (`/clear` or new terminal) at these natural boundaries:

1. **After each completed phase.** Phase 1 → commit → new session → Phase 2. Never run Phases 1 through 4 in one session.
2. **After a commit.** If you've committed and the next task is unrelated, start fresh.
3. **When switching from planning to building.** The plan is captured in a file — the planning conversation is no longer needed.
4. **When debugging exceeds 10 exchanges.** If a bug takes more than 10 back-and-forth messages, the context is polluted with failed attempts. Start a new session with a clean description of the problem.
5. **When `/context` shows high usage.** If the visual grid is mostly full, compress with `/compact` or start fresh.

### Session Size Limits (Guidelines)

| Metric | Target | Maximum |
|---|---|---|
| User messages | 15-20 | 30 |
| Tool calls | 50-100 | 200 |
| Files changed | 10-20 | 40 |
| Duration | 1-2 hours | 4 hours |

These are guidelines, not hard rules. The point is: if you're approaching these limits, you should be asking "is it time for a fresh session?"

### Before Ending a Session

1. **Name the session**: `/rename "phase-2-auth-and-services"` — makes it easy to find later.
2. **Commit if ready**: Don't leave uncommitted work across session boundaries.
3. **Document what's pending**: If work remains, add it to a project-level tracking file (e.g., `doc_internal/TODO.md` or an MVP gap document).
4. **Save key decisions to memory**: `"remember that we chose magic link auth over password-based"`.

### Before Starting a New Session

1. **Read the project CLAUDE.md** — it reloads automatically, but verify it's up to date.
2. **Read any pending TODO / gap documents** — start with awareness of what's left.
3. **Reference the last commit** — `git log -1 --oneline` to orient yourself.
4. **State the objective clearly** — "Implement Phase 3 per the plan in doc_internal/PLAN.md" is better than "continue where we left off."

### Context Window Exhaustion Patterns

From real projects, these are the most common causes of context exhaustion:

| Cause | Sessions Affected | Prevention |
|---|---|---|
| Running 4 phases in one session | Mega-sessions (4+ hours) | One phase per session |
| Extended debugging cycles | Auth failures, config issues | Cap at 10 exchanges; fresh session with clean problem description |
| Pasting large error outputs | Console dumps, stack traces | Paste only the relevant error line, not the full output |
| Repeatedly reading the same files | Agent re-reading files after each message | Use `/compact` to summarize; reference by path |
| Large file rewrites | Agent regenerating entire files | Use targeted edits (diff-over-rewrite) |

### The Ideal Session Arc

```
1. Orient (2 min)    — read CLAUDE.md, check git status, state objective
2. Plan (5-10 min)   — review or create plan for this phase
3. Build (30-90 min) — execute the plan, delegate if needed
4. Verify (5-10 min) — type check, lint, build, smoke test
5. Commit (2 min)    — commit with descriptive message
6. Close (1 min)     — rename session, document pending work
```

Total: 45 minutes to 2 hours. If it's taking longer, consider splitting.

## Context Efficiency

- **One task per session.** Start a new session for unrelated work.
- **Use `/compact` at task boundaries** to reclaim context space.
- **Use `/clear` between task switches** when changing focus entirely.
- **Point to files by path** rather than pasting large blocks into the prompt.
- **Diff over rewrite.** Prefer targeted edits over regenerating entire files.

## Single-Agent Loop Mode (Ralph Loop)

An alternative to team delegation during Build. A single agent runs in a loop: read plan → implement next item → test → commit if passing → repeat.

**When to use instead of team delegation:**
- Task is sequential (each step depends on the previous)
- Clear, testable completion criteria exist
- No human design decisions needed mid-flight
- Parallelism wouldn't help (single-domain work)

**When to use team delegation instead:**
- Multiple independent domains can be parallelized
- Human judgment needed during implementation
- No test suite to verify progress automatically

The Team Lead can also use hybrid mode: delegate a Ralph Loop sub-agent for one bounded task during Build while handling other tasks directly.

See `ralph-loop.md` for the full pattern, PRD format, and safety guards.

## Model & Effort Quick Reference

Effort levels assume Opus 4.7 for the Plan/Review tier. `xhigh` is Opus 4.7 only — on Opus 4.6 and Sonnet 4.6 it falls back to `high`. `high`, `medium`, and `low` are supported across all current models.

| Phase        | Model Tier       | Effort  | Delegation                      |
|--------------|------------------|---------|---------------------------------|
| Plan         | Highest (Opus)   | `xhigh` | None                            |
| Build        | Fast (Sonnet)    | `high`  | Yes                             |
| Build (loop) | Fast (Sonnet)    | `high`  | None — single agent loops       |
| Review       | Highest (Opus)   | `xhigh` | None                            |
| Quick fix    | Fastest (Haiku)  | `low`   | None                            |

**Opus 4.7 calibration note:** Opus 4.7 spawns fewer subagents by default and calibrates response length to task complexity — it prefers concise, inline work over verbose, sprawling delegation. If your task genuinely benefits from parallel subagents or a verbose written analysis, spell that out explicitly in the delegation prompt (e.g., "use subagents to investigate X and Y in parallel" or "produce a detailed written analysis with code examples"). Do not assume it will infer the same defaults Opus 4.6 used.

## Multi-Session Coordination (Tool-Specific)

Some copilots offer experimental multi-session coordination beyond the single-session pattern above (e.g., Claude Code's Agent Teams, Cursor's Cloud Agents, Codex's Subagents SDK). These are tool-specific mechanisms that are not wire-compatible with each other. The single-session principles in this document — non-overlapping file ownership, bounded tasks, lead integration — apply regardless of mechanism. See your tool's documentation for multi-session details.
