/meta-orchestrator build and orchestrate

Install

Install just this, from a clone of the repo. Anything it needs comes with it.

./scripts/install-skills.sh --skill meta-orchestrator   # bash, Git Bash, macOS, Linux
.\scripts\install-skills.ps1 -Skill meta-orchestrator   # Windows PowerShell

Needs: consult-plan, divide, handoff-auto, kanban-setup, lanes, next, pair, progress-report, session-handoff, update-progress, implementer, manager, planner, verifier, the guard-git hook (installed with it).

What it does

Works through a repo's backlog unattended. Claude becomes the orchestrator: it never implements.

• It loops planner → manager (or implementer, or a swarm of haiku implementers) → merge gate → verifier.
• It holds the merge gate itself (tests + CI green or no merge).
• It logs every event to a ledger.
• It hands off to a fresh orchestrator session after a budget of merges.

Almost every behaviour is a setting you pick on the first run.

When to use

• "Go through the open issues and don't stop", "work through the board with subagents", "act as the orchestrator".
• "Resume" a previous orchestrator run.
• For one task, use pair instead.

How to invoke

/meta-orchestrator <repo path> [resume | reconfigure] [key=value ...]

• First run: setup interview (below), then the loop.
• resume: no questions; continues from orchestrator-handoff.md.
• reconfigure: re-run the interview on an existing run.
• key=value skips that question, e.g. merge=ask shape=flat reports=end. An old execution= key still works as shape=.

How it works

0. Setup (SETUP.md).
   • Read-only recon (contributing guide, skilleddocs/, branches, PRs, CI, merge style).
   • Resolves defaults in layers: built-ins → your saved ~/.claude/orchestrator-defaults.md → the repo's AGENTS.md/CLAUDE.md → arguments.
   • Shows the resulting contract and asks "Use these, or customize?".
   • Customize walks four short rounds (multiple choice, recommended option first):

   Round	You choose
   Run shape	which issues, when to stop (queue empty / N merges / time box), shape (pair / auto / swarm / flat), how many issues in parallel
   Control	merge auto / ask each time / pr-only, merge style, whether agents may answer planning questions for you, ask vs assume on calls with no written answer, which changes always pause for you (new deps, migrations, deletions, API or CI changes; billable always)
   Documentation	what gets written (ledger always; decisions register, per-issue handoffs, manager reports, CHANGELOG lines), whether docs are committed, report cadence (each handoff / every N merges / end / on request), Markdown or docx, ledger detail
   Models and pacing	implementer model (by size unless pinned), review model, handoff budget, push notifications

   Writes skilleddocs/orchestrator/scope.md (a yaml block of every key), commits it, and offers to save your choices as personal defaults so the next repo starts from them.

1. Agents.
   • planner → kickoff brief with the issue's size (a size:* label wins over its rating) and a recommended shape; then by shape (SKILL.md §2):
     • pair (default) runs a manager per issue
     • flat an implementer directly
     • swarm runs one haiku implementer per trivial item. Each item gets its own worktree off one batch branch and takes one parallel slot, and is merged into the batch branch. The batch then gets one opus review at the merge gate and one PR
     • auto takes the planner's pick per brief
   • Implementer model by size: trivial → haiku, small/medium → sonnet, large or risky → opus, unless the brief or implementer_model says otherwise.
   • Then verifier. Mechanical chores go to general-purpose on haiku; judgment calls and the merge gate never do.
   • Each step is a fresh Agent call.
   • Agents run code review inline, because agents spawning their own reviewers stall.
   • An INTERIM report is not a result. Neither is a manager handback missing its Branch, Tests or Rounds section: the orchestrator asks once for the full report, then reruns.
2. Loop: planner → manager | implementer | swarm → merge gate → verifier → repeat.
   • Parallel issues each get their own worktree.
   • With parallel > 1, lanes groups the queue into file-disjoint lanes, each working its issues in order; /lanes changes them mid-run.
3. Merge gate (orchestrator only).
   • Tests/CI green for the head SHA.
   • Diff skimmed for scope creep, secrets, drift and anything on your pause list.
   • Push, then merge per your merge setting.
   • Worktree torn down, unlinking dependency links before removing it; ledger entry.
4. Autonomy.
   • One retry per failure, then split or park, never loop.
   • decisions: assume covers calls the written plan doesn't answer. Agents pick their own recommendation and log it as an open A-n for you to confirm. Open A-n items are listed in every handoff and report. (interview: answer is different: it answers only from the written plan.)
   • The guard-git.py hook blocks agents from pushing to the default branch or merging.
5. Ledger. Append-only skilleddocs/orchestrator/ledger.md, local timestamps, committed per entry (unless you chose uncommitted docs).
6. Rotation (ROTATION.md).
   • After handoff_budget merges, or a smart-zone warning that its context is getting full (with lanes, once every in-flight lane has merged or parked): writes orchestrator-handoff.md, logs it, optionally runs a progress report, stops.
   • resume picks up from there.
7. Done when every in-scope issue is closed or parked with a reason (or stop is reached), default is green, every merge has a verify entry.

Flow

One issue's trip (a swarm: one batch's). With lanes, each lane runs this loop on its own issues; the merge gate stays serial.

Design principles

• The orchestrator never implements. Its context stays free for decisions; a strong model there is worth more than anywhere else.
• State lives in files, not context. scope.md + ledger + git mean any fresh session can take over, so rotating is cheap and degrading is avoidable.
• Ask once, up front. Every preference is settled in setup and saved; the loop itself only stops for destructive or scope-changing calls.
• Gates are binary. Green tests and CI for the exact SHA, or no merge.

Shared context for these principles: Matt Pocock's video.

Use cases

• Clearing a labelled backlog overnight with merge=auto.
• Running cautiously on a shared repo with merge=pr-only, so every change waits as a PR for you.
• Long runs split across days via resume, with a progress report at each handoff.

Tips

• Run it once, customize, and save defaults; later repos then need one "use these" click.
• merge=ask is a good first run on a repo you care about; switch to auto once you trust the gate.
• Pair with branch protection on GitHub; the guard hook is a guardrail, not a sandbox.

Example

First run on a repo (no scope.md yet), defaults otherwise, one loop shown in full, then the rotation after the tenth merge:

Related

• Spawns planner, manager, implementer, verifier.
• Uses pair's worktree pattern; kanban skills via the agents (next, divide, update-progress, consult-plan).
• lanes sets and changes parallel + lanes in scope.md.
• progress-report reads its ledger.
• Optional hooks/smartzone.py triggers an early rotation.

Prereqs

• gh (authenticated); the four agents installed (scripts/install-skills.*); a board, status:* labels, or a roadmap doc for next to read.
• Push notifications need the PushNotification tool.

Sample workflows

• Plan an effort too big for one session
  you → wayfinder → grill-docs → you → divide → you → meta-orchestrator
  Install just this one: ./scripts/install-skills.sh --workflow big-effort or .\scripts\install-skills.ps1 -Workflow big-effort
• Run the backlog unattended
  you → lanes → you → meta-orchestrator → planner → manager → implementer → verifier → you → switch → remind → progress-report → you
  Install just this one: ./scripts/install-skills.sh --workflow unattended-backlog or .\scripts\install-skills.ps1 -Workflow unattended-backlog
• Match each issue to a shape: swarm, pair or flat
  you → meta-orchestrator → planner → implementer → manager → verifier → you
  Install just this one: ./scripts/install-skills.sh --workflow orchestration-shapes or .\scripts\install-skills.ps1 -Workflow orchestration-shapes

Source

• meta-orchestrator/SKILL.md
• meta-orchestrator/README.md