Documentation Manager
Living project knowledge for humans and AI agents. Code is the source of truth for how and for whether a claim is true.
AGENTS.md + docs/ capture what, why, decisions, and plans — but never override code when they disagree.
Core rules
- Prefer
AGENTS.mdas the hub. Ifagents.mdalready exists, use it. If onlyCLAUDE.mdexists, either extend it with a docs index or addAGENTS.mdand cross-link — do not create three competing hubs. - Every generated/updated doc uses relative Markdown links back to the hub and related docs.
- Never delete durable knowledge without a reason; prefer Superseded by notes on ADRs.
- Do not auto-commit or auto-push. Leave git to the user.
- Write generated content in the user's language (or the repo's dominant language). This skill body is English for ecosystem compatibility.
- Prefer accuracy and usefulness over volume. Core set first; optional docs on demand.
- Intent first (project-level). Classify Intent:
integrate|audit|from-zero(and optional hybrid). See Step 0. Not required for pure feature/plan/sync. - Code wins on conflict. Doc claims that fail structural verification are marked Contradicted/Missing — do not invent code to match docs; fix or flag the doc.
- Integrate-first (when Intent=integrate). Mature docs → index + gaps + canonical links; no parallel rewrite of product-vision/requirements/ADRs. See adopt-integrate.
- One authority per topic. Each topic has one canonical doc; everything else links.
- Coverage matrix on adopt/from-zero project. Product surfaces (nav, ModuleId, package) appear as documented / linked / gap.
- Feature atomicity. One slug ≈ one ModuleId or bounded context. Clusters = index + children.
- Status taxonomy. references/status-taxonomy.md.
- Sandbox opt-in / first-class from-zero.
Out: sandbox:pathwhen user asks (test/, etc.). Sandbox hubs banner non-SSOT + promotion plan. - Feature autopilot (v1.5 / v2). Plain “new feature X” / “documentá X” → skill chooses plan vs feature pack, applies default non-writes, sets Kind (new feature | spike | epic | redesign). Implementation bridge (placement / stubs) only on opt-in (“implementá”, “stubs”, “scaffold”) — default is docs-only + one-line hint. See modes.md §3 and implementation-bridge.md.
- Plan mode (v1.3+). Greenfield feature ideas land in
docs/plans/<slug>/, not a fake implementation pack and not a full project bootstrap. Promote todocs/features/<slug>/when code is real (not stubs alone). - ArkGate bridge (v1.4). If ArkGate is detected (
ark.config.json,ark-check,.ark/, ark skills) or the user just finished a gate, run the bridge sub-flow: enrich inventory from the contract; after gate pass → scoped sync / audit; residual violations → mark claims Contradicted/Partial — never rewrite docs to excuse broken architecture. No Ark → no-op. Placement hints in Implementation bridge reuse Ark layers when detected. See arkgate-bridge.md and modes.md §9. - Knowledge dashboard (v1.6). Optional static HTML view of plans/features/claims (
scripts/generate-docs-dashboard.sh→docs/audit/generated/dashboard.html). Markdown is SSOT; HTML is gitignored view-only. Offer after audit once or on “dashboard” request. See knowledge-dashboard.md and modes.md §10. - Skill hardening (v1.7). Maintainers: run
validate-skill.sh+test-skill-hardening.shbefore release. Agents: detect install/version via skill-discovery.md; suggest reinstall when outdated (no silent auto-patch). - v2.0 package. Completes the 10× line: capabilities 1.4–1.7 plus docs/adoption-matrix.md tracking. Baseline install floor remains 2.0.0; polyglot 2.1.0; monorepo 2.2.0; team 2.3.0; Bridge complete 2.4.0; current line is 2.5.0+ (Knowledge OS first increment toward 100× — living claims + CI audit; not a second 10×).
- Polyglot stack detection (v2.1 Slice A / skill 2.1.0). On project discover (integrate / audit / from-zero / adopt), detect stack from filesystem (
package.json,pyproject.toml,go.mod, …) via skill-discovery.md Polyglot stack detection (orscripts/detect-stack.sh). Use Inventory by stack and Docs layout guidance by stack — do not assume Node/TS. Never invent ModuleIds/endpoints for frameworks without code evidence. See modes.md §0.3. - Monorepo hubs (v2.2 Slice B). Detect multi-package trees (
pnpm-workspace.yaml,package.jsonworkspaces,go.work, multi-package dirs) via skill-discovery.md Monorepo hubs (orscripts/detect-packages.sh). Root hub is a map + Package index, not a dump; multi-package coverage marks gap packages; default package non-writes when only indexing root. See modes.md §0.4. - Team governance (v2.3 Slice C). Optional
docs/team/with owners + approval notes (last-approved style). Create vs link per team-governance.md; hub links Team without becoming an HR wiki; integrate-first — adding team must not rewrite product-vision / requirements / ADRs. No CODEOWNERS engine or BPM. See modes.md §11. - Template telemetry (v2.4 Slice D). Opt-in local ledger for template/skill UX gaps only (template-telemetry.md;
scripts/template-telemetry.sh). Default off; never-send source/secrets/repo URLs; network never; air-gapped no-op when opt-in off. See modes.md §12. - Living claims + CI structural audit (v2.5 / Knowledge OS first increment). Audit matrices use living claims v0:
anchor.path/ optionalanchor.symbol/ optionalanchor.hash,severity(critical|normal), verdicts unchanged. Matrix-first (audit-template.md); procedure living-claims.md; wire ADR-0001. Truth score stays advisory (dashboard heuristic); local air-gappedscripts/audit-claims.sh/ exampledocs-auditCI is the gate (fail on critical Contradicted). No SaaS. See modes.md §6 / §13.
Step 0 — Detect scope, mode, and Intent
Scope (required):
| Scope | When | Output focus |
|---|---|---|
| project | Whole product / “docs for the project” | Hub + project docs (per Intent) |
| feature | Named feature/module with code (or refresh pack) | docs/features/<slug>/ + hub link |
| plan | Named new feature / epic before or without solid code | docs/plans/<slug>/ + hub link |
| hybrid | Feature/plan when no hub yet | Pack or plan + minimal hub |
Mode (required):
| Mode | Signals |
|---|---|
| bootstrap | Greenfield, no hub/docs, or Intent from-zero on empty/thin |
| adopt | Code exists; docs thin/missing or Intent integrate |
| audit | “audit docs”, “docs vs code”, drift, validate claims |
| plan | “new feature”, “plan”, “epic”, “vamos a construir X” without code |
| feature | Document one feature/module that has (or is) code |
| sync | Diff / PR / update docs for a change; post-gate when Ark just passed |
| roadmap | Plan release / epic list refresh |
Intent (required for project-level work only):
| Intent | User signals (examples) | Behavior |
|---|---|---|
| integrate | “mejorar docs”, “ordenar”, “sync hub”, mature improve | adopt-integrate (or full if thin); optional pre-audit if drift suspected |
| audit | “auditar”, “¿las docs mienten?”, “docs vs code”, “validar paths” | Code inventory + claim matrix only (or then hand off) |
| from-zero | “toda nueva”, “de cero”, “generá docs en test/”, “full KB en carpeta X” | Full knowledge base; prefer sandbox if path given; code-inferred; old docs = hypothesis only |
Inference (do not over-ask):
- “nueva feature X” / “new feature X” / “quiero agregar X” → Feature autopilot (plan if no code, feature if code; Kind from phrasing). Intent = n/a
- “implementá X” / “generá stubs” / “scaffold X” → autopilot Stage A if needed + Implementation bridge opt-in (code only if stubs requested)
- “generá toda la documentación en
test/” → Intent: from-zero | Out: sandbox:test/ - Mature repo + “mejorá / integrá / indexá” → Intent: integrate
- “auditar docs” / “código vs docs” → Intent: audit
- Ambiguous project work with existing
docs/→ ask once: integrate | audit | from-zero - Named single surface → never require the user to list non-writes or choose folders
- “after ark-check” / “post-gate docs” / gate just ran + docs intent → sync or audit with ArkGate bridge
- “dashboard” / “docs HTML” / “knowledge report” → generate Knowledge dashboard (knowledge-dashboard.md)
- “owners” / “quién es dueño” / “team docs” / “approval notes” / “docs/team” → Team governance (team-governance.md; modes §11)
- “template telemetry” / “opt-in telemetry” / “record template gap” → Template telemetry only if user opts in (template-telemetry.md; modes §12); default off
- “living claims” / “truth score” / “docs CI” / “fail on Contradicted” → Living claims + local CI gate (living-claims.md; modes §13)
Maturity (when relevant): thin | mixed | mature — see modes.md.
If scope/mode still ambiguous after inference, ask once. Load procedures from references/modes.md.
Announce before writing:
Scope: <x> | Mode: <y> | Intent: <integrate|audit|from-zero|n/a> | Variant: <full|integrate|arkgate-bridge|n/a> | Maturity: <…|n/a> | Out: <root|sandbox:path> | Stack: <node-ts|python|go|mixed|unknown|n/a> | Monorepo: <yes|no|n/a> | ArkGate: <none|detected> | Slug: <slug|n/a>
When integrate, list non-writes (include package non-writes when monorepo root-index only). When audit, list matrix path and top contradictions. When from-zero + sandbox, include promotion plan. When plan or feature, list path + default non-writes. When ArkGate bridge, list signals and post-gate sync vs audit-enrich. When project-level, include Stack and Monorepo from discovery.
Recommended layout
project-root/
├── AGENTS.md
└── docs/
├── product-vision.md # bootstrap / from-zero / adopt-full
├── requirements.md
├── architecture.md
├── roadmap.md
├── team/ # v2.3 team governance (optional)
│ ├── OWNERS.md
│ └── approval-notes.md
├── audit/ # Intent audit (optional)
│ └── claims-matrix.md # living claims v0 columns
├── adr/ # package / project ADRs (optional)
├── plans/<slug>/ # v1.3 plan mode (pre-code / epic)
│ └── README.md
├── decisions/
└── features/<slug>/ # code-backed feature packs
Supporting docs only when justified (except from-zero, which may create a full minimal core set).
Artifact matrix (summary)
| Artifact | from-zero / bootstrap | integrate (mature) | audit | plan | feature | sync |
|---|---|---|---|---|---|---|
| Hub | create | extend / index | update status optional | link Plans | link | if needed |
| Core narrative docs | yes | no rewrite | no (read only) | no | no | if impact |
| Coverage matrix | yes | required | part of inventory | row optional | row | update |
| Claims matrix | optional pre | recommended if drift | required | n/a | scoped if audit | if drift |
Plans docs/plans/ | n/a | n/a | n/a | required | link if exists | if impact |
| Feature packs | key domains | gaps / entries | no (unless asked) | no (until promote) | required | if impact |
Team docs/team/ | if owners known | create/link if asked | no | n/a | n/a | if impact |
| Parallel full tree | sandbox ok | forbidden at root | n/a | n/a | n/a | n/a |
Workflow (all modes)
- Step 0 — scope, mode, Intent (if project), maturity/variant, Out, slug; detect ArkGate signals when relevant; detect Stack and Monorepo for project work (skill-discovery.md Polyglot + Monorepo hubs).
- Discover code first — stack-aware inventory; if monorepo, Package index + per-package inventory; tree, manifests, entry points, sample tests. Then docs (if any). For named features, search that surface first. If Ark detected, enrich inventory per arkgate-bridge.md.
- If audit or docs exist and Intent is integrate/from-zero with suspected drift: run reconciliation (modes.md § Audit, audit-template.md). Post-gate → bridge handoff (modes.md §9).
- Plan files — creates/updates and non-writes (defaults for feature/plan).
- Load templates → write/edit → hub pass.
- Summary — Intent/mode, files, non-writes, matrix stats, ArkGate note, promotion notes. No auto-commit.
Bootstrap / from-zero
Greenfield interview or code archaeology for brownfield from-zero. Full core set + hub. Sandbox if Out says so. See modes.md and § from-zero.
Adopt / integrate
Maturity → adopt-full or adopt-integrate. See modes.md §2.
Audit
Code inventory → structural claims → living-claims matrix (anchors + severity) → report. Code wins. CI gate separate from dashboard score. See modes.md §6, §13, living-claims.md.
Plan / Feature (autopilot v2)
Named surface → plan (docs/plans/<slug>/) if no code / planning language; feature (docs/features/<slug>/) if code-backed. Kind spike/epic/redesign when signaled. Default non-writes always. Optional Implementation bridge on implement/stubs language. Promote plan → pack when code is real. See modes.md §3 and implementation-bridge.md.
Sync / Roadmap
Blast-radius sync; roadmap links plans for net-new work. See modes §4–5.
ArkGate bridge (v1.4)
Detect Ark → post-gate sync/audit or inventory enrich; residual violations become claim debt, not narrative rewrites. See arkgate-bridge.md and modes §9.
Knowledge dashboard (v1.6)
Static HTML from existing docs only (generate-docs-dashboard.sh). View-only; markdown SSOT. See knowledge-dashboard.md and modes §10.
Team governance (v2.3)
Optional docs/team/ owners + approval notes; create vs link; integrate-first. See team-governance.md and modes §11.
Template telemetry (v2.4)
Opt-in local ledger for template gaps only; default off; air-gapped no-op. See template-telemetry.md and modes §12.
Living claims + CI audit (v2.5)
Matrix-first living claims; local audit-claims.sh / example docs-audit GHA; score advisory. See living-claims.md and modes §13.
Hub requirements
- Overview, nav links, agent instructions (read docs; update after significant work; ADRs; code wins), status line.
- Link Plans (
docs/plans/) and Features (docs/features/) when present. - Link Team (
docs/team/OWNERS.md) when team docs exist — pointer only, not an HR wiki. - Adopt / from-zero project: Surface coverage matrix (multi-package rows when monorepo).
- Monorepo: Package index on root hub (map, not dump).
- After audit: link to claims matrix if written.
Template: agents-md-template.md
Quality bar
Follow quality-checklist.md.
Anti-snapshot: no hardcoded table/route/endpoint counts.
Templates & references
| File | Use |
|---|---|
| references/agents-md-template.md | Hub + coverage |
| references/adr-template.md | ADRs |
| references/plan-template.md | Plan mode (docs/plans/<slug>/) |
| references/implementation-bridge.md | Implementation bridge (Stage B, stubs opt-in) |
| references/feature-readme-template.md | Feature entry |
| references/feature-cluster-template.md | Cluster index |
| references/architecture-template.md | Architecture |
| references/status-taxonomy.md | Status tokens |
| references/audit-template.md | Claims matrix + living-claims columns |
| references/living-claims.md | Living claims v0 (anchors, severity, truth score vs CI) |
| references/modes.md | Full procedures |
| references/arkgate-bridge.md | ArkGate bridge (detect, post-gate, violation→claim) |
| references/knowledge-dashboard.md | Knowledge dashboard (static HTML view; score advisory) |
| references/skill-discovery.md | Discovery / upgrade + Polyglot + Monorepo hubs (package index) |
| references/team-governance.md | Team governance (create/link, non-writes) |
| references/team-owners-template.md | Consumer docs/team/OWNERS.md |
| references/team-approval-notes-template.md | Consumer docs/team/approval-notes.md |
| references/template-telemetry.md | Template telemetry (opt-in, privacy, local ledger) |
| references/quality-checklist.md | Done criteria |
When NOT to use / defaults
- Pure code with no doc intent
- Throwaway notes outside the repo
- Silent overwrite of productive SSOT without Intent from-zero or explicit user order
- Mature improve without audit request → integrate (not full parallel tree)
- Replacing MkDocs/Docusaurus wholesale — integrate with it
- New feature request → do not run full project from-zero; use plan/feature autopilot
Activation
Standalone or with coding skills (including ArkGate / ark-* when present). Suggest doc updates after significant architecture/product changes; after a gate pass, offer bridge sync/audit once. Ask before large narrative rewrites unless Intent is from-zero or audit-driven patch.
After shipping a coded feature that only had a plan, suggest promote plan → feature pack.