Goal Ledger is a git-tracked execution record for coding agents. Its skills
and rule install user-global into each harness's discovery paths; the
record itself (.goal-ledger/) lives committed in each project that uses it.
It provides crash recovery, model-tier hand-off, branch isolation, phase commits,
a planner review gate, and optional safe squash-on-acceptance through a committed
.goal-ledger/.
The same rules and skills install into Antigravity CLI, Codex, Claude Code, Cline, and Pi.
Goal Ledger splits the work by role, not by harness:
- A planner — your strongest model — inspects the project, writes the plan, prepares Git, hands out phases, reviews everything at Gate D, and accepts.
- An executor — a cheaper model, a subagent, or a separate CLI session — runs one assigned phase from its written instructions and stops.
That only works if the plan carries the reasoning the executor does not have.
So a phase file is written for the weaker model: exact paths in Scope: In,
an explicit Out list, a Pattern to follow pointing at real code to imitate,
sub-tasks that are single concrete actions, a copy-pasteable ## Verify block,
and an ## Escalate when list naming the ways this phase goes wrong.
The executor's standing instruction is escalate, do not improvise: when it
meets a decision the phase file does not answer, it records
needs-human — reason: <the exact question> and stops. A stopped phase is a
clean hand-off; a phase finished by guessing is a mess the planner has to find.
Executors write to the ledger, but only in their lane — their own phase file,
their phase's mirror line, ## Handoff, and ## Log. Goal status, the phase
list, Git fields, and ## Review are planner-only. Execution mode: solo in
GOAL.md puts both roles in one session; the gates still apply.
Gate D is the planner's review: run the recorded Full verification command,
read git diff <baseline>..HEAD in full, check every changed path against some
phase's scope, and re-check each phase's ## Evidence against its ## Verify.
Executor summaries are claims until the planner re-runs the check. Findings
become fix-up sub-tasks or a remediation phase, not caveats.
Pushing, opening a PR, and merging are never automatic — Goal Ledger prepares a reviewed branch and stops there.
DOX, compose-helper, and lazyway-io-design are not vendored or installed by this repository. Install those projects separately if a project needs them.
AGENTS.md
CLAUDE.md
.agents/skills/
goal-ledger/SKILL.md
goal-ledger-execute/SKILL.md
goal-ledger-resume/SKILL.md
goal-ledger-status/SKILL.md
goal-ledger-abandon/SKILL.md
.claude/skills/ # generated byte-identical mirrors
.clinerules/workflows/ # generated thin invocation shims
rules/shared/goal-ledger.md # distributable user-global rule body
The .agents/skills/ tree is authoritative. The install copies it into
user-global harness discovery locations; the committed Claude mirrors and Cline
shims make this repository itself portable without creating another procedure
source.
The former core reasoning rules are intentionally separate from this repository and are available as a public core-reasoning-rules.md Gist.
Installation is agent-guided only — there are no install scripts. Your agent merges with whatever you already have — existing global instruction files, legacy Master Plan artifacts, same-named skills — instead of colliding with it. Paste this into your coding agent:
Fetch https://github.com/ghraw/jpbaking/goal-ledger/main/AGENT-INSTALL.md and follow its instructions exactly to install Goal Ledger. Merge with — never blindly overwrite — any existing global or project instruction files, and report every file you created or changed.
The procedure in AGENT-INSTALL.md is the authoritative
install contract. The agent acquires the sources itself (git clone, repo
zip, or gh) in a temporary directory and copies the skills and rule into
each selected harness's user-global discovery paths — nothing is added
to your repos. The rule self-gates on .goal-ledger/ in the current
project, so it stays inert elsewhere.
| Harness | Rules | Skills |
|---|---|---|
Antigravity CLI (agy) |
pointer in ~/.gemini/GEMINI.md → ~/.agents/rules/ |
~/.gemini/antigravity-cli/skills/ |
| Codex | pointer in ~/.codex/AGENTS.md → ~/.agents/rules/ |
~/.agents/skills/ |
| Claude Code | pointer in ~/.claude/CLAUDE.md → ~/.agents/rules/ |
~/.claude/skills/ |
| Cline | pointer in ~/.agents/AGENTS.md → ~/.agents/rules/ |
~/.cline/skills/ |
| Pi | pointer in ~/.pi/agent/AGENTS.md → ~/.agents/rules/ |
~/.agents/skills/ |
The install is per-user and per-machine: teammates who want the skills
install them for themselves, and every clone of a project works regardless —
the committed .goal-ledger/ record needs no adapters to be readable.
Project-level adapter install remains an explicit opt-in documented in
AGENT-INSTALL.md.
Re-run the install with the same harness selection. Canonical Goal Ledger rule and skill copies are refreshed in place. Whole same-named Goal Ledger skill directories are replaced so retired bundled resources cannot linger.
The procedure assumes every unrelated existing adapter belongs to another tool. It never deletes legacy core reasoning, DOX, compose-helper, lazyway-io-design, workflow, command, or skill files. It only inspects same-purpose Master Plan and Goal Ledger locations, reports possible duplicates, and leaves non-destination files untouched. Review and remove stale adapters manually when appropriate — including old gitignored project-level Goal Ledger adapters from installs made before the user-global default.
If .tmp-agent-scratch/MASTER-PLAN.md contains an unfinished legacy plan,
the procedure stops before changing anything so that work can be finished,
abandoned, or deliberately migrated first.
Ask your strongest model to use the goal-ledger skill for multi-phase or
long-running work. When it reaches an executor-owned phase it hands you a
prompt to paste into a cheaper session:
Use the goal-ledger-execute skill.
Project root: /path/to/project
Phase: phase-0003
Execute that phase only. Do not plan, re-scope, or continue to another phase.
That prompt carries no context on purpose — everything the executor needs is in
the ledger. Use goal-ledger-resume for recovery or handoff,
goal-ledger-status for a read-only report (it also reports whether the next
phase is executor-ready), and goal-ledger-abandon to stop while preserving
history.
Goal Ledger writes GOAL.md and phase-NNNN.md files directly under
.goal-ledger/. The directory is committed, never gitignored, and remains in the
accepted result. GOAL.md records an immutable baseline, a stable Goal ID, the
chosen Git strategy, and handoff state. Commit trailers connect Git history to
the goal without trying to store a moving HEAD hash inside the commit itself.
The workflow strongly recommends an isolated goal/<goal-id> branch. Staying on
the current branch is supported, but automatic squashing is refused when commits
are foreign, interleaved, merged, published, or otherwise unsafe to rewrite.
When a goal branch was pushed for remote handoff, retain its history and use a
squash merge during integration instead of rewriting the published branch.
Harness-specific menus may expose different invocation syntax, but successful use does not depend on a slash-command wrapper.
The main skill includes a read-only scripts/validate_goal_ledger.py helper. The
Goal Ledger skills run it when Python 3 is available and fall back to manual
contract checks otherwise. It validates file structure, status mirrors,
dependencies, lifecycle invariants, Git baselines, branches, and commit trailers.
It also enforces the parts of the format that make delegation work, so an
under-specified phase fails before an executor ever sees it: every phase needs
an Owner, a filled-in Scope: In/Out, a real ## Escalate when condition,
and a ## Verify that is either a runnable command block or an explicit
- manual: check. It warns when an executor-owned sub-task still says "as
needed" or "if necessary", when an executor-owned phase can only be verified by
eye, and when a phase is marked done with nothing in ## Evidence. Reaching
awaiting-acceptance requires a recorded Gate D review.
Run the local checks with:
python3 -m unittest discover -s tests -vCI runs the validator fixtures on Linux, macOS, and Windows.
This repository is licensed under 0BSD.