Orchestrate

Orchestrate — parallel work packages with async human decisions

Turn one parent task into small work packages executed by parallel subagents, while every decision only the human can make becomes a plain-language question document with a stated default — so the human answers on their own schedule and nothing ever stalls waiting for them.

Three roles: the orchestrator (you — decompose, launch, verify, keep shared state), worker agents (each produces exactly one output file), the human (answers question docs asynchronously, does the steps only they can do).

The five invariants

Everything else adapts to the project; these do not.

1. One package = one agent = one output file. A worker creates or edits exactly one file and touches nothing else. This is what makes N agents safe in parallel — no merge conflicts, no racing writes on shared files (a real hazard on Drive/Dropbox-synced or concurrently-open repos) — and it makes verification trivial: read the file, check the done-when.
2. Packages are small enough to finish without a human. Size each package so no human decision is needed mid-package. If a decision might arise, it becomes a question doc and the package proceeds on a default. A package that must pause for an answer was cut wrong — split it.
3. Never block. Workers and orchestrator alike: when a human-only decision or an underivable fact appears, write a question doc (see below), state a default, continue on the default. The human course-corrects later; momentum is worth more than pre-approval on reversible drafts.
4. Only the orchestrator edits shared state. Task statuses, index files, the question index, cross-links between docs — orchestrator only. Workers create their own files (output + question docs) and never touch indexes. Two agents appending to the same index is the classic race; this rule removes it.
5. Verify on disk before closing. Never mark a package done from an agent's self-report alone. Read the output file, check it against the package's done-when items. Agents occasionally report success for files that are wrong, partial, or (on synced folders) clobbered.

Configuration

Optional. With no config at all the skill discovers the project's tracker in Phase 1 and runs on defaults; config only caches those decisions so you stop re-making them.

Three layers under .agents/config/orchestrate/ — global, repo, local, later wins — per the Agent Config Standard. Throughout this document, $O means the bundled config CLI:

O="<this-skill-dir>/scripts/orchestrate-config.ts"   # installed as a plugin:
                                                     # $CLAUDE_PLUGIN_ROOT/skills/orchestrate/scripts/orchestrate-config.ts
bun "$O" help

Run this once at the start of an orchestration, before decomposing anything:

bun "$O" check

• Exits 0 (ready) → use the settings it prints. They replace the discovery steps in Phase 1: the tracker is already chosen, and so are the questions path and model tiers.
• Exits 2 with "No configuration yet" → the expected first-run state, not an error. Run Onboarding. Never report it to the user as a failure.
• Exits 2 with "not ready" → config exists but is incomplete; it lists exactly which keys are missing. Fix those keys, don't rewrite the user's config.

tracker.kind is one of file, tasknotes, github, jira, linear. The first two are local and need no credential, so a file tracker is a complete secret-free setup; only the three hosted trackers engage the credential path at all. Orchestrate's own keys — questions.path, questions.human, models.judgment, models.mechanical, and defaults — are documented with realistic values in config.example.json next to this file.

Onboarding

Only when check reports missing configuration. The agent-config skill owns the walkthrough — which layer, credential-reference sources and their shapes, writing, gitignoring. Four questions are orchestrate's own; use AskUserQuestion so the user picks rather than types.

1. Where should work packages be tracked? Look before asking and put the discovered option first: an existing tasks.md or TODO.md (file), a task folder with frontmatter task files such as Obsidian TaskNotes (tasknotes), or GitHub / Jira / Linear. If nothing exists, recommend file with a new tasks.md next to the work — no credential, no setup.
2. Where does the credential live — only for github, jira, linear. GitHub needs none at all when gh auth status already succeeds; offer that first. If the source can prompt (1Password, Keychain), add cacheVar to the reference and give the user the one-line export that seeds it: orchestrate runs many short-lived processes, and without it each one re-resolves the secret and raises its own Touch ID prompt.
3. Where do question docs collect, and who answers them — questions.path, questions.human.
4. Model tiering — which model for judgment-heavy drafting versus mechanical work. Offer to skip; unset means every worker inherits the session model.

Then write it and confirm it works:

echo '<layer JSON>' | bun "$O" write repo   # or: global | local
bun "$O" verify                             # resolves the credential, makes one real call

write rejects a secret inlined in credentials and gitignores the local layer for you. Onboarding is not finished until verify prints OK — "configured" means working, not "file written". To change an answer, write the layer again; bun "$O" show prints the merged result with credentials described, never revealed.

Phase 1 — Setup

Read the project's own rules first. CLAUDE.md / AGENTS.md, any glossary or terminology doc the project marks as canonical, style conventions, past feedback. Every worker prompt will carry a "read these first" list built from what you find here. Orchestrating without this produces fluent, wrong output at scale.

Settle the tracker; never import your own. If check printed a tracker.kind, that is the answer — use it. Otherwise look for what the project already uses: a tasks folder with frontmatter task files (e.g. Obsidian TaskNotes — needs tags: [task] and the project's field conventions), a task-index.md / TODO.md, GitHub issues (gh). Mirror its exact conventions — naming, frontmatter fields, status vocabulary, link style. If nothing exists, create a minimal tasks.md (table: package / status / due / output file) next to the work and say so.

Create the questions folder at questions.path if config set one, otherwise near the work (e.g. <workspace>/questions/), with a README holding the template and two index tables (open / answered). Full template, writing rules, and index skeleton: read references/question-protocol.md before creating it.

Decompose the parent task. Each package gets:

• a one-line mission and exactly one output file (new file, or one existing file edited in place);
• an explicit inputs list (files the worker must read);
• 2–4 checkable done-when items;
• a due date if the parent has hard dates;
• its dependency edges (which packages must land first).

Create a tracker entry per package, link them from the parent task, and note in the parent that the split happened and where questions collect. Good package boundaries follow the outputs the human will actually use (a briefing doc, a worksheet, a drafted deck), not internal process steps. Stay within defaults.maxPackages when config sets it — if the work genuinely needs more, say so rather than silently exceeding it.

Phase 2 — Launch

Waves by dependency. Everything with no unmet dependency launches in wave 1 — all in a single message so they run concurrently, up to defaults.maxParallelAgents. Later waves launch as their inputs land. Don't hold a ready package hostage to an unrelated one.

Tier models by judgment required. Judgment-heavy drafting (client-facing prose, analysis, anything where taste matters) → models.judgment. Mechanical work (decomposing an existing table, reformatting, inventory-building) → models.mechanical. With no config, pick per package on the same criterion. Say which you chose and why when reporting.

Build each worker prompt from the scaffold in references/agent-prompt.md — read it when writing the first prompt. The non-negotiable blocks: the context paragraph (a worker knows nothing about the engagement), the single-output-file assignment, the ordered read-first list, content requirements, the question protocol (verbatim block from the reference), the shared-state prohibition (never edit indexes, including the questions README), on-disk verification after the final write, and a structured final report (output path / key decisions / question files created / assumptions).

Phase 3 — Process completions

On each completion notification (they can arrive as bare "idle" signals with no report, and duplicates are normal — processing must be idempotent; if the task is already closed, say so and stop):

A completion signal means a turn ended, not that the work is done. An orchestrating agent idles while its own sub-workers still run, then resumes when they finish — so a package (or a whole orchestration) can signal several times before it is actually complete. Before closing anything, check quiescence on disk: the declared output exists in final form and the tracker state is terminal, not "in progress". Judging a mid-flight snapshot produces confidently wrong conclusions.

1. Verify: read the output file on disk; check every done-when item.
2. Collect questions: list the questions folder; read any new files; register each in the README index (orchestrator-only edit) with its one-line question and default.
3. Close: mark the tracker entry done (check the boxes, add a dated completion note naming the output and any questions raised), update the index/mirror.
4. Launch any wave whose dependencies just cleared.
5. Report to the human, leading with the outcome: what landed and what it contains, new questions (one line + default each), scoreboard (X of N done, what's running), and which questions are worth answering soon versus safely deferrable.

If verification fails, message the same agent with the specific gap (it retains context) rather than respawning cold.

Phase 4 — Answers and wrap-up

When the human answers a question (in the file or in chat): if the answer matches the default, flip the file's status to answered, move its index row to the answered table, done. If it overrides the default, apply the delta — question docs are written to name what the default touched, so the edit is targeted — then update status and index, and note the change where the affected doc's conventions require.

Wrap up when all packages are closed: final report (deliverables, open questions with defaults, what remains human-only — meetings, approvals, rehearsals), and leave a resume trail: the parent task and any persistent memory should record the split, the questions-folder location and its open count, and what event unblocks each remaining step, so a fresh session can pick up mid-flight.

Anti-patterns

• Question inflation. Raising questions to look diligent. If you can infer the answer confidently and annotate the reasoning, infer — the annotation is the question. Reserve question docs for genuine forks where the human's choice changes the work. (Expect roughly one question per package, often zero.)
• Jargon in question docs. The human may batch-answer days later, on a phone, without context. A question doc a stranger can't follow has failed. Plain words, short sentences, every project term explained at first use.
• Two workers, one file. If two packages "need" the same file, either merge them into one package or re-cut the boundary. No exceptions — this includes indexes.
• Closing on self-report. See invariant 5.
• Restructuring paths under running workers. Never move, rename, or reorganize directories that live workers hold absolute paths into — their later writes land in recreated old paths or vanish. Reorganize only at quiescence.
• Blocking. Ending a turn with "waiting for your answer before continuing" while runnable packages exist. The only things that wait are the things that genuinely depend on the answer.
• Invented facts. Workers must trace every figure and claim to a source or mark it TBD; instruct this explicitly and spot-check during verification.
• Onboarding as a gate. Missing config is not a reason to stall an orchestration. Ask the four questions, write the layer, move on — or, if the user is already away, proceed on a discovered file tracker and raise the choice as a question doc.