10.3 Running an Agent Team

Subagents gave you departments; worktrees gave you lanes. An agent team is the full construction crew: multiple agents on one shared goal, with divided responsibilities, defined interfaces, and you as the general contractor. This is the lesson where a real feature gets built by a team you're running — and where you learn the two documents that make teams work: the split and the contract.

What you will learn

• Decompose a feature into parallel workstreams that won't fight.
• Write interface contracts — the coordination document that replaces meetings.
• Run the full team cycle: split, brief, build, integrate, review.

Builder principle

Teams don't fail at the work; they fail at the seams. Design the seams first and the work coordinates itself.

When a team, actually

Honest gate before the fun: teams add coordination overhead — split-planning, contracts, integration, your divided attention. The work must be parallel enough to pay for it:

• Decomposable into chunks with thin seams (a page section + its data + its docs: yes; a single tangled algorithm: no).
• Big enough — a day-plus of serial agent work. Under that, one well-run session wins (10.5 will keep you honest here).
• Seam-describable — if you can't write down where the chunks meet, you haven't decomposed it; you've just cut it randomly.

The split

Real example — your capstone-scale feature: adding an online ordering flow to the candle site. The split session (plan mode, main worktree, no building):

Feature: customers pick products, fill a pickup form, get confirmation.
Decompose this for a 3-lane agent team. For each lane: scope, files
it owns, and — most carefully — the seams: every point where lanes
meet, and what crosses there. Flag anything two lanes both need to
touch; that's either a shared contract or a re-split.

A good split comes back looking like:

LANE A — product data + selection UI     (owns: products.json, gallery region)
LANE B — order form + validation         (owns: form region, form logic)
LANE C — confirmation + docs + tests     (owns: confirm view, docs/, harness additions)

SEAMS: A→B: the selected-product object · B→C: the order object
SHARED: index.html layout regions (pre-partitioned above) · styles (append-only)

Note the two moves that kill most collisions before they exist: file ownership (one lane, one owner — anything co-owned gets re-split or contracted) and append-only zones for genuinely shared surfaces.

The contract

The seams need one more thing: agreement on what crosses them — before anyone builds. That's docs/contracts.md, and it's three paragraphs, not a spec novel:

## selected-product (A → B)
{ id, name, price_cents, image_path }
A guarantees: id unique, price_cents integer, image exists.

## order (B → C)
{ products: [selected-product], customer: {name, phone}, pickup_date }
B guarantees: validated before handoff — phone format, date not past.

Every lane's brief points at this file. Now watch what it does: Lane B builds against the contract, not against Lane A's half-finished reality — which is what makes simultaneous work on connected parts possible at all. Sound familiar? It's the same trick as 9.3 (encode the standard, let workers check themselves against it) applied to coordination. Contracts are a harness for seams. Meetings are what teams have instead of contracts; your agents don't need meetings.

The cycle, end to end

1. Split (above) — decisions into decisions.md; contracts written.
2. Brief — each lane gets: its scope, its owned files, the contract, the lane-boundary clause (10.2), and its done-means. Full 2.3 rigor × 3. Yes, briefing a team is real work — it's the work; everything after is supervision.
3. Build — three worktrees, three sessions, you rotating (10.2's rhythm). New team-specific move: seam checks mid-flight — periodically ask a lane, "show me the object you're producing for the contract — exact shape." Drift from contract caught mid-build costs minutes; at integration, hours.
4. Integrate — in dependency order (A, then B, then C), each: PR → reviewer subagent → harness → you → merge → next lane rebases. The seams you designed are where you look hardest — run the crossing: does A's real object satisfy B's real form?
5. Review the whole — one final pass on the assembled feature (your 4.4 human acceptance, at feature scale), then the team retro in your journal: which seam leaked? Which lane's brief was weakest? That's your split-writing skill compounding.

🌱 No-code lane⚙️ Engineer lane

Read the lesson again and count the new concepts: honestly, one — the contract. Everything else is your existing stack at team scale (splits are 1.4 scoping, briefs are 2.3, rotation is 10.2, integration is PRs + reviewer + harness). Run your first team at 2 lanes, not 3, with the thinnest seam you can design — the confidence compounds fast, and 2-lane you of this week becomes 4-lane you of next month without any new lessons. Just reps.

The décomposition skills here are your day job's — the difference is the cost of exercising them just collapsed: interface-first design used to be discipline you paid for upfront; with agent teams it's the literal precondition of parallel speed, which means the incentive gradient finally points at good architecture. Notes from the field: keep lanes short-lived (integrate daily-ish), put contract validators in the harness when the seams are data-shaped (a contract you can execute beats one you can read — 9.3 to the end), and try the specialized-lane pattern: one build lane, one test-writing lane working from the same contract — genuinely adversarial coverage, since the test lane never saw the implementation's assumptions.

Try it now

Your first real team — the 2-lane version:

1. Pick a genuinely decomposable feature on your project (or run the ordering-flow example scaled down: product display + contact-to-order form).
2. Split session → ownership map + one contract. Get the seam right; everything else is forgiving.
3. Brief, build, rotate. Run at least one mid-flight seam check per lane.
4. Integrate in order, crossings tested, retro journaled.
5. Save the split + contract docs — they're templates for every future team, and the capstone is coming.

Check your understanding

• What three properties gate "should this be a team?"
• File ownership and append-only zones — what does each prevent?
• What is a contract, mechanically — and what does "contracts are a harness for seams" mean?
• Why do lanes integrate in dependency order, and where does your review attention concentrate?