D1 Orchestration — Splitting The CI Migration Across Subagents

Learning objective

(Bloom's: Create) Design and run a multi-agent orchestration plan for the payments-service CI migration — which agent owns which stage, at which invocation guarantee, in which isolation — where every handoff is a durable artifact "readable by a cold reader with no session context" and in-progress state is "engineered to survive session death — durable artifacts committed before stepping away, successor briefs written for the thread that will resume the work" — AIHC.2.D1 (Orchestration, amended [v03], quoted).

Work at hand: everything so far ran through one session at a time — you, plus one reviewer subagent, serially. The migration's remaining work doesn't fit that shape: the CI config rewrite, the ledger-migration review, and the item-2 endpoint audit are three workstreams with different owners-in-waiting. Your profile says band 1 on D1 — this is the arc's deliberate stretch lesson, and it stands on every artifact you've built: contracts (L2), scoped agents (L3), lanes (L7), records (L8), governance (L9), metrics (L10).

SSD cycle 1 — an orchestration is owners × artifacts, not a pile of agents

• SAY: Adding agents multiplies context loss unless each stage has exactly one owner and one output artifact. The doc-set's own division of labor is the starting inventory — §8: built-in Explore ("read-only, fast codebase search"), Plan ("read-only, research during plan mode"), general-purpose ("all tools, complex multi-step tasks"), plus your custom reviewer; and §8's when-to-delegate rule: reach for a subagent when the work "would flood your main conversation with search results, logs, or file contents you won't reference again" — the subagent works in its own context and "returns only the summary." One caution the freeze disclosure forces: nested-subagent mechanics sit in the unread ~25% of the source, so this plan keeps YOU as the only orchestrator — no agent spawns agents here.
• SEE: The migration, drawn as a pipeline table (owners from the frozen inventory, artifacts from your own formats):

One §8 fact shapes row 1: "Explore and Plan are the two exceptions that skip loading CLAUDE.md" — your L6 log already learned this the hard way, so the recon contract (not CLAUDE.md) must carry any rule the recon needs. - DO: Redraw the table for your real remaining migration backlog (your items, not these five) — every row gets one owner, one §8-rule justification, one artifact. Then apply your L3 2×2 to the full table and mark any row whose blast radius means it must NOT run in parallel with anything (the ledger migration should earn that mark on its own).

SSD cycle 2 — invocation is a guarantee level, not a phrasing choice

• SAY: §8 gives three escalating ways to make an agent run: natural language ("Claude decides whether to delegate"), @-mention ("guarantees that specific subagent runs"), and claude --agent <name> ("the whole session's main thread becomes that subagent"). Under-specifying the invocation re-introduces the wish-vs-contract gap from L2, one level up: "use a subagent to check the CI config" leaves the owner to chance, and your plan just made ownership load-bearing. There's also a collision rule to design against — §8: when subagents share a name, "Managed settings > --agents flag > .claude/agents/ > ~/.claude/agents/ > plugin" — project scope beats user scope.
• SEE: Row-by-row invocation lines for cycle 1's table, guarantee level chosen deliberately (described): recon claude session → "use a subagent to investigate…" is NOT enough here; @Explore guarantees the read-only owner (§3's delegate-research recipe, hardened) first-pass @payments-first-pass-reviewer with the L2 contract (named guarantee) CI rewrite claude --agent general-purpose in its own worktree (whole-session owner — nothing else in that terminal can be blamed)
• DO: Write the real invocation line for every row of your table, and for each, one clause naming why that guarantee level (what goes wrong at the level below it?). Check one collision while you're here: ls .claude/agents/ ~/.claude/agents/ (described) — if any name exists in both scopes, record which one §8 says wins and whether that's the one you meant.

SSD cycle 3 — parallel needs isolation: worktrees, and what they share

• SAY: Two workstreams in one working directory collide at the filesystem long before they collide at the merge. §3: "claude --worktree feature-auth creates an isolated git worktree/branch so two terminals don't collide; repo needs ≥1 commit first." And one subtlety worth designing around rather than discovering: §4 — auto memory is "per-repository, shared across worktrees" — so what Claude learned about your repo travels between your parallel terminals even though files don't. Isolation is per-track; learning is repo-wide. Both are frozen facts; your plan should exploit the second, not be surprised by it.
• SEE: Your two-terminal layout, with the L3 mark from cycle 1 honored: terminal A claude --worktree ci-config-rewrite (general-purpose owner, L7 lanes live) terminal B claude --worktree endpoint-audit (Explore recon → your judgment) NOT RUNNING ledger migration (2×2-marked serial; runs alone, in plan mode per L7's mode lanes, only after A and B merge)
• DO: Stand up your real parallel layout (two worktrees max — a first orchestration that needs three is two orchestrations), confirm the ≥1-commit precondition, and write the serialization note for every 2×2-marked row: what must finish, and what evidence of finishing (which artifact, per cycle 1) unblocks it.

SSD cycle 4 — the handoff artifact: your cold reader is future-you, or not-you

• SAY: The amended band-2 expectation is blunt: handoffs are artifacts "readable by a cold reader with no session context." The test is operational — could a teammate (or a fresh session, or you after a weekend) resume from the artifact alone? §3's resume machinery (claude --continue, --resume, /resume) recovers conversations, and your L8 --from-pr link recovers the session behind a PR — but resume-ability is not cold-readability: a conversation is evidence, not a brief. The handoff artifact is written for the reader who has neither.
• SEE: The recon handoff, done badly and done to standard: ``` BAD "Explore finished — findings in the session above." (reader must replay you)

GOOD docs/handoffs/ci-recon.md stage: CI recon owner: Explore date/commit: contract: docs/contracts/ci-recon-contract.md findings: 3 bullet claims, each with file:line receipts (L5 rule: claims carry checks) open questions: 2, each tagged BLOCKS-REWRITE or DOESN'T-BLOCK next thread starts by: verifying receipt #2, then rewrite stage may open `` Six fields, no narrative. *(A Fania chart works because any sub who can read can sit in tonight — the arrangement doesn't live in the bandleader's head, it lives on the stand.)* - **DO:** Write your real handoff template (≤6 fields) intodocs/handoffs/README.md, then produce the first real instance from your actual recon stage output. Cold-read test it the honest way: hand it to a freshclaudesession (no--continue` — cold is the point) and ask what it would do next; if the answer requires information the artifact doesn't carry, the artifact failed — fix it, not the reader.

SSD cycle 5 — surviving session death is a design input, not an apology

• SAY: The amendment's second clause: "durable artifacts committed before stepping away, successor briefs written for the thread that will resume the work." Orchestration multiplies in-flight state, which multiplies what an interruption can vaporize. The rule is mechanical: no stage is "in progress" unless its current truth is committed and its successor brief exists. Not because crashes are likely — because a plan that requires luck isn't a plan (X6: design for the reversible resume, not the heroic reconstruction).
• SEE: The step-away ritual, as three lines appended to your handoff template: on stepping away: commit WIP to the stage's worktree branch (tagged wip/<stage>) update the stage's handoff artifact: status line + next-action line total cost: ~3 minutes; total protection: the whole stage
• DO: Run the ritual for real, mid-work, today — step away from one live stage on purpose, then resume it in a fresh session from the brief alone and log (one line, in docs/review-metrics.md) what the brief was missing. That miss-list is how the template earns its next revision.

Independent at-bat

Fully unscaffolded — the orchestrated pass: run one complete migration stage end-to-end through your own plan — invocation at the chosen guarantee level, in its worktree, under its contract, first-pass and verification gates per your table, handoff artifact produced and cold-read-tested, step-away ritual exercised at least once mid-stage. Success is not the stage finishing; success is the artifact trail — a teammate reading only docs/handoffs/ can reconstruct who did what, what was verified, and what runs next. (Your L10 measurement applies: log the stage's minutes and any defects caught per layer — orchestration that can't show up in the metrics is theater.)

Exit ticket

(Graded against your pipeline table, handoff artifacts, and the cited doc-set sections — never against how coordinated the terminals looked.)

1. (Remember) Name the three invocation guarantee levels from §8 and what each one guarantees.
2. (Understand) Per §8 and your L6 log, why must the recon stage's rules travel in its contract rather than in CLAUDE.md — and per §4, what does travel between your parallel worktrees anyway?
3. (Apply) A new stage appears: "profile the test suite for the 5 slowest tests" — verbose, read-only, self-contained. Write its full plan row: owner + §8 justification, invocation line with guarantee level, isolation, and handoff artifact fields.
4. (Analyze) Your CI-rewrite session dies overnight, mid-stage. Trace the two recovery paths — §3 resume machinery vs. your cycle-5 ritual's committed-WIP-plus-brief — and state what each one alone recovers, and which one your teammate could use.
5. (Create — objective level) Your plan currently keeps you as sole orchestrator (the nested-subagent tail is unread — a freeze fact, not a law of nature). Design the one-paragraph revision you'd propose if a future doc-set freeze covers nesting: which single stage would you first hand to a sub-orchestrator, what new handoff artifact appears, and which of your existing gates must NOT move — with a one-line reason each.

ledger_write

ledger_write:
  learner_id: L1-DEV-MAYA
  lesson_id: L1-dev-maya-11-d1-orchestration
  anchors: [AIHC.2.D1]
  bloom_reached: Create
  exit_ticket_score: ""
  auto_score: ""
  self_score: ""
  calibration_gap: " — computed once Maya's self_score exists"
  starting_mastery:
    AIHC.1.D1: 0.30  # profiled band 1 — this lesson is the deliberate band-2 stretch
  journal_prompt: >
    Cycle 4's cold-read test failed on something (they always do, first time). Write what
    the fresh session couldn't figure out from your artifact, and the sentence you added to
    fix it. Then the real question: how much of your daily work currently lives in places
    that would fail that same test?
  structure_used: PBL
  referents_used: [salsa-fania-chart-on-the-stand]
  next_lesson_seed: >
    Lesson 12 closes the arc where the JD closes: the platform will move under all of this.
    D2 regeneration — an artifact inventory, reading release deltas, a freshness beat, and
    the capstone drill: a simulated Claude Code update she re-verifies against alone.

RUBRIC SELF-AUDIT

Escalation: all load-bearing indicators PASS → auto-ships (Playbook §5, AIHC X2/B3).