Goal Loop Herdr

goal-loop-herdr

The coordinator variant of a loop contract. The executor is an external worker agent (Codex, opencode, …) running in a Herdr pane; Claude is the coordinator and plays three roles at once from a monitoring loop:

• dispatcher — sends the goal and pushes the frontier forward,
• validator — approves permission prompts that fall inside the contract,
• monitor — watches progress and escalates anything outside it.

Respond in the user's language. (The authored goal file and tickets stay in whatever language the target repo uses for its tooling and commit messages.)

The worker has no /goal evaluator — that is a Claude Code feature. So the contract cannot live in an evaluator; it must live in files the worker reads and updates. That is the single structural difference from the lean variant, and everything below follows from it.

Knowledge base: references/coordinator-playbook.md (artifact templates, the monitoring-loop check list, the validator decision table, failure modes).

Requirements

• Herdr installed, and this Claude session running inside a Herdr-managed pane

(HERDR_ENV=1). Herdr is a terminal multiplexer for coding agents — panes, agent status detection, and a herdr CLI.

• A worker agent binary available in PATH (codex, opencode, …).
• Claude Code with /loop for the monitoring cadence.
• The herdr skill installed separately, from the Herdr project. This skill deliberately

does not bundle or restate Herdr's command syntax — see the next section.

If HERDR_ENV is not 1, say so and stop: use the lean /goal variant instead (the sibling goal-loop skill in this repo).

Herdr syntax lives in the installed binary, not here

> The authority for every Herdr command is the installed binary: herdr --help, plus each > command group printed without a subcommand. Verify every Herdr command before writing it > into a contract.

Command names, flags, and status semantics change between versions. A contract that names a flag the installed build does not accept stalls the drain on a phantom blocker and burns a turn. This is the same discipline as verifying done-checks against shipped behavior (below) — applied to the coordinator's own commands.

Artifacts — all three exist before the worker starts

1. Goal file (e.g. .scratch//worker-goal.md) — the contract, and the worker's

equivalent of a /goal condition:

• the per-ticket loop: claim → implement → run the gates → commit → resolve,
• hard rules: no paid calls, no push, scope boundary,
• "on doubt: write it into the ticket's ## Comments and skip to the next ticket — do not

guess",

• the definition of finished.

1. Tickets with edges (e.g. .scratch//issues/NN-*.md) — each carries Status: and

Blocked by:. The frontier is the lowest-numbered ticket with no unfinished blockers. Tickets are the memory between iterations: the worker sees what it already resolved.

1. A short start message — points at the goal file and repeats the 3-4 hardest rules. Keep

it short; the detail lives in the goal file and the tickets, not in the message.

The completion contract (freeze the finish line on turn 1)

The goal file makes the worker, on turn 1, before any edits, print its completion contract — a numbered list of evidence lines, each a command + the exact expected string (e.g. ` → 0 failed; → exit 0`; "spec acceptance item N: checked"). This freezes the finish line before turn 2 and stops the goalposts drifting mid-drain.

Because there is no evaluator reading the transcript, the monitor reads the files: a done-check must be a command + an exact expected result that shows up in a commit, a ticket, or the worker's own echoed output.

Verify every done-check against shipped behavior BEFORE writing it

For every command, flag, or subcommand a done-check names, run it with --help (or as a dry-run) and read the output. If a required flag or subcommand is missing there, the contract is wrong — fix the line, do not ship it. Never copy a done-check verbatim from a PRD or a slice's acceptance criteria: acceptance describes intent, not the shipped surface. A contract copied that way can name a flag the product dropped versions ago; the worker correctly stalls, and the turn is burnt.

Authoring procedure

a. Get the task — from the user's ask, the current context, or the PRD/spec. b. Pre-flight (before authoring, not after):

• test "$HERDR_ENV" = 1 passes,
• the worker is visible in the pane listing (herdr pane list, per the installed CLI).

If the worker pane does not exist, ask the user in one sentence whether to start it ("Start the worker in Herdr?"). Consent in the current conversation is enough. Then, per the herdr skill: split the coordinator's pane with --no-focus → rename it to a readable label → run the worker's plain interactive binary in it → wait for idle → only then send the start message. Without consent, fall back to the lean /goal variant. Also check the ordinary loop pre-flight: the working tree is clean for the files in scope, no dev server is holding the port, no paid-call env lock is set, nobody else is writing in the same checkout. c. Discover the project guardrails — read the repo's CLAUDE.md / AGENTS.md / README and establish five things before writing the goal file: the test command, the typecheck, the build (a real build, at the DONE gate — a typecheck does not cover build-time), the paid / destructive operations and the env locks that gate them, and the commit / push policy. If those files are silent, ask rather than guess. d. Write the three artifacts (above). Keep the goal file lean; detail goes into the PRD and the tickets. e. Verify every done-check against shipped behavior (section above), including every Herdr command the contract or the monitoring loop will use. f. Bound it — a scope terminator (turn or time cap) and an escape hatch ("if the same gate fails 3 turns in a row, stop and report instead of guessing"). Unbounded drains are expensive. g. Neutralize action bias. Both the goal file and the monitoring loop must say: if there is nothing to do, finish without acting; do not change anything just to look busy. A cyclic prompt that wakes every N minutes will otherwise invent work. h. Stop and wait for the user's approval. Never set paid-call env vars, never start the drain without the go. After approval the coordinator proceeds on its own: start the worker (if needed), send the start message, and open its monitoring loop.

The monitoring loop

Run it as /loop 5m — a fixed 5-minute interval, not the dynamic pacing. A predictable cadence is one a human can follow along with; use 10m when the drain is slow or overnight, or when the user asks for it.

Each tick does four things, in order:

1. Worker status (per the installed CLI) — working → do nothing; blocked → validator

role; idle / done → decide whether it finished a turn mid-drain (push the frontier) or finished the whole thing.

1. Progress without reading the screen — grep the tickets' Status: lines and read

git log --oneline. Cheaper and more reliable than scraping a terminal viewport.

1. The tickets' ## Comments — the worker's questions. Answer within the contract.

Widening the scope mid-drain is the human's decision, not the coordinator's.

1. At the end — reconcile commits against tickets, report, and stop the loop. The report

ends with the HITL list: criteria a worker cannot satisfy (anything needing a human to look, click, or spend). Those stay unchecked, annotated HITL: .

If a tick finds nothing to do, end the tick without acting.

The validator role

| Situation | Coordinator's move | |---|---| | Permission prompt for a free command inside the contract (tests, typecheck, build, grep) | Approve. "Don't ask again" for repeat commands drops the friction to zero. | | Paid, destructive, or out-of-scope command | Escalate to the human. Never approve on their behalf. | | Worker asks a design question the task never settled | Answer only if the goal file already settles it; otherwise escalate. | | Status looks wrong or stuck | Inspect the pane before acting; a wait timeout is not by itself a failure. |

Alternative: run the worker in an auto-approval mode instead of validating. Two rules: verify the exact flags against the installed worker's --help before writing them into the contract (auto-mode flag names differ between builds and some documented ones simply do not exist in a given build), and prefer a sandbox mode whose network is off by default — that makes paid calls and git push physically impossible, which is a harder guarantee than a prompt a human might approve by reflex. Side effect: dependency installs also fail, so install new dependencies before the drain starts. Never grant unrestricted access permanently.

The validator variant is a notch safer (unforeseen commands get judged); auto-mode is a notch faster.

What this variant does NOT replace

• The build gate. A drain that is green on tests + typecheck can still be broken at build

time. If the work touches routes, UI, app code, native deps, or a packaged artifact, the DONE gate must include the real build (and the packaging build for a release).

• The free / paid split. A free drain may prove the code correct; it does not prove

behavior against a real paid model. Behavioral validation is a separate, separately authorized run with its own budget.

• The human's push. The loop never pushes. It commits per unit of work, on the branch the

guardrails name; the human pushes.

Templates for the goal file, the ticket, the start message, and the monitoring prompt: references/coordinator-playbook.md.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Szewowsky
• Source: Szewowsky/goal-loop-skill
• License: MIT

Install and usage instructions live in the source repository linked above.