agent-docs

kevin-wiki / scripts/agent-docs

Purpose

The Agent-Docs Mesh kit — the engine that scaffolds, adopts, and health-checks the layered agent documentation (AGENTS.md + per-directory SKILL.md, with memory.md + RESOLVER.md coming in later plans) for any repo. It detects a repo's stack and structure, renders/refreshes machine-derived auto-blocks without ever clobbering human prose/fill-slots, and runs a docs-doctor.

Mental model & key files

  • detect/ — pure, synchronous detectors (StackDetector, DirtreeDetector) each extend BaseDetector and contribute part of a RepoProfile; merged in detect/index.ts.
  • render/ — markers.ts (idempotent auto-block engine), templates/ (module- driven AGENTS.md + SKILL.md), scaffold.ts (non-destructive plan: refresh auto-blocks, append missing ones, leave prose untouched).
  • doctor/ — BaseCheck registry (structure, safety, links) run by doctor/index.ts; mirrors the shape of the wiki's scripts/doctor.ts.
  • lib/ — repo-walk.ts (significant-dir detection), write-plan.ts (apply planned writes).
  • index.ts — CLI: init | scaffold | doctor.

Patterns to follow / invariants

  • TDD with node:test + assert/strict; run npm run test:agent-docs.
  • ESM: local relative imports use a .js extension (NodeNext).
  • Auto-blocks (<!-- agent-docs:auto:<id> ... -->) are always regenerated; fill-slots / prose are never overwritten. This is the core safety property.
  • A significant dir = depth ≤ 2 from the run root AND ≥ 3 source files. Missing per-dir SKILL.md is a warn; only AGENTS.md + root SKILL.md are hard-required.
  • Symlinks (and dangling links) are skipped in the walk — never followed.
  • Extend, don't fork: a new signal → subclass BaseDetector; a new health check → subclass BaseCheck.

Common tasks → first action

  • Add a doctor check → create doctor/checks/<name>.ts extending BaseCheck, register it in the CHECKS array in doctor/index.ts, add a red→green test.
  • Add a detector → create detect/<name>-detector.ts extending BaseDetector, register in DETECTORS in detect/index.ts.
  • Change generated doc shape → edit render/templates/agents.ts / skill.ts.
  • Run against a repo → node --import tsx scripts/agent-docs/index.ts <init|scaffold|doctor> <root> [--json].

Gotchas

  • significantDirs depth is measured from the run root — for a monorepo, enroll each package separately so its modules sit at depth ≤ 2.
  • upsertAutoBlock is a no-op if the marker is absent; mergeAgents appends missing blocks under the "Agent-docs (auto-maintained)" section instead.
  • reportDoctor writes .agent-docs/doctor-results.json only if .agent-docs/ already exists (so a pre-enrollment doctor run is read-only).
  • parseCliArgs strips flags before the repo root — doctor --json (no root) defaults to cwd. Other repos use scripts/run-agent-docs.ts shim → canonical kit.