Skip to content

About

Living knowledge for codebases — AGENTS.md + docs/ agents trust. v2.4 Bridge complete: polyglot · monorepo · team · telemetry · ArkGate. Plan · Autopilot · Intent · Audit · Code wins.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Documentation Manager

Living knowledge for codebases — so agents and humans stop guessing.

v2.5.26 · Agent Skill · MIT

Install Skill version License


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.


Install

One command. Ready in seconds.

npx skills add pedroknigge/documentation-manager

Need 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 -y

List skills in the package

npx skills add pedroknigge/documentation-manager -l

Classic installer (npx first, then this — re-run to restore scripts)

curl -fsSL https://raw.githubusercontent.com/pedroknigge/documentation-manager/main/install.sh | bash

Uninstall:

curl -fsSL https://raw.githubusercontent.com/pedroknigge/documentation-manager/main/install.sh | bash -s -- --uninstall

From source

git clone https://github.com/pedroknigge/documentation-manager.git
cd documentation-manager
./install.sh
./scripts/validate-skill.sh

No auto-commit. No auto-push. You stay captain of git.

Try this prompt

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.

How it writes (when you ask)

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)

What lands in your tree

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.


Pair with ArkGate

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


Pair with vibe-proof-auditor

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


Pair with pstack

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 repository

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

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


History

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

About

Living knowledge for codebases — AGENTS.md + docs/ agents trust. v2.4 Bridge complete: polyglot · monorepo · team · telemetry · ArkGate. Plan · Autopilot · Intent · Audit · Code wins.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages