goal-conditions

The skill /goal should have shipped with.

English · 中文

/goal shipped 2026-05-11 in Claude Code v2.1.139. Its evaluator only reads the transcript — never runs tools. One mis-stated condition burns dozens of turns before you notice.

This skill makes you write conditions the evaluator can actually judge.

---

See it in 30 seconds

You ask Claude:

用 /goal 把 legacyAuth 重构干净

Without this skill, you might compose:

/goal 把 legacyAuth 重构干净

Claude says "重构完了" mid-conversation. The evaluator reads those characters and clears the goal. Untouched call sites, type errors silently passing, a test command that never ran. Tens of turns. Burned.

With this skill, you get:

/goal Migrate all call sites of `legacyAuth()` to `auth.verify()` repo-wide, proven by:
  1) `rg "legacyAuth\(" -t ts` returns zero matches, AND
  2) `bun run typecheck` exits 0, AND
  3) `bun test test/auth` exits 0,
without modifying any file under `vendor/`, `node_modules/`, or `*.generated.ts`,
or stop after 20 turns.

Three objective signals, each an exit code Claude must paste. Converges and exits clean. No surprise edits.

---

Install

/plugin marketplace add CSZHK/goal-conditions
/plugin install goal-conditions@goal-conditions

The skill auto-triggers on phrases like /goal, goal condition, goal 怎么写, /goal 烧 token, and similar variants in English + Chinese.

---

What's in the box

The 4-piece recipe. Every robust /goal condition needs four slots. Skip one and the failure mode below is what you'll hit:

Slot	Skipped → failure mode
End state	Evaluator never sees a clean "done" — loop drags on
Proof	Evaluator guesses from code edits — high false-positive rate
Invariant	Out-of-scope edits land in your PR — blast radius grows
Bound	Tokens burn until you manually intervene

6 patterns + 6 worked examples, one per common task shape:

Pattern	Worked example
P1 Cross-repo migration / rename	migrate legacyAuth call sites
P2 File-size budget refactor	split a fat hook file under 300 LOC each
P3 Queue drain	clear a labeled GitHub issue queue to zero
P4 Test repair with anti-flake	stabilize a flaky test across 3 consecutive runs
P5 Dependency upgrade	bump react-query v4 → v5 with 4-layer proof
P6 Docs / changelog completion	ensure every merged PR has a CHANGELOG entry

Each example has copy-paste-ready conditions, slot-by-slot reasoning, variations for adjacent tooling (npm / pnpm / Linear / etc.), and common pitfalls when running it.

8 NEVER rules. The design discipline made explicit. Catches the trap of "all tests pass" without naming the test command, destructive operations without dry-run invariants, fabricated verification commands, turn bounds that silently disappear after /resume.

Ecosystem integration. When the official /goal alone isn't enough:

• itsuzef/goalkeeper — adds an independent judge subagent against an explicit Definition of Done. Catches the case where the validator passes but the feature isn't really done.
• jthack/claude-goal — adds --tokens budgeting, native pause/resume, SQLite cross-session persistence.

tools.md tells you which to install when.

---

How the evaluator actually works

/goal is a session-scoped Stop hook. After every turn, the evaluator (a small fast model, defaults to Haiku) receives:

• Your condition
• The full conversation up to that point

And returns yes/no + a one-line reason. It does not call tools. This single fact has three non-obvious consequences, and every pattern in this skill is shaped by them:

1. Proofs must produce transcript-visible output — an exit code Claude pastes, a wc -l listing, a git status. "The DB has 0 rows" is not a proof unless a SQL command's output appears in the conversation.

2. /resume silently resets your turn bound. The official docs spell this out; most users miss it. After 3 resumes, your or stop after 20 turns bound has quietly become 60 elapsed turns.

3. Small evaluators are unreliable at cross-turn comparison. They technically see the full history, but Haiku-sized models can't be trusted to compare values across many turns. Fresh per-turn anchors are the only robust pattern.

Full mechanics deep-dive in SKILL.md.

---

Why this exists

/goal shipped 24 hours before this repo. The official docs (1800 words) describe the mechanism — what it does, how to set one. They don't describe the defensive design discipline the mechanism demands. That's a separate gap, and it's where Token blowups happen.

This skill fills the gap, before your first 60-turn blowup teaches you the same thing.

---

No-fabrication policy

Every claim in this repo is audit-able:

• Official docs: 5 direct quotes verified verbatim against the live page on 2026-05-12 (https://code.claude.com/docs/en/goal)
• Third-party tool features: verified via gh api (release metadata + README)
• Examples: template-shape with placeholder values, no invented case studies
• Mechanics descriptions: cross-checked against the official Hooks docs

Find a claim that doesn't hold up? Open an issue. Half the value here is being verifiable.

---

Repository layout

goal-conditions/
├── .claude-plugin/{marketplace,plugin}.json
├── README.md · LICENSE · CHANGELOG.md
└── skills/goal-conditions/
    ├── SKILL.md                       ← workflow + 8 NEVER rules
    ├── references/
    │   ├── patterns.md                ← 4-piece recipe + 6 patterns + anti-patterns
    │   └── tools.md                   ← ecosystem notes (goalkeeper, jthack, awesome lists)
    └── examples/01-06.md              ← one worked example per pattern

---

Contributing

PRs welcome. Especially valuable:

• A new pattern that doesn't fit P1–P6
• A war story where a template prevented a Token blowup — or where it failed and needs a new anti-pattern entry
• Translations to other natural languages (current: English; trigger words include 中文)

---

License: MIT · Author: @CSZHK · authored 2026-05-12, ~24 hours after /goal shipped.