agent-docs

Enroll and maintain the Agent-Docs Mesh on any Kevin project — layered AGENTS.md + per-dir SKILL.md, auto-blocks, Graphify repo-graph awareness, docs-doctor. Use when entering a new repo, starting work on loop/Dedalus/any project, "enroll this repo", "agent docs", "scaffold AGENTS.md", "docs-doctor", "agent-docs mesh", "use graphify with projects", after substantive edits to refresh machine facts, or when Kevin says keep agent documentation current.

Category
Productivity
Skill
212 of 261
Source
Kevin wiki

Every Kevin project carries four artifacts (MECE). Plan 1 ships the first two; Plans 2–6 add the rest.

ArtifactScopeJob
AGENTS.mdrepo rootReference — what's true now (auto-blocks rewritten, prose preserved)
SKILL.mdroot + significant dirsProcedure — how to work here (read before editing in that dir)
memory.mdrepo rootHistory — append-only session log (Plan 2)
RESOLVER.mdrepo rootRouting — task → skill/doctor (Plan 2)

Canonical kit: ~/Documents/GitHub/kevin-wiki/scripts/agent-docs/ Spec: docs/superpowers/specs/2026-06-07-agent-docs-mesh-design.md Concept: wiki/concepts/agent-docs-mesh.md Enrolled repos: config/agent-docs/registry.json

Session protocol (every project)

  1. Check enrollment — repo has .agent-docs/ and AGENTS.md contains `

` sections; never edit auto-blocks by hand.

  1. Third time rule — if a workflow repeats 3×, codify it (future: build-scaffold / build-resolver / build-doctor).

Enroll a new repo (test-before-bulk)

Pilot order: kevin-wiki ✓ → loop → reticle-ui/Agent-Machines → ariadne/Princeton-TD → bulk.

  1. cd <repo>
  2. Run init (uses canonical kit via shim, or in-repo kit if vendored):
# From kevin-wiki checkout (canonical kit in-tree):
node --import tsx ~/Documents/GitHub/kevin-wiki/scripts/agent-docs/index.ts init .

# Or, after init wrote scripts/run-agent-docs.ts:
npm run agent-docs -- init .
  1. Fill every new SKILL.md description and agent-docs:fill slot with real procedures (not placeholders).
  2. Graphify sidecar is automatic: init / scaffold writes the repo-graph auto-block into AGENTS.md. Keep generated graph runs in ~/Documents/GitHub/kevin-wiki/outputs/graphify/<repo>/; do not install Graphify hooks into the project.
  3. Doctor must pass structure + safety before commit:
node --import tsx ~/Documents/GitHub/kevin-wiki/scripts/agent-docs/index.ts doctor --json
# exit 0 required; warnings on missing per-dir SKILL.md are OK during rollout
  1. Register the repo in config/agent-docs/registry.json (wiki) with path, date, wiki project page.
  2. Show Kevin the diff sample (3–5 files) before bulk-enrolling more repos.

Monorepo packages

Run init per package root (e.g. website/, api/) so significant dirs sit at depth ≤ 2 from that root. Do not init once at monorepo root and expect every nested app to get correct dir-map depth.

Vendoring vs shim

ApproachWhen
In-tree kit (kevin-wiki)Kit lives at scripts/agent-docs/; npm run test:agent-docs
Shim (scripts/run-agent-docs.ts)Other repos; init writes shim → canonical kit via KEVIN_WIKI_ROOT or ~/Documents/GitHub/kevin-wiki
Vendor copyCI must run doctor without wiki checkout; copy scripts/agent-docs/ + add test:agent-docs

Commands

# Enroll + scaffold/adopt (creates .agent-docs/, AGENTS.md auto-blocks, SKILL.md stubs)
agent-docs init [root]

# Refresh auto-blocks only (non-destructive; prose untouched)
agent-docs scaffold [root]

# Health check (structure=safety fail; missing per-dir SKILL=warn)
agent-docs doctor [root] [--json]

# Tests (kevin-wiki or vendored kit)
npm run test:agent-docs

doctor --json without an explicit root defaults to cwd — flags are stripped before path resolution.

Invariants (never break)

  • Auto-blocks ` — machine-derived; always regenerated by scaffold`.
  • Fill-slots / prose — written once; never overwritten by scaffold.
  • Adopt, don't clobber — existing marker-less AGENTS.md gets a managed section appended; human prose stays verbatim.
  • Significant dir = depth ≤ 2 from run root AND ≥ 3 source files; symlinks skipped.
  • Doctor severity — missing root AGENTS.md/SKILL.md = fail; missing .agent-docs/, missing agent-docs:auto markers, or missing per-dir SKILL.md = warn (progressive).
  • Secrets — env var names only in docs; values = doctor fail.

Generated docs boundary

Treat Factory AutoWiki-style output as evidence for docs-as-build-artifact, not as a replacement for this mesh. Generated repo wikis can summarize architecture, modules, and flows, and they should carry source hashes plus refresh metadata. They must not overwrite hand-authored AGENTS.md, SKILL.md, RESOLVER.md, memory.md, or agent-docs:fill prose.

If a project adopts generated wiki output, route it through the doctor: verify source commit, staleness, links, secrets, and ownership boundaries before agents trust it.

Extending the kit

Read scripts/agent-docs/SKILL.md (module-level procedures for the kit itself).

  • New detector → detect/<name>-detector.ts extends BaseDetector
  • New check → doctor/checks/<name>.ts extends BaseCheck
  • TDD: node:test + assert/strict; red → green before merge
  • wiki-doctor skill — wiki repo health (separate from per-project docs-doctor)
  • skill-creator — when a mesh workflow itself should become a skill
  • doctor-pattern concept — shared shape with scripts/doctor.ts
  • conventions-test-before-bulk — pilot 1 repo before fleet rollout