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:
- 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.
- Pick the highest-priority item that is actionable right now — from the
Queue, the referenced workorder, or the handoff's "exact next action".
- Journal before acting — append
TODO <task> to ## Progress. If the
session dies here, a successor knows precisely what was attempted.
- 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).
- Journal after — append
DONE <task> — <receipt> immediately. Receipt =
commit sha, PR number, test counts, or posted artifact. No receipt, not done.
- 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)
- Done — goal achieved; call
complete().
- 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.
- Context limit approaching — write the handoff document (see Handoff),
append the final Progress line, stop cleanly.
- 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".
1---2name: goal3description: 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.4domain: meta5metadata:6 source: https://skillmd.com/skills/coco-research/goal7---89# Goal — persistent project objective1011A goal is a single objective the agent keeps pursuing across turns and12sessions until it is marked done. Inspired by Prime Agent's thread goal:13state lives outside any one conversation, so any tool with this skill14installed (Claude Code, Cursor, Codex, ...) picks up where another left off.1516## State file1718One file per project: `.goal.md` in the repository root. Human-readable and19human-editable on purpose — pause, resume, edit, and clear are controlled by20the user editing the file directly.2122```markdown23---24objective: Ship release notes for v2.325status: active # active | paused | done26created: 2026-08-2227---2829## Progress30- 2026-08-22 14:02 — drafted changelog from git log31```3233Optional sections the loop reads if present: `## Queue` (ordered work items),34`## Standing constraints` (owner-set rules that bind every session),35`## Decisions` (recorded owner calls — binding, never re-litigated),36`## Done criteria`.3738## API3940- **get** — read `.goal.md`. No file means no goal is set. Report the41 objective, status, and latest progress entries when asked about goal status.42- **create(objective)** — write `.goal.md` with `status: active` and today's43 date. If an `active` goal already exists, do NOT silently replace it; show44 it and ask whether to complete, pause, or replace. Only create a goal when45 the user explicitly asks for a persistent goal; do not infer goals from46 ordinary tasks.47- **update(note)** — append one dated line to `## Progress` after each48 meaningful work session toward the goal. Keep notes short and factual.49- **complete()** — set `status: done`. Only when the objective has actually50 been achieved and no required work remains — not because the session is51 ending or momentum ran out.5253## Session behavior5455At the start of a session in a repo containing `.goal.md`:5657- `status: active` — surface the objective to the user, then ENTER THE WORK58 LOOP below before starting unrelated work.59- `status: paused` — mention it exists; resume only if the user asks.60- `status: done` — leave it as history; offer to archive or replace.6162## Work loop (continuous execution)6364An active goal with remaining actionable items means you run a LOOP, not a65single pass. One iteration:66671. **Resume** — read `.goal.md` plus the newest handoff document it references68 (typically under `docs/plans/`). Verify recorded receipts against reality69 (HEAD sha, merged PRs, live state) before trusting them.702. **Pick** the highest-priority item that is actionable right now — from the71 Queue, the referenced workorder, or the handoff's "exact next action".723. **Journal before acting** — append `TODO <task>` to `## Progress`. If the73 session dies here, a successor knows precisely what was attempted.744. **Execute** — do the work. Run the real gates. Commit/PR per whatever75 authority the goal grants (e.g., self-review-and-merge if so recorded).765. **Journal after** — append `DONE <task> — <receipt>` immediately. Receipt =77 commit sha, PR number, test counts, or posted artifact. No receipt, not done.786. **Repeat** from step 2 while an actionable item remains and no STOP79 condition applies.8081Never end a turn with actionable items outstanding unless a STOP condition82fired. "Momentum ran out" is not a stop condition.8384## Failure resilience8586- **Transient LLM/API/tool failures** — timeouts, 429/5xx, dropped87 connections — are NEVER stop conditions. Retry with backoff (≈30s → 60s →88 120s, cap ~5 attempts). If one dependency stays down, journal `BLOCKED <item>89 — <reason>`, switch to the next non-dependent actionable item, and circle back.90- **Crash/interrupt safety**: because TODO precedes work and DONE follows it,91 an interrupted session loses nothing. On resume, a task with TODO and no DONE92 is simply not started yet — verify no half-committed debris, then restart it.93- **Tool/environment failure ≠ task failure.** A failing gate gets diagnosed;94 a failing external service gets routed around; neither ends the loop.95- **Flaky tests** fail-then-pass-isolated are recorded as known-flaky, not96 treated as regressions — but always rerun isolated before concluding that.9798## Stop conditions (the ONLY reasons to end the loop)991001. **Done** — goal achieved; call `complete()`.1012. **Blocked on owner** — every remaining item needs an answer only the owner102 can give. Post the questions (one line each), mark items BLOCKED/DEFERRED,103 update `.goal.md`, stop with a clear summary of what you need.1043. **Context limit approaching** — write the handoff document (see Handoff),105 append the final Progress line, stop cleanly.1064. **Repeated hard failure** — ≥3 consecutive unrecoverable failures across107 DIFFERENT items (not retries of one) → write an incident note into Progress108 and the handoff, stop, report to owner.109110Everything else — API flakiness, slow builds, flaky tests, waiting on a local111service — is worked through or routed around.112113## Handoff (graceful exit)114115If the repo keeps committed plan/handoff documents (e.g., `docs/plans/`), the116graceful exit is: write/update the handoff file containing exact HEAD sha, PRs117landed this session, current queue position, receipts, known gotchas, and the118exact next action — then append the final Progress line to `.goal.md`, then119stop. Ending a session without those two writes is a defect: the successor120must be able to resume from `.goal.md` + the latest handoff alone.121122## Rules123124- One active goal per repository. The file is the source of truth — never keep125 goal state only in conversation memory.126- Never delete or rewrite past progress lines; append.127- Completion must reflect reality. An agent that marks a half-finished goal128 done defeats the entire mechanism.129- Standing constraints and recorded decisions inside `.goal.md` bind every130 session and outrank this skill's defaults.131- Journal honestly: a TODO line without a matching DONE line is expected and132 safe; a DONE line without receipts is a lie.133134## Harness note (out of skill scope)135136This skill makes the AGENT persistent within a session and recoverable across137sessions. Fully automatic relaunch after a dead session requires harness-level138scheduling (cron/gateway/watchdog) outside any skill's control. If the owner139wants unattended overnight loops, pair this skill with a scheduler that140re-invokes the agent with "resume the goal".