Goal Ledger

Goal Ledger

A single-file agent goal ledger that pairs with `/goal` mode in **Claude Code** and **OpenAI Codex CLI**.

`/goal` mode is great at keeping an agent pointed at one durable objective. It is not great at remembering what already happened. The Goal Ledger fills that gap: every checkpoint, decision, blocker, and validation gets written into one human-readable `implementation-notes.html` file that opens in any browser and survives compaction, hand-offs, and chained goals.

The same skill works in both agents. Same `SKILL.md`, same script, same on-disk layout. Drop it into `~/.claude/skills/goal/` and `~/.codex/skills/goal/` and both agents pick it up natively.

What it does

When the agent says `$goal`, `/goal mode`, `start a goal`, or any equivalent goal-mode language, the skill:

1. Creates a fresh ledger under .agent/runs// in the current project.
2. Writes a contract file (GOAL.md): objective, finishing criteria, escape hatch, parent goal.
3. Writes a single canonical state file (implementation-notes.html): a self-contained HTML page with a Resume Here block at the top and an embedded progress timeline.
4. Couples to the runtime goal: when the user is in Codex /goal mode, the absolute ledger path is dropped into the goal objective so the next agent on the thread knows exactly where to read and write.
5. Updates the HTML at every meaningful checkpoint: validation runs, implementation milestones, blockers, spec-vs-reality conflicts, compaction prep, final hand-off.

The progress timeline is rendered directly from an inline `progressEvents` array inside the HTML file. There is no separate `events.jsonl` to keep in sync — the page is its own history. Open the file locally and you get the whole story at a glance.

Why one HTML file