feat(feature-spec): add SDD-style Q&A skill for feature planning (#172)

* feat(feature-spec): add SDD-style Q&A skill for feature planning

* docs(pr-172): add handoff, ADR-072, update project-map

---------

Co-authored-by: opencode-agent <agent@opencode.local>

.opencode/commands/feature-spec.md

@@ -0,0 +1,5 @@
+---
+description: Feature spec — SDD-style Q&A before implementation
+agent: build
+---
+Load the `feature-spec` skill via `skill({name: "feature-spec"})` and follow its ПРОТОКОЛ strictly. Главный агент — оркестратор: Q&A с юзером по SDD-шаблону, план в чате, затем issue через `issue` скилл. Не создаёт issues сам — только планирует. Не запускает /run-pipeline — юзер сам.

.opencode/skills/feature-spec/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: feature-spec
+description: Lightweight SDD-style Q&A skill for feature planning. Guides the agent through Spec-Driven Development questions before implementation. Produces a structured plan with 7 SDD sections (Контекст, Задача, Контракты, Инварианты, Граничные случаи, Вне scope, Критерии приемки). Also when user says "спека фичи", "feature spec", "план фичи", "обсудим фичу", "spec feature", "спецификация фичи".
+---
+
+# Feature Spec
+
+Лёгкий SDD-скилл: Q&A с юзером по SDD-шаблону → план в чате → issue через `issue` скилл.
+
+## Когда использовать
+
+| Ситуация | Инструмент |
+|----------|-----------|
+| 1 файл, очевидное поведение | Прямой чат, без формальностей |
+| 2+ компонента, бизнес-правила, diff >400 строк | `/feature-spec` |
+| Новый проект с нуля | `/spec` (9 фаз) |
+
+## ПРОТОКОЛ
+
+### 1. Анализ
+
+Юзер описывает фичу. Агент читает SDD-шаблон (ниже) и определяет, каких данных не хватает.
+
+### 2. Q&A
+
+Агент задаёт вопросы списком — НЕ гадает. Пример:
+
+```
+Не хватает информации по:
+1. Контракты: какой формат запроса/ответа? Какие коды ошибок?
+2. Инварианты: какие лимиты? Какой TTL? Какая модель/библиотека?
+3. Граничные случаи: что если внешний сервис недоступен? Что если данных нет?
+4. Вне scope: что точно НЕ делаем в этой итерации?
+```
+
+Юзер отвечает. Если ответ неполный — агент уточняет. Q&A продолжается пока все 7 секций не заполнены.
+
+### 3. План
+
+Когда все данные собраны, агент выводит структурированный план:
+
+```
+## Контекст
+Зачем: [мотивация]
+Контекст: [текущее состояние]
+
+## Задача
+[Что делаем — архитектурный подход, пошагово]
+
+## Контракты
+[API, форматы, коды ошибок]
+
+## Инварианты
+[Правила без исключений: лимиты, ограничения, выбор технологий]
+
+## Граничные случаи
+[Что при ошибках: невалидный вход, отказ сервиса, превышение лимита]
+
+## Вне scope
+[Что НЕ делаем]
+
+## Критерии приемки
+- [ ] Сценарий 1: "пользователь делает X → видит Y"
+- [ ] Сценарий 2
+```
+
+### 4. Handoff
+
+После готовности плана:
+- Агент: "План готов. Скажи 'создай issue' чтобы создать issue, потом запусти /run-pipeline."
+- Юзер: "создай issue" → загружается `issue` скилл → `create-issue` tool (7 секций) → issue создан
+- Юзер: `/run-pipeline` → реализация
+
+## Правила
+
+- **Не гадай** — если данных не хватает, задай вопрос
+- **Будь конкретным** — не "используй кеш", а "Redis с TTL 7 дней"
+- **Спека описывает ЧТО, не КАК** — контракты и решения, не алгоритмы
+- **Каждый пункт 1-3 предложения** — если больше, это две задачи
+- **Если фича простая** (1 файл, очевидное поведение) — скажи юзеру что спека не нужна
+- **Не создавай issues сам** — только планируй. Issues через `issue` скилл по команде юзера
+- **Не запускай /run-pipeline** — юзер делает это сам
+- **Не создавай файлы** — план живёт в чате, потом в issue
+- **1 issue = 1 PR** — если фича большая, предложи разбить на подзадачи
+
+## SDD-шаблон (7 секций)
+
+Совпадает с `create-issue` validation (PR #169):
+
+| # | Секция | Что содержит |
+|---|--------|-------------|
+| 1 | `## Контекст` | Зачем (мотивация) + текущее состояние |
+| 2 | `## Задача` | Что делаем — пошагово, с путями к файлам |
+| 3 | `## Контракты` | Ожидаемое поведение: API, форматы, коды ошибок |
+| 4 | `## Инварианты` | Правила без исключений: лимиты, ограничения, технологии |
+| 5 | `## Граничные случаи` | Что при ошибках: edge cases, отказы сервисов |
+| 6 | `## Вне scope` | Что НЕ делаем в этой итерации |
+| 7 | `## Критерии приемки` | Проверяемые сценарии: "X → видит Y" |

docs/decisions/072-pr-172-feature-spec-skill.md

@@ -0,0 +1,28 @@
+# ADR-072: Feature-spec skill — SDD-style Q&A for feature planning
+
+## Статус
+
+Accepted (PR #172)
+
+## Контекст
+
+При реализации фич через прямой чат агент часто не получает результат с первого промпта. Причины: нет зафиксированных контрактов, граничных случаев, out-of-scope. Агент угадывает решения вместо того, чтобы спросить.
+
+Существующий `/spec` скилл (9 фаз, 7 файлов) — для новых проектов, слишком тяжёл для feature-level работы. После PR #169 `create-issue` tool валидирует 7 SDD-секций. Нужен лёгкий скилл, который через Q&A вырабатывает план фичи по SDD-шаблону.
+
+## Решение
+
+Создан `feature-spec` скилл — лёгкая SDD-дисциплина для feature-level работы:
+- Slash-команда `/feature-spec` загружает скилл
+- Скилл направляет Q&A: агент задает вопросы по 7 SDD-секциям, не гадает
+- План остаётся в чате (без файлов спеки)
+- После Q&A юзер говорит "создай issue" → issue через `issue` скилл + `create-issue` tool (7 секций)
+- Затем `/run-pipeline` реализует
+
+Decision criteria: feature-spec нужен когда 2+ компонента, бизнес-правила, diff >400 строк. Не нужен для 1 файла или простых правок.
+
+## Альтернативы
+
+1. **Обогатить `issue` скилл SDD-секциями** — но issue скилл фокусируется на создании issues, а не на Q&A-планировании
+2. **Добавить "feature mode" в `/spec`** — усложнило бы существующий 9-фазный скилл
+3. **Два режима в create-issue (sdd flag)** — отвергнуто в пользу единого 7-секционного стандарта (PR #169)

docs/handoff/pr-172-feature-spec-skill.md

@@ -0,0 +1,31 @@
+---
+pr: 172
+title: feat(feature-spec): add SDD-style Q&A skill for feature planning
+---
+
+## Что сделано
+
+- `.opencode/commands/feature-spec.md` — slash-команда `/feature-spec` (pattern как spec.md, run-pipeline.md)
+- `.opencode/skills/feature-spec/SKILL.md` — скилл с:
+  - SDD-шаблон (7 секций, совпадает с create-issue validation)
+  - Инструкции Q&A: агент задает вопросы списком, не гадает
+  - Decision criteria: когда feature-spec нужен (2+ компонента, бизнес-правила, diff >400 строк), когда нет (1 файл — прямой чат)
+  - Handoff: план в чате → юзер говорит "создай issue" → issue скилл → /run-pipeline
+
+## Почему
+
+При реализации фич через прямой чат агент часто не получает результат с первого промпта — нет зафиксированных контрактов, граничных случаев, out-of-scope. Feature-spec — лёгкий скилл: Q&A по SDD-шаблону → план в чате → issue через `issue` скилл → `/run-pipeline`. Не требует oracle-скрипта, файлов спеки или создания issues.
+
+## Pending
+
+- Обновить AGENTS.md если нужно упомянуть feature-spec в pipeline или workflow
+- Добавить feature-spec в README репозитория (если применимо)
+- Мониторить использование: действительно ли Q&A улучшает результаты с первого промпта
+
+## Watch out
+
+- Feature-spec НЕ создаёт issues — только планирует. Юзер должен сказать "создай issue"
+- Feature-spec НЕ запускает /run-pipeline — юзер делает это сам
+- SDD-шаблон должен совпадать с 7 секциями create-issue validation (PR #169)
+- Если фича простая (1 файл) — агент должен сказать что спека не нужна
+- Нет oracle-скрипта — это Q&A, не детерминистичный процесс как /spec

docs/project-map/README.md

@@ -21,6 +21,7 @@ opencode-config/
 │   │   └── reviewer.md             # Code review subagent (verdict via `post-review` tool: APPROVE|REQUEST_CHANGES|NEEDS_DISCUSSION) — PR#46, PR#69
 │   ├── commands/
 │   │   ├── configure-opencode.md   # /configure-opencode — edit opencode.json
+│   │   ├── feature-spec.md          # /feature-spec — SDD-style Q&A for feature planning (loads feature-spec skill) — PR#172
 │   │   ├── repo-readme.md           # /repo-readme — standardized README generation (frontmatter agent: build, loads repo-readme skill) — PR#158
 │   │   ├── run-pipeline.md          # /run-pipeline — 7-phase PR pipeline
 │   │   └── spec.md                  # /spec — 9-phase spec generation
@@ -30,6 +31,7 @@ opencode-config/
 │   │   ├── branch/SKILL.md         # Branch naming conventions
 │   │   ├── code-standards/SKILL.md # Universal code style rules
 │   │   ├── configure-opencode/SKILL.md # Canonical rule: write to .opencode/
+│   │   ├── feature-spec/SKILL.md    # SDD-style Q&A for feature planning (7 SDD sections, decision criteria, handoff to issue skill) — PR#172
 │   │   ├── get-project-map/SKILL.md # Maintain docs/project-map/
 │   │   ├── issue/SKILL.md          # GitHub issue creation (7 SDD sections template) — PR#169
 │   │   ├── memory/SKILL.md         # opencode-memory usage guide