Compare commits
8 Commits
6073c6d0e8
...
2b2dea897b
| Author | SHA1 | Date | |
|---|---|---|---|
| 2b2dea897b | |||
| d3a83a7d41 | |||
| 074cbe9065 | |||
| 72022fc1dc | |||
| 9508db92a1 | |||
| 002a6b6e35 | |||
| fad8f87fc0 | |||
| 724897d7c6 |
@@ -14,6 +14,30 @@ _Updated: 2026-04-28_
|
||||
🔵 Blocked — waiting on external input
|
||||
-->
|
||||
|
||||
## 🟢 [bootstrap-recommend-superpowers] — project-bootstrap recommends superpowers plugin if missing
|
||||
**Status:** done
|
||||
**Where I stopped:** Step 5.6 added to `skills/project-bootstrap/SKILL.md` (read `~/.claude/plugins/installed_plugins.json`, print install command + upstream link if `superpowers@claude-plugins-official` key missing); version bumped 1.0.0 → 1.1.0; README workflow numbering updated; skill reinstalled to `~/.claude/skills/project-bootstrap/` and `dist/project-bootstrap.skill` rebuilt; log entry added
|
||||
**Next action:** (none — kept until merged)
|
||||
**Branch:** master
|
||||
|
||||
---
|
||||
|
||||
## 🟢 [mac-support-scripts] — fix install.sh / build.sh for stock macOS
|
||||
**Status:** done
|
||||
**Where I stopped:** patched both scripts to drop `mapfile` (bash 4+) and `find -printf` (GNU find) — replaced with portable shell glob + `basename` + `sort`; verified on git-bash (16 skills discovered, install dry-run + build smoke-test passed); wiki concept page `install-portability.md` added; index + log updated
|
||||
**Next action:** (none — kept until merged)
|
||||
**Branch:** master
|
||||
|
||||
---
|
||||
|
||||
## 🟡 [skill-readmes] — write English README.md for every skill + translate root README
|
||||
**Status:** paused
|
||||
**Where I stopped:** infra-skill cluster done — READMEs for `project-bootstrap`, `setup-wiki`, `setup-tasks`, `using-wiki`, `using-tasks`; root README translated; cross-links between all five skills wired up
|
||||
**Next action:** continue with the next batch — suggest the caveman cluster (`caveman`, `caveman-commit`, `caveman-review`, `caveman-help`, `caveman-compress`, `compress`) since they form a coherent group; or jump to `active-platform`, `find-skills`, `setup-context7`, `using-context7`, `using-markitdown` if the caveman cluster needs deduplication first (see `compress-dedup` task)
|
||||
**Branch:** master
|
||||
|
||||
---
|
||||
|
||||
## ⚪ [compress-dedup] — resolve compress vs caveman-compress duplication
|
||||
**Status:** ready
|
||||
**Where I stopped:** (not started) — noticed during initial migration that both skills ship identical `scripts/` subtrees (`compress.py`, `cli.py`, `detect.py`, `validate.py`, `benchmark.py`)
|
||||
|
||||
34
.tasks/bootstrap-recommend-superpowers.md
Normal file
34
.tasks/bootstrap-recommend-superpowers.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# bootstrap-recommend-superpowers
|
||||
|
||||
## Goal
|
||||
`project-bootstrap` writes `use superpowers` into the new project's `CLAUDE.md` (Step 5 template), but that trigger only fires if the `superpowers@claude-plugins-official` plugin is installed. On a fresh machine the plugin is often absent, so the trigger silently no-ops. Add a Step 5.6 that detects the plugin via `~/.claude/plugins/installed_plugins.json` and, when missing, prints a recommendation with the exact install command + upstream link. Strictly informational — never auto-installs.
|
||||
|
||||
## Key files
|
||||
- `skills/project-bootstrap/SKILL.md` — add Step 5.6 between 5.5 (manifest) and 6 (commit); bump frontmatter `version: 1.0.0 → 1.1.0`
|
||||
- `skills/project-bootstrap/README.md` — extend the steps overview to mention the new check
|
||||
- `~/.claude/plugins/installed_plugins.json` — detection source
|
||||
|
||||
## Decisions log
|
||||
- 2026-04-28: Place check at Step 5.6 (right after manifest, before commit). Reason: CLAUDE.md just got `use superpowers`, so the recommendation lands while context is fresh. Alternative — fold into Step 0 detect — rejected: Step 0 is meant to be quick + read-only summary; threading plugin checks there bloats the no-op happy path.
|
||||
- 2026-04-28: Detection by file read, not by `/plugin list`. Reason: slash commands aren't callable from inside a skill; the JSON file is the source of truth Claude Code itself reads. Same approach as `setup-context7` Phase 1.
|
||||
- 2026-04-28: Recommendation, not auto-install. Reason: `/plugin install` is interactive and per `setup-context7` we can't drive slash commands from a skill. Even if we could, auto-installing a plugin without consent is overreach.
|
||||
- 2026-04-28: Limit scope to `superpowers` only. User explicitly asked for that one. Generic "recommended plugins" framework is feature creep — defer until there's a second item.
|
||||
|
||||
## Open questions
|
||||
- [ ] None — done.
|
||||
|
||||
## Completed steps
|
||||
- [x] Confirm plugin install path / JSON shape from local `installed_plugins.json`
|
||||
- [x] Pick insertion point (Step 5.6)
|
||||
- [x] Pick detection method (file read of `installed_plugins.json`)
|
||||
- [x] Patch `SKILL.md` (Step 5.6 + frontmatter `version: 1.1.0`)
|
||||
- [x] Update `README.md` workflow numbering
|
||||
- [x] Reinstall to `~/.claude/skills/project-bootstrap/`
|
||||
- [x] Rebuild `dist/project-bootstrap.skill`
|
||||
- [x] Append wiki log entry
|
||||
- [x] Commit
|
||||
|
||||
## Notes
|
||||
- Plugin install command (canonical, from `installed_plugins.json` key): `/plugin install superpowers@claude-plugins-official`
|
||||
- Upstream: https://github.com/anthropics/claude-plugins-official
|
||||
- Cross-platform path: `~/.claude/plugins/installed_plugins.json` resolves identically on Windows / Linux / macOS.
|
||||
31
.tasks/mac-support-scripts.md
Normal file
31
.tasks/mac-support-scripts.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# mac-support-scripts
|
||||
|
||||
## Goal
|
||||
Make `scripts/install.sh` and `scripts/build.sh` work on stock macOS (BSD find, bash 3.2). Currently both use `mapfile` (bash 4+) and `find -printf` (GNU-only) — fatal on a fresh Mac. Without the fix, the README's "Linux / macOS (bash)" quick-start is a lie.
|
||||
|
||||
## Key files
|
||||
- `scripts/install.sh:11` — `mapfile -t names < <(find ... -printf ...)`
|
||||
- `scripts/build.sh:18` — same pattern
|
||||
- `README.md:30-38` — claims macOS bash quick-start works
|
||||
- `.wiki/concepts/build-notes.md` — companion concept page; add a sibling for the install-script portability gotcha
|
||||
|
||||
## Decisions log
|
||||
- 2026-04-28: Replace `mapfile` + `find -printf` with shell glob (`for d in "$SRC"/*/`). Reason: works in bash 3.2 (stock macOS) and avoids a `find` flavor dependency. Alternative — require `bash 4+` via `#!/usr/bin/env bash` + version check — rejected: pushes the burden onto Mac users, who would need `brew install bash` for a 30-line script.
|
||||
- 2026-04-28: Don't drop the `set -euo pipefail` line — POSIX-ish bash supports it from 3.x.
|
||||
- 2026-04-28: Final — patched both scripts; verified on git-bash (`bash -n` clean, install dry-run installs all 16 skills sorted alphabetically into temp dir, `build.sh active-platform` produces a valid `.skill` archive); wrote `.wiki/concepts/install-portability.md`; index + log updated; dist/ unchanged (smoke-rebuild was byte-identical so no dist churn).
|
||||
|
||||
## Open questions
|
||||
- [ ] None — done.
|
||||
|
||||
## Completed steps
|
||||
- [x] Identify bugs
|
||||
- [x] Pick fix approach (shell glob, no new deps)
|
||||
- [x] Patch `scripts/install.sh`
|
||||
- [x] Patch `scripts/build.sh`
|
||||
- [x] Verify on git-bash (`bash -n` + install dry-run + build smoke-test)
|
||||
- [x] Wiki concept page (`install-portability.md`) + index + log
|
||||
- [x] Commit
|
||||
|
||||
## Notes
|
||||
- `basename` is in POSIX, fine on Mac.
|
||||
- Empty `skills/` would have `"$SRC"/*/` literal under bash 3.2 without `nullglob`. Guard with `[ -d "$d" ] || continue` — works without `shopt`.
|
||||
31
.tasks/skill-readmes.md
Normal file
31
.tasks/skill-readmes.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# skill-readmes
|
||||
|
||||
## Goal
|
||||
Write English `README.md` for every skill source under `skills/`, plus translate the repo-root `README.md` to English (preserving the Russian original as `README.ru.md`). READMEs document each skill for outside readers — what it does, when it triggers, prerequisites, install. Done iteratively, one skill at a time.
|
||||
|
||||
## Key files
|
||||
- `skills/<name>/README.md` — per-skill README (created here)
|
||||
- `skills/<name>/SKILL.md` — source of truth for skill behavior; README is derived from it
|
||||
- `README.md` (root) — top-level repo README, translated to English
|
||||
- `README.ru.md` (root) — original Russian preserved
|
||||
|
||||
## Decisions log
|
||||
- 2026-04-28: Project-wide language for new READMEs is English. Russian root README preserved as `README.ru.md` for the bilingual record.
|
||||
- 2026-04-28: Skip emoji-heavy / marketing layout (caveman-compress style). Default to plain technical README with: title, one-line, sections for behavior / triggers / prerequisites / install. Skill-by-skill, no batch rewrite.
|
||||
- 2026-04-28: Started with `project-bootstrap` per user request.
|
||||
- 2026-04-28: Infra cluster (5 skills) finished; user paused the task here. Resume by picking the next batch (caveman, context7, or other) — see Next action in STATUS.md.
|
||||
|
||||
## Open questions
|
||||
- [ ] Order for the remaining skills — alphabetical, or by importance (using-wiki, using-tasks, setup-wiki, setup-tasks first since they are referenced by project-bootstrap)?
|
||||
|
||||
## Completed steps
|
||||
- [x] `project-bootstrap` README — `skills/project-bootstrap/README.md`
|
||||
- [x] Root README EN translation — `README.md` (EN) + `README.ru.md` (original RU, fixed broken `.wiki/source/...` link)
|
||||
- [x] `setup-wiki` README
|
||||
- [x] `setup-tasks` README
|
||||
- [x] `using-wiki` README
|
||||
- [x] `using-tasks` README
|
||||
|
||||
## Notes
|
||||
- Skills with README already: `caveman-compress` (different style — keep as-is, do not normalize for now).
|
||||
- Cross-platform install reference: repo root README (PS + bash both, per active-platform docs rule).
|
||||
69
.wiki/concepts/install-portability.md
Normal file
69
.wiki/concepts/install-portability.md
Normal file
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: Install / Build Script Portability
|
||||
type: concept
|
||||
updated: 2026-04-28
|
||||
---
|
||||
|
||||
# Install / Build Script Portability
|
||||
|
||||
`scripts/install.sh` and `scripts/build.sh` must run on three combos:
|
||||
|
||||
1. Windows + git-bash (primary dev workstation)
|
||||
2. Linux + bash (typical server)
|
||||
3. macOS + bash (the gotcha)
|
||||
|
||||
Stock macOS ships **bash 3.2** (frozen at 2007 because GPLv3) and **BSD `find`**. Both diverge from what Linux's bash 4+ / GNU `find` accept.
|
||||
|
||||
## What broke before the fix
|
||||
|
||||
Both scripts originally used:
|
||||
|
||||
```bash
|
||||
mapfile -t names < <(find "$SRC" -mindepth 1 -maxdepth 1 -type d -printf '%f\n' | sort)
|
||||
```
|
||||
|
||||
Two failures on stock Mac:
|
||||
|
||||
- **`mapfile`** — bash 4+ builtin. Bash 3.2 throws `mapfile: command not found`.
|
||||
- **`find -printf`** — GNU extension. BSD find throws `find: -printf: unknown primary or operator` and exits non-zero, killing the pipeline under `set -euo pipefail`.
|
||||
|
||||
Result: `bash scripts/install.sh` died on line 11 with a confusing error, before copying anything. Same for `build.sh`.
|
||||
|
||||
## Fix
|
||||
|
||||
Replace with shell glob — pure POSIX-compatible bash 3.2 syntax, no `find` flavor dependency:
|
||||
|
||||
```bash
|
||||
names=()
|
||||
for d in "$SRC"/*/; do
|
||||
[ -d "$d" ] || continue
|
||||
names+=("$(basename "$d")")
|
||||
done
|
||||
IFS=$'\n' names=($(printf '%s\n' "${names[@]}" | sort))
|
||||
unset IFS
|
||||
```
|
||||
|
||||
- `for d in dir/*/` — glob expansion. Trailing slash filters to directories.
|
||||
- `[ -d "$d" ] || continue` — guards the empty-dir case (when no subdirs exist, the literal pattern `dir/*/` is left unexpanded by default; the test rejects it).
|
||||
- `basename` — POSIX, present everywhere.
|
||||
- `IFS=$'\n' ... sort` — preserves alphabetical order to match the previous behavior (`find | sort`).
|
||||
|
||||
`$'...'` ANSI-C quoting is bash 2+. The whole approach works identically on bash 3.2 (Mac), bash 4 (Linux), bash 5 (modern Linux + brew on Mac), and the bash bundled with git-for-Windows.
|
||||
|
||||
## What still requires bash, not POSIX `sh`
|
||||
|
||||
The shebangs are still `#!/usr/bin/env bash`. Arrays (`names=()`, `names+=(...)`, `"${names[@]}"`) are bash, not POSIX. That's fine — bash is on every target OS. Demoting to `sh` would force a much uglier rewrite for no real portability gain.
|
||||
|
||||
## What was already portable
|
||||
|
||||
- `cp -R "$src" "$dst"` — POSIX flag, works everywhere.
|
||||
- `rm -rf` — POSIX.
|
||||
- `mkdir -p` — POSIX.
|
||||
- `~/.claude/skills/` — `~` expands the same on all three shells.
|
||||
- The `zip`/PowerShell branching in `build.sh` already handled "no zip on stock Windows" — the Mac path simply uses `zip`, which ships in `/usr/bin/zip` on every macOS release since forever.
|
||||
|
||||
## Test coverage
|
||||
|
||||
Manually verified on Windows + git-bash after the fix: 16 skills discovered, sorted, installed to `$CLAUDE_SKILLS_DIR`. `build.sh active-platform` produced a valid archive. No real BSD-find / bash-3.2 environment was tested — confidence comes from the fact that the new code uses only POSIX-shell + bash-2 features, all explicitly supported on stock macOS.
|
||||
|
||||
The `archive-roundtrip-test` task on the board would catch any regression here automatically.
|
||||
@@ -14,6 +14,7 @@ Catalog of all wiki pages. One line per page, organized by type. Updated on ever
|
||||
|
||||
- [active-platform-decision.md](concepts/active-platform-decision.md) — why `active-platform` is a skill (not a memory entry); why default = Windows; how it's wired into `project-bootstrap`
|
||||
- [build-notes.md](concepts/build-notes.md) — why `build.ps1` exists alongside `build.sh`; PS 5.1 backslash-in-zip gotcha; how to extract a `.skill`
|
||||
- [install-portability.md](concepts/install-portability.md) — `install.sh` / `build.sh` rewritten to drop `mapfile` (bash 4+) and `find -printf` (GNU only) so stock macOS (bash 3.2 + BSD find) works
|
||||
- [context7-setup.md](concepts/context7-setup.md) — switched context7 from manual MCP entries to the official plugin; API key in `.mcp.json` as `--api-key`; now also captured as `setup-context7` skill (one-time install/migrate flow with key discovery)
|
||||
- [repo-layout.md](concepts/repo-layout.md) — flat `skills/`, committed `dist/`, bash + PowerShell scripts; install model
|
||||
- [skill-versioning.md](concepts/skill-versioning.md) — why infra skills carry `version: <semver>` in frontmatter and how `project-bootstrap` records them in a per-project manifest
|
||||
|
||||
@@ -27,3 +27,6 @@ Parseable: `grep "^## \[" .wiki/log.md | tail -20`.
|
||||
## [2026-04-28] refactor | tasks split — `task-status-wiki` renamed to `using-tasks` (policy); new `setup-tasks` skill owns greenfield + interactive migration (no auto-parsing of old flat STATUS.md); `project-bootstrap` Step 4 delegates
|
||||
## [2026-04-28] refactor | this repo's `.tasks/` migrated to canonical layout — flat `## Done`/`## Backlog` replaced by emoji-status board (7 ⚪ Ready blocks); historical Done entries dropped (preserved in git log); `.bak` ignored via .gitignore
|
||||
## [2026-04-28] cleanup | removed stale `~/.claude/skills/{wiki-maintainer,task-status-wiki}/` installs (replaced by `using-wiki`/`using-tasks`); 16 skills installed, no duplicates; context7 plugin (mcp__plugin_context7_context7__*) confirmed live after restart
|
||||
## [2026-04-28] decision | install-portability — `install.sh`/`build.sh` patched to drop `mapfile`+`find -printf`; stock macOS (bash 3.2 + BSD find) now works; verified on git-bash (16 skills discovered, sorted, installed; build.sh produces archive)
|
||||
## [2026-04-28] decision | project-bootstrap@1.1.0 — added Step 5.6: detects `superpowers@claude-plugins-official` via `~/.claude/plugins/installed_plugins.json` and prints install command + upstream link if missing; chat-only, never auto-installs (slash commands aren't callable from a skill, and silent plugin install is overreach)
|
||||
## [2026-04-28] doc | README.md + README.ru.md — new "Using skills in projects" / "Использование в проектах" section after install quick-start; describes project-bootstrap workflow (git, .gitignore, README, .wiki/, .tasks/, CLAUDE.md, manifest, superpowers-plugin check) and the init/upgrade modes
|
||||
|
||||
86
README.md
86
README.md
@@ -1,64 +1,100 @@
|
||||
# claude-skills
|
||||
|
||||
Совместное хранилище и мастерская навыков для Claude.
|
||||
> Russian version: [README.ru.md](README.ru.md).
|
||||
|
||||
Joint workshop and storage for Claude skills.
|
||||
|
||||
## About
|
||||
|
||||
Здесь мы с Claude вместе разрабатываем, отлаживаем и храним скиллы:
|
||||
A shared workspace where Claude and I author, debug, and ship skills together:
|
||||
|
||||
- **`skills/`** — редактируемые исходники (markdown + ассеты), source of truth
|
||||
- **`dist/`** — собранные `.skill` архивы, закоммичены в репо
|
||||
- **`scripts/`** — утилиты: `build.sh` (исходник → `.skill`), `install.sh` (исходник → `~/.claude/skills/`)
|
||||
- **`.wiki/`**, **`.tasks/`** — рабочие материалы и доска задач
|
||||
- **`skills/`** — editable sources (markdown + assets), the source of truth
|
||||
- **`dist/`** — built `.skill` archives, committed to the repo
|
||||
- **`scripts/`** — utilities: `build.sh` (source → `.skill`), `install.sh` (source → `~/.claude/skills/`)
|
||||
- **`.wiki/`**, **`.tasks/`** — working notes and the task board
|
||||
|
||||
## Quick start
|
||||
|
||||
### Установить скиллы на новом компе
|
||||
### Install skills on a fresh machine
|
||||
|
||||
**Windows (PowerShell):**
|
||||
|
||||
```powershell
|
||||
git clone <repo> claude-skills
|
||||
cd claude-skills
|
||||
bash scripts/install.sh # copies every skills/* into ~/.claude/skills/
|
||||
# or only specific ones:
|
||||
bash scripts/install.sh caveman wiki-maintainer
|
||||
```
|
||||
|
||||
**Linux / macOS (bash):**
|
||||
|
||||
```bash
|
||||
git clone <repo> claude-skills
|
||||
cd claude-skills
|
||||
bash scripts/install.sh # копирует все skills/* в ~/.claude/skills/
|
||||
# или конкретные:
|
||||
bash scripts/install.sh # copies every skills/* into ~/.claude/skills/
|
||||
# or only specific ones:
|
||||
bash scripts/install.sh caveman wiki-maintainer
|
||||
```
|
||||
|
||||
Цель установки можно переопределить переменной `CLAUDE_SKILLS_DIR=/path bash scripts/install.sh`.
|
||||
The install target can be overridden with `CLAUDE_SKILLS_DIR=/path bash scripts/install.sh`.
|
||||
|
||||
### Отредактировать скилл
|
||||
> `install.sh` works on Windows under git-bash. A native `install.ps1` is on the task board but not yet implemented.
|
||||
|
||||
### Using skills in projects
|
||||
|
||||
Once the skills are installed, the easiest way to wire them into a new
|
||||
(or existing) project is the [`project-bootstrap`](skills/project-bootstrap/)
|
||||
skill. Tell the agent **"bootstrap"** or **"set everything up"** from the
|
||||
project's folder and it will, in one pass:
|
||||
|
||||
- initialize `git` (if missing) and write a sane `.gitignore`
|
||||
- create a starter `README.md`
|
||||
- lay out `.wiki/` per the [Karpathy LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) (delegated to [`setup-wiki`](skills/setup-wiki/))
|
||||
- lay out `.tasks/` with the canonical task board (delegated to [`setup-tasks`](skills/setup-tasks/))
|
||||
- write `CLAUDE.md` with skill triggers (`use superpowers`, `use project wiki`, `use task management system`, `we're on Windows`)
|
||||
- record the skill versions used in `.wiki/concepts/bootstrap-manifest.md` so cross-project layout drift stays debuggable
|
||||
- check whether the official `superpowers@claude-plugins-official` plugin is installed and, if not, print the install command — the `use superpowers` trigger is a no-op without it
|
||||
|
||||
Two modes, picked automatically: **init** for an empty folder, **upgrade**
|
||||
for an existing project (the skill only fills the gaps and never overwrites
|
||||
without explicit confirmation).
|
||||
|
||||
### Edit a skill
|
||||
|
||||
```bash
|
||||
# 1. Правишь skills/<name>/SKILL.md (или ассеты)
|
||||
# 2. Раскатываешь правки в живые скиллы:
|
||||
# 1. Edit skills/<name>/SKILL.md (or its assets).
|
||||
# 2. Push the changes into the live skill folder:
|
||||
bash scripts/install.sh <name>
|
||||
# 3. Пересобираешь архив (опц., но удобно делать перед коммитом):
|
||||
# 3. Rebuild the archive (optional, but handy before a commit):
|
||||
bash scripts/build.sh <name>
|
||||
```
|
||||
|
||||
### Собрать `.skill` архивы
|
||||
### Build `.skill` archives
|
||||
|
||||
```bash
|
||||
bash scripts/build.sh # все
|
||||
bash scripts/build.sh caveman # один
|
||||
bash scripts/build.sh # all skills
|
||||
bash scripts/build.sh caveman # one skill
|
||||
```
|
||||
|
||||
`build.sh` использует `zip` если он есть (Linux/macOS) или делегирует в
|
||||
`scripts/build.ps1` через PowerShell (Windows без `zip`). На Windows
|
||||
можно сразу запускать `powershell scripts/build.ps1`.
|
||||
`build.sh` uses `zip` when it's available (Linux/macOS) or delegates to
|
||||
`scripts/build.ps1` via PowerShell (Windows without `zip`). On Windows you
|
||||
can also run `powershell scripts/build.ps1` directly.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
claude-skills/
|
||||
├── skills/ ← исходники (по папке на скилл)
|
||||
├── dist/ ← .skill архивы (коммитятся)
|
||||
├── skills/ ← sources (one folder per skill)
|
||||
├── dist/ ← .skill archives (committed)
|
||||
├── scripts/
|
||||
│ ├── build.sh / build.ps1
|
||||
│ └── install.sh
|
||||
├── .wiki/ ← дизайн-доки, заметки
|
||||
├── .wiki/ ← design docs, notes
|
||||
├── .tasks/ ← STATUS.md
|
||||
├── CLAUDE.md
|
||||
└── README.md
|
||||
└── README.md (this file — see README.ru.md for Russian)
|
||||
```
|
||||
|
||||
Подробнее про принципы и решения — в [`.wiki/source/repo-layout.md`](.wiki/source/repo-layout.md).
|
||||
For the principles and decisions behind this layout see
|
||||
[`.wiki/concepts/repo-layout.md`](.wiki/concepts/repo-layout.md).
|
||||
|
||||
85
README.ru.md
Normal file
85
README.ru.md
Normal file
@@ -0,0 +1,85 @@
|
||||
# claude-skills
|
||||
|
||||
> English version: [README.md](README.md).
|
||||
|
||||
Совместное хранилище и мастерская навыков для Claude.
|
||||
|
||||
## About
|
||||
|
||||
Здесь мы с Claude вместе разрабатываем, отлаживаем и храним скиллы:
|
||||
|
||||
- **`skills/`** — редактируемые исходники (markdown + ассеты), source of truth
|
||||
- **`dist/`** — собранные `.skill` архивы, закоммичены в репо
|
||||
- **`scripts/`** — утилиты: `build.sh` (исходник → `.skill`), `install.sh` (исходник → `~/.claude/skills/`)
|
||||
- **`.wiki/`**, **`.tasks/`** — рабочие материалы и доска задач
|
||||
|
||||
## Quick start
|
||||
|
||||
### Установить скиллы на новом компе
|
||||
|
||||
```bash
|
||||
git clone <repo> claude-skills
|
||||
cd claude-skills
|
||||
bash scripts/install.sh # копирует все skills/* в ~/.claude/skills/
|
||||
# или конкретные:
|
||||
bash scripts/install.sh caveman wiki-maintainer
|
||||
```
|
||||
|
||||
Цель установки можно переопределить переменной `CLAUDE_SKILLS_DIR=/path bash scripts/install.sh`.
|
||||
|
||||
### Использование в проектах
|
||||
|
||||
Когда скиллы установлены, проще всего раскатить их на новый (или
|
||||
существующий) проект через скилл [`project-bootstrap`](skills/project-bootstrap/).
|
||||
Скажи агенту **«bootstrap»** или **«настрой проект»** в папке проекта — он
|
||||
за один проход:
|
||||
|
||||
- инициализирует `git` (если ещё нет) и положит вменяемый `.gitignore`
|
||||
- создаст стартовый `README.md`
|
||||
- развернёт `.wiki/` по [паттерну Karpathy LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) (делегируется в [`setup-wiki`](skills/setup-wiki/))
|
||||
- развернёт `.tasks/` с канонической доской задач (делегируется в [`setup-tasks`](skills/setup-tasks/))
|
||||
- запишет `CLAUDE.md` со скилл-триггерами (`use superpowers`, `use project wiki`, `use task management system`, `we're on Windows`)
|
||||
- зафиксирует версии использованных скиллов в `.wiki/concepts/bootstrap-manifest.md`, чтобы дрифт раскладки между проектами оставался отлаживаемым
|
||||
- проверит, установлен ли официальный плагин `superpowers@claude-plugins-official`, и если нет — выведет команду установки (без плагина триггер `use superpowers` мёртвый)
|
||||
|
||||
Два режима, выбирается автоматически: **init** для пустой папки и **upgrade**
|
||||
для существующего проекта (скилл только дозаполняет пробелы и ничего не
|
||||
перезаписывает без явного подтверждения).
|
||||
|
||||
### Отредактировать скилл
|
||||
|
||||
```bash
|
||||
# 1. Правишь skills/<name>/SKILL.md (или ассеты)
|
||||
# 2. Раскатываешь правки в живые скиллы:
|
||||
bash scripts/install.sh <name>
|
||||
# 3. Пересобираешь архив (опц., но удобно делать перед коммитом):
|
||||
bash scripts/build.sh <name>
|
||||
```
|
||||
|
||||
### Собрать `.skill` архивы
|
||||
|
||||
```bash
|
||||
bash scripts/build.sh # все
|
||||
bash scripts/build.sh caveman # один
|
||||
```
|
||||
|
||||
`build.sh` использует `zip` если он есть (Linux/macOS) или делегирует в
|
||||
`scripts/build.ps1` через PowerShell (Windows без `zip`). На Windows
|
||||
можно сразу запускать `powershell scripts/build.ps1`.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
claude-skills/
|
||||
├── skills/ ← исходники (по папке на скилл)
|
||||
├── dist/ ← .skill архивы (коммитятся)
|
||||
├── scripts/
|
||||
│ ├── build.sh / build.ps1
|
||||
│ └── install.sh
|
||||
├── .wiki/ ← дизайн-доки, заметки
|
||||
├── .tasks/ ← STATUS.md
|
||||
├── CLAUDE.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
Подробнее про принципы и решения — в [`.wiki/concepts/repo-layout.md`](.wiki/concepts/repo-layout.md).
|
||||
BIN
dist/project-bootstrap.skill
vendored
BIN
dist/project-bootstrap.skill
vendored
Binary file not shown.
@@ -15,7 +15,15 @@ DIST="$ROOT/dist"
|
||||
if command -v zip >/dev/null 2>&1; then
|
||||
mkdir -p "$DIST"
|
||||
if [ "$#" -eq 0 ]; then
|
||||
mapfile -t names < <(find "$SRC" -mindepth 1 -maxdepth 1 -type d -printf '%f\n' | sort)
|
||||
# Portable across bash 3.2 (stock macOS) and bash 4+ (Linux, git-bash):
|
||||
# avoid `mapfile` (bash 4+) and `find -printf` (GNU find only).
|
||||
names=()
|
||||
for d in "$SRC"/*/; do
|
||||
[ -d "$d" ] || continue
|
||||
names+=("$(basename "$d")")
|
||||
done
|
||||
IFS=$'\n' names=($(printf '%s\n' "${names[@]}" | sort))
|
||||
unset IFS
|
||||
else
|
||||
names=("$@")
|
||||
fi
|
||||
|
||||
@@ -8,7 +8,15 @@ SRC="$ROOT/skills"
|
||||
TARGET="${CLAUDE_SKILLS_DIR:-$HOME/.claude/skills}"
|
||||
|
||||
if [ "$#" -eq 0 ]; then
|
||||
mapfile -t names < <(find "$SRC" -mindepth 1 -maxdepth 1 -type d -printf '%f\n' | sort)
|
||||
# Portable across bash 3.2 (stock macOS) and bash 4+ (Linux, git-bash):
|
||||
# avoid `mapfile` (bash 4+) and `find -printf` (GNU find only).
|
||||
names=()
|
||||
for d in "$SRC"/*/; do
|
||||
[ -d "$d" ] || continue
|
||||
names+=("$(basename "$d")")
|
||||
done
|
||||
IFS=$'\n' names=($(printf '%s\n' "${names[@]}" | sort))
|
||||
unset IFS
|
||||
else
|
||||
names=("$@")
|
||||
fi
|
||||
|
||||
108
skills/project-bootstrap/README.md
Normal file
108
skills/project-bootstrap/README.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# project-bootstrap
|
||||
|
||||
Initializes or upgrades a project workspace in one pass: git, `.gitignore`,
|
||||
`README.md`, `.wiki/` (Karpathy's LLM Wiki layout), `.tasks/` (per-task board),
|
||||
and `CLAUDE.md` with skill triggers.
|
||||
|
||||
Operates in two modes, picked automatically:
|
||||
|
||||
- **init** — empty or near-empty folder. Creates everything from scratch.
|
||||
- **upgrade** — existing project. Detects what's already there, only fills the
|
||||
gaps. Never overwrites without explicit confirmation.
|
||||
|
||||
## When it triggers
|
||||
|
||||
The skill auto-activates on phrases like:
|
||||
|
||||
- "initialize project", "bootstrap", "setup project"
|
||||
- "upgrade project", "add wiki", "add tasks"
|
||||
- "start project", "set everything up"
|
||||
- "let's start a project", "init"
|
||||
|
||||
It also triggers when an agent is launched in a fresh folder that the user
|
||||
clearly intends to turn into a workspace.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
`project-bootstrap` does not lay out `.wiki/` or `.tasks/` by itself — it
|
||||
delegates to two companion skills, which must be installed on the machine
|
||||
running it:
|
||||
|
||||
- [`setup-wiki`](../setup-wiki/) — creates the canonical `.wiki/` layout.
|
||||
- [`setup-tasks`](../setup-tasks/) — creates the canonical `.tasks/` layout.
|
||||
|
||||
If either is missing, `project-bootstrap` stops with a clear error rather
|
||||
than falling back to ad-hoc creation. This keeps layout drift between
|
||||
projects bootstrapped at different times debuggable.
|
||||
|
||||
## What it creates
|
||||
|
||||
| Path | Source | Notes |
|
||||
|---|---|---|
|
||||
| `.git/` | `git init` | Skipped if repo already initialized. |
|
||||
| `.gitignore` | `assets/.gitignore.template` | Skipped if file exists. |
|
||||
| `README.md` | minimal stub | Skipped if file exists. |
|
||||
| `.wiki/` | delegated to `setup-wiki` | Karpathy LLM Wiki layout — `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/`, `entities/`, `concepts/`, `packages/`, `sources/`. |
|
||||
| `.tasks/` | delegated to `setup-tasks` | Canonical board — `STATUS.md` plus per-task `<task-slug>.md` files. |
|
||||
| `CLAUDE.md` | `assets/CLAUDE.md.template` | Skill triggers (`use superpowers`, `use project wiki`, etc.). On non-Windows hosts, swap the `we're on Windows` line for `we're on Linux` / `we're on macOS`. |
|
||||
| `.wiki/concepts/bootstrap-manifest.md` | generated | Records which skill versions initialized the project, so cross-project layout drift is debuggable. |
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Detect mode.** Inspect the current directory — git, `.wiki/`, `.tasks/`,
|
||||
`CLAUDE.md`, `README.md` — and print a single summary block: what was
|
||||
found, what will be created, what will be skipped.
|
||||
2. **Confirm.** One question, one confirmation. Nothing is written before the
|
||||
user agrees.
|
||||
3. **Steps 1–5.** Create or skip each piece in order — git, README, `.wiki/`,
|
||||
`.tasks/`, `CLAUDE.md`. Steps 3 and 4 delegate to the setup-skills.
|
||||
4. **Step 5.5.** Write `bootstrap-manifest.md` recording the versions of
|
||||
`project-bootstrap`, `setup-wiki`, and `setup-tasks` used.
|
||||
5. **Step 5.6.** Detect the official `superpowers@claude-plugins-official`
|
||||
plugin via `~/.claude/plugins/installed_plugins.json`. If absent, print
|
||||
a one-time chat recommendation with the install command and upstream
|
||||
link. Never auto-installs, never modifies project files.
|
||||
6. **Commit.** `chore: bootstrap project structure` for fresh repos, or
|
||||
`chore: upgrade project structure` adding only the new files for existing
|
||||
ones. Pushes only on explicit user request.
|
||||
7. **Summary.** Final report — what was created, what was skipped, suggested
|
||||
next step.
|
||||
|
||||
## Rules
|
||||
|
||||
- Never overwrite an existing file without explicit user confirmation.
|
||||
- Always show the plan before touching the filesystem.
|
||||
- Never invent project details — read what's already there.
|
||||
- Commit only files just created — never touch the rest of the tree.
|
||||
- Push only after the user explicitly says so.
|
||||
|
||||
## Install
|
||||
|
||||
From the repo root:
|
||||
|
||||
**Windows (PowerShell):**
|
||||
|
||||
```powershell
|
||||
bash scripts/install.sh project-bootstrap
|
||||
```
|
||||
|
||||
**Linux / macOS (bash):**
|
||||
|
||||
```bash
|
||||
bash scripts/install.sh project-bootstrap
|
||||
```
|
||||
|
||||
`install.sh` works on Windows under git-bash. A native `install.ps1` is
|
||||
[planned](../../.tasks/STATUS.md) but not required.
|
||||
|
||||
The skill installs to `~/.claude/skills/project-bootstrap/`. Override the
|
||||
target with `CLAUDE_SKILLS_DIR=/path bash scripts/install.sh …`.
|
||||
|
||||
## See also
|
||||
|
||||
- [`setup-wiki`](../setup-wiki/) — companion, owns `.wiki/` layout.
|
||||
- [`setup-tasks`](../setup-tasks/) — companion, owns `.tasks/` layout.
|
||||
- [`using-wiki`](../using-wiki/) — runtime policy for working with `.wiki/`.
|
||||
- [`using-tasks`](../using-tasks/) — runtime policy for working with `.tasks/`.
|
||||
- Karpathy's LLM Wiki gist:
|
||||
<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: project-bootstrap
|
||||
version: 1.0.0
|
||||
version: 1.1.0
|
||||
description: >
|
||||
Initializes or upgrades a project in the current folder: git, .gitignore, README.md,
|
||||
.wiki/ using Karpathy's method, .tasks/ for task tracking, CLAUDE.md with skill triggers.
|
||||
@@ -272,6 +272,50 @@ This file is overwritten if `project-bootstrap` is re-run on the same project. F
|
||||
|
||||
If a delegated setup-skill is unavailable on this machine (e.g. user installed only a subset), record the missing skill as `unknown` in the version column so the gap is visible.
|
||||
|
||||
---
|
||||
|
||||
## Step 5.6 — Recommend `superpowers` plugin (chat-only, never auto-install)
|
||||
|
||||
The `CLAUDE.md` template just written contains `use superpowers` as a trigger.
|
||||
That trigger is a no-op unless the official `superpowers` plugin is installed
|
||||
on the host. On a fresh machine the plugin is often absent, and the user
|
||||
won't know the trigger is silently dead. Detect and recommend.
|
||||
|
||||
Read `~/.claude/plugins/installed_plugins.json`. The path is identical on
|
||||
Windows / Linux / macOS — `~` resolves correctly under git-bash too.
|
||||
|
||||
Look for the key `superpowers@claude-plugins-official` under `plugins`.
|
||||
Two outcomes:
|
||||
|
||||
- **Installed** — say nothing. Skip to Step 6.
|
||||
- **Missing** (key absent, or the JSON file itself doesn't exist) — print
|
||||
this block in chat exactly once. Do **not** write it into any project file:
|
||||
|
||||
```
|
||||
ℹ️ Recommended: install the official `superpowers` plugin
|
||||
|
||||
CLAUDE.md now contains `use superpowers`, but that trigger is a no-op
|
||||
until the plugin is installed. With it, every session auto-loads
|
||||
brainstorming, planning, code-review, debugging, and TDD skills.
|
||||
|
||||
Install (run inside Claude Code):
|
||||
/plugin install superpowers@claude-plugins-official
|
||||
|
||||
Source: https://github.com/anthropics/claude-plugins-official
|
||||
|
||||
After install + Claude Code restart, the trigger picks it up.
|
||||
```
|
||||
|
||||
**Hard rule — never auto-install.** Slash commands aren't callable from a
|
||||
skill, and silently mutating user-level plugin state without consent is
|
||||
overreach. The recommendation is informational. The user can install it
|
||||
later, ignore it entirely, or remove the `use superpowers` line from
|
||||
`CLAUDE.md` if they prefer a leaner setup.
|
||||
|
||||
If the JSON file is malformed (rare), treat as "missing" and print the
|
||||
recommendation. Do not crash the bootstrap over a plugin-detection edge
|
||||
case — the file isn't ours to fix here.
|
||||
|
||||
## Step 6 — Commit
|
||||
|
||||
```bash
|
||||
|
||||
108
skills/setup-tasks/README.md
Normal file
108
skills/setup-tasks/README.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# setup-tasks
|
||||
|
||||
One-time skill that creates or migrates a project's `.tasks/` board to the
|
||||
canonical layout — `STATUS.md` (the board, with emoji status legend) plus
|
||||
per-task `<task-slug>.md` files for each active or paused task. The runtime
|
||||
policy for working *with* the board lives in
|
||||
[`using-tasks`](../using-tasks/) — `setup-tasks` is the only place that
|
||||
creates the structure.
|
||||
|
||||
## When it triggers
|
||||
|
||||
- User says: "set up tasks", "init tasks", "create task tracking",
|
||||
"migrate tasks to canon", "tasks broken", or the Russian equivalents
|
||||
("настрой таски", "инициализируй таски").
|
||||
- [`using-tasks`](../using-tasks/) detects a missing or non-canonical
|
||||
`.tasks/` and delegates here via its Prerequisites section.
|
||||
- [`project-bootstrap`](../project-bootstrap/) Step 4 delegates here when
|
||||
initializing a new project.
|
||||
|
||||
## Modes
|
||||
|
||||
`setup-tasks` picks one of three modes after a discovery scan:
|
||||
|
||||
| Mode | Trigger | Action |
|
||||
|---|---|---|
|
||||
| **greenfield** | No `.tasks/` exists | Write `.tasks/STATUS.md` from the canonical template. No per-task files yet — they're created on demand. |
|
||||
| **noop** | `.tasks/STATUS.md` already canon (emoji status legend + at least one per-task file) | Report and exit. |
|
||||
| **migrate** | `.tasks/STATUS.md` is flat (plain `## Done` / `## In Progress` / `## Backlog`, no emoji legend, no per-task files) | Back up, then drive an interactive migration — one task at a time, asking the user for the canonical fields. |
|
||||
|
||||
A "placeholder" STATUS.md (just the bootstrap default with no real tasks) is
|
||||
treated as `greenfield` — no migration needed.
|
||||
|
||||
## What canon means
|
||||
|
||||
```
|
||||
.tasks/
|
||||
├── STATUS.md ← board, with emoji status legend + one block per task
|
||||
└── <task-slug>.md ← per-task deep context (one file per active/paused task)
|
||||
```
|
||||
|
||||
Status legend: 🔴 active / 🟡 paused / ⚪ ready / 🟢 done / 🔵 blocked.
|
||||
|
||||
`STATUS.md` block format (one per task):
|
||||
|
||||
```
|
||||
## 🔴 [task-slug] — short description
|
||||
**Status:** active
|
||||
**Where I stopped:** one sentence — the exact thought or action interrupted
|
||||
**Next action:** one concrete step to resume immediately
|
||||
**Blocker:** (only if blocked) what is preventing progress
|
||||
**Branch:** git branch name
|
||||
```
|
||||
|
||||
Per-task file sections: Goal, Key files, Decisions log, Open questions,
|
||||
Completed steps, Notes.
|
||||
|
||||
## 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 auto-parse a flat STATUS.md.** Old layouts vary; agent heuristics
|
||||
mangle real work. Migration is interactive — the agent asks the user for
|
||||
each task's canonical fields.
|
||||
- **Never invent task slugs / branches / "where you stopped" values.** The
|
||||
whole point is *real* preserved context, not hallucinated context.
|
||||
- **No empty per-task files at greenfield.** Wait until the user adds a
|
||||
real task.
|
||||
- **Never edit the `.bak` file.** It's the rollback artifact.
|
||||
|
||||
## Procedure (high-level)
|
||||
|
||||
1. **Phase 0** — environment sanity (project root).
|
||||
2. **Phase 1** — discovery (greenfield / noop / migrate).
|
||||
3. **Phase 2** — plan + confirm. Wait for explicit "ok"/"go"/"поехали".
|
||||
4. **Phase 3** — backup (migrate only) → `STATUS.md.bak-YYYYMMDD-HHMMSS`.
|
||||
5. **Phase 4a/4b** — greenfield create or interactive migrate.
|
||||
6. **Phase 5** — verify (canon `STATUS.md`, per-task files for active/paused
|
||||
only, no required content lost).
|
||||
7. **Phase 6** — final report; if invoked from `project-bootstrap`, return
|
||||
silently.
|
||||
|
||||
Full procedure with templates and the migration script lives in
|
||||
[`SKILL.md`](SKILL.md).
|
||||
|
||||
## Rollback
|
||||
|
||||
- Greenfield: `rm -rf .tasks/`.
|
||||
- Migrate: `mv .tasks/STATUS.md.bak-<ts> .tasks/STATUS.md` plus `rm` for any
|
||||
newly created per-task files; `git reset HEAD .tasks/`.
|
||||
|
||||
## Install
|
||||
|
||||
From the repo root:
|
||||
|
||||
```bash
|
||||
bash scripts/install.sh setup-tasks
|
||||
```
|
||||
|
||||
Works on Windows under git-bash, Linux, macOS.
|
||||
|
||||
## See also
|
||||
|
||||
- [`using-tasks`](../using-tasks/) — runtime policy for working with `.tasks/`.
|
||||
- [`project-bootstrap`](../project-bootstrap/) — orchestrator that delegates
|
||||
here for new projects.
|
||||
- Source pattern: `.wiki/raw/setup-task-status-wiki.md` in this repo —
|
||||
extended documentation, decisions log format, agent operations.
|
||||
101
skills/setup-wiki/README.md
Normal file
101
skills/setup-wiki/README.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# 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 + four 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
|
||||
```
|
||||
|
||||
The four 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>
|
||||
139
skills/using-tasks/README.md
Normal file
139
skills/using-tasks/README.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# using-tasks
|
||||
|
||||
Runtime policy for keeping compressed working context across parallel tasks
|
||||
in a monorepo. The agent reads and updates `.tasks/` so every session starts
|
||||
oriented and every switch costs seconds, not minutes.
|
||||
|
||||
`using-tasks` governs *usage* of an existing `.tasks/`. Initial creation and
|
||||
migration to canon are owned by [`setup-tasks`](../setup-tasks/).
|
||||
|
||||
> Renamed from `task-status-wiki` at v1.0.0.
|
||||
|
||||
## When it triggers
|
||||
|
||||
- User is switching between tasks, resuming a paused task, starting a new
|
||||
one, or asks "where were we" / "what's the status".
|
||||
- User says: "use task management system", "pause", "switch to X",
|
||||
"update status".
|
||||
- Any context-switching or multi-task coordination question in a code
|
||||
project.
|
||||
- If `.tasks/` is missing or non-canonical, this skill delegates to
|
||||
[`setup-tasks`](../setup-tasks/) before doing anything else.
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
<monorepo-root>/
|
||||
└── .tasks/
|
||||
├── STATUS.md ← board: one block per task, sorted by priority
|
||||
└── <task-slug>.md ← deep context per task, one file each
|
||||
```
|
||||
|
||||
Commit `.tasks/` to git — decision history is valuable, diffs show how
|
||||
thinking evolved.
|
||||
|
||||
## STATUS.md format
|
||||
|
||||
```markdown
|
||||
# Task Board
|
||||
_Updated: YYYY-MM-DD_
|
||||
|
||||
## 🔴 [task-slug] — short description
|
||||
**Status:** active | paused | blocked | done
|
||||
**Where I stopped:** one sentence — the exact thought or action interrupted
|
||||
**Next action:** one concrete step to resume immediately
|
||||
**Blocker:** (only if blocked) what is preventing progress
|
||||
**Branch:** git branch name
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
Status legend:
|
||||
|
||||
| Emoji | State | Notes |
|
||||
|---|---|---|
|
||||
| 🔴 | Active | Currently worked on. **Only one at a time.** |
|
||||
| 🟡 | Paused | In progress, resumable. |
|
||||
| ⚪ | Ready | Defined, not started. |
|
||||
| 🟢 | Done | Kept until merged. |
|
||||
| 🔵 | Blocked | Waiting on external input. |
|
||||
|
||||
## Per-task file format (`<task-slug>.md`)
|
||||
|
||||
Sections, in order: **Goal** (one paragraph — what this achieves and why),
|
||||
**Key files** (`path/to/file.ts:42` style — specific lines when relevant),
|
||||
**Decisions log** (reverse-chronological, append-only — past entries are
|
||||
immutable), **Open questions**, **Completed steps**, **Notes** (temporary
|
||||
hypotheses, links).
|
||||
|
||||
## Operations
|
||||
|
||||
### Session start
|
||||
|
||||
1. Check `.tasks/STATUS.md`. If missing → invoke
|
||||
[`setup-tasks`](../setup-tasks/) and stop until it returns.
|
||||
2. Read `STATUS.md`.
|
||||
3. If user names a task, read its `<task-slug>.md`.
|
||||
4. Confirm in one sentence: "We're in the middle of X, next step is Y."
|
||||
5. Ask if the plan is still correct before doing anything.
|
||||
6. If `_Updated` is more than 3 days old, flag it and ask the user to
|
||||
confirm current state.
|
||||
|
||||
### Session end / pause / switch
|
||||
|
||||
1. Update `STATUS.md`: set the current task to 🟡, refresh "Where I stopped"
|
||||
and "Next action".
|
||||
2. Append non-obvious decisions to `<task-slug>.md` Decisions log.
|
||||
3. Move finished items to "Completed steps".
|
||||
4. Commit: `git add .tasks/ && git commit -m "chore: update task status [<task-slug>]"`.
|
||||
|
||||
### Task switch
|
||||
|
||||
1. Run session-end ops for the current task.
|
||||
2. Read the target `<task-slug>.md`.
|
||||
3. Set the target to 🔴 in `STATUS.md` (demote previous active to 🟡).
|
||||
4. Confirm orientation before starting work.
|
||||
|
||||
### New task
|
||||
|
||||
1. Ask: slug, goal, known key files, branch.
|
||||
2. Create `<task-slug>.md` with Goal and Key files populated.
|
||||
3. Add a ⚪ block to `STATUS.md`.
|
||||
4. Create / checkout the branch if missing.
|
||||
|
||||
### Task completion
|
||||
|
||||
1. Resolve or drop all open questions.
|
||||
2. Set status to 🟢 in `STATUS.md`.
|
||||
3. Append a final summary line to the Decisions log.
|
||||
4. Remind the user to delete the branch after merge.
|
||||
|
||||
## Rules
|
||||
|
||||
- **Never lose "Where I stopped".** Most critical field. If unclear, ask
|
||||
before ending the session.
|
||||
- **One sentence per `STATUS.md` field.** Compress, don't write prose.
|
||||
- **Key files must be specific** — not "auth module" but
|
||||
`packages/auth/src/useAuth.ts:87`.
|
||||
- **Decisions log is append-only.** Past entries are immutable.
|
||||
- **Commit after every session end.** `git log` is the history of thinking.
|
||||
- **Always confirm orientation at session start.** State understanding
|
||||
before acting.
|
||||
- **One active task at a time** — only one 🔴 in `STATUS.md`.
|
||||
|
||||
## Install
|
||||
|
||||
From the repo root:
|
||||
|
||||
```bash
|
||||
bash scripts/install.sh using-tasks
|
||||
```
|
||||
|
||||
Works on Windows under git-bash, Linux, macOS.
|
||||
|
||||
## See also
|
||||
|
||||
- [`setup-tasks`](../setup-tasks/) — companion, owns `.tasks/` creation and
|
||||
canon migration.
|
||||
- [`project-bootstrap`](../project-bootstrap/) — invokes `setup-tasks` for
|
||||
new projects.
|
||||
179
skills/using-wiki/README.md
Normal file
179
skills/using-wiki/README.md
Normal file
@@ -0,0 +1,179 @@
|
||||
# using-wiki
|
||||
|
||||
Runtime policy for an LLM Wiki built on the
|
||||
[Karpathy LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
|
||||
Knowledge is **compiled once and kept current** across three layers, via
|
||||
three named operations, with strict file formats that keep the wiki
|
||||
parseable and grep-friendly.
|
||||
|
||||
`using-wiki` governs *usage* of an existing `.wiki/`. Initial creation and
|
||||
migration to canon are owned by [`setup-wiki`](../setup-wiki/).
|
||||
|
||||
> Renamed from `wiki-maintainer` at v1.0.0.
|
||||
|
||||
## When it triggers
|
||||
|
||||
- User says: "use project wiki", "query the wiki", "ingest this", or the
|
||||
Russian equivalents ("обнови вики", "проверь вики", "запроси вики",
|
||||
"заингесть").
|
||||
- Any time the agent modifies a file under `.wiki/` — the workflow and
|
||||
formats below are mandatory.
|
||||
- If `.wiki/` is missing or non-canonical, this skill delegates to
|
||||
[`setup-wiki`](../setup-wiki/) before doing anything else.
|
||||
|
||||
## Three layers (do not blur)
|
||||
|
||||
1. **Raw sources** — `.wiki/raw/` (or external paths registered in
|
||||
`raw/README.md`). **Immutable.** Read, never edit. The only exception is
|
||||
appending a `> Status` blockquote when the user explicitly asks for a
|
||||
status audit.
|
||||
2. **Wiki** — everything else under `.wiki/`. Agent-owned. Entity / concept /
|
||||
package / source summary pages.
|
||||
3. **Schema** — `.wiki/CLAUDE.md`. Project-specific conventions (what
|
||||
entities, what packages, naming). Always read it first; it overrides this
|
||||
skill on conflict.
|
||||
|
||||
## Three operations
|
||||
|
||||
### Ingest
|
||||
|
||||
«заингесть X» — pull a raw source into the wiki.
|
||||
|
||||
1. Read the raw source fully.
|
||||
2. Extract: entities, concepts, packages, cross-cutting patterns.
|
||||
3. Create `sources/<slug>.md` (one summary page per source, ~50–150 lines).
|
||||
4. For each affected entity / concept / package page: update if exists,
|
||||
create if not. Flag contradictions explicitly with
|
||||
`> **Противоречие:** источник A говорит X, источник B — Y`.
|
||||
**Never silently overwrite.**
|
||||
5. Update `index.md`.
|
||||
6. Append one line to `log.md`.
|
||||
7. Report: what was created, updated, contradicted.
|
||||
|
||||
One ingest may touch 10–15 pages. That's normal — that's why an LLM does it.
|
||||
|
||||
### Query
|
||||
|
||||
A question answered from the wiki.
|
||||
|
||||
1. Read `index.md` first, drill into relevant pages.
|
||||
2. Answer with citations as markdown links.
|
||||
3. **Compound the wiki.** If the answer is a real synthesis, ask the user:
|
||||
"Сохранить как страницу wiki?" Good queries become durable pages under
|
||||
`concepts/` or `analyses/`.
|
||||
4. Append one line to `log.md`.
|
||||
|
||||
### Lint
|
||||
|
||||
«проверь wiki» — health check.
|
||||
|
||||
Scan for:
|
||||
|
||||
- Contradictions between pages.
|
||||
- Orphans (pages with no inbound links).
|
||||
- Stale claims (raw source updated after the summary's `ingested:` date —
|
||||
check via `git log -p`).
|
||||
- Concepts mentioned in prose but missing their own page.
|
||||
- Empty / TODO sections.
|
||||
|
||||
Report as a punch list. Don't delete anything automatically. Append one
|
||||
line to `log.md` with the findings.
|
||||
|
||||
## File formats (mandatory)
|
||||
|
||||
### Page frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Человекочитаемое имя
|
||||
type: entity | concept | package | source | overview
|
||||
tags: [short, tokens]
|
||||
sources: [../sources/foo.md, ../sources/bar.md]
|
||||
updated: 2026-04-21
|
||||
---
|
||||
```
|
||||
|
||||
Source pages also carry `ingested: YYYY-MM-DD` and `raw_path: ../raw/...`.
|
||||
|
||||
### 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`.
|
||||
|
||||
### `log.md` — append-only, grep-parseable
|
||||
|
||||
Every entry must start with:
|
||||
|
||||
```
|
||||
## [YYYY-MM-DD] <operation> | <short description>
|
||||
```
|
||||
|
||||
Operations: `ingest`, `query`, `lint`, `refactor`, `decision`, `init`.
|
||||
|
||||
Parse with: `grep "^## \[" .wiki/log.md | tail -20`.
|
||||
|
||||
### `index.md`
|
||||
|
||||
Catalog, not narrative. One line per page: `- [Title](path) — hook.`
|
||||
Sections by type. Update on every ingest.
|
||||
|
||||
### Cross-references
|
||||
|
||||
- Wiki → wiki: relative markdown links — `[Name](../entities/x.md)`.
|
||||
- Wiki → code: relative path from repo root — `[foo.js](../../packages/api/foo.js)`.
|
||||
- Wiki → raw: `../raw/<file>`.
|
||||
- URL-encode spaces (`%20`) and Cyrillic when needed.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Situation | Files touched |
|
||||
|---|---|
|
||||
| Ingest one doc | `sources/<slug>.md` (new) + 3–15 entity/concept/package pages + `index.md` + `log.md` |
|
||||
| Query | (read only) + optionally a new wiki page + `log.md` |
|
||||
| Lint | (read only) + `log.md` |
|
||||
| Bootstrap / migrate | (delegated to [`setup-wiki`](../setup-wiki/)) |
|
||||
|
||||
## Common mistakes
|
||||
|
||||
- **Editing `raw/`.** Don't. Only allowed change: status blockquote on
|
||||
explicit request.
|
||||
- **Dumping raw content into `sources/`.** Summaries are summaries. Link to
|
||||
raw, don't copy.
|
||||
- **Silent overwrites on contradictions.** Flag them with a `> **Противоречие:**`
|
||||
block.
|
||||
- **Narrative `log.md`.** "Today I added…" is wrong. Use
|
||||
`## [YYYY-MM-DD] ingest | <what>`.
|
||||
- **Non-ASCII filenames.** Breaks greppability and cross-platform. Transliterate.
|
||||
- **Forgetting `index.md`.** Pages not listed there are invisible to future
|
||||
queries.
|
||||
- **Improvising layout when canon files are missing.** Hand off to
|
||||
[`setup-wiki`](../setup-wiki/) instead of patching ad-hoc.
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- The project has CLAUDE.md / AGENTS.md docs but no `.wiki/` — that's regular
|
||||
documentation, not an LLM Wiki.
|
||||
- The user wants a single-file README or ADR — this skill is for persistent,
|
||||
interlinked knowledge bases.
|
||||
- One-off questions about code — read files directly, no wiki workflow needed.
|
||||
|
||||
## Install
|
||||
|
||||
From the repo root:
|
||||
|
||||
```bash
|
||||
bash scripts/install.sh using-wiki
|
||||
```
|
||||
|
||||
Works on Windows under git-bash, Linux, macOS.
|
||||
|
||||
## See also
|
||||
|
||||
- [`setup-wiki`](../setup-wiki/) — companion, owns `.wiki/` creation and
|
||||
canon migration.
|
||||
- [`project-bootstrap`](../project-bootstrap/) — invokes `setup-wiki` for
|
||||
new projects.
|
||||
- Karpathy's LLM Wiki gist:
|
||||
<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>
|
||||
Reference in New Issue
Block a user