agent-docs

Agent-Docs Mesh

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

Artifact Scope Job
AGENTS.md repo root Reference — what's true now (auto-blocks rewritten, prose preserved)
SKILL.md root + significant dirs Procedure — how to work here (read before editing in that dir)
memory.md repo root History — append-only session log (Plan 2)
RESOLVER.md repo root Routing — 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 <!-- agent-docs:auto: markers.
  2. Read root AGENTS.md (always-on reference) and the nearest SKILL.md for the directory you will edit.
  3. Repo topology — for onboarding, PR risk, path/explain/affected, or "what touches what?" questions, use the generated repo-graph auto-block and load graphify-sidecar before broad raw file reads.
  4. After substantive work — refresh machine facts and verify health (see commands below).
  5. Fill slots — write human/agent prose only in <!-- agent-docs:fill:* --> sections; never edit auto-blocks by hand.
  6. 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

Approach When
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 copy CI 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 <!-- agent-docs:auto:<id> --> — 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