[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80098":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":15,"stars30d":16,"stars90d":14,"forks30d":14,"starsTrendScore":17,"compositeScore":18,"rankGlobal":9,"rankLanguage":9,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":14,"starSnapshotCount":14,"syncStatus":15,"lastSyncTime":27,"discoverSource":28},80098,"goal-ledger","kingbootoshi\u002Fgoal-ledger","kingbootoshi","Single-file agent goal ledger for Claude Code and Codex CLI - pairs with \u002Fgoal mode",null,"Python",69,5,57,0,2,7,1,2.33,"MIT License",false,"main",true,[],"2026-06-12 02:03:58","# Goal Ledger\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"plugins\u002Fgoal-ledger\u002Fskills\u002Fgoal\u002Fassets\u002Fhero.jpeg\" alt=\"Vibe Bot crossing the finish line with arms raised, scoreboard of completed objectives behind him\" width=\"720\">\n\u003C\u002Fp>\n\nA single-file agent goal ledger that pairs with `\u002Fgoal` mode in **Claude Code** and **OpenAI Codex CLI**.\n\n`\u002Fgoal` 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.\n\nThe same skill works in both agents. Same `SKILL.md`, same script, same on-disk layout. Drop it into `~\u002F.claude\u002Fskills\u002Fgoal\u002F` and `~\u002F.codex\u002Fskills\u002Fgoal\u002F` and both agents pick it up natively.\n\n## What it does\n\nWhen the agent says `$goal`, `\u002Fgoal mode`, `start a goal`, or any equivalent goal-mode language, the skill:\n\n1. Creates a fresh ledger under `.agent\u002Fruns\u002F\u003Cgoal-id>\u002F` in the current project.\n2. Writes a contract file (`GOAL.md`): objective, finishing criteria, escape hatch, parent goal.\n3. 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.\n4. Couples to the runtime goal: when the user is in Codex `\u002Fgoal` 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.\n5. Updates the HTML at every meaningful checkpoint: validation runs, implementation milestones, blockers, spec-vs-reality conflicts, compaction prep, final hand-off.\n\nThe 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.\n\n## Why one HTML file\n\nEarlier versions of this skill used a sprawl of `PROGRESS.md`, `HANDOFF.md`, `events.jsonl`, and `CODEBASE_STATUS.md`. Agents got confused about which file was canonical. Humans got confused about which file to read. State drifted between them.\n\nGoal Ledger collapses all of that into one self-contained HTML file:\n\n- **Top** is a `Resume Here` block: status, current phase, blockers, next exact action, last validation, protected paths. Built so the next agent (or human) can resume in under a minute.\n- **Middle** is `Decisions Outside The Spec`, `Changes And Tradeoffs`, `Validation`, `Evidence`. The execution record.\n- **Bottom** is `Progress Timeline`. Rendered from an inline events array, no external file dependencies, no fetches against sibling files. Opens cleanly even when you double-click the HTML straight out of the file browser.\n\nThe HTML is the contract with the next agent. `GOAL.md` is the contract with the current agent. That's the whole system.\n\n## What problem this actually solves\n\nYou ask Codex or Claude Code to do something multi-hour or multi-day. Halfway through it compacts, gets interrupted, or hands off to a new session. Without a ledger, the new agent picks up with vibes and a stale objective.\n\nWith this skill in `\u002Fgoal` mode, the active goal text itself includes the ledger path. Compaction can drop the conversation history and the next agent still knows:\n\n- where to read state\n- what was already validated\n- what's actively in progress\n- what's blocked and why\n- which paths are user-owned and out of bounds\n- what the next exact action is\n\nThe skill is the difference between an agent that resumes work and an agent that re-explores the codebase.\n\n## Install\n\n### Claude Code\n\nAdd the marketplace, then install the plugin:\n\n```text\n\u002Fplugin marketplace add kingbootoshi\u002Fgoal-ledger\n\u002Fplugin install goal-ledger\n```\n\nRestart Claude Code if the skill does not appear immediately. After install, the skill triggers automatically on goal-mode language, or you can invoke it explicitly.\n\n### OpenAI Codex CLI\n\nCodex looks for skills at `~\u002F.codex\u002Fskills\u002F\u003Cname>\u002F`. Drop the skill directory there:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fkingbootoshi\u002Fgoal-ledger.git ~\u002F.goal-ledger\nmkdir -p ~\u002F.codex\u002Fskills\nln -sfn ~\u002F.goal-ledger\u002Fplugins\u002Fgoal-ledger\u002Fskills\u002Fgoal ~\u002F.codex\u002Fskills\u002Fgoal\n```\n\nRestart Codex if needed. Invoke explicitly with `$goal` or describe the work in goal-mode language and Codex will auto-select it.\n\nCodex also ships a native `\u002Fgoal` lifecycle (`\u002Fgoal`, `\u002Fgoal pause`, `\u002Fgoal resume`, `\u002Fgoal clear`). Enable it once in `~\u002F.codex\u002Fconfig.toml`:\n\n```toml\n[features]\ngoals = true\n```\n\nWhen the native goal exists, the skill couples the ledger path directly into the runtime goal objective so compaction-safe continuation works end to end.\n\n### One canonical location for both agents\n\nIf you prefer a single source of truth, keep the skill in one place and symlink it into both agents:\n\n```bash\n# clone once\ngit clone https:\u002F\u002Fgithub.com\u002Fkingbootoshi\u002Fgoal-ledger.git ~\u002F.goal-ledger\n\n# Claude Code\nmkdir -p ~\u002F.claude\u002Fskills\nln -sfn ~\u002F.goal-ledger\u002Fplugins\u002Fgoal-ledger\u002Fskills\u002Fgoal ~\u002F.claude\u002Fskills\u002Fgoal\n\n# Codex CLI\nmkdir -p ~\u002F.codex\u002Fskills\nln -sfn ~\u002F.goal-ledger\u002Fplugins\u002Fgoal-ledger\u002Fskills\u002Fgoal ~\u002F.codex\u002Fskills\u002Fgoal\n```\n\nBoth agents follow symlinks for skill discovery, so updates to the cloned repo flow to both automatically.\n\n## Usage\n\nOnce installed, the skill activates on phrases like:\n\n- `$goal`\n- `\u002Fgoal mode`\n- `start a goal`\n- `continue this goal`\n- `chain goals`\n- `agent progress ledger`\n- `flight recorder`\n- `implementation notes`\n\nTypical session:\n\n```text\n$goal start migrating the auth service to the new schema. finishing criteria:\nall integration tests green, old endpoints deleted, runbook updated.\n```\n\nThe agent will:\n\n1. Initialize the ledger under `.agent\u002Fruns\u002F\u003Cgoal-id>\u002F`.\n2. Write `GOAL.md` with the objective, finishing criteria, and escape hatch.\n3. Write `implementation-notes.html` with a `Resume Here` block, decision sections, and an inline progress timeline.\n4. Couple to `\u002Fgoal` mode if available and drop the absolute ledger path into the runtime goal objective.\n5. Update the HTML at every meaningful checkpoint while it works.\n\nOpen `.agent\u002Fruns\u002F\u003Cgoal-id>\u002Fimplementation-notes.html` in a browser at any point to see live state.\n\n## Layout\n\n```text\n.agent\u002F\n  GOALS.md                          # project-level index of all goals\n  runs\u002F\n    \u003Cgoal-id>\u002F\n      GOAL.md                       # contract: objective, finishing criteria, escape hatch\n      implementation-notes.html     # canonical readable state + inline progress timeline\n      evidence\u002F                     # optional: bulky logs, screenshots, command output\n```\n\n## What lives in the HTML\n\n- **Meta block**: goal id, started timestamp, parent goal, mode, objective.\n- **Resume Here**: status, current phase, completed work, active work, blockers, next exact action, last validation, protected paths.\n- **Progress Timeline**: scrollable list of compact event objects, rendered directly from an inline `progressEvents` array. No external file dependencies.\n- **Decisions Outside The Spec**: where the spec was silent and the agent had to choose.\n- **Changes And Tradeoffs**: where the spec and the repo disagreed, and how the agent reconciled.\n- **Validation**: the commands that were run, what passed, what failed, what's still pending.\n- **Evidence**: links to bulky proof files in `evidence\u002F`.\n- **Next Goal Candidates**: when this goal unlocks another, list it here.\n\n## Status states\n\nThe skill uses six explicit states inside `implementation-notes.html`:\n\n- `[todo]` known and not started\n- `[doing]` currently active\n- `[done]` completed and validated\n- `[blocked]` waiting on external input or dependency\n- `[incomplete]` attempted, not fully solvable inside current constraints\n- `[abandoned]` intentionally stopped because the goal changed or no longer pays rent\n\n`[incomplete]` is the honest fallback when a checkpoint is impossible inside current constraints. It carries a structured explanation: reason, proof, attempted, impact, next human\u002Fagent decision. This is the path that lets the agent tell the truth without quietly skipping work.\n\n## Escape hatch\n\nEvery serious goal ships with an escape hatch in `GOAL.md`. The agent is told to pause, ask, or mark a scoped item `[blocked]` \u002F `[incomplete]` if:\n\n- validation contradicts the goal\n- the goal requires a scope change\n- the agent is looping without measurable progress\n- the next step risks deleting or rewriting durable memory\n- the PRD and actual repo disagree\n- the ledger itself starts contaminating validation\n\nThis is the honesty path. It exists so the agent never has to lie or fake completion to satisfy the goal.\n\n## Compatibility\n\nBuilt against the open [Agent Skills](https:\u002F\u002Fdevelopers.openai.com\u002Fcodex\u002Fskills) standard. Should work in any agent that scans a skills directory for `SKILL.md`:\n\n| Agent | Personal path | Project path |\n| --- | --- | --- |\n| Claude Code | `~\u002F.claude\u002Fskills\u002Fgoal\u002F` | `.claude\u002Fskills\u002Fgoal\u002F` |\n| OpenAI Codex CLI | `~\u002F.codex\u002Fskills\u002Fgoal\u002F` | `.agents\u002Fskills\u002Fgoal\u002F` or `.codex\u002Fskills\u002Fgoal\u002F` |\n| Cursor | n\u002Fa | `.cursor\u002Fskills\u002Fgoal\u002F` |\n| Google Antigravity | `~\u002F.gemini\u002Fantigravity\u002Fskills\u002Fgoal\u002F` | `.agent\u002Fskills\u002Fgoal\u002F` |\n\nThe `agents\u002Fopenai.yaml` sidecar is Codex-specific UI metadata. Other agents ignore it.\n\n## License\n\nMIT.\n","Goal Ledger 是一个单文件代理目标账本，专为 Claude Code 和 OpenAI Codex CLI 的 `\u002Fgoal` 模式设计。其核心功能在于记录每个检查点、决策、障碍和验证到一个易于阅读的 `implementation-notes.html` 文件中，确保信息在不同环节间无缝传递。该工具通过创建新的账本、编写合同文件及维护进度时间线来实现对目标执行过程的全面追踪。适用于需要持续追踪和管理复杂任务或项目进展的场景，尤其是在涉及多个开发者或自动化代理协作的情况下。简洁的设计使得无论是在当前还是后续的任务处理过程中都能快速恢复工作状态，避免了多文件同步带来的混乱。","2026-06-11 03:59:14","CREATED_QUERY"]