How it works · a guide for people who haven't seen it

Tagteam

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.

View on GitHub ← Back to the workshop
Lead · e.g. Claude

Plans and builds

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.

Reviewer · e.g. Codex

Reads and rules

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.

Arbiter · you

Sets direction and breaks ties

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.

In 30 seconds

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.

The big picture · the whole project, start to finish

A project starts as a conversation, becomes a roadmap, then goes through the phases one at a time

YOU + LEAD Brainstorm free conversation LEAD WRITES Roadmap docs/roadmap.md EACH PHASE, IN ORDER LEAD Plan doc docs/phases/… REVIEWER Plan review rounds → approve LEAD Build code + tests GATE + REVIEWER Code review tests, then rounds approved → phase complete → next phase until the roadmap is finished
You and the lead talk freely only at the start. After that, each phase goes through two review gates: plan review, before any code exists, and code review, after the tests pass. The reviewer has to approve at both gates before the next phase opens.
Step 1 · brainstorm with the lead

Start with a conversation, not a spec

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.

docs/roadmap.mdexample project
# 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.
tagteam serve · cockpit 3.13.0 · demo project
Tagteam cockpit on an idle demo project. The top Needs-you card is a Start card: Next: csv-export — plan, with the command to start it, a Copy command button and a Start button. Below, the lead lane shows a conversation with Claude that ends with the roadmap reordered so csv-export comes first. The reviewer lane on the right is empty: No reviews yet.
Brainstorming in the cockpit. The left lane is a chat with the lead. Here you've agreed to reorder the roadmap, and the lead has done it. The card at the top reads the roadmap and shows the next step (csv-export — plan). Pressing Start turns on the watcher and tells the lead to start that phase. The reviewer lane stays empty until there's a plan to review.
Step 2 · write the phase plan

Each phase gets a written plan, and the reviewer approves it before any code is written

docs/phases/csv-export.mdexample
# 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.

Step 3 onward · one phase, turn by turn

Only one agent works at a time

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.

PLAN CYCLE BUILD IMPL CYCLE Lead plans · builds Gate automatic Reviewer reads · rules Arbiter you Plan · R1 Changes Plan · R2 Approve ✓ Build Impl · R1 Tests pass Approve ✓ phase complete On call the whole time, but not needed for this phase. Steps in on an ESCALATE or NEED_HUMAN, and can leave a note for either agent at any point.

Command it runs
Files written
    handoff-state.json afterwards
    The handoff · what happens inside every cycle

    The reviewer always gets the same four options

    Lead's turn writes / revises Reviewer's turn reads the diff, decides Approved cycle closed Arbiter (you) reads the brief, rules gate · impl SUBMIT tests pass bounce: tests failed REQUEST_CHANGES lead resubmits as round N+1 APPROVE ESCALATE NEED_HUMAN rule: request changes · answer rule: approve
    Every submission goes to the reviewer. On implementation cycles, the gate runs the tests first. The reviewer responds with one of four actions. If the lead resubmits the same thing without changes ten rounds in a row, tagteam escalates to you automatically.

    How the turn gets passed

    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 │
    └──────────────────────────────────────────────────┘

    What gets saved: every round, in order

    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.

    R1LEAD · SUBMIT_FOR_REVIEW

    Plan for csv-export: docs/phases/csv-export.md. Adds export --format csv to the invoices command; tests in tests/test_export.py.

    R1REVIEWER · REQUEST_CHANGES

    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.

    R2LEAD · SUBMIT_FOR_REVIEW

    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.

    R2REVIEWER · APPROVE

    Approved. The quoting rule and streaming are now specified and testable.

    Example content. Real rounds read like this, usually longer.

    Build and code review

    The code has to pass the tests before the reviewer looks at it

    Lead

    Builds to the approved plan

    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.

    tagteam cycle init --phase csv-export --type impl
    Gate (automatic)

    Runs the checks, not an AI

    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.

    GATE: PASS | tests ok | scope 6 paths | plan-doc ok
    Reviewer

    Reads the diff against the plan

    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.

    --action APPROVE → phase complete

    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>.

    tagteam serve · cockpit 3.13.0 · demo project
    Tagteam cockpit during an implementation cycle, round 2. Top strip: checkout-validation, implementation round 2; Codex is working, review round 2; watcher on. The lead lane shows two finished implementation turns and a note that Codex is reviewing. The reviewer lane shows round 1's review marked CHANGES REQUESTED, a pre-check for round 2 marked PASSED with 212 tests ok, scope 6 paths, plan-doc ok, and the round 2 review streaming its live log with a stop turn button.
    A code review in progress. The lead is on its second implementation round, after the reviewer requested changes in round 1. The round-2 submission has already passed the gate (pre-check · PASSED: 212 tests, 6 files in scope, plan doc present). The reviewer's review of it is streaming live in the right lane. While it's the reviewer's turn, the lead waits.
    You · when the human steps in

    You're not in every exchange, only where you're needed

    Escalation

    The reviewer thinks the disagreement is one only you can settle. A short decision brief is written for you, and then you rule.

    tagteam brief
    tagteam rule approve | request-changes

    A question

    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.

    tagteam rule answer --to lead

    Stuck loop

    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.

    auto-escalate at 10 stale rounds

    A note, any time

    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 interject
    tagteam pause · resume
    tagteam serve · cockpit 3.13.0 · demo project
    Tagteam cockpit with an escalation. Top strip: rate-limit-middleware, plan round 3, escalated to you; waiting on you. The Needs-you card, outlined in red, shows the escalation and a decision brief: the crux (what the rate limiter does when its store is unreachable), the lead's position (fail open), the reviewer's position (fail closed with a fallback bucket), and a recommendation with medium confidence, followed by the two tagteam rule commands, a comment box, and Request changes and Approve buttons. Below, both lanes show three plan rounds, the reviewer's first two marked changes requested and the third escalated.
    An escalation, waiting on you. After three plan rounds, the lead and the reviewer still disagree on a product question: should the rate limiter fail open or fail closed? The reviewer escalated, and the briefer wrote a one-screen summary: the crux, each side's position, and a recommendation. Clicking Approve or Request changes runs the same tagteam rule command you'd type in the terminal.
    What it leaves behind · files in your project

    Everything is a file you can open, diff and commit

    PathAppearsWhat it is
    Set once
    tagteam.yamlquickstartWho's the lead, who's the reviewer, and whether the gate is on and which test command it runs.
    templates/ · docs/checklists/quickstartThe phase-plan template and the plan and code-review checklists.
    AGENTS.md · CLAUDE.mdquickstartShort pointers that tell each agent how the handoff works (only created if missing).
    Planning documents: written by the lead, read by everyone
    docs/roadmap.mdbrainstormThe ordered phases, their status and dependencies. Updated as each phase finishes.
    docs/phases/<phase>.mdeach phaseThe plan the reviewer approves, and later the standard the code is checked against.
    docs/decision_log.mdas neededDecisions that last beyond a single phase, and why they were made.
    The record: written by tagteam commands
    handoff-state.jsonevery turnThe baton: phase, plan/impl, round, whose turn, status, plus a short history.
    docs/handoffs/<phase>_plan_rounds.jsonlplan cycleEvery plan submission and reviewer verdict. Tagteam only ever adds to it, never edits.
    docs/handoffs/<phase>_impl_rounds.jsonlimpl cycleThe same for the code review, with the gate's results included.
    docs/handoffs/<phase>_<type>_status.jsoneach cycleThe cycle's current state, plus the git commit it started from, so scope checks compare against the right baseline.
    .tagteam/gates/…logeach impl submitFull test output from each gate run.
    docs/escalations/…mdescalations onlyThe decision brief written for you.
    .tagteam/tagteam.dbalwaysA SQLite mirror of all of the above plus token usage, for the dashboard.
    Running it · how the turn gets from one agent to the other

    The workflow is the same in every mode; only the amount of automation changes

    Manual

    No watcher. When one agent finishes, you tell the other to run /tagteam:handoff. It's the best way to learn the workflow.

    Watched

    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.

    Headless

    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.

    Terms

    Six terms that cover most of it

    Phase
    One section of the roadmap, small enough to plan, build and review in one sitting. It has a slug, like csv-export.
    Cycle
    One review loop for a phase. Every phase has two: plan, then impl.
    Round
    One lead submission plus the reviewer's response. A request for changes starts round N+1.
    Turn
    Whose move it is right now: lead, reviewer, or nobody (done, or waiting on you).
    Gate
    The automatic check (tests, scope, plan doc) that runs when the lead submits code, before the reviewer sees it.
    Arbiter
    You. You set the direction, settle disputes, and answer questions.

    Try it

    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

    Want to see it run?

    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.