[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7DBQJ2ABFJ0J6GZKHAG9ZS4":3,"skill-same:01M7DBQJ2ABFJ0J6GZKHAG9ZS4":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":25,"commitSha":26,"skillDirectory":27,"forksCount":14,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M7DBQJ2ABFJ0J6GZKHAG9ZS4","orchestrate-work",null,"Orchestrator contract for running one body of work as several concurrent delegated lanes and merging the results. Load when a job is too big for one worker, when parts of it can run at the same time, or when you are deciding whether to parallelise. Covers cutting work into lanes by write scope, the contract-first wave, branch-per-lane worktrees under `.worktrees\u002F` and the alternative isolation strategies, dispatch briefs, serialized integration by squash\u002Fmerge\u002Fcherry-pick, failure and escalation handling, and provisional rules for nesting orchestrators. Worker rules live in `implement`; tool mechanics live in `pi-delegate`; the merge step itself lives in `merge-coordinate`.","CenterForAgenticAI\u002Ftools","CenterForAgenticAI","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F250424195?v=4","01M7DBNBBRNZ6NT6WYSEPYK811","CAAIR","01M7DBNBCBH3B7HHWP0ACQW3F7",0,"MIT","https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI\u002Ftools\u002Fblob\u002Fmain\u002Fpackages\u002Fpi-delegate\u002Fskills\u002Forchestrate-work\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: orchestrate-work\ndescription: >-\n  Orchestrator contract for running one body of work as several concurrent\n  delegated lanes and merging the results. Load when a job is too big for one\n  worker, when parts of it can run at the same time, or when you are deciding\n  whether to parallelise. Covers cutting work into lanes by write scope, the\n  contract-first wave, branch-per-lane worktrees under `.worktrees\u002F` and the\n  alternative isolation strategies, dispatch briefs, serialized integration by\n  squash\u002Fmerge\u002Fcherry-pick, failure and escalation handling, and provisional\n  rules for nesting orchestrators. Worker rules live in `implement`; tool\n  mechanics live in `pi-delegate`; the merge step itself lives in\n  `merge-coordinate`.\nload: recognition\ndisable-model-invocation: false\n---\n\n# orchestrate-work\n\n## Your job\n\nYou hold a body of work that is bigger than one dispatch. You do not implement\nit. You:\n\n1. cut it into **lanes** — slices one worker can finish alone, each owning its\n   own files;\n2. group lanes into **waves** — sets that can run at the same time because none\n   needs another's output;\n3. dispatch each wave, isolated so the workers cannot overwrite each other;\n4. put the finished work back together, in a defined order, without inventing\n   resolutions; and\n5. report one result upward.\n\nThree skills divide this work. Keep them separate:\n\n| Skill | Owner | Covers |\n| --- | --- | --- |\n| `orchestrate-work` (this) | you | decomposition, isolation choice, dispatch, integration order, failure policy |\n| `pi-delegate` | you | `delegate` tool parameters, background wakes, steering, escalation plumbing |\n| `implement` | each worker | read-before-edit, file scope, evidence, commit, `done`\u002F`gap`\u002F`blocked` |\n| `merge-coordinate` | the merge step | applying finished lanes onto one branch, conflict taxonomy, refusal rules |\n\n## First decide whether to parallelise at all\n\nSerial is the default. Parallelism buys wall-clock time and costs correctness\nrisk, context, and merge work. Run lanes concurrently only when **all** of\nthese hold:\n\n- the work splits into slices whose write scopes do not overlap;\n- the shared shapes those slices depend on already exist, or can be landed\n  first in one serial wave;\n- each slice has its own proof that does not depend on a sibling's output; and\n- integrating them is mechanical — a defined order plus the repository's own\n  checks, not a judgement call about whose version is right.\n\nStay serial when the work is small, exploratory, concentrated in one or two\nfiles, or when the interface is still being discovered. Two workers editing the\nsame file in isolation is not parallelism; it is a conflict you scheduled on\npurpose.\n\nIf you split work that should have stayed serial, the cost lands at merge time,\nafter every worker has already spent its budget. Decide before dispatching.\n\n## Cut lanes by write scope, not by narrative\n\nThe cut rule is mechanical: **two lanes in the same wave must not need to write\nthe same file.**\n\nProcedure:\n\n1. List the concrete changes the job needs, as paths.\n2. Group paths that must change together — a module and its test, a schema and\n   its migration.\n3. Any path that appears in more than one group is a **shared file**. It is the\n   whole problem. Resolve it one of three ways, in order of preference:\n   - move it into an earlier serial wave, so it is settled before fan-out;\n   - assign it to exactly one lane and make the others read-only against it; or\n   - if neither works, the lanes are not independent — merge them into one lane.\n4. What remains, with disjoint write scopes, are your lanes.\n5. Order lanes into waves by what they consume, not by importance.\n\nA feature described as \"backend, frontend, docs\" is a narrative, not a cut. The\ncut is whichever grouping makes the write scopes disjoint, even when it splits a\nfeature down the middle or puts two unrelated features in one lane.\n\n## The contract wave\n\nIf several lanes depend on the same type, schema, protocol message, trait,\ninterface, or public signature, land that shape **first, alone, serially**.\nFanning out before the shape exists produces N incompatible versions of it and\nan unmergeable wave. This is the single most common way a parallel plan fails.\n\nWhat belongs in the contract wave, by stack:\n\n| Stack | Land first |\n| --- | --- |\n| TypeScript | shared types and interfaces, runtime schemas, discriminated-union variants, barrel\u002Fexport surface, public signatures |\n| Python | protocols and ABCs, dataclasses and model classes, enums, public function signatures, package exports |\n| Rust | traits, enums and their variants, public struct fields, error types, `Cargo.toml` members and feature flags |\n| Frontend | design tokens, component prop types, route definitions, API client types, shared state shape |\n\nThe contract wave is a normal lane in every other respect: one worker, real\nproof, a commit. Dispatch it with a type-first brief — the `implement` skill's\ntype-first method and the matching `implement-\u003Clanguage>` orientation already\ndescribe how a worker executes it. Merge it, verify it, and only then plan the\nfan-out against the shape that actually landed.\n\nIf a later lane discovers the contract is wrong, that is a `gap` coming back to\nyou, not a licence for that lane to change the shared shape. Amend the contract\nin a serial step and re-dispatch.\n\n## Sizing and fan-out\n\n- One `delegate` call takes **1..6** entries. `concurrency` (default 4) caps how\n  many run at once.\n- Prefer 2–4 lanes per wave. Six lanes that each need review is usually slower\n  end to end than three that do not.\n- Size a lane to one worker's context: a handful of files, one coherent\n  behavior, one proof command. A lane that will exhaust its context returns a\n  `gap` and you pay for the work twice.\n- More waves with fewer lanes beats one wide wave, whenever a later lane can\n  read an earlier lane's landed code instead of guessing at it.\n\n## Write the lane brief\n\nEach lane's `task` is a contract. The worker loads `implement`, which expects\nthese fields, so supply them explicitly:\n\n```text\nrequirements: REQ-1 ... (numbered, so evidence and gaps can cite them)\nwrite scope:  exact paths this lane may change\nread scope:   paths to read for context, explicitly read-only\nproof:        the command(s) that must pass, and what they cover\nbranch:       the branch to commit on\ncommit:       message style and any required trailers\nhandoff:      done | gap | blocked, per the implement skill\n```\n\nAdd the two fields that only exist because the lane is running in parallel:\n\n```text\nconcurrent lanes: \u003Cwhat else is running, in one line each>\ndo not change:    \u003Cshared files owned by another lane or by the contract wave>\n```\n\nRules for the brief:\n\n- Never give two lanes in one wave overlapping write scopes. This is the\n  invariant the whole plan rests on; check it before dispatching, not after.\n- Tell the lane what it may **not** touch, by path. A worker that hits a\n  compiler-forced ripple into another lane's file must return a `gap`, and it\n  can only do that if it knows the boundary.\n- Do not paste sibling lanes' plans into a brief. One line of awareness prevents\n  duplicate work; a full copy invites a worker to implement its neighbour's job.\n- Keep `clone_mode: \"task_only\"` or `\"snippet\"` for lane dispatches. A lane\n  brief is self-contained by construction, and `full` copies your entire\n  orchestration history into every worker.\n\n## Isolation: one branch and one worktree per lane\n\n**Default strategy: `branch-worktree`.** Give every lane its own branch, checked\nout in its own worktree under `\u003Crepo>\u002F.worktrees\u002F`, let its worker commit there,\nand integrate by merging branches. This is ordinary Git. The history is real,\nthe work survives a crash, `git log`\u002F`bisect`\u002F`revert` keep working, and the\nmerge step has something to merge.\n\nThree strategies exist. Choose deliberately; the choice decides how you\nintegrate.\n\n| Strategy | Set | Lane produces | Use |\n| --- | --- | --- | --- |\n| **`branch-worktree`** (default) | `worktree: false` + per-run `cwd` into a worktree you provisioned | **commits on a branch that persists** | almost always; required for squash merges, review, and nesting |\n| `patch-capture` | `worktree: true` | a **patch file**; branch and worktree are deleted | short throwaway waves whose history is worthless |\n| `shared-checkout` | neither | edits in place | serial lanes, or read-only fan-out |\n\n### `branch-worktree` — the default\n\nLoad `delivering-work` for the procedure.\n\n### `patch-capture` (`worktree: true`) — available, lossy\n\nThe extension creates one temporary worktree per run from the current `HEAD`,\nrejects per-worker `cwd`, captures committed and uncommitted work as one\ncumulative patch, and removes the branch and worktree unless capture fails.\n\nThe patch is the only durable artifact. Because capture runs `git add -A`, stray\nunignored files land in it. It preserves no commit history and cannot nest. Use\nit only for a short independent wave you deliberately want as patches;\notherwise prefer `branch-worktree`.\n\n### `shared-checkout`\n\nDo not run two writing lanes concurrently in one checkout. There is no\nisolation; the last write wins and neither worker knows. Read-only lanes\n(`scout`, `reviewer`) are safe to fan out this way and usually should be.\n\n## Seed lane checklists\n\nIf a lane has more than one step worth tracking and its worker has a\n`session_tasks` claimant, seed its durable checklist when you cut the dispatch.\nWithout a claimant, the handoff becomes a prompt checklist only; it is not durable\nand has no subtree progress to read:\n\n```ts\ndelegate({\n  runs: [{\n    name: \"lane-a\",\n    agent: \"worker\",\n    task: \"Complete lane A.\",\n    handoff: { tasks: [{ title: \"Inspect\" }, { title: \"Implement and verify\" }] },\n  }],\n})\n```\n\nWhen the worker loads a `session_tasks` claimant, the handoff seeds a durable\nlist; read the lane subtree with `session_tasks action=subtree` to see progress\nrather than asking the worker for a status update. Without a claimant, the worker\nreceives a prompt checklist only: it has no durability or subtree progress. A\n`blocked` row includes either its reason or, when the event budget cannot retain the\nfull reason, an explicit `…` truncation marker. Act on a real reason; investigate\nor escalate a marker-only row.\n\n## Dispatch\n\nBefore starting an `implementer` on multi-file work with no plan artifact, warn\nonce: planner-first work averaged 2.7 review rounds versus 5.7 without a plan\n(n=31 with a plan, n=15 without). Advisory, not a gate.\n\n```ts\ndelegate({\n  concurrency: 3,\n  runs: [\n    { name: \"\u003Clane-a>\", agent: \"implementer\", task: \"\u003Clane brief A>\", cwd: \".worktrees\u002F\u003Cplan>-a\",\n      mode: \"supervised\", clone_mode: \"task_only\", escalation: \"local\", rounds: 6 },\n    { name: \"\u003Clane-b>\", agent: \"implementer\", task: \"\u003Clane brief B>\", cwd: \".worktrees\u002F\u003Cplan>-b\",\n      mode: \"supervised\", clone_mode: \"task_only\", escalation: \"local\", rounds: 6 },\n  ],\n})\n```\n\n- **Name every lane.** `name:` is the key you will use to steer, cancel, or\n  recover that lane, and it is what you will read in the widget and in the\n  completion result. Name it after the work — the lane id, issue reference, or\n  component — never after the agent. Two unnamed `implementer` slots come back\n  as `implementer` and `implementer#2`, which tells you nothing about which one\n  failed. This is your responsibility, not the tool's: without `name:` the\n  runtime can only derive a label from the task text, and lanes briefed from the\n  same file are indistinguishable to it.\n\n- **Dispatch in the background.** It is the default. The call returns a `runId`\n  and the combined result wakes you when every lane finishes. Never poll\n  `delegate_control(action=\"status\")`, never `sleep`. End your turn and let the wake arrive.\n- **Enable `escalation: \"local\"` on writing lanes.** A lane that hits a\n  cross-lane decision must be able to reach you instead of guessing. Escalation\n  requires background dispatch; `await: true` is rejected when any slot resolves\n  to enabled.\n- **Do not steer routinely.** Steering a lane mid-flight usually means the brief\n  was wrong. Fix the brief and re-dispatch rather than negotiating through\n  `delegate_control(action=\"steer\")`.\n- Dispatch one wave per call where you can. A single call gives you one\n  completion wake and one place to compare results; two overlapping calls give\n  you interleaved wakes and no natural integration point.\n\n## Integration\n\nIntegration is mechanical and serialized. It is not a place for judgement.\n\n**Order.** Apply lanes in the order you planned them, not the order they\nfinished. Completion order is nondeterministic; planned order is reproducible\nand reviewable.\n\n**Serialize per target.** One merge into one branch at a time. Never apply two\nlanes concurrently to the same branch, at any depth.\n\n**Preflight, all-or-nothing.** Before applying anything:\n\n1. Collect each lane's changed paths.\n2. Confirm each lane changed only its declared write scope. A lane that\n   exceeded scope is a finding, not something to clean up silently.\n3. Confirm no two lanes changed the same path. If they did, the plan's\n   invariant broke — stop, do not merge the \"safe subset\", and re-plan or\n   escalate.\n\n**Pick one apply strategy for the wave and name it in the merge brief:**\n`squash`, `merge`, `cherry-pick`, or `apply`.\n\nLoad `delivering-work` for the procedure.\n\n**Delegate the merge when it is more than trivial.** A compatible development-tool\npackage's `integrator` agent exists for exactly this and loads\n`merge-coordinate`, the narrow contract:\nsupplied sources, a declared strategy, a supplied path whitelist, an\nall-or-nothing preflight, a small taxonomy of resolvable conflicts, and\nescalation for everything else.\n\n```ts\ndelegate({ runs: [{ agent: \"integrator\", mode: \"supervised\", clone_mode: \"task_only\",\n                    task: \"\u003Cmerge brief JSON>\" }] })\n```\n\n`merge-coordinate` defines the brief's JSON shape and repeats the preflight\nabove against real Git state, so a decomposition error surfaces there too rather\nthan only in your bookkeeping. The integrator returns `success`, `partial`, or\n`escalate` — treat `escalate` as the safety mechanism working, not as a failed\nrun.\n\n**Verify after integrating, not per lane.** Each lane proved itself against the\nbase commit in isolation. Only the integrated tree proves they compose. Run the\nrepository's real gate — its `check`, test, typecheck, and lint commands — after\nthe wave lands, and treat a failure there as the wave's failure, not the last\nlane's.\n\n**Stale parent.** If the integration branch moved after a lane branched (an\nearlier lane landed, or a sibling orchestrator merged), re-check that lane\nagainst the new head before applying it. A lane that no longer applies goes back\nas a remediation dispatch with the conflict as its input. Never hand-edit a\nworker's output into applying; you would be implementing, unreviewed, in the\norchestrator.\n\nLoad `delivering-work` for the procedure.\n\n## When a lane does not come back clean\n\n| Signal | Action |\n| --- | --- |\n| `delegate:fork-failed` wake with `recoveryAvailable: true` | `delegate_control({action: \"recover\", runId, forkName, strategy: \"auto\"})` for **that lane only**. Healthy siblings continue; the aggregate wake still arrives once. |\n| `status: gap` | Read what is missing. Dispatch a follow-up lane with a brief that names exactly the gap, or widen scope deliberately and re-dispatch. Do not finish it yourself. |\n| `status: blocked` | Fix the cause at your level: supply the missing input, make the decision, land the prerequisite. Then re-dispatch. |\n| Escalation raised | `delegate_escalation(action=\"list\")` to re-read canonical state, then resolve inside your authority or pass it up with action `pass_up`. Never infer the operator's answer. |\n| Lane exceeded write scope | Do not merge it. Either re-dispatch with corrected scope or accept the wider scope explicitly and re-plan the wave whose invariant it broke. |\n| Two lanes touched one file | The cut was wrong. Re-plan; the merge is not the place to fix a decomposition error. |\n\nPartial waves are normal. Merge the lanes that came back clean, keep the\nintegration branch green, and re-dispatch the rest. Do not hold a whole wave\nhostage to one lane.\n\n## Nesting (provisional)\n\nA lane can itself be a body of work. Then its worker is an orchestrator: it\nloads this skill, cuts its slice into sub-lanes, and returns one collapsed\nhandoff to you. The tree is orchestrator → orchestrator → worker.\n\nRules that already hold:\n\n- **Depth is budgeted.** Nested delegation obeys `maxSubagentDepth` (default 2;\n  a fresh root may set a deliberate higher value up to the hard ceiling of 16;\n  descendants may tighten but never raise it). A detached `driver` root\n  keeps its minimum of 3. Plan the depth you need before dispatching, and give\n  each level an agent whose `allowNestedDelegate` and `nestedDelegateAgents`\n  permit its children.\n- **Each level integrates only its own children.** A sub-orchestrator merges its\n  sub-lanes into its own branch and hands you one result. It never merges into\n  your branch, and it never reaches past you.\n- **Each level reports one handoff upward**, in the same `done`\u002F`gap`\u002F`blocked`\n  shape a worker uses. Depth must not multiply the reporting surface.\n- **Isolation must follow the tree.** Today only caller-provisioned worktrees\n  can do this, because `worktree: true` always branches from the main checkout's\n  HEAD and rejects per-run `cwd`.\n\nTwo or three levels is a real plan. Deeper is speculation: every level adds a\nbrief that can be wrong, a merge that can conflict, and a summary that can lose\ndetail. Keep the tree shallow until #136 makes provisioning and lineage\nfirst-class, then revisit.\n\n## Worked example\n\nA change adding a new record type to an API, its client, and its docs.\nPlan id `records`; integration branch `records\u002Fintegration`, branched from `main`.\n\n```text\nwave 1 (contract, serial)\n  lane types    branch records\u002Ftypes    .worktrees\u002Frecords-types\n    write: src\u002Ftypes\u002Frecord.ts, src\u002Ftypes\u002Findex.ts\n    proof: npm run typecheck\n  → squash-merge into records\u002Fintegration, verify, then branch wave 2 from its head\n\nwave 2 (fan-out, 3 lanes, disjoint scopes, all branched from records\u002Fintegration)\n  lane server   branch records\u002Fserver   .worktrees\u002Frecords-server\n    write: src\u002Fserver\u002Frecords\u002F**, tests\u002Fserver\u002Frecords\u002F**\n  lane client   branch records\u002Fclient   .worktrees\u002Frecords-client\n    write: src\u002Fclient\u002Frecords\u002F**, tests\u002Fclient\u002Frecords\u002F**\n  lane docs     branch records\u002Fdocs     .worktrees\u002Frecords-docs\n    write: docs\u002Frecords.md\n  do not change (all three): src\u002Ftypes\u002F**\n  → preflight, squash-merge server → client → docs, then npm run check on the result\n\nwave 3 (serial)\n  lane wiring   branch records\u002Fwiring   .worktrees\u002Frecords-wiring\n    write: src\u002Fserver\u002Frouter.ts, src\u002Fclient\u002Findex.ts\n    (both are shared files; that is exactly why they are not in wave 2)\n\nclose out\n  merge records\u002Fintegration into main, remove the four worktrees,\n  git branch -d each lane branch\n```\n\nThe wiring lane exists because two files could not be assigned to a single wave-2\nlane. Naming them in wave 3 is cheaper than discovering them in a merge.\n\n## Checklist\n\nBefore you dispatch a wave:\n\n- no two lanes in it write the same path;\n- every shared shape they depend on has already landed and been verified;\n- every brief carries requirements, write scope, read scope, proof, branch,\n  commit, handoff, concurrent lanes, and do-not-change;\n- every lane slot has a `name:` describing its work, not its agent;\n- the isolation strategy is named, and every lane's worktree and branch exist and\n  are branched from the same integration-branch head;\n- the apply strategy (`squash`, `merge`, `cherry-pick`, `apply`) is chosen;\n- writing lanes have `escalation: \"local\"`, and the dispatch is in the\n  background.\n\nBefore you call the work done:\n\n- every lane returned a terminal handoff, and every `gap` is either closed or\n  reported upward;\n- integration applied lanes in planned order, serialized, with no invented\n  conflict resolution;\n- the repository's own gate passed on the **integrated** tree;\n- every worktree and branch you provisioned is removed or deliberately kept;\n- your own report upward is one handoff, not a transcript of the wave.\n","# orchestrate-work\n\n## Your job\n\nYou hold a body of work that is bigger than one dispatch. You do not implement\nit. You:\n\n1. cut it into **lanes** — slices one worker can finish alone, each owning its\n   own files;\n2. group lanes into **waves** — sets that can run at the same time because none\n   needs another's output;\n3. dispatch each wave, isolated so the workers cannot overwrite each other;\n4. put the finished work back together, in a defined order, without inventing\n   resolutions; and\n5. report one result upward.\n\nThree skills divide this work. Keep them separate:\n\n| Skill | Owner | Covers |\n| --- | --- | --- |\n| `orchestrate-work` (this) | you | decomposition, isolation choice, dispatch, integration order, failure policy |\n| `pi-delegate` | you | `delegate` tool parameters, background wakes, steering, escalation plumbing |\n| `implement` | each worker | read-before-edit, file scope, evidence, commit, `done`\u002F`gap`\u002F`blocked` |\n| `merge-coordinate` | the merge step | applying finished lanes onto one branch, conflict taxonomy, refusal rules |\n\n## First decide whether to parallelise at all\n\nSerial is the default. Parallelism buys wall-clock time and costs correctness\nrisk, context, and merge work. Run lanes concurrently only when **all** of\nthese hold:\n\n- the work splits into slices whose write scopes do not overlap;\n- the shared shapes those slices depend on already exist, or can be landed\n  first in one serial wave;\n- each slice has its own proof that does not depend on a sibling's output; and\n- integrating them is mechanical — a defined order plus the repository's own\n  checks, not a judgement call about whose version is right.\n\nStay serial when the work is small, exploratory, concentrated in one or two\nfiles, or when the interface is still being discovered. Two workers editing the\nsame file in isolation is not parallelism; it is a conflict you scheduled on\npurpose.\n\nIf you split work that should have stayed serial, the cost lands at merge time,\nafter every worker has already spent its budget. Decide before dispatching.\n\n## Cut lanes by write scope, not by narrative\n\nThe cut rule is mechanical: **two lanes in the same wave must not need to write\nthe same file.**\n\nProcedure:\n\n1. List the concrete changes the job needs, as paths.\n2. Group paths that must change together — a module and its test, a schema and\n   its migration.\n3. Any path that appears in more than one group is a **shared file**. It is the\n   whole problem. Resolve it one of three ways, in order of preference:\n   - move it into an earlier serial wave, so it is settled before fan-out;\n   - assign it to exactly one lane and make the others read-only against it; or\n   - if neither works, the lanes are not independent — merge them into one lane.\n4. What remains, with disjoint write scopes, are your lanes.\n5. Order lanes into waves by what they consume, not by importance.\n\nA feature described as \"backend, frontend, docs\" is a narrative, not a cut. The\ncut is whichever grouping makes the write scopes disjoint, even when it splits a\nfeature down the middle or puts two unrelated features in one lane.\n\n## The contract wave\n\nIf several lanes depend on the same type, schema, protocol message, trait,\ninterface, or public signature, land that shape **first, alone, serially**.\nFanning out before the shape exists produces N incompatible versions of it and\nan unmergeable wave. This is the single most common way a parallel plan fails.\n\nWhat belongs in the contract wave, by stack:\n\n| Stack | Land first |\n| --- | --- |\n| TypeScript | shared types and interfaces, runtime schemas, discriminated-union variants, barrel\u002Fexport surface, public signatures |\n| Python | protocols and ABCs, dataclasses and model classes, enums, public function signatures, package exports |\n| Rust | traits, enums and their variants, public struct fields, error types, `Cargo.toml` members and feature flags |\n| Frontend | design tokens, component prop types, route definitions, API client types, shared state shape |\n\nThe contract wave is a normal lane in every other respect: one worker, real\nproof, a commit. Dispatch it with a type-first brief — the `implement` skill's\ntype-first method and the matching `implement-\u003Clanguage>` orientation already\ndescribe how a worker executes it. Merge it, verify it, and only then plan the\nfan-out against the shape that actually landed.\n\nIf a later lane discovers the contract is wrong, that is a `gap` coming back to\nyou, not a licence for that lane to change the shared shape. Amend the contract\nin a serial step and re-dispatch.\n\n## Sizing and fan-out\n\n- One `delegate` call takes **1..6** entries. `concurrency` (default 4) caps how\n  many run at once.\n- Prefer 2–4 lanes per wave. Six lanes that each need review is usually slower\n  end to end than three that do not.\n- Size a lane to one worker's context: a handful of files, one coherent\n  behavior, one proof command. A lane that will exhaust its context returns a\n  `gap` and you pay for the work twice.\n- More waves with fewer lanes beats one wide wave, whenever a later lane can\n  read an earlier lane's landed code instead of guessing at it.\n\n## Write the lane brief\n\nEach lane's `task` is a contract. The worker loads `implement`, which expects\nthese fields, so supply them explicitly:\n\n```text\nrequirements: REQ-1 ... (numbered, so evidence and gaps can cite them)\nwrite scope:  exact paths this lane may change\nread scope:   paths to read for context, explicitly read-only\nproof:        the command(s) that must pass, and what they cover\nbranch:       the branch to commit on\ncommit:       message style and any required trailers\nhandoff:      done | gap | blocked, per the implement skill\n```\n\nAdd the two fields that only exist because the lane is running in parallel:\n\n```text\nconcurrent lanes: \u003Cwhat else is running, in one line each>\ndo not change:    \u003Cshared files owned by another lane or by the contract wave>\n```\n\nRules for the brief:\n\n- Never give two lanes in one wave overlapping write scopes. This is the\n  invariant the whole plan rests on; check it before dispatching, not after.\n- Tell the lane what it may **not** touch, by path. A worker that hits a\n  compiler-forced ripple into another lane's file must return a `gap`, and it\n  can only do that if it knows the boundary.\n- Do not paste sibling lanes' plans into a brief. One line of awareness prevents\n  duplicate work; a full copy invites a worker to implement its neighbour's job.\n- Keep `clone_mode: \"task_only\"` or `\"snippet\"` for lane dispatches. A lane\n  brief is self-contained by construction, and `full` copies your entire\n  orchestration history into every worker.\n\n## Isolation: one branch and one worktree per lane\n\n**Default strategy: `branch-worktree`.** Give every lane its own branch, checked\nout in its own worktree under `\u003Crepo>\u002F.worktrees\u002F`, let its worker commit there,\nand integrate by merging branches. This is ordinary Git. The history is real,\nthe work survives a crash, `git log`\u002F`bisect`\u002F`revert` keep working, and the\nmerge step has something to merge.\n\nThree strategies exist. Choose deliberately; the choice decides how you\nintegrate.\n\n| Strategy | Set | Lane produces | Use |\n| --- | --- | --- | --- |\n| **`branch-worktree`** (default) | `worktree: false` + per-run `cwd` into a worktree you provisioned | **commits on a branch that persists** | almost always; required for squash merges, review, and nesting |\n| `patch-capture` | `worktree: true` | a **patch file**; branch and worktree are deleted | short throwaway waves whose history is worthless |\n| `shared-checkout` | neither | edits in place | serial lanes, or read-only fan-out |\n\n### `branch-worktree` — the default\n\nLoad `delivering-work` for the procedure.\n\n### `patch-capture` (`worktree: true`) — available, lossy\n\nThe extension creates one temporary worktree per run from the current `HEAD`,\nrejects per-worker `cwd`, captures committed and uncommitted work as one\ncumulative patch, and removes the branch and worktree unless capture fails.\n\nThe patch is the only durable artifact. Because capture runs `git add -A`, stray\nunignored files land in it. It preserves no commit history and cannot nest. Use\nit only for a short independent wave you deliberately want as patches;\notherwise prefer `branch-worktree`.\n\n### `shared-checkout`\n\nDo not run two writing lanes concurrently in one checkout. There is no\nisolation; the last write wins and neither worker knows. Read-only lanes\n(`scout`, `reviewer`) are safe to fan out this way and usually should be.\n\n## Seed lane checklists\n\nIf a lane has more than one step worth tracking and its worker has a\n`session_tasks` claimant, seed its durable checklist when you cut the dispatch.\nWithout a claimant, the handoff becomes a prompt checklist only; it is not durable\nand has no subtree progress to read:\n\n```ts\ndelegate({\n  runs: [{\n    name: \"lane-a\",\n    agent: \"worker\",\n    task: \"Complete lane A.\",\n    handoff: { tasks: [{ title: \"Inspect\" }, { title: \"Implement and verify\" }] },\n  }],\n})\n```\n\nWhen the worker loads a `session_tasks` claimant, the handoff seeds a durable\nlist; read the lane subtree with `session_tasks action=subtree` to see progress\nrather than asking the worker for a status update. Without a claimant, the worker\nreceives a prompt checklist only: it has no durability or subtree progress. A\n`blocked` row includes either its reason or, when the event budget cannot retain the\nfull reason, an explicit `…` truncation marker. Act on a real reason; investigate\nor escalate a marker-only row.\n\n## Dispatch\n\nBefore starting an `implementer` on multi-file work with no plan artifact, warn\nonce: planner-first work averaged 2.7 review rounds versus 5.7 without a plan\n(n=31 with a plan, n=15 without). Advisory, not a gate.\n\n```ts\ndelegate({\n  concurrency: 3,\n  runs: [\n    { name: \"\u003Clane-a>\", agent: \"implementer\", task: \"\u003Clane brief A>\", cwd: \".worktrees\u002F\u003Cplan>-a\",\n      mode: \"supervised\", clone_mode: \"task_only\", escalation: \"local\", rounds: 6 },\n    { name: \"\u003Clane-b>\", agent: \"implementer\", task: \"\u003Clane brief B>\", cwd: \".worktrees\u002F\u003Cplan>-b\",\n      mode: \"supervised\", clone_mode: \"task_only\", escalation: \"local\", rounds: 6 },\n  ],\n})\n```\n\n- **Name every lane.** `name:` is the key you will use to steer, cancel, or\n  recover that lane, and it is what you will read in the widget and in the\n  completion result. Name it after the work — the lane id, issue reference, or\n  component — never after the agent. Two unnamed `implementer` slots come back\n  as `implementer` and `implementer#2`, which tells you nothing about which one\n  failed. This is your responsibility, not the tool's: without `name:` the\n  runtime can only derive a label from the task text, and lanes briefed from the\n  same file are indistinguishable to it.\n\n- **Dispatch in the background.** It is the default. The call returns a `runId`\n  and the combined result wakes you when every lane finishes. Never poll\n  `delegate_control(action=\"status\")`, never `sleep`. End your turn and let the wake arrive.\n- **Enable `escalation: \"local\"` on writing lanes.** A lane that hits a\n  cross-lane decision must be able to reach you instead of guessing. Escalation\n  requires background dispatch; `await: true` is rejected when any slot resolves\n  to enabled.\n- **Do not steer routinely.** Steering a lane mid-flight usually means the brief\n  was wrong. Fix the brief and re-dispatch rather than negotiating through\n  `delegate_control(action=\"steer\")`.\n- Dispatch one wave per call where you can. A single call gives you one\n  completion wake and one place to compare results; two overlapping calls give\n  you interleaved wakes and no natural integration point.\n\n## Integration\n\nIntegration is mechanical and serialized. It is not a place for judgement.\n\n**Order.** Apply lanes in the order you planned them, not the order they\nfinished. Completion order is nondeterministic; planned order is reproducible\nand reviewable.\n\n**Serialize per target.** One merge into one branch at a time. Never apply two\nlanes concurrently to the same branch, at any depth.\n\n**Preflight, all-or-nothing.** Before applying anything:\n\n1. Collect each lane's changed paths.\n2. Confirm each lane changed only its declared write scope. A lane that\n   exceeded scope is a finding, not something to clean up silently.\n3. Confirm no two lanes changed the same path. If they did, the plan's\n   invariant broke — stop, do not merge the \"safe subset\", and re-plan or\n   escalate.\n\n**Pick one apply strategy for the wave and name it in the merge brief:**\n`squash`, `merge`, `cherry-pick`, or `apply`.\n\nLoad `delivering-work` for the procedure.\n\n**Delegate the merge when it is more than trivial.** A compatible development-tool\npackage's `integrator` agent exists for exactly this and loads\n`merge-coordinate`, the narrow contract:\nsupplied sources, a declared strategy, a supplied path whitelist, an\nall-or-nothing preflight, a small taxonomy of resolvable conflicts, and\nescalation for everything else.\n\n```ts\ndelegate({ runs: [{ agent: \"integrator\", mode: \"supervised\", clone_mode: \"task_only\",\n                    task: \"\u003Cmerge brief JSON>\" }] })\n```\n\n`merge-coordinate` defines the brief's JSON shape and repeats the preflight\nabove against real Git state, so a decomposition error surfaces there too rather\nthan only in your bookkeeping. The integrator returns `success`, `partial`, or\n`escalate` — treat `escalate` as the safety mechanism working, not as a failed\nrun.\n\n**Verify after integrating, not per lane.** Each lane proved itself against the\nbase commit in isolation. Only the integrated tree proves they compose. Run the\nrepository's real gate — its `check`, test, typecheck, and lint commands — after\nthe wave lands, and treat a failure there as the wave's failure, not the last\nlane's.\n\n**Stale parent.** If the integration branch moved after a lane branched (an\nearlier lane landed, or a sibling orchestrator merged), re-check that lane\nagainst the new head before applying it. A lane that no longer applies goes back\nas a remediation dispatch with the conflict as its input. Never hand-edit a\nworker's output into applying; you would be implementing, unreviewed, in the\norchestrator.\n\nLoad `delivering-work` for the procedure.\n\n## When a lane does not come back clean\n\n| Signal | Action |\n| --- | --- |\n| `delegate:fork-failed` wake with `recoveryAvailable: true` | `delegate_control({action: \"recover\", runId, forkName, strategy: \"auto\"})` for **that lane only**. Healthy siblings continue; the aggregate wake still arrives once. |\n| `status: gap` | Read what is missing. Dispatch a follow-up lane with a brief that names exactly the gap, or widen scope deliberately and re-dispatch. Do not finish it yourself. |\n| `status: blocked` | Fix the cause at your level: supply the missing input, make the decision, land the prerequisite. Then re-dispatch. |\n| Escalation raised | `delegate_escalation(action=\"list\")` to re-read canonical state, then resolve inside your authority or pass it up with action `pass_up`. Never infer the operator's answer. |\n| Lane exceeded write scope | Do not merge it. Either re-dispatch with corrected scope or accept the wider scope explicitly and re-plan the wave whose invariant it broke. |\n| Two lanes touched one file | The cut was wrong. Re-plan; the merge is not the place to fix a decomposition error. |\n\nPartial waves are normal. Merge the lanes that came back clean, keep the\nintegration branch green, and re-dispatch the rest. Do not hold a whole wave\nhostage to one lane.\n\n## Nesting (provisional)\n\nA lane can itself be a body of work. Then its worker is an orchestrator: it\nloads this skill, cuts its slice into sub-lanes, and returns one collapsed\nhandoff to you. The tree is orchestrator → orchestrator → worker.\n\nRules that already hold:\n\n- **Depth is budgeted.** Nested delegation obeys `maxSubagentDepth` (default 2;\n  a fresh root may set a deliberate higher value up to the hard ceiling of 16;\n  descendants may tighten but never raise it). A detached `driver` root\n  keeps its minimum of 3. Plan the depth you need before dispatching, and give\n  each level an agent whose `allowNestedDelegate` and `nestedDelegateAgents`\n  permit its children.\n- **Each level integrates only its own children.** A sub-orchestrator merges its\n  sub-lanes into its own branch and hands you one result. It never merges into\n  your branch, and it never reaches past you.\n- **Each level reports one handoff upward**, in the same `done`\u002F`gap`\u002F`blocked`\n  shape a worker uses. Depth must not multiply the reporting surface.\n- **Isolation must follow the tree.** Today only caller-provisioned worktrees\n  can do this, because `worktree: true` always branches from the main checkout's\n  HEAD and rejects per-run `cwd`.\n\nTwo or three levels is a real plan. Deeper is speculation: every level adds a\nbrief that can be wrong, a merge that can conflict, and a summary that can lose\ndetail. Keep the tree shallow until #136 makes provisioning and lineage\nfirst-class, then revisit.\n\n## Worked example\n\nA change adding a new record type to an API, its client, and its docs.\nPlan id `records`; integration branch `records\u002Fintegration`, branched from `main`.\n\n```text\nwave 1 (contract, serial)\n  lane types    branch records\u002Ftypes    .worktrees\u002Frecords-types\n    write: src\u002Ftypes\u002Frecord.ts, src\u002Ftypes\u002Findex.ts\n    proof: npm run typecheck\n  → squash-merge into records\u002Fintegration, verify, then branch wave 2 from its head\n\nwave 2 (fan-out, 3 lanes, disjoint scopes, all branched from records\u002Fintegration)\n  lane server   branch records\u002Fserver   .worktrees\u002Frecords-server\n    write: src\u002Fserver\u002Frecords\u002F**, tests\u002Fserver\u002Frecords\u002F**\n  lane client   branch records\u002Fclient   .worktrees\u002Frecords-client\n    write: src\u002Fclient\u002Frecords\u002F**, tests\u002Fclient\u002Frecords\u002F**\n  lane docs     branch records\u002Fdocs     .worktrees\u002Frecords-docs\n    write: docs\u002Frecords.md\n  do not change (all three): src\u002Ftypes\u002F**\n  → preflight, squash-merge server → client → docs, then npm run check on the result\n\nwave 3 (serial)\n  lane wiring   branch records\u002Fwiring   .worktrees\u002Frecords-wiring\n    write: src\u002Fserver\u002Frouter.ts, src\u002Fclient\u002Findex.ts\n    (both are shared files; that is exactly why they are not in wave 2)\n\nclose out\n  merge records\u002Fintegration into main, remove the four worktrees,\n  git branch -d each lane branch\n```\n\nThe wiring lane exists because two files could not be assigned to a single wave-2\nlane. Naming them in wave 3 is cheaper than discovering them in a merge.\n\n## Checklist\n\nBefore you dispatch a wave:\n\n- no two lanes in it write the same path;\n- every shared shape they depend on has already landed and been verified;\n- every brief carries requirements, write scope, read scope, proof, branch,\n  commit, handoff, concurrent lanes, and do-not-change;\n- every lane slot has a `name:` describing its work, not its agent;\n- the isolation strategy is named, and every lane's worktree and branch exist and\n  are branched from the same integration-branch head;\n- the apply strategy (`squash`, `merge`, `cherry-pick`, `apply`) is chosen;\n- writing lanes have `escalation: \"local\"`, and the dispatch is in the\n  background.\n\nBefore you call the work done:\n\n- every lane returned a terminal handoff, and every `gap` is either closed or\n  reported upward;\n- integration applied lanes in planned order, serialized, with no invented\n  conflict resolution;\n- the repository's own gate passed on the **integrated** tree;\n- every worktree and branch you provisioned is removed or deliberately kept;\n- your own report upward is one handoff, not a transcript of the wave.\n",{"load":24,"name":5,"description":7,"disable-model-invocation":20},"recognition","main","a341ec69437d028e71ea1de51b7f6d9c1238048b","packages\u002Fpi-delegate\u002Fskills\u002Forchestrate-work","https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI\u002Ftools","https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI","https:\u002F\u002Fwww.centerforairesearch.org\u002F","CAAIR develops applied AI systems that support civil society, public accountability, and democratic infrastructure.","2026-11-12 02:15:25",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add CenterForAgenticAI\u002Ftools --skill orchestrate-work",{"tool":39,"command":40},"bunx","bunx skills add CenterForAgenticAI\u002Ftools --skill orchestrate-work",{"tool":42,"command":43},"pnpm","pnpm dlx skills add CenterForAgenticAI\u002Ftools --skill orchestrate-work","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI\u002Ftools\u002Fblob\u002Fmain\u002Fpackages\u002Fpi-delegate\u002Fskills\u002Forchestrate-work\u002FSKILL.md",true,[],[48,55,62,69,76,83],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":19},"01M7DBS96C51VE1KHCM1N0SR47","work-execution","Execute a validated pi-work node or wave when you need the ready-set, by-reference work_plan brief, Fabric default, pi-delegate fallback, explicit tree-bound verification, remediation, scope amendments, or a post-integration refactor pass. Use after decomposition and before claiming any node is done.","https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI\u002Ftools\u002Fblob\u002Fmain\u002Fpackages\u002Fpi-work\u002Fskills\u002Fwork-execution\u002FSKILL.md",[],[],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":19},"01M7DBS2SJ4ZND4SG77JX66BWK","work-decomposition","Turn a validated pi-work intent into a strict workspec work graph when the work is too large for one bounded worker. Use when assigning criterion homes, dependencies, honest write scopes, open decisions, or optional model-change nodes before planning execution.","https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI\u002Ftools\u002Fblob\u002Fmain\u002Fpackages\u002Fpi-work\u002Fskills\u002Fwork-decomposition\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M7DBRXT98J0Q84K38FCFQ9VT","work-authoring","Draft a pi-work workspec when an outcome, scope, or proof obligation is still unclear. Use this before turning a conversation, issue, or design into a markdown draft, especially when acceptance criteria need to survive lossless promotion into strict YAML.","https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI\u002Ftools\u002Fblob\u002Fmain\u002Fpackages\u002Fpi-work\u002Fskills\u002Fwork-authoring\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M7DBRST29F8J729DHGCM55WJ","intent-records","Draft or approve an intent record when a person asks for a change, or describe existing behaviour before retrofitting compiled intent. Use before turning intent into a pi-work workspec.","https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI\u002Ftools\u002Fblob\u002Fmain\u002Fpackages\u002Fpi-intent\u002Fskills\u002Fintent-records\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M7DBRNVNYBW7K25Y7W7CYVEA","intent-conformance","Connect an approved finite Bend model to actual application code with a language-neutral conformance manifest, app-language oracles and a broken-model control. Load when proving implementation parity or diagnosing decision drift.","https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI\u002Ftools\u002Fblob\u002Fmain\u002Fpackages\u002Fpi-intent\u002Fskills\u002Fintent-conformance\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M7DBRH9KT2DMXVT16P1JCHQK","compiled-intent-model","Author or change a finite Bend model from an approved intent record, review its meaning, obtain human law approval, and produce an offline-verifiable Jev receipt. Load for model-change nodes, not for emergent runtime behaviour.","https:\u002F\u002Fgithub.com\u002FCenterForAgenticAI\u002Ftools\u002Fblob\u002Fmain\u002Fpackages\u002Fpi-intent\u002Fskills\u002Fcompiled-intent-model\u002FSKILL.md",[],[]]