objective-loop

name	objective-loop
description	Loop /do cycles until done-criteria verify or budget stops.
user-invocable	false
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep","Skill","Task"]
routing	{"not_for":"one-off tasks that finish in a single dispatch, the harness '/loop 5m /cmd' command, installing system cron jobs (headless-cron-creator), implementing retry/backoff code inside a program (condition-based-waiting), single-condition waits (Monitor tool)","triggers":["keep working until","keep going until","iterate until done","loop on this until","until the tests pass","until CI is green","until all PRs are merged","drive this to done","objective with done criteria","work this until verified","reschedule yourself until"],"complexity":"Complex","category":"meta","pairs_with":["verification-before-completion","condition-based-waiting","feature-lifecycle"]}

Objective Loop

The toolkit's iterate-until-verified-done loop. A user states an objective with verifiable done-criteria; each iteration routes one /do cycle, verifies the criteria by executing them, and reschedules itself via ScheduleWakeup until verified-done or budget-stop. This skill is a planner/verifier wrapped around the /do router — it executes no work inline. Objectives over tasks: describe what done looks like and how to verify it; the loop finds the path.

Phase 1: SPEC

Gather the objective spec from the request. Interview only for missing fields.

Field	Required	Default
Objective statement	yes	—
DONE-CRITERIA	yes	—
Iteration budget	no	5
Token-budget note	no	orchestration.token_budget from .claude/settings.json (500000 when absent)
NOT-DONE-YET guardrails	no	empty

DONE-CRITERIA are verifiable checks. Each criterion has a type: command (default, preferred) or rubric.

• command — a deterministic command with an expected exit code/output: pytest -q exits 0; gh pr view N --json state -q .state prints MERGED; validate-doc-counts.py reports zero drifts. A criterion the model reasons about is not a criterion; each needs a command plus an expected observable.
• rubric — allowed only where no mechanical check exists, per the PHILOSOPHY.md verification ranking (exit code > fresh-context grader > self-critique). Store the rubric verbatim in the state file at SPEC time: pass conditions plus the evidence the grader must cite. Frozen once the loop starts — changes require the user, same as a guardrail.

NOT-DONE-YET guardrails name what may never be done to satisfy a criterion (e.g. "never weaken a gate to make it pass"). They bind every iteration: inject them verbatim into each /do dispatch.

Gate: spec complete. Proceed to Phase 2.

Phase 2: STATE

Write .objective/<slug>/state.md from the template in references/state-file.md: objective, criteria table, guardrails, per-iteration log, next planned step.

• Wakeups resume FROM THE STATE FILE, never from conversation memory — the wakeup prompt carries only a pointer.
• .objective/ mirrors .feature/'s ephemerality but stays separate: .feature/ is feature-lifecycle's phase machine, managed only by feature-state.py, and its presence reroutes /do into feature phases. Objectives are arbitrary goals.
• State is session working memory — keep .objective/ unstaged; stage repo files by name only.

Gate: state file written. Proceed to Phase 3.

Phase 3: ITERATE — one /do cycle

Plan the smallest next step toward the unmet criteria, then route it through the /do phases: classify → route → dispatch agents → evaluate. The loop dispatches work exclusively through /do — catching yourself editing or analyzing inline means stop and route. Multi-part objectives may dispatch parallel agents per /do's rules.

Learning capture is automatic. Every iteration dispatches through /do, so routing rows and outcomes record via the /do learning hooks. Add no manual capture.

Gate: dispatch evaluated, iteration log updated in the state file. Proceed to Phase 4.

Phase 4: VERIFY (execution, not reasoning)

Run every done-criterion check. A worker's "criterion passes" claim never substitutes for the re-run.

• command — run the command; paste the exit code and the decisive output line into the iteration log.
• rubric — dispatch a fresh-context sub-agent that did NOT produce the work. Input is the artifact plus the rubric, nothing else — no iteration history. It returns PASS/FAIL plus cited evidence (file:line or output excerpt), pasted into the iteration log exactly like an exit code.

Then:

• All criteria pass → write the final report (per-criterion evidence), STOP. The loop ends by not calling ScheduleWakeup.
• Any criterion unmet → Phase 5.

Criteria-gaming guard (hard rule). A criterion may never be satisfied by weakening a hook, gate, test, or safety control — and a rubric is never weakened to pass. When the only visible path to "pass" weakens a control or the rubric text, stop the loop and report the conflict to the user.

Phase 5: RESCHEDULE or STOP

State	Action
All criteria pass	Final report; stop — no wakeup call
Unmet + iterations remain	Update state file (log, next planned step); call ScheduleWakeup {delaySeconds, reason, prompt} with prompt = "Read .objective/<slug>/state.md, then resume the objective-loop skill from that state file."
Budget exhausted	Honest NOT-DONE report: per-criterion status with last evidence, remaining gaps, suggested next step; stop — no wakeup call

Delay table (prompt-cache aware; ScheduleWakeup clamps 60–3600s):

Wait type	Delay	Cache economics
Active polling (CI run, PR merge expected soon)	270s or less	Keeps the Anthropic prompt cache warm (5-min TTL)
Idle / long agent work	1200s+	Pays one cache miss; right for long gaps
~300s band	skip it	Worst case — pays the miss with none of the idle benefit

Harness fallback. When ScheduleWakeup is absent from your tool list, run iterations sequentially in-session against the same state file and budgets. For a single until-condition wait inside an iteration, the Monitor tool fits; loop boundaries use ScheduleWakeup.

Safety stance (binding)

• Default mode is ScheduleWakeup: session-scoped, dies with the session, zero persistence.
• Cron mode is persistence. CronCreate or system crontab survives the session and requires the owner's explicit OWNER-APPROVED-PERSISTENCE phrase per the home CLAUDE.md. Stop and ask before any cron-mode loop; on approval, route to headless-cron-creator.
• Criteria-gaming guard (Phase 4) and NOT-DONE-YET guardrails (Phase 1) bind every iteration.

Error Handling

Error	Cause	Solution
State file missing on wakeup	.objective/<slug>/ removed mid-loop	Report and stop; ask the user to restate the objective rather than re-deriving it from memory
Criterion command fails to run (not just non-zero)	Tool missing, bad path	Fix the check command in the state file first; a broken check verifies nothing
Unmet-criteria set unchanged across 2 iterations (read from the Last result column, not judged from memory)	Plan stuck	Change approach: re-route through /do with a different agent or skill; unchanged after a third iteration, spend the report on what blocked progress and stop
Wakeup arrives with fresh context	Normal — wakeups carry only the prompt	Resume entirely from the state file per references/state-file.md

Reference Loading Table

Signal	Load These Files	Why
Writing or resuming the state file	state-file.md	Template, slug rules, resume protocol

References

• ${CLAUDE_SKILL_DIR}/references/state-file.md — state-file template, slug rules, and the wakeup resume protocol