Goal — persistent project objective

A goal is a single objective the agent keeps pursuing across turns and sessions until it is marked done. Inspired by Prime Agent's thread goal: state lives outside any one conversation, so any tool with this skill installed (Claude Code, Cursor, Codex, ...) picks up where another left off.

State file

One file per project: .goal.md in the repository root. Human-readable and human-editable on purpose — pause, resume, edit, and clear are controlled by the user editing the file directly.

---
objective: Ship release notes for v2.3
status: active        # active | paused | done
created: 2026-08-22
---

## Progress
- 2026-08-22 14:02 — drafted changelog from git log

Optional sections the loop reads if present: ## Queue (ordered work items), ## Standing constraints (owner-set rules that bind every session), ## Decisions (recorded owner calls — binding, never re-litigated), ## Done criteria.

API

• get — read .goal.md. No file means no goal is set. Report the objective, status, and latest progress entries when asked about goal status.
• create(objective) — write .goal.md with status: active and today's date. If an active goal already exists, do NOT silently replace it; show it and ask whether to complete, pause, or replace. Only create a goal when the user explicitly asks for a persistent goal; do not infer goals from ordinary tasks.
• update(note) — append one dated line to ## Progress after each meaningful work session toward the goal. Keep notes short and factual.
• complete() — set status: done. Only when the objective has actually been achieved and no required work remains — not because the session is ending or momentum ran out.

Session behavior

At the start of a session in a repo containing .goal.md:

• status: active — surface the objective to the user, then ENTER THE WORK LOOP below before starting unrelated work.
• status: paused — mention it exists; resume only if the user asks.
• status: done — leave it as history; offer to archive or replace.

Work loop (continuous execution)

An active goal with remaining actionable items means you run a LOOP, not a single pass. One iteration:

1. Resume — read .goal.md plus the newest handoff document it references (typically under docs/plans/). Verify recorded receipts against reality (HEAD sha, merged PRs, live state) before trusting them.
2. Pick the highest-priority item that is actionable right now — from the Queue, the referenced workorder, or the handoff's "exact next action".
3. Journal before acting — append TODO <task> to ## Progress. If the session dies here, a successor knows precisely what was attempted.
4. Execute — do the work. Run the real gates. Commit/PR per whatever authority the goal grants (e.g., self-review-and-merge if so recorded).
5. Journal after — append DONE <task> — <receipt> immediately. Receipt = commit sha, PR number, test counts, or posted artifact. No receipt, not done.
6. Repeat from step 2 while an actionable item remains and no STOP condition applies.

Never end a turn with actionable items outstanding unless a STOP condition fired. "Momentum ran out" is not a stop condition.

Failure resilience

• Transient LLM/API/tool failures — timeouts, 429/5xx, dropped connections — are NEVER stop conditions. Retry with backoff (≈30s → 60s → 120s, cap ~5 attempts). If one dependency stays down, journal BLOCKED <item> — <reason>, switch to the next non-dependent actionable item, and circle back.
• Crash/interrupt safety: because TODO precedes work and DONE follows it, an interrupted session loses nothing. On resume, a task with TODO and no DONE is simply not started yet — verify no half-committed debris, then restart it.
• Tool/environment failure ≠ task failure. A failing gate gets diagnosed; a failing external service gets routed around; neither ends the loop.
• Flaky tests fail-then-pass-isolated are recorded as known-flaky, not treated as regressions — but always rerun isolated before concluding that.

Stop conditions (the ONLY reasons to end the loop)

1. Done — goal achieved; call complete().
2. Blocked on owner — every remaining item needs an answer only the owner can give. Post the questions (one line each), mark items BLOCKED/DEFERRED, update .goal.md, stop with a clear summary of what you need.
3. Context limit approaching — write the handoff document (see Handoff), append the final Progress line, stop cleanly.
4. Repeated hard failure — ≥3 consecutive unrecoverable failures across DIFFERENT items (not retries of one) → write an incident note into Progress and the handoff, stop, report to owner.

Everything else — API flakiness, slow builds, flaky tests, waiting on a local service — is worked through or routed around.

Handoff (graceful exit)

If the repo keeps committed plan/handoff documents (e.g., docs/plans/), the graceful exit is: write/update the handoff file containing exact HEAD sha, PRs landed this session, current queue position, receipts, known gotchas, and the exact next action — then append the final Progress line to .goal.md, then stop. Ending a session without those two writes is a defect: the successor must be able to resume from .goal.md + the latest handoff alone.

Rules

• One active goal per repository. The file is the source of truth — never keep goal state only in conversation memory.
• Never delete or rewrite past progress lines; append.
• Completion must reflect reality. An agent that marks a half-finished goal done defeats the entire mechanism.
• Standing constraints and recorded decisions inside .goal.md bind every session and outrank this skill's defaults.
• Journal honestly: a TODO line without a matching DONE line is expected and safe; a DONE line without receipts is a lie.

Harness note (out of skill scope)

This skill makes the AGENT persistent within a session and recoverable across sessions. Fully automatic relaunch after a dead session requires harness-level scheduling (cron/gateway/watchdog) outside any skill's control. If the owner wants unattended overnight loops, pair this skill with a scheduler that re-invokes the agent with "resume the goal".