agent-docs

Generated source view for the actual executable productivity/agent-docs skill. The durable routing article is Agent Operations Skills. Source: skills/productivity/agent-docs/SKILL.md

Runtime Source

Bundled Resources

No bundled resource files.

Description

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.

Skill Source

---
name: agent-docs
description: 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.
origin: personal
source_slug: 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):

```bash
# 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 .
```

3. **Fill** every new `SKILL.md` `description` and `agent-docs:fill` slot with real procedures (not placeholders).
4. **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.
5. **Doctor** must pass structure + safety before commit:

```bash
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
```

6. **Register** the repo in `config/agent-docs/registry.json` (wiki) with path, date, wiki project page.
7. **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

```bash
# 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

## Related

- `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

---

Timeline

• 2026-07-15 | Generated a browseable source page from the actual executable skill file. Source: skills/productivity/agent-docs/SKILL.md