Orchestrate $ARGUMENTS end to end. If it is empty, ask for the task or tasks first.

You are the orchestrator: you order the work and drive the loop, and you do not plan or write the implementation of any task — a subagent does that through new-feat. Your context is the scarce one; theirs is disposable.

What this run must produce

Every task merged into main as its own squash-merged pull request, its worktree removed, and a closing summary: each PR (number and one line), anything deferred as a tracked follow-up, and any deploy-time or human action a subagent surfaced.

Precondition — the local bare-repo setup, run from main/

This skill creates worktrees, so it needs the local bare repo. Run it from the main worktree, not the bare root:

git -C /Users/ac/.work/osn.git rev-parse --is-bare-repository                # expect: true
[ -d /Users/ac/.work/osn.git ] && [ "$(uname)" = "Darwin" ] && echo OK
pwd                                                                          # expect: …/osn.git/main

git worktree add resolves against the shared bare repo, so it works just as well from main/ as from the root. The reason to prefer main/ is what the session records look like afterwards. A bare repo has no checked-out branch, so Claude Code stamps every record of a session started there with gitBranch: "HEAD" — an anonymous bucket that no card and no report can name. From main/ the same records read main, which is a label you can measure and subtract. 64% of this repository's recorded token spend currently sits in that anonymous HEAD pool, and moving the orchestrator is most of the fix.

Anywhere else — the remote environment, a container, or inside a task worktree — stop and say: "orchestrate needs the local bare repo so it can create worktrees — run it from /Users/ac/.work/osn.git/main, or use new-feat and prep-pr in place instead." There is no static equivalent of this run; the deliverable is merged pull requests.

[!warning] An orchestrated task is carded only if every dispatch carries the branch. gitBranch is captured once when a session starts and inherited by every subagent it dispatches — it is a property of the session, not of the work, and isolation: "worktree" does not change it: that pins a subagent's cwd correctly and still reports the parent's gitBranch. So a subagent building in a task worktree would record the orchestrator's branch, and the task's own card would read zero.

What closes that is the TASK-BRANCH: marker in Step 3 — the collector reads it back out of the dispatch prompt. It is the whole of the attribution, and it fails silently: a dispatch that omits the line does not warn, it just banks that subagent's spend against the orchestrator's own branch, where nothing will look for it.

So put it in every prompt this skill sends — hand-offs, fix subagents, reviewers, shepherds, re-dispatches — and check the run afterwards rather than assuming. Every task branch should appear in:

bun run --cwd tools/pr-metrics backfill -- --dry-run

A branch missing from that list was not attributed. See wiki/observability/session-metrics.md.

The blackboard

Write ORCHESTRATE.md in the main worktree — outside every task worktree, so no .gitignore governs it and no worktree can stage it, which is the point: one file for a run that spans several branches. Rewrite it at every step boundary — a task dispatched, a gate run, a commit made, a PR opened. A long run gets compacted, and what survives a compaction is what was written down, not what you were holding in context. Read it first after any compaction, before touching a worktree. One block per task:

## task 3 — vendor enquiry weddingName
issue:       xchromo/osn#812
worktree:    /Users/ac/.work/osn.git/vendor-enquiry-name
branch:      feat/vendor-enquiry-name (base origin/main)
pr:          not opened
gates:       check ok · lint ok · test:run NOT RUN · fmt:check NOT RUN
findings:    plan 1 · brief 0 · worker 2
next:        stress-plan finding #2 still open — the DoD names a command that runs nothing

NOT RUN is a real value and usually the honest one: a gate whose result you cannot name off this file has not been run, whatever anyone reported. findings: counts where each finding came from — the plan's when the plan said to do the wrong thing, the brief's when the instruction was right but under-specified, the worker's when the brief was right and the code is not. It costs one line and it is the only signal that says which stage to spend more on.

Step 00 — Feature or task list?

Classify the input before ordering anything.

• A ready task list — concrete changes, each with clear acceptance criteria ("add weddingName to the vendor enquiries response", "wire astro check into the two cire frontends"). Go to Step 0.
• A feature — open scope, needs product or design direction, spans subsystems, or is big enough to want phases. Run the design phase first. When unsure, treat it as a feature: a short design gate is cheaper than a subagent guessing at scope.

The design phase is interactive; the build loop is not. Do it with the user, synchronously, before any subagent exists:

1. superpowers:brainstorming turns the idea into an approved spec at docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md. It has a hard gate — no worktree, no plan, no implementation until the user approves — and a feature spanning independent subsystems comes out as sub-project specs, which become your phases.
2. superpowers:writing-plans turns each approved spec into a task-by-task plan at docs/superpowers/plans/YYYY-MM-DD-<name>.md, one per phase. Note each plan's Global Constraints; they go into every dispatch.
3. Run the stress-plan skill on each phase's plan before dispatching that phase. A wrong assumption in a plan is copied faithfully by a good implementer and comes back as a clean diff doing the wrong thing; no downstream review catches it, because every downstream review checks the work against the plan rather than the plan against the repo. Every finding is closed — fixed in the plan or rejected in writing — before Step 2 cuts the worktree.
4. The ordered phases are the tasks Step 0 orders — one phase, one branch, one PR. Inside a phase, the plan's tasks are the subagent's work, not yours.

Point every dispatch and every reviewer at the phase's plan file path and its Global Constraints. The plan is the single source of requirements; do not paste task detail into a dispatch.

For a feature with more phases than prose can hold, a .canvas beside the plan (obsidian:json-canvas — one node per phase, edges for dependencies, labelled with the files two phases both touch) lets the user check the ordering. Optional, and the plan file stays the source of truth.

Step 0 — Order the work

Parse the input into discrete tasks and plan structure only:

• Order by dependency. A task another builds on, or that touches files another touches, goes first. Independent tasks still run through this loop one at a time; parallelise only when they share no files and you will manage separate worktrees.
• One task, one branch, one PR by default. Group two only when they are genuinely one unit of work.
• A task with no clear acceptance criteria is not dispatched. Ask the user to clarify before a subagent guesses at scope; if it needs product direction, that is Step 00.

State the ordered list and which tasks get their own branch in one short message, then start. Do not describe how any task will be built.

Per task — Steps 1 to 5, in order

Step 1 — Gather context, lightly

Collect orientation pointers for the subagent: the files in play, the pattern to copy from elsewhere in the repo, the schema and types involved, the footguns. Explore, grep, Read. This is context, not a design.

Hit the wiki before the source — its system pages already hold the contract, the finding history and the footguns. Use the three-tier ladder in CLAUDE.md §Searching the wiki, pulling one heading (get_note_outline, get_vault_file_partial) rather than a whole page. Hand the subagent wiki page paths, not pasted prose: it has its own context window. Include the pages the task will make stale — that is prep-pr's docs work list.

Step 2 — Worktree and branch

git -C /Users/ac/.work/osn.git fetch origin main
git -C /Users/ac/.work/osn.git worktree add /Users/ac/.work/osn.git/<dir> -b <prefix>/<dir> origin/main
(cd /Users/ac/.work/osn.git/<dir> && bun install)      # a fresh worktree has no node_modules

<prefix> is feat/, fix/, chore/, refactor/ or docs/; <dir> is the branch name without it. Skip only when the task genuinely continues an existing, unmerged branch. A task that stacks on an open PR's branch is cut from that branch and gets git config branch.<name>.gh-merge-base <parent> — wiki/conventions/stacked-prs.md.

Step 3 — Hand the task off, whole

Dispatch one subagent that owns planning and implementation. Give it the task, the Step 1 pointers, the worktree path and branch, and these instructions.

Which one: run the pick-agent skill. It maps the task and its complexity: label to a definition in .claude/agents/, and so to a model and an effort level — implementer for anything that designs something, mechanic for work whose answer is fixed before it starts. Default to implementer when unsure; defaulting up is recoverable and defaulting down produces a subagent that does a worse job and reports success.

The dispatch is a contract, not a description. A subagent inherits no conversation, so anything not in the text does not exist, and anything wrong in it gets followed to the letter. Every dispatch carries:

• The branch, as the first line: TASK-BRANCH: <branch>. On its own line, verbatim, in every prompt this skill sends to the Agent tool — Step 3's hand-off, Step 4's fix subagents, Step 5's shepherd, and every re-dispatch. A subagent's gitBranch is the orchestrator session's, captured once at session start and inherited, so without this line its spend is attributed to main and lands on no card. It is 85.8% of subagent spend today. The collector reads the marker back out of this prompt (tools/pr-metrics/index.ts, resolveDispatchBranch); a subagent that dispatches further work does not need to repeat it, because a child with no marker inherits its parent's.
• The reader. Every file the task creates names the file or command that reads it. If nothing reads it, the task is not done — "create the file" and "make something call it" are separate steps, and an implementer reliably does the first and skips the second.
• Never invent an identifier. Hostname, key name, path, port, flag, package name. Unknown value means stop and report NEEDS INPUT, never a plausible placeholder.
• The command to run. Name it, and make sure it actually runs the thing: a type check is not a run, and bun test ./scripts/ collects no *.test.sh.
• Commit on the branch. An uncommitted tree is not a result.
• Report only what git cannot tell you — assumptions, deviations, blockers. You read the diff for everything else.
• The shared files this task touches that another task also touches. That is a real dependency and belongs in the order alongside the logical ones.
• The wiki pages to read, by repo path, and the ones this work makes stale. Paths, never pasted prose — the subagent has its own context window and can open a file; yours is the run's bottleneck.

test -e every path a dispatch names before sending it. A whole task has been lost to a directory that did not exist, and that was the orchestrator's fault.

Then the instructions themselves:

• Invoke the new-feat skill and follow it — it routes to the right sub-skills. Plan the implementation itself; do not wait for a plan from you.
• Match repo conventions (CLAUDE.md, the product's wiki/apps/<product>-development.md), add the changeset, follow the observability rules, write tests — TDD where there is logic.
• Edit wiki pages with Edit/Write in its own worktree, invoking obsidian:obsidian-markdown for the syntax. Say explicitly: the Obsidian MCP and the obsidian CLI both point at main's wiki/; they read, never write.
• Commit on the branch; do not push and do not open a PR — Step 4 owns that.
• On a decision it cannot resolve from the context and sensible defaults, stop and return NEEDS INPUT: <question> + options + recommendation rather than guess.

Do not re-implement or second-guess its design. Its final message is a report to you, not to the user.

For a large phase — a plan with many independent tasks — tell the subagent to run superpowers:subagent-driven-development against the plan file instead of new-feat: a fresh implementer per task, a review per task, a review of the whole branch, all inside the one branch. Still one PR; prep-pr runs once at the end.

Step 4 — prep-pr, with findings fixed

No subagent's stated verification counts. Before reading a word of its report, check the mechanical half yourself in its worktree: the commit exists and the tree is clean (git -C <dir> status --porcelain, git log --oneline <base>..HEAD), no conflict markers survived a rebase, no brief or scratch file was committed, every JSON and TOML the branch touched still parses, and git -C <dir> diff --stat shows it touched what it claimed. Each of those has caught a report that was wrong — including one quoting a commit SHA it had invented. Then read the diff, then run the gates.

Two rules for anything you dispatch into a worktree:

• A reviewer never builds. Read-only means read-only about the tree, not just about your files: two builds running at once in one checkout interleave their output into a directory that never existed, and the measurements taken from it are not real. Take measurements yourself, in a worktree nothing else is touching. A finding quoting a measured number states the worktree and the file count it measured, so you can reject it on sight when the count disagrees with what the app emits.
• One agent per worktree, reviewers included, and never one alongside your own uncommitted edits. A review agent comparing an old shape against a new one reaches for git checkout <ref> -- <path>, and putting it back discards whatever you had uncommitted in that tree.

Run the prep-pr skill on the branch. Its own steps validate the changeset, build and test, run review-tests, and run the performance and security reviews in parallel. This skill's contract is stronger: after the reviews, dispatch implementer fix subagents to add the missing tests and fix every security and performance finding — Critical, High and Medium at minimum, Low and Info when cheap — then re-verify. Critical and High are not deferrable at all: fix them here, or open the follow-up pull request immediately and link it before either merges — see wiki/conventions/review-findings.md. A Medium deliberately deferred is carried into the PR body as a tracked follow-up. Scale review depth to the change: a docs or config PR does not need three review agents; an auth, route or binding change does. Then the five-section PR body, push, and open the PR.

Step 5 — Retro, then watch, merge, tear down

First, the card. Invoke the retro skill on the task's branch before dispatching the shepherd. It writes and commits the session-metrics card with the pull request's identity on it, and reads what the task cost against the complexity declared at Step 1. Under this skill that matters more than anywhere else: an orchestrated task's spend sits in subagent transcripts, and the card is the only place it is ever added up. Skip it and the task's own cost is unrecoverable once the worktree is torn down at the end of this step.

Then delegate the waiting, not the deciding. Dispatch a shepherd subagent (.claude/agents/shepherd.md) to poll — slow CI polling should not sit in your context, and waiting does not need an expensive model. It polls to a terminal state and reports. It does not merge, does not rebase, does not push and does not remove a worktree: those are the only irreversible operations in this loop, and shepherd pins the cheapest model in the fleet precisely because it is not the thing making that call.

The shepherd's whole job:

gh pr ready <n>                                                       # if opened as a draft; then wait ~10 s before reading state
gh pr view <n> --json mergeStateStatus,statusCheckRollup,state

It reports the terminal state, and for a failure the job name and the decisive line of its output — not the whole log. Then you act on what it reports:

• All checks green and mergeStateStatus: CLEAN → you run gh pr merge <n> --squash --delete-branch.
• DIRTY or BEHIND → dispatch an implementer to rebase onto the latest origin/main, resolve conflicts (sibling PRs that merged first are usually additive — keep both sides; for changeset or version churn from the release workflow, take the regenerated state), re-run the touched package's tests and git push --force-with-lease. Conflict resolution is a judgement call and a force-push is not recoverable, so neither belongs to the polling agent.
• A real check failure → dispatch an implementer fix subagent, push, re-poll. Never merge red.
• Once MERGED, you run git worktree remove --force <dir> and delete the local branch. Never leave a merged task's worktree behind.

Between dependent tasks: git fetch origin main and fast-forward local main so the next worktree is cut from the updated tip. If a later task's branch already exists and now conflicts, rebase it before its Step 5.

When a subagent dies mid-task

Session limits, API errors and crashes all land the same way: the agent stops and the worktree holds a partial change nobody has verified. Do not re-dispatch into it blind — a second agent inherits half-finished edits it did not make and cannot tell them from the tree.

1. git -C <worktree> status --porcelain and git log --oneline <base>..HEAD. Committed work is salvage; an uncommitted tree is a draft with no author.
2. Read the partial diff yourself. Decide one of three things and write the decision into ORCHESTRATE.md: finish it yourself, re-dispatch with a brief that names what is already done, or git restore and start the task over.
3. Re-dispatching wins only when the remaining work is large and separable. Below roughly a file's worth, finishing it yourself is cheaper than writing a brief that describes someone else's half-finished tree.
4. A limit that resets on a clock is a wait, not a failure. Park the task in ORCHESTRATE.md with next: filled in and pick up a task that touches no file this one touches.

Handling subagent questions

Subagents cannot prompt the user; they surface NEEDS INPUT in their report. Then:

1. Answer it yourself from the task, the codebase, repo conventions, prior decisions this session and sensible defaults — by continuing that agent (SendMessage to its id) or by dispatching the next step with the decision baked in.
2. Escalate to the human only when it is genuinely their call — a product or scope choice, a value only they hold (real domains, account ids, legal copy), spend, anything outward-facing or irreversible. Ask concisely with clear options, then feed the answer back.
3. Never let a subagent block silently or guess on a consequential decision.

Gotchas

The full table, with the reason behind each, is references/gotchas.md. The ones that cost a run:

• Feature input dispatched straight into the loop → the subagent guesses scope. Step 00 first.
• gh pr ready does not propagate at once; a still-draft PR shows BLOCKED with green checks. Wait, then read.
• Pre-push runs bun audit --audit-level=high. An advisory in an installed package is a real stop; do not push with --no-verify to get past one — fix or override it in package.json and say so in the PR.
• Merging several PRs in sequence: the release workflow versions on every merge, so sibling PRs touching wrangler.toml or an index.ts conflict. Merge in dependency order and rebase additively.
• Wrangler named environments inherit no top-level bindings. Every [[d1_databases]], [[r2_buckets]] and [images] is mirrored into [env.production] and [env.dev]; verify with wrangler deploy --dry-run.

When not to use this

A one-line or single-file change — edit it and open the PR directly. Outside the local bare repo — new-feat then prep-pr in place.