repo-context-ledger
Maintain durable, evidence-based repository context whenever an agent initializes a repository, implements or fixes behavior, refactors code, changes an interface, checkpoints or switches tasks, resumes or hands work to another AI tool, collaborates across parallel task sessions, Git branches, or worktrees, prepares a pull request, or completes a coding task. Use this skill to bridge Codex, Claude, Cursor, GitHub Copilot, Grok, and other coding agents through native instruction adapters, private session-isolated handoff drafts, atomic completed-change publication, a shared Context Manifest, language-aware Context Packs, stable feature specifications, verified change history, coverage gates, and managed README summaries without asking the user to run bookkeeping commands.
gviiisen · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add gviiisen/repo-context-ledger --skill repo-context-ledger技能说明
name: repo-context-ledger description: Maintain durable, evidence-based repository context whenever an agent initializes a repository, implements or fixes behavior, refactors code, changes an interface, checkpoints or switches tasks, resumes or hands work to another AI tool, collaborates across parallel task sessions, Git branches, or worktrees, prepares a pull request, or completes a coding task. Use this skill to bridge Codex, Claude, Cursor, GitHub Copilot, Grok, and other coding agents through native instruction adapters, private session-isolated handoff drafts, atomic completed-change publication, a shared Context Manifest, language-aware Context Packs, stable feature specifications, verified change history, coverage gates, and managed README summaries without asking the user to run bookkeeping commands.
Repo Context Ledger
Keep repository knowledge current across AI tools and fresh conversation windows. Treat semantic documentation as part of completing code work, while using the bundled deterministic runtime for paths, native adapters, the Context Manifest, indexes, links, README blocks, and validation. Never attempt to read or synchronize private vendor Memory; promote only code-verified facts into Git-tracked context.
Locate the runtime
Resolve the directory containing this SKILL.md. The bundled runtime is scripts/ledger.py relative to that directory.
After initialization, prefer the repository-local copy:
python .context-ledger/ledger.py <command>
Use python3 instead of python when that is the available interpreter.
--repo is optional. If omitted, the runtime walks up from the current directory to the nearest .context-ledger/config.json, and stops at a nested Git repository boundary.
Choose the shortest path
Do not run the full lifecycle for every request.
- Read-only understanding:
context --query "<task>", thenfocus --feature "<feature>". Do notstarta session. - Single-task small fix:
status→start --feature→ implement →verify -- <command>→finish --spec.finishrecords evidence automatically when this is the only session. If the worktree is large or another session exists, passevidence --path. - Parallel tasks: pass
--session <id>on every lifecycle command. Capture evidence with repeated--pathvalues for only this task. - Medium or large change: also refresh the related Context Pack, update the stable spec, and write Before/After evidence before
finish.
context returns one primary Context Pack, its linked specs, and why it was chosen. Read that Pack's load order before scanning the rest of the repository.
Initialize a repository
When the user asks to initialize, adopt, or configure repository context documentation:
- Run
python <skill-dir>/scripts/ledger.py --repo <repository-root> init --dry-runand inspect the exact planned files, managed blocks, migrations, and detected modules. The preview must remain read-only. - If the plan matches the user's requested repository scope, run the same command without
--dry-run. Do not hand-recreate or selectively replay the plan. - Inspect the generated
.context-ledger/config.json, detected modules, and existing documentation. - Run
python .context-ledger/ledger.py adapters checkandpython .context-ledger/ledger.py manifest checkto confirm native entry files and the shared route index are current. - Set
quality.language(auto,en, orzh-CN) andquality.detail(concise,standard, ordetailed) only when the repository needs a non-default policy. - Preserve existing
AGENTS.md,CLAUDE.md,.github/copilot-instructions.md, README content, and documentation. Only managed blocks or the dedicated Cursor adapter may be regenerated. - Treat nested Git repositories and worktrees as discovery boundaries. When adopting legacy
docs/changes/YYYY-MM/...trees, preserve and reuse an existing monthlyindex.md; remove an obsolete index only when the runtime can reproduce the whole file byte-for-byte from current sibling records. - Summarize what was added. Do not require the user to learn internal lifecycle commands.
Read document-model.md when choosing where information belongs or migrating an existing documentation layout.
Complete behavior-changing work
Apply this workflow autonomously when code behavior changes. Follow Choose the shortest path. Do not ask the user to run ledger commands.
-
Run
python .context-ledger/ledger.py status. Reuse only this task's private draft. Never adopt, pause, publish, or rewrite another task's draft. -
Resolve the record language. Keep code identifiers in source form.
-
If this task will change behavior and has no session,
start --title "<title>" --feature "<feature>". Keep the session ID. When more than one task is active, pass--session <id>; omission must fail. -
Route context, then read the primary Pack and its specs:
python .context-ledger/ledger.py context --query "<feature, interface, or module>" python .context-ledger/ledger.py focus --feature "<feature>"If no Context Pack exists, create one with
pack --feature, fill every semantic section, then focus it. -
Implement the change. Record every claimed check with
verify --session <id> -- <command>. Failed output is stored as a redacted failure capsule, never as a raw log. Persisted verification evidence replaces repository, Codex, temporary, and user-home roots with stable placeholders, including JSON-escaped Windows paths. If verification is unavailable, useverify --not-run --reason "<substantive reason>". -
For a small single-session fix,
finishcan collect evidence. If another session exists, or automatic collection finds too many implementation paths, runevidence --pathfor only this task. Read .context-ledger/writing-quality.md and remove everyTODO.