name: sosal-spec
description: Структурированный поэтапный рабочий процесс, превращающий исходный запрос пользователя в исследованную спецификацию и исполняемый план работ.

disable-model-invocation: true
user-invocable: true

Процесс спецификации

Поэтапный рабочий процесс, который берёт сырой запрос пользователя и превращает его в исследованную, проверенную спецификацию с исполняемым планом работ. Работа идёт дискретными этапами; у каждого этапа один артефакт и чёткий шлюз перед началом следующего этапа.

Жёсткие правила (порядок)

Они не подлежат обсуждению и перевешивают любое желание «быть полезным», перепрыгнув вперёд:

Только новые задачи: ОБЯЗАТЕЛЬНО создать draft.md (шаг 3) до выполнения ЛЮБОГО исследования, анализа или чтения исходного кода. Первое действие в НОВОЙ задаче — всегда запись сырого ввода в draft.md.
Возобновление: при продолжении существующей задачи НЕ пересоздавайте и не перезаписывайте её файлы. Определите текущий этап по уже существующим файлам (см. «Возобновление существующей задачи») и продолжайте с него.
НЕ НАЧИНАЙТЕ исследование (шаг 6), пока не существует draft.md и не пройден шлюз уточнения (шаг 5).
Немедленные дописывания в research.md: каждый раз, когда вы находите что-то полезное для задачи — критическое техническое ограничение, путь к файлу, сигнатуру метода или любую другую значимую деталь — вы ОБЯЗАНЫ немедленно дописать это в research.md (операция дописывания в файл). Не откладывайте это до конца шага и не накапливайте находки в памяти.
Каждый этап ДОЛЖЕН быть завершён до начала следующего; не объединяйте этапы и не пишите артефакты следующих этапов, пока не существуют их входные данные.
Никакого архивирования без подтверждения: НИКОГДА не перемещайте задачу из current/ в archive/ — и вообще не считайте её завершённой/замороженной — пока пользователь явно не подтвердит, что задача выполнена. Завершённость никогда не выводится: даже если все чекбоксы в plan.md стоят [x], сообщите о завершённом состоянии и попросите пользователя подтвердить архивирование, и архивируйте только после его явного одобрения.
Единственный способ пропустить шлюз — явное указание пользователя (например, «выполни всё полностью автономно»); никогда не предполагайте автономность самостоятельно.

Правила оркестрации (делегирования)

При исполнении спецификации основная роль — оркестратор, а не исполнитель. Оркестратор поручает работу агентам и проверяет их отчёты; сам он работу не выполняет.

Жёсткие правила:

Делегируйте, а не делайте. Не ищите, не исследуйте, не реализуйте и не выполняйте задачу напрямую. Единственные прямые действия оркестратора — тривиальная «склейка», которую требует сам процесс спецификации: создание/чтение файлов задачи, переключение чекбоксов в plan.md и коммиты. Всё остальное делегируется.
Основной инструмент: subagent (синхронный). Каждая отдельная самодостаточная задача отправляется в subagent с run_in_background: false: отправка, ожидание результата, затем продолжение. Никогда не используйте фоновые запуски для работы по спецификации.
Одна задача на один subagent. Промпт subagent содержит ровно ОДНУ задачу — одну конкретную единицу работы: один шаг-чекбокс из plan.md, один исследовательский вопрос, одну проверку. Никогда не объединяйте несколько задач в одном промпте, какими бы тривиальными они ни казались. Когда задач несколько, либо отправляйте по одному subagent на задачу (последовательно), либо — когда это много независимых частей — распараллеливайте через workflow.
Самодостаточные промпты. subagent не видит этот диалог. Его промпт должен содержать всё, что нужно агенту: конкретную задачу, соответствующие пути к файлам, контекст и ограничения из spec.md/research.md, а также точный формат отчёта (что изменено, подтверждения — например, выполненные команды и их вывод — и что осталось). Всё, что вы ожидаете от него знания, но не написали в промпте, он не знает.
Ситуационный инструмент: workflow. workflow — инструмент для МНОЖЕСТВА задач: используйте его всегда, когда несколько независимых частей работы нужно распараллелить (собрать, проверить, выполнить) и затем агрегировать в структурированный отчёт. Одна задача никогда не является workflow — она уходит одному subagent.
Только последовательно. Не более одного активного sub-агента одновременно; синхронный запуск возвращает результат до следующей отправки. Никогда не запускайте несколько агентов в одном сообщении.
Независимая приёмка. Приёмка этапа — это отдельный запуск агента, который проверяет Критерий; она не полагается на самоотчёт агента-исполнителя.

Соответствие фазам спецификации:

Фаза спецификации	Инструмент
Исследование (шаг процесса 6)	синхронный `subagent`, если задача — один элемент; `workflow`, если охватывает несколько элементов (исправления багов, несколько фич)
Сбор того, что нужно сделать (контекст для этапа)	синхронный `subagent`, если один элемент; `workflow`, если несколько — соберите конкретные детали, необходимые до отправки работы
Выполнение подэлемента (каждый чекбокс этапа)	синхронный `subagent` — ровно один subagent на подэлемент; объединять несколько подэлементов в один промпт запрещено, даже для тривиальных подэлементов
Выполнение этапа с множеством подэлементов	`workflow` — по одному subagent на подэлемент, распараллеленные и агрегированные в структурированный отчёт
Приёмка этапа (Критерий этапа)	синхронный `subagent` — отдельный запуск subagent, проверяющий наблюдаемый Критерий

Правила исследования

Исследование (шаг 6 процесса) — это сбор контекста, а не решение проблемы. Оно должно оставаться поверхностным:

Область — только зависимости и файлы. Исследование означает сканирование проекта на предмет релевантного кода, зависимостей, конфигурации и существующей структуры; то есть сбор контекста. Никакие решения не проектируются, не оцениваются и не реализуются во время исследования.
Ограничения — это факты, а не догадки. Записывайте то, что уже зафиксировано: стек, бюджет, совместимость, дедлайны и существующий код. Записывайте ограничения только так, как они появляются в файлах проекта, конфигурации или вводе пользователя — не выдумывайте и не предполагайте их.
Соответствуйте существующим решениям. Если проект уже содержит похожий код или архитектуру, спецификация должна соответствовать им — не изобретайте параллельную вселенную. Расширяйте и переиспользуйте то, что есть.
Выбор инструмента по форме задачи. Задача из одного элемента исследуется через синхронный subagent (самодостаточный промпт: проект, вопрос, на который нужно ответить, и формат отчёта); задача, охватывающая несколько элементов (исправления багов, несколько фич), исследуется через инструмент workflow.
Глубокое исследование идёт в план, а не в шаг 6. Если начальное (поверхностное) исследование показывает, что требуется глубокое изучение — веб-поиск, погружение в проблему, внешние источники — это глубокое исследование добавляется в spec.md и в plan.md как запланированный рабочий элемент и выполняется как этап, а не внутри шага исследования.

Структура каталогов

Спецификации живут в .sosal-spec/: активные задачи в current/<task-tag>/, завершённые/замороженные задачи перемещаются в archive/<task-tag>/. Полную структуру и соглашения по файлам задачи см. в .sosal-spec/AGENTS.md.

Формат тега задачи

Тег задачи — <YYYY-MM-DD>_<task-name>: дата создания, затем короткий slug в kebab-case, например 2026-09-15_dark-mode.

Дата: сегодняшняя дата в ISO-формате — получите её через date -Idate — на момент создания задачи.
Имя: короткий slug в нижнем регистре, производный от запроса. Если пользователь дал имя (например, v2), используйте его; если дал полный тег, используйте как есть.
Тег — это и имя каталога задачи (current/<task-tag>/), и имя git-ветки.

Язык

Пользовательский контент пишется на языке пользователя — языке, на котором он с вами говорит. Это касается draft.md, spec.md и каждого вопроса, подтверждения или сообщения, адресованного пользователю.
Внутренние артефакты пишутся на английском: research.md и plan.md.

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

Формат спецификации (`spec.md`)

spec.md — это согласованный документ об области и подходе. Он несёт собственную метку времени создания и журнал изменений. Первая полная спецификация (v1) пишется после исследования, до плана (шаг 7); скелет на шаге 4 — это голый рабочий черновик, ещё без этого формата. Начиная с v1 spec.md всегда выглядит так:

⎗
✓
# <task-tag>: <краткое имя>

**Создано:** 2026-09-15T15:05:57+03:00

## Область
<что входит в область / что вне области>

## Подход
<как выполняется работа, ключевые решения>

## Ограничения
<фиксированные факты из исследования: стек, бюджет, совместимость, существующий код>

## Открытые вопросы
<нерешённые вопросы, или «нет»>

## Изменения

- 2026-09-15T15:05:57+03:00 -- v1, начальная спецификация (драфт + исследование)
- 2026-09-15T18:22:10+03:00 -- пользователь изменил <X>; <что именно изменилось>

Правила:

**Создано:** — метка времени, записанная при создании v1 (date -Isecond); она никогда не обновляется.
## Изменения — хронологический список, одна строка на запись, формат: - <timestamp> -- <what changed>, метки времени из date -Isecond.
Список не дополняется при каждом редактировании спецификации. Записи добавляются только когда спецификация существенно обновляется — пользователь передумал или вспомнил что-то, или после плана (или во время выполнения) было принято решение, меняющее область/подход. Каждое такое обновление получает одну запись (или несколько) со свежей меткой времени.
Список v1 начинается с одной записи, фиксирующей создание v1; мелкие правки на месте, не меняющие содержание спецификации, записи не получают.
Записи об изменениях — это пользовательский контент, поэтому они следуют правилу Языка.

Формат плана (`plan.md`)

plan.md — это живой журнал прогресса: его чекбоксы обновляются по ходу работы, а не пишутся один раз и замораживаются. Каждый этап следует TDD (падающий тест → реализация → рефакторинг) и заканчивается коммитом. Используйте этот шаблон:

⎗
✓
# <task-tag>: план реализации (<краткое имя>)

Спецификация — [spec.md](./spec.md); исследование — [research.md](./research.md).

**Формат:** каждый этап = TDD (падающий тест → реализация → рефакторинг) + коммит в конце.
Этот файл — **живой журнал прогресса** — обновляйте статусы по ходу работы.

Обозначения: `[ ]` не начато · `[~]` в процессе · `[x]` выполнено.

---

## Этап 0 — Исследование + спецификация + план
- [x] <конкретный шаг>
- [x] <конкретный шаг>

**Критерий:** <наблюдаемый критерий приёмки этапа>
**Коммит:** `<type>(<scope>): <summary>`

## Этап N — <название этапа>
- [x] <конкретный шаг>
- [~] <конкретный шаг>
- [ ] <конкретный шаг>

**Критерий:** <наблюдаемый критерий приёмки этапа>
**Коммит:** N/A 

Правила:

Один заголовок ## Этап на каждый рабочий этап; каждый этап независимо коммитится.
Каждый этап перечисляет конкретные шаги-чекбоксы, затем Критерий (как понять, что этап завершён) и строку Коммит. Строка Коммит остаётся пустой, пока этап реально не выполнен — впишите настоящее сообщение conventional commit только когда чекбоксы этапа [x] (у ещё не выполненного этапа нет коммита).
Начинайте с Этапа 0, охватывающего само исследование + спецификацию + план.
Обновляйте чекбоксы на месте по мере продвижения; не переписывайте весь файл.

Процесс

Захват ввода. Получите запрос пользователя. Если пользователь не указал тег задачи, сформируйте его в формате <YYYY-MM-DD>_<task-name> (дата через date -Idate, имя — короткий kebab-case slug, придуманный из запроса); если пользователь дал только имя (например, v2), добавьте к нему сегодняшнюю дату; если дан полный тег, используйте его как есть.
Предварительные проверки (git). Перед записью любого файла:
- если в рабочем дереве есть незакоммиченные изменения — немедленно остановитесь и сообщите о них пользователю; ничего не пишите.
- если текущая ветка — master — создайте ветку с именем <task-tag> и переключитесь на неё.
Создайте или обновите draft.md. ДОЛЖЕН быть первым файлом, записанным в новой задаче. Запишите сырой ввод дословно. Не переписывайте, не резюмируйте и не интерпретируйте на этом этапе — никакого исследования, чтения исходников, никакого «дай-ка проверю, как это работает» до создания этого файла.
Напишите начальный spec.md. Создайте первый вариант spec.md только из draft.md — его область, подход и вопросы, уже видимые в драфте. Этот шаг лишь переводит драфт: никакого исследования, никакого чтения исходников. Это голый рабочий скелет (без заголовка Создано, без раздела Изменения), который будет доработан до v1 на шаге 7.
Подтвердите уточнение. Спросите пользователя, нужно ли уточнить драфт (и начальную спецификацию, написанную по нему) перед продолжением. Примените запрошенные правки к draft.md и перенесите их в spec.md.
Исследование. Начинайте только после прохождения шага 5. Собирайте контекст по Правилам исследования (поверхностное сканирование: зависимости, файлы, фиксированные ограничения, существующие решения); инструмент выбирается по форме задачи (синхронный subagent для одного элемента, workflow для нескольких). Важно: обновляйте research.md непрерывно по ходу дела — не откладывайте запись находок до конца, чтобы ничего не потерялось после сжатия контекста.
Уточните спецификацию. Обновите spec.md из драфта вместе с результатами исследования. Учтите, что некоторые пункты могут оказаться невыполнимыми или дорогими по результатам исследования; честно отразите это в спецификации. Этот шаг создаёт v1 — первую спецификацию в полном формате: метку времени **Создано:** (date -Isecond) и раздел ## Изменения, засеянный одной начальной записью.
Проверьте спецификацию. Проработайте spec.md и разрешите все открытые вопросы или проблемы.
Напишите план. Если блокирующих вопросов или проблем не осталось, создайте plan.md.
Выполняйте после подтверждения. Начинайте выполнение только после того, как пользователь подтвердил план.

Возобновление существующей задачи

Пользователь может указать на существующую задачу её каталогом (current/<task-tag>/ внутри .sosal-spec/) или файлом внутри него (например, .../draft.md). В этом случае задача не новая — не начинайте с шага 1 и не перезаписывайте существующие артефакты без явной просьбы. Вместо этого изучите каталог задачи и возобновите с этапа, на который указывают уже существующие файлы:

Файлы в каталоге задачи	Текущий этап	Продолжить с
только `draft.md`	драфт (шаг 3)	уточнить / подтвердить драфт
`draft.md` + `research.md`	исследование (шаг 6)	завершить исследование, затем написать спецификацию
… + `spec.md`	спецификация (шаги 7–8)	проверить спецификацию
… + `plan.md`	план (шаг 9)	выполнять после подтверждения

Если файл существует, но явно неполон, продолжайте его на месте, а не переписывайте с нуля. Если этап неоднозначен, сформулируйте своё понимание текущего этапа и подтвердите его перед продолжением.

Примечания

Закоммитьте задачу (план) до её выполнения, чтобы зафиксировать согласованную область.
Делайте коммит в конце каждого крупного этапа работы.
Если спецификация обновляется после v1 — пользователь передумал, вспомнил что-то или выполнение вынудило изменить область/подход — обновите spec.md и добавьте запись в ## Изменения со свежей меткой времени, согласно правилам Формата спецификации.
Использование списка задач и/или инструментов целей рекомендуется, но не обязательно; важно, чтобы прогресс фиксировался в plan.md.