Claude Code · Power User Curriculum

Orchestration Mastery:
From Zero to Multi-Repo Infrastructure

A progressive curriculum for Claude Code power users

Extracted from 208 sessions · 432 hours · 469 agent dispatches — April 2026

208 Sessions

469 Agent dispatches

89 Commits / 18 days

5 Mastery levels

1 The Mental Model

Before touching a tool, internalize four ideas. Everything else follows from these.

Work as a DAG, not a task list

Every non-trivial project is a directed acyclic graph of dependencies. A task list is flat — a DAG is structural. The shape of the graph determines what can run in parallel and what must wait. Most orchestration mistakes reduce to ignoring the graph.

Example DAG from a real 18-day sprint:

Gateway Wave 1 (foundation)
├── Wave 2A (middleware)  ←── parallel with ──→  VPS Deploy
│   ├── Wave 2B (persistence)                     │
│   └── Wave 2C (RAG pipeline)                    │
│                                                  ↓
└────────────────────────────── Atlas Commission ──┘
                                     │
                                     ↓
                              PDI Data Pipeline
                                     │
                                     ↓
                            Ecosystem Convergence

Wave 2A and VPS Deploy have no dependency on each other — they can run in parallel agents simultaneously. Atlas Commission depends on both completing. This distinction — which things block which — is the core decision in every dispatch.

ⓘ Rule: identify blocking relationships first. Then dispatch everything that has no unmet dependency.

The Sonnet / Opus split — 80 / 20

Not every task deserves the same model. Routing is a first-class decision.

Sonnet (80%)	Opus (20%)
Parsing, templating, bulk normalization	Architecture decisions, synthesis
Implementation tracks from a spec	Convergence gates and trajectory evaluation
Audit sweeps, skill upgrades	Cross-repo strategy sessions
Test generation, code review	Decisions that fork the product direction
Data pipeline scripts	When Sonnet has failed twice on the same task

✓ Codify the split in your SKILL.md frontmatter: model: sonnet or model: opus. Default to Sonnet. Escalate deliberately.

Seeds as organizational memory

A seed is a compressed pattern extracted from friction. The lifecycle:

# Lifecycle of a seed
Friction   →  you hit the same mistake twice
Pattern    →  you name the root cause and the fix
Seed       →  you write it as a portable lesson (200 chars max headline)
Skill      →  optional: automate the fix as a reusable skill command

# Target: 60%+ friction-to-seed extraction rate
# Every seed prevents the same mistake in every future session

Seeds are stored in ~/.claude/projects/memory/, indexed in MEMORY.md. Sub-agents start cold — they do NOT inherit your session context. Seeds bridge that gap.

ⓘ The question after every friction event: "Is this worth a seed?" If you had to look it up or figure it out again, the answer is yes.

The compilation gate — mechanical trust, not aspirational compliance

Policies without enforcement drift to 0% compliance. Every best practice you write in a doc and never verify has an effective compliance rate of zero.

The compilation gate is the antidote: before any commit, before marking any task done, the build must pass. This is not a suggestion — it is a hook in settings.json that blocks the action.

# Go stack
go build ./...   # must be clean
go test ./...    # must pass

# Rust stack
cargo check     # type-checks without full compile
cargo test      # full suite

# TypeScript / Svelte 5
tsc --noEmit    # type-check only
npx svelte-check

For parallel agent tracks: every agent must pass its own compilation gate before the main thread integrates. No exceptions. One broken track poisons the merge.

⚠ Never skip — --no-verify and --no-gpg-sign are off-limits unless the user explicitly requests it.

2 The Five Levels

Each level unlocks a new leverage multiplier. Master each before climbing.

Level 0 — Foundation

Foundation: Infrastructure Before Work

CLAUDE.md TodoWrite Root-cause debugging Build gate

CLAUDE.md is your constitution. It is the first file read in every session. It encodes: language defaults, frontend conventions, debugging protocol, architecture patterns, and project references. If it's wrong or stale, every session builds on a broken foundation.

TodoWrite gives granular, session-visible tracking. One todo per deliverable — not per area. "Fix auth bug" is an area. "Fix missing JWT expiry check in middleware/auth.go:47" is a deliverable.

Root-cause debugging protocol: before writing any fix, trace to the originating line. Check config files first (settings.json, .env, wrangler.toml) before debugging code. At least 3 sessions per operator have been wasted debugging code when the problem was a stale URL.

Exercise

Create or audit your CLAUDE.md. Run your full build suite from scratch. Verify it passes clean before doing any other work in the repo.

Anti-pattern

"Write once, never update" — CLAUDE.md written at repo creation and never touched again. A stale constitution is worse than none: it actively misdirects agents.

📄 Key command: go build ./... (or stack equivalent)

Level 1 — Single-Repo Mastery

Single-Repo Mastery: Clean Solo Work

Compilation gate One todo per deliverable Seed extraction habit

At Level 1, every change follows a gate: implement → build → test → commit. No exceptions. The discipline here is the foundation for parallel work later — you cannot reliably split work you cannot reliably finish alone.

Seed extraction habit: after every session where you hit friction, write one seed. Keep a running extraction rate. Target 60%+. Low extraction rate means you're paying the same cost repeatedly across sessions.

Exercise

Find a failing test suite. Create one todo per failing test. Fix each in order. Verify the full suite passes before marking any done. Extract one seed from whatever slowed you down.

Anti-pattern

Marking a task done before the full test suite passes. "It works for the case I tested" is not done. Full suite, no exceptions.

📄 Reference: seed_compilation_as_contract

Level 2 — Multi-Agent Dispatch

Multi-Agent Dispatch: Parallel Execution

Plan → Dispatch → Verify → Resolve → Report File manifests False completion trap

The dispatch cycle has five phases. Skipping any one causes the failure mode named after it:

1. Plan     — identify files; assign non-overlapping manifests per agent
2. Dispatch — run agents in parallel, each with explicit file manifest
3. Verify   — run git status + grep for expected changes (never trust self-reports)
4. Resolve  — fix conflicts, failed builds, missed writes
5. Report   — final go build ./... + go test ./... before closing task

File manifests prevent merge conflicts at zero cost. Each agent gets an explicit list of files it may write. No file appears in two manifests. This is the zero-overlap guarantee.

Agent false completion: agents report "complete" without persisting writes. Always verify with git status and grep for expected output. Agent "done" is not done until independently verified.

⚠ Never use isolation: "worktree" for agents that write files. The worktree is auto-cleaned and all writes are silently discarded.

Exercise

Pick a structural change touching 5+ files. Write explicit file manifests for 3 parallel agents. Dispatch them. Run a verification sweep on each agent's output independently. Fix anything that didn't land.

Anti-pattern

Dispatching without file manifests (overlap causes merge conflicts) or trusting agent self-reports (silent write failure is common).

📄 Reference: parallel-dispatch skill · seed_zero_overlap_agent_swarm

Level 3 — Multi-Repo Orchestration

Multi-Repo Orchestration: Cross-Boundary Dependency

DAG sequencing Interface contracts first Cross-repo gates Convergence gate

At Level 3, dependencies span repositories. The same DAG thinking applies, but now "build Wave 2A before Wave 2B" means the provider repo must have stable interfaces before the consumer repo can start.

Interface contracts before implementation is the rule. Define the API surface (types, endpoints, function signatures) in a shared contract before any agent writes code against it. Without a contract, consumer work is written against a moving target.

Convergence gate every 3–4 sessions. After 4 sessions of parallel work, accumulated drift — stale references, version mismatches, undiscovered gaps — exceeds the cost of a convergence pass. Run one. YELLOW signal: 10+ dirty files or 4+ sessions without a gate.

# Convergence gate checklist
go build ./...          # every sub-repo
go test ./...           # every sub-repo
git status              # no untracked noise
grep -r "TODO\|FIXME\|HACK" # triage leftovers
# cross-repo: verify shared interface versions match

Exercise

Take two repos (API + client). Define the interface contract first (endpoint list + types). Then dispatch parallel agents — one per repo — to implement against the contract. Run cross-repo integration tests. Perform a convergence pass.

Anti-pattern

Building the consumer before the provider interface is stable. Every consumer line written against an unstable provider is technical debt that arrives as a build failure at integration time.

📄 Reference: parallel-tracks skill · seed_convergence_gate

Level 4 — Ecosystem Governance

Ecosystem Governance: The Long Game

Seeds as institutional memory Tiered authority Scheduled maintenance Friction-to-seed 60%+

Level 4 is about the infrastructure that outlasts any individual session. Skills, seeds, and governance structures that make every future session faster than the last.

Tiered authority: canonical (source of truth) > distribution (curated copy) > community (user-submitted). Every skill, seed, and config lives at exactly one canonical location. Distribution copies are managed, not edited. Community contributions are audited before promotion.

Scheduled maintenance: convergence gates, supply chain syncs, freshness checks. These are not optional. They run on a cron. Governance without scheduling is governance in theory only.

# Scheduled maintenance (examples)
midday-memory-tending    MWF 2:17pm     # compress + index seeds
weekly-supply-chain-sync Sun 10:42am    # audit canonical vs distribution
cwd-data-freshness-check Wed 11:23am    # verify data pipeline freshness

Exercise

Audit 5 repos against their canonical versions. Create a convergence ledger. Extract one cross-repo seed from the friction you find. Set up at least one scheduled maintenance task.

Anti-pattern

Treating governance as optional — "I'll write the seeds later," "I'll do a convergence pass when things slow down." Things never slow down. Governance that isn't scheduled doesn't happen.

📄 Reference: seed_tiered_skill_authority · seed_audit_before_sync

3 First Session Script

Eight steps. Do them in this order. The order is load-bearing.

Read or create CLAUDE.md

cat CLAUDE.md # or create from scratch

Why: this is your agent's instruction set. Every agent in this session — including the ones you dispatch — starts cold and reads this file. If it's missing or stale, you're orchestrating with faulty instructions from the first tool call.

Run the full build and test suite

go build ./... && go test ./...

Why: you need a known-good baseline. Any existing failures are not yours — but if you skip this step, you will eventually claim credit for fixing something you didn't break and get blamed for something you didn't introduce.

Pick a 3–5 file task

git log --oneline -10 # understand what's happened recently

Why: 3–5 files is the sweet spot for learning dispatch. Small enough to complete in one session. Large enough to be worth splitting into parallel agents. One file is too small; ten files is too large to verify cleanly on your first try.

Write a TodoWrite plan

# One todo per file, not per "area"

Why: TodoWrite creates session-visible tracking. One todo per concrete deliverable forces you to decompose the task before touching code. The plan also becomes the file manifest for your agents in step 6.

Complete the task yourself first

go build ./... && go test ./... # after each file

Why: you cannot write a good agent dispatch prompt for work you don't understand. Do the task once. Note where you hit friction. This knowledge goes into the dispatch prompt and, later, into a seed.

Reset and redo with 2–3 parallel agents

git stash # reset to baseline; dispatch agents with file manifests

Why: this is where you learn whether your plan was good enough. Agents will expose ambiguities in your spec. Run the verification sweep (step 3 of the dispatch cycle) independently on each agent's output. Don't trust self-reports.

Write one seed

# seed_[descriptive-name].md in ~/.claude/projects/memory/

Why: every session should leave the system smarter. The seed you write tonight prevents the same friction in every future session. Aim for 200 chars headline max. Update MEMORY.md index. Sub-agents in future sessions will have this knowledge.

Commit with a conventional prefix

git commit -m "feat: ..." # or fix: / chore: / docs:

Why: conventional commits make the log machine-readable. They also force you to classify the work — is this a feature, a fix, or maintenance? That classification affects whether it goes in a release note and how agents interpret recent history.

4 Mechanical Enforcement

Policies without hooks have a compliance rate of zero. These hooks make the levels self-enforcing.

Hook Lifecycle

Claude Code hooks run at defined lifecycle points. The critical distinction: PreToolUse blocks (exit 2 prevents the action), PostToolUse informs (the write already happened, exit 2 has no blocking effect).

Hook Event	Fires When	Can Block?	Use For
`PreToolUse`	Before any tool call runs	Yes (exit 2)	destructive-guard, force-push-guard, pre-commit build gate
`PostToolUse`	After tool call completes	No	go-build-check, go-test-check, svelte5-lint, rust-check, ts-check, skill-validate
`UserPromptSubmit`	Before processing user message	Yes (exit 2)	context-inject (load seeds/MEMORY.md), drift-detector (convergence signal)
`Notification`	On agent events, completions	No	alerting, logging to SQLite, dashboard updates

⚠ PostToolUse fires AFTER the write is already on disk. To prevent a bad write, you must use PreToolUse. PostToolUse is only for reporting and side-effects after the fact.

Example: Pre-Commit Build Gate

This hook fires on every Bash tool call and blocks git commit if the build is not clean:

#!/usr/bin/env bash
# ~/.claude/hooks/pre-commit-build-gate.sh
# Registered as: PreToolUse — Bash

# Only act on git commit calls
if ! echo "$CLAUDE_TOOL_INPUT" | grep -q "git commit"; then
  exit 0
fi

# Find go.mod root and run build
ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
if [ -f "$ROOT/go.mod" ]; then
  if ! go build -C "$ROOT" ./... 2&1; then
    echo "[BLOCKED] go build failed — fix before committing" >&2
    exit 2   # exit 2 blocks the commit
  fi
fi

exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "~/.claude/hooks/pre-commit-build-gate.sh"
        }]
      }
    ]
  }
}

✓ The drift detector runs on UserPromptSubmit: it counts dirty files and session count, then emits YELLOW or RED to signal when a convergence gate is overdue.

5 Pattern Reference

Twelve orchestration patterns. Each has a topology, a trigger condition, and a typical agent count.

Pattern	Topology	When to Use	Agents
Pipeline	A → B → C → D	Sequential data transformation where each stage produces input for the next	1/stage
Map-Reduce	1 → N (map) → 1 (reduce)	Same operation applied to many independent items, results aggregated	N+1
Hierarchical	Orchestrator → sub-agents → leaf workers	Large specs decomposed by domain, each domain has its own agent tree	3–20
Swarm	N parallel peers, shared state	Many independent files needing the same transformation simultaneously	5–30
Generator-Critic	Generator → Critic → revise loop	Quality-sensitive output where first pass is insufficient (specs, copy, architecture)	2
Adversarial	Two agents with opposing goals	Security review, argument stress-testing, red-team scenarios	2
Jury	N independent agents → synthesizer	High-stakes decisions requiring independent perspectives before synthesis	3–7
Blackboard	Shared write surface, specialists read/write	Multi-domain problem where specialists contribute fragments that accumulate	3–10
Chain-of-Responsibility	Request passed until handled	Routing requests to the first capable handler; fallback chains	2–5
Circuit-Breaker	Monitored pipeline with trip condition	Long-running pipelines where a mid-stage failure should halt downstream work	1+monitor
Event-Driven	Event bus → multiple subscribers	Reactive workflows: file change triggers lint + test + deploy fan-out	N subscribers
Meta-Pattern Selector	Classifier → routes to appropriate pattern	When task type is unknown upfront; classifier determines which pattern to use	1+chosen

ⓘ Most real tasks use Pattern Composition: a Hierarchical orchestrator dispatching Swarms within each domain, with a Generator-Critic pass on the final output. The catalog is a vocabulary, not a constraint.

6 Anti-Pattern Hall of Shame

Ten mistakes. All documented from real sessions. All painful. All avoidable.

#1 Worktree Isolation Trap

The mistake

Using isolation: "worktree" for agents that write implementation files

What happens

The worktree is auto-cleaned after the agent completes. All writes are silently discarded. Agent reports "done." Nothing changed in your repo.

The fix

Never use worktree isolation for implementation work. Use it only for read-only analysis. Verify with git status after every agent.

#2 Agent False Completion

The mistake

Trusting an agent's "I've completed the task" self-report without verification

What happens

Agent wrote to a temp path, forgot to save, or had a permission error. Files are unchanged. You proceed with integration on ghost work.

The fix

Always run git status + grep for expected output after every agent. Agent "done" is not done until independently verified.

#3 Shallow First-Pass Fixes

The mistake

Fixing the symptom (error message, failing assertion) without tracing to the root cause

What happens

The upstream condition that caused the symptom persists. The bug reappears in a different form, often 2–3 sessions later. The original fix is now part of the confusion.

The fix

Before writing any fix: identify the exact line/config where the problem originates. When a fix doesn't hold, ask "what upstream condition allows this state?"

#4 Config-Before-Code Miss

The mistake

Debugging code when the problem is a stale URL, missing env key, or wrong port in config

What happens

3+ hours spent tracing code logic. Root cause: settings.json had the wrong port. .env had an expired key. wrangler.toml had a stale worker URL.

The fix

For any connectivity/provider error: check settings.json, .env, wrangler.toml, and config files BEFORE debugging code. This costs 2 minutes. The alternative costs hours.

#5 Aspirational Without Mechanical

The mistake

Writing a policy in CLAUDE.md or a doc with no enforcement hook

What happens

Compliance starts at 100% the day you write it, drifts to 0% over 3–4 sessions. Sub-agents never see it. The policy exists only in the markdown file.

The fix

Every behavioral constraint needs a hook. PreToolUse for blocking, PostToolUse for informing. If you can't hook it, it's a suggestion, not a policy.

#6 Dispatching Without a Plan

The mistake

Sending agents without file manifests or explicit scope boundaries

What happens

Two agents write to the same file. Merge conflict. Or agents overlap in scope, produce duplicate implementations, and you spend the verification phase resolving the chaos.

The fix

Every dispatch starts with a file manifest. One file, one agent. No overlap. The plan takes 10 minutes. The merge conflict resolution takes 2 hours.

#7 Building Consumer Before Provider Is Stable

The mistake

Starting client/consumer implementation before provider API surface is finalized

What happens

Provider changes its interface. Every consumer call site must be updated. The work done against the unstable interface is thrown away or becomes rework.

The fix

Define the interface contract (types, endpoint signatures) before dispatching any consumer agents. The contract is the blocking dependency. Consumer work starts after the contract is frozen.

#8 Marking Done Before Full Suite Passes

The mistake

"It works for the case I tested" — closing a task before running the full test suite

What happens

A regression in an adjacent test surfaces in the next session, attributed to your change. The real failure was not running the suite. The apparent failure is "something broke."

The fix

The task is not done until go test ./... (or equivalent) passes green. No exceptions. This is the compilation gate in practice.

#9 Skipping Convergence

The mistake

"I'll do a convergence pass when things slow down" — indefinitely deferring the gate

What happens

After 6+ sessions, accumulated drift (version mismatches, stale references, undiscovered gaps) exceeds the cost of a convergence pass by 5x. The "slow down" never comes.

The fix

Convergence gate every 3–4 sessions, scheduled, non-negotiable. The drift-detector hook signals YELLOW at 4 sessions, RED at 6.

#10 Trusting Self-Reports

The mistake

Accepting "all agents complete" as the final verification step after a parallel dispatch

What happens

One agent hit an edge case and silently wrote a partial result. The full-workspace build catches it. You shipped incomplete work from an integration that "passed."

The fix

After ALL agents report completion: run go build ./..., go test ./..., and grep for expected output files. Agent "done" is not done until independently verified.