diff --git a/.tasks/STATUS.md b/.tasks/STATUS.md index f883d0d..49751d2 100644 --- a/.tasks/STATUS.md +++ b/.tasks/STATUS.md @@ -15,10 +15,12 @@ _Updated: 2026-04-28_ - [x] Build + install affected skills (loop in build.sh handles 6-arg invocation cleanly) #### (b) Split wiki -- [ ] Rename `skills/wiki-maintainer/` → `skills/using-wiki/`; update `name:` in frontmatter -- [ ] New `skills/setup-wiki/` (canonical layout creation, gated, derived from current "Bootstrap empty wiki" section + Karpathy gist) -- [ ] Prerequisites section in `using-wiki` → invokes `setup-wiki` if `.wiki/` is missing/non-canon -- [ ] `project-bootstrap` Step 3 delegates to `setup-wiki` +- [x] `git mv skills/wiki-maintainer/ skills/using-wiki/` (history preserved as rename) +- [x] Updated `name:` to `using-wiki` and description to include `use project wiki` trigger; H1 + headline rewritten +- [x] New `skills/setup-wiki/SKILL.md` — 6 phases (sanity → discovery → plan+confirm → backup → 4a greenfield / 4b migrate → verify → report), with full templates for each canon file +- [x] `using-wiki` Prerequisites section delegates to `setup-wiki` when layout missing/non-canon +- [x] `project-bootstrap` Step 3 now delegates to `setup-wiki`; inline templates kept as reference only +- [x] Stale `dist/wiki-maintainer.skill` removed #### (c) Split tasks - [ ] Rename `skills/task-status-wiki/` → `skills/using-tasks/`; update `name:` diff --git a/.wiki/log.md b/.wiki/log.md index e9654f9..c9eda2d 100644 --- a/.wiki/log.md +++ b/.wiki/log.md @@ -23,3 +23,4 @@ Parseable: `grep "^## \[" .wiki/log.md | tail -20`. ## [2026-04-28] verify | setup-context7 — Vitya ran using-context7 in a session that needed setup; Prerequisites pointer triggered setup-context7; full flow worked end-to-end. Pattern (policy + setup split) validated. ## [2026-04-28] decision | skill-vs-plugin — documented when a bare skill suffices vs when a plugin is required (slash commands, hooks, sub-agents, MCP via marketplace) ## [2026-04-28] decision | skill-versioning — added `version: 1.0.0` to 6 infra skills' frontmatter; project-bootstrap now writes .wiki/concepts/bootstrap-manifest.md per project +## [2026-04-28] refactor | wiki split — `wiki-maintainer` renamed to `using-wiki` (policy); new `setup-wiki` skill owns greenfield creation and canon migration; `project-bootstrap` Step 3 delegates diff --git a/dist/project-bootstrap.skill b/dist/project-bootstrap.skill index a8a4bb5..705b484 100644 Binary files a/dist/project-bootstrap.skill and b/dist/project-bootstrap.skill differ diff --git a/dist/setup-wiki.skill b/dist/setup-wiki.skill new file mode 100644 index 0000000..7a479b0 Binary files /dev/null and b/dist/setup-wiki.skill differ diff --git a/dist/using-wiki.skill b/dist/using-wiki.skill new file mode 100644 index 0000000..6678d19 Binary files /dev/null and b/dist/using-wiki.skill differ diff --git a/dist/wiki-maintainer.skill b/dist/wiki-maintainer.skill deleted file mode 100644 index 4c21b21..0000000 Binary files a/dist/wiki-maintainer.skill and /dev/null differ diff --git a/skills/project-bootstrap/SKILL.md b/skills/project-bootstrap/SKILL.md index 00dba50..9c9263c 100644 --- a/skills/project-bootstrap/SKILL.md +++ b/skills/project-bootstrap/SKILL.md @@ -76,12 +76,11 @@ If it exists — leave it untouched. ## Step 3 — .wiki/ -If `.wiki/` already exists — skip it, notify the user. +**Delegate to the `setup-wiki` skill.** It handles greenfield creation, canon migration, and the no-op case (already canon) uniformly, with its own confirmation gate. Don't recreate the layout inline here — that's how drift happens. -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. +If `setup-wiki` is not installed on this machine, **stop** and tell the user: project-bootstrap requires `setup-wiki` (and `setup-tasks`) installed. Don't fall back to ad-hoc creation. + +**Reference (for context only — `setup-wiki` is the source of truth):** the canonical layout per Karpathy (gist: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) and `using-wiki`: ``` .wiki/ diff --git a/skills/setup-wiki/SKILL.md b/skills/setup-wiki/SKILL.md new file mode 100644 index 0000000..bd343a2 --- /dev/null +++ b/skills/setup-wiki/SKILL.md @@ -0,0 +1,284 @@ +--- +name: setup-wiki +version: 1.0.0 +description: Creates or migrates a project's `.wiki/` to the canonical Karpathy LLM Wiki layout — `CLAUDE.md` schema, `index.md`, `log.md`, `overview.md`, `raw/README.md`, plus empty `entities/`, `concepts/`, `packages/`, `sources/`. Use when the user says "set up wiki", "init wiki", "настрой вики", "инициализируй вики", "create wiki", "migrate wiki to canon", "wiki сломана", "wiki layout broken", or whenever `using-wiki` detects a missing or non-canonical `.wiki/`. Two modes — greenfield (no wiki) and migrate (existing non-canonical layout). Confirmation gate before writing. Cross-platform. +--- + +# setup-wiki + +> Creates or migrates a `.wiki/` to canon. The canonical layout is documented at https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f and enforced by `using-wiki`. This skill is the *only* place that creates or rearranges those files. + +## When to use + +- User explicitly asks: set up / init / migrate / create wiki. +- `using-wiki` runs and detects a missing or non-canonical `.wiki/` — its Prerequisites delegate here. +- `project-bootstrap` Step 3 delegates here when initializing a new project. + +## Out of scope + +- Editing existing wiki *content* (that's `using-wiki`'s job). +- Anything outside `.wiki/`. + +## Hard rule: don't auto-mutate + +The procedure mutates the project's `.wiki/`. **Pause for explicit confirmation between Phase 1 (discovery) and Phase 2 (plan).** A trigger phrase is permission to inspect, not to write. + +## Procedure + +### Phase 0 — Environment sanity + +- Confirm current working directory is a project root (has `.git/` ideally, or at minimum is a place the user wants a wiki). +- Detect platform; pick file paths accordingly. Wiki paths are POSIX-style (`.wiki/...`) on every OS. + +### Phase 1 — Discovery + +Inspect `.wiki/`: + +- **No `.wiki/`** → mode = `greenfield`. +- **`.wiki/` exists AND has all of:** `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/README.md`, plus directories `entities/`, `concepts/`, `packages/`, `sources/` → mode = `noop` (already canon; report and exit). +- **`.wiki/` exists but missing some canon files OR has non-canon files** (`SUMMARY.md`, `WORKFLOW.md`, `source/`) → mode = `migrate`. + +Report findings to the user as a short summary: + +``` +Mode: greenfield | noop | migrate +Has: +Missing: +Non-canon: +``` + +### Phase 2 — Plan + confirm + +Show the plan in one block: + +**Greenfield:** +``` +Will create .wiki/ with canonical layout: + CLAUDE.md (schema), index.md, log.md, overview.md + raw/README.md + entities/, concepts/, packages/, sources/ (with .gitkeep) +``` + +**Migrate:** +``` +Will rename: + source/*.md → concepts/*.md (via git mv when in a git repo, plain mv otherwise) +Will create: + CLAUDE.md, index.md, log.md, overview.md, raw/README.md + entities/, packages/, sources/ (with .gitkeep) +Will delete: + SUMMARY.md, WORKFLOW.md, raw/.gitkeep, source/ (after moves) +Will not touch existing files in raw/ — they're immutable sources. +``` + +Wait for explicit confirmation ("ok", "go", "поехали"). Anything else → stop. + +### Phase 3 — Backup (migrate only) + +In migrate mode only, copy each file we will rename/delete to `.wiki/.backup-YYYYMMDD-HHMMSS/`. (Greenfield has nothing to back up.) + +If git is available, the rename history is also recoverable via `git reflog`, but a filesystem backup is belt-and-suspenders. + +### Phase 4a — Greenfield create + +Create the canonical layout. Each file gets the content shown below; the project name comes from the parent directory's basename. + +**`.wiki/CLAUDE.md`** (schema): + +```markdown +# Wiki Schema — + +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 `using-wiki` skill enforces the workflow and file formats. This file overrides the skill where they conflict. + +## Page types + +- `entities/` — discrete things this 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; 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 + + +``` + +**`.wiki/index.md`** (catalog): + +```markdown +# 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) — project overview + +## Entities + + + +## Concepts + + + +## Packages + + + +## Sources + + +``` + +**`.wiki/log.md`** (op log; backfill an `init` line dated today): + +```markdown +# Wiki Log + +Append-only operation log. Format: + +\`\`\` +## [YYYY-MM-DD] | +\`\`\` + +Operations: `init`, `ingest`, `query`, `lint`, `refactor`, `decision`. + +Parseable: `grep "^## \[" .wiki/log.md | tail -20`. + +--- + +## [] init | wiki bootstrapped via setup-wiki@ +``` + +**`.wiki/overview.md`**: + +```markdown +--- +title: overview +type: overview +updated: +--- + +# — 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 outside the repo, register them here: + +\`\`\` +- short-name → /absolute/path/to/source +\`\`\` +``` + +**Empty `.gitkeep`** in each of `entities/`, `concepts/`, `packages/`, `sources/` so git tracks the dirs. + +### Phase 4b — Migrate + +If migrate mode: combine creation (for missing canon files) with file moves (for non-canon). + +```bash +# 1. Create missing directories +mkdir -p .wiki/concepts .wiki/entities .wiki/packages .wiki/sources + +# 2. Move source/* → concepts/* (use git mv if in a git repo) +if git rev-parse --git-dir >/dev/null 2>&1; then + for f in .wiki/source/*.md; do + [ -e "$f" ] && git mv "$f" ".wiki/concepts/$(basename "$f")" + done + git rm -f .wiki/SUMMARY.md .wiki/WORKFLOW.md .wiki/source/.gitkeep .wiki/raw/.gitkeep 2>/dev/null +else + mv .wiki/source/*.md .wiki/concepts/ 2>/dev/null + rm -f .wiki/SUMMARY.md .wiki/WORKFLOW.md .wiki/source/.gitkeep .wiki/raw/.gitkeep +fi +rmdir .wiki/source 2>/dev/null + +# 3. Create missing canon files (CLAUDE.md, index.md, log.md, overview.md, raw/README.md) +# using the templates from Phase 4a, but skip files that already exist. + +# 4. Add .gitkeep to entities/, packages/, sources/ +touch .wiki/entities/.gitkeep .wiki/packages/.gitkeep .wiki/sources/.gitkeep +``` + +For migrated `concepts/*.md` pages, **do not rewrite their content** — just prepend a minimal frontmatter if missing: + +```yaml +--- +title: +type: concept +updated: +--- +``` + +Build `index.md` with one entry per migrated `concepts/.md`, derived from the file's H1 and any one-liner the agent can extract. + +Append a line to `log.md`: + +``` +## [] refactor | wiki migrated to canon via setup-wiki@ +``` + +### Phase 5 — Verify + +After writes, confirm: + +- All canon files exist: `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/README.md`. +- Four content directories exist (with at least `.gitkeep` or content). +- No leftover non-canon files (`SUMMARY.md`, `WORKFLOW.md`, `source/`). +- For migrate mode: every migrated page has frontmatter with `type: concept`. + +If anything's off — restore from `.wiki/.backup-*` and report. + +### Phase 6 — Report + +Print final state: + +``` +✅ Wiki ready at .wiki/. + Mode: greenfield | migrate + Files: 5 canon + 4 dirs + N migrated concept pages + Backup (if migrate): .wiki/.backup-/ + +Next steps for the user: + • Edit .wiki/overview.md to describe the project + • Edit .wiki/CLAUDE.md "Domain conventions" with project-specific rules + • Read using-wiki SKILL.md if unfamiliar with the workflow +``` + +If invoked from `project-bootstrap`, return control silently — bootstrap continues with its remaining steps. + +## Rollback + +1. `rm -rf .wiki/` (greenfield rollback) OR `cp -r .wiki/.backup-/* .wiki/` (migrate rollback). +2. If a git repo, `git reset HEAD .wiki/` to unstage moves. +3. Tell user what failed. + +## Common mistakes + +- **Touching `raw/` content during migration.** `raw/` is immutable — only the `.gitkeep` placeholder may be removed (and that only because `raw/README.md` replaces it). +- **Skipping confirmation on greenfield.** Yes, even greenfield needs the gate — the user might be running this skill in the wrong directory. +- **Re-running on already-canon wiki and rewriting files.** Phase 1 detection guards this; bail out at `noop` mode. +- **Inventing project-specific Domain conventions in `CLAUDE.md`.** The schema's "Domain conventions" section is intentionally a stub — let the user fill it as they accumulate domain knowledge. + +## Cross-platform notes + +The procedure is platform-agnostic. `mkdir -p`, `mv`, `git mv`, `cp -r`, `rm -rf`, `touch` work in git-bash on Windows the same as on Linux/macOS. Wiki paths use forward slashes throughout. diff --git a/skills/wiki-maintainer/SKILL.md b/skills/using-wiki/SKILL.md similarity index 71% rename from skills/wiki-maintainer/SKILL.md rename to skills/using-wiki/SKILL.md index cc1f550..cd986db 100644 --- a/skills/wiki-maintainer/SKILL.md +++ b/skills/using-wiki/SKILL.md @@ -1,12 +1,18 @@ --- -name: wiki-maintainer +name: using-wiki version: 1.0.0 -description: Use when a repo has a `.wiki/` directory following Karpathy's LLM Wiki pattern and the user asks to ingest a document, answer from the wiki, lint/health-check it, or says "заингесть", "обнови вики", "проверь вики", "запроси вики", "query the wiki". Also use when modifying any file under `.wiki/` — the workflow and formats below are mandatory, and project-specific conventions live in `.wiki/CLAUDE.md`. +description: Policy skill for working with an existing `.wiki/` (Karpathy LLM Wiki pattern). Use when the user asks to ingest a document, answer from the wiki, lint/health-check it, or says "use project wiki", "обнови вики", "проверь вики", "запроси вики", "заингесть", "query the wiki". Also use when modifying any file under `.wiki/` — the workflow and formats below are mandatory, and project-specific conventions live in `.wiki/CLAUDE.md`. If `.wiki/` is missing or non-canonical, delegate to `setup-wiki` first (it has its own confirmation gate). Renamed from `wiki-maintainer` at v1.0.0. --- -# wiki-maintainer +# using-wiki -> Maintain an LLM Wiki (Karpathy pattern: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). Knowledge is **compiled once and kept current** across three layers, via three named operations, with strict file formats that make the wiki parseable and grep-friendly. +> Policy for maintaining an LLM Wiki (Karpathy pattern: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). Knowledge is **compiled once and kept current** across three layers, via three named operations, with strict file formats that make the wiki parseable and grep-friendly. This skill governs *usage* of an existing wiki — initial creation and migration to canon are owned by `setup-wiki`. + +## Prerequisites + +This skill assumes the project has a canonical `.wiki/` layout: `CLAUDE.md` (schema), `index.md` (catalog), `log.md` (op log), `overview.md`, `raw/README.md`, and the four content directories `entities/`, `concepts/`, `packages/`, `sources/`. + +If `.wiki/` is **missing**, or the layout is **non-canonical** (e.g. `SUMMARY.md` instead of `index.md`, or `source/` instead of `concepts/`/`sources/`) — invoke the `setup-wiki` skill first. It detects the situation (greenfield vs migrate) and creates or migrates the structure with its own confirmation gate. Only after `setup-wiki` finishes should this skill proceed with the operations below. ## Three layers (do not blur) @@ -20,7 +26,7 @@ description: Use when a repo has a `.wiki/` directory following Karpathy's LLM W 2. Read `.wiki/index.md` to locate relevant pages. 3. Only then act. -If `.wiki/CLAUDE.md` is missing, treat it as a greenfield wiki and offer to bootstrap one (schema + empty index/log + `raw/README.md`). +If `.wiki/CLAUDE.md` is missing, the layout is incomplete — invoke `setup-wiki` rather than improvising. ## Three operations @@ -108,7 +114,7 @@ Catalog, not narrative. One line per page: `- [Title](path) — hook.` Sections | Ingest one doc | `sources/.md` (new) + 3–15 entity/concept/package pages + `index.md` + `log.md` | | Query | (read only) + optionally new wiki page + `log.md` | | Lint | (read only) + `log.md` | -| Bootstrap empty wiki | `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/README.md` + empty `entities/ concepts/ packages/ sources/` | +| Bootstrap / migrate to canon | (delegated to `setup-wiki`) | ## Common mistakes @@ -119,7 +125,7 @@ Catalog, not narrative. One line per page: `- [Title](path) — hook.` Sections - **Non-ASCII file names.** Breaks greppability and cross-platform. Transliterate. - **Forgetting `index.md`.** Pages not listed there are effectively invisible for future queries. - **Skipping contradictions in lint.** The wiki's value grows from surfaced tensions, not from false consensus. -- **Bootstrapping a new wiki without asking for domain.** Directory layout depends on whether this is a code-project wiki, a research wiki, or a reading-companion wiki. Ask briefly before creating. +- **Improvising layout when canon files are missing.** If the wiki is missing or partial, hand off to `setup-wiki` instead of patching ad hoc. ## When NOT to use this skill