From 71863040ed6bfcbecbde705e6266b94815787353 Mon Sep 17 00:00:00 2001
From: vitya <vitya.kuznetsov@gmail.com>
Date: Wed, 12 Aug 2026 20:14:14 +0300
Subject: [PATCH] =?UTF-8?q?feat:=20command-index=20v0.1.0=20=E2=80=94=20ju?=
 =?UTF-8?q?st/Makefile=20convention=20skill=20(idea=203,=20claude-to-agent?=
 =?UTF-8?q?s)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 dist/command-index.skill      | Bin 0 -> 2333 bytes
 skills/command-index/SKILL.md |  58 ++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 dist/command-index.skill
 create mode 100644 skills/command-index/SKILL.md

diff --git a/dist/command-index.skill b/dist/command-index.skill
new file mode 100644
index 0000000000000000000000000000000000000000..3bb04c6c9454a9aa85e493ce43c51a6e4f0c4ce6
GIT binary patch
literal 2333
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
DEqz`t

literal 0
HcmV?d00001

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