Objective loop

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