team-protocol git:20261020.a58ef77A

Immutable. This exact content never changes and is served at /api/v1/blob/30051744526c3659.

---
name: team-protocol
description: Use when running any team-* skill (team-council, team-council-plan, team-kickoff, team-refactor, team-review) — dispatching its role agents, settling what they disagree on, or handing off at a CEO gate.
---

# team-protocol

The rules every team-* skill shares. Each caller owns its roles, rounds and gate mapping; this skill owns how agents are dispatched, how their positions are counted, how a run hands off, and how approved work is executed and checked. When a caller and this skill disagree, the caller wins for its own flow.

## Dispatch

- **One agent per role, dispatched in parallel.** Never play the roles yourself in one context (one context, one opinion in several costumes).
- **Separation of context.** Every agent gets the minimum it needs; none receives the conversation, the raw transcripts or another agent's output unless its caller says so. The caller's table says what each one receives.
- **Agents return async.** Send every agent of a round in one message. Each completion wakes you for a turn that re-reads the whole run: until the round's last agent is back, answer a notice in one line under 10 words — no tool call, no Read, no summary of the reply. Then read the replies once and take the next step.
- **Pass the model and budget** from the caller's table to every dispatch.
- **Skill files go into the run folder first.** The skill's base directory (`~/.claude/skills/…` or the plugin cache) is outside the project, so an agent's Read there waits on a permission prompt. Before the first dispatch, copy every skill file an agent will Read into the run folder with one Bash call: the caller's `templates.md`, the role files, this skill's `counting.md`, `bridge.md`, `scope.md`, `execution.md`, `auto-accept.md` and `lane-handoffs.md`, this skill's `SKILL.md` as `team-protocol.md` when the caller's `templates.md` points to a `team-protocol` section, and `team-ceo-view`'s `contract.md` and `figures.md` for any agent that builds a page or draws a sketch. E.g. `cp <base directory>/{templates.md,roles/role-*.md} <base directory>/../team-protocol/{counting.md,bridge.md,scope.md,execution.md,auto-accept.md,lane-handoffs.md} <base directory>/../team-ceo-view/{contract.md,figures.md} <run folder>/ && cp <base directory>/../team-protocol/SKILL.md <run folder>/team-protocol.md`. Create the run folder once the caller's preconditions pass. Check for overrides with `[ -d .council/role-overrides ] && ls .council/role-overrides`: a bare `ls` of a missing folder fails the step. Adapt the paths to the caller: team-council-plan has no `roles/` and copies its role files from `<base directory>/../team-council/roles/`; team-kickoff has no `templates.md` and no `roles/` (its council run copies team-council's). Then point each agent to its copy; a template's pointer to a `team-protocol` section means that section of `team-protocol.md`. A script run through Bash (`render.js`, `cards.sh`) needs no copy, and a project override (`.council/role-overrides/`) is already inside the project. **The copy is the run's first action, and you read the copies too.** Read no skill file but the SKILL.md the Skill tool loaded until it is copied. When you need a section yourself, read it from the copy (`grep -n '^## ' <run folder>/templates.md` first), never from the base directory: a Read there stops the run on a permission prompt.
- **Role overrides.** Templates live in the caller's `roles/`. A project may override any of them with `.council/role-overrides/role-<name>.md`; the project file wins. `<name>` is the role's file name.
- **Roles are lenses.** A role is named after what it looks at, never after a person. This holds for built-in roles, ad-hoc specialists and project overrides.
- **Sources.** Every role file has a `## Sources` section: 5–8 entries, one line each, a source and the question or test it brings. The list is varied on purpose, in gender, country, discipline and epoch. A source earns its place by changing what the agent does.
- **Pick and declare.** The agent picks the 2–3 sources that best fit the case and is not bound to the others. It names the ones it used, where its caller's output format says.
- **Ad-hoc specialists.** When you summon one, write it 3–5 sources by the same rule.
- **Attribution.** Every finding is credited to the role that made it, including what a role got from a specialist skill.

## Writers

Writers keep the orchestrator short. Gate JSON, decision, refactor and review records, exec briefs and plans are written by agents (from the synthesis file, the decisions block or a reviewer's lines). The orchestrator writes prompts and small run-folder notes, flips a `Status:` line, appends a record's *Execution* section, serves the page, and passes the decisions block on. A CEO follow-up that needs more than one grep goes to a sonnet evidence agent: your context is the run's most expensive. A record amendment of ≤ 5 lines you append yourself (`cat >>`), no writer. Each caller's table gives these writers a model and a budget.

- **The synthesis** stays under ~300 lines and holds everything the gate page and the record need, since it is the only run-folder file the gate writer and the record writer read.
- **The exec brief** is for the executors and nothing else: a header (scope, the quality-gate commands copied verbatim, fences for the whole run), then the approved cards in order. No debate, no arguments, no declined or rejected items. Aim under ~150 lines.
- **After execution**, complete the record yourself with one Bash call that appends to it (`cat >> <record> <<'EOF'`), then flip `Status:` to `executed`. The appended `## Execution` section copies the reply lines as they came: *Commits* (hash and item, one line each), *Reverted or blocked* (item and reason), *Notes* (the final reviewer's `note` findings; the caller says what they count as).

## Off-model seat

The caller names the seat that can go off-model. Before the roster line that seats it, read `off-model.md` in this skill's base directory: why, when to offer it, and how to run it.

## Run folder

`.council/runs/YYYY-MM-DD-<topic>/`. Every agent writes its full output there, except a writer whose output is a project file (*Agent contract*). Later agents (Round 2, gate, synthesizer) read the files they need from it. The orchestrator reads only the synthesis file, or, in a flow with none, the reply lines its caller names.

## Agent contract

Append this block to every dispatch prompt, with the budget, run folder and agent id filled in. Every turn re-reads the whole context, so context size × turns is the bill.

```markdown
## How to work
- Budget: about <N> tool calls. Put several searches in one Bash call; Read a file once, whole.
- Tool rules: <the user's standing tool rules from CLAUDE.md, e.g. "absolute paths, never `cd`">
- Only a command's output counts, never IDE diagnostics (they can come from stale buffers). Run each gate command exactly as your brief writes it, with no pipe, redirect or prefix added.
- Write your full output to <run folder>/<agent id>.md.
- A question the code answers is yours: answer it with `file:line`. A claim that something does not exist names the terms and paths you searched, else mark it `unverified`.
- Reply with: the file path, one line per position, card, verdict or defect (id + title), the questions for the CEO, and what you settled alone (`question → answer — source`). Nothing else.
```

Drop the *Tool rules* line when the user has none. A caller may add lines above the budget (team-refactor adds "Start from the Code Brief").

**A writer whose output is a project file** (a plan, a record, an exec brief, a gate JSON) writes it there: its project path replaces the run-folder line, as `- Write your full output to <project path>.` An off-model seat replaces that line too (`off-model.md`).

An agent whose job is not to change the project (a role, a reviewer, an evidence pass) also gets this line: `- Leave the project tree as you found it. Scratch files (a probe test, a script) go in <run folder>; if a tool only runs them from inside the tree, delete them before you reply and say so.`

## Counting positions

Every question the roles disagree on is settled by `counting.md` in this skill's base directory: the count goes in `tags` (`3–1`). The synthesizer and the writers apply it from their copy.

**Confidence.** `counting.md` § *Confidence* is the only definition of `high`, `med` and `low`; agents apply it from their copy.

## Bridge

How business and tech meet on one decision is set by `bridge.md` in this skill's base directory: lenses, constraints and trade-offs. A caller that follows it names it in its REQUIRED BACKGROUND line; its role agents, synthesizer and writers apply it from their copy.

## Structural choices

A structural choice is any of: a new package or module, a new layer, a dependency direction or import rule, a public contract other code builds on, a folder convention. Each is expensive to undo, so the CEO makes it as a choice between options, with a recommendation. A writer never settles one, and an `approve` on a routine step that happens to create one is not that choice. The caller says where its structural choices reach the CEO. A settled one that later work could break also becomes a constraint (`bridge.md` § *Structural choices and constraints*). A choice the user sees (a screen's layout or placement, wording, a flow) is the CEO's in the same way. A spike answers a fact; it never settles one of these.

## Settled without the CEO

The CEO sees every question, and every answer nobody asked them for.
- **A question the code answers is not a CEO question.** The agent that raises it answers it, or an evidence pass does before the pause.
- **Everything settled without the CEO goes on the gate's *Settled without you* list** (`contract.md`, `settled`): a question answered from code, an `assumed` premise or constraint taken as true, a default you or a writer took, an author-intent question sent to a merge request's comment. The CEO can reopen each one.
- **Before the question pause, grep the role files for `assumed`.** Each one is in a question or on the list.

## Code scope

For any caller that reads existing code (Recon, seats, executors): read `scope.md` (copied to the run folder).

## Lane hand-offs

For team-refactor and team-review, which hand what they stumble on in the other lane to a list: read `lane-handoffs.md` (copied to the run folder).

## Handoff

Each CEO gate ends a session. **An open answer.** An UNDECIDED, or a note that asks a question: one check (an evidence agent if it needs code), then one question in chat that states only what the run's files hold and flags the rest as unchecked. The record says "gate pick X, changed in chat to Y" and quotes the CEO; a card made moot is recorded `moot`. Write the record the next phase needs. Before deleting the run folder, grep the deliverables for `runs/` and for ids that exist only in the run (reviewer defects); rewrite those as plain sentences. Evidence, settled notes and sketches worth keeping go to `.council/decisions/<name>-sources/`. Then delete the run folder (anything worth keeping is in the record by then). Then ask once: *"Commit `<the files the next phase reads>` now, as one docs commit?"* Ask it with AskUserQuestion, and name each gitignored file the next phase reads (`git check-ignore`): a worktree executor cannot see it. Worktree executors only see committed files, and a commit made after the handoff line costs turns at the session's largest context. Then tell the user:

*"`/clear`, then: `<next command>` `<path>`."*

The next phase starts from that file, not from a context that holds the whole debate.

## Execution

At execution, read `execution.md` (copied to the run folder).

## Weakened checks

Read `## Weakened checks` in `execution.md` (copied to the run folder). A caller writes "no check weakened (`team-protocol` § *Weakened checks*)".

## Sweep

For a sweep of zones: read `## Sweep` in `execution.md`.

## Auto-accept

Only on an `auto-accept` run: read `auto-accept.md` (copied to the run folder).

## Rationalizations

| Excuse | Reality |
|--------|---------|
| "I'll play the roles myself, it's faster" | One context gives one opinion wearing several costumes, and no tension. Dispatch them. |
| "Four roles back it, that's a clear majority" | Count only positions with checkable evidence. Four uncited agents on one model are one prior counted four times. |
| "I'll skim the transcripts to check the synthesis is fair" | Every file you read is re-read on every later turn. The synthesizer read them; you read its file. |
| "It's close, I'll pick a side and call it a decision" | No majority makes it a tension. The synthesizer suggests a side; the CEO takes it. |
| "We're on a roll, I'll keep going in this session" | The next phase would pay for this whole context on every turn. Write the record, then `/clear`. |
| "The user won't mind the brief going to codex" | Sending their code to another vendor needs their yes, from the profile or from them. |
| "It's a few edits, I'll patch the file myself" | Every edit lands in the most expensive context of the run. Send the fix lines to a fresh writer. |
| "I'll say where the round stands" | Each notice turn re-reads the whole run. One line, no tool, until the last agent is back. |
| "The code answers it, no need to mention it" | Answer it, and put it on *Settled without you*: nothing is decided in the dark. |
| "The placement is a detail, I'll pick" | A choice the user sees is the CEO's. |
| "A new package is an implementation detail; the writer will shape it" | Its boundaries, dependencies and folders are expensive to undo, and an `approve` on one step line among forty is not a choice the human made (§ *Structural choices*). |
| "The fence says format only the changed lines; the executor will comply" | It didn't, seven times in one sweep. The *Diff guard* runs before every commit; words alone don't. |
| "The hand-off list is in the record; someone will pick it up" | Nobody reads it unless a run takes it in. Run the intake (§ *Lane hand-offs*), or the sweep's step for it. |
| "A writer should log the commits in the record" | You already hold the reply lines. One `cat >>` costs less than an agent that reloads everything to write ten lines. |
| "I'll just read the template from the skill folder, it's one file" | It sits outside the project: the Read stops the run on a permission prompt. Copy first, then read the run-folder copy. |

## Red Flags

- Writing a role's position, card or verdict yourself
- Writing or patching a gate JSON, record, exec brief or plan yourself (a `Status:` line and the *Execution* append aside)
- Fixing a reviewer's finding, or editing code between batches, yourself
- A turn spent only on "X is back, waiting for the others"
- An agent waiting on a permission prompt to read a skill file
- You reading a skill file from its base directory instead of the run-folder copy
- A counted position written before a CEO answer that contradicts it
- Every role agreeing on everything
- A count in `tags` that includes a position with no `file:line`, doc, output or measurement
- Opening a run-folder file other than the synthesis or a skill-file copy
- Starting the next phase in the session that ran the gate
- An external model CLI called without a yes on record
- A gate auto-accepted in a run the human did not invoke with `auto-accept`
- A template pointing an agent to a `team-protocol` section, with no `team-protocol.md` in its run folder
- A structural choice that reached the CEO only as a routine step, or not at all
- A commit made without its brief's *Diff guard* run
- A hand-off line with no scenario
- A card that restates a *Settled* line with no new evidence
- On an auto-accept run with no page, an item without a recommendation, a `corrects` item or an unmet `after` that was never asked about