{"id":51510430,"url":"https://github.com/kostiantyn-matsebora/docs-keeper","last_synced_at":"2026-07-08T05:30:27.768Z","repository":{"id":368279651,"uuid":"1279634313","full_name":"kostiantyn-matsebora/docs-keeper","owner":"kostiantyn-matsebora","description":"Documentation steward for coding agents — writer + hierarchical Markdown indexer + sources-of-truth registrar with a commit-time drift gate. Platform-neutral core + thin Claude Code plugin; stack-, domain-, and product-agnostic.","archived":false,"fork":false,"pushed_at":"2026-06-29T20:34:46.000Z","size":206,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-29T22:21:26.242Z","etag":null,"topics":["agent-skills","ai-agent","automation","claude","claude-cli","claude-code","developer-tools","docs","documentation","documentation-tool","drift-detection","indexing","llm","markdown","plugin","sources-of-truth","technical-writing"],"latest_commit_sha":null,"homepage":"https://kostiantyn-matsebora.github.io/docs-keeper/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kostiantyn-matsebora.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-24T21:54:15.000Z","updated_at":"2026-06-29T20:32:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kostiantyn-matsebora/docs-keeper","commit_stats":null,"previous_names":["kostiantyn-matsebora/docs-keeper"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/kostiantyn-matsebora/docs-keeper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kostiantyn-matsebora%2Fdocs-keeper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kostiantyn-matsebora%2Fdocs-keeper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kostiantyn-matsebora%2Fdocs-keeper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kostiantyn-matsebora%2Fdocs-keeper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kostiantyn-matsebora","download_url":"https://codeload.github.com/kostiantyn-matsebora/docs-keeper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kostiantyn-matsebora%2Fdocs-keeper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35253862,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-agent","automation","claude","claude-cli","claude-code","developer-tools","docs","documentation","documentation-tool","drift-detection","indexing","llm","markdown","plugin","sources-of-truth","technical-writing"],"created_at":"2026-07-08T05:30:27.311Z","updated_at":"2026-07-08T05:30:27.753Z","avatar_url":"https://github.com/kostiantyn-matsebora.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# docs-keeper\n\nA **stack-, domain-, product-agnostic** documentation steward: a documentation writer +\nhierarchical indexer + sources-of-truth registrar. The capability is **platform-neutral\nat its core**, with **thin per-platform adapters**. The Claude Code adapter (a plugin) is\nthe first; this repo doubles as its own single-plugin marketplace.\n\n## What it does\n\n- **Index.** Build / refresh per-directory `index.md` files (github/docs-style\n  recursive-descent `children:` lists with sub-index boundaries) and walk up the tree.\n- **Revise.** Tighten or author docs against the host project's authoring rules\n  (extract-over-compact, structure-over-prose), never inventing product decisions.\n- **Register.** Keep the host's \"sources of truth\" registry in minimum-footprint sync.\n- **Sweep.** Cross-doc consistency: orphans, broken links, ambiguous resolutions, legacy\n  READMEs.\n- **Guard.** A commit-time drift gate (block / warn), session tracking of edited docs, and\n  capture of doc-worthy decisions — all backed by the same neutral engine.\n\n## Layout\n\n```\ncore/\n  engine/      Platform-neutral Python engine (pure drift/session/capture + git/fs\n               collaborators) + a neutral `cli.py --drift-only` for CI on any platform.\n  spec/        Platform-neutral spec: role.md, conventions/, the 7 command procedures,\n               and companion templates (Documentation Report, anchor slugs).\nadapters/\n  claude-code/ The Claude Code plugin: .claude-plugin/plugin.json, thin hooks/cc_*.py\n               entrypoints (CC payload \u003c-\u003e engine), hooks.json, agents/ + commands/\n               wrappers, and the vendored core (hooks/_engine/ + spec/, generated).\n  copilot/     Reserved contract stub referencing the same core/engine API.\nbuild/\n  assemble.py  Vendors core/ into the adapter so the plugin is self-contained\n               (Claude Code plugins cannot reference files outside their root);\n               `assemble.py --check` guards core \u003c-\u003e adapter sync in CI.\n.claude-plugin/marketplace.json   This repo as a single-plugin marketplace.\n```\n\n**Core / adapter separation (invariant).** No host-specific payload field names, hook\ndecision verbs, or plugin-root references live in `core/` — adapters translate their\nplatform's hook payload into engine calls at the edge. CI enforces this.\n\n## Install (Claude Code)\n\ndocs-keeper is distributed from this repository as a single-plugin marketplace and installs\n**per repository**, not per user — so the whole team (and CI) picks it up from one committed\nconfig. Run these in the repo you want to steward:\n\n```\nclaude plugin marketplace add kostiantyn-matsebora/docs-keeper\nclaude plugin install docs-keeper@docs-keeper --scope project\n```\n\n`--scope project` writes the enablement into the repo's `.claude/settings.json` — commit that\nfile and every collaborator gets docs-keeper automatically. A plain `/plugin install` inside a\nsession enables it for **you** only; use project scope so it travels with the repo.\n\nThis registers the `docs-keeper` agent, the seven `/docs-keeper:*` commands (see\n[Commands](#commands)), and the SessionStart / PreToolUse / PostToolUse / PostCompact / Stop /\nSessionEnd hooks.\n\nConfigure docs-keeper via `.docs-keeper/config.json`, a per-repo settings file you commit\nalongside your docs:\n\n```json\n{\n  \"enforcement\": \"warn\",\n  \"paths\": [\"**/*.md\"]\n}\n```\n\n- **`enforcement`** — `warn` surfaces the drift queue without blocking; `block` fails the\n  commit (exit 2) on drift. Defaults to `block` when the file or setting is absent.\n- **`paths`** — array of glob patterns docs-keeper watches and indexes. Defaults to\n  `[\"**/*.md\"]` (every Markdown file in the repo). Narrow it (`[\"docs/**/*.md\"]`) or add\n  more globs (`[\"docs/**/*.md\", \"adr/**/*.md\", \"**/*.mdx\"]`) to change scope. Globs support\n  `**/` (any depth), `*` (within a path segment), and `?`.\n\nEdit the file directly, or use the `/docs-keeper:config` command to view and change settings\nwith validation:\n\n```\n/docs-keeper:config                                 # show current config\n/docs-keeper:config enforcement block               # switch enforcement\n/docs-keeper:config paths docs/**/*.md adr/**/*.md  # replace the watch/index globs\n```\n\nPer-machine runtime state (session / capture files) lives under `.docs-keeper/sessions/` and\nstays gitignored — only `config.json` is committed.\n\n### First run (bootstrap)\n\nInstall registers the agent/commands/hooks but does not touch your repo. To reach a green\nbaseline — index your docs and create the \"sources of truth\" registry — run once:\n\n```\n/docs-keeper:setup            # whole repo\n/docs-keeper:setup docs/      # or scope to specific doc roots\n```\n\nAfter that, the commit-time gate and `/docs-keeper:index` · `revise` · `sweep` ·\n`registry-sync` keep things in sync.\n\n## Commands\n\n| Command | Use it when |\n|---|---|\n| `/docs-keeper:setup [roots...]` | First run — bootstrap config + indexes + registry |\n| `/docs-keeper:index \u003cdir\u003e` | A directory's docs changed, or you want to (re)build / split an index |\n| `/docs-keeper:revise [doc] [-- brief]` | Tighten an existing doc or author a new one |\n| `/docs-keeper:registry-sync` | The \"Sources of truth\" registry drifted |\n| `/docs-keeper:sweep [scope]` | Consistency check — orphans, broken links, legacy READMEs |\n| `/docs-keeper:capture` | Record a doc-worthy decision for later |\n| `/docs-keeper:config` | View or change settings |\n\n## Use without a platform (neutral CI gate)\n\n```\npython3 core/engine/cli.py --drift-only [--repo-root \u003cpath\u003e] [--enforce warn|block]\n```\n\nExit 0 (clean) or 2 (drift; message on stderr). No hook host required.\n\n## Alternatives \u0026 comparison\n\ndocs-keeper occupies a niche no single tool covers: **agent-native, in-repo, structural\ndocumentation stewardship**. Adjacent tools each cover one slice; none unify\n**INDEX + REVISE + REGISTER + DRIFT GATE + CAPTURE + SWEEP**.\n\n| Competitor | Overlaps | docs-keeper does better |\n|---|---|---|\n| **Swimm** | Drift gate | Gates inside coding-agent hooks (not just PR-check time); watches all Markdown + indexes + registry, not only code-coupled snippets; no full-history requirement. |\n| **Doc Detective** | Consistency sweep | Static index/registry/link analysis with a fix queue, vs runtime tests against a live product. |\n| **lychee / markdown-link-check** | Broken links | Adds orphans, ambiguous resolutions, registry sync, and indexing — not links alone. |\n| **Mintlify `llms.txt`** | Indexing | Recursive per-directory `index.md` with ancestor walk-up, vs one flat hosted index (100K-char cap). |\n| **Docusaurus / MkDocs / Sphinx / Antora** | Nav + link check | Automatic code-to-docs drift detection and walk-up indexing, vs manual nav and release-snapshot versioning. |\n| **adr-log / Log4brains / Backstage** | Registry | Whole-repo sources-of-truth sync + drift gating, not ADR-scoped manual nav edits. |\n\n**Where docs-keeper wins:**\n\n- Commit-time drift gating wired into coding-agent hooks.\n- Hierarchical `index.md` generation with ancestor walk-up.\n- Agent-native decision capture during coding sessions.\n- Platform-neutral core + thin adapters.\n\n**Where established tools still lead:** hosting, versioning, ecosystem breadth, and\nnon-Markdown/API docs.\n\n## Example host repo (pair-repo)\n\n`docs-keeper-example` is a standalone sample host project — the **Acme Stack** app (frontend +\nbackend + infrastructure + testing + docs) — used to exercise docs-keeper end-to-end and as a\nrunnable example. It ships a clean docs baseline and a pairing test that runs this engine against\nitself. Keep it checked out next to this repo to run the pairing suite.\n\n## Develop\n\n```\npython3 -m pytest          # core + adapter + build suites (no mocks)\npython3 -m ruff check .     # lint\npython3 build/assemble.py           # regenerate the vendored plugin\npython3 build/assemble.py --check   # CI: fail if core \u003c-\u003e adapter drifted\n```\n\nAfter editing anything under `core/`, re-run `build/assemble.py` so the vendored copies\ninside `adapters/claude-code/` stay in sync (CI's `assemble --check` enforces it).\n\n## License\n\nMIT — see [`LICENSE`](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkostiantyn-matsebora%2Fdocs-keeper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkostiantyn-matsebora%2Fdocs-keeper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkostiantyn-matsebora%2Fdocs-keeper/lists"}