promptdojo_

Pipeline boundaries — where one agent's job ends — step 1 of 7

The boundary is an artifact, not a vibe

Here is the run everyone tries first: one agent, one context window, one prompt — "research the topic, write the draft, review it, publish." Forty steps later the window is a landfill of stale tool output, the agent is grading its own draft (glowingly — chapter lesson 04 covered why), and when step 34 fails, your only restart point is step 1. Nothing in the middle can be inspected, retried, or trusted in isolation.

That is not a model problem. It is a missing-boundaries problem.

A pipeline boundary is the point where one agent's job ends and the next begins. A real boundary has exactly two parts:

  1. An artifact. A file, a JSON blob, a plan.md — durable, on disk, readable by anything.
  2. An acceptance check. A mechanical test the artifact must pass before the next stage starts.

The editor shows the whole idea: a handoff dict, a required list, an all(...) gate. If the sections are there, the boundary is crossed. If not, the handoff bounces back to the producer. What crosses a boundary is the artifact — never the conversation that produced it.

Why not just pass the transcript?

Teams do this constantly: pipe the researcher's full session into the writer "so nothing is lost." Everything is lost. The writer inherits 60k tokens of the researcher's dead ends and context rot (lesson 03), you can never rerun the writer without rerunning the researcher, and there is no contract to check — the downstream agent just absorbs whatever mood the upstream one was in. A boundary that passes vibes is not a boundary. It is one big agent with extra latency.

An artifact handoff buys you four things a transcript never can:

  • A fresh window per stage. Each agent starts with only the artifact and its own instructions. This is the strongest context-rot mitigation in the chapter — compaction you designed in advance instead of performing under pressure.
  • A restart point. Stage three failed? Rerun stage three. The artifact from stage two is still on disk.
  • Isolation testing. You can eval the writer against a fixed research.md a hundred times without touching the researcher.
  • An audit trail. Every artifact and every bounce is a record. Bounces feed the ratchet (lesson 02): a handoff that failed for a new reason earns a new line in the acceptance check.

Who decides what runs next: code or an agent?

Chapter 16 showed you that multi-step work is already a graph — dependencies, joins, gates. The orchestration question is who walks that graph. The rule:

If you can draw the stages in advance, the orchestrator should be code. A for loop over stages, an if on each acceptance check. Deterministic, free, debuggable with a print statement. This is the line Anthropic's Building Effective Agents draws between workflows (predetermined code paths) and agents (the model directs its own process) — and its advice is to reach for the simplest shape that works.

Reserve agent-directed orchestration — an agent deciding which subagent runs next — for the cases where the path genuinely cannot be known up front: open-ended debugging, exploratory research, "figure out why prod is down." Even then, the handoffs stay structured. Letting an agent choose the next stage is sometimes necessary. Letting it improvise what crosses the boundary never is.

Where do you cut? Cut where a natural artifact already wants to exist — a plan, a draft, a verdict, a diff — and where the acceptance check is mechanical. If you can't name the artifact or write the check, you haven't found a boundary; you've found a wish.

Run the editor. Then delete "sources" from the handoff's sections and run it again — that's a bounce, and the producer gets to try again before the writer ever wakes up.