Pipeline Planner
Save this as: /capstone/pipeline-v1-draft/blueprint.md (or print and keep alongside).
Fill order: Parts 1–5 during Lesson 8.3 (Claude Code CLI build). Parts 6–7 during Lesson 8.4 (Cowork-tab build + path pick). Handoff contracts for Part 4 come from the Handoff Contract Template worksheet — copy one filled sheet per handoff into this file.
The parent session is bookkeeping, not reasoning. Tool allowlists are runaway prevention. A pipeline you cannot read in five minutes is a pipeline you cannot debug in five hours.
Pick the frozen path by goal shape, not by which path was easier. On-demand + varying input → Claude Code CLI. Fixed schedule + fixed input shape → Cowork tab.
Part 1 — Goal and shape (from Lesson 8.1)
Goal
One sentence. Copy from the Orchestration Shape Picker.
Shape and justification
☐ Sequential ☐ Parallel ☐ Hierarchical
One-sentence justification from the two-question test:
Part 2 — Agents (Claude Code CLI path)
Fill one row per agent. The agent folder goes under .claude/subagents/<name>/. Name is kebab-case. Model is "cloud-default" or the explicit family. Tools is the minimum allowlist — a drafter does not need web_search; a reviewer does not need write access outside its own stage folder.
| Name (kebab-case) | One-sentence responsibility | Model | Tool allowlist (minimum) |
|---|---|---|---|
Part 3 — Shared-state folder convention
Every pipeline writes to /pipeline/<name>/<YYYY-MM-DD>/<stage>/. Status folder is always 00-status/ so it sorts to the top. Stage folders are numbered in pipeline order; filenames inside each stage match the output shape in the handoff contract exactly.
My pipeline name (kebab-case):
My stage folders (numbered):
Part 4 — Handoffs (contracts)
Count the handoffs (N − 1 for sequential; 2 for parallel; one per supervisor-worker edge for hierarchical). Copy one filled Handoff Contract Template sheet per handoff into the blueprint. Do not write a contract here from scratch — use the dedicated template so every field is present.
Handoff count:
Contract sheets filed: ☐ #1 ☐ #2 ☐ #3 ☐ #4
Output-matches-next-input cross-check completed: ☐ Yes (all contracts tight)
Part 5 — Parent-session orchestrator prompt (Claude Code CLI)
The parent-session prompt is procedural and short. It reads the blueprint, dispatches each subagent in order, verifies each output, and stops on failure. No "be smart" language. One step per stage, plus verification. Save at pipeline/<name>/orchestrator-prompt.md.
Orchestrator-prompt checklist (mark each as written)
- Opening line names pipeline name, date, topic/input, and shared-state folder.
- One numbered step per stage: Dispatch <subagent> via Task tool with tightly-scoped invocation prompt.
- One numbered verification step per stage: checks file exists, checks success criteria from the handoff contract, stops on failure.
- Final step writes 00-status/pipeline-complete.md with stages completed, wall-clock, and token-cost estimate.
- Zero "be smart about this" language. Zero invitations to invoke other subagents. Zero unbounded retries.
Part 6 — Cowork-tab scheduled-task version (Lesson 8.4)
One row per stage. Each Cowork-tab scheduled task fires on its own clock, reads from the previous stage's folder, writes to its own stage folder, and self-verifies (reads the file it just wrote and checks it against the handoff contract before declaring success). The coordination is by convention: staggered schedules + shared folders + self-verifying stages.
| Scheduled task (kebab-case) | Fires at | Reads from | Writes to | Self-verify (success criteria) |
|---|---|---|---|---|
Stagger rule: each task fires at least N minutes after the previous stage's expected completion time, where N is the upstream stage's worst-case wall-clock plus a safety buffer. If a stage's self-verify fails, the task writes 00-status/<stage>-failed.md and stops — the downstream task will see the failure file and exit without producing output.
Part 7 — Pick the frozen path
After both paths have run at least once end-to-end (or failed meaningfully), pick one as the frozen capstone. The other lives as the sibling learning trace under pipeline-v1-draft/<other-path>-sibling/.
Pick this when: pipeline is on-demand (the student types a topic); input shape varies across runs; student wants a live trace and immediate feedback; hierarchical shape needed.
☐ Picked as frozen path
Pick this when: pipeline runs on a fixed schedule; input shape is fixed; student wants the pipeline to run without them being present (daily briefing, weekly report); hierarchical shape is not needed.
☐ Picked as frozen path
Path justification (one paragraph)
Name the goal property that drove the pick. Frozen path is goal-driven, not effort-driven. If the goal truly fits both and you feel ambivalent, pick the Claude Code CLI path.
Part 8 — Budget and kill switch (placeholders for Lesson 8.5)
Leave the following as placeholders here; fill them in after running the pre-flight cost estimate (see the Pre-Flight Cost Estimate worksheet) and practicing the kill switch (Lesson 8.5, Content Block 3).
Pre-flight cost estimate (from Lesson 8.5 worksheet)
Per-invocation estimated cost:
Per-invocation estimated wall-clock:
Per-run budget ceiling (stop if exceeded):
Kill switch (from Lesson 8.5 blueprint)
Command or clicks that stop the pipeline:
Observable confirmation (what tells me it actually stopped):
Recovery (how I restart after a safe stop):
☐ Kill switch practiced once before freeze.
Part 9 — Next review
A frozen pipeline gets a scheduled review. Set a date no more than 90 days from freeze. On the review date, re-run the pre-flight estimate, re-run the runaway audit, and confirm the pipeline still does what the blueprint says.
Freeze date: Next review date:
Part 10 — Ready-to-freeze checklist
- Parts 1–5 completed during Lesson 8.3; two captured Claude Code traces saved under /capstone/pipeline-v1-draft/traces/claude-code/.
- Part 6 completed during Lesson 8.4; two captured Cowork-tab traces saved under /capstone/pipeline-v1-draft/traces/cowork/.
- Part 7 path picked with one-paragraph justification grounded in goal shape.
- Part 8 pre-flight estimate and kill switch filled in from the Lesson 8.5 worksheets.
- Runaway audit (nine checks) all pass; see the Runaway Audit worksheet.
- before-after.md block exists for both paths, showing the invocation-1 → invocation-2 tightening.
- Next review date written in Part 9.
- On freeze: copy /capstone/pipeline-v1-draft/<picked>/ to /capstone/pipeline-v1/; rename the un-picked path to /capstone/pipeline-v1-draft/<other>-sibling/.
This worksheet accompanies Lessons 8.3 and 8.4 of AI Architect Academy. Part 3 (shared-state folder convention), Part 5 (parent-session orchestrator discipline), Part 6 (self-verifying Cowork-tab stages), and Part 7 (path pick by goal shape) are the load-bearing concept concepts. Exact file layout and command syntax live in /recipe-book/building-a-subagent-pipeline-in-claude-code.md and /recipe-book/chaining-scheduled-tasks-in-cowork-tab.md.