# Goal Loop Herdr

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-szewowsky-goal-loop-skill-goal-loop-herdr`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Szewowsky](https://agentstack.voostack.com/s/szewowsky)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Szewowsky](https://github.com/Szewowsky)
- **Source:** https://github.com/Szewowsky/goal-loop-skill/tree/main/skills/goal-loop-herdr

## Install

```sh
agentstack add skill-szewowsky-goal-loop-skill-goal-loop-herdr
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.
2. **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.
3. **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.
2. **Progress without reading the screen** — grep the tickets' `Status:` lines and read
   `git log --oneline`. Cheaper and more reliable than scraping a terminal viewport.
3. **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.
4. **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](https://github.com/Szewowsky)
- **Source:** [Szewowsky/goal-loop-skill](https://github.com/Szewowsky/goal-loop-skill)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-szewowsky-goal-loop-skill-goal-loop-herdr
- Seller: https://agentstack.voostack.com/s/szewowsky
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.