Long Running Goals

Long-Running Goals

A lightweight, agent-agnostic alternative to bespoke session/memory systems. Goals live in human-readable goals.md files the user can edit directly — no daemons, no databases.

When to use

• User says "let's set a goal", "remember this objective", "keep working on X across sessions"
• User asks "what are we working on?", "what goals are active?", "resume the goal"
• A task is too large for one session and needs incremental progress across many
• You're about to lose context (compaction, /clear, /new) and want continuity

Do not use for ephemeral todos within a single session — use the runtime's todo tool or a plan.md for that.

File locations

For non-Copilot agents, use the user's requested namespace if they specify one, for example .claude/goals.md or .codex/goals.md. If the user does not specify a namespace, prefer .copilot/goals.md because it is the proposed portable convention from github/copilot-cli#3364.

When both exist, always read both at session start. Per-repo takes precedence on conflicts.

Add .copilot/goals.md to .gitignore on first write unless the team wants shared goals committed. Ask before committing goals files or ignore-file changes.

File format

# Goals

<!-- managed by the long-running-goals skill — humans may edit freely -->

## active

### goal: <short-id-kebab-case>
- title: One-line summary
- created: 2026-05-18
- updated: 2026-05-18
- progress: 0/5 work units
- notes: |
    Free-form context the agent needs to resume work.
    Acceptance criteria, links, decisions made.
- next: The single next concrete action.

### goal: <another-id>
...

## paused

### goal: <id>
- title: ...
- paused: 2026-05-17
- reason: blocked on API access

## done

### goal: <id>
- title: ...
- completed: 2026-05-16
- outcome: PR #42 merged

Keep it small. If a goal grows past ~30 lines, link out to a design doc instead of inlining.

Workflow

On session start (if either goals file exists)

1. Read both files in parallel.
2. If there are active goals, surface them to the user briefly:

   "Active goals: (1) — next: . (2) — next: . Resume work on one, or continue with something else?"

3. Wait for direction before acting. Do not auto-start work — the user's current message takes priority.

If the agent runtime does not invoke skills at session start, apply this workflow the first time the user asks about goals, continuity, resuming work, or long-running objectives.

Adding a goal

When the user asks to set a goal:

1. Confirm: title, scope (per-repo or global), acceptance criteria, the first next action.
2. Create the file if missing (with the header comment).
3. Append under ## active with a fresh kebab-case id.
4. Echo back: "Saved goal <id> to <path>."

Working on a goal

1. Read the goal's notes and next to recover context.
2. Do the work for the current session.
3. Before ending the session (or before /clear), update:
   • updated: to today's date
   • progress: if measurable
   • notes: with new decisions/context (append, don't rewrite history)
   • next: to the new single next action
4. If complete, move the goal to ## done with completed: and outcome:.
5. If blocked, move to ## paused with reason:.

Editing goals

The file is the source of truth. If the user edits it directly, respect their edits — never overwrite without re-reading first. Use targeted edits, not full rewrites.

Principles

• One file, two locations. Per-repo + global. Nothing else.
• Human-readable + human-editable. No JSON, no DB. Markdown the user owns.
• Idempotent updates. Re-reading and re-writing should converge, not diverge.
• Survives compaction. Goals live on disk, not in context. They're durable by construction.
• Don't auto-resume. Surface, then wait for the user.
• Don't grow unbounded. Move done/abandoned goals out, or link to longer docs.

Anti-patterns

• ❌ Treating goals.md as a todo list (use todos for within-session work).
• ❌ Auto-starting goal work on session start without user confirmation.
• ❌ Writing structured data the user can't read or edit (YAML inside JSON inside markdown, etc.).
• ❌ Creating a goal for every user request — only when the user explicitly asks for persistence.
• ❌ Storing secrets, credentials, or PII in goals.md.

Template

See references/goals.template.md for a copy-paste starting file.