Updated version of my Claude Code agent-teams starter prompt after two months of running the previous cut on real projects.

Key additions:

  • Pre-flight — before spawning any teammate, deliberately violate each enforced rule and confirm the gate actually blocks. Broken tooling with false confidence is worse than no tooling.
  • Explicit specialist spawn triggers — Security Reviewer and Reviewer now have mandatory conditions (auth changes, secret handling, refactors >10 files, etc.). "As needed" collapses to "never" under pressure.
  • Return-format discipline — Builder ≤150 words per task report, Tester cites TESTLOG IDs instead of pasting stack traces, Reviewer writes findings to docs/reviews/ and returns a short pointer. Protects the lead's context window.
  • Structured teammate messaging — SEVERITY / WHAT / WHERE / REPRO / ASK shape. Kills ambiguous "can you look at this" handoffs.
  • Phase pre-mortems — five to ten "what could go wrong" bullets in the phase plan at kickoff. Retrospectives catch what already broke; pre-mortems prevent it.
  • HANDOVER-LOG.md — append-only archive of prior handovers. Cheap insurance against the day you overwrite HANDOVER.md and lose the context you needed.
  • Specialist dismissal at phase close — long-lived reviewers/researchers accumulate context debt. Respawn fresh each phase.
  • Source: field on every ADR — stakeholder | lead | builder | reviewer. Future sessions need to know who made the call, not just what was decided.

Download: STARTPROMPT-AGENT-TEAMS-v2.md.

Full write-up: Paper rules break first.