Building a sequential pipeline in Claude Code.

A subagent is a description plus a tool budget CORE

In Claude Code, a subagent is structurally a sibling to a skill: it lives as a folder, it has a description that functions as a classifier, and the parent session reads that description to decide when to dispatch to it. The differences are scope and authority. A skill is a piece of instruction the agent reaches for; a subagent is a whole agent the parent dispatches to. A skill runs inside the same agent’s reasoning; a subagent runs in its own reasoning, with its own context window, with its own tool allowlist, and returns a single result the parent can use.

That last property is what makes subagents the right Claude Code primitive for orchestration. In a sequential pipeline, the parent session is the supervisor — it dispatches to subagent A (research), reads A’s output (a file), dispatches to subagent B (draft) with knowledge of where A’s output lives, reads B’s output, and so on. The parent session is doing very little reasoning of its own; it is mostly orchestrating. Each subagent is doing the heavy reasoning for one stage. That separation is the legibility win — when a stage is wrong, you can re-run that subagent in isolation against the same input and see what it does.

Two corollaries that matter for this lesson:

• The subagent’s description is the routing decision the parent makes. A vague subagent description means the parent will not dispatch to it cleanly when the time comes. The Module 7 description-as-classifier discipline applies one layer up. For an orchestration scenario where the parent is following a pre-written script (the blueprint), the description matters a little less than for a skill — but if you want the parent to be able to recover from a half-finished pipeline by deciding “I should re-dispatch the drafter to fill in the missing draft,” the description is what makes that recovery possible.
• The subagent’s tool allowlist is your single biggest cost lever. A subagent that is allowed to read the entire web and call ten MCP servers will, eventually, do exactly that — and the runaway risk lives there. A subagent restricted to “read files in /pipeline/<name>/<date>/01-research/ and write files in /pipeline/<name>/<date>/02-draft/” cannot run away by definition. Tool allowlists are not paranoia; they are the cheapest runaway prevention you have.

A useful mental model: the parent session is a band conductor; each subagent is a section player. The conductor knows the score (the blueprint). Each section player knows their instrument (the contract) and how to read their part (the system prompt). The conductor does not play any instrument; the players do not look at the score directly. That separation is what makes the band sound coordinated rather than chaotic.

Skill vs. subagent — what changes when you go up one layer

If you are coming from Module 7 (where you authored a skill), the jump to a subagent is real. The two structures look similar — both live as folders, both rely on a description, both have a body — but they are not the same thing. The differences govern when you reach for which.

The practical implication: a skill makes one agent better at a recurring task. A subagent makes the system able to compose multiple agents' work into one pipeline. Both belong in your toolkit; the choice is “do I want this work to happen inside the parent's reasoning, or handed off and reported back?”

How the parent session orchestrates CORE

The parent session’s job in a sequential Claude Code pipeline is small, specific, and disciplined. In practice it does five things, in order, for each stage:

1. Read the blueprint. Specifically, the next stage’s input shape and the previous stage’s output shape from the relevant handoff contract. The parent does not need to read every contract every time — but it does need to know what the next subagent expects and what should already exist on disk.
2. Verify the previous stage’s output. Check that the file the previous subagent was supposed to write exists at the expected path and meets the success criteria of the handoff contract. If it does not, do not dispatch the next subagent — invoke the failure mode instead.
3. Dispatch the next subagent. Through the Task tool, with a tightly scoped invocation prompt: “Read the handoff contract for <previous> → <this>. Read your input from <path>. Produce your output at <path> per the contract. Do not invoke other subagents.”
4. Wait, then verify the output. Same check as step 2, but for the new subagent’s output. If the success criteria fail, invoke the failure mode (typically: stop the pipeline, write a status file, alert the student).
5. Move to the next stage, or — if this was the last stage — produce a short pipeline summary the student reads.

This is the whole algorithm for a sequential pipeline. There is no orchestration framework, no event bus, no retry library. There is the parent session reading files, invoking subagents, and checking results. That simplicity is the point: a pipeline you cannot read in five minutes is a pipeline you cannot debug in five hours.

A first-time student often reaches for a more elaborate parent-session prompt — “you are an expert orchestrator; reason about each stage; decide what to do next.” Resist that. The parent’s prompt should be procedural and short. Reasoning belongs in the subagents. The parent is bookkeeping.

What a good trace contains CORE

The trace is the most useful artifact the pipeline produces. A good trace contains:

• Parent-session transcript — the conversation log of the orchestrator, showing each verification check and each Task-tool invocation. This is what the student reads first when something is wrong.
• Each subagent’s invocation — the input the subagent received, the reasoning it did (if the model exposes it), and the output it produced. Subagent invocations appear inline in the parent transcript but are easier to read in isolation if you copy them out.
• The shared-state folder snapshot — every file the pipeline produced, in its end state. This is what proves the pipeline did what it claimed; the transcript can lie or omit, but the files cannot.
• The pipeline summary — the 00-status/pipeline-complete.md (or *-failed.md) file, which is the parent’s own summary.
• Wall-clock time and token cost — at minimum a rough estimate. The Recipe Book has a script that pulls these from the Claude Code session log; you do not need to write it.

Save all five for at least two successful invocations. The traces are what you will read in three months when you wonder why this pipeline behaves the way it does. They are also what you will hand future-you (or, in a less-strict module than Module 8, a teammate) when you need help debugging.

A trace that contains only the final output is not a trace. A trace that contains only the parent transcript is half a trace. A complete trace is all five elements above, in one folder, dated.

.claude/subagents/research-sweeper/
.claude/subagents/brief-drafter/
.claude/subagents/brief-reviewer/
pipeline/<your-pipeline-name>/2026-04-18/00-status/
pipeline/<your-pipeline-name>/2026-04-18/01-research/
pipeline/<your-pipeline-name>/2026-04-18/02-draft/
pipeline/<your-pipeline-name>/2026-04-18/03-review/

---
name: research-sweeper
description: Runs a multi-source research sweep on a named topic and
  writes a sources.md matching the Module 8 research → draft handoff
  contract. Use when dispatched by a parent orchestration session in a
  research → draft → review pipeline. Do not use as a general-purpose
  research tool; the contract is strict and the output path is fixed.
model: cloud-default
allowed-tools: web_search, read_file, write_file
---

You are the research stage of a sequential pipeline.

Your handoff contract is:
- Input: a topic string passed by the parent session.
- Output: a single file at /pipeline/<name>/<date>/01-research/sources.md,
  markdown, with the following required structure:
  - ## Summary (100–300 words)
  - ## Key sources (≥ 3 bullets, each with a URL in parens,
    format `[Title](URL) — 1-sentence takeaway`)
  - ## Open questions (may be empty)
- Success criteria: file exists; summary is 100–300 words;
  ≥ 3 bullets in Key sources, each with a URL.
- Failure mode: if you cannot meet success criteria, write
  /pipeline/<name>/<date>/00-status/research-failed.md naming which
  criterion failed, and stop. Do not retry.

[Then: detailed procedure for how to actually do the research, in the
same five-section body shape as a Module 7 skill — purpose, inputs,
procedure, output contract, failure modes.]

You are orchestrating a three-stage sequential pipeline for
the topic: <TOPIC>.

The pipeline name is <name>. Today's date is <YYYY-MM-DD>.
The shared-state folder is /pipeline/<name>/<date>/.

Execute the following steps in order. Do not skip steps.
Do not invoke any subagent other than what is named.

Step 1 — Dispatch research-sweeper via the Task tool with:
  "Topic: <TOPIC>. Write your output to
   /pipeline/<name>/<date>/01-research/sources.md
   per your handoff contract."

Step 2 — Verify /pipeline/<name>/<date>/01-research/sources.md
  exists. Verify ## Summary is 100–300 words. Verify ## Key sources
  has ≥ 3 bullets each with a URL. If any check fails, stop and alert.

Step 3 — Dispatch brief-drafter via the Task tool with:
  "Read /pipeline/<name>/<date>/01-research/sources.md.
   Write your output to /pipeline/<name>/<date>/02-draft/draft.md
   per your handoff contract."

Step 4 — Verify /pipeline/<name>/<date>/02-draft/draft.md exists.
  Verify it is 600–900 words. Verify each claim has a citation
  pointing to a source from sources.md. If any check fails, stop and alert.

Step 5 — Dispatch brief-reviewer via the Task tool with:
  "Read /pipeline/<name>/<date>/01-research/sources.md and
   /pipeline/<name>/<date>/02-draft/draft.md.
   Write your review to /pipeline/<name>/<date>/03-review/review.md
   per your handoff contract."

Step 6 — Verify /pipeline/<name>/<date>/03-review/review.md
  exists. Verify it has at least one of each: a missing-citations
  section, a weak-claims section, and a factual-conflicts section.
  If any check fails, stop and alert.

Step 7 — Write a short pipeline summary to
  /pipeline/<name>/<date>/00-status/pipeline-complete.md with:
  pipeline name, date, topic, stages completed, total wall-clock time,
  total token cost (best estimate from the trace), and a one-paragraph
  summary of the review's findings.

Adapt the walkthrough to your own pipeline RECIPE

The reference pipeline is research → draft → review. Most students’ real Module 8 pipelines have the same shape (sequential, two or three agents) but a different topic. Adapt the walkthrough as follows:

Substitute your agents. Use your Lesson 8.1 sketch and Lesson 8.2 contracts. If your pipeline is triage → reply-draft, you have two subagents and one handoff contract; the orchestrator prompt has four steps instead of seven. If your pipeline is gather → summarize → format, you have three subagents and two handoff contracts; the orchestrator prompt has roughly the same length as the reference.

Substitute the folder convention. The /pipeline/<name>/<date>/<stage>/ convention does not change. Pick stage names that match your pipeline (01-triage/, 02-reply-draft/, etc.). Three things must be true regardless of the stage names:

1. Stage folders are numbered in pipeline order. This makes it possible to read the folder structure top-down and see the pipeline shape without reading any code.
2. The status folder is 00-status/ so it sorts to the top.
3. Filenames inside each stage folder match the output shape in the handoff contract exactly. If the contract says sources.md, the file is sources.md — not research-output.md.

Adjust the parent-session prompt. The structure stays the same; the steps, paths, and verification checks come from your own contracts. Re-read each verification step and ask: if a subagent silently produced a wrong-looking output, would this check catch it? If not, tighten the check. Verification is the parent’s main job; under-specified checks are the entry point for silent corruption to make it through the whole pipeline.

Adjust the tool allowlists. Each subagent’s allowed-tools should be the minimum set of tools it needs to do its job. A drafter does not need web_search. A reviewer does not need write_file for anywhere outside the 03-review/ folder. The narrower the allowlist, the smaller the runaway surface.

Run the first invocation against a real input. Not a test topic. A topic from your own life. The pipeline only earns its keep if you would actually use the output.

The two-round tightening loop RECIPE

A pipeline that runs end-to-end on the first invocation is rare. A pipeline that produces useful output on the first invocation is rarer. The expected workflow is two rounds of tightening — sometimes three — before you call the pipeline ready.

Round 1 — Read the trace, find the weakest handoff. Read the parent-session transcript and every intermediate file. Ask one question, in this order:

1. Did the pipeline complete? If no — which stage failed and which success criterion did it fail on? The fix is usually in the handoff contract that produced the failed input, not in the failed agent. Tighten the contract; re-invoke.
2. If the pipeline completed, is the final output what the user wanted? If no — read the intermediate files, walking backwards from the final output. Find the first stage whose intermediate output already lacks the quality the final output needs. The weakness almost always entered there.
3. At the weak stage, is the problem the agent or the contract? Almost always the contract. The agent is producing what the contract describes; the contract under-specifies what is needed. Add a specific success criterion (a required section, a required citation format, a length floor) and tighten the upstream agent’s system prompt to produce it.

Re-invoke after every contract change. Save the new trace to 2026-04-18-invocation-2.md. The before/after comparison is the lesson’s deliverable.

Round 2 — Tighten the agent (if needed). If round 1’s contract tightening still does not produce useful output, the agent’s procedural body is the problem. Read the agent’s SUBAGENT.md body. Apply the same five-section discipline from Module 7 lesson 7.3: purpose, inputs, procedure, output contract, failure modes. The most common procedural weakness in Module 8 subagents is over-broad procedure — the agent is told to “do good research” rather than “follow this six-step procedure.” Tighten.

Round 3 — Tighten the orchestration prompt (rare). If the parent session is dispatching wrongly — invoking subagents in the wrong order, skipping verification steps, getting confused about paths — the parent session’s prompt is the problem. This is rare for sequential pipelines because the parent prompt is so short, but it does happen. Treat the parent prompt as just another piece of writing that can be over-broad or unclear, and tighten it the same way.

After round 1 (or round 2 if needed), capture invocation 2’s trace. The capstone requires two successful traces. Successful here means the pipeline completed and the output was usable for the student’s actual goal — not just that the success criteria fired green.