The Wiki

The wiki is a compiled, structured knowledge base that outlives every session. It implements the Karpathy LLM Wiki pattern: raw source material is compiled once into interlinked markdown pages. Future sessions query the compiled wiki — never the raw specs. Compile once, query fast. Knowledge compounds.

Architecture

The wiki lives under superspec/wiki/ with the following layout:

superspec/wiki/
├── raw/                ← you drop files here; agent reads, never edits
├── _meta/
│   └── taxonomy.md     ← canonical tag vocabulary (managed by /superspecs:tag-taxonomy)
├── _archives/          ← timestamped vault snapshots (managed by /superspecs:wiki-rebuild)
├── Home.md             ← vault home: domain table + recent updates
├── log.md              ← append-only activity log (grep-friendly)
├── _manifest.json      ← machine-readable ingestion history
├── _lint-report.md     ← written by /superspecs:wiki-lint
├── _insights.md        ← written by /superspecs:wiki-status (optional)
└── <domain>/
    ├── Home.md         ← domain index
    ├── <topic-a>.md    ← one page per knowledge unit
    └── <topic-b>.md

The wiki is organized into three layers:

Layer	Path	Who touches it
Raw (source material)	`wiki/raw/`	You drop files; agent reads only
Compiled (knowledge base)	`wiki/`	Agent writes on ingest/query/capture
Schema (operating rules)	`.skills/verify-wiki/SKILL.md`	Defines how to ingest, link, and format

The wiki doubles as an Obsidian vault. Open superspec/wiki/ in Obsidian for graph view, backlinks, tag search, and hover previews — all pre-configured by superspecs install.

Domain Organization

Domains are concern-centric, not feature-centric. A page's domain describes what the knowledge is about, not which feature introduced it. Feature traceability lives in spec: frontmatter instead.

superspec/wiki/
├── patterns/        ← cross-cutting: error handling, caching, retry, testing
├── decisions/       ← ADRs: why X was chosen over Y
├── auth/            ← auth, sessions, tokens
├── api/             ← contracts, endpoints, versioning
├── data/            ← models, schemas, storage
├── infra/           ← deployment, CI/CD, environment
├── ui/              ← frontend, components, styling
├── techstack/       ← stack profile (managed by /superspecs:techstack)
└── <feature-slug>/  ← only if nothing above fits

Routing rules are applied by /superspecs:wiki on ingest:

Knowledge unit	Domain
Reusable cross-cutting pattern	`patterns/`
Why X was chosen over Y	`decisions/`
Auth / sessions / tokens	`auth/`
API contract or endpoint design	`api/`
Data model or storage decision	`data/`
Infrastructure or deployment	`infra/`
Frontend / UI / styling	`ui/`
Feature-specific, doesn't fit above	`<feature-slug>/`

One domain per page. If a page spans multiple concerns, split it. One knowledge unit = one page — merge instead of creating duplicates.

The canonical domain list lives in superspec/wiki/_meta/taxonomy.md under ## Domains. This file is created by superspecs install with the core domains pre-populated. Add project-specific domains to the "Project Domains" section before creating new folders. /superspecs:wiki-lint detects drift — folders that exist but aren't registered in the taxonomy.