Goal Loop

goal-loop

Turn a task into a paste-ready /goal (or /loop) prompt. The point of this skill is that the mechanics live here, so producing a good loop prompt is one shot — no re-deriving theory each time. When triggered, author the prompt and present it for approval. Do not run it.

Respond in the user's language. (The generated /goal block itself stays in whatever language the target repo uses for its tooling and commit messages.)

Knowledge base: references/goal-loop-playbook.md (load it if you need the 7-loop taxonomy, Nate's patterns, antipatterns, the verbatim /goal doc details, or the template library).

This skill authors a contract for Claude's own session. If the work is instead meant to be executed by an external worker agent (Codex, opencode) running in a Herdr pane, with Claude dispatching, validating and monitoring it, use the sibling goal-loop-herdr skill in this repo — there the contract lives in a goal file plus tickets, because the worker has no /goal evaluator.

What /goal and /loop are (verified mechanics)

• /goal (Claude Code ≥ v2.1.139) sets a completion condition; Claude keeps

starting new turns until it's met. After each turn a small fast model (defaults to Haiku) reads the condition + the conversation and returns yes/no + a reason; a "no" becomes the guidance for the next turn, a "yes" clears the goal. The evaluator does NOT run commands or read files — it judges only what Claude already surfaced in the transcript. Condition ≤ 4000 characters. Status: /goal; stop early: /goal clear.

• /loop re-runs a prompt on a time interval (polling/patrol); it

stops when you stop it or Claude decides the work is done. Treat /goal and /loop as alternatives (the docs do), not a combined syntax.

Pick by what should start the next turn: previous turn finished → /goal; a clock tick → /loop.

The one rule that makes or breaks it

> The evaluator judges your condition against what Claude has surfaced. Write the condition as > something Claude's own output can demonstrate in the transcript.

• GOOD: " prints ' passed' with 0 failed, shown in the transcript"

— Claude runs it, the result lands in the transcript.

• BAD: "there are no bugs" / "the architecture is good" / "until satisfied" — nothing the

evaluator can read; this is the #1 cause of loops that never stop. (Nate: "the best agent loops are where you literally say, keep iterating until X metric equals Y result.")

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

The new bit on top of the rule above: the authored /goal makes the agent, on turn 1, before any edits, print its completion contract — a numbered list of evidence lines, each a command + the exact expected string the evaluator can read (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-loop.

• Each line just enumerates the one rule (above) and the backlog-drain proof discipline

(playbook §6) up front — don't re-derive them. The contract lives in the transcript; for a backlog-drain the backlog file already is it.

• Restating the contract on turn 1 does not replace the hard cap or escape hatch — the

authored /goal still carries both (see Authoring procedure, step d).

Two pillars before writing (Nate Herk)

1. GOAL — what is the objective? As objective as possible, not subjective.
2. VERIFICATION — how does the agent know it's done, and with what tool? Different work

needs different checks: code → run tests / typecheck + a build (the typecheck does NOT cover build-time — see the build-check rule below); UI → screenshot + visual check; text → flow / tone. "A loop is only as good as its done check." Make sure the agent has the tool to perform that check (the repo's test, typecheck, and build / packaging commands, plus any preview or screenshot tools).

Authoring procedure

a. Get the task — from the user's ask, the current context, or the PRD/spec, if any. a-bis. Triage the task size — decide single-loop vs large before drafting:

• Single-loop task (one measurable end-state) → continue with b–g below.
• Large task (many slices / many PRDs / "a whole feature") → author a backlog file

first, then a single lean drain-goal (see "Long loops: backlog-drain" below and playbook §6). Creating/editing the backlog file (e.g. notes/-backlog.md, or a path the user names) is an ALLOWED write: an ordered [ ] list where each item has a description, a pointer to its PRD/spec, and its own done-check (command → proof). You still do NOT run the loop (step g holds).

• Design not written (no PRD/spec for some of the work) → do NOT guess the architecture.

Tell the user to write the PRD(s) first, explain why (the backlog is only as good as the PRDs feeding it — without them the agent invents architecture mid-loop), and propose what each PRD should cover. Then come back and author the backlog. b. Pick the mechanism — /goal for "work until a verifiable end-state" (the default for "finish this"); /loop only for polling/waiting (CI, a PR merge, a deploy). c. Draft the condition — one measurable end-state + a stated check (name the exact command/evidence) + any constraint that must not change. c-bis. Verify each done-check line against shipped behavior BEFORE writing it. For every command/flag/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 from that output, the contract is wrong — fix the line, do not paste it. NEVER copy a done-check verbatim from a PRD/slice acceptance without this check: acceptance criteria describe intent, not shipped CLI surface. For loops that ARE allowed to spend (release/validation): every paid command in the contract must be dry-run-verified here too, so the executor never pays to discover a wrong flag. (A contract copied verbatim from acceptance criteria can name a flag or subcommand the shipped product doesn't have — running its --help first is what catches it.) d. Bound it — append a scope terminator (or stop after 20 turns / or stop after 1 hour) and an escape hatch (if the same check fails 3 turns in a row, stop and report instead of guessing). Unbounded loops are expensive and can run for days. e. Discover and weave the project guardrails (next section) when the loop edits a repo. e-bis. Neutralize action bias in cyclic work. Any /loop prompt (and any contract that wakes on a clock rather than on finished work) must say: if there is nothing to do, end the tick without acting; do not change anything just to look busy. A prompt that fires every N minutes and finds an idle repo will otherwise invent work — the polling equivalent of a loop that never stops. f. Fit ≤ 4000 chars. Output the block, then one line: what exactly the evaluator will read to confirm done. g. Stop. Wait for the user's approval. Never set paid-call env vars, never paste or run the loop yourself. (Writing/editing the backlog file in step a-bis is the only allowed write — the loop itself still stays unrun.)

Discover project guardrails (when the loop edits a repo)

Before authoring a loop that changes a codebase, read that repo's CLAUDE.md, AGENTS.md, and README, and establish these five things; then fold the relevant ones into the condition and constraints. An unattended loop must not trip the repo's load-bearing rules.

1. Test command — how the repo runs its unit tests (plus any flag it needs, e.g. a longer

timeout). This is the fast per-commit / per-turn green check. Note any known-pre-existing failure that is an accepted exception.

1. Typecheck — the static check, if any (tsc --noEmit, mypy, …). Also fast; keep it

per-commit.

1. Build — the real build / packaging command. test + typecheck do NOT cover

build-time: a framework build validates route handlers, config/workspace files, and asset resolution that the standalone typecheck skips. Put the build at the DONE / milestone gate, not every commit (it's slow). If the repo ships a packaged artifact, add the packaging build to the release gate too.

1. Paid / destructive operations and their env-locks — any command that spends money or is

irreversible (a provider API call, a deploy, a data migration) and the env var / flag that gates it. An unattended loop must stay free and safe: forbid setting those locks and passing those flags.

1. Git push / commit policy — whether the loop may commit, to which branch, and whether it

may push. Common default: commit per unit of work on a feature branch, never push, never commit to the default branch unless told.

If those files are absent or silent, ASK the user for these five things instead of guessing — a wrong guess here re-introduces bugs the repo already paid for. Also fold in: "read the PRD/spec and the relevant invariant docs first", "on any design decision the task did not settle, stop and ask", "keep diffs small, commit per unit of work", and "match the repo's language / style conventions".

Long loops: backlog-drain (a backlog file as memory between iterations)

This is the first-class pattern for a large, multi-slice, autonomous loop (e.g. an overnight run). The backlog file is memory between iterations (antipattern #6, "no memory", disappears: after each step the agent sees the [x] it already did + what's left), and the /goal stays thin — all the detail lives in the PRD + backlog, not in the condition. When the work spans several "loops" (a whole feature across many PRDs), do NOT write one mega condition or a separate /goal per piece. The backlog-drain pattern:

1. All PRDs done + audited first. The backlog is only as good as the PRDs that feed it — don't

chain before the design is written down (otherwise the agent guesses architecture).

1. Write the backlog — a file (e.g. notes/-backlog.md) with an ORDERED list of

[ ] tasks, each: an unambiguous description + its PRD/slice pointer + its own done-check (command/proof). Every task independently verifiable and leaves the repo green.

1. One lean /goal drains the backlog — condition: "work through `` top to bottom;

for each [ ] do it per its PRD, check it off as [x] with proof, commit; DONE when ALL [x] AND ` + green AND (if the backlog touched routes/UI/native/packaged code) passes — put the build at the DONE gate, see the guardrails section". This is the documented /goal pattern ("work through a backlog until the queue is empty"); the evaluator sees progress as [x]` + green tests/build in the transcript.

1. Milestone report + a cap sized to the number of tasks (not one giant cap), an escape hatch

as usual; an optional "stop at the boundary of loop N and ask" checkpoint. That's how "loop after loop" runs without a human — at the cost that the WHOLE plan (PRDs + backlog) must be written up front.

Backlog + drain-goal template: references/goal-loop-playbook.md (§6).

Examples

Generic, verifiable — Node/npm (note the demonstrable check + cap + escape hatch):

/goal Refactor src/lib/foo.ts into focused modules, each under 200 lines. Done when:
`npm test` shows 0 failed AND `wc -l src/lib/foo*.ts` shows every file ≤ 200 lines, both
results printed in the transcript, with no other test file modified. Run the test + wc and
show output every turn. Stop after 15 turns, or if the same failure repeats 3 turns in a row —
then report and stop.

Feature with guardrails — Python/pytest (bounded, evaluator-readable, build at the DONE gate):

/goal Implement the "batch export" feature from spec.md. Read that spec and the repo's
CONTRIBUTING/README first. On turn 1, before any edits, print your completion contract — the
evidence lines you'll produce (each command → expected output). Work in small commits. Done when:
`pytest -q` prints 0 failed AND `mypy src` prints "Success: no issues found" AND `python -m build`
exits 0 (run at the end, not every commit), all shown in the transcript, and every spec acceptance
item is checked off in your summary. Constraints: make NO paid API calls, never set any
*_ALLOW_PAID env var, do not git push, do not commit to main. If a design point isn't settled by
the spec, stop and ask. Stop after 25 turns regardless.

Output the block, then add the one-line rationale (e.g. "Evaluator confirms done by reading the 0 failed / Success / exit 0 lines you'll print each turn") and hand it to the user to paste.

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.