team-protocol

Team protocol

A team is not a set of roles. It is a set of roles plus an agreed way to talk.

Without one, this happens: an IC hits an ambiguity, writes BLOCKED: needs tech-lead, and exits. The orchestrator reads it, spawns tech-lead with a paraphrase, gets an answer, paraphrases it back, and re-spawns the IC from cold. Three context rebuilds, two lossy translations, and the original question is now a summary of a summary.

The channel: docs/team/messages.jsonl

One append-only event log for the whole team, schema studio-event-schema/v1. It works on a vanilla install, survives an agent dying mid-run, and gives a restarted agent its history back.

docs/team/messages.md is the generated human view of that log — the same relationship docs/31-board.md has to docs/31-board-events.jsonl. Never hand-edit it. A hand edit is overwritten by the next render and is invisible to every rule.

{"id":"MSG-0421","v":1,"ts":"2026-07-29T10:12Z","project":"tipjar","thread":"THR-APP-004",
 "ticket":"APP-004","kind":"question","from":"android-developer","to":["tech-lead"],
 "priority":"material","blocking":false,"requires_response":true,"expires_after_round":6,
 "requirements":["REQ-031"],"summary":"Which error type for a failed toggle?",
 "body":"Spec names TodoError but the repo throws IOException. Which wins?","status":"open"}

Kinds: question · answer · handoff · blocker · fyi · escalation · decision

answer and decision each close exactly one open question on that ticket — pairing is by count, oldest first. So do not use decision for a note that decides nothing: it will silently consume a real open question. Observed live — a decision correcting a tooling mistake made a genuinely unanswered product question look resolved, and the ticket had already shipped on the assumption underneath it. Use fyi for anything that is not an answer.

Rules:

• Append, never edit. Correct a wrong record by appending a later one.
• --summary is one line and must stand alone. It is what the orchestrator and the user read.
• Every message names a ticket — or the ASCII hyphen -, and only -, for project-wide chatter: --ticket -. This said — (an em dash), which team-message.sh does not recognise as the sentinel: it treats it as an ordinary ticket ID, so every project-wide broadcast joined one pseudo-thread and the third one was refused by the anti-ping-pong pair guard. The guard is skipped for - precisely because broadcast chatter carries no thread. A message with no ticket at all cannot be routed or closed.
• A question is not resolved until an answer or a decision on the same ticket exists. board-doctor reads the channel (as a sibling of the board) and reports question_unanswered — and says explicitly when the ticket has already reached qa/done, i.e. shipped on an unconfirmed assumption.