Spec First

---
name: spec-first
description: >
  Start a new project with a spec before code. Two phases: Vision (what/why) then Blueprint (how/order).
  Use when: user describes a new project idea ("I want to build a bot", "need a site for...",
  "new project", "start a project", "plan the project",
  "build me", "let's make"), says /spec-first, or when existing code has no docs/vision/blueprint.
  Also triggers on Russian: "хочу сделать", "нужен сайт для", "новый проект", "начинаем",
  "давай спеку", "запускаем".
  Do NOT use for: reviewing existing specs (use multi-layer-review), debugging, code review, adding features
  to a project that already has docs/vision.md, or general Q&A.
---

# Spec-First — старт проекта через спецификацию

Структурированный запуск проекта: сначала спека, потом код. Две фазы: Vision (что и зачем) → Blueprint (как и в каком порядке).

## Онбординг

Скажи пользователю:

"Давай сначала опишем проект — я задам несколько простых вопросов, а потом сам составлю план сборки. Это займёт около 20 минут.

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

---

## Определи фазу

Все пути (`docs/vision.md`, `docs/blueprint.md`) — относительно корня проекта (текущая рабочая директория). Если папка `docs/` не существует — создай.

### Проверь контекст

| Код есть? | vision.md | blueprint.md | Действие |
|-----------|-----------|--------------|----------|
| Нет | Нет | Нет | **Vision** с нуля |
| Нет | Да | Нет | Проверь что vision.md содержит секции "User Stories" и "MVP Scope". Если да → **Blueprint**. Если нет → дополни Vision |
| Нет | Да | Да | Покажи статус (задачи из blueprint), предложи начать сборку |
| **Да** | **Нет** | **Нет** | **Ретроспека**: изучи код (package.json/requirements.txt, главный файл, модели), предложи черновик ответов на Q1-Q9. Спроси: "По коду я понял так: [...]. Верно?" Дальше — стандартный Vision, но только по неотвеченным вопросам |
| Да | Да | Нет | Проверь vision.md на соответствие коду, затем **Blueprint** |

### Аргументы
- `vision` — фаза Vision (если vision.md есть — покажи и спроси: "Переделываем или правим?")
- `blueprint` — фаза Blueprint (если vision.md нет — предупреди и начни с Vision)
- Любой другой текст — прими как описание проекта (ответ на Q1), начни Vision с Q2

---

## Фаза Vision (что и зачем)

Задавай вопросы ПО ОДНОМУ. Жди ответа перед следующим. Если пользователь ответил сразу на несколько — прими все ответы, подтверди ("Понял: это [X], для [Y]"), продолжи с первого неотвеченного.

### Вопросы (порядок: сначала мечта, потом рамки, потом проверка)

**Q1:** Что ты хочешь сделать? Опиши в одном-двух предложениях.

**Q1.5:** Зачем тебе это? Что изменится, когда проект заработает?

**Q2:** Для кого это? Ты сам, друзья, публичная аудитория?

**Q3:** Опиши главный сценарий: пользователь открывает → делает → видит. По шагам, как инструкцию.

**Q4:** Пользователь закрыл приложение и вернулся завтра. Что должно сохраниться? (история, настройки, ничего?)

**Q5** (если в ответах упоминается AI/LLM/нейросеть/генерация): Как AI должен общаться? Формально, дружески? Есть ли запретные темы?

**Q6:** Есть ли что-то похожее на то, что ты хочешь? Чем твоё будет отличаться?
*Подсказка: если не знает — предложи 2-3 известных аналога из этой области. Если аналогов нет — запиши "Аналоги не выявлены" и продолжай.*

**Q7:** Где это будет работать — телефон, компьютер, Telegram?

**Q7.5:** Нужны ли внешние сервисы (API, базы, платёжки)? Есть ограничения по бюджету?

**Q8:** Чего точно НЕ будем делать в первой версии?
*Подсказка: если затрудняется — предложи 3-4 типичных расширения для такого типа проекта и спроси: "Берём в v1 или оставим на потом?"*

**Q9:** Представь — проект готов. Ты открываешь и проверяешь. Какие 3 вещи сделаешь чтобы убедиться что всё работает?
(Пример: "напишу боту /start и получу приветствие")

### Если пользователь затрудняется

Не оставляй вопрос без ответа. Помоги:
- **Q1:** предложи аналогию: "Это как [X], только для [Y]?"
- **Q3:** пройди вместе: "Представь — ты открыл. Что первое видишь?"
- **Q4:** предложи варианты: "Обычно для такого проекта сохраняют: тексты, настройки, историю действий, ничего. Что ближе?"
- **Q5:** предложи рамку: "Представь AI как сотрудника — он формальный и точный, или дружелюбный и разговорчивый?"
- **Q6:** подскажи 2-3 аналога из области. Если пользователь не знает — это нормально, запиши и двигайся дальше
- **Q7:** предложи дефолт: "Для начала — локально. Деплой добавим потом. Ок?"
- **Q7.5:** предложи типичные варианты: "Обычно для такого проекта нужны: база данных, API какого-то сервиса, хостинг. Что из этого актуально? По бюджету — бесплатные тарифы или готов платить?"
- **Q8:** подсказка уже встроена в вопрос. Если затрудняется — предложи 3-4 типичных расширения и спроси что оставить на потом
- **Q9:** предложи 3-4 проверки из контекста проекта, спроси какие подходят

Если после двух попыток ответа нет — предложи разумный дефолт и запиши в секцию "Риски" как допущение.

### Генерация vision.md

После всех ответов сгенерируй `docs/vision.md`:

```
# Vision: [Название]
## Одной строкой
## Проблема
## Для кого
## User Stories (минимум 2, из ответов на Q3; если мало — спроси ещё)
## Аналоги и отличия (из Q6; если аналогов нет — "Не выявлены")
## MVP Scope (чеклист фич, каждая помечена [MUST], [NICE] или [LATER])
## НЕ делаем в v1
## Проверки готовности (превращай ответы Q9 в конкретные проверки с числами — это твоя работа, не пользователя)
## Данные и состояние (из Q4)
## AI-поведение (если применимо, из Q5)
## Риски (минимум 1 запись)
```

### Gate → Blueprint

Не переходи дальше пока не выполнено:
- Минимум 2 сценария "делаю X → получаю Y" (из Q3/Q9)
- Хотя бы 1 конкретная проверка (не "чтобы работало", а действие → результат)
- Есть хотя бы 1 пункт в "НЕ делаем"
- Пользователь подтвердил Vision

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

**Если пользователь настаивает пропустить:** "Понимаю, хочется быстрее. Но без [недостающее] через 2 часа упрёмся в переделку. Давай за 2 минуты закроем — вот вопрос: [...]". Если настаивает второй раз — пропусти, но запиши пропущенное в "Риски" с пометкой `[GATE SKIP]`.

Когда gate пройден: "Vision готов. Сейчас подготовлю план сборки — тебе нужно будет только проверить и одобрить."

---

## Фаза Blueprint (как строим)

Прочитай `docs/vision.md`. Проверь наличие обязательных секций. Если чего-то нет — дополни через вопросы Vision прежде чем продолжать.

Проходи шаги ИНТЕРАКТИВНО — каждый покажи; где решение за пользователем, жди ответа:

**Шаг 1. Технологии** — предложи 2 готовых набора технологий. Объясни разницу простым языком: не "React vs Vue", а "Вариант 1 загружается быстрее, Вариант 2 проще и дешевле". Дай рекомендацию. **Жди выбора.**

**Шаг 2. Какие данные хранит приложение** — покажи наглядно таблицей (сущности, поля). Обязательно учти ответ на Q4 (что сохраняется между сессиями). Спроси: "Ничего не забыл?" **Жди ответа.**

**Шаг 3. Структура проекта** — дерево папок и файлов. Покажи и сразу переходи к шагу 4: решать тут пользователю нечего, поправит, если захочет.

**Примечание по дизайну:** если проект имеет визуальный интерфейс (сайт, приложение) — упомяни что дизайн прорабатывается отдельно, перед началом вёрстки. Не углубляйся — это не задача этого скилла. Достаточно добавить в план сборки задачу-placeholder: "Подготовить дизайн/прототип (отдельный этап)".

**Шаг 4. Деплой** — основной вариант — VPS владельца (его сервер Timeweb, где живут остальные проекты); альтернатива — локально или Telegram-хостинг, если проекту не нужен сервер. Облачные хостинги (Vercel и подобные) не предлагай, если пользователь сам о них не попросил. Учти ответы на Q7/Q7.5 (платформа, бюджет). Если проект чисто локальный — скажи "Деплой не нужен, запускаем локально" и двигайся дальше. **Жди ответа.**

**Шаг 5. План сборки** — 3-15 задач в правильном порядке. Каждая задача в формате:
```
1. [ ] Название задачи (зависит от N)
   Файлы: file1.js, file2.js
   Готово когда: [конкретная проверка — что можно увидеть/запустить]
```
Каждая задача понятна без технических знаний. Если >15 — предложи разбить на этапы. **Жди ответа.**

**Шаг 6. Чек-лист проверки** — минимум 5 проверок "Делаю X → Вижу Y" (из Q9 + дополнительные). **Жди ответа.**

**Шаг 7** (если в vision есть AI-поведение): добавь в стек AI-провайдер, задачу на системный промпт, 2+ проверки на AI-поведение. **Жди ответа.**

**Шаг 8. Свежий взгляд** — после шагов 1-7 предложи:

"Хочешь, я взгляну на весь план свежим взглядом — проверю, не упустил ли чего?"

Если пользователь согласен — перечитай vision.md и все шаги Blueprint заново. Проверь:
1. **Полнота:** все ли фичи из MVP Scope попали в задачи? Нет ли обсуждённого в Vision, что потерялось?
2. **Порядок:** задачи стоят в правильной последовательности? Зависимости не нарушены?
3. **Конкретность:** каждый "Готово когда" — это проверяемое действие, а не "должно работать"?
4. **Фазы разработки:** учтены ли все этапы — настройка, основная логика, интеграции, деплой, проверки?
5. **Соответствие Vision:** blueprint не противоречит scope, антископу или ограничениям?

Покажи результат: что ок, что предлагаешь исправить. Если есть правки — внеси после одобрения. **Жди ответа.**

Если пользователь отказался — двигайся дальше без задержки.

### Генерация blueprint.md

После одобрения (или пропуска шага 8) — сгенерируй `docs/blueprint.md`:

```
# Blueprint: [Название]
## Tech Stack (с обоснованием)
## Структура проекта (дерево)
## Data Model (таблицы)
## API / Endpoints (если есть)
## Деплой (куда, как, бюджет)
## Задачи (чеклист: название, файлы, "готово когда")
## Проверки готовности (минимум 5)
```

### Gate → код

- Стек одобрен
- 3-15 задач
- Минимум 5 проверок готовности
- Данные описаны
- Нет противоречий с vision.md

**Если пользователь настаивает пропустить:** те же правила — одна попытка убедить, при втором отказе пропустить с записью в blueprint.md секции "Пропущенные проверки".

Когда gate пройден — обнови CLAUDE.md проекта (**дополни**, не перезаписывай если уже существует):
- Описание проекта (из vision)
- Стек и структура (из blueprint)
- Boundaries: Always (тесты, .env, коммиты, **сверяться с docs/blueprint.md перед началом работы**) / Ask First (новые зависимости, миграции БД) / Never (секреты в коде, удаление данных)
- Ссылки на docs/vision.md и docs/blueprint.md

Скажи: "План готов! Скажи 'поехали' — и начинаю собирать по шагам."

При старте сборки: если доступен скилл `superpowers:executing-plans` — используй его. Если нет — бери задачи из blueprint.md по порядку, реализуй по одной, отмечай [x] после каждой.

---

## Навигация между фазами

**Возврат из Blueprint в Vision:**
Если пользователь хочет изменить scope/сценарий во время Blueprint:
1. Мелкая правка (добавить/убрать фичу) → обнови vision.md, продолжи Blueprint
2. Меняется суть (другая аудитория, другой сценарий) → вернись к нужному вопросу, пересоздай vision.md, проверь gate

**После любого изменения vision.md** — проверь, не противоречит ли текущий blueprint. Если да — предупреди и предложи пересобрать затронутые секции.

---

## Антипаттерны

Проверяй на каждом ответе. Если замечаешь — сразу мягко предупреди:

- **"Ещё одну фичу"** → покажи сколько компонентов добавится, предложи v1.1
- **"Сделай чтобы работало"** → уточни ЧТО и КАК конкретно
- **"Потом разберёмся"** → запиши в риски vision.md
- **Scope > 15 задач** → предложи разбить на этапы