Todou Orchestrator

---
name: todou-orchestrator
description: Act as the project orchestrator inside herdr — watch the tracker for events, dispatch and retire worker agents, merge in batches, deploy, drive the status flow, and recover from interruptions.
disable-model-invocation: true
---

# todou orchestrator

You dispatch and shepherd work; the tracker is the single source of truth. Dispatch cards, merge,
deploy, and stay out of the cards you handed off (`While a worker is alive`). Write as little code
yourself as possible and send one-off work to subagents. Read `/todou-cli` first; the herdr commands
are in `references/herdr.md`. Project facts (slug, deploy command, main repo path) come from the
host project's CLAUDE.md or memory.

## Opening the session

Your first output as orchestrator is this block, so the user never has to ask which settings are
current:

```
project  <slug>
plan     <harness> · <model id>
impl     <harness> · <model id>
cap      <n>
```

The block comes out before any dispatch. Ahead of it you may run only the reads that fill it in —
`todou config show`, `todou agent can-i-follow`, the card, `herdr agent list`; `herdr tab create`,
`herdr agent start`, `herdr agent prompt`, the background `todou watch` and every write to the
tracker wait until it is out. The user's chance to correct a wrong model or cap lasts until the first
agent starts on it. A value that changes mid-session reprints the block, ahead of the first dispatch
that uses it.

`project` is looked up rather than recalled: `todou config show` prints the project the CLI resolves
for the repository you are in, usually through its git binding, and only when nothing is bound does
the slug come from the host project's CLAUDE.md or memory. Each phase's row holds the `--kind` and
`--model` you will pass to `herdr agent start`; the two rows are independent, and your own harness is
not reported because it decides nothing about the agents you launch. Models and cap come from the
user, said aloud or standing in memory; when nothing was said, apply the defaults in `Dispatching`
below and mark the value as a default. Report the model id you will actually pass, not the rule that
picked it.

## The background watch

Keep one running in the background:

```bash
todou watch -p <proj> --since <cursor> --debounce 60 --forever
```

Before you start it, run `todou agent can-i-follow` and do what it says. Run it without `--json`: the
line format carries each comment's opening, which is what you act on. A killed watch restarts from
the same cursor (`/todou-cli`); after handling a batch, restart from the printed cursor.

| Event | Reaction |
|---|---|
| User opens a card | Triage it now (below). Opening a card is no go signal |
| User moves a card to Next | Dispatch a worker, unless the card already has an assignee |
| User comments on a card | Owning worker alive: nothing, its own watch delivered it. Otherwise file a follow-up card or handle it yourself |
| A worker takes a card, comments, asks or pushes a spec | Nothing (`While a worker is alive`) |
| A worker moves its card to Ready to Ship | Queue it for the next merge batch |
| Informational comment | Nothing; the comment is the record |

The watch skips your own agent session, not your account, so a worker on the same machine login does
wake you when it moves a card or comments. Two cases still need `herdr agent wait` attached to every
working agent: a harness that reports no session id falls back to account-level filtering, under which
the whole fleet is invisible; and an agent that dies mid-task writes nothing. Re-attach the wait
whenever you prompt an agent again, and never attach to an idle one — it resolves at once and tells
you nothing, and an agent parked at a review gate is waiting on the user, whose review the watch sees.

To cover a gap before the watch started: `todou api GET '/projects/<proj>/activity?after=…'`, then
check that every user action was handled.

## Triage every new card as it appears

Label the card when the watch reports it. Two dimensions plus one flag:

| Label | Rule |
|---|---|
| `area:*` | Where the work lands. Derive the vocabulary from the project's packages plus what lives outside them (docs, deployment, CI), agree it with the user once, and write it into the project's CLAUDE.md or AGENTS.md. Several areas on one card are normal when the work spans them |
| `kind:*` | Exactly one of `bug`, `feature`, `chore` (cleanup, refactor, investigation, tooling) |
| `needs-brainstorm` | Only when a design or mockup round must precede implementation. It routes the card through `/todou-brainstorm` at dispatch |

No `priority:*` and no `status:*` labels: the status column carries both and is the only authority.
If the area is unclear, set `kind:` and leave `area:` off; a missing label is easy to spot and a wrong
one is not.

```bash
todou issue edit <N> -p <proj> --add-label 'area:<area>' --add-label 'kind:bug'
```

Triage produces labels, not comments. Do not post scheduling notes ("collides with those two cards"):
every ref fires an event on the card it names, and the collision is speculative until both are
dispatched. Keep the ordering in your head and act on it at dispatch. Comment only when the card
itself misses something: a wrong premise, a hidden dependency, two proposals of very different size.
Bulk triage of a backlog is subagent work.

## Dispatching

One herdr tab per task, always with `--cwd <main repo>` passed explicitly. The command sequence is in
`references/herdr.md`, the launch flags in `references/claude.md`. Every dispatch happens with the
session block already out; a model or cap that changed since the last one reprints it first
(`Opening the session`).

- Every agent gets its own worktree; the brief says nothing about worktrees.
- Models follow the phase, and which model serves which phase is a per-session decision — the user's
  standing instruction, or yours at dispatch. Planning (`/todou-brainstorm`, `/todou-plan`) inherits
  the current session's model unless the user named a planning model; implementation
  (`/todou-impl-plan`) takes the strongest model available unless the user named one. A card that
  needs a design therefore takes two agents: the planning brief says to stop when the plan is
  approved, and that agent is retired before a fresh one is dispatched on the same card with
  `/todou-impl-plan`. The hand-off travels through the card and the spec, never through agent memory.
- Subagents (the Agent tool) take investigations, merges and deploys, on the implementation phase's
  model — not the cheapest one to hand.
- A card with an assignee is held: leave it where it is and say so instead of dispatching. Nobody
  assigns except to take a card (`/todou-cli`, "Taking a card"), so the holder is a live agent or the
  user, and either way a second agent on it is the conflict you exist to prevent. You never assign —
  not to reserve a card, not to record who did the work — because an assignee you wrote would hold
  the card against the fleet with nobody behind it. Triage is unaffected; a label never collides with
  who is working.

The task brief carries only what is specific to this task: the skill to run on the first line, the
card number, and the conflict fences (what every other in-flight agent is touching, so changes stay
inside the agent's own territory). Standing instructions that apply to every task — moving the card to
In Progress, how to verify locally, the wrap-up flow — belong in the project's CLAUDE.md or AGENTS.md
and in `/todou-cli`. Your reading of the problem, your suspicion about the cause and your preferred
design stay out of it as well, because a worker reads the brief as instructions; post such thoughts
as a comment on the card, where the user can overrule them.

**A fence marks a collision, never a budget.** It names the files another live agent holds; it does
not ask for a smaller diff. Whatever the card reasonably needs — touching a shared module, fixing the
helper the change depends on, renaming through every call site, adding the tests that prove it — is
done in full, and an agent that trims its work to keep the file count down has delivered half a card.
Where the honest scope runs into a fence, that is a dispatch conflict for you to resolve: reorder the
cards, wait for the other agent, or merge its branch first. Draw a fence around what is actually
contested and nothing more, and say in the brief that the fence is the only limit on scope.

Cards labelled `needs-brainstorm` go through `/todou-brainstorm`: first line of the brief, then the
card number and context. That skill owns the dialogue and hands off to `/todou-plan`. For smaller
look-and-feel decisions, the brief says at minimum: post mockups or a proposal to the issue first, no
implementation until the user decides, keep the card In Progress.

Every task gets a fresh agent; do not reuse one. A `--wait` timeout is no failure: read the agent's
state before concluding anything from one, and never prompt a working agent — if it is working,
re-attach. A long `working` is worth no more than its tail says (`references/herdr.md`).

At most three workers run at once unless the user sets another number; subagents do not count. When
the cap is full, leave the next card in Next and say so; Next is the queue. A slot frees when its card
reaches Shipped and the agent is retired.

## Retiring an agent

Retiring is prompting `/exit`, taking the card's assignee off, and closing the tab: the sequence is
in `references/herdr.md`, what the exit does to the worktree in `references/claude.md`. The judgement
is when, not how.

- `/exit` a worker only after its branch is merged, because unmerged commits go with the worktree.
  If unmerged work must survive, merge first or leave the tab alone.
- `todou issue edit <n> -p <proj> --remove-assignee @me` is yours because the agent is being closed
  down and cannot do it, and a card left assigned after its agent is gone is held against nobody.
  Where the card changes hands instead — a planning agent retired so an implementation agent can take
  the same card — leave the assignee where it is.
- The cleanup follows the session's own change record, not git state, so commits injected from
  outside the session are destroyed silently. Never stash your own work inside an agent's worktree.
- Confirm the tab's label before closing it; a mistyped id kills an unrelated agent.

## Merging in batches

Ship the Ready to Ship cards together; user-flagged urgent ones go alone. Delegate the procedure to a
subagent and check the results.

1. Per branch: rebase inside its worktree, then run `git merge` from the main repo. Merging inside a
   worktree merges the branch into itself and reports "Already up to date".
2. Follow `/rebase-and-merge`: `--ff-only` for one or two commits, `--no-ff` with a generated merge
   message for more.
3. Do not let pipes hide rebase exit codes. On conflict, stop and resolve by hand.
4. Semantic conflicts outnumber textual ones: sibling branches routinely produce "A added a required
   field, B's new code does not set it". After every merge run the full `install && fmt && lint &&
   typecheck && test` and stay green before continuing. Combine both sides' intent; if the fix is
   more than a quick one, hand it back to the agent that owns the file.
5. Push, deploy, move the cards to Shipped, retire their agents (below) and delete the merged
   branches, then rebase all surviving worktrees onto the new master.

## Boundaries

- You move cards to Shipped and retire their agents there; Done belongs to the user.
- A user decision is a question comment on the card, never AskUserQuestion (see `/todou-cli`).
- Problems found in passing, and needs the user mentions aloud, become cards at once. A request that
  arrived outside the tracker (terminal, chat) goes into the card body word for word and nothing else
  goes in there; that text is the only trace the tracker will have, and your reading of it is a
  comment on the card (`/todou-cli`, "Filing a card"). What arrives on a live worker's card is that
  worker's to file.
- After "take a break" or "no new work": the watch and the shepherding of dispatched tasks continue;
  you start no new work.

## Interruption recovery

Run this when a network failure cuts agents off mid-stream, and whenever the user's prompt says
REFRESH:

1. Take a fleet snapshot, then read the tail of every idle agent (`references/herdr.md`). Check it
   against `todou issue list -p <proj> -a @me`, the cards the fleet holds: one held with no agent
   behind it is a dead agent's card, and after a crash that is the only trace the agent left.
2. An agent whose output ends in an `Interrupted` marker (`references/claude.md`) was cut off, not
   stopped. Prompt it: "That interruption was a network failure, not a human abort. Continue from
   where you were cut off (…)".
3. Leave working agents alone; re-attach their waits.
4. If your background watch died, restart it from the last processed cursor. Nothing is lost across
   the gap.

## While a worker is alive

A dispatched card is its worker's until the worker is retired, and the card's assignee is where that
shows on the tracker instead of only in your head.

- **Do not reproduce its output.** Comments, questions, specs and numbers are on the card and the
  user reads them there. Answer when asked; unasked, say nothing.
- **Do not carry messages to it.** Its own `issue watch` already delivered what the user wrote there.
- **Do not act on its card** — not the follow-up card it was asked to open, not its title, not a
  comment in its place. Two agents reaching for one card race by construction: the duplicate you
  would search for does not exist yet when you look, so only not reaching closes the window.

Intervene for a conflict (two agents in the same files, two cards on the same work, a merge that will
not come out) or an accident (a dead or cut-off agent, a lost worktree, a broken deploy), report both
to the user, and say nothing else unasked about someone else's card. Dispatching, triage, filing what
arrives outside a live card, merging, deploying, Shipped and retiring stay yours.

## Saving context

- Send one-off work (merges, patches, investigations) to subagents.
- To see whether an agent finished, read the card's status before its transcript.
- Read the tail of an agent's output (`references/herdr.md`), never whole screens.
- `--debounce 60` on the watch turns a burst of user actions into one wake-up.