fix(project-bootstrap): align wiki init with Karpathy canon

Bootstrap was creating .wiki/SUMMARY.md + WORKFLOW.md + source/ — none of
which match Karpathy's LLM Wiki pattern or what wiki-maintainer reads first.
The skill had to bend around an invented layout (no schema file, wrong
catalog name, missing log/overview/entities/concepts/packages).

Rewrote Step 3 to create the canonical layout verbatim:
  .wiki/CLAUDE.md          schema (project-specific conventions)
  .wiki/index.md           catalog
  .wiki/log.md             append-only op log
  .wiki/overview.md        project overview
  .wiki/raw/README.md      immutability note
  .wiki/{entities,concepts,packages,sources}/.gitkeep

Pinned the gist URL inside the schema:
  https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f

Bumped dist/project-bootstrap.skill, recorded the why in
.wiki/source/wiki-realignment.md, and queued migration of *this* repo's own
.wiki/ (still on the old layout) as a backlog task — to be done deliberately.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-04-28 11:17:36 +03:00
parent af94830fd5
commit 1cae0a2cf3
5 changed files with 167 additions and 22 deletions

View File

@@ -77,49 +77,134 @@ If it exists — leave it untouched.
If `.wiki/` already exists — skip it, notify the user.
If it does not exist — create the structure:
If it does not exist — create the **canonical Karpathy LLM-Wiki layout** (gist:
https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). The
`wiki-maintainer` skill expects exactly this shape; do not invent your own
names.
```
.wiki/
raw/raw inputs: transcripts, docs, links — anything not yet processed
source/ ← compiled knowledge: wiki pages maintained by the agent
SUMMARY.md ← table of contents: all source/ pages with one-line descriptions
WORKFLOW.md ← how to work with the wiki: when to read, when to update
CLAUDE.mdschema: project-specific wiki conventions
index.md ← catalog of all pages (by type), updated on every ingest
log.md ← append-only op log: ## [YYYY-MM-DD] op | desc
overview.md ← single human-readable project overview
raw/
README.md ← raw/ is immutable; this file documents that
entities/ ← entity pages (people, services, modules) — empty .gitkeep
concepts/ ← concept / design decision pages — empty .gitkeep
packages/ ← package pages — empty .gitkeep
sources/ ← one summary per ingested source — empty .gitkeep
```
Contents of `WORKFLOW.md`:
Page-level workflow (ingest, query, lint) and file formats are owned by the
`wiki-maintainer` skill. Bootstrap only lays the skeleton; the skill takes
over from there.
### `.wiki/CLAUDE.md` (schema)
```markdown
# Wiki Workflow
# Wiki Schema — <project name>
This wiki follows Karpathy's method: knowledge accumulates rather than being re-derived.
Project-specific wiki conventions. Read this before any wiki operation.
## Rules for the agent
This wiki follows Karpathy's LLM Wiki pattern:
**https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f**
- **Before starting work** — read relevant pages from source/
- **After an important decision** — update or create a page in source/
- **New raw materials** (links, docs, transcripts) — put in raw/
- **Processed knowledge** — write as markdown pages in source/
- **SUMMARY.md** — update whenever a page is added to source/
The `wiki-maintainer` skill enforces the workflow and file formats. This
file overrides the skill where they conflict.
## Trigger
## Page types
Skill is activated by the phrase: **use project wiki**
- `entities/` — discrete things the project tracks (people, services, modules).
- `concepts/` — recurring ideas, design decisions, gotchas.
- `packages/` — code packages this project produces or consumes.
- `sources/` — one summary page per ingested external doc; frontmatter carries `ingested:` and `raw_path:`.
- `overview.md` — single project-wide overview.
## Naming
- `kebab-case.md`, **Latin only**. Transliterate Cyrillic in filenames; keep the original title in the H1 + frontmatter.
## Domain conventions
<!-- Fill in as the project takes shape — what counts as an entity here, which packages exist, naming idioms specific to this codebase. -->
```
Contents of `SUMMARY.md`:
### `.wiki/index.md`
```markdown
# Wiki Summary
# Wiki Index
List of all pages in source/ with one-line descriptions.
The agent updates this file whenever source/ changes.
Catalog of all wiki pages. One line per page, organized by type. The agent updates this on every ingest.
## Pages
## Overview
<!-- Empty for now. Pages will appear as the project progresses. -->
- [overview.md](overview.md) — project overview
## Entities
<!-- (none yet) -->
## Concepts
<!-- (none yet) -->
## Packages
<!-- (none yet) -->
## Sources
<!-- (none yet) -->
```
### `.wiki/log.md`
```markdown
# Wiki Log
Append-only operation log. One entry per operation. Format:
\`\`\`
## [YYYY-MM-DD] <op> | <one-line description>
\`\`\`
Operations: `init`, `ingest`, `query`, `lint`, `refactor`, `decision`.
Parseable: `grep "^## \[" .wiki/log.md | tail -20`.
---
## [<today's date>] init | bootstrap empty wiki via project-bootstrap
```
### `.wiki/overview.md`
```markdown
# <project name> — overview
<!-- Replace with a high-level description: what this project does, who it's for, the main components. -->
```
### `.wiki/raw/README.md`
```markdown
# Raw Sources
**Immutable.** Read, never edit. The only allowed modification is appending a `> Status:` blockquote when the user explicitly asks for a status audit.
Place raw inputs here — articles, transcripts, PDFs, screenshots — exactly as they came in. The agent reads from `raw/`, writes summaries into `../sources/`, and never modifies raw files.
For large or path-sensitive sources that live outside the repo, register them here:
\`\`\`
- short-name → /absolute/path/to/source
\`\`\`
```
The empty subdirectories (`entities/`, `concepts/`, `packages/`, `sources/`)
each get a `.gitkeep` so git tracks them.
---
## Step 4 — .tasks/