Orchestration Shape Picker
Save this as: /capstone/pipeline-v1-draft/shape-picker.md (or print and keep alongside your blueprint).
Fill order: one-agent-too-many test first (should you orchestrate at all?) → two-question shape test → agent sketch → depth/fan-out rail declaration. Do not skip ahead to writing contracts; the shape is what the contracts will sit inside.
The quality of an orchestrated system is set by the quality of its interfaces, not the quality of its agents.
Most first pipelines are sequential. When in doubt, pick sequential. A pipeline you cannot read in five minutes is a pipeline you cannot debug in five hours.
Header
Part 1 — The one-agent-too-many test
Before you pick a shape, decide whether you should orchestrate at all. Answer every question. If the answer to any question is no, do not orchestrate — tighten the single-agent version first and come back to Module 8 later.
Does the single-agent version already succeed?
Have you actually run this as one prompt, one skill, or one scheduled task and gotten an acceptable result? Half of would-be pipelines collapse into "one agent with a better prompt is fine."
☐ Yes ☐ No — One-line evidence:
Is the single-agent version failing on separable sub-problems?
When it fails, does it fail at the same step every time? Orchestration helps with localized failures; not diffuse ones.
☐ Yes ☐ No — Which step(s) keep failing?
Does each sub-problem get materially better with a dedicated agent?
Would a focused agent — its own prompt, its own context, maybe its own model — actually do a cleaner job than "please also check X" appended to the main agent?
☐ Yes ☐ No — What does the dedicated agent do differently?
Is the goal big enough to justify the orchestration overhead?
A goal a human takes 5 minutes on and an agent takes 30 seconds on is almost never worth a pipeline. A goal a human takes an hour on, that happens three times a week, usually is.
☐ Yes ☐ No — How often does this job run? How long does it take today?
Gate decision
All four answers yes? ☐ Yes — proceed to Part 2. ☐ No — stop here, tighten the single-agent version first.
Part 2 — The two-question shape test
Now pick the shape. Answer both questions, then circle the shape the answers point to.
Does the work have order dependencies?
Is there a clean "first this, then this" story? Example: you cannot draft the brief before the research is done.
☐ Yes, strong order dependency ☐ No, several pieces could start at the same time
Evidence (one line):
Does the decomposition itself need runtime judgment?
Do you already know what the subtasks are and how many there will be — or does the right decomposition depend on what the input actually is?
☐ Decomposition is fixed (I know the stages) ☐ Decomposition needs runtime judgment (varies by input)
Evidence (one line):
Shape: A → B → C.
Order dependency + fixed decomposition.
Shape: input → W1/W2/W3 → combiner.
No order dependency + fixed decomposition (same input, several outputs).
Shape: supervisor decides decomposition, spawns workers.
Decomposition needs runtime judgment. Most powerful; highest runaway risk. When in doubt, pick sequential instead.
Shape justification (one sentence)
Copy this sentence into blueprint.md under Shape.
Part 3 — Agent sketch
Name each agent and its one-sentence responsibility. Aim for two or three agents; four is the soft ceiling for Module 8. Each agent's scope will tighten once you write the handoff contracts in Lesson 8.2.
Agent 1
Name (kebab-case):
Responsibility (one sentence):
Input it starts from — Output it produces:
Agent 2
Name (kebab-case):
Responsibility (one sentence):
Input it reads — Output it produces:
Agent 3 (optional)
Name (kebab-case):
Responsibility (one sentence):
Input it reads — Output it produces:
Agent 4 (only if necessary — justify)
Four agents is the ceiling. If you reach for a fourth, write one sentence explaining why three will not suffice.
Part 4 — Pipeline input/output
What kicks off the pipeline?
A topic the student types? A scheduled fire-at-6am trigger? A file appearing in a folder? Name the concrete start signal.
What is the final output?
The artifact a human reads (or the tool the pipeline feeds). Name the file path, format, and roughly what the student does with it.
Part 5 — Depth and fan-out rail declaration
Every Module 8 pipeline operates under explicit rails. Write them down before you build; re-check them in Lesson 8.5.
Depth cap: ☐ 3 (module default) ☐ 2 (tighter, usually better)
Fan-out cap: ☐ 4 (module default) ☐ _______ (custom — write why)
Retry cap per stage: ☐ 0 (stop on first failure) ☐ 1 (one tighter retry, then stop)
If you write anything other than these defaults, justify in one line:
Part 6 — Ready-to-blueprint checklist
- Part 1 gate: all four one-agent-too-many questions answered yes, with evidence written.
- Part 2: shape picked with one-sentence justification from the two-question test.
- Part 3: two to three agents sketched, each with a one-sentence responsibility and named input/output.
- Part 4: pipeline start signal and final output named.
- Part 5: depth, fan-out, and retry caps written down.
- Goal is in a form you could hand to a classmate and they could guess the pipeline shape from reading it.
This worksheet accompanies Lesson 8.1 of AI Architect Academy. The two-question shape test, one-agent-too-many test, three orchestration shapes, and depth/fan-out rail are all concept. Next: the Handoff Contract Template (Lesson 8.2) turns the agent sketch into named interfaces.