/project-wiki

name: project-wiki
description:
  Build and keep a Karpathy-style LLM wiki inside a repo, as a project record or
  a research vault, with a schema, an index, a log, a lint, and a Quartz site on
  GitHub Pages.
disable-model-invocation: true

Project wiki

A wiki is a persistent, compounding record: interlinked markdown pages the agent writes and maintains and the human reads. Knowledge is compiled once and kept current, so every page already carries its cross-references, its contradictions, and its place in the whole. The pattern is Karpathy's ([`references/karpathy-llm-wiki.md`](references/karpathy-llm-wiki.md)); this skill is its shape for a repo.

Three layers, all inside the repo:

• **Raw sources** (`raw/`): immutable. Read, never edited. Corrections go on

wiki pages.

• **The wiki**: the pages. Written by the agent only. In a project run by the

`lead` skill, the lead writes them and the worker never does.

• **The schema** (`SCHEMA.md`): the page types, frontmatter, tag taxonomy, and

conventions. The agent and the human co-evolve it; a convention changes there first, then on the pages.

Two presets, chosen at init: **project record** (plans, sessions, decisions, a roadmap board, a standing synthesis, maps) for a repo being built, and **research vault** (sources, entities, concepts, comparisons, filed queries) for a topic being studied. Both share the operations below.

Start of session

Read, in order: `SCHEMA.md` whole, `index.md`, the last 20 entries of `log.md` (`grep "^## \[" log.md | tail -20` finds them). In a project record, also the synthesis page and the roadmap board. Only then touch a page.

No `SCHEMA.md` in the repo means the wiki does not exist yet: follow [`references/init.md`](references/init.md).

Operations

Ingest

A source arrives (a URL, a file, a pasted transcript, a worker's report).

1. Save it under `raw/<kind>/` with frontmatter (`source_url`, `ingested`, and `sha256` of the body), named by what it is and when. 2. Find what already exists: search `index.md` and the pages for every entity, concept, or step the source names. This is the difference between a wiki and a pile of duplicates. 3. Write or update pages by the schema's thresholds: a page when a thing appears in two sources or is central to one, an update when it is already covered, nothing for a passing mention. Every page carries frontmatter from the schema, two or more outbound `[[wikilinks]]`, and a `## Related` list. New information that contradicts a page keeps both claims with dates, marks `contested: true` and `contradictions:` on both, and names the pair for the human. 4. Update `index.md` for new pages and append one `log.md` entry naming every file touched.

Done when every page the source bears on has been read and either updated or left with a reason.

Query

A question about the domain.

1. Read `index.md` to pick the pages; past a hundred pages, search the text too. 2. Read them, answer, and cite the pages. 3. File an answer worth keeping (a comparison, a synthesis, a connection) as a page of the schema's type for it; leave a lookup unfiled. 4. Append a `log.md` entry either way.

Checkpoint

The project-record preset's unit of work, run at every acceptance, every pause, and every closed topic.

1. Edit the pages the event touches: the plan's status and Result, the decision rows, the session page, the changelog, the roadmap board. 2. Bump `updated:` on each, add new pages to `index.md`, append one `log.md` entry. 3. At a pause, rewrite the synthesis page whole and the maps a landed page belongs on. 4. Run the lint and commit by path (`git commit -m <msg> -- <paths>`).

Done when the lint reports no broken links, no missing index entries, and no frontmatter faults, and the log's last entry is this checkpoint.

Lint

`python3 <wiki>/tools/lint.py` from the repo root: broken wikilinks, orphans, index completeness, required frontmatter, tags outside the taxonomy, raw drift, contested or low-confidence pages, pages over 200 lines, log size. Run it at every checkpoint and at the end of every session, and record the count in `log.md`. Issues the human owns stay listed and are named as theirs.

Publishing

The wiki reads as a site with Quartz and GitHub Pages, built on every push to the default branch. Setup is one branch of init: [`references/publish.md`](references/publish.md).

Conventions that hold in every preset

• File names lowercase with hyphens; a numbered page keeps its number forever.
• `created:` never changes; `updated:` is bumped on every edit.
• `raw/` is immutable; the `sha256` in its frontmatter is how drift shows.
• `index.md` lists every page with one line; `log.md` is append-only with the

prefix `## [YYYY-MM-DD] action | subject`.

• Tags come from the taxonomy in `SCHEMA.md`; add the tag there first.
• Who said what stays visible: the human's words are quoted as theirs, the

agent's recommendations are marked as recommendations.

• Prose the human reads comfortably: short paragraphs, narrow tables, snippets

under 20 lines.