Rule
When work transitions between agents or between phases, the outgoing agent produces a structured handoff document carrying decisions, evidence, open issues, and user preferences. The incoming agent reads only this document — never the raw conversation history from the previous phase.
Why
Raw conversation history wastes tokens on context that no longer matters: ideate-phase discussion is noise during a build, and the build agent doesn’t need the user’s first-pass exploration of options to ship the feature. Structured handoffs distill what the next agent actually needs — the decision, the rationale, the evidence — and let each agent start with a clean context window focused on its task. The token cost reduction is significant in practice: ~16K per call dropping to ~4K with structured handoffs, a 3–4x improvement that compounds across phases.
Applies To
Every phase transition in Build Studio and any multi-agent workflow. External coding agents producing PRs or spec follow-ups also hand off via structured artifacts (PR description, spec doc, plan doc) rather than raw chat transcripts.
How To Apply
Define a typed handoff schema for every phase transition (PhaseHandoff with fromPhase, toPhase, summary, evidence, openIssues, userPreferences). The outgoing agent writes the handoff; the orchestrator routes the handoff (not the transcript) to the incoming agent. If you find yourself wanting to attach the conversation log, that’s a signal the handoff schema is missing a field.
Decision Dimensions
long_term_maintainability: 0.6— typed handoffs age into documentation; transcripts age into noise.schema_grounding: 0.8— handoff fields are explicit slots that lint can validate; freeform chat history cannot be reasoned about programmatically.speed_to_value: 0.4— smaller context windows produce faster, cheaper, more focused agent responses.
Examples
- Positive: The
planphase ends with aPhaseHandoffdocument containing the chosen architecture, the rejected alternatives, the constraints surfaced by the user, and the verification checklist. Thebuildphase agent reads this and starts coding. - Counterexample: The build agent receives the full
planchat transcript including the user’s stream-of-consciousness exploration of options. Tokens burn on irrelevant content and the agent has to re-derive what the actual decision was.
Sources
(Rendered from the sources: frontmatter by WikiSourceCitations — do not duplicate citation prose here.)