repo-context-ledger

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