tend-wiki

---
name: tend-wiki
version: 0.1.0
description: Curate the project's memory into an LLM Wiki (Karpathy's pattern) — an interlinked markdown knowledge base. Three bounded operations — INGEST a source into a summary page with [[wiki-links]] + an index entry; QUERY the wiki with citations and file good answers back; LINT to fix contradictions, stale claims, orphans, and missing links. The deterministic capture-learnings hook stays as the un-loseable floor; this skill is the LLM curation on top. Bounded by .agent/wiki.conf so it can't run away. Trigger with "ingest a source into the wiki", "tend the wiki", "lint the wiki", or "/tend-wiki".
---

# Tend Wiki

Turn the flat `.agent/memory/` store into a real **LLM Wiki**: knowledge compiled **once** into
interlinked markdown pages that **compound**, instead of notes re-derived per session. The agent
writes; the human curates the sources and asks the questions.

> **Operating principle:** compile-once-compounds, *bounded and grounded*. Each run does a **small,
> defined amount** of curation (read `.agent/wiki.conf` caps) and then **stops with a short report** —
> never a recursive expansion or an unbounded loop. Lint is precision-first: only flag a real,
> citable contradiction; if the wiki is clean, **say so and stop** (abstain). The deterministic
> capture-learnings hook is the un-loseable floor under all of this — this skill never deletes a raw
> note it hasn't safely folded in.

## The store as a wiki
`.agent/memory/` is the wiki. v2 format:
- **Pages**: `conventions/*.md`, `reference/*.md`, … — one concept/entity per file.
- **`[[wiki-links]]`**: cross-link related pages by their slug (e.g. `see [[skill-mirror]]`).
- **`index.md`**: a catalog — one line per page: `- [[slug]] — one-line summary (updated: <date>)`.
- **`reference/*` pages carry a `Sources:` line** — where the knowledge came from.
- **`session-log.md`**: the existing append-only log (the audit trail; not a wiki page).
- **`_staging.md`**: the deterministic capture inbox (un-loseable; this skill folds it in, never wipes it raw).

## The three operations

### `ingest <source>`
Fold a new source (a staged note, a pasted doc, a file, a URL the user provides) into the wiki:
1. Read the source. Write/append a concise **summary page** under the right path (`reference/<slug>.md`
   for external facts, `conventions/<slug>.md` for project rules), with a **`Sources:`** line.
2. Add **`[[wiki-links]]`** to (and from) the few genuinely related existing pages — at most
   `WIKI_MAX_LINKED_PAGES` (default ~10). Do **not** rewrite unrelated pages.
3. Update **`index.md`** (add/refresh the page's catalog line) and append a dated entry to `session-log.md`.
4. If you ingested from `_staging.md`, clear only the section(s) you fully folded in. **Stop + report.**

### `query <question>`
Answer **from the wiki**, citing the page(s) (`[[slug]]`) you used. Read only the relevant pages
(`index.md` first to find them) — not the whole store. If the answer is durable and not yet captured,
**file it back** as a new/updated page (then it compounds). Report the answer + what you filed.

### `lint`
A bounded health pass over the wiki (at most `WIKI_MAX_LINT_PAGES`, default ~20):
- **Contradictions** — two pages that make incompatible claims. Only flag a **real, citable** one
  (quote both lines); propose the fix, don't guess which is right if it's genuinely ambiguous.
- **Stale / orphan / missing-link** — pages nothing links to, broken `[[links]]`, an out-of-date
  `index.md`. Fix the mechanical ones (index, dead links); report the judgment ones.
- **Abstain when clean** — if there's nothing real to fix, say "wiki is clean" and stop. Do **not**
  invent issues (the precision lesson: a reviewer that's quiet on clean input is the trustworthy one).

## Bounds (always on — read `.agent/wiki.conf`)
- `WIKI_MAX_LINKED_PAGES` — most pages a single ingest may touch (default ~10).
- `WIKI_MAX_LINT_PAGES` — most pages a single lint may scan (default ~20).
- `WIKI_AUTOCURATE` — whether the agent should curate proactively (e.g. before compaction) or only
  on explicit invocation (default: on explicit invocation — keeps cost deliberate).
- Every run is **one bounded pass** that ends with a short report. Never recurse, never "keep going
  until perfect." If the scope exceeds the caps, do what fits and report the remainder.

## Relationship to the deterministic memory loop (the floor)
`capture-learnings.sh` (PreCompact) and `load-memory.sh` (SessionStart) stay **deterministic** — the
un-loseable capture + the cheap re-inject. This skill is the **LLM curation** layer the agent runs to
turn raw captures + sources into a proper wiki. If curation never runs (or hits its cap), you still
have the primitive deterministic memory — nothing is ever lost. The wiki is the primary model;
determinism is the floor.

## Portability
Follows the Agent Skills (`SKILL.md`) standard. Canonical in `.agents/skills/tend-wiki/`; mirrored
byte-identical to `.claude/skills/tend-wiki/`. Config: `.agent/wiki.conf`. Floor hooks:
`.agent/hooks/capture-learnings.sh` + `load-memory.sh`.

More agent context in CodyAMaughan/agent-first-engineering

30 other files this repository gives its agents.