auto-author-goal
Turn a plan into a model-judgeable goal doc the user binds with `/goal <doc-path.md>`. Use when the user says "generate a goal for this plan", "make a goal doc", "write a /goal for <plan>", "write a g
SKILL.mdskills/auto-author-goal/SKILL.md
GitHubauto-author-goal (the goal compiler)
A goal doc is a saved, model-judgeable exit predicate derived from a plan.
The user binds it with /goal <doc-path.md> (a file-referenced goal — the
model judges the file's whole content as the "done" condition). This skill
writes that doc; it never runs /goal.
The binding model (read first)
The user runs /goal .claude/auto/goals/<slug>.md themselves. The model then
judges the entire doc as the goal at each stop attempt. Two consequences
drive how the doc is written:
- The doc IS the condition. Everything in it is read as the predicate, so write it AS a judgeable spec — observable "done" criteria, not rationale prose the judge would have to interpret. The ONLY permitted aside is a single footer line carrying OPERATIONAL instructions (how to release the goal), never rationale or authoring commentary — the judge reads it but won't mistake a release instruction for a criterion.
- It's an independent, model-judged gate. Auto's own deliberate-stop is a
deterministic run-record read (
lib/on-stop.py); a native/goalis model-judged and shares NO verdict with it. They can DIVERGE — a goal judged stricter than the run-record keeps re-prompting "Goal not yet met… continuing" even after auto reachesdone(the spam class the Stop-hook fix addressed, now self-inflicted via the goal). We can't guarantee agreement; we write the doc to TRACK auto's predicate to minimize divergence./goal clearis the escape — name it in the doc. Auto never arms or clears this goal; the user does. Seeskills/auto/SKILL.md§1.
Phrasing rules — a model-judgeable exit predicate
The criteria the model judges should each be:
- Binary & terminal. Describe the DONE state, not the process. "every step in the plan is implemented and reviewed clean" — not "work through the plan."
- Observable. Verifiable from repo state or the transcript: tests pass, files exist, no open review findings, a command exits 0. Nothing only an external system knows.
- Agent-completable — the agent can REACH the done-state on its own.
Observable is not enough. If a criterion requires a manual human action the
agent cannot perform — toggle a UI/LD flag, drag-and-drop, click through a
flow, do something while a job is running, exercise a device — then the
model-judged goal can NEVER flip to met autonomously and re-prompts "Goal not
yet met… continuing" forever. This is the never-met loop: the worst case
of the divergence above, because no amount of agent work can satisfy it. Every
criterion must name a state the agent can both REACH and verify. Any
human-gated / manual-QA step goes on the out-of-scope line, NOT in the
criteria. If the goal is inherently a manual test (its whole point is a human
exercising the UI), say so and do NOT author it as a
/goal— it cannot be one; recommend a checklist or a test the agent can drive instead. - Scoped to THIS plan, and INLINED. The doc IS the condition, so write the
specific acceptance outcomes INTO the doc — do not just cite "AE1–AE4 in
<plan>" and assume the judge opens the plan (that's an unverified second-file read). Name the plan as provenance, but spell out the concrete done-states the judge can check from repo/transcript without leaving the doc. - No vague adjectives unless operationalized. Not "clean / good / done well" — instead "no P0/P1/P2 review findings remain" or "the suite is green."
- Make auto's exit predicate the PRIMARY criterion; everything else is what
it entails. Auto exits when all steps are terminal AND only P3 findings
remain. Lead with that as the sufficient condition, and frame the plan's
acceptance examples / tests-green as what it ENTAILS ("which means AE1–AE4 are
satisfied and
tests/run.shis green"), NOT as separate bullets ANDed on top. Any independent gate ANDed onto the predicate can only make the goal STRICTER than the run-record — re-introducing the divergence (re-prompt-after-done) from the binding model above. If you DO want a stricter gate deliberately (e.g. keep the session going until tests pass, beyond auto's review-loop), that is a valid choice — but say so explicitly, because the extra "continuing" prompts are then INTENDED, not the spam failure mode. - Tight. A focused checklist, not an essay. Exclude deferred/out-of-scope items explicitly so the judge doesn't hold the goal open on them.
Procedure
- Locate the plan. Take the plan path from the user (or the most recent
docs/plans/*.md). Read it. Pull: the requirements trace (R1…), acceptance examples (AE1…), scope boundaries, deferrals, and any explicit success / "done when" criteria. - Compose the condition per the rules above — lead with auto's exit
predicate as the primary/sufficient criterion, then inline the concrete
acceptance outcomes it entails (observable, spelled out, grounded in the
plan's acceptance examples / explicit success lines). Screen every criterion
for agent-completability (rule 3): route any human-gated / manual-QA step to
the out-of-scope line — it must never be a criterion. Add the out-of-scope
line for deferrals too, so the goal doesn't hang on them. If the only "done"
state is a manual human test, STOP — tell the user this can't be a
/goaland suggest a checklist instead. - Write the goal doc to
<repo>/.claude/auto/goals/<plan-slug>.mdusing the template below (creategoals/if absent)..claude/auto/is gitignored runtime state — the doc is a local artifact, not a committed file. - Surface the bind command — the path plus:
/goal .claude/auto/goals/<slug>.md← run this to bind/goal clear← run this to release it
Goal-doc template
The whole file is the condition — keep it criteria-focused.
# Goal: <plan title>
Source plan: `<relative/path/to/plan.md>`
This goal is met when auto's exit predicate holds: every step in the plan is
implemented and reviewed, and only P3 review findings remain (P0/P1/P2 all
resolved). Concretely, that state means:
- <inlined acceptance outcome 1 — e.g. "a circle shape can be drawn and persists across reload">
- <inlined acceptance outcome 2 — observable, spelled out, not a citation>
- `tests/run.sh` exits 0.
Out of scope (do NOT hold this goal open on these): <deferred items, and any human-gated/manual-QA steps the agent can't perform itself, or "none">.
<!-- note: model-judged goal, independent of auto's Stop hook; release with `/goal clear`. -->
Invariants
- Never run
/goal. Author and surface only; the user binds. - The doc is the condition. Write judgeable criteria, not rationale prose — the model reads the whole file.
- Every criterion is agent-completable. A criterion the agent can't reach on
its own (manual UI action, human QA) makes a never-met loop —
/goalre-prompts "continuing" forever. Human-gated steps go out-of-scope; a goal that is ONLY a manual test must not be authored as a/goalat all. - Ground in the plan. Every criterion traces to a requirement / acceptance example / explicit success line — no invented scope. State deferrals as out-of-scope so the goal doesn't hang on them.
- Track auto's predicate to minimize (not eliminate) divergence; the goal is
an independent model-judged gate,
/goal clearis the escape.