diff --git a/.tasks/STATUS.md b/.tasks/STATUS.md index 23fa8f8..1e5590d 100644 --- a/.tasks/STATUS.md +++ b/.tasks/STATUS.md @@ -3,6 +3,14 @@ _Updated: 2026-04-28_ ## Done +### project-bootstrap: align wiki init with Karpathy canon +- [x] Read Karpathy gist + `wiki-maintainer` SKILL.md — gap confirmed +- [x] Rewrite Step 3: create `index.md`, `log.md`, `overview.md`, `.wiki/CLAUDE.md` schema, `raw/README.md`, empty `entities/ concepts/ packages/ sources/` with `.gitkeep` +- [x] Drop the bogus `SUMMARY.md` + `WORKFLOW.md` + `source/` from the template +- [x] Pin Karpathy gist URL inside the schema file +- [x] Rebuild + reinstall `project-bootstrap.skill` +- [x] Document the realignment in `.wiki/source/wiki-realignment.md` + ### project-bootstrap: include `active-platform` trigger in CLAUDE.md template - [x] Add `we're on Windows` line to `assets/CLAUDE.md.template` - [x] Update embedded preview in `SKILL.md` Step 5 (with note about Linux/macOS substitution) @@ -35,3 +43,4 @@ _Updated: 2026-04-28_ - Decide whether to write a smoke-test that round-trips `skills//` → `dist/.skill` → unpack → diff (would catch archive-shape regressions). - Tune `active-platform` triggers based on real-world usage; add WSL handling if it comes up. - Consider running formal `skill-creator` eval loop on `active-platform` once we have ~5 real interactions to learn from. +- **Migrate this repo's `.wiki/` to the canonical Karpathy layout** (it was bootstrapped with the old buggy template). Directory rename + file moves; needs a conscious commit, not a silent piggyback. diff --git a/.wiki/SUMMARY.md b/.wiki/SUMMARY.md index c3f0e48..7d60c64 100644 --- a/.wiki/SUMMARY.md +++ b/.wiki/SUMMARY.md @@ -8,3 +8,4 @@ The agent updates this file whenever source/ changes. - [repo-layout.md](source/repo-layout.md) — how the repo is organized: `skills/` sources, `dist/` builds, `scripts/` build & install - [build-notes.md](source/build-notes.md) — why `build.ps1` exists, ZIP layout, PowerShell 5.1 backslash gotcha - [active-platform-decision.md](source/active-platform-decision.md) — why we made `active-platform` a skill instead of a memory entry +- [wiki-realignment.md](source/wiki-realignment.md) — fixed `project-bootstrap` to create the Karpathy-canonical wiki layout (`index.md`/`log.md`/schema), not the bogus `SUMMARY.md`+`WORKFLOW.md` diff --git a/.wiki/source/wiki-realignment.md b/.wiki/source/wiki-realignment.md new file mode 100644 index 0000000..016f040 --- /dev/null +++ b/.wiki/source/wiki-realignment.md @@ -0,0 +1,50 @@ +# Wiki realignment to Karpathy canon + +_2026-04-28._ + +## What was wrong + +`project-bootstrap` Step 3 was creating `.wiki/SUMMARY.md`, `WORKFLOW.md`, +and a `source/` folder. **None of these match** Karpathy's LLM Wiki pattern +or what the `wiki-maintainer` skill reads: + +| Bootstrap created | Canon expects | +|---|---| +| `SUMMARY.md` | `index.md` | +| `WORKFLOW.md` (duplicates skill) | (no such file — workflow lives in `wiki-maintainer`) | +| `source/` (singular) | `sources/` (plural) | +| (missing) | `.wiki/CLAUDE.md` schema | +| (missing) | `log.md` (append-only op log) | +| (missing) | `entities/`, `concepts/`, `packages/`, `overview.md` | +| (missing) | `raw/README.md` | + +When `wiki-maintainer` triggered, it had to bend around an invented layout: +the schema file it expects to read first wasn't there at all, and the +catalog had the wrong name. + +## Fix + +Rewrote `project-bootstrap` Step 3 to create the canonical layout verbatim: + +``` +.wiki/ + CLAUDE.md schema (project-specific conventions) + index.md catalog of all pages + 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 documents that + entities/ concepts/ packages/ sources/ (with .gitkeep) +``` + +Each file has its initial content baked into the SKILL.md so bootstrap can +write them without external assets. + +The Karpathy gist is pinned at the top of `.wiki/CLAUDE.md`: +**https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f** + +## What about this repo's `.wiki/`? + +This repo was itself bootstrapped with the old buggy layout. Its `.wiki/` +still uses `SUMMARY.md` + `source/`. Migrating to canon is a directory +rename + file moves; queued as a backlog task to do consciously rather than +silently bundling it here. diff --git a/dist/project-bootstrap.skill b/dist/project-bootstrap.skill index 057e108..df80f68 100644 Binary files a/dist/project-bootstrap.skill and b/dist/project-bootstrap.skill differ diff --git a/skills/project-bootstrap/SKILL.md b/skills/project-bootstrap/SKILL.md index 5d1cd0b..8410fb6 100644 --- a/skills/project-bootstrap/SKILL.md +++ b/skills/project-bootstrap/SKILL.md @@ -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.md ← schema: 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 — -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 + + ``` -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 - +- [overview.md](overview.md) — project overview + +## Entities + + + +## Concepts + + + +## Packages + + + +## Sources + + ``` +### `.wiki/log.md` + +```markdown +# Wiki Log + +Append-only operation log. One entry per operation. Format: + +\`\`\` +## [YYYY-MM-DD] | +\`\`\` + +Operations: `init`, `ingest`, `query`, `lint`, `refactor`, `decision`. + +Parseable: `grep "^## \[" .wiki/log.md | tail -20`. + +--- + +## [] init | bootstrap empty wiki via project-bootstrap +``` + +### `.wiki/overview.md` + +```markdown +# — overview + + +``` + +### `.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/