Handoff Contract Template

Module 8, Lesson 8.2 · four-field contract worksheet · one sheet per handoff

Copy each filled sheet into: /capstone/pipeline-v1-draft/blueprint.md under the Handoffs section.

How many to print: one sheet per handoff. Count first (see Part 2). A three-agent sequential pipeline uses two sheets; a four-worker parallel fan-out uses two (one fan-out, one fan-in); a hierarchical supervisor with four worker types uses four.

Arrows do not carry meaning. Contracts carry meaning.

A contract with three of the four fields is not a contract — it is a wish. The most common omission is field 4 (failure mode), and that omission is exactly the opening through which retry runaway enters.

Part 1 — The four-field contract, copy-paste markdown

Paste this block once per handoff into blueprint.md. Then fill every field; do not leave any blank. "Whatever the upstream agent produces" is not an acceptable answer — if you write it, you have not thought about the handoff yet.

### Handoff: <upstream agent> → <downstream agent>

- **Input shape (<downstream agent> reads):** <file path; format; required structure; required content>
- **Output shape (<upstream agent> produces):** <file path; format; required structure; required content>
- **Success criteria:** <testable conditions the receiver uses to decide the handoff is usable>
- **Failure mode:** <stop / retry-once / fall-back / skip — and who gets told>

Part 2 — Contract-counting sanity check

Count the handoffs before you start filling sheets. If the count surprises you, revisit the shape picker (Lesson 8.1) before you go further.

Shape	Handoff count	Rule
Sequential, N agents	N − 1	One contract per arrow. Two agents = 1. Three = 2. Four = 3.
Parallel, N workers	2 (always)	One fan-out contract (all workers share it) + one fan-in contract (governs the combiner). Worker count does not multiply.
Hierarchical, K worker types	K (plus upstream/downstream edges)	One contract per supervisor-worker edge. Multiple instances of the same worker type share one contract.

My pipeline shape: ☐ Sequential ☐ Parallel ☐ Hierarchical

My handoff count: — print that many sheets.

Part 3 — Sheet template (fill one per handoff)

Handoff #_____: →

1. Input shape (downstream agent reads)

File path. Format (markdown / JSON / prose). Required structure (headings, bullets, fields). Required content (must include citations, must be under a length limit, etc.).

2. Output shape (upstream agent produces)

Same specificity as input shape, from the sender's point of view. If the receiver's input shape and the sender's output shape do not match, the contract is broken by definition. The two often look identical — that is the sign the contract is tight.

3. Success criteria

At least three testable conditions the receiver can check without reading the sender's mind. Objective and ideally machine-checkable.

Condition 1:
Condition 2:
Condition 3:
Condition 4 (optional):

4. Failure mode

Pick one. Be explicit about what "alert" means (a file written where, a notification how). No unbounded retries.

☐ Stop the pipeline and alert the student. Alert =

☐ Retry once with a tighter prompt, then stop. Retry prompt lives at

☐ Fall back to degraded output at

☐ Skip this stage and pass empty to the next. Downstream impact:

Part 4 — Schema or prose? (three-part test)

A contract is always written as prose in the blueprint. The question is whether the output shape the sender produces should be a machine-parseable schema or a prose format the next stage reads as natural language. Answer for each handoff.

Is the output consumed by logic or by language? Logic (script, tool, calendar) → schema. Language (next agent reasons about it) → prose is usually fine.
Is the output's structure stable enough to write down? Fixed fields every time → schema. Variable-length, variable-emphasis → prose.
Is the pipeline running often enough to reward the ceremony? Daily + downstream script → schema earns its keep. Once a week, one-off → prose.

My answer for this handoff: ☐ Prose with markdown structure ☐ Named-field schema (JSON / YAML / table)

Part 5 — Six vague-contract signals (read every draft with this list)

If any of the following appears in a contract field, the draft is not ready. Tick the ones you caught — the iteration is the learning.

"The output should be good." — Or "high-quality," "well-organized," "clear." Replace with word counts, required sections, required fields.
"The receiver reads the output and uses it." — Not specified what shape, not specified what happens on malformed input.
"Retry if something goes wrong." — Unbounded retries are the fastest path to token runaway. Specify cap and conditions.
"The output is a JSON object." — Not specified which keys, which types, which are required. A JSON contract without named keys is a prose contract with an extra step.
"The input is whatever the upstream agent produces." — The absence of a contract. Write the actual shape.
Contract longer than a page. — Usually the student doing the agent's job inside the contract. Pull the work back into the agent's system prompt.

Part 6 — Output-matches-next-input cross-check

After you have filled every sheet, read them in order. For a sequential pipeline: the output shape of contract N should match the input shape of contract N+1 nearly verbatim. Any mismatch is a silent-corruption risk.

Output shape of contract 1 matches input shape of contract 2.
Output shape of contract 2 matches input shape of contract 3.
Output shape of contract 3 matches input shape of contract 4 (if applicable).
Every contract's failure mode names a bounded action (no unbounded retries).
Every contract is readable in under a minute (roughly half a page).
No contract contains any of the six vague signals from Part 5.

Part 7 — Worked example (reference)

From Lesson 8.2, for comparison against your own drafts.

### Handoff: research-sweeper → brief-drafter

- **Input shape (brief-drafter reads):** A single file at
  /pipeline/<name>/<YYYY-MM-DD>/01-research/sources.md. Markdown.
  Required sections: ## Summary (100–300 words), ## Key sources
  (bulleted list; each bullet is [Title](URL) — 1-sentence takeaway),
  ## Open questions (bulleted list; may be empty).
- **Output shape (research-sweeper produces):** Same file, same path,
  same structure.
- **Success criteria:** File exists. ## Summary section is 100–300 words.
  ## Key sources has ≥ 3 bullets, each with a URL in parentheses.
  ## Open questions exists (may be empty).
- **Failure mode:** If the file is missing or any success criterion
  fails, stop the pipeline and write
  /pipeline/<name>/<YYYY-MM-DD>/00-status/research-failed.md
  naming which criterion failed. Do NOT retry automatically.

This worksheet accompanies Lesson 8.2 of AI Architect Academy. The four-field contract, the contract-counting rule, the schema-or-prose test, and the six vague-contract signals are all concept. File layout and exact frontmatter are recipe and live in /recipe-book/writing-a-handoff-contract.md.