diff --git a/.opencode/commands/feature-spec.md b/.opencode/commands/feature-spec.md new file mode 100644 index 0000000..f5651d5 --- /dev/null +++ b/.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 — юзер сам. diff --git a/.opencode/skills/feature-spec/SKILL.md b/.opencode/skills/feature-spec/SKILL.md new file mode 100644 index 0000000..b80fd5d --- /dev/null +++ b/.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" | diff --git a/docs/decisions/072-pr-172-feature-spec-skill.md b/docs/decisions/072-pr-172-feature-spec-skill.md new file mode 100644 index 0000000..0e27ed7 --- /dev/null +++ b/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) diff --git a/docs/handoff/pr-172-feature-spec-skill.md b/docs/handoff/pr-172-feature-spec-skill.md new file mode 100644 index 0000000..4bea519 --- /dev/null +++ b/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 diff --git a/docs/project-map/README.md b/docs/project-map/README.md index 1968580..c985e92 100644 --- a/docs/project-map/README.md +++ b/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