Heyvhuang/copybook-skills / standalone/coordinator/skills/coordinator
coordinator
FlaggedCoordinate an ongoing software delivery run when the user assigns this session the coordinator role or asks it to manage worker handoffs, gates, release approvals and progress. Use when starting, supervising or resuming that run, including a run with one active lane. Lanes run as Herdr workers (parallel-goal-fleet) on Claude or Codex, from whichever harness coordinates; T3 Code child tasks are the fallback. Do not start a coordinator run for discussion, a read-only review of the workflow, a standalone quick second opinion or an ordinary single-session edit.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.8 KB |
| references/example-run.md | markdown | 3.4 KB |
| references/herdr.md | markdown | 7.7 KB |
| references/lessons.md | markdown | 6.9 KB |
| references/models.md | markdown | 4.9 KB |
| references/pipeline.md | markdown | 6.1 KB |
| references/situations.md | markdown | 3.4 KB |
| references/t3.md | markdown | 4.9 KB |
| scripts/gemini.mjsexecutable | script | 2.3 KB |
| scripts/heavy.shexecutable | script | 829 B |
| scripts/status.shexecutable | script | 2.0 KB |
| scripts/watch-ready.shexecutable | script | 2.0 KB |
| templates/lane-brief.md | markdown | 1.5 KB |
| templates/release-packet.md | markdown | 1.4 KB |
| templates/run-record.md | markdown | 1.2 KB |
| templates/ship.md | markdown | 1.1 KB |
references/herdr.md
View on GitHub# Herdr in a coordinator run
Herdr is the lane runtime on every host (SKILL.md, Runtime). The mechanics live in the parallel-goal-fleet skill: its `SKILL.md`, `references/herdr.md` (session, worker start, dispatch, waiting, quick reviews) and `references/cleanup.md`. Read the section you need there. This page adds only what the coordinator learned on the example run. Counts from two coordinator transcripts: `agent prompt` 224, `pane read` 126, `agent list` 62, `agent start` 56, `workspace close` 33.
## 0. Full access and providers
Workers start without permission prompts (read the warning in SKILL.md, Runtime). Verified in Herdr 0.9.5:
| Provider | Start | Checked |
| --- | --- | --- |
| Claude | `H agent start <w> --kind claude --pane <p> -- --session-id <uuid> --model <claude-id> --effort <e> --permission-mode bypassPermissions` | status line `bypass permissions on`; wrote outside its cwd without a prompt |
| Codex | `H agent start <w> --kind codex --pane <p> -- -m <codex-id> -c model_reasoning_effort=<e> -s danger-full-access -a never` | fresh pane ran its task in 10.2 s from workspace create, no dialog |
`<claude-id>`, `<codex-id>` and `<e>` come from `references/models.md`; these checks ran with `claude-opus-5-5` and `gpt-6.1-sol`. The first bypass launch of Claude Code asks you to confirm once; answer it in that pane. To keep permission prompts, leave out `--permission-mode bypassPermissions`, `-s danger-full-access` and `-a never`. Lanes then wait at each dialog: read panes on every tick and answer within the brief's scope.
## 1. Host-aware startup
- First reconcile: `H agent list`, the run record's lanes table, panes with unsent text. Reuse what is running; never restart, stop or close another run's server or panes.
- Wrapper used throughout: `H() { env -u HERDR_SESSION herdr --session <run-session> "$@"; }`.
- **Claude desktop app**: start the run's server from the app's terminal panel and show an attached tab every run.
- **Claude Code CLI**: the canonical headless server; attach a TUI in another terminal if someone wants to watch.
- **Codex**: use its own terminal and browser capabilities; Claude panel tools do not exist there.
- A server restart restarts its workers: re-prompt each standing lane with its brief path and queue position.
## 2. Base for writer lanes
```bash
git -C <repo> fetch origin <branch> # read-only fetch of the intended base
BASE=$(git -C <repo> rev-parse origin/<branch>) # or the brief's frozen base SHA
H worktree create --cwd <repo> --base "$BASE" --branch <lane-branch> --path <work>/wt/<lane> --label <lane> --no-focus
```
Record `BASE` in the brief and run record. Keep a deliberately frozen base when the brief pins one. If fetch fails, record "freshness unverified" and use the allowed local ref; never update or reset the shared checkout to fix it (on the example run local `main` was once a day behind `origin/main`). Install dependencies inside the worktree with the project's package manager.
## 3. Talking to a running lane
Decide first whether the message steers, queues or is held (SKILL.md, A lane). A held message isn't sent at all: it waits under Holds in the run record until its evidence or the user's yes is there.
| Lane state | How to send |
| --- | --- |
| Idle | `H agent prompt <name or pane> "<text>"` |
| Busy Codex, steer | `H pane send-text <pane> "<text>"`, then `H pane send-keys <pane> Enter`: it joins the current turn |
| Busy Codex, queue | `H pane send-text <pane> "<text>" && sleep 1 && H pane send-keys <pane> Tab`: it waits for the next turn |
| Busy Claude Code | paste with `send-text`, then `Enter`: it queues and reaches the worker once the running tool calls finish, inside the same turn, so it acts as a correction. `Ctrl+X` then `Enter` (v2.1.247+) marks it to wait its turn without interrupting; `Ctrl+X` then `Ctrl+S` (v2.1.275+) sends the draft and everything queued at once |
| Dialog or menu | read with `pane read --source visible`, then `send-keys Down` / `Enter` within scope |
Sources, read 18 Nov 2026: Codex CLI [developer commands](https://learn.chatgpt.com/docs/developer-commands?surface=cli) (Enter steers, Tab queues; Codex CLI 0.169 here) and Claude Code [queued messages](https://code.claude.com/docs/en/interactive-mode#queue-messages-while-claude-works) and [chat keys](https://code.claude.com/docs/en/keybindings#chat-actions). On the example run the Codex Tab queue and the Escape stop were used; `agent prompt` was sent to busy Claude workers without confirming that it queues every time, and the Claude Ctrl+X chords were not sent through Herdr. Herdr 0.9.5's `pane send-keys --help` names `esc` but not how to write a Ctrl chord, so check the pane after trying one.
**Check it landed.** Read the pane (`pane read --source visible`) after every send. The message landed when it shows in the conversation or in the CLI's queue (Claude Code shows queued messages in grey until it starts on them) and the input box is empty. Text still in the box was not sent: press the key for the mode you meant, once. A busy `agent prompt --wait` can return on the current turn ending, which proves nothing about your message.
**Stopping a lane.** When work must stop now (wrong target, a held action about to run): `H pane send-keys <pane> esc`, read the pane until the turn shows as interrupted, and check the effect you were stopping did not happen (no push, no migration, no deploy) before sending anything new. Claude Code sends what was queued as soon as Esc interrupts, so look at the queue first and take back anything stale. Then `H agent prompt <name> "Coordinator: STOP … read <new brief>"`. A lane that stopped by itself (crash, quota, a dialog) is a stalled lane: read the pane, log it, and answer the dialog or resume the worker from its recorded session id.
Messages start `Coordinator:` and name files, PRs and heads, not chat context.
## 4. Traps and fixes
- **Codex hook-review dialog**: after `~/.codex/hooks.json` is edited, the hooks no longer match their trusted hashes in `~/.codex/config.toml`, and every new Codex pane opens "N hooks need review" at start. The first prompt vanishes into it while `agent prompt --wait --until working` still returns `working`; three lanes sat about 3 minutes before anyone read the pane. Show the user the new hook commands and let them choose to trust them in one Codex TUI. Until then, read the pane after each first send, `send-keys escape`, and resend.
- **`invalid_agent_name`**: names are lowercase letters, digits, `-` or `_`, 1 to 32 characters. A script that ignores the failed `agent start` then waits on a lane that never existed; stop on a non-zero exit.
- **`agent_name_taken`**: names are unique per server. Reuse that worker (it keeps context) or start under a new name; address by pane id when unsure.
- **Brief left unsent / messages queued and never submitted / lane sitting on a dialog**: read the pane after every send and on every tick.
- **Standing monitor stopped and idle**: briefs tell standing lanes to write a STOP line to the run record before stopping; your tick reads their panes.
- **Status flicker**: completion is the READY line plus your own check, never `done`/`idle`.
- **Compaction**: long lanes compact mid-task. Keep follow-ups self-contained (brief path, PR, head, exact change). Whether idle lanes compact on their own is not established.
- **`rm` permission prompts** stopped auto-mode Claude workers on the example run. Even with prompts off, keep the rule: scratch output outside the worktree; never delete files.
## 5. Closing lanes
Idle sessions pile up. On a tick, close this run's workspaces whose PRs shipped and have no follow-up (`H workspace close <workspace>`); keep gates, shipping, reviewers of open releases and lanes with live work; worktrees stay on disk; log what you closed. Owner sessions that other sessions report to are never archived.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |