THE /goal COMMAND

TL;DR — a condition that survives 20+ turns has three ingredients: one measurable end state, a stated check Claude can run, and constraints that name what must not change.

▸ Ingredient 1 — Measurable end state

An observable quantity that flips from "not yet" to "yes" exactly once. Not a vibe. Examples that work: a test run's exit code, a file count, a queue length, "git status is clean". Examples that fail: "the code is good", "users will be happy", "production-ready".

▸ Ingredient 2 — Stated check

How Claude should prove the end state. The evaluator reads the transcript; if proof isn't in the transcript, the goal stalls. Spell out the command Claude should run: "npm test exits 0", "jq . config.json succeeds", "the build/ dir contains index.html".

▸ Ingredient 3 — Constraints

What must not change while reaching the end state. Without these the worker may "fix" tests by deleting them or downgrade a dep instead of fixing the bug.

/goal all tests in test/auth pass (npm test --silent exits 0),
the diff touches only src/auth/* and test/auth/*,
and package.json is unchanged.

▸ The 4,000-char budget

The condition can be long — use it. A two-paragraph condition with constraints typically outperforms a five-word one because the evaluator has more cues to judge against. Past ~1,000 chars the worker also reads it as a small spec.

TL;DR — read these side by side. The pattern reveals itself faster than any rule.

▸ Tests

✓ /goal all tests in test/auth pass (npm test --silent exits 0)
✗ /goal fix the tests

▸ Migration

✓ /goal every call site of db.queryOld has been replaced with db.queryV2,
   bun tsc --noEmit exits 0, no .ts file outside src/db touches db.queryOld
✗ /goal migrate the database calls

▸ Cleanup

✓ /goal CHANGELOG.md has one entry per PR merged in the last 7 days
   (verified by gh pr list --state merged --search "merged:>=2026-05-10");
   each entry has a date, type, and link.
✗ /goal update the changelog

▸ Refactor

✓ /goal src/parser.ts has been split so every resulting file is ≤200 lines,
   all callers compile, bun test exits 0, no new dependencies in package.json
✗ /goal break the parser into smaller files

▸ Backlog

✓ /goal every issue with label "good-first" is either closed,
   labeled "blocked", or has a comment from me explaining the next step.
   Stop after 30 turns even if not done.
✗ /goal triage the issues

▸ The pattern

Every "good" example names a thing to count, a command to run, and what stays untouched. Every "bad" example names a verb and trusts the worker to define done.

TL;DR — there is no built-in cap on a /goal session. Add a stop clause to the condition itself, or burn money in your sleep.

▸ Built-in: nothing

A goal keeps running until the evaluator says "yes" or you run /goal clear. There is no default max-turn, no default budget cap, no default timeout.

▸ Three ways to bound

1. Inline in the condition. Append "or stop after 20 turns" or "or stop after 1 hour". The worker reports progress each turn; the evaluator reads the progress and judges the clause.
2. Headless caps. When running with -p, add --max-turns N and --max-budget-usd X at the CLI level. These are enforced by Claude Code itself, not the evaluator.
3. External kill switch. Ctrl+C in interactive mode, or kill the process for headless. Crude but reliable.

▸ A bounded goal in practice

/goal flake-2-out-of-5 in test/network/* is resolved
(running each suite 5× and showing 5/5 passes in the output),
or stop after 25 turns. Constraint: don't touch test infra
unless a single test file's setup is the cause.

▸ A real reason to set a cap

Without a cap, a goal that can't converge will iterate forever, each turn costing real money. The author of the community pre-official claude-goal tool defaulted to 500 continuations as a runaway protection — which tells you how bad it can get.