Agent Teams
New v4.2Multiple agents working together — sharing a task list, swapping findings through a filesystem mailbox, and converging on better answers than any one of them could produce alone.
A single agent has tunnel vision
Hard problems benefit from parallel exploration: one agent investigating UX, another the data layer, a third playing devil's advocate. But naive parallelism (spawn 5 isolated subagents and let them report back) loses every interesting interaction — the agents never get to challenge each other's assumptions, build on each other's findings, or coordinate to avoid duplicated work.
Agent Teams (Article XXI, added in v4.2) keeps the parallelism but reintroduces the missing coordination layer through two simple primitives: a shared YAML task list and a filesystem mailbox where agents drop structured JSON messages for each other.
Architecture
One Team Lead spawns N Teammates. They communicate through a shared task list and a JSON mailbox on disk — both auditable, both diff-able, both surviving the session.
How it works
Spawn
Lead creates the team, defines tasks (TT-PLN-001, TT-PLN-002, ...), and spawns named teammates. Each teammate receives the team_id, task_list_path, and mailbox_path in its prompt.
Coordinate
Teammates claim tasks from the shared list, work independently, and post structured JSON messages to the mailbox when they find something cross-cutting. Other teammates read the mailbox before finalizing.
Synthesize
Lead reads the full mailbox, integrates findings across teammates, and produces the consolidated output. Every message is auditable in git history.
Two team modes
Article XXI defines two coordination patterns optimized for different phases of the pipeline.
Planning Team
Detail, Architect, UX, and QA-Planning produce sealed-bid drafts independently, then exchange cross_review_request messages. QA-Planning validates the integrated output.
Build Team (Wave Mode)
Dev and QA-Implementation alternate in waves of 5 tasks. Each Dev completion triggers a task_ready_for_review; QA responds with task_review_findings before Dev picks up the next wave.
Planning Team sequence
How the four planning agents synchronize without stepping on each other.
10 message types
The full vocabulary of the mailbox protocol. Every JSON message is appended to the team's mailbox directory with a stable filename pattern that makes the conversation diff-able and replayable.
task_startedLifecycleTeammate announces they have begun work on a task.
task_ready_for_reviewBuild waveBuild wave: Dev signals a task is implemented and awaiting QA review.
task_review_findingsBuild waveBuild wave: QA returns verdict (pass / warn / block) on a Dev-completed task.
task_completedLifecycleTeammate confirms a task is fully done. Includes summary and counts.
cross_review_requestPlan teamPlan team: ask another teammate to review your output before finalizing.
cross_review_responsePlan teamPlan team: response to a cross-review request, with comments and verdict.
qa_review_findingPlan teamPlan team: QA-Planning flags an issue in another teammate's artifact, requesting re-validation.
qa_baseline_readyBuild waveBuild wave: QA confirms baseline lint/typecheck environment is set up before Dev wave 1.
findingCross-cuttingCross-cutting: a discovery that affects another teammate's domain. Routed by 'to' field.
blockerLifecycleTeammate cannot make progress and needs intervention. Optionally addressed to a specific recipient.
Real-world example
The full audit of this dashboard against the canonical chati.dev framework was conducted using exactly this protocol — 3 sequential teams, 5 parallel teammates each, communicating entirely through the filesystem mailbox. The output report is included in the project's docs/audit directory.