Words about orchestration
- Orchestration
- Running several agents together on one job. The shift from Module 7 (one agent doing better work) to Module 8 (several agents composing together).
- Composing vs. directing
- Directing (Modules 3–7) is one agent, one instruction at a time. Composing (Module 8) is several agents with handoffs between them, where the thing you own is the pipeline between them — not any individual agent.
- Pipeline
- The orchestrated system itself — the agents, the handoffs between them, the shared-state folder, the budget and kill switch. The Module 8 capstone artifact is one frozen pipeline.
- Interfaces over agents
- The headline insight: a pipeline's quality is set by the quality of its handoff contracts, not by any single agent. A pipeline of three mediocre agents with tight contracts beats three brilliant agents with vague ones.
The three orchestration shapes
- Sequential pipeline
- Agent A produces output; agent B reads it and produces its own; optionally C reads B's. The work has order dependencies — you cannot draft before research is done. Most students' first pipeline is sequential. When in doubt, sequential.
- Parallel workers
- Several agents run at once on independent subtasks; their outputs are combined. The work has no order dependency among the parallel siblings — each starts from the same input. Faster in wall-clock time; usually more expensive in dollars because of the combiner step.
- Hierarchical supervisor
- A supervisor agent decomposes a goal into subtasks at runtime, spawns workers (often in parallel), reads their outputs, produces the final artifact. The right shape when the decomposition itself requires runtime judgment. The most powerful shape and the most dangerous (depth runaway lives here).
- Fan-out
- The step in a parallel-workers pipeline where one input is split among multiple workers. Cap at 4 in Module 8 unless you have a written reason.
- Fan-in
- The step where the workers' outputs are combined into a single artifact. Always paired with a fan-out.
Picking shape
- Two-question test
- The filter for picking the orchestration shape: (1) Does the work have order dependencies? and (2) Does the decomposition itself need runtime judgment? Yes/no/no → sequential. No/x → parallel. Yes/yes → hierarchical.
- One-agent-too-many test
- Four questions that say do not orchestrate: (1) Has the single-agent version been tried? (2) Is the single-agent version failing on separable sub-problems? (3) Would each sub-problem actually improve with a dedicated agent? (4) Is the goal big enough to justify the overhead? Any "no" means stay with one agent.
Handoff contracts (Lesson 8.2)
- Handoff
- The arrow between two agents in a pipeline. Where work flows from one stage to the next. The place where most pipelines silently corrupt themselves.
- Handoff contract
- The written specification of what flows down a handoff. Four required fields: input shape, output shape, success criteria, failure mode. The Module 8 headline artifact.
- Input shape
- Field 1 of a handoff contract: what the receiving agent expects to get — file path, format, required structure, required content.
- Output shape
- Field 2: what the sending agent promises to produce. Should match the input shape of the next contract. Mismatch is the canonical silent-corruption failure.
- Success criteria
- Field 3: how the receiving agent decides the handoff is usable. Testable conditions, not hopes. "File exists, summary is 100–300 words, ≥3 bullets each with a URL."
- Failure mode
- Field 4: what happens when the handoff fails. Bounded actions only — stop and alert, retry once with tighter prompt, fall back to degraded output, skip and pass empty. Never "retry until successful" — that's retry runaway.
- Schema vs. prose contract
- A handoff is schema-shaped when the receiver is logic (a tool, a script) consuming named fields. Prose-shaped when the receiver is an agent reasoning about natural-language content. Most pipelines have both — prose between language stages, schema where a tool takes over.
- The six vague-contract signals
- Symptoms that a contract is wishful, not testable: "the output should be good"; "the receiver reads and uses it"; "retry if something goes wrong"; "the output is a JSON object" (without keys); "the input is whatever the upstream produces"; contract longer than a page.
Subagents and parent sessions (Lesson 8.3)
- Subagent
- A whole agent the parent dispatches to and waits for. Lives as a folder with a description (classifier), system prompt, and tool allowlist. Different from a Module 7 skill: a skill runs inside the parent's reasoning; a subagent runs in its own context window and returns a single artifact.
- SUBAGENT.md
- This lesson's convention for the file inside each subagent folder, holding the YAML frontmatter and the body. Verify against the current Recipe Book — Claude Code subagent file conventions are evolving.
- Parent session
- The Claude Code session that orchestrates a pipeline. Reads the blueprint, dispatches to subagents via the Task tool, verifies outputs, decides next-steps. Bookkeeping, not reasoning.
- Task tool
- Claude Code's mechanism for dispatching to a subagent. The parent session calls it; the subagent runs in its own context; the parent gets back a result and continues.
- Tool allowlist
- Field in a subagent's frontmatter naming the exact tools that subagent may use. The single biggest cost lever in orchestration. A subagent restricted to specific paths and operations cannot run away by definition.
- Two-round tightening loop
- The expected workflow after authoring a pipeline: Round 1 — find the weakest handoff (almost always not the weakest agent); tighten the contract or the upstream subagent's prompt to match. Round 2 — if needed, tighten the agent's procedural body. Each round produces a dated changelog entry. The before/after pair is the lesson's deliverable.
Cowork pipelines (Lesson 8.4)
- Orchestration by convention
- Cowork pipelines have no live supervisor; the orchestration is the arrangement — staggered scheduled tasks plus a shared folder convention. The student arranges; the schedule runs.
- Self-verifying stages
- The Cowork equivalent of the parent session's check-before-dispatch. Each downstream task's skill begins by reading the upstream output, checking each success criterion, and writing a <stage>-skipped.md status file if any criterion fails. Lives in the skill, not in an orchestrator.
- Stagger
- The time gap between scheduled tasks in a chained pipeline. Must be comfortably longer than each upstream task's worst-case runtime. Stagger too short → downstream reads half-written input; stagger too long → harmless. When in doubt, add minutes.
- 00-status/ folder
- The status folder per pipeline run. Contains <stage>-completed.md / -skipped.md / -failed.md files plus a pipeline-level pipeline-complete.md (or pipeline-<date>.md). The numerical prefix sorts the folder to the top of the date-folder for legibility.
- Pipeline-complete.md vs. <stage>-completed.md
- Two distinct levels: pipeline-level summary (the whole run) lives in pipeline-complete.md or pipeline-<date>.md. Stage-level status lives in <stage>-completed.md etc. Don't confuse them.
- Pipeline path on disk
- The lesson's /pipeline/<name>/<date>/<stage>/ shorthand is for whatever folder root you choose — usually ~/ai-architect-academy/automation/pipeline/ (continuing Module 6's convention) or ~/pipeline/ for a flatter tree. Not literally /pipeline/ at filesystem root.
- Picking the frozen path
- End of Lesson 8.4 — apply two rules. On-demand, goal-bounded → Claude Code is the frozen path. Scheduled, cadence-driven → Cowork is the frozen path. Ambiguous → default to Claude Code for debuggability. The unpicked path is preserved as a sibling under /capstone/pipeline-draft/<other>-sibling/.
Runaway prevention (Lesson 8.5)
- Runaway orchestration
- A pipeline that consumes materially more tokens, time, or dollars than the student expected at blueprint time. Three predictable shapes: depth, fan-out, retry.
- Depth runaway
- A supervisor spawns workers that spawn sub-workers that spawn sub-sub-workers. Each layer looks innocent; the total is not. Rail: depth ≤ 3 layers.
- Fan-out runaway
- A supervisor spawns ten workers when four would have done. Each worker is small; ten of them is not. Rail: fan-out ≤ 4 children per parent. Exceeding either cap requires a written reason on the blueprint.
- Retry runaway
- A stage fails verification, retries, fails again, retries again — and because no one bounded the retry loop, it keeps going. Rail: bounded retries on every failure mode. No contract may say "retry until successful."
- Pre-flight cost estimate
- The arithmetic worksheet you run before any pipeline invocation: agents × expected tokens per agent × price per token = estimated $ per invocation. Must be inside the blueprint's per-pipeline dollar budget and wall-clock budget. Re-run any time the pipeline changes in a way that affects tokens.
- Per-pipeline budget
- The two budgets on the blueprint: a dollar budget per invocation and a wall-clock budget per invocation. The pre-flight estimate must fit inside both.
- Kill switch
- The motor habit of stopping a running pipeline mid-run. On Claude Code: Ctrl-C in the parent session. On Cowork: disable each scheduled task. Three required fields on the blueprint: command/clicks, observable confirmation, recovery. A kill switch you've never used is not a kill switch.
- Runaway audit
- A nine-check audit run against the frozen pipeline before freeze: three shape checks (depth, fan-out, contract completeness), three failure-mode checks (no unbounded retries, verification actually checks, no silent failures), three budget/kill-switch checks (cost estimate inside budget, time estimate inside budget, kill switch fully documented). All nine must pass before freeze.
- Frozen pipeline
- /capstone/pipeline-v1/ — the canonical artifact at end of Module 8. Contains: blueprint, runaway audit, pre-flight cost estimate, subagents/ or scheduled-tasks/, skills-referenced/, traces/, before-after.md.
- Sibling path
- The orchestration path not picked in Lesson 8.4. Preserved as learning evidence under /capstone/pipeline-draft/<other>-sibling/. Not required to pass the audit; required to be legible enough that a reader can tell what it is and how far it got.
- Next review date
- A date ≤ 90 days from freeze, on the blueprint. The pipeline pauses at this date until you re-audit it. Same discipline as Modules 6 and 7.
Capstone artifact paths
- /capstone/pipeline-draft/
- — the working folder during Lessons 8.1–8.4. Contains both paths' work-in-progress files. After freeze in Lesson 8.5, contains only the unpicked path as <other>-sibling/.
- /capstone/pipeline-v1/
- — the frozen artifact at end of Lesson 8.5. Contains the picked path's blueprint, audit, cost estimate, agent definitions, traces, and before/after block.
- /capstone/pipeline-v1/blueprint.md
- — the canonical reference for the pipeline. Shape, agents, handoffs, shared-state folder, budget, kill switch, next review date. Plus a path-picking decision block at the top.