Repo Context Ledger — Feature Change Ledger & Cross-Agent Context Relay

English | 简体中文

Automatically record every behavior-changing feature update, then let Codex, Cursor, or Claude continue from the right code, decisions, and boundaries.

Repo Context Ledger is an open, repository-level feature change ledger for AI coding. After a feature is added, fixed, or behaviorally adjusted, it preserves what changed, why it changed, where the implementation lives, which boundaries must remain stable, and how the result was verified.

Those verified records become durable context for Codex, Claude, Cursor, GitHub Copilot, Grok, and other coding agents. A fresh window or a different tool can follow a focused route into the relevant code and continue without replaying a long chat or rediscovering the feature from scratch.

Use it for AI feature change tracking, software change documentation, AI context management, Codex context management, Cursor context switching, Claude context management, and cross-agent development handoffs. The change ledger is the knowledge source; cross-session and cross-tool continuation are capabilities built on top of it.

Install it with the standard Agent Skills CLI:

npx skills@latest add gviiisen/repo-context-ledger --skill repo-context-ledger

You make ordinary coding requests. The AI owns the documentation lifecycle.

Before any lifecycle command, the Agent can ask the read-only Workflow Plan whether the request is understanding work, a small fix, an ordinary change, or a continuation. The plan reuses the bounded context router, explains its decision, and asks for clarification instead of guessing when intent is ambiguous.

Why it exists

AI-assisted changes are easy to implement but hard to preserve as durable repository knowledge. Without a feature-level record, the reason for a fix, its code path, verification evidence, and important boundaries remain trapped in a chat or must be rediscovered from a large diff and codebase.

The same gap becomes more visible when work moves to a fresh window or another coding agent. The next agent must reconstruct the feature from scratch, and implementation details or important constraints can be lost between sessions.

Repo Context Ledger records each behavior-changing feature addition, repair, and adjustment, then turns that verified history into a small, durable map of the repository:

• where a feature lives;
• how its code path works;
• which contracts and edge cases must remain stable;
• what changed, why it changed, and how it was verified;
• which project and module README summaries need refreshing.

What it maintains

• docs/ai/: concise repository-wide orientation for fresh AI sessions.
• docs/ai/context-manifest.json: generated feature-to-context routes for machine discovery.
• docs/ai/context-packs/: minimal feature context, load order, boundaries, tests, and tracked-file fingerprints.
• docs/specs/: current feature behavior, code maps, contracts, and boundaries.
• docs/changes/: chronological implementation and repair handoffs, grouped as YYYY/MM/<change>.md with a small monthly index.
• Private branch/worktree state: independent active and paused drafts are stored under Git metadata and are never committed; only completed changes enter formal history.
• Root and module README.md files: generated navigation blocks without rewriting human prose.
• AGENTS.md, CLAUDE.md, Cursor rules, and .github/copilot-instructions.md: thin native adapters that route coding agents to the same ledger.
• .context-ledger/writing-quality.md: local evidence, language, and record-form rules available to every AI tool.

Compatibility

The core skill follows the open Agent Skills SKILL.md format. It is designed for Codex, Claude Code, Cursor, GitHub Copilot, Grok, and other agents that support Agent Skills or repository instruction files.

Initialized repositories also receive plain instruction files, so tools without native Skill discovery can follow the same workflow. Native discovery and exact installation locations vary by product.

See COMPATIBILITY.md for supported Python/platform and CLI schema guarantees, and MIGRATIONS.md for upgrade rules.

Install

Clone this repository or download a release, then install the directory skills/repo-context-ledger in your AI tool.

Codex

Ask Codex:

Use $skill-installer to install the skills/repo-context-ledger skill from https://github.com/gviiisen/repo-context-ledger.

For repository-scoped use, copy or link the skill directory to:

.agents/skills/repo-context-ledger/

Claude Code

Copy or link skills/repo-context-ledger to either the personal or project skill directory:

~/.claude/skills/repo-context-ledger/
.claude/skills/repo-context-ledger/

Cursor

Import this GitHub repository from Cursor's Skills/Rules settings, or copy the skill to:

~/.agents/skills/repo-context-ledger/
.agents/skills/repo-context-ledger/

GitHub Copilot

Install the Skill through a compatible Agent Skills client, or let an initialized repository's .github/copilot-instructions.md route Copilot to the ledger. The runtime preserves existing Copilot prose outside its managed block.

Common usage examples

After installation and one-time repository initialization, talk to your coding Agent normally. You do not need to run Ledger lifecycle commands yourself.

The routed files are a starting map, not a limit. The Agent must still read additional callers, implementations, configuration, persistence, permissions, concurrency, retries, tests, and external boundaries whenever they can affect the requested behavior.

Tutorial

1. Initialize a repository once

Open the target project with your AI coding tool and ask:

Use repo-context-ledger to initialize this repository.

The agent first previews the exact operation list with init --dry-run, then applies the same plan with init. It creates the documentation structure, private workspace state, and durable agent instructions without overwriting existing documentation.

For a manual preview, run:

python path/to/ledger.py --repo path/to/repository init --dry-run

The output is a compact plan, not a full diff. It does not create a lock, repository file, or private session-state file.

2. Work normally

Make the same request you would make without this skill:

Fix the withdrawal monitoring interface and verify the behavior.

You do not need to run ctx begin, name a handoff, or remember lifecycle commands. The agent should autonomously:

1. produce a read-only workflow-plan-v1 decision for the request;
2. retrieve the relevant repository and feature context when the selected workflow needs it;
3. start a private handoff only for a small fix or ordinary behavior change;
4. update code and execute claimed checks through the verification recorder;
5. derive changed paths from Git and record Before/After behavior, boundaries, and evidence;
6. update the stable feature spec and Context Pack when current facts or tracked dependencies change;
7. update affected module README prose when its usage changes, deferring shared generated summaries until merge;
8. close the handoff and validate structure plus Git-diff documentation coverage.

On a feature branch, shared monthly indexes and README summary blocks are intentionally left unchanged until merge.

Small fixes, less bookkeeping

Similar follow-ups do not automatically restart the workflow. The Agent first checks what is actually new using context it already has: an ordinary log recheck needs no new Ledger task, and a same-window continuation keeps the active session. New behavior on another path still needs its own explanation and current verification. Reuse background and methods, not stale success claims; completed records remain unchanged.

Ledger records acceptance goals, not every terminal operation. Reads, searches, file generation, and deployment preparation use ordinary tools. Reuse the current task session; run related acceptance checks through one reviewed script/preset instead of wrapping every helper separately. Preserve each step's result and failure exit code, keep required pre/post-deployment checks in their proper phases, and never replay a deployment merely to ad