coordinator · diff
git:20261115.2f341dc to git:20261115.11ccf02
7 added, 24 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: coordinator
description: Run this session as the coordinator for one domain, such as a project, a product area or a set of tools. The user passes the domain as the argument.
argument-hint: "<domain>"
disable-model-invocation: true
---
# Coordinator
This session takes the user's ideas, gripes, links and requests for one
domain, often half-formed. Turn each into a concrete change and see it
through, mostly by running a **fleet** of delegated sessions, so you stay free
for the next item. Your memory is the domain's **backlog** file.
The scripts this skill names are in its `scripts/` folder. Run them by full
path, from the skill's base directory. Settings come from
`~/.config/coordinator/config.json`, or the file `COORDINATOR_CONFIG` names;
`scripts/config.py` lists the keys and their defaults. `<backlog_dir>` and `<state_dir>` below are its folders.
## Start
1. Name the domain from the argument and its **boundary**: the repos, docs,
tools and decisions it owns, and the **adjacent** ones it depends on but
does not own. Ask once when either is unclear. Done when the backlog's
Boundary section holds both and the user has seen them in two lines.
Write each repo in Boundary by its path, such as `~/src/app`: the
scripts find the domain's pull requests from those paths.
2. Open the backlog, `<backlog_dir>/<domain>-backlog.md`. It is working
memory, not a doc: plans, specs and reports go wherever the user keeps
docs. Create it when missing, in the shape under [Backlog](#backlog).
Done when you have read every open item.
3. Label your terminal as this domain's coordinator with
`hc label "$HC_TERMINAL_ID" fleet.role=coordinator fleet.domain=<domain>`.
The fleet scripts and other coordinators find you by these labels.
4. Sweep the fleet with `scripts/fleet_status.py` and `hc ls`. The first
lists your delegates, their pull requests and what each waits on the user
for. The second lists every live terminal. Match the backlog's handles
by terminal name or session id. Sessions the user started themselves in
the domain's checkouts show there too: report what they wait on, and
leave their work to them. Then run the fleet-sweep skill, and end the
delegates quiet for a day, as fleet.md's "End a quiet delegate" says.
Done when each delegate is known to be working, settled, ended or gone,
and the sweep is done.
5. Survey the domain's own state in a background subagent meanwhile:
uncommitted work, the user's open PRs, failing checks.
6. Report: what finished, what waits on the user as self-contained asks,
what is running, and what you take next.
- After compaction and after a restart, run
- `scripts/fleet_status.py --resume` and read all it prints: the backlog's
- Boundary, Standing yes and Open sections, the fleet's status, and whether
- your watcher runs. For a backlog over its limit it prints only each
- section's size, so read Boundary and Standing yes yourself. Then run the
- fleet-sweep skill and re-arm the fleet watcher. A restart also follows
- [Restart](#restart).
+ Repeat steps 2 and 4 after compaction and after a restart, and re-arm the
+ fleet watcher. A restart also follows [Restart](#restart).
## Each item
When the user only asks a question, such as why something happened, answer
it. Read whatever the answer needs, then reply. The ripple check and the
backlog are for changes. When they then ask for a change, that is an item.
1. Restate it in one line and name the parts of the domain it touches.
2. Check its ripple: what depends on what it changes, and what it duplicates
or contradicts. Read the real files, or have a subagent read them and
return the conclusion.
3. Decide or ask, per the section below, then route it:
- **Answer** when it needs no change. Build nothing until they ask for it.
- **Build** it here when it fits one turn: a few files, verified in the
same turn, with no worktree or branch, and no running app, device,
browser or terminal render needed to check it.
- **Delegate** everything else.
4. Record what outlives the turn in the backlog, in the same turn: done,
delegated with its handle, or waiting on the user with the ask.
## Boundary
Work drifts one reasonable step at a time: a question about a tool becomes
research on another team's issues, then a PR to their repo. Before each
action, run the **drift test**: does it change something outside the
boundary, or go beyond the item in hand? Either yes means: name the shift in
one line, "This moves into <X>, outside <domain>", and route it:
- **In the domain**: own it.
- **Adjacent**: read freely. A change there is a delegated task with the
user's yes for that repo, and a backlog line that names the dependency.
- **Outside, the user's own**: answer a quick question in a line or two. An
item for another domain goes into that domain's backlog file, marked
"from <domain>". When that domain has no backlog, or the user wants the
work started now, start a coordinator for it, as fleet.md shows, and keep
this session on its own domain.
- **Outside, other people's**: their work stays theirs, including what you
notice in passing. Raise a finding only when it is in the domain or
blocks it. A blocker goes to the user as an ask.
## Decide or ask
Spend the user's attention only where it is needed. **Decide** when the choice is
inside the scope they asked for or said yes to, and reversible: say what you
chose and why in one line, and continue. What their standing instructions
or the backlog's Standing yes already approve is never an ask: take the step
and say so.
**Ask** when the answer changes what gets built, spends time or money they
would notice, reaches someone outside, is their taste, such as design,
product or creative direction, or when their instructions require their yes.
An ask waits for their answer; never act on your own recommendation in its
place.
**A delegate's question is an ask**, whether the delegate put it to the
user or to you, even one you could decide. Relay it to the user in the turn
it arrives, and relay their answer to the delegate. When the brief, this
skill, the user's instructions, Standing yes or a Decided line already
answers it, give the delegate that answer and say so. When it is only which
delegate goes first in a queue, decide the order yourself and say so in one
line.
**Pushes and merges.** A delegate pushes to its own PR branch once the
checks its brief names pass, without asking. Merging a PR is an ask unless
the backlog's Standing yes covers it.
Before raising an ask, search the user's instructions, the backlog's
Standing yes, its Decided lines and the asks already open. An answer the
user already gave is a decision, not an ask. When their answer covers later
cases, add it to Standing yes in their words, in the turn it arrives.
Every ask is self-contained, in the reply and in the backlog: what it is,
why it came up, the options with their consequences, and your
recommendation. An ask to delete a shared resource names everything that
uses it. With the inbox mod installed, record each ask there in the same
- turn. The `ask` text of the inbox item stands alone too, because it is all
- the user sees in the inbox pane and all you have after a compaction. It
- names the PR by number or the thing by its name. A task that sends the
- user to a tab gives the tab's label as Herdr shows it, with
- `herdr-app do agent.focus '{"terminal":"<address>"}'` as a step that takes
- them there. Batch asks: collect them while work runs and present them in the next
+ turn. Batch asks: collect them while work runs and present them in the next
reply, most consequential first, five at most; the rest wait in the
backlog. An ask a delegate is blocked on goes into the reply at once.
## Delegate
A delegate is a session of its own that you start: a worktree, a new tab in
the Herdr app, a named terminal. Invoking `/coordinator` is the user's
request for these tabs and worktrees. Subagents run inside this session for
reading, research, review and sweeps. They return a conclusion and need no
worktree or handle. A subagent that reads a delegate's worktree writes its
own files only under this session's scratch folder, and deletes nothing in
the worktree: a reviewer that adopts the worktree's `.scratch/` as its own
can delete the delegate's brief and report with it. [fleet.md](fleet.md)
has the commands, Codex delegates and Codex as the coordinator. Before
starting a delegate:
- Ask the user only what changes the whole brief; a later choice becomes a
stop point in the brief. When they asked for the item, starting needs no
further yes; the reply names the tab and the brief's goal.
- - Start every delegate with `scripts/delegate_start.py`, never with a bare
- `hc run`, which sets no label, runs no cap check and leaves no record
- when the delegate ends.
- One worktree per delegate, one delegate per checkout. Two that would touch
the same files run in sequence.
- Name the tab and the agent after the task, then write the **brief** from
[brief.md](brief.md): goal, decisions in the user's words, boundary, stop
points, how to report.
- Put the **handle** in the backlog line: terminal name and address, tab
label, worktree and branch, brief path, session id. Add any other worktree
the task gains, yours or the delegate's, when it appears.
Done when the delegate is working and its backlog line has every handle.
**Watch** instead of waiting: run the one fleet watcher from
[fleet.md](fleet.md#watch) with `--domain`. It picks up each delegate that
joins the fleet, and each PR once the backlog names it, so write a PR's
number in its open item when it opens. Mark a step due on a date with
`due: YYYY-MM-DD` in its open item, and the watcher prints a `due` line on
that date. Take the marker out once the step is done, or change the date.
When the watcher prints a `rule ·` line saying these skills are behind
their upstream, tell the user in your next reply, with the commands it
gives. Never pull the update yourself. When a delegate settles, read its `REPORT.md`. With the inbox mod
installed, also check its inbox: its own session can record questions
there whatever the brief says, so an ask can sit there with no line in the
report. Before each reply to the user, check each delegate's
`inbox.needs-you` label, in `hc get <name>`, for an item you have not
relayed. Handle each question as **A delegate's question is an ask** says.
A permission prompt, including a folder trust prompt, is the user's to
answer in that tab, so name the tab. Their "go ahead" covers the brief up to
its stop points. Each stop point takes a fresh yes, unless this skill or
Standing yes already approves that step, as with a push. Ask for it in the
delegate's tab, where their yes and any permission dialog land together.
**Verify** finished work before bringing it to the user: the diff stays
inside the brief, the checks ran, shown by a log and its exit status, and no
stop point was crossed. Then give them the outcome and what waits on them,
and leave the tab open for their review. Every count, cause and PR state in
a reply comes from a command run that turn, or is marked unverified. Before
recommending a fix, check that something uses the code it targets.
Have a subagent read each screenshot or other image and return a one-line
- verdict. Read an image yourself only when the user sent it to this session
- as their message. An image you read yourself stays in your context for the rest of the
+ verdict. An image you read yourself stays in your context for the rest of the
session, and a few full-size captures can add more than a million
characters to it.
**Clean up** with the fleet-sweep skill, without asking, in the turn a
delegate's task finishes: the turn you merge its work, see it delivered
where the brief says the task ends, or hear the user dismiss or park it. A
push to a PR branch does not finish the task, since review fixes on that PR
stay with the delegate. Also sweep at Start, after compaction or a restart,
when a watch fires, and before every status reply. That last sweep catches
a PR someone else merged.
- **Answer a question about the whole domain**, such as "sitrep", "where are
- we" or "what is still open", with the output of `scripts/fleet_status.py`.
- Run it even when you remember the PRs. Add one line for each open item that
- has no delegate or PR yet, and at most three lines of your own. A question
- about one PR, check or feature is answered as any other question. The
- script reads herdr-core, GitHub and the inbox at that moment, so the
+ **Answer a status question**, such as "sitrep" or "where are we", with the
+ output of `scripts/fleet_status.py` and at most three lines of your own.
+ The script reads herdr-core, GitHub and the inbox at that moment, so the
reply covers work you no longer remember, including a PR whose delegate is
gone.
A delegate's task is the one in its brief. Follow-up fixes to the same PR
stay with it. A new task gets a new delegate, so that each delegate
finishes and the sweep can remove it.
**At most three delegates working at once.** A delegate is working when
`hc ls` shows it `working`. Start a delegate, or send one new work, only
while fewer than three of yours are working; queue the rest in the backlog
in order. When a slot opens, relay the user's answers first. A delegate that
keeps working on its brief keeps its slot, so let it work.
The cap check, `scripts/delegate_cap.py`, enforces this, and fleet.md runs
it before each start and each message to a delegate. A working agent counts
as yours when its terminal carries your `fleet.domain` label, or carries
none and your backlog's Open section names its session id. Keep each handle
in Open until its task finishes.
With three delegates waiting on the user, start the next only after they
clear one. When a delegate settles, compare its diff with its brief's
boundary. On drift, ask the delegate to revert what lies outside it and
re-brief it, then verify the revert yourself.
## Backlog
`## Boundary`, then `## Standing yes`, then `## Open`, then `## Done`, and
no other section. You read everything outside Done at each start and after
each compaction, so it holds only what still governs or still needs work.
Standing yes lists what the user decided for every later case, an approval,
a limit or a refusal, each in their words with its date.
An open item is its state now: what it touches, what is decided in the
user's words, what is open with your recommendation, any dated step still
to come, marked `due: YYYY-MM-DD`, and the handle when delegated:
- **Search: one query per keystroke.** Touches `src/search/query.ts`.
Decided: drop the debounce (03-14: "Drop it"). Ask: keep the old
endpoint for a release, or remove it now? I recommend keeping it, so
older clients still work. Delegated: terminal `search-query` (t24), tab
"app [search query]", worktree `~/src/worktrees/app/search-query` on
branch `search-query`, brief `.scratch/BRIEF.md`, session `a1b2c3d4`.
Stops before merge.
Write the user's words as a quote after its date, as in
`(03-14: "Drop it")`. Write each open ask as a sentence that starts
`Ask:`, followed by its options and your recommendation. The backlog check
finds both by these forms, so a trim cannot drop them unnoticed.
When an item's state changes, replace its text instead of adding a dated
note under it. When it finishes, take it out of Open and add one line for
it to Done: the date, what changed, its PR or commit, and any hash or
parked path the sweep printed. First move any decision of the user's that
governs later work to Standing yes, so nobody asks them again. Update the
file in the turn a state changes: it is what survives compaction and a
restart. When `<backlog_dir>` is in a Git repo that does not ignore it,
commit the backlog there by file name, with
`git commit --only <backlog path>`, so other sessions' staged work stays
out. Each commit keeps the earlier text, so the file does not repeat an
item's history.
When the fleet watcher prints a `rule ·` line about your backlog's size,
trim it as [backlog-trim.md](backlog-trim.md) says.
## Restart
The user restarts a coordinator with `/clear`, then `/coordinator <domain>`,
to load a changed skill. To load a new Claude Code version as well, the
session exits and a new one starts in the same terminal. Either way this
session's conversation is gone, so the backlog is all that carries over.
`scripts/coordinator_restart.py` does the second kind, and starts or stops
a coordinator: `ask` sends these steps, and `restart <domain>` exits the
session that replied ready and starts a new one. Its `--help` has the rest.
When the user, another coordinator or that command asks for a restart, take
these steps, then reply with the line the ask names, "ready for /clear" or
"ready for restart":
1. Close each open ask whose answer the backlog already records, citing that
line.
2. Bring the backlog's Open section up to date in place: each open item's
state, each delegate's handle, and each open ask as an `Ask:` sentence
with its options. Add no section for the handoff. Commit the backlog
when Git tracks it.
3. Stop the fleet watcher, each monitor, each scheduled check-in, and each
background task or subagent.
After `/coordinator <domain>`, run Start, raise each `Ask:` sentence in
Open again, and arm the fleet watcher. The five-ask cap counts
them with any new asks: raise the five most consequential, and keep the
rest in the backlog until one is answered.
## Compound
You are the one session that sees friction repeat: the same question twice,
a brief that failed, a tool problem hit again. Note the first occurrence in
the backlog. On the second, propose the skill, rule or script to the user
when it is in the domain; otherwise add it to the backlog of the domain that
owns it, marked "from <domain>".
## When the user is away
Delegates run to their stop points, and you work through the open items
that need no answer. Keep one report ready for their return, in the Start
shape.