vitya
93a37f9aa5
Extends Karpathy LLM Wiki canon with two new artifact types alongside existing entities/concepts/packages/sources. Inspired by community discussion that highlighted explicit tracking of surfaced tensions and unanswered questions as missing aggregation points in the canonical layout — they currently get scattered into concepts/ or lost in log.md. Scope is schema-level only — no new ingest behaviour prescribed. Policy on when to escalate an inline `> **Противоречие:**` flag into a contradictions/<slug>.md page (and the analogous flow for open-questions) stays the user's call. setup-wiki [v1.0.0 → v1.1.0, MINOR — additive page types]: - Discovery (Phase 1) now requires 6 content dirs for `noop` mode - Phase 2 plan blocks list new dirs in greenfield + migrate - CLAUDE.md schema template gains two page-type entries with status enums (contradictions: open|resolved|accepted-divergence; open-questions: open|answered|obsolete) - index.md template gains two empty sections - Phase 4a .gitkeep list, Phase 4b mkdir + touch, Phase 5 verify count (four → six dirs), Phase 6 report count all updated - README.md layout tree + content-dirs sentence using-wiki [v1.0.0 → v1.1.0, MINOR — additive type values]: - Prerequisites: four → six content directories - Page frontmatter type enum: + contradiction | open-question - Per-type frontmatter extensions documented (status + affects/touches) - File naming patterns: + contradictions/<slug>.md, open-questions/<slug>.md - index.md sections-by-type list updated - README.md mirrors SKILL.md changes dist/: setup-wiki.skill + using-wiki.skill rebuilt. project-bootstrap inline reference block intentionally untouched — it's labelled "Reference (for context only — setup-wiki is the source of truth)" and drift-tolerant by design. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
104 lines
4.2 KiB
Markdown
104 lines
4.2 KiB
Markdown
# setup-wiki
|
|
|
|
One-time skill that creates or migrates a project's `.wiki/` to the
|
|
canonical Karpathy LLM Wiki layout. The runtime policy for working *inside*
|
|
that wiki lives in [`using-wiki`](../using-wiki/) — `setup-wiki` is the only
|
|
place that creates or rearranges the file structure.
|
|
|
|
Canonical layout reference:
|
|
<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>
|
|
|
|
## When it triggers
|
|
|
|
- User says: "set up wiki", "init wiki", "create wiki", "migrate wiki to canon",
|
|
"wiki layout broken", or the Russian equivalents ("настрой вики",
|
|
"инициализируй вики", "wiki сломана").
|
|
- [`using-wiki`](../using-wiki/) detects a missing or non-canonical `.wiki/`
|
|
and delegates here via its Prerequisites section.
|
|
- [`project-bootstrap`](../project-bootstrap/) Step 3 delegates here when
|
|
initializing a new project.
|
|
|
|
## Modes
|
|
|
|
`setup-wiki` chooses one of three modes after a discovery scan:
|
|
|
|
| Mode | Trigger | Action |
|
|
|---|---|---|
|
|
| **greenfield** | No `.wiki/` exists | Create the canonical layout from scratch. |
|
|
| **noop** | `.wiki/` already canon (all five canon files + six content dirs) | Report and exit — no writes. |
|
|
| **migrate** | `.wiki/` exists with non-canon files (`SUMMARY.md`, `WORKFLOW.md`, `source/`) or missing canon files | Move legacy files (e.g. `source/*.md` → `concepts/*.md` via `git mv`), create missing canon files, drop a timestamped `.backup-*/` next to it. |
|
|
|
|
Migration **does not auto-rewrite** existing concept content — it only moves
|
|
files and prepends minimal frontmatter when missing. Real edits stay your
|
|
job.
|
|
|
|
## What canon means
|
|
|
|
```
|
|
.wiki/
|
|
├── CLAUDE.md ← schema: project-specific wiki conventions
|
|
├── index.md ← catalog of pages by type
|
|
├── log.md ← append-only op log
|
|
├── overview.md ← single project overview
|
|
├── raw/
|
|
│ └── README.md ← raw/ is immutable; this file documents that
|
|
├── entities/ ← entity pages (people, services, modules)
|
|
├── concepts/ ← design decisions, recurring ideas
|
|
├── packages/ ← code packages
|
|
├── sources/ ← one summary per ingested source
|
|
├── contradictions/ ← surfaced tensions worth tracking long-term
|
|
└── open-questions/ ← unresolved questions raised during ingest/query
|
|
```
|
|
|
|
The six content directories each get a `.gitkeep` so git tracks them.
|
|
|
|
## Hard rules
|
|
|
|
- **Never auto-mutate.** Phase 1 (discovery) and Phase 2 (plan) always pause
|
|
for explicit confirmation. A trigger phrase grants permission to inspect,
|
|
not to write.
|
|
- **Never touch `raw/` content during migration.** `raw/` is immutable; only
|
|
the `.gitkeep` placeholder may be removed when `raw/README.md` replaces it.
|
|
- **No re-runs that overwrite a canon wiki.** Phase 1 detection guards
|
|
this — `noop` mode bails out cleanly.
|
|
- **No invented domain conventions.** The schema's "Domain conventions"
|
|
section stays a stub for the user to fill in.
|
|
|
|
## Procedure (high-level)
|
|
|
|
1. **Phase 0** — environment sanity (project root, platform check).
|
|
2. **Phase 1** — discovery (greenfield / noop / migrate).
|
|
3. **Phase 2** — plan + confirm. Wait for explicit "ok"/"go"/"поехали".
|
|
4. **Phase 3** — backup (migrate only) → `.wiki/.backup-YYYYMMDD-HHMMSS/`.
|
|
5. **Phase 4a/4b** — greenfield create or migrate.
|
|
6. **Phase 5** — verify (canon files present, dirs exist, no leftover
|
|
non-canon, frontmatter on migrated pages).
|
|
7. **Phase 6** — final report; if invoked from `project-bootstrap`, return
|
|
silently.
|
|
|
|
Full procedure with templates and the migration shell snippet lives in
|
|
[`SKILL.md`](SKILL.md).
|
|
|
|
## Rollback
|
|
|
|
- Greenfield: `rm -rf .wiki/`.
|
|
- Migrate: `cp -r .wiki/.backup-<ts>/* .wiki/` and `git reset HEAD .wiki/`.
|
|
|
|
## Install
|
|
|
|
From the repo root:
|
|
|
|
```bash
|
|
bash scripts/install.sh setup-wiki
|
|
```
|
|
|
|
Works on Windows under git-bash, Linux, macOS.
|
|
|
|
## See also
|
|
|
|
- [`using-wiki`](../using-wiki/) — runtime policy for working with `.wiki/`.
|
|
- [`project-bootstrap`](../project-bootstrap/) — orchestrator that delegates
|
|
here for new projects.
|
|
- Karpathy's LLM Wiki gist:
|
|
<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>
|