How it works · a guide for people who haven't seen it
One AI builds it. A second AI checks it. You make the final call.
Tagteam runs a project as a series of small phases. For each phase, a lead agent writes the plan and the code. A reviewer agent, usually a model from a different company, has to approve the plan before any code gets written, and has to approve the code before the phase is done. The two take turns, one at a time, and every exchange is saved to a file.
Talks through the idea with you, writes the roadmap and each phase plan, writes the code and tests, and makes the changes the reviewer asks for.
Can't approve its own work.
Reads each submission, checks it against the plan and the code, then does one of four things: approve, request changes, escalate to you, or ask you a question.
Doesn't write the code.
Decides what gets built. Steps in only when the agents disagree, when one of them has a question, or when you want to leave them a note.
You don't pass messages between them. The handoff state does that.
If you ask one AI to review its own work, you haven't really had it reviewed. Tagteam makes a second AI sign off twice for every phase: once on the plan, before any code exists, and once on the code, after the tests have run. The agents hand the turn back and forth using a small state file, and every step is written down, so you can see why each decision was made.
Run tagteam quickstart in your project. It asks which agent is the lead and which is the reviewer, writes those names to tagteam.yaml, adds starter files (a blank roadmap, a decision log, templates, review checklists), and opens three terminals: Lead, Watcher and Reviewer.
Then you just talk to the lead, either in its terminal or in the web cockpit's lead lane. Tell it what you're building, who it's for, what's out of scope, and what you're worried about. The lead suggests how to break the work into phases, and you push back until the order makes sense to you.
What comes out of this is docs/roadmap.md: an ordered list of phases, each with a status and a one-paragraph description. A phase can also list another phase it depends on, so it won't start until that one is done.
The reviewer hasn't done anything yet. Review starts with the first phase plan.
# Project Roadmap ## Phases ### Phase 1: Invoice data model - **Status:** ✅ Complete - **Description:** Invoice, line-item and customer tables; migrations; seed data. ### Phase 2: CSV export - **Status:** In progress - **Depends on:** Phase 1 - **Description:** `invoices export --format csv` so the accountant stops asking for screenshots. ### Phase 3: Overdue reminders - **Status:** Not started - **Depends on:** Phase 1 - **Description:** Nightly job emails customers whose invoice is 14+ days overdue.
# Phase 2: CSV export ## Summary **What:** `invoices export --format csv` **Why:** accountant needs it for month-end **Depends on:** Phase 1 ## Scope In: one row per invoice, date filter Out: Excel, scheduled exports ## Technical Approach Stream rows with Python's csv module … ## Files to Create/Modify - `app/export.py` — new - `tests/test_export.py` — new ## Success Criteria - [ ] commas/newlines in names survive - [ ] 50k invoices without loading all
When it's time to start a phase, the lead writes a plan at docs/phases/<phase>.md from a fixed template: Summary, Scope (in and out), Technical Approach, Files, Success Criteria, Open Questions, Risks.
Then the lead submits it for review. That opens the phase's plan cycle. The reviewer reads the plan against the real codebase, and anything wrong gets fixed in the document, where a fix takes a sentence. If the same problem shows up in code three days later, it can take an afternoon to fix.
The success criteria are important here: the reviewer uses them in the next cycle to judge whether the code does what the plan said it would.
This is a real phase from the example: one round of changes on the plan, a clean build, and code that passes review the first time. Click any box or use the arrows to see what happens at that step: the command, the files it writes, and what handoff-state.json (the file that tracks whose turn it is) says afterward.
The agents never talk to each other directly. All they share is handoff-state.json, a small file saying which phase they're on, whether it's the plan or implementation cycle (plan/impl), the round number, and whose turn it is. It works like a baton: an agent only acts when the baton is in its hands.
Each agent's turn starts with /tagteam:handoff. The agent reads the state and the latest round, does its work, and runs exactly one command that records the round and hands the baton over. The watcher sees the change and types /tagteam:handoff into the other agent's terminal, so no one has to copy and paste between them.
Each agent begins its reply with a status banner and ends with a box that says who goes next, so you always know where things stand:
Phase: csv-export | Type: plan | Round: 2 | Turn: reviewer | Status: ready Reviewing lead's submission. Read docs/phases/csv-export.md against app/ and the round-1 feedback. Quoting rule is now RFC 4180 via csv.QUOTE_MINIMAL with a test; export streams. $ tagteam cycle add --phase csv-export --type plan \ --role reviewer --action APPROVE --round 2 \ --content "Approved. Quoting + streaming specified." ┌──────────────────────────────────────────────────┐ │ NEXT: Plan approved. Tell claude to implement, │ │ then run /tagteam:handoff start csv-export impl │ └──────────────────────────────────────────────────┘
Each cycle has a log file, docs/handoffs/csv-export_plan_rounds.jsonl, that tagteam only ever adds to. It's the full record of what was submitted and what the reviewer said, so you can check why the plan changed.
Plan for csv-export: docs/phases/csv-export.md. Adds export --format csv to the invoices command; tests in tests/test_export.py.
The plan doesn't say how commas and newlines inside customer names get escaped. Name the quoting rule and add a test for it. Also: is the export streamed or built in memory? Some accounts have 50k invoices.
Quoting: RFC 4180 via csv.QUOTE_MINIMAL; added a success criterion and a test for embedded commas/newlines. Rows stream through a generator, and there's a 50k-row memory test.
Approved. The quoting rule and streaming are now specified and testable.
Example content. Real rounds read like this, usually longer.
Once the plan is approved, the lead writes the code and tests. Nothing is being reviewed during this time. Then it opens the impl cycle with a short submission: what changed, where, and how it was checked.
The same command runs the full test suite. It also checks that the code actually changed since the plan was approved, and that the plan doc exists. If anything fails, the gate bounces the turn back to the lead with the failing output, and the reviewer never sees it.
The reviewer takes the test result as given and doesn't run the suite again. It reads the diff and checks it against the plan's scope and success criteria. Then it's the same four options: approve, request changes (and another round), escalate, or ask you.
When the implementation is approved, the phase is done. The lead marks it ✅ Complete in the roadmap and the phase doc. In single-phase mode, it stops there, and you start the next phase when you're ready. In full-roadmap mode, the watcher moves straight on to the next phase that's ready, meaning one whose dependencies are finished, and hands the lead /tagteam:handoff start <next-phase>.
The reviewer thinks the disagreement is one only you can settle. A short decision brief is written for you, and then you rule.
NEED_HUMAN: the reviewer (or the lead) needs a fact or a preference only you have. Your answer goes to the agent that asked, and the cycle picks up where it left off.
If the lead resubmits identical content ten rounds in a row, tagteam escalates to you automatically. A cycle that's still making progress, even slowly, is never cut off.
Leave an instruction for either agent. It shows up in their next turn, and they have to say how they handled it. You can also pause and resume the handoffs.
tagteam rule command you'd type in the terminal.| Path | Appears | What it is |
|---|---|---|
| Set once | ||
| tagteam.yaml | quickstart | Who's the lead, who's the reviewer, and whether the gate is on and which test command it runs. |
| templates/ · docs/checklists/ | quickstart | The phase-plan template and the plan and code-review checklists. |
| AGENTS.md · CLAUDE.md | quickstart | Short pointers that tell each agent how the handoff works (only created if missing). |
| Planning documents: written by the lead, read by everyone | ||
| docs/roadmap.md | brainstorm | The ordered phases, their status and dependencies. Updated as each phase finishes. |
| docs/phases/<phase>.md | each phase | The plan the reviewer approves, and later the standard the code is checked against. |
| docs/decision_log.md | as needed | Decisions that last beyond a single phase, and why they were made. |
| The record: written by tagteam commands | ||
| handoff-state.json | every turn | The baton: phase, plan/impl, round, whose turn, status, plus a short history. |
| docs/handoffs/<phase>_plan_rounds.jsonl | plan cycle | Every plan submission and reviewer verdict. Tagteam only ever adds to it, never edits. |
| docs/handoffs/<phase>_impl_rounds.jsonl | impl cycle | The same for the code review, with the gate's results included. |
| docs/handoffs/<phase>_<type>_status.json | each cycle | The cycle's current state, plus the git commit it started from, so scope checks compare against the right baseline. |
| .tagteam/gates/…log | each impl submit | Full test output from each gate run. |
| docs/escalations/…md | escalations only | The decision brief written for you. |
| .tagteam/tagteam.db | always | A SQLite mirror of all of the above plus token usage, for the dashboard. |
No watcher. When one agent finishes, you tell the other to run /tagteam:handoff. It's the best way to learn the workflow.
tagteam watch keeps an eye on the baton and types the next command into the right terminal, but it waits until that agent is idle so it never interrupts one mid-task. This is the everyday setup: three terminals side by side.
Each turn runs as a fresh CLI process with no terminal. You follow it with tagteam tail, or watch it in the cockpit (tagteam serve --theme cockpit), the web view of the same state. The screenshots above are from the cockpit.
csv-export.Tagteam is on PyPI under Apache-2.0. Install it, run quickstart in a project, and start talking to the lead.
For the full reference, see docs/how-tagteam-works.md. For the exact rules the agents follow, run tagteam contract.
# install (either works) $ pip install tagteam $ uv tool install tagteam # in your project $ tagteam quickstart
Tagteam drives my client work every day, and it built this site. If you'd like a walkthrough on a real project, or to talk about putting review gates around AI-written code, send a note.