Agent-Docs Mesh

A self-healing layer of agent-facing documentation every Kevin project carries as a byproduct of coding — reference at the repo root, procedures per significant directory, kept current by a docs-doctor and grown by builders as workflows develop.

Problem

Kevin works across ~60 repos. Agent context is ad hoc: some have AGENTS.md, some CLAUDE.md, most drift from the code. There is no standard enrollment, no drift detection, and no mechanism that grows docs as workflows evolve. Source: User + brainstorm, 2026-06-07

Standard — four artifacts (MECE)

Per-directory skills are reachable without nested AGENTS.md: the root doc's Directory Index (dir-map auto-block) lists each SKILL.md with a one-liner; agents read the nearest SKILL.md before editing in that directory. Source: spec §3, 2026-06-07

Content classes in AGENTS.md

• Auto-blocks (<!-- agent-docs:auto:<id> -->) — stack, commands, dir-map, env names; always regenerated by scaffold.
• Fill-slots (<!-- agent-docs:fill:<id> -->) — human/agent prose; written once, never overwritten.

This mirrors README repo-stats:auto markers in kevin-wiki. Source: spec §6.1, 2026-06-07

The mesh also emits a generated repo-graph auto-block. That block tells agents how to use Graphify safely for repo topology, PR risk, and onboarding without installing Graphify hooks or writing graphify-out/ into the project. Graph runs live under kevin-wiki/outputs/graphify/<repo>/. The same block reminds agents that qmd/Kevin-Wiki owns compiled knowledge, Browser Testing Skills owns browser/UI work, Playwright owns committed regression tests, and runtime memories such as Hindsight/Honcho do not become project truth until written back to AGENTS.md, SKILL.md, or the wiki. Source: User request, 2026-07-04

Pointer-index rule

Root agent docs (AGENTS.md, CLAUDE.md, CODEX.md, CURSOR.md) are indexes of pointers, not instruction warehouses. They should answer four questions quickly: what repo is this, what files should the agent open first, which generated command/skill index is authoritative, and which safety constraints are non-negotiable. Detailed behavior belongs in SKILL.md, generated command indexes, wiki procedures, package scripts, and per-directory docs. Source: User request, 2026-07-07

Delete a root-agent-doc line if removing it does not change routing, file choice, command choice, safety behavior, output contract, or verification. This is the same no-op pruning standard used by Browser Testing Skills and Matt Pocock's Skills (Skills for Real Engineers): if a line is vague encouragement, duplicated elsewhere, or impossible to act on, it is sediment.

Kit location

Canonical implementation: scripts/agent-docs/ in kevin-wiki. CLI: init | scaffold | doctor. Executable skill: skills/productivity/agent-docs/SKILL.md. Enrolled-repo registry: config/agent-docs/registry.json. Source: implementation, 2026-06-07

Other repos enroll via init (writes .agent-docs/ + shim) or vendor-copy the kit for CI independence.

docs-doctor (Plan 1 checks)

Deferred: drift, freshness, resolver (Plans 2–3). Source: spec §6.2, 2026-06-07

Significant-directory policy

Depth ≤ 2 from the run root, ≥ 3 source files, symlinks skipped. Prevents blast-radius scaffolds (e.g. 63 dirs → 5 on kevin-wiki pilot). Source: User + pilot, 2026-06-07

Rollout

Test-before-bulk: kevin-wiki (pilot 1, enrolled 2026-06-07) → loop → Agent-Machines → Princeton-TD → fleet. Each pilot: init → fill SKILL.md → doctor PASS → register → commit. Source: foundation plan, 2026-06-07

Self-extension (Plans 3–4)

Code-generating builders (build-scaffold, build-resolver, build-doctor) plus observations.jsonl → weekly codify proposals. Rule: third time you do something, codify it. Source: spec §6.4, 2026-06-07

AutoWiki comparison

Factory AutoWiki validates the same broad thesis from the hosted-product side: repository docs can be generated from source, refreshed on push, synced to GitHub Wiki, read by agents inside sessions, and treated as a build artifact. That strengthens the mesh's generated-block direction.

The boundary is ownership. AutoWiki-style generation is useful for architecture summaries, module maps, and flow explanations. Kevin's mesh still owns root reference, per-directory procedure, routing, fill slots, append-only history, and doctors. Generated docs may enrich the mesh only when they preserve source commit metadata and pass staleness, link, secret, and ownership checks.

---

Timeline

• 2026-07-07 | Added the pointer-index rule: root AGENTS.md / harness docs should stay short and route to durable skills, wiki pages, generated command indexes, and scripts rather than copying full procedures. Source: User request, 2026-07-07
• 2026-07-04 | Extended the generated project repo-graph block with memory/browser routing: qmd for compiled knowledge, Graphify for repo topology, agent-browser for browser work, Playwright for committed tests, and Hindsight/Honcho runtime memories only after writeback. Source: User request, 2026-07-04
• 2026-06-30 | Compared Factory AutoWiki against the mesh: adopt docs-as-build-artifact and source-hash refresh behavior, but keep Kevin-owned AGENTS.md, SKILL.md, RESOLVER.md, memory.md, fill slots, and doctors as the operational authority. Source: Factory AutoWiki; Factory docs, 2026-06-30
• 2026-06-17 | docs-doctor structure check tightened: root docs still fail when missing, while missing .agent-docs/, missing auto-block markers, and missing per-directory SKILL.md now warn as progressive enrollment drift. Source: Codex audit, 2026-06-17
• 2026-06-07 | Foundation kit shipped: detect, markers, scaffold/adopt, docs-doctor (structure/safety/links), kevin-wiki pilot enrolled on main. Source: User session, 2026-06-07
• 2026-06-07 | Personal agent-docs skill + registry + cursor rule codified for future-project enrollment. Source: User, 2026-06-07
• 2026-06-17 | Referenced in Vercel Eve — Vercel's eve framework ships the same "agent is a directory of files" model (instructions.md, skills/*.md, subagents/, schedules/) as this mesh; a shipped reference implementation of the filesystem-first agent thesis. Source: Vercel, 2026-06-17