Files

vitya 93a37f9aa5 feat(setup-wiki, using-wiki): add contradictions/ and open-questions/ as canonical page types

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>

2026-05-21 21:36:28 +03:00

4.2 KiB

Raw Blame History

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 — 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 detects a missing or non-canonical .wiki/ and delegates here via its Prerequisites section.
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)

Phase 0 — environment sanity (project root, platform check).
Phase 1 — discovery (greenfield / noop / migrate).
Phase 2 — plan + confirm. Wait for explicit "ok"/"go"/"поехали".
Phase 3 — backup (migrate only) → .wiki/.backup-YYYYMMDD-HHMMSS/.
Phase 4a/4b — greenfield create or migrate.
Phase 5 — verify (canon files present, dirs exist, no leftover non-canon, frontmatter on migrated pages).
Phase 6 — final report; if invoked from project-bootstrap, return silently.

Full procedure with templates and the migration shell snippet lives in 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 scripts/install.sh setup-wiki

Works on Windows under git-bash, Linux, macOS.

4.2 KiB Raw Blame History