dox-describe

dox-describe

Turn a path-only directory AGENTS.md tree into a searchable kb corpus. A fresh kb dox init tree carries rows shaped | `file.ts` | | — the Purpose cell is empty, so the agents retrieval lane (the one file-lookup queries depend on) finds nothing. This skill fills those cells with one-line, caveman-style purposes, one subagent per AGENTS.md.

Read-only first: the CLI enumerates empty rows; the LLM only ever writes a Purpose cell. The parent never edits an AGENTS.md itself, and a subagent edits only the single file it was assigned.

Step 1 — enumerate the empty rows

kb dox describe --list --json

Parse { groups: [{ agentsPath, subjects: string[] }], total }. Each group is one AGENTS.md; each subject is a path whose Purpose cell is empty. Nothing to do when total === 0 — say so and stop.

Step 2 — present the plan and confirm

Show the user, then WAIT (ask_user, confirm) for approval before any write:

• number of AGENTS.md files (groups) and number of rows (total);
• a rough cost estimate (≈ rows × one short file read, plus one subagent per group; state it is a rough bound, not a promise);
• the per-run cap: 50 rows. Rows beyond the cap are DEFERRED to a re-run (the walk is empty-cells-only, so a re-run is resumable by construction);
• any row whose subject file is missing or unreadable (report, do not assign).

Never start fan-out without an explicit yes.

Step 3 — fan out ONE subagent per AGENTS.md

Cap concurrency at 2 in flight (the extension schedules a debounced reindex on every markdown write, and every subagent contends on the single SQLite index; ≤2 keeps SQLITE_BUSY recoverable — the parent's final reindex is authoritative). Skip groups whose rows are entirely past the cap.

Spawn with an inline Agent label (write-capable, parent defaults). Do NOT use Explore — it is read-only and cannot fill cells.

Each subagent's task must include:

• the absolute AGENTS.md path and its assigned subjects (cap 50 total across all groups for this run);
• must read every file it describes — never guess from the filename;
• the row rules:
  • ONE line per row, exactly the schema | `file` | purpose |;
  • purpose ≤ 200 chars, caveman style: short declarative fragments, drop articles/copulas, subject → verb → object;
  • name key exports / contracts / params verbatim (symbolName, paths, env vars); concrete tokens over prose;
  • CONDENSE, never promote to a <File>.AGENTS.md sidecar — sidecar splitting is the parent's/scripts/split-large-agents.mjs job;
  • edit ONLY its own AGENTS.md; do not touch any other file;
  • write the purpose into the EXISTING row (same line, same path cell) — do not add, delete, or reorder rows;
  • a subject file that cannot be read (missing, binary, 0-byte) → leave its Purpose cell EMPTY and report it back; never invent a purpose.