factory/skills/setup-wiki/SKILL.md

name, version, description

name	version	description
setup-wiki	1.1.0	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/`, `contradictions/`, `open-questions/`. 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/, contradictions/, open-questions/ → 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:   <list of canon files present>
Missing: <list>
Non-canon: <list>

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/, contradictions/, open-questions/ (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/, contradictions/, open-questions/ (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):

# Wiki Schema — <project>

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:`.
- `contradictions/` — surfaced tensions between sources or pages worth tracking long-term; each page cross-links the affected entities/concepts/sources and carries a status (`open` / `resolved` / `accepted-divergence`).
- `open-questions/` — unresolved questions raised during ingest or query that the wiki cannot answer yet; each page cross-links the pages/sources that touch the question and carries a status (`open` / `answered` / `obsolete`).
- `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. -->

.wiki/index.md (catalog):

# 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

<!-- (none yet) -->

## Concepts

<!-- (none yet) -->

## Packages

<!-- (none yet) -->

## Sources

<!-- (none yet) -->

## Contradictions

<!-- (none yet) -->

## Open Questions

<!-- (none yet) -->

.wiki/log.md (op log; backfill an init line dated today):

# Wiki Log

Append-only operation log. Format:

\`\`\`
## [YYYY-MM-DD] <op> | <one-line description>
\`\`\`

Operations: `init`, `ingest`, `query`, `lint`, `refactor`, `decision`.

Parseable: `grep "^## \[" .wiki/log.md | tail -20`.

---

## [<today>] init | wiki bootstrapped via setup-wiki@<version>

.wiki/overview.md:

---
title: <project> overview
type: overview
updated: <today>
---

# <project> — overview

<!-- Replace with a high-level description: what this project does, who it's for, the main components. -->

.wiki/raw/README.md:

# 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/, contradictions/, open-questions/ so git tracks the dirs.

Phase 4b — Migrate

If migrate mode: combine creation (for missing canon files) with file moves (for non-canon).

# 1. Create missing directories
mkdir -p .wiki/concepts .wiki/entities .wiki/packages .wiki/sources .wiki/contradictions .wiki/open-questions

# 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/, contradictions/, open-questions/
touch .wiki/entities/.gitkeep .wiki/packages/.gitkeep .wiki/sources/.gitkeep .wiki/contradictions/.gitkeep .wiki/open-questions/.gitkeep

For migrated concepts/*.md pages, do not rewrite their content — just prepend a minimal frontmatter if missing:

---
title: <derived from existing H1>
type: concept
updated: <today>
---

Build index.md with one entry per migrated concepts/<file>.md, derived from the file's H1 and any one-liner the agent can extract.

Append a line to log.md:

## [<today>] refactor | wiki migrated to canon via setup-wiki@<version>

Phase 5 — Verify

After writes, confirm:

• All canon files exist: CLAUDE.md, index.md, log.md, overview.md, raw/README.md.
• Six content directories exist (entities/, concepts/, packages/, sources/, contradictions/, open-questions/) — 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 + 6 dirs + N migrated concept pages
   Backup (if migrate): .wiki/.backup-<ts>/

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-<ts>/* .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.