dev-skills/av-dev/skills/doc-init/SKILL.md

name, description

name

description

doc-init

Завести новый проект — сессия вопросов и ответов по свободному описанию замысла, из которой рождается первичная документация по канону av-dev: паспорт, CLAUDE.md с инвариантами и командами, модель угроз с периметром и скелет остальных документов; первый план работ собирает интервью, а записывает его вызовом скилла av-dev:task-track — беклог принадлежит учёту работ. OpenSpec заводит не сам, а вызовом скилла av-dev:code-openspec — каталог принадлежит конвейеру. Использовать, когда начинают новый проект с нуля, когда есть только текст «что мне нужно и почему» и надо превратить его в рабочую документацию, когда просят провести стартовое интервью по брифу. Проект, где документация уже как-то ведётся, переводит скилл canon.

Заведение нового проекта

Вход — свободный текст «что мне нужно и почему». Выход — канон документов, с которого дальше работают все остальные скиллы.

Определение канона — канон. Прочитай его до первого вопроса: интервью идёт по слотам канона, а не по вкусу. Что класть в каждый файл — скелеты; не выдумывай заглушки своей формы, docs.py узнаёт только плейсхолдер оттуда.

Что init физически не может произвести

В новом репозитории нет кода, а architecture.md, database.md, conventions/ и research/ выводятся из него. Сочинить их на старте — значит проектировать вперёд реальности, и написанное протухнет раньше первой задачи.

Поэтому init заполняет то, что человек знает до первой строки кода:

Заполняется	Остаётся скелетом с честной строкой
passport.md	architecture.md
CLAUDE.md	database.md
security.md	conventions/
.av-dev.toml	research/, adr/
	review.md — журнал пуст, настройка появится с первым ревью

Честная строка информативна, а не «TBD»: «архитектуры пока нет: кода нет, заводится первой задачей». Проход читает её как факт.

tasks/BACKLOG.md в таблице нет намеренно. Первый план работ init собирает интервью (блок 6), но записывает его не он: каталогом задач владеет av-dev:task-track, и это шаг 7. Человек от каталога задач отказался — план остаётся списком в докладе, беклога в проекте не появляется, и это говорится строкой.

Порядок интервью — зависимость, а не удобство

Каждый блок опирается на ответ предыдущего; переставлять нельзя.

1. Цель и потребители. Ради чего это; кто пользуется — список закрытый, и он определяет, что считать нужным, а что интересным.
2. Чем это НЕ является и мера успеха. Граница домена — критерий, по которому потом судят в теме architecture о переносе понятия. Мера — по чему поймём, что удалось.
3. Периметр и недоверенный вход. Открыт наружу или контур доверенный; что приходит извне и каким каналом; что чувствительнее чего. Контур ещё не развёрнут — назови оба периметра, целевой и сегодняшний.
4. Стек, хранилище, необратимое. Чем пишем и почему; где данные; что в этом проекте нельзя откатить — деплой, выкладка наружу, перезапись данных.
5. Чем краснеет гейт. Какие проверки обязательны; что красит безусловно; чего в гейте намеренно не будет и кто тогда это гоняет.
6. Первые шаги стройки. Новый проект по определению начинается со стадии build: приложения ещё нет. Собери список от базы к деталям — что нужно сделать, чтобы приложение заработало, — и обоснуй порядок: он значит зависимость, а не важность. Пять-десять шагов достаточно: план дописывается по ходу стройки, и это законно.

Как вести

• Не больше трёх вопросов за итерацию (AskUserQuestion), рекомендация первым вариантом. Между итерациями применяй уже решённое.
• Сперва вычитай ответы из брифа. Если ответ уже есть в тексте, вопрос не задавай — покажи своё прочтение и спроси, верно ли.
• Не выдумывай четыре вещи: периметр, что необратимо, измеренные числа и адресата дорогой проверки. Их из замысла не вывести. Не сказано — пиши «неизвестно» с пометкой, что ждёт ответа.
• Развилка замысла — человеку, механика — сама. Имена файлов, слаги, порядок строк не выноси.

Чего может не быть

Два шага порядка работы — вызовы чужого: OpenSpec заводит конвейер, каталог задач ведёт скилл задач. Ни того, ни другого init не делает руками.

Копия. Дом правила — shared/absence.md в репозитории плагина. Правится дом, а не этот файл.

Скилл не вправе считать раскладку проекта полной. Части заводятся порознь и живут порознь; каждая узнаётся своим следом:

Чего нет	Как видно	Чего теперь не делает никто
настройки av-dev	нет .av-dev.toml в корне	проект под процесс не заводился; версии нет, настроек нет
документы канона	нет docs/	проектную конкретику брать неоткуда — темы, инварианты, прецеденты
учёт работ	нет каталога задач	запись остаётся владельцу: назови её текстом в докладе
источник требований	нет openspec/config.yaml	цикл SDD не запускается: спеки не с чем сверять

Свой скилл зовётся полным именем — av-dev:canon, av-dev:task-track, av-dev:code-review. Короткое имя может разрешиться в устаревшую проектную копию из .claude/skills/, и подмены не будет видно ни в докладе, ни в поведении.

Внешний плагин может не стоять. Их два: opsx:* — цикл SDD, и av-dev-git:commit — сообщения коммитов. Путь в дерево чужого плагина не пишется никогда: $CLAUDE_PLUGIN_ROOT ведёт только в своё дерево, а вычисленный от него путь к соседу либо не откроется, либо откроет чужую установку. Нужен чужой справочник — зови владеющий им скилл, он прочитает его сам.

Отсутствие — исход, а не поломка. Назови строкой доклада, чего теперь не делает никто, и продолжай работу. Молчать нельзя: пропуск неотличим от сделанного. Выдумывать обходной путь нельзя тоже.

Присутствие узнаётся следом в проекте, а не объявлением. Перечня того, что здесь заведено, проект не ведёт — он разошёлся бы с действительностью молча.

Оба скилла в этом же плагине и разрешаются всегда; чем оборачивается отказ от того, что они заводят, — на самих шагах 3 и 7. Заведение проекта из-за этого не останавливается: проект без OpenSpec и без учёта задач законен.

Порядок работы

1. Прочитай бриф целиком. Выпиши, на какие блоки интервью ответ уже есть.

2. Проведи интервью итерациями по ≤3 вопроса.

3. OpenSpec — вызови Skill av-dev:code-openspec. Он заводит каталог и заменяет пример в config.yaml настройкой. Делается это до первого документа: без openspec/ не работают ни opsx:propose, ни ревью дизайна, ни сверка требований. Каталог принадлежит конвейеру, а не канону, поэтому здесь только вызов — ни команды, ни формы файла init не знает.

   Человек от OpenSpec отказался — проект живёт без него законно: строка доклада, и дальше; docs.py check о каталоге тоже промолчит. Цикл SDD в таком проекте не запускается, и это надо назвать, а не обойти.

4. Заведи .av-dev.toml в корне с текущей версией раскладки — число берётся из docs.py version, а не из памяти.

5. Напиши заполняемые документы. Бриф переезжает в passport.md и отдельным файлом не остаётся: два дома для одного замысла разойдутся на первом же уточнении.

6. Заведи скелет остальных по скелетам — каждый с честной строкой.

7. Каталог задач и первые шаги — вызови скилл av-dev:task-track: он владеет форматом задач и стадией (init --stage build). Не разрешился — учёт задач остаётся владельцу, и это тоже строка доклада.

8. docs.py check из скилла canon — до отсутствия дрейфа. Замечания о незаполненных плейсхолдерах остаются: их закрывает не init, а работа.

9. Вычитай написанное — агент doc-wording, по пачке заполненных документов (passport.md, CLAUDE.md, security.md). Здесь он нужен сильнее, чем где бы то ни было: весь текст сочинён только что и по свободному брифу человека, а бриф — это как раз залог, оценки без факта и жаргон. Скелеты с честной строкой в пачку не клади, вычитывать в них нечего. Находки — готовые формулировки, подставляешь их ты.

10. Покажи человеку, что получилось, и отдельным списком — что выведено из брифа, что предположено, что осталось неизвестным. Правят по этим строкам.

Что дальше

• Содержимое канона по ходу разработки ведёт скилл doc-sync.
• Раскладку проверяет canon check.
• Первую задачу берёт конвейер проекта; architecture.md и conventions/ наполняются его шагом синка, а не заранее.

Чего этот скилл не делает

• Не проектирует систему. Архитектура выводится из кода, а не наоборот.
• Не пишет код и не заводит сборку.
• Не переводит существующий проект — это canon adopt. Признак: в репозитории уже есть документация или беклог в какой-то раскладке.
• Не решает за человека, что важно: цель, границы и периметр — его ответы.