diff --git a/dist/command-index.skill b/dist/command-index.skill new file mode 100644 index 0000000..3bb04c6 Binary files /dev/null and b/dist/command-index.skill differ diff --git a/skills/command-index/SKILL.md b/skills/command-index/SKILL.md new file mode 100644 index 0000000..d318ebb --- /dev/null +++ b/skills/command-index/SKILL.md @@ -0,0 +1,58 @@ +--- +name: command-index +author: ours +version: 0.1.0 +description: > + Convention skill for the project's executable contract: a `justfile` (preferred, + cross-platform) or `Makefile` at the repo root listing the standard targets + `setup test lint build run clean help`. The command index is the single answer to + "how does this project run" — any agent reads one file instead of guessing between + build.ps1 / npm scripts / pyproject. Use when entering a project (read the index + before running project operations), asked «как тут запускается» / «как собрать, + запустить, протестить», or when scaffolding a repo's command surface. Prefer + `just` over make (native Windows binary, no sh dependency); make is the fallback. + Windows one-time install: `winget install neil.fraser.just`. Rooted in idea 3 / + 18 (claude-to-agents): Makefile/just as единый интерфейс управления проектом. +--- + +# command-index + +> The project's command surface as a single executable file. `just --list` / `make help` is auto-documentation; the agent reads the index once and never guesses again. + +## When to use + +- **Entering a project** — read the command index before running any project operation: `justfile` → `Makefile` → `package.json` `scripts` → `pyproject` task runners. First hit wins. +- **«Как тут запускается?»** / «как собрать, запустить, протестить?» — answer from the index, don't reverse-engineer scripts by reading them. +- **Scaffolding** — when a repo has no index and 2+ recurring operations (build + test + lint), propose creating one. + +## Convention + +- One file at repo root: **`justfile`** (preferred) or **`Makefile`** (fallback). +- Standard target names: `setup test lint build run clean help`. +- **`help` / `--list` = auto-doc**: every target carries a one-line comment (`just`: `# comment` above the recipe; `make`: `## comment` above the target), so `just --list` / `make help` reads as the project's manual. +- `CLAUDE.md` / `AGENTS.md` references it: «все операции — через just». The index is the **executable contract** (AGENTS.md = readable contract; command-index = executable contract). + +## Steps + +1. **Discover.** Check in order: `justfile`, `Makefile`, `package.json#scripts`, `pyproject.toml` task runners. First hit wins; stop there. +2. **Read targets.** Extract the target list (`just --list` / `make help` / `npm run`). Prefer indexed targets over raw script chains. +3. **Answer.** «Как тут запускается» — из индекса: setup → test → lint → build → run. +4. **No index?** Propose one with the standard target set, or document the de-facto index (`package.json` scripts) explicitly — a written pointer beats silent guessing. + +## Windows notes + +- **`just` preferred**: native Windows binary, cross-platform recipes, no `sh` dependency. `make` recipes run through `sh` on Windows — friction (paths, quoting). +- One-time install: `winget install neil.fraser.just` (или `choco install just` / `scoop install just`). +- If the repo already uses `make` — follow it, don't force-migrate unasked. + +## What NOT to do + +- **Не угадывать команды**, когда индекс существует — читать его. +- **Не выдумывать таргеты** вне индекса; таргет, который есть в репо, но не заиндексирован = документационный долг → предложить добавить. +- **Не гонять raw-цепочки** npm/pip, когда индексированный таргет покрывает ту же операцию. +- **Не форсить make на Windows** (just лучше); не мигрировать рабочий make-репо без просьбы. +- **Не игнорировать индекс** в пользу памяти «я знаю этот проект» — стек меняется, индекс актуален. + +## Why this exists + +Идея 3 / 18 (running record `claude-to-agents`): make/just как единый интерфейс управления проектом — агент открывает один файл и видит весь репертуар операций (setup/test/lint/build/run/clean/help), убивая класс вопросов «как тут запускается»; любой агент (pi/claude/hermes/codex) читает одно и то же. `just` выбран над `make` из идеи 18 (Buzz-референс): нативный Windows-бинарь, кросс-платформенный, без sh-зависимости. Интеграция в `project-bootstrap` (эмитит justfile при бутстрапе) — follow-up, не в этом скоупе.