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>
This commit is contained in:
BIN
dist/setup-wiki.skill
vendored
BIN
dist/setup-wiki.skill
vendored
Binary file not shown.
BIN
dist/using-wiki.skill
vendored
BIN
dist/using-wiki.skill
vendored
Binary file not shown.
@@ -25,7 +25,7 @@ Canonical layout reference:
|
||||
| Mode | Trigger | Action |
|
||||
|---|---|---|
|
||||
| **greenfield** | No `.wiki/` exists | Create the canonical layout from scratch. |
|
||||
| **noop** | `.wiki/` already canon (all five canon files + four content dirs) | Report and exit — no writes. |
|
||||
| **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
|
||||
@@ -45,10 +45,12 @@ job.
|
||||
├── entities/ ← entity pages (people, services, modules)
|
||||
├── concepts/ ← design decisions, recurring ideas
|
||||
├── packages/ ← code packages
|
||||
└── sources/ ← one summary per ingested source
|
||||
├── sources/ ← one summary per ingested source
|
||||
├── contradictions/ ← surfaced tensions worth tracking long-term
|
||||
└── open-questions/ ← unresolved questions raised during ingest/query
|
||||
```
|
||||
|
||||
The four content directories each get a `.gitkeep` so git tracks them.
|
||||
The six content directories each get a `.gitkeep` so git tracks them.
|
||||
|
||||
## Hard rules
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
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.
|
||||
version: 1.1.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/`, `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
|
||||
@@ -35,7 +35,7 @@ The procedure mutates the project's `.wiki/`. **Pause for explicit confirmation
|
||||
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 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:
|
||||
@@ -56,7 +56,7 @@ Show the plan in one block:
|
||||
Will create .wiki/ with canonical layout:
|
||||
CLAUDE.md (schema), index.md, log.md, overview.md
|
||||
raw/README.md
|
||||
entities/, concepts/, packages/, sources/ (with .gitkeep)
|
||||
entities/, concepts/, packages/, sources/, contradictions/, open-questions/ (with .gitkeep)
|
||||
```
|
||||
|
||||
**Migrate:**
|
||||
@@ -65,7 +65,7 @@ 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)
|
||||
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.
|
||||
@@ -101,6 +101,8 @@ The `using-wiki` skill enforces the workflow and file formats. This file overrid
|
||||
- `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
|
||||
@@ -137,6 +139,14 @@ Catalog of all wiki pages. One line per page, organized by type. Updated on ever
|
||||
|
||||
## Sources
|
||||
|
||||
<!-- (none yet) -->
|
||||
|
||||
## Contradictions
|
||||
|
||||
<!-- (none yet) -->
|
||||
|
||||
## Open Questions
|
||||
|
||||
<!-- (none yet) -->
|
||||
```
|
||||
|
||||
@@ -190,7 +200,7 @@ For large or path-sensitive sources outside the repo, register them here:
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
**Empty `.gitkeep`** in each of `entities/`, `concepts/`, `packages/`, `sources/` so git tracks the dirs.
|
||||
**Empty `.gitkeep`** in each of `entities/`, `concepts/`, `packages/`, `sources/`, `contradictions/`, `open-questions/` so git tracks the dirs.
|
||||
|
||||
### Phase 4b — Migrate
|
||||
|
||||
@@ -198,7 +208,7 @@ If migrate mode: combine creation (for missing canon files) with file moves (for
|
||||
|
||||
```bash
|
||||
# 1. Create missing directories
|
||||
mkdir -p .wiki/concepts .wiki/entities .wiki/packages .wiki/sources
|
||||
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
|
||||
@@ -215,8 +225,8 @@ 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
|
||||
# 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:
|
||||
@@ -242,7 +252,7 @@ Append a line to `log.md`:
|
||||
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).
|
||||
- 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`.
|
||||
|
||||
@@ -255,7 +265,7 @@ Print final state:
|
||||
```
|
||||
✅ Wiki ready at .wiki/.
|
||||
Mode: greenfield | migrate
|
||||
Files: 5 canon + 4 dirs + N migrated concept pages
|
||||
Files: 5 canon + 6 dirs + N migrated concept pages
|
||||
Backup (if migrate): .wiki/.backup-<ts>/
|
||||
|
||||
Next steps for the user:
|
||||
|
||||
@@ -86,7 +86,7 @@ line to `log.md` with the findings.
|
||||
```yaml
|
||||
---
|
||||
title: Человекочитаемое имя
|
||||
type: entity | concept | package | source | overview
|
||||
type: entity | concept | package | source | contradiction | open-question | overview
|
||||
tags: [short, tokens]
|
||||
sources: [../sources/foo.md, ../sources/bar.md]
|
||||
updated: 2026-04-21
|
||||
@@ -94,13 +94,16 @@ updated: 2026-04-21
|
||||
```
|
||||
|
||||
Source pages also carry `ingested: YYYY-MM-DD` and `raw_path: ../raw/...`.
|
||||
Contradiction pages also carry `status: open | resolved | accepted-divergence` and `affects: [../entities/x.md, ../concepts/y.md]`.
|
||||
Open-question pages also carry `status: open | answered | obsolete` and `touches: [../entities/x.md, ../sources/z.md]`.
|
||||
|
||||
### File naming
|
||||
|
||||
- `kebab-case.md`, **Latin only**. Transliterate Cyrillic / non-Latin in
|
||||
filenames; keep the original title in H1 + frontmatter.
|
||||
- `entities/<name>.md`, `concepts/<name>.md`, `packages/<name>.md`
|
||||
(no `@org/` prefix), `sources/<slug>.md`.
|
||||
(no `@org/` prefix), `sources/<slug>.md`, `contradictions/<slug>.md`,
|
||||
`open-questions/<slug>.md`.
|
||||
|
||||
### `log.md` — append-only, grep-parseable
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: using-wiki
|
||||
version: 1.0.0
|
||||
version: 1.1.0
|
||||
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.
|
||||
---
|
||||
|
||||
@@ -10,9 +10,9 @@ description: Policy skill for working with an existing `.wiki/` (Karpathy LLM Wi
|
||||
|
||||
## 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/`.
|
||||
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 six content directories `entities/`, `concepts/`, `packages/`, `sources/`, `contradictions/`, `open-questions/`.
|
||||
|
||||
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.
|
||||
If `.wiki/` is **missing**, or the layout is **non-canonical** (e.g. `SUMMARY.md` instead of `index.md`, or `source/` instead of `concepts/`/`sources/`, or `contradictions/`/`open-questions/` directories are absent) — 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)
|
||||
|
||||
@@ -70,7 +70,7 @@ Append one line to `log.md` summarizing the findings.
|
||||
```yaml
|
||||
---
|
||||
title: Человекочитаемое имя
|
||||
type: entity | concept | package | source | overview
|
||||
type: entity | concept | package | source | contradiction | open-question | overview
|
||||
tags: [short, tokens]
|
||||
sources: [../sources/foo.md, ../sources/bar.md]
|
||||
updated: 2026-04-21
|
||||
@@ -79,10 +79,14 @@ updated: 2026-04-21
|
||||
|
||||
Source pages also carry `ingested: YYYY-MM-DD` and `raw_path: ../raw/...`.
|
||||
|
||||
Contradiction pages also carry `status: open | resolved | accepted-divergence` and `affects: [../entities/x.md, ../concepts/y.md]`.
|
||||
|
||||
Open-question pages also carry `status: open | answered | obsolete` and `touches: [../entities/x.md, ../sources/z.md]`.
|
||||
|
||||
### File naming
|
||||
|
||||
- `kebab-case.md`, **Latin only**. Transliterate Cyrillic / other scripts in filenames (`план переписывания` → `ozon-client-rewrite.md`). Keep the original title in the H1 and frontmatter.
|
||||
- `entities/<name>.md`, `concepts/<name>.md`, `packages/<name>.md` (no `@org/` prefix), `sources/<slug>.md`.
|
||||
- `entities/<name>.md`, `concepts/<name>.md`, `packages/<name>.md` (no `@org/` prefix), `sources/<slug>.md`, `contradictions/<slug>.md`, `open-questions/<slug>.md`.
|
||||
|
||||
### `log.md` — append-only, grep-parseable
|
||||
|
||||
@@ -98,7 +102,7 @@ Parseable with: `grep "^## \[" .wiki/log.md | tail -20`.
|
||||
|
||||
### `index.md`
|
||||
|
||||
Catalog, not narrative. One line per page: `- [Title](path) — hook.` Sections by type (entities / concepts / packages / sources). Update on every ingest.
|
||||
Catalog, not narrative. One line per page: `- [Title](path) — hook.` Sections by type (entities / concepts / packages / sources / contradictions / open-questions). Update on every ingest.
|
||||
|
||||
### Cross-references
|
||||
|
||||
|
||||
Reference in New Issue
Block a user