jpicklyk / orchestrate

Orchestrate — Tier, Delegation and Dispatch

On-demand depth for sizing work and dispatching agents. The tier table and the delegation model table apply when orchestration.mode is workflow. In schema mode the schema alone governs process, so skip the tier and model-table content — but the phase-owner dispatch rules and the explicit-model rule below still apply, with the model chosen by judgment.

Tier Classification

Classify every piece of work into a tier before starting — the tier determines how much process to apply.

<!-- BEGIN GENERATED:tier-classification | source: claude-plugins/task-orchestrator/fragments/tier-classification.md · regen: node claude-plugins/task-orchestrator/fragments/generate.mjs -->
| Criteria | Tier | Pipeline |
|----------|------|----------|
| 1-2 files, known fix, no migration/new API | Direct | Orchestrator edits, tests, reviews inline |
| 3-10 files, single logical unit, clear or explorable scope | Delegated | Single subagent, separate review agent |
| 11+ files, multiple independent work streams, dependency edges | Parallel | Worktree agents, full pipeline |

Force-UP signals (bump tier regardless of file count):

• Database migration → min Delegated
• New public API surface → min Delegated
• Multiple independent work streams → Parallel
• User says "let's plan" / collaborative language → min Delegated

Force-DOWN signals:

• User says "just fix it" / "quick" → Direct (unless complexity contradicts)
• Schema tag is default or absent → eligible for Direct

<!-- END GENERATED:tier-classification -->

Tier Pipeline Summary

Review applies only when the item's schema declares review-phase notes; otherwise work advances straight to terminal — detect via newRole and skip review dispatch.

Multi-item dispatch: when post-plan-workflow's four-part condition holds (two or more unblocked leaf items, a resolvable rootId, filled queue notes, protocol rules listed), dispatch goes through /task-orchestrator:run-wave; otherwise hand-dispatch.

Delegation

Project convention, not a plugin requirement. The specific model assignments and the
MCP-write batching threshold below are tuned for this repository. Projects using this skill
should treat them as sensible defaults and adjust to their own model availability and tooling —
what transfers is the principle (match model to task weight; keep the orchestrator's context
lean), not the exact table values.

Always set model explicitly on every Agent dispatch — defaulting wastes opus tokens or under-powers complex work.

Dispatching an item's phase owner

Applies only to the agent that OWNS the phase being entered — the implementer entering work, the reviewer entering review — never test author, planning seats, or the docs seat (those keep the Delegation table above).

Read the profile for the phase you are dispatching INTO, not the item's current phase:

• If the orchestrator already performed the transition (e.g. dispatching the reviewer after advancing the item into review), read dispatch off that advance_item call's success result — it reports the profile for newRole, the phase being dispatched into.
• If the agent will perform its own phase entry (the agent-owned-phase protocol: the implementer is dispatched while the item is still in queue, and calls advance_item(start) itself to enter work), get_context(itemId=...) returns only the profile for the item's CURRENT role (queue) — not the work-phase profile needed for dispatch. Read query_items(operation="schema", itemId=...)'s per-phase dispatch.work map instead.

When that profile names an agent, dispatch with subagent_type set to that dispatch.agent. Regardless of whether agent is set, ALWAYS still pass model explicitly: dispatch.model if the profile sets one, otherwise the Delegation table's value above (or your own judgment in schema mode) — both shipped agents (task-orchestrator:implementer, task-orchestrator:reviewer) ship model: inherit, and Claude Code resolves the per-invocation Agent-tool model first, then the agent's own frontmatter, where inherit means the main conversation's model — omitting model silently runs the phase owner on the orchestrator's own model instead of the intended assignment.

effort has no Agent-tool parameter of its own. In Claude Code it is honored only through the dispatched agent definition's own frontmatter effort field, so a profile's effort is advisory unless agent also names a definition carrying that effort — to change effort, point agent at a definition with that effort. (A client that calls the model API directly may apply a profile's effort field itself.) This rule is for the phase OWNER only — auxiliary dispatches on the same item (test author under needs-test-author, planning seats, the docs seat) keep the Delegation table; a work-phase dispatch profile names the phase owner, not every work-phase dispatch.

For a seat-aware item (its schema declares seats:), read every seat's profile — including the test author and planning seats — from the resolved dispatchBySeat, which supersedes the Delegation table for those seats. When a resolved profile pins a model, change it through the project's config traits, not by overriding it at dispatch time.

Batching and prompts

Project convention (workflow mode only; in schema mode batch by ordinary judgment): avoid 3+ MCP write calls in a single turn. Parallelized reads (e.g., get_context + query_items overview) are fine and encouraged. Delegate bulk MCP write work to the Agent tool with model: "haiku" to keep the orchestrator context clean.

Delegation prompts must include entity IDs and full context — subagents start fresh.

Dispatch contract

Parallel-tier dispatches follow a dispatch contract. Where the project's /implement skill ships a dispatch-contract template, generate the run's plan file from it; otherwise write one plan file for the wave that pins branch, worktree, file ownership, commit form, build self-check and review scoping. Either way, point every dispatch prompt at that file by absolute path instead of restating those rules inline. Under a run plan (/task-orchestrator:run-wave) seat prompts are generated and never reference this file; the contract then serves the orchestrator (fallback hand-dispatches, the post-run commit map) and the reviewers, and anything a seat must know goes in the item's specification/task-scope note.

Hand-dispatched seats carry the project's verify commands

/task-orchestrator:run-wave reads the project's .taskorchestrator/run-profile.json and a project dispatch contract pins its own build self-check. A seat you dispatch by hand, outside both of those, gets neither unless you put it there. When that file exists:

• For each verify entry whose seats lists the seat you are dispatching (implementer, test-author, ...), paste its command into the seat's prompt verbatim, substituting <worktree> and <scratchpad>, as the check the seat runs before committing. If the command calls a wrapper that a wave's setup creates (a lock script in the scratchpad, say) and that file is absent, give the seat the same tasks through the build tool directly: the task list is what matters, not the wrapper.
• Run every entry whose seats lists orchestrator yourself, on the item's worktree, before dispatching the reviewer and again before pushing. A failure there goes back to the owning seat before review, not to the reviewer.
• Without a run-profile, mirror the project's CI checks instead (its workflow files): a seat prompt that asks only for the test task misses any lint or format gate CI runs first.

Verification

Do not delegate verification. Do not dispatch subagents to verify or double-check your own work. Verification belongs to the schema's review phase (a separate reviewer) or to inline review on Direct tier. Current models self-verify well, so a redundant verification agent adds cost without catching more. This does not cover independent test authoring under the needs-test-author trait — dispatching a separate test author is production work the trait requires, not re-verification; the separation between writing code and writing its tests is the point. Redundant double-checking of your own edits remains discouraged.

Notes are the report

Subagents write findings into their work item's notes; their final message back is 1-2 lines (item ID, outcome, note keys filled). Never ask agents to restate note content in replies.

Delegation metadata

If your project defines a delegated trait (see your schema config), applying it is recommended for Delegated/Parallel items: apply the trait at item creation (traits: "delegated" — it appears in availableTraits on create responses) or via manage_items update before dispatch (per-item form: items: [{itemId, traits: "delegated"}]), so the note below is schema-visible rather than convention-only. Then, after each subagent returns, fill its delegation-metadata work note — model · isolation · one-line rationale · one-line outcome. The orchestrator fills this, not the subagent (only the orchestrator knows the dispatch details). It feeds /session-retrospective's delegation-alignment scoring; projects that don't define the trait simply skip it.