跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

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>", then focus --feature "<feature>". Do not start a session.
  • Single-task small fix: status → start --feature → implement → verify -- <command> → finish --spec. finish records evidence automatically when this is the only session. If the worktree is large or another session exists, pass evidence --path.
  • Parallel tasks: pass --session <id> on every lifecycle command. Capture evidence with repeated --path values 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:

  1. Run python <skill-dir>/scripts/ledger.py --repo <repository-root> init --dry-run and inspect the exact planned files, managed blocks, migrations, and detected modules. The preview must remain read-only.
  2. 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.
  3. Inspect the generated .context-ledger/config.json, detected modules, and existing documentation.
  4. Run python .context-ledger/ledger.py adapters check and python .context-ledger/ledger.py manifest check to confirm native entry files and the shared route index are current.
  5. Set quality.language (auto, en, or zh-CN) and quality.detail (concise, standard, or detailed) only when the repository needs a non-default policy.
  6. 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.
  7. Treat nested Git repositories and worktrees as discovery boundaries. When adopting legacy docs/changes/YYYY-MM/... trees, preserve and reuse an existing monthly index.md; remove an obsolete index only when the runtime can reproduce the whole file byte-for-byte from current sibling records.
  8. 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.

  1. Run python .context-ledger/ledger.py status. Reuse only this task's private draft. Never adopt, pause, publish, or rewrite another task's draft.

  2. Resolve the record language. Keep code identifiers in source form.

  3. 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.

  4. 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.

  5. 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, use verify --not-run --reason "<substantive reason>".

  6. For a small single-session fix, finish can collect evidence. If another session exists, or automatic collection finds too many implementation paths, run evidence --path for only this task. Read .context-ledger/writing-quality.md and remove every TODO.

阅读完整来源 ↗