/goal

name: goal
description: Persistent project goal that survives across sessions and tools, with continuous-execution loop semantics. Use when someone asks to "set a goal", "what is my goal", "goal status", "keep working on X until done", "resume the goal", or wants work to continue across sessions until an objective is achieved. File-backed (.goal.md at project root); shared by every Coco-installed tool working in that repository.
domain: meta

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 conversa