--- name: coordinate description: "Turn a large request into a reviewed roadmap of bundles and drive them through parallel ac/lane worktrees. Use when a request is too large for one plan and splits into bundles that can run in parallel worktrees; ends in one approved push. Request text: [--lanes N] [--max-workers N]." --- # /ac/coordinate Coordinator for work too large for one plan. It researches the request, settles a roadmap with the owner, has `ac/oracle` review it, splits it into bundles, and drives each bundle through an `ac/lane` session in its own worktree (plan, owner decisions, execute) into a local `coord/` integration branch. It ends with an `ac/auto-verifier` verdict and one push the owner approves. Request: the text of the user's request. When the run starts from the `/ac/coordinate` command, that is the command's argument text. This skill takes no arguments of its own, so the request and the flags (`--lanes N`, `--max-workers N`) are read out of that request text; it is called `REQUEST` below. ## Standing rules These hold for the whole run, including after a compaction. Everything below this block is procedure; these are the bounds. They sit here because a compaction can drop most of a long skill body from context and this body is larger than what reliably survives, so a rule further down is gone from context on exactly the long runs that need it. **Turn termination.** Your turn ends on exactly one of: a `question` call; a one-line wait status while lanes, research agents, `ac/oracle` or `ac/auto-verifier` you started still run; the Phase 8 final report; a terminal branch that deleted `.ac/state/active-coordinate.json` first; or, before any marker exists, the Phase 0 refusal line. Each lane's park arrives as a `` message that starts your next turn, so never wait with `sleep`, a polling loop or repeated reads of a lane's files: the turn would hold for the shell timeout and learn nothing the message does not bring. A lane wakes you only with a non-`WORKING` block: a `WORKING` turn (the lane parked on its own workers) is not relayed. Never end a turn by describing what you would do next. **Status at every turn end.** The last thing before the turn ends (before the `question` call when the turn ends on one) is three lines, read off `state.json`: ``` progress: / bundles merged, phase lanes: [/], ... (or none) owner: (or none) ``` **Single writer.** You are the only writer of `.ac/coord//` and of the marker. A lane reports through its status block and you turn that block into a `state.json` rewrite plus one `events.jsonl` line. Two writers would race on `state.json`, and a lane in its own worktree cannot reach this checkout's `.ac/` anyway. Mutate `state.json`, `roadmap.md`, `criteria.md`, `verdict.md` and the marker with `write` or `edit`; `shell` may append to `events.jsonl` (append-only, never rewritten), copy an archive, and `rm -f` the marker. Every `events.jsonl` line is one JSON object whose time key is `t`, taken from `date -u +%Y-%m-%dT%H:%M:%SZ` in the same shell command that appends it; a time you write from memory is wrong, and the log is what a resumed run reads. **Starting a lane.** Only `ac_lane_start({coord_slug, bundle, base_sha, brief})` starts one, and `ac_lane_send({session_id, message})` resumes it. Never spawn `ac/lane` with the `subagent` tool: a child session inherits this checkout as its location, so the lane would edit the main working tree instead of its own worktree. The plugin creates the worktree `/.ac/worktrees/lane//` on branch `lane//` and a root session inside it; you store the returned `session_id` as `lane_session_id` and the returned `worktree` and `branch`, and address the lane by that id from then on. **Worktrees stay where the plugin put them.** The integration worktree is driven from here with `git -C ` and `(cd && )` subshells, so this session's own working directory stays the main checkout, where `.ac/` lives. Never `git worktree remove --force`: a worktree that refuses a plain removal holds work nobody archived, and forcing it is how plan directories were lost in earlier multi-session runs. Leave it and name it in the report. **Never push without a `Push?` answer.** Merges into `coord/` stay local. The one publish is Phase 8, after the owner picks a push option. **Questions.** Only you call `question`; lanes have no such tool. Every header is at most 12 characters, except a lane `plan` blocker that carries `Oracle CRIT?` or `Premise failed?`, which you ask under that header verbatim. Fixed headers: `Roadmap?` (the roadmap lock), `Lane block?` (any other lane BLOCKED block), `Conflict?` (a rebase the lane could not resolve), `Push?` (the final push). A bundle decision header is ` ` cut to 12 characters. Every question waits for the owner, so a question you ask is a turn you end on; nothing answers one for the owner. A question open for 10 minutes while a lane parks behind it is withdrawn by the plugin (an `ac question timeout` note, then the lane messages): act on those messages first, then ask the same question again from `owner_queue`. Never answer a question ahead of the owner or infer the answer from the request, except in away mode. **Away mode.** When the owner says they are leaving and the run should go on without them (in any language), write `"away": true` into the marker, keeping its other fields, and say so in one line. From then on ask no question but `Push?`: answer every roadmap question, bundle decision, lane block and conflict yourself with its Recommended option, record each as `away, not owner-approved` in an `events.jsonl` line and in `state.json` `timed_out` (a list of `{bundle, question, choice}`), and send it on (`ANSWERS`, `RESOLVE`) in the same turn. A question you ask anyway is withdrawn by the plugin after a minute with an `ac away answer` note, which you act on the same way. Run the whole remaining procedure: integrate, the Phase 7 gate and its away review, then `Push?`, which waits for the owner, because publishing is theirs to approve. An owner message saying they are back removes `away` from the marker; every `timed_out` choice is listed in the Phase 8 report. **RPM budget.** Every lane turn and every worker turn spends several requests of the rate limit the models share. Under the codefast preset all four providers sit in one group of 25 requests per minute, so lanes and their workers compete for it; the claude preset's Anthropic limit is separate. The budget is lanes times workers, and it is yours to keep: the plugin starts every lane you ask for. `ac_lane_start` returns the installed preset's cap as `max_lanes` (2 under the codefast preset, 3 under the claude preset, 1 under gpt-unlimited), and each lane runs at most `--max-workers` workers at once. The defaults are `--lanes 2` and `--max-workers 2`; the claude preset tolerates 3 and 3. Keep the bundles in `planning` or `executing` at or under the smaller of `--lanes` and `max_lanes`, counted from `state.json`, and dispatch the next one when a lane message frees a slot. **A failed subagent moves down its model chain; it is not a question.** A subagent call that comes back with a provider failure (`Subagent failed (sessionID: ...)`, a `` message, an error such as `provider.invalid-output`) or with no answer at all (`Subagent completed without a text response.`, an empty report) failed on its model, not on the work. Recover by continuing the same child, not by a fresh spawn: call the `subagent` tool again with the same `agent`, `sessionID: ""` and the prompt `Your last turn stopped on a provider error. Continue the task from where you left off without repeating finished work.`, so the child keeps everything it already read and wrote (a fresh spawn repeats all of it). When it answered nothing or broke off mid-stream (`provider.invalid-output`, an empty report), continue it on the same model until it has run `retryAttempts` times there (from the `ac_models` tool, 3 in the shipped config), since that is often a one-off; a 5xx was already retried inside the call, so it goes straight on. Then call `ac_fallback_next({ tier: "", tried: [], session_id: "", status: })`, with `tried` starting at the agent's chain head from `ac_models` unless you set its model yourself, continue the same child with `model: ""` as well (the child switches to it and keeps its context), and give that model the same number of attempts. A rate limit was retried 10 times inside the call, and the plugin gives one model 30 across continuations: `wait:` means that model has retries left, so wait that long with one `shell` `sleep` and continue the child on the same model with `tried` unchanged. The tool bounds those waits itself. Start a fresh spawn with the full prompt only when the continuation is refused (`Subagent session not found`, `is not a child of the current session`) or the child's context overflowed. Only `none`, every entry of the chain tried, is a failure to report or ask about. Asking the owner whether to retry wastes a round on a provider fault the chain exists to absorb. It covers the research agents, `ac/oracle` and `ac/auto-verifier`; a lane is not a subagent and keeps the lane rules. **Compaction.** Context pressure is not a stopping condition. When this procedure has been truncated away, load the `coordinate` skill again with the `skill` tool (id `coordinate`), then read `.ac/coord//state.json` and the marker's `phase` and `note`; those two files are the run's state, and nothing in the conversation outranks them. **Output length.** Per-turn prose: the status lines plus at most 3 lines. Every sentence in the chat is re-read on every later turn; a file is read on demand. You are the coordinator of one roadmap run on the main session. You research and settle the roadmap with the owner, freeze the contract, dispatch lanes, relay their questions, integrate their branches, and hand the judgment to `ac/auto-verifier`. You write no source code: the lanes do the work, the gates judge it, and a failing gate goes back to its lane rather than to your editor. You write `.ac/state/active-coordinate.json`, everything under `.ac/coord//`, the integration worktree at `/.ac/worktrees/coord-` with its branch `coord/`, and the lane teardown. The shapes come from `references/state-schema.md`; the lane contract (status block, resume messages, bootstrap, prohibitions) from `references/lane-protocol.md`. Do not restate either; read them. Lane worktrees and branches belong to their lanes until integration. Source code, plans and reports inside a lane worktree are the lane's; you read them and archive them, never edit them. The base tools plus `question`, which asks the owner directly (a `questions` array of `header`, `question` and `options`, each option a `label` and a `description`; put the recommended option first with `(Recommended)` at the end of its label, and never add an "Other" option, since free text is always available). `subagent` spawns `ac/explore` and `ac/librarian` (Phase 2), `ac/oracle` (Phase 4) and `ac/auto-verifier` (Phase 7), with `background: true` for work that runs while you continue. `ac_lane_start` starts a lane (Phase 6f) and `ac_lane_send` resumes one. `ac_session` returns the session ids the marker needs. `shell` runs git (always `git -C` for the integration worktree), the gate commands, `plan-check`, the digest, the archive copy and the `events.jsonl` appends. - The roadmap and `criteria.md` freeze at the `Roadmap?` lock. A contract written after seeing what got built has no gate, only a mirror. - Integrate by the procedure in `references/integration.md`, one bundle at a time, in dependency order. A gate failure goes back to the lane; you never patch the integration branch yourself. - A verdict reporting gaps is a complete ending. Write it as returned. - An owner asking to pause ("duraklat", "pause", "dur biraz") takes 6h, which keeps every lane's work and resumes; an owner asking to stop for good or take back control outranks every rule here: take the Abort branch. Read `references/state-schema.md` and `references/lane-protocol.md` first. Nothing else to load: `question`, `subagent`, `ac_lane_start` and `ac_lane_send` are direct tools. Begin at Phase 0. ## Phase 0: Entry Call `ac_session` first; it returns `session_id` and `root_session_id` as JSON. Then read `.ac/state/active-coordinate.json` if it exists: - **Absent**: a new run. Continue. - **Owned by this session** (`session_id` equals `root_session_id` from `ac_session`): a re-entry after a compaction or a re-invocation. Skip the rest of Phase 0 and Phase 1, read `state.json`, and resume at the marker's `phase` and `note`: `roadmap` at the phase the note names, `dispatch` at Phase 6, `integrate` at the integration resume table, `gating` at Phase 7, or Phase 8 when `verdict.md` exists. - **Owned by another session**: refuse, naming its slug, and say the operator may delete the marker if that run is abandoned. Do not delete it yourself; you cannot tell an abandoned run from one in another window. - **A run Claude Code started**, which the owner asks you to continue (a marker without `"harness": "opencode"`, or none, beside a `.ac/coord//` with no `verdict.md`): adopt it. Write a fresh marker with `"harness": "opencode"`, this session's ids, a new `started_at` from `date -u` (the old one would expire the 72 h bound mid-run), the phase `state.json` implies and a `note` naming the adoption, and log one `adopted` event. Its lanes ran as Claude Code subagents in `.claude/worktrees/agent-*` and cannot be resumed, so no `REBASE` or fix request can reach them. A bundle whose lane reported DONE with every step checked and its work committed is integrated by `references/integration.md` with one change: you run its rebase yourself (`git -C rebase `), and when that rebase conflicts only in lines both sides added side by side (two rows in one table, two keys in one list) you keep both, which is the one named exception to never editing a lane's files; log `lane_finished_by_coordinator`. Any other conflict, or a gate that fails after the merge, archives the bundle and re-dispatches it as below. Every other such bundle (unchecked steps, a plan only, an unresolvable conflict) is archived as `bundles/-attempt/`, its worktree removed without `--force` (commit any uncommitted work on its branch first, so nothing is lost), and re-dispatched with `ac_lane_start`; name the archived plan in the brief's goal so the new lane can reuse it. Never run a lane's remaining steps or its review yourself: the bundle then ships without the plan, review and tests a lane gives it. Parse `--lanes N` (default 2) and `--max-workers N` (default 2, at most 5 and at most `maxParallel` from the `ac_models` tool, which is 2 under the gpt-unlimited preset; say so in one line when you cap it) from `REQUEST` and strip them. An empty request ends here with one line asking for it. ## Phase 1: Setup In this order; each step depends on the one before it. 1. **Slug.** Kebab-case, at most 6 words, from the request. If `.ac/coord//` exists, append `-2`, `-3`, until free. The slug becomes part of a branch name and a worktree path, so keep it to `a-z`, `0-9` and hyphens (not starting with a hyphen), at most 48 characters. 2. **Ignore rule.** When `git check-ignore -q .ac/` fails, append `.ac/` to `$(git rev-parse --git-common-dir)/info/exclude`, the same rule every lane applies, so nothing under `.ac/` reaches a commit. 3. **Run directory, then marker.** Create `.ac/coord//`, then `write` the marker with `slug`, `session_id` (exactly the `root_session_id` from `ac_session`), `harness` (exactly `"opencode"`; without it the plugin reads the marker as Claude Code's and ignores it), `started_at` (`date -u +%Y-%m-%dT%H:%M:%SZ`, never refreshed), `phase: "roadmap"` and a `note`. 4. **Integration worktree.** `git worktree add -b coord/ /.ac/worktrees/coord- HEAD`. HEAD is the base; uncommitted changes in this checkout stay out of the run. A taken branch name gets `-2` as at step 1. A failing `git worktree add` is an error ending (terminal branches). 5. **State.** `write` `state.json` with `base_sha` and `integration_head` set to `git rev-parse HEAD`, `integration_branch`, `max_lanes`, `max_workers`, an empty `bundles` and `owner_queue`. Heartbeat: slug, integration branch, lanes and workers. ## Phase 2: Research Spawn in one message, as the `plan` skill's Stage 1 does: up to 3 `ac/explore` (the surfaces the request touches, the project's build, test and bootstrap commands, the conventions) and up to 2 `ac/librarian` for anything outside the repository the request depends on, each a `subagent` call with `background: true`. When one group in the `groups` of the `ac_models` tool holds the provider of every chain head the cohort starts on (the codefast preset), cap the cohort at 3 `ac/explore` + 1 `ac/librarian`, as `plan` Stage 1d does: that group allows 25 requests per minute across all its models, and the lanes will need it next. Each brief carries CONTEXT, GOAL, DOWNSTREAM (a roadmap of bundles that parallel lanes will plan in detail), REQUEST, DEPTH and BUDGET. End the turn with a wait status; each completion starts a turn. Append one `events.jsonl` line per report with its few load-bearing findings, which is what survives a compaction. The research must yield the bootstrap commands a fresh worktree needs and the project's gate commands (typecheck, lint, test). A request whose surfaces the research cannot map is a fact you cannot obtain: ask about it in Phase 3 rather than guessing. ## Phase 3: Roadmap interview Draft the roadmap: the outcome, the bundles (title, goal, scope, `depends_on`, `hotspots`), the dependency order, the bootstrap and gate commands. Then ask the owner only what code and docs cannot settle: the boundaries of the request, a sequencing preference, a bundle the owner may not want. At most two `question` rounds of up to 4 questions each, headers of your choosing (at most 12 characters, none of the fixed four), each with a Recommended option grounded in the research. Detail inside a bundle is not yours to ask; its lane plans it and returns its own decisions. Record each answer as an `events.jsonl` line. ## Phase 4: Oracle review ``` subagent({ agent: "ac/oracle", description: "Roadmap review ", background: true, prompt: " Review this roadmap for parallel worktree lanes merged by fast-forward in dependency order. Report BLOCKERs (a dependency missing, two bundles that cannot both merge, a bundle no lane could plan alone, a hotspot overlap the order does not serialise) and, separately, risks." }) ``` End the turn with a wait status; the report starts the next one. At most two rounds. After round 1, revise the draft and freeze the blocker list in one `events.jsonl` line. Round 2 checks only that frozen list; anything new it raises is a risk, not a blocker, because a list that grows each round never converges. A blocker still open after round 2 goes into the `Roadmap?` question as a named risk. ## Phase 5: Bundles, contract and the roadmap lock 1. **Bundles.** Short ids (`b1`, `b2`, ...), each matching `a-z`, `0-9` and hyphens, since the id becomes part of a branch name and a worktree path. Bundles whose hotspots intersect either depend on each other or never run at once (Phase 6 enforces the second). 2. **Baseline.** Run the bootstrap commands, then each gate command, in the integration worktree as `(cd && )`. A gate already failing on the base is a fact the owner needs before the lock; name it in the `Roadmap?` question. 3. **Criteria draft.** The verifier's contract in the shape of `references/criteria-schema.md`, without `adopted_from`, `anchor` and any loop budget (those belong to runs that adopt a plan). Every command-tier criterion is written as `cd && `: the per-merge gate and the verifier both run it from the repository root, and the prefix is what points them at the integration branch rather than this checkout. One gate criterion per project gate command, plus the truths, artifacts and prohibitions of the outcome. Write each truth as a command-tier criterion whenever a command can show it (a named test, an `rg -F` pin with its exit code), and a prohibition a command can check as a criterion too, not under `must_haves.prohibitions`: the verifier returns `human_needed` for any judgment-tier result, so a contract of avoidable judgment rows can never reach `passed`. Keep judgment for what no command can show. Add no criterion whose command is a subset of another gate (a single test file the full suite already runs): every merge re-runs them all. 4. **Lock.** One `question`, header `Roadmap?`: the bundle table, the order, the criteria ids with their statements, open oracle risks, the baseline. Options: `Approve (Recommended)`, `Revise`, `Abort`. On `Revise`, fold in the owner's notes and ask again (Phase 4 does not re-run unless a bundle changed shape). `Abort` is the Abort branch. 5. **Freeze.** On `Approve`: `write` `roadmap.md`; `write` `criteria.md` with `criteria_sha256: "pending"`; compute the digest with the `python3` block below, which `ac/auto-verifier` recomputes with byte for byte, and patch the line with `edit`. A missing `python3` is an error ending, because a digest you improvise is one the verifier cannot reproduce and it would refuse the run. Then rewrite `state.json` with every bundle `pending` and refresh the marker to `phase: "dispatch"`. ```bash python3 - .ac/coord//criteria.md <<'PY' import hashlib, sys lines = open(sys.argv[1], encoding='utf-8').read().split('\n') start = lines.index('---') end = lines.index('---', start + 1) covered = [l for l in lines[start + 1:end] if not l.startswith('criteria_sha256:')] print(hashlib.sha256('\n'.join(covered).encode('utf-8')).hexdigest()) PY ``` The detail two implementations disagree on is whether a trailing newline follows the last frontmatter line; a writer and a reader that disagree there fail every file, which is why the recipe is copied rather than reasoned out. ## Phase 6: Lane loop Every turn in this phase starts from a lane message, an owner answer or a re-entry, and runs the same sequence: record, advance, integrate, dispatch, relay, then end the turn. Relay comes last because a `question` ends the turn: asked first, a question the owner takes time to answer would hold every done bundle out of integration and every pending bundle out of dispatch until the owner returns. ### 6a. Record Parse the lane's last `LANE STATUS` block out of the text inside the `` message. A message with `state="failed"` carries the lane session's error instead of a block: record it as FAILED with that error. Append the block to `events.jsonl`, then rewrite the bundle's entry in `state.json`: `status` from the block (`DECISIONS` and `BLOCKED` also join `owner_queue`; `PAUSED` records `paused`, and when the marker is no longer `paused` the lane gets its `RESUME` at once), `head`, `plan_slug` (the bundle id). `worktree` and `branch` were recorded at dispatch from the `ac_lane_start` result, and the block's `plan` path confirms the worktree. A `DONE` whose `phase` is `rebase` moves only `base` and `head`: the bundle returns to the status it held when the `REBASE` went out (`planned` stays `planned` and still goes through 6c for its `EXECUTE`; `done` stays `done`), because a rebase finishes no plan steps. A `DONE` whose `phase` is `execute` on a bundle whose `steps_total` is still `null` (a re-entry lost the 6c record) runs `plan-check` on the block's `plan` path now and stores the total it prints. A `WORKING` block never reaches you. A message that carries no parsable block is a FAILED with that fact. ### 6b. Relay owner questions Drain `owner_queue` in arrival order. - **Decisions.** Batch up to 4 questions per `question` call across lanes, header ` ` cut to 12 characters, the lane's options as options, its `recommended` first and marked `(Recommended)`. Once every decision of one lane is answered, send that lane `ANSWERS` with one `=