feat(skills): bundle minimum skill set from claude-skills into factory/skills/

Copies 8 standalone skills (active-platform, caveman, project-discipline, pulling-before-work, setup-tasks, setup-wiki, using-tasks, using-wiki) from ~/projects/claude-skills/skills/ and all 14 superpowers sub-skills from the installed plugin cache into factory/skills/superpowers/. Adds skills install step to bootstrap.ps1: copies all factory/skills/ directories to ~/.claude/skills/ so users get the skill set automatically without manual plugin install for the baseline set. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-11 13:24:38 +03:00
parent 62b94034f4
commit dcf4077e82
61 changed files with 10441 additions and 0 deletions
--- a/skills/setup-wiki/README.md
+++ b/skills/setup-wiki/README.md
@@ -0,0 +1,103 @@
+# 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>
--- a/skills/setup-wiki/SKILL.md
+++ b/skills/setup-wiki/SKILL.md
@@ -0,0 +1,294 @@
+---
+name: setup-wiki
+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
+
+> 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):
+
+```markdown
+# 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):
+
+```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
+
+<!-- (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):
+
+```markdown
+# 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`**:
+
+```markdown
+---
+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`**:
+
+```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/`, `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).
+
+```bash
+# 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:
+
+```yaml
+---
+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.