skills.md

Справочник скиллов

Детальная спецификация каждого скилла экосистемы: режим, задача, механика. Обзор жизненного цикла и как скиллы сцепляются — в README.md; принципы (Modes, Structured CoT, Grounding) — в context-engineering.md.

Два стиля скиллов

Скиллы разделяются по стилю написания (детали стиля — в ../contributing/skill-writing.md):

• Процедурные (Procedural) — рутинные задачи с понятным концом (/work, /step-done, /prime, /storyteller). Чистый императив: чёткий чек-лист case → action, модель исполняет шаги.
• Judgment (требующие рассуждения) — планирование, обсуждение архитектуры, capture (/grill, /blueprint, /mem). Structured Chain-of-Thought: скилл задаёт когнитивную траекторию (назови допущения → опровергни/подтверди через поиск → интегрируй → предложи).

Атомарность (The Linux Way): скиллы не объединяются в комбайны, граница скилла = граница фазы. Модель физически не может убежать вперёд — текущий скилл не несёт инструкций следующей фазы.

Interaction mode — ось, ортогональная режимам

Помимо Mode (Ask/Architect/Code/bespoke), скилл исполнения несёт ось interaction mode — может ли он блокироваться вопросом к человеку. Она не меняет, что скилл производит, только может ли он остановиться и спросить.

• attended — скилл вправе остановиться и спросить, затем продолжить с ответа.
• autonomous — никогда не блокируется: берёт лучший приемлемый дефолт и логирует, а при отсутствии дефолта завершается своим терминальным артефактом (вердикт, стоп, pointer-возврат), а не ожиданием человека.

Канал, а не флаг. Inline-вызов пользователем = attended (канал к человеку открыт). Спавн субагентом = всегда autonomous (возврат идёт родителю, не человеку — блокирующий вопрос некому ответить).

Реальная развилка attended↔autonomous — только у /work и /finalize (есть ветка вопроса к человеку). У /validate//diagnose//step-done//prepare слайс поведенчески no-op: их единственный выход — терминальный артефакт (вердикт/файл-отчёт/стоп), они уже abort-safe. Планировочные (/grill//storyteller//blueprint//prime) attended по природе — автономная ветка там недостижима. /autopilot — вершина трека, держит канал к человеку и свой run-режим (см. его спеку).

---

/prime — загрузка контекста

• Режим: — (System).
• Задача: подготовить рабочую среду сессии.
• Механика:
  1. Читает базовые спецификации (корень specs/, без подпапок) и индексный файл единственного active-плана (если есть). Планы draft (бэклог) и completed не грузятся.
  2. Загружает доменную карту (list_entities).
  3. Не задаёт вопросов, не начинает обсуждение.

/grill — обсуждение и проектирование

• Режим: Ask Mode (сдвиг) → Architect Mode.
• Задача: утвердить архитектурный подход до написания плана. Файлов не пишет.
• Механика (Structured CoT):
  1. Задаёт вопросы по одному (Ask Mode).
  2. Shift Detection: как только обсуждение касается технической реализации (паттерны, таблицы, механизмы), модель переходит в Architect Mode.
  3. Memory Grounding: обязателен search по затронутым сущностям; двухисточниковый — память и управляющая спека области, если глубже загруженного на /prime.
  4. Synthesis Form: предлагая решение, модель сплетает находку с нарративом: «Проверил entity:X; согласно ADR [[id]] соблюдаем инвариант Y, поэтому предлагаю Z».

/storyteller — создание User Story

• Режим: Architect Mode.
• Задача: сконвертировать уже обсуждённые и согласованные требования (обычно после /grill) в формализованную System-Aware User Story.
• Механика:
  1. Не ищет контекст и не задаёт вопросов — контекст уже загружен/обсуждён.
  2. Анализирует текущий контекст диалога.
  3. Создаёт <id>-<slug>.md в specs/user-stories/ (короткий id, свободная подпапка).
  4. Строго соблюдает формат: каждый шаг несёт action (наблюдаемое действие) и system_reaction (какие таблицы/джобы/сервисы затронуты). Формат и шаблон — ../consumer-guide/user-stories.md.

/blueprint — создание и правка плана

• Режим: Architect Mode.
• Задача: оформить договорённости из /grill в файлы плана plans/ либо применить более поздний итог обсуждения к существующему плану. Траектория ветвится по одному сигналу — наличию @<path>.
• Диспетчеризация:
  • нет @<path> → создание нового плана. Сканирует все *-00-index.md на status: active: фокуса нет → новый план active (берёт фокус); фокус есть → новый план draft (бэклог, фокус не воруется).
  • @<path> → правка названного плана любого статуса; status: и закрытые [x] шаги не трогаются.
  • правка draft при отсутствии активного → после записи предложить перевести его в active (подтверждение plain-text, prefill «да»).
• Механика:
  1. Финальный retrospective-чек (нет ли архитектурных антипаттернов).
  2. Обязателен search по памяти для затрагиваемой области (особенно для нового «хвоста» при правке); Architecture Block в чат до записи — на правке это обоснование изменения плана относительно закрытых шагов, оно же ложится в ## Отклонения.
  3. Создание: генерирует 00-index.md (Цель, Контекст, блок ## Grounding с двумя источниками — ### Спецификации и ### Память) и NN-step.md на каждый этап (один этап = один осмысленный коммит).
  4. Правка (use cases: расширение/урезание скоупа, «хвосты», ре-декомпозиция): обновляет 00-index.md (шаги, Решения/Отклонения, Grounding), создаёт новые NN-step.md со следующим свободным NN, не ломая закрытые [x] шаги.
  • Шаблоны индекса и step-файла — ../consumer-guide/formats.md.
• Декомпозиция — Tracer Bullets дефолт: этап = тонкий вертикальный слайс (микро-бэкенд + UI + E2E в одном коммите), а не слой; бэкенд-only этап — обоснованное исключение (инфраструктура, чистый алгоритм, миграция).
• Разметка этапа под автономный трек (заполняется при создании, питает /autopilot):
  • ## Связанные истории — <id> System-Aware Stories, которые этап обязан удовлетворить (ссылка по id, путь не несущий).
  • ## Стратегия гейта — производна от историй, не свободный выбор: пусто → test (гейт по сырому выводу тестов); есть → e2e плюс указатель на механизм запуска приложения и сева precondition.
  • ## Режим разработки — авторский выбор, три значения: standard (дефолт, он же пусто) — обычный поток; tdd — надстройка Red-Green-Refactor; ui — исследовательская вёрстка. Не производен от историй и независим от гейта (tdd-этап может иметь e2e-гейт).
  • ## Журнал проходов и ## Отложенные решения — оставляются стабами шаблона: ими владеет /autopilot.

/prepare — разведка контекста этапа

• Режим: Reconnaissance (bespoke).
• Задача: собрать карту контекста текущего этапа (файлы, символы, заметки, сущности) и записать её в plans/<prefix>/run-<NN>.md, чтобы /work реализовывал, не переоткрывая территорию, и быстро возвращался в контекст после прерывания. Реализацию (HOW) не проектирует — это работа /work.
• Дуальность: запуск пользователем (/prepare) — инлайн в основном потоке (ручная подготовка); спавн субагентом из /work — делегированно (тяжёлая загрузка сгорает в одноразовом контексте). Скилл оркестрационно-нейтрален — спавн это работа вызывающего.
• Механика (Structured CoT):
  1. Self-prime: резолв плана, индекс + файл шага, корень specs/ + RULES.md, list_entities. Назвать scope этапа одной строкой.
  2. Назвать всю территорию-кандидатов из ## Grounding и ## Затрагиваемые файлы / символы, не первые попавшиеся.
  3. Пройти методично: anchored-поиск по узлам + full-text по симптому; ключевые файлы читать целиком, из полного чтения извлечь хинты.
  4. Вердикт релевантности по каждому кандидату — нужен/нет, почему, координаты (символы, строки). Без рецепта реализации.
  5. Валидация, реверс blind-spots: отдать карту читателю без контекста разведки → найти и закрыть слепые зоны; догадки отделить от проверенного.
  6. Валидация, достаточность: сверить карту с ## Цель шага, ## Definition of done, ## Подзадачи — каждый пункт DoD имеет координату.
  7. Записать run-файл (+ компактное «Проверено и отброшено»).
  8. Презентовать супер-компактно: не дублировать файл, дать одну standout- находку — выбор лучшего и есть финальный self-check (ничего не выделяется → разведка поверхностна).
• Мотивация (две морковки): спереди — полная карта, по которой исполнитель идёт прямо в HOW; сзади — неполная карта хуже, чем никакой: исполнитель жжёт контекст на доразведку, blind-spot всплывает сломанным инвариантом.

/work — исполнение

• Режим: Code Mode.
• Задача: исполнить первый незакрытый шаг плана.
• Механика:
  1. Читает 00-index.md и NN-step.md.
  2. Разведка: есть run-<NN>.md → использует; нет → оценивает этап: нетривиальный (дефолт) делегирует /prepare-субагенту, тривиальный читает сам; решение фиксирует явной строкой.
  3. Загрузка контекста по ветке: делегация грузит только rules floor (корень specs/ + RULES.md, индекс) и не тянет полный list_entities — домен-карту приносит субагент в run-файле; self-read зовёт полный /prime. Полный list_entities — только через escape hatch.
  4. Граундится по карте run-файла (координаты, [[id]], сущности) и по ### Спецификации-указателям — контекст в голову до кода.
  5. Выводит HOW из карты и пишет код и обязательно тесты:
     • Testing Discipline — тесты под требования, не под написанный код.
     • Unit vs Feature — юнит для изолированных алгоритмов/DTO; фичевые для сценариев использования.
     • State-Machine & Flow Coverage — для многошаговых визардов/пайплайнов запрещено тестировать только прямой проход: покрывать переходы состояний, шаги назад, повторные вызовы, невалидные переходы.
     • Test Strategy Doc — перед сложным фичевым тестом кратко задокументировать, какие состояния/переходы покрываются.
     • Red-Green — багфикс начинается с падающего теста.
     • Режим разработки — маркер ## Режим разработки, три значения: standard (дефолт, он же пусто) → обычный поток, полная Testing Discipline без строгого test-first (багфиксный Red-Green действует); tdd → надстройка Red-Green-Refactor (один падающий тест → минимум кода → рефактор) на всю новую функциональность; ui → overlay выключен, этап исследовательский, проверяется UI-веткой /validate. Режим независим от стратегии гейта.
  6. Ведёт ## Рабочие заметки в файле шага. Запрещено писать туда пересказ диффа («переименовал переменную») — код виден в git. Только борьба и решения: что пробовал, почему упало, какие инварианты выяснились.
  7. Останавливается только когда все тесты проходят.
• Interaction mode (см. ниже): реальная ветка attended↔autonomous. Autonomous (спавн субагентом) — очевидный дефолт решает на месте + лог, нужно решение человека → pointer-возврат вызвавшему, без блокировки; attended (inline) — «при сомнении спроси».

/checkpoint — сохранение прогресса для перезапуска

• Режим: — (System).
• Задача: посреди этапа (контекст раздулся) сохранить состояние в файл шага, чтобы свежий /work перезапустился без переоткрытия. Держится отдельно от /step-done — терминальные эффекты противоположны.
• Механика:
  1. Резолв плана; текущий шаг = первый без [x]; чтение step-файла целиком.
  2. Оценка готовности (инверсия finished-check /step-done): какие подзадачи сделаны, какие пункты Definition of done закрыты, что осталось.
  3. Проставляет [x] готовым подзадачам; сносит находки и маркер «где встал / следующий шаг» в ## Рабочие заметки.
  4. Forbidden: не капчит в /mem, не удаляет run-файл, не ставит [x] этапа, не трогает specs/.
• Re-entry: свежий /work стартует с первой неотмеченной подзадачи и читает рабочие заметки — отдельной resume-секции нет.

/step-done — закрытие шага и capture

• Режим: Architect Mode (рефлексия).
• Задача: завершить этап, перенести знания.
• Механика:
  1. Читает ## Рабочие заметки из файла шага.
  2. Суммаризирует их в индекс (Решения / Отклонения / Открытые вопросы).
  3. Если приняты новые технические решения или найдены подводные камни — вызывает /mem для ADR-заметки.
  4. Ставит [x] в индексе.

/finalize — финализация

• Режим: Architect Mode.
• Задача: свести концы и закрыть план.
• Механика:
  1. Проверяет, что все шаги [x].
  2. Разносит знания по водоразделу: specs/ (изменились бизнес-требования, контракты, роуты) и /mem (глобальные архитектурные решения плана).
  3. Меняет статус плана на completed.
  4. Сметает run-файлы плана (plans/<prefix>/run-<NN>.md) — per-step леса завершённого прогона; файлы-запись (индекс, шаги) остаются для ручного удаления.
• Interaction mode: реальная ветка. Поднятие edge-кейсов/открытых вопросов условно по режиму; autonomous-выход — surface + стоп без перевода в completed (у скилла нет verdict-артефакта, как у /validate).

/autopilot — автономный прогон плана

• Режим: Orchestration Mode (bespoke) — спавнит и решает.
• Задача: довести готовый active-план до конца, спавня атомарные скиллы субагентами и маршрутизируя прогон по их вердиктам. Model-driven скилл, не harness-Workflow. Только исполнение; планирование ручное.
• Инвариант тонкости: оркестратор читает только индекс, step-файлы, отчёты субагентов и их pointer-возвраты; пишет только ## Журнал проходов, ## Отложенные решения и финальный отчёт. Тяжёлая работа (прогон тестов, рендер, чтение кода, диагностика) сгорает в одноразовых контекстах субагентов.
• Механика:
  1. Резолв плана (@path / единственный active / refuse при неоднозначности); план должен быть active и полностью расписан.
  2. Объявить run-режим видимой строкой: walk-away дефолт / attended по позиционному слову attended (/autopilot attended).
  3. Цикл по этапам (первый без [x]): на каждом — цикл этапа; когда этапов нет → /finalize, затем финальный отчёт.
• Цикл этапа (спавн на пиннутом этапе @<index>#NN — оркестратор владеет позицией, субагент не ре-резолвит; ветку не выбирает — она в маркерах step-файла):
  1. /work — реализация до зелёного в своём контексте.
  2. /validate — вердикт из текста отчёта: green → /step-done, этап [x]; blocked → Tier C (стоп+эскалация); defect → запись прохода → диагностика.
  3. Запись прохода строкой в ## Журнал проходов.
  4. Стоп-кран: 3 прохода без green → стоп + эскалация (решение читается из числа строк в файле, не из головы).
  5. /diagnose — located → координаты для fix-forward; inconclusive → Tier C.
  6. /work fix-forward в текущем этапе (закрытые [x] не откатываются) → к гейту.
• 3-уровневая политика неоднозначности (mode-gated):
  • Tier A — очевидный дефолт: решает /work на месте + лог.
  • Tier B — отложить за мок: судит оркестратор как держатель плана по downstream индекса; безопасно → ## Отложенные решения + маркер в коде.
  • Tier C — не нашёл / угроза downstream (или задевает закрытый [x]) → стоп + точный вопрос человеку. blocked/inconclusive — уже материализованный Tier C.
  • walk-away гоняет полную A/B/C; attended — Tier A сам, всё за ним → сразу стоп+вопрос человеку.
• Канал эскалации walk-away (Tier C): вопрос в ## Эскалации отчёта → уведомление хоста (нет механизма → деградация в чистый стоп) → останов.
• Resume бесплатный: повторный вызов стартует с первого этапа без [x] по чекбоксам; спец-паузы/resume-маркера нет.
• Keep-alive watchdog: kicked-таймер на ScheduleWakeup, собственность автопилота — оживляет зависший/выдохшийся контекстом оркестратор в той же сессии (Spawn watchdog ловит лишь субагента). ARM на старте, KICK на каждом спавне, FIRE только на остановке. Payload всегда привязанный /autopilot @<index> (bare-форма как watchdog-payload запрещена — иначе fire после завершения подхватит чужой план). Повторный вход через wakeup — сперва guard завершения: все [x] / status≠active / есть autopilot-report.md → снять wakeup и выйти, иначе возобновить. Снятие — терминальным шагом, что пишет отчёт. Guard читает только существующие артефакты, без resume-маркера.
• Финальный отчёт plans/<prefix>/autopilot-report.md — на любом завершении (finalize / Tier-C / стоп-кран): итог · прогон по этапам · отложенные (Tier B) · эскалации (Tier C) · счётчики стоп-крана. Ничто не теряется молча.
• Interaction mode: attended живёт только на оркестраторе (держателе канала к человеку); спавнимые субагенты всегда autonomous (нет канала), передаётся пиннутый этап @<index>#NN, не run-режим.

/validate — гейт этапа

• Режим: Verification Mode (bespoke) — гейт; вердикт только под неподделываемый артефакт.
• Задача: прогнать гейт текущего этапа и отдать вердикт против фиксированных артефактов. Код не правит, спеки/планы/истории не трогает — дефекты уходят в /work, корень в /diagnose.
• Дуальность: inline пользователем или спавн субагентом из /autopilot; оркестрационно-нейтрален, единственный выход — файл-отчёта, в чат компактный указатель.
• Механика:
  1. Резолв плана; текущий шаг = первый без [x]; чтение step-файла (Цель/DoD/Связанные истории/Стратегия гейта).
  2. Селектор ветки из ## Стратегия гейта (производна от наличия истории); кросс-чек presence — расхождение репортить, не угадывать.
  3. Test-ветка: полный прогон, сырой stdout/stderr verbatim; любой упавший или skipped → defect.
  4. E2E-ветка (она же UI validation branch для ui-режима): по связанным историям через браузер (Playwright). Зависит от поднятого приложения + сева precondition (механизм из ## Стратегия гейта); отсутствует → blocked (Tier C), не суждение на ходу. Покрытие — все negative_paths, не только happy path; скриншот на каждый expected.
  5. Observation/verdict split: «Что видно на экране» (нейтральная транскрипция) отдельно от «Соответствие expected» (вердикт) — оркестратор доверяет вердикту из текста, картинки не грузит.
  6. Отчёт в plans/<prefix>/step-<NN>.md (Markdown), скриншоты в plans/<prefix>/screenshots/ с префиксом step-<NN>-.
• Вердикт-контракт (читается из текста): green / defect (гейт прошёл, поведение разошлось) / blocked (гейт не смог запуститься → Tier C).

/diagnose — локализация корня

• Режим: Diagnosis Mode (bespoke) — трасса к корню, карта координат, без рецепта и правок.
• Задача: проследить упавший гейт от симптома к первопричине через слои (фронт/бэк/проводка) и отдать координаты для fix-forward. Карта — весь выход; починка принадлежит /work.
• Дуальность: inline или спавн из /autopilot; оркестрационно-нейтрален, единственный выход — файл-отчёта.
• Принцип долговечного знания: корень реконструируется из долговечных артефактов (якоря плана ## Затрагиваемые файлы/## Grounding, [[id]], коммитнутый код), переживших мёртвый контекст исполнителя; догадка по живому симптому запрещена. Fix-forward в текущем этапе, закрытые [x] не откатываются.
• Механика (Structured CoT, 7 шагов):
  1. Self-prime + формулировка симптома из ## Дефект отчёта /validate.
  2. Назвать всю подозреваемую территорию по слоям, не ближний слой.
  3. Трасса: anchored-поиск по узлам + full-text по симптому, чтение кода по координатам.
  4. Локализация: координаты корня отделены от поверхности симптома.
  5. Валидация корня: объясняет весь симптом; не локализуется из долговечных артефактов → inconclusive, не угадывать.
  6. Отчёт plans/<prefix>/diagnose-<NN>.md (+ «Проверено и отброшено»).
  7. Презентация компактная: вердикт + путь.
• Вердикт-контракт (читается из текста): located (корень на координате под долговечным артефактом) / inconclusive (не локализуется → Tier C, стоп + эскалация).

/mem — сохранение знаний

• Режим: Architect Mode.
• Задача: записать ADR-заметку в .memory/.
• Механика:
  1. Заполняет ролевую структуру: Контекст · Решение · Альтернативы · Инварианты · Антипаттерны.
  2. Якоря по двум осям: entity: (концепт) и file:/symbol: (реализация).
  3. Вес critical — только при наличии жёстких Инвариантов.
  • Дисциплина содержания и шаблоны тела — specs/04-note-authoring.md.

/mem-onboarding — онбординг существующего проекта

• Режим: Ask / Architect.
• Задача: дать стартовый seed памяти при подключении к уже существующему проекту (разовый многосессионный процесс).
• Механика: skill-driven процесс поверх существующих инструментов (search/create_note/create_entity/update_note); чанк-цикл с дедупом через search include_drafts, заметки создаются draft. Полный флоу — specs/06-onboarding.md.

/mem-explore — аварийный тормоз

• Режим: Ask / Architect.
• Задача: вывести диалог из тупика или галлюцинаций. Не часть штатного workflow — ручной тормоз, вызывается пользователем.
• Механика:
  1. Стоп-генерация предложений.
  2. Широкий retrieval по активным сущностям (list_entities + search) и сверка со Specs / RULES.md.
  3. Сопоставление последних 2–3 предложений модели с найденными инвариантами.
  4. Корректирующий дашборд расхождений. Ждёт указаний.