From 4382fd36b95dae07ac822c20a725ef604b673645 Mon Sep 17 00:00:00 2001 From: vitya Date: Tue, 28 Apr 2026 11:22:43 +0300 Subject: [PATCH] refactor(wiki): migrate this repo's .wiki/ to canonical Karpathy layout MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Stop being inconsistent with our own fixed project-bootstrap template. - SUMMARY.md → index.md (catalog by type, with one-line hooks) - source/*.md → concepts/*.md (with `git mv` so history is preserved) - WORKFLOW.md removed (workflow lives in wiki-maintainer, not duplicated here) - New: .wiki/CLAUDE.md (project schema, Karpathy gist URL pinned at top) - New: log.md (append-only op log; backfilled with prior decisions) - New: overview.md (single project intro page) - New: raw/README.md (immutability note; replaces .gitkeep placeholder) - Empty .gitkeep added to entities/, packages/, sources/ - Migrated pages got `type: concept` frontmatter After this, wiki-maintainer reads .wiki/CLAUDE.md → index.md as it expects, and the layout matches what newly-bootstrapped projects will look like. Co-Authored-By: Claude Opus 4.7 (1M context) --- .tasks/STATUS.md | 11 +++++ .wiki/CLAUDE.md | 40 +++++++++++++++++++ .wiki/SUMMARY.md | 11 ----- .wiki/WORKFLOW.md | 15 ------- .../active-platform-decision.md | 6 +++ .wiki/{source => concepts}/build-notes.md | 6 +++ .wiki/{source => concepts}/repo-layout.md | 6 +++ .../{source => concepts}/wiki-realignment.md | 6 +++ .wiki/{raw => entities}/.gitkeep | 0 .wiki/index.md | 26 ++++++++++++ .wiki/log.md | 20 ++++++++++ .wiki/overview.md | 29 ++++++++++++++ .wiki/{source => packages}/.gitkeep | 0 .wiki/raw/README.md | 13 ++++++ .wiki/sources/.gitkeep | 0 15 files changed, 163 insertions(+), 26 deletions(-) create mode 100644 .wiki/CLAUDE.md delete mode 100644 .wiki/SUMMARY.md delete mode 100644 .wiki/WORKFLOW.md rename .wiki/{source => concepts}/active-platform-decision.md (96%) rename .wiki/{source => concepts}/build-notes.md (96%) rename .wiki/{source => concepts}/repo-layout.md (96%) rename .wiki/{source => concepts}/wiki-realignment.md (95%) rename .wiki/{raw => entities}/.gitkeep (100%) create mode 100644 .wiki/index.md create mode 100644 .wiki/log.md create mode 100644 .wiki/overview.md rename .wiki/{source => packages}/.gitkeep (100%) create mode 100644 .wiki/raw/README.md create mode 100644 .wiki/sources/.gitkeep diff --git a/.tasks/STATUS.md b/.tasks/STATUS.md index 1e5590d..fe28a1c 100644 --- a/.tasks/STATUS.md +++ b/.tasks/STATUS.md @@ -3,6 +3,17 @@ _Updated: 2026-04-28_ ## Done +### Migrate this repo's `.wiki/` to canonical Karpathy layout +- [x] `git mv` `.wiki/source/*.md` → `.wiki/concepts/` (rename detection preserves history) +- [x] Add `type: concept` frontmatter to each migrated page +- [x] Create `.wiki/CLAUDE.md` (schema, with Karpathy gist URL pinned at top) +- [x] Create `.wiki/index.md` (replaces `SUMMARY.md`) +- [x] Create `.wiki/log.md` with backfilled entries for prior decisions +- [x] Create `.wiki/overview.md` (project intro page) +- [x] Create `.wiki/raw/README.md` (replaces `.gitkeep` placeholder) +- [x] Empty `.gitkeep` in `.wiki/entities/`, `packages/`, `sources/` +- [x] Delete `.wiki/SUMMARY.md`, `.wiki/source/`, `.wiki/raw/.gitkeep` + ### 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` diff --git a/.wiki/CLAUDE.md b/.wiki/CLAUDE.md new file mode 100644 index 0000000..5e0004f --- /dev/null +++ b/.wiki/CLAUDE.md @@ -0,0 +1,40 @@ +# Wiki Schema — claude-skills + +Project-specific wiki conventions. Read this before any wiki operation. + +This wiki follows Karpathy's LLM Wiki pattern: +**https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f** + +The `wiki-maintainer` skill enforces the workflow and file formats. This file overrides the skill where they conflict. + +## Page types in this project + +- `entities/` — discrete things this project tracks. Reserved for future use (individual skills if they accumulate non-obvious context, tools we adopt). +- `concepts/` — design decisions, technical gotchas, refactor notes. Most pages live here. +- `packages/` — currently empty. Would be used if we extract a package (e.g. a CLI) from this repo. +- `sources/` — one summary per ingested external doc; carries `ingested:` and `raw_path:` frontmatter. +- `overview.md` — single project-wide overview. Read this first if new to the repo. + +## Naming + +- `kebab-case.md`, **Latin only**. Transliterate Cyrillic in filenames; keep the original title in the H1 + frontmatter. + +## Domain conventions + +- Skill-related design notes go in `concepts/-*.md` (e.g. `active-platform-decision.md`). +- Build / install pipeline notes live in `concepts/build-*.md`. +- Refactor / re-alignment commits get a `concepts/-realignment.md` page. + +## Frontmatter + +Minimum: + +```yaml +--- +title: Human-readable title +type: concept | entity | package | source | overview +updated: YYYY-MM-DD +--- +``` + +`source/` pages also carry `ingested:` and `raw_path:`. diff --git a/.wiki/SUMMARY.md b/.wiki/SUMMARY.md deleted file mode 100644 index 7d60c64..0000000 --- a/.wiki/SUMMARY.md +++ /dev/null @@ -1,11 +0,0 @@ -# Wiki Summary - -List of all pages in source/ with one-line descriptions. -The agent updates this file whenever source/ changes. - -## Pages - -- [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/WORKFLOW.md b/.wiki/WORKFLOW.md deleted file mode 100644 index dd9d8e8..0000000 --- a/.wiki/WORKFLOW.md +++ /dev/null @@ -1,15 +0,0 @@ -# Wiki Workflow - -This wiki follows Karpathy's method: knowledge accumulates rather than being re-derived. - -## Rules for the agent - -- **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/ - -## Trigger - -Skill is activated by the phrase: **use project wiki** diff --git a/.wiki/source/active-platform-decision.md b/.wiki/concepts/active-platform-decision.md similarity index 96% rename from .wiki/source/active-platform-decision.md rename to .wiki/concepts/active-platform-decision.md index af3a74d..8140afe 100644 --- a/.wiki/source/active-platform-decision.md +++ b/.wiki/concepts/active-platform-decision.md @@ -1,3 +1,9 @@ +--- +title: "Decision: active-platform skill" +type: concept +updated: 2026-04-28 +--- + # Decision: `active-platform` skill _2026-04-28._ diff --git a/.wiki/source/build-notes.md b/.wiki/concepts/build-notes.md similarity index 96% rename from .wiki/source/build-notes.md rename to .wiki/concepts/build-notes.md index 653054b..ea4e32f 100644 --- a/.wiki/source/build-notes.md +++ b/.wiki/concepts/build-notes.md @@ -1,3 +1,9 @@ +--- +title: Build Notes +type: concept +updated: 2026-04-28 +--- + # Build Notes Practical gotchas around building `.skill` archives. diff --git a/.wiki/source/repo-layout.md b/.wiki/concepts/repo-layout.md similarity index 96% rename from .wiki/source/repo-layout.md rename to .wiki/concepts/repo-layout.md index 996fb73..3aaa4f7 100644 --- a/.wiki/source/repo-layout.md +++ b/.wiki/concepts/repo-layout.md @@ -1,3 +1,9 @@ +--- +title: Repo Layout & Skill Workflow +type: concept +updated: 2026-04-28 +--- + # Repo Layout & Skill Workflow _Decision: 2026-04-28. Approved by Vitya in chat._ diff --git a/.wiki/source/wiki-realignment.md b/.wiki/concepts/wiki-realignment.md similarity index 95% rename from .wiki/source/wiki-realignment.md rename to .wiki/concepts/wiki-realignment.md index 016f040..da2533b 100644 --- a/.wiki/source/wiki-realignment.md +++ b/.wiki/concepts/wiki-realignment.md @@ -1,3 +1,9 @@ +--- +title: Wiki realignment to Karpathy canon +type: concept +updated: 2026-04-28 +--- + # Wiki realignment to Karpathy canon _2026-04-28._ diff --git a/.wiki/raw/.gitkeep b/.wiki/entities/.gitkeep similarity index 100% rename from .wiki/raw/.gitkeep rename to .wiki/entities/.gitkeep diff --git a/.wiki/index.md b/.wiki/index.md new file mode 100644 index 0000000..2fc944b --- /dev/null +++ b/.wiki/index.md @@ -0,0 +1,26 @@ +# Wiki Index + +Catalog of all wiki pages. One line per page, organized by type. Updated on every ingest / new page. + +## Overview + +- [overview.md](overview.md) — what claude-skills is, layout, how to navigate + +## Entities + + + +## Concepts + +- [active-platform-decision.md](concepts/active-platform-decision.md) — why `active-platform` is a skill (not a memory entry); why default = Windows; how it's wired into `project-bootstrap` +- [build-notes.md](concepts/build-notes.md) — why `build.ps1` exists alongside `build.sh`; PS 5.1 backslash-in-zip gotcha; how to extract a `.skill` +- [repo-layout.md](concepts/repo-layout.md) — flat `skills/`, committed `dist/`, bash + PowerShell scripts; install model +- [wiki-realignment.md](concepts/wiki-realignment.md) — fixing `project-bootstrap` to create the Karpathy-canonical wiki layout + +## Packages + + + +## Sources + + diff --git a/.wiki/log.md b/.wiki/log.md new file mode 100644 index 0000000..ee68104 --- /dev/null +++ b/.wiki/log.md @@ -0,0 +1,20 @@ +# 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`. + +--- + +## [2026-04-28] init | bootstrap empty wiki via project-bootstrap (old layout) +## [2026-04-28] decision | repo-layout — flat `skills/`, committed `dist/`, bash + PS scripts +## [2026-04-28] decision | build-notes — PS 5.1 Compress-Archive backslash bug; build.ps1 via .NET ZipArchive +## [2026-04-28] decision | active-platform — skill chosen over global CLAUDE.md / project memory; default Windows; wired into project-bootstrap +## [2026-04-28] refactor | wiki-realignment — fixed project-bootstrap Step 3 to create Karpathy-canonical layout +## [2026-04-28] refactor | this repo's `.wiki/` migrated to canonical layout (SUMMARY.md→index.md, source/→concepts/, added log.md/overview.md/CLAUDE.md schema, raw/README.md) diff --git a/.wiki/overview.md b/.wiki/overview.md new file mode 100644 index 0000000..244e82e --- /dev/null +++ b/.wiki/overview.md @@ -0,0 +1,29 @@ +--- +title: claude-skills overview +type: overview +updated: 2026-04-28 +--- + +# claude-skills — overview + +Joint workshop where Vitya and Claude develop, test, and store Claude skills. Both editable sources (`skills//`) and built archives (`dist/.skill`) live here, so a fresh machine can clone the repo and install every personal skill in one command. + +## Components + +- **`skills/`** — editable skill sources, one folder per skill (each with `SKILL.md` + optional `assets/`). +- **`dist/`** — built `.skill` archives, committed so installs don't need a build toolchain on the target. +- **`scripts/`** — `build.sh` / `build.ps1` (zip sources → archive), `install.sh` (copy sources → `~/.claude/skills/`). +- **`.wiki/`** — Karpathy LLM Wiki for design decisions and gotchas. See [CLAUDE.md](CLAUDE.md) for schema. +- **`.tasks/`** — task board (`STATUS.md`). +- **`CLAUDE.md`** — repo-level agent instructions (skill triggers). + +## Where to look + +- New here? → [concepts/repo-layout.md](concepts/repo-layout.md), then `README.md`. +- Working on a skill? → edit `skills//`, then `bash scripts/install.sh ` (or `pwsh scripts/build.ps1 ` to refresh the archive). +- Tracking work? → [.tasks/STATUS.md](../.tasks/STATUS.md). +- Made a non-trivial decision? → add a `concepts/.md` page, link from [index.md](index.md), append a line to [log.md](log.md). + +## Cross-references + +This page intentionally stays short. The substantive material lives in `concepts/` (decisions, gotchas) and the [index](index.md) catalog. diff --git a/.wiki/source/.gitkeep b/.wiki/packages/.gitkeep similarity index 100% rename from .wiki/source/.gitkeep rename to .wiki/packages/.gitkeep diff --git a/.wiki/raw/README.md b/.wiki/raw/README.md new file mode 100644 index 0000000..621d262 --- /dev/null +++ b/.wiki/raw/README.md @@ -0,0 +1,13 @@ +# 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 outside the repo, register them here: + +``` +- short-name → /absolute/path/to/source +``` + +Currently: no raw sources yet. diff --git a/.wiki/sources/.gitkeep b/.wiki/sources/.gitkeep new file mode 100644 index 0000000..e69de29