feat: command-index v0.1.0 — just/Makefile convention skill (idea 3, claude-to-agents)

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, не в этом скоупе.