From 1cae0a2cf3005438fe273d5da6e2545486f2a805 Mon Sep 17 00:00:00 2001 From: vitya Date: Tue, 28 Apr 2026 11:17:36 +0300 Subject: [PATCH] fix(project-bootstrap): align wiki init with Karpathy canon MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- .tasks/STATUS.md | 9 +++ .wiki/SUMMARY.md | 1 + .wiki/source/wiki-realignment.md | 50 ++++++++++++ dist/project-bootstrap.skill | Bin 3066 -> 4131 bytes skills/project-bootstrap/SKILL.md | 129 +++++++++++++++++++++++++----- 5 files changed, 167 insertions(+), 22 deletions(-) create mode 100644 .wiki/source/wiki-realignment.md 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 057e1087e8efc4fd309bdaab2aa74b52f7c400e6..df80f68fdf43391485abb596925eaf0c89e9c437 100644 GIT binary patch delta 3466 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 delta 2414 zcmV-!36b`rAo>>^P)h>@6aWAK2mqv5oLo)l=|wq85w)xpb&>8$@npgDoBl;>3*}?%pQ~rV@k-A`cAt8RD;cJ!!luBsoFZ<7 zQYCA>r`P(U@qsv^W2LIGqpAbwt;}t`Hk;OIX5L%3^Nq?idEq8{g!ZhZSq~ogvGpOj zq0|9BkE-?oozSkVuE8pQ90*lsA_Hi|m-0FV{bi3BvCz;3u2RsZY9KNyLMrR}&Ny3F z5f{*1R+hlf*fDx+4VNm9*u87CQvt3ZOzkbG0kyfDPAOi~sr;IJk~p8TC#KUB6nfjc zsw0_+r1zI{5p*MeCO`eAS2^4$#XoJZB)6-#kAr^xb*g!iisfC3U{Fa)OuhgZ2~o(@&$7 z+D^nDWLCt)kbfNL>G_0#mj({T+?a(IPI%&4Vp@-qXvCKTiiJL5Op85dpT=WOa$I%F znHGr?4g*lOc0a&>P)Xlbm2!s;0;|#@5)>eg#$I_~rmay7;xpy)3h{v0po2gNeurb_R(L@DHc1^Fd=Og5$B)EZku6Y za8tJyop6C#M%MnR)jn3)$(6NWMY?Xo3%S@*%I&$x?P=R27Mx{y$LbMMU+!c0Tqq;ros#2=8)Fq$uZWk-t2J!5REJOLA7P*Qgw`169 zN0}dqf7coynagTqc~hfSwmC(@a|B&m*A%L;2;%O%`@j0(7fctMY6=hkUY-^;B12nj zBz0$a$gB^2O3ps-J|c~#py#9%OuI_y)c$-(nNNRz`v6i=m%H|$n~~$xjrAsrAA{)UC3Q+_xRo*cR6Pp^iK>C%G3e>AXpuS zwhB>;+qZ8o-v6FUKok|!s?^f1DP01HpeZF_w`UZ{g9ZSTL1QgPGm?kQ5AWW8_wCiY z4^b$8$>cg`xeG>CZq8J+(=cKs1?8-NYMTPyjnThMdXP@bk?iF?w0ImJzogzc~ zeHn`lgPj=3X!K$VD%psSQr}@*NuK0-kethZ{1@xMLya_5V_hK1Lg&WAxk*fP4hBSVq2NJrReG8T7-1dUMhJY$k^xMTLbzoS*B$5vHzghR&d|mLt?2$_ z&WR2KypDCJIMeLctB(1(D6kJ=-|>@|)66EQ%K(H#hN5vt{jNiDvvtaAnu(CIeeIxs zu%pD^2hgC=BluawCM?7ir8-y${inwLmjsvrciq?;t@UyEUL!#V!#hDaAO_hHRM)hP zh$ZrM)r12B46dKWSFz`-rqRlg^T*W^-y284^0T3G9@WHO#+n!p5~(Q0hyP1eO#7nd z++5t;E>g)!H3vh$$|_ep6tRx{e!y;ji0>uy{cy{^Mn*piwosJf^!)sXX_!pDUhxFmOrPpCRwuqaKtZyNICvh8m zfI%W1@P>h4CSR+3D><_$0G$c(#8fjal2RuNu^}FJpx;p`%wZNHA}Bn*#rdhRdzddy ztAltveqyhm02{VOMW~^&kHMt8UY@>MMm;-}#GG96qt3_+P`X;CSWxg9s82*9DMLWj zYt@!W;Y3cMO5)|Yye9n@TMd4HhJ=;y7#|A@>if{XU|5Ja^_>(7Eg{ANsKMC1ujjh2(8MK6g2PuvJBp6*DNw zwRIV@m#VOjNB*OO)3HkNGN!w888U5{(?>J*!|I>hjoefI$V0zjUHjH^?J%z)C~H$= zFem$5NM)4HX|K?DzL1xl`u*k6FltgSA7Nd7-Az7e?s+O?Z{3*b=w_+Q201<__N2$v zh2#ys8Hg~y6e!Pq^Pb{7K$`~QJ=T?;9&^^ z&~S6bAfy=rhbSyJrOD|uL)QS~Q)(Ot%RSvq`R=j+eypRGX{H)~pPtY7>7IdGU z;zr{vz~dlsr<<_OHOIZ=EY7TS-|&R1meVZna+Fp5<-|CtlJLTEH{rmfT#Z9jmx=(8 zJ`$D75)GzipOD14Z*iLO{43!Xw zgGgnAela<|VVKYeO^)~vP)h>@lVA@Tlj08 -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/