v2.5.26 · Agent Skill · MIT
Your repo already has the truth in the code.
What it usually lacks is a durable story of what, why, and what’s next — one that coding agents can trust without hallucinating endpoints that don’t exist.
Documentation Manager is an Agent Skill that builds and maintains a living knowledge base next to your code. On-demand — not an always-on product.
Make knowledge enslavement inevitable for agents, with the human as captain.
| Why this shape | |
|---|---|
| Enslavement | Claims stay bound to code and parent knowledge. Agents stop inventing architecture from vibes. |
| Diff-first | Audit and reconcile reads default to the git change set. The merge CI gate still parses the whole claims matrix (existing critical Contradicted cannot hide). |
| Captain | The skill proposes. It never overrides the layout you already evolved. No auto-commit. Conflicts go to you (HITL). |
Binding decision: ADR-0002. Audit procedure: modes.md §6.0. CI examples (whole-matrix gate): .github/workflows/docs-audit.yml and an opt-in Vercel buildCommand (vercel-ci.md). ci-surface.sh reads either surface.
Playbook vs motor (honest, ~30 seconds). When you ask, agents follow documented procedures. Four on-demand loops on audit-claims.sh are real now — you run them; nothing watches the repo:
| Loop | Flag | What it does |
|---|---|---|
| Parse | --list-claims |
Read @claim from the git change set |
| Persist | --upsert-claims |
Write touched ids into the claims matrix |
| Record | --record-haken |
Note hold / for-review on Action (escalate/break → you decide) |
| Cascade-recommend | --cascade-recommend |
List children already in the set that need review when a parent was released |
Opt-in report (not a fifth enslavement loop): --group-by provenance groups the change set by explicit owner (TO-BE: frontmatter owner: / steward / CODEOWNERS) and git first/last buckets (AS-IS: human · bot/agent · unknown). Never invents owner from git. Orphans → propose owner: or archive. No write. See modes.md §6.11.
Haken is that parent/child test — a comment and a matrix note. It is not a database and not a daemon.
Still not a motor: walking the whole repo for children · a background enslavement engine · Orderfield/ArkGate ports · the LLM inventing the regime.
| Hub | Narrative | Plans | Features | Truth check |
|---|---|---|---|---|
AGENTS.md |
vision · requirements · architecture · roadmap · ADRs | docs/plans/<github-login>/<slug>/ |
docs/features/<slug>/ |
optional docs/audit/ claims matrix |
Whole project. Single module. Or a full rewrite in a sandbox — without torching the docs that already work.
Works with Claude Code, Grok Build, Codex, Cursor, and any host that loads SKILL.md skills.
One command. Ready in seconds.
npx skills add pedroknigge/documentation-managerNeed the helper scripts too (audit-claims.sh and friends)? Run the classic installer after npx — not before. npx replaces the skill folder and wipes those scripts. Classic install.sh writes ~/.gemini/skills/ when gemini or ~/.gemini is present (also ~/.gemini/config/skills/ and ~/.gemini/antigravity/skills/ if those parents already exist).
More install options
Global (all agents on this machine)
npx skills add pedroknigge/documentation-manager -g -yList skills in the package
npx skills add pedroknigge/documentation-manager -lClassic installer (npx first, then this — re-run to restore scripts)
curl -fsSL https://raw.githubusercontent.com/pedroknigge/documentation-manager/main/install.sh | bashUninstall:
curl -fsSL https://raw.githubusercontent.com/pedroknigge/documentation-manager/main/install.sh | bash -s -- --uninstallFrom source
git clone https://github.com/pedroknigge/documentation-manager.git
cd documentation-manager
./install.sh
./scripts/validate-skill.shNo auto-commit. No auto-push. You stay captain of git.
First run or a later audit/sync — copy and paste. Same honest stage: you ask; the agent follows the playbook. AS-IS vs TO-BE (§6.8) · stale comments (§6.10) stay report-only.
Use /documentation-manager in this repo.
1) Audit docs vs code (diff-first; full-tree only if the diff is useless).
2) AS-IS = what the code says. TO-BE = the latest living plan/claim per topic; mark the rest Superseded.
3) Update the claims matrix. Do not invent code. Do not auto-commit.
4) If you see stale narrative comments in the change set, report them; do not rewrite them.
5) At the end: what changed, what you left alone, and what needs my OK.
For whole-project work, the skill picks how hard it should write:
| Intent | Best when you want… | Writing style | |
|---|---|---|---|
| 1 | integrate | Better navigation on docs that already exist | Index · coverage · gaps · links — no parallel vision/requirements rewrite |
| 2 | audit | To know if the docs still match the change set | Diff-first claims matrix: OK · Partial · Missing · Contradicted |
| 3 | from-zero | A full knowledge base from scratch | Core set inferred from code (or a short greenfield interview); old docs = hypothesis only |
For a named feature, you don’t need Intent at all — feature autopilot chooses:
| Mode | Lands in | When | |
|---|---|---|---|
| A | plan | docs/plans/<github-login>/<slug>/ |
New idea / epic / no solid code yet |
| B | feature | docs/features/<slug>/ |
Code exists (or pack refresh) |
| C | promote | plan → feature pack | Implementation landed |
Lifecycle modes:
bootstrap · adopt · audit · plan · feature · sync · roadmap
Before it writes a byte, the skill announces scope so you can course-correct:
Scope · Mode · Intent · Variant · Maturity · Out · Slug
Default non-writes on plan/feature: no product-vision/requirements rewrite, no unrelated ADRs — even if you never listed them.
Slash command: /documentation-manager. Or just talk:
Plain-language examples
| You say | It leans toward |
|---|---|
| “Bootstrap docs for this greenfield SaaS.” | bootstrap / from-zero |
| “Nueva feature: team invitations.” | plan → docs/plans/<github-login>/team-invitations/ |
| “Documentá el módulo checkout en src/checkout.” | feature pack + hub link |
| “Promové el plan de team invitations.” | plan → docs/features/… |
| “We changed billing webhooks — sync the docs.” | surgical sync |
| “Audit docs vs code — do we still tell the truth?” | audit + claims matrix (diff-first) |
“Full knowledge base under test/, don’t touch prod docs.” |
from-zero · sandbox |
| “Improve and index what we already have.” | integrate (mature default) |
| “Gate passed — sync the docs.” / “after ark-check” | ArkGate bridge → scoped audit/sync |
| “Implementá team invitations” / “generá stubs” | plan/pack + Implementation bridge (stubs opt-in) |
| “Spike: rate-limit exploration” | plan Kind: spike (thin + open questions) |
| “Generate the knowledge dashboard” | static HTML view of docs (markdown SSOT) |
| “This is a pnpm monorepo — index packages.” | Monorepo hubs → root map + package index |
| “Python / Go stack — don’t assume Node.” | Polyglot stack detection + layout tables |
| “Add docs/team owners for this module.” | Team governance (optional OWNERS + notes) |
| “Nueva feature X” on a repo with code but weak architecture | plan + one vibe-proof HITL propose (never auto-run) |
“Nueva feature X” when pstack / /architect is on the host |
plan + pstack bake + one pstack HITL propose (never auto-run) |
project-root/
├── AGENTS.md ← single hub for humans + agents
└── docs/
├── product-vision.md
├── requirements.md
├── architecture.md
├── roadmap.md
├── audit/
│ └── claims-matrix.md ← when you ask for truth
├── plans/
│ └── team-invitations/ ← new work before code
│ └── README.md
├── team/ ← optional (v2.3): OWNERS + approval notes
│ ├── OWNERS.md
│ └── approval-notes.md
├── ops/ ← optional (v2.5.4): go/no-go Gate A/B trail
│ └── go-nogo.md
├── decisions/
│ └── ADR-001-….md
└── features/
└── checkout/
├── README.md
└── design.md
Monorepos (v2.2): root hub stays a map + package index; optional hub/docs per package.
Sandbox runs can mirror the same shape under a path like test/ — marked non-SSOT, with a plan to promote later.
ArkGate keeps code inside the architecture contract. Documentation Manager keeps the narrative honest against that code.
| ArkGate | Documentation Manager | |
|---|---|---|
| Owns | layers, gates, violations | hub, plans, features, claims matrix |
| Truth | contract + source | code wins on doc claims |
| After a change | ark-check / /ark-loop |
bridge: post-gate sync or audit |
When the skill sees ark.config.json, ark-check, .ark/, or ark host skills, it enriches inventory and, after a gate, offers a scoped docs pass. No Ark → no-op (never required). Residual violations become claim debt — docs are not rewritten to excuse broken architecture.
Procedure: skills/documentation-manager/references/arkgate-bridge.md
vibe-proof-auditor is the sibling production-readiness auditor. Documentation Manager stays the docs owner.
In plan mode, if the tree already has auditable code and architecture docs are weak or missing, the skill asks once (HITL): run vibe-proof and fold findings into the plan’s acceptance / MVP / next actions? Strong living architecture or no code → it does not ask. It never auto-runs. An explicit “close gaps” / “listo para prod” / “asegurá huecos” (or a vibe-proof flag) is the only internal call.
Procedure: skills/documentation-manager/references/vibe-proof-bridge.md
pstack (/architect, /figure-it-out) is the sibling design stack. Documentation Manager stays the docs owner.
In plan mode, the skill always applies a portable pstack bake (subtract-before-add, falsifiable acceptance, verifiable next actions, two approaches on one-way doors) so hosts without the plugin still get the rules. When those skills are present, it asks once (HITL): run /architect (or /figure-it-out for large ambiguous work) with checkpoint and fold findings into the plan? It never auto-runs. Absent plugin → bake only.
Procedure: skills/documentation-manager/references/pstack-bridge.md
This folder is the skill package (source of truth under
skills/documentation-manager/), not a product app that consumes the skill. Install it into other projects; only dogfood bootstrap here on purpose.
skills/documentation-manager/
SKILL.md ← agents load this first
references/ ← modes, templates, audit, quality bar
install.sh
scripts/
validate-skill.sh
install-smoke.sh
detect-stack.sh ← polyglot (v2.1)
detect-packages.sh ← monorepo (v2.2)
survey-docs.sh ← finds Readme.md, real ADRs only, skips examples unless you ask
audit-claims.sh ← CI gate + on-demand parse / persist / record / cascade-recommend (not a daemon)
generate-docs-dashboard.sh
(install.sh ships this runtime subset into the installed skill’s scripts/)
Developers of the skill
./scripts/validate-skill.sh
./scripts/test-skill-hardening.sh
./scripts/install-smoke.shPublishing notes → PUBLISH.md · Behavior source → SKILL.md
Philosophy in one line:
Code owns how and whether a claim is true.
Docs own what, why, and what’s next — and never override the code.
Version notes, shipped packs, and epics live off this page:
| Releases | CHANGELOG.md |
| Shipped packs | AGENTS.md |
| Roadmap / plans | docs/roadmap.md · docs/plans/ |
| Adoption | docs/adoption-matrix.md |
| Sales / dogfood | docs/sales-stats.json — anonymous aggregates also back or lower README claims when evidence changes (code wins; no target names) |
| Upgrade | npx first, then ./install.sh (or the curl/bash install.sh). npx last wipes scripts/. · skill-discovery.md |
Stop documenting for the archive.
Start documenting for the agents that ship with you.
Install · Try this prompt · North star · Honest stage · ADR-0002 · Skill source · MIT License