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:
@@ -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/<name>/` → `dist/<name>.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.
|
||||
|
||||
@@ -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`
|
||||
|
||||
50
.wiki/source/wiki-realignment.md
Normal file
50
.wiki/source/wiki-realignment.md
Normal file
@@ -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.
|
||||
BIN
dist/project-bootstrap.skill
vendored
BIN
dist/project-bootstrap.skill
vendored
Binary file not shown.
@@ -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 — <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/
|
||||
|
||||
Reference in New Issue
Block a user