# Long Running Goals

> Maintain long-running, cross-session goals for an agent (Copilot CLI, Claude Code, Codex, etc.) using a declarative goals.md file. Use when the user wants the agent to remember objectives across sessions, when they say "let's set a goal", "remember to keep working on X", "what are we working on?", "resume the goal", or asks for persistent objectives that survive context resets and compaction.

- Skill: `bunsdev/long-running-goals` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add bunsdev/long-running-goals`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bunsdev/long-running-goals/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: BunsDev (https://skillmd.com/u/bunsdev)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/bunsdev/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

| Scope | Path | When |
|---|---|---|
| Per-repo | `.copilot/goals.md` | Default for Copilot CLI and for repo-owned goals. Project-specific objectives. |
| Global  | `~/.copilot/goals.md` | Default for Copilot CLI and cross-repo objectives ("learn Rust", "migrate everything to pnpm"). |

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](https://github.com/github/copilot-cli/issues/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

```markdown
# 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) <title> — next: <next>. (2) <title> — next: <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.