@alxyrgin/agent-forge 1.0.0 → 3.1.0

package/templates/rules/development-cycle.md.ejs

@@ -2,53 +2,187 @@
 
 ## Главное правило
 
-При `/take-task` запускается **автоматический цикл**. Агенты вызываются по порядку. Пользователь подтверждает ключевые решения (план, архитектура).
+При `/take-task` запускается автоматический цикл. Агенты вызываются по порядку. Пользователь подтверждает только ключевые решения (план, архитектура). Маршрутизация — по verdict каждого агента (см. quality-gates.md).
 
-## Пайплайн
+## Feature-size маршрутизация
+
+| Размер | Критерии | Шаги |
+|--------|----------|------|
+| **S** | 1-2 файла, фикс, конфиг | 6 шагов |
+| **M** | 3-5 файлов, новая функция | 8 шагов |
+| **L** | >5 файлов, новый модуль | 10 шагов |
+
+## S-pipeline (6 шагов)
+
+```
+[0] CHECKPOINT
+[1] КОД ─────── developer
+[2] ТЕСТЫ ───── tester(unit) → inspector
+[3] QUICK REVIEW ── reviewer(mode: quick, 1 раунд)
+[4] TECH-DEBT
+[5] ФИКСАЦИЯ
+```
+
+S-задачи теперь включают quick review (security + контроль доступа + critical bugs) и inspector после тестов.
+
+## M-pipeline (8 шагов)
+
+```
+[0] CHECKPOINT
+[1] АНАЛИЗ ──── analyst
+[2] TDD (RED) ── tester(mode: tdd) — failing тесты по tdd_anchors
+[3] КОД + ТЕСТЫ (GREEN) ── developer → tester(unit) → inspector (per-feature)
+[4] РЕВЬЮ ───── reviewer (full, макс. 3 раунда)
+[5] TECH-DEBT
+[6] ФИКСАЦИЯ
+```
+
+M-задачи включают TDD-якоря: сначала failing тесты, потом код.
+
+## L-pipeline (10 шагов)
 
 ```
 /take-task [ID]
      │
      ▼
-[1] АНАЛИЗ ──── агент analyst
-     │           Читает документацию, критерии, ПМИ
+[0] CHECKPOINT ─── проверить checkpoint.yml
+     │              Если active → предложить восстановление
+     │              Обновить: active=true, task_id, started_at
+     │              ✎ checkpoint
      ▼
-[2] DISCOVERY ── если есть неясности
-     │           Задаёт вопросы, фиксирует решения
+[1] АНАЛИЗ ─────── Agent(analyst)
+     │              → JSON с verdict COMPLETE/NEEDS_DISCOVERY
+     │              Gate: NEEDS_DISCOVERY → discovery → retry
+     │              ✎ checkpoint: steps.analysis = {status, verdict, key_findings}
      ▼
-[3] ПЛАН ────── агент architect (для новых модулей)
-     │           Предлагает структуру, API, схемы
+[2] АРХИТЕКТУРА ── Параллельно:
+     │              Agent(architect) → план
+     │              Agent(reviewer, mode: plan_review) → второе мнение
+     │              Gate: оба READY/APPROVE → next
+     │              Gate: конфликт → architect исправляет → retry
+     │              Пользователь подтверждает план
+     │              ✎ checkpoint: steps.architecture = {status, plan_summary, files}
      ▼
-[4] КОД ─────── агент developer
-     │           Пишет код по плану
+[3] REALITY CHECK ─ Agent(skeptic) → mirage detection
+     │              Gate: PASS → next
+     │              Gate: PASS_WITH_WARNINGS → developer получит warnings
+     │              Gate: FAIL → вернуть architect
+     │              ✎ checkpoint: steps.skeptic = {status, verdict, warnings}
      ▼
-[5] ТЕСТЫ ───── агент unit-tester
-     │           Покрытие ≥80%, запуск <%= testCommand %>
+[4] TDD + КОД + ТЕСТЫ ── per-feature цикл:
+     │
+     │   Для каждой фичи в плане architect:
+     │   ┌─────────────────────────────────────────────┐
+     │   │ 4a. Agent(tester, mode: tdd) → failing tests│
+     │   │     по tdd_anchors из tasks.json             │
+     │   │ 4b. Agent(developer) → реализация            │
+     │   │ 4c. Agent(tester, level: unit) → GREEN check │
+     │   │     + edge cases сверх якорей               │
+     │   │ 4d. Agent(inspector) → качество тестов       │
+     │   │     Gate: REQUEST_CHANGES → tester fixes     │
+     │   └─────────────────────────────────────────────┘
+     │   Порядок фич — по зависимостям из плана architect
+     │   Покрытие ≥80% на выходе из цикла
+     │   ✎ checkpoint: steps.developer = {status, files_changed, files_remaining}
      ▼
-[6] РЕВЬЮ ───── агент reviewer
-     │           Безопасность, качество, соответствие
+[5] РЕВЬЮ ─────── Agent(reviewer, max 3 rounds)
+     │              + проверка контроля доступа (check_security: true)
+     │              Gate: APPROVE → next
+     │              Gate: REQUEST_CHANGES → developer fixes → re-review
+     │              Gate: ESCALATE (round 3) → пользователь решает
+     │              ✎ checkpoint: steps.review = {status, round, findings_count}
      ▼
-[7] ФИКСАЦИЯ ── обновить tasks.json, progress.md
-                 Предложить коммит
+[6] TECH-DEBT ──── Team Lead проверяет 3 источника:
+     │              1. Reviewer findings (MEDIUM/LOW не исправленные)
+     │              2. Implementation deviations (mock, simplified, workaround)
+     │              3. Skeptic warnings (не адресованные в коде)
+     │              Если найдено → TD-NNN в tech-debt.md
+     │              Если нет → tech_debt: none в checkpoint
      ▼
-[8] TECH-DEBT ── проверить отклонения от целевой реализации
-                 Зафиксировать в tech-debt.md
+[7] ФИКСАЦИЯ ──── tasks.json(done), progress.md, active-context.md
+                   checkpoint.yml(active: false)
+                   Предложить коммит
+```
+
+## Checkpoint
+
+Файл `dev-infra/memory/checkpoint.yml` обновляется после КАЖДОГО шага (символ ✎).
+
+Формат checkpoint:
+```yaml
+active: true
+task_id: TASK-XXX
+task_title: Название
+feature_size: S|M|L
+current_step: analysis|architecture|skeptic|developer|review|tech_debt|finalize
+started_at: ISO-8601
+steps:
+  analysis: {status: done, verdict: COMPLETE}
+  architecture: {status: done, plan_summary: "...", files: [...]}
+  skeptic: {status: done, verdict: PASS_WITH_WARNINGS, warnings: [...]}
+  developer: {status: in_progress, files_changed: [...], features_done: 2, features_total: 4}
+  review: {status: pending}
+  tech_debt: {status: pending}
 ```
 
-## Когда пропускать шаги
+## Таблица пропуска шагов
+
+| Размер | Выполняются | Пропускаются |
+|--------|------------|--------------|
+| **S (6)** | [0] checkpoint, [1] код, [2] тесты+inspector, [3] quick-review, [4] tech-debt, [5] фиксация | анализ, архитектура, skeptic |
+| **M (8)** | [0] checkpoint, [1] анализ, [2] TDD(RED), [3] код+тесты+inspector, [4] ревью(full), [5] tech-debt, [6] фиксация | архитектура параллельная, skeptic |
+| **L (10)** | ВСЕ шаги | Ничего |
+
+Шаг 0 (checkpoint) и tech-debt выполняются ВСЕГДА.
+
+## Per-feature loop
+
+Формализованный цикл для шага «Код + Тесты»:
+
+1. Architect предоставляет список фич с порядком (по зависимостям)
+2. Для каждой фичи выполняется полный мини-цикл: tdd(RED) → developer → tester(GREEN) → inspector
+3. При FAIL на любом этапе — откат к developer для исправления
+4. Переход к следующей фиче только после APPROVE от inspector
+5. Checkpoint обновляется после каждой фичи: features_done + 1
+
+## Wave-execution (для milestone)
+
+При `/feature [milestone] --wave N`:
 
-| Тип задачи | Пропустить |
-|------------|-----------|
-| Анализ / изучение | шаги 3-6 (нет кода) |
-| Мелкий фикс | шаг 3 (нет нового модуля) |
-| Тестирование | шаги 3-4 (нет нового кода) |
-| Документация | шаги 3-6 |
-| Новый модуль | выполнить ВСЕ шаги |
+1. Из tasks.json выбираются задачи для wave N (поле `wave` в задаче)
+2. Задачи выполняются последовательно через /take-task pipeline
+3. Между задачами обновляется checkpoint
+4. После волны: smoke test (<%= testCommand %>), обновление прогресса, коммит
 
-## Discovery-интервью
+Волны определяются при планировании (/plan init):
+- Wave 1 — задачи без зависимостей
+- Wave 2 — зависят от Wave 1
+- Wave 3 — полировка, документация, tech-debt
 
-Если требование неясно — **не додумывай**:
+## Integration тесты
+
+tester(integration) вызывается в /audit-wave перед сдачей milestone. Не в каждой задаче.
+
+## Фазовый подход для milestone
+
+Перед стартом нового milestone — discuss phase:
+1. Обсудить scope, приоритеты, зависимости
+2. Зафиксировать решения в decisions.md
+3. Разбить на волны через /plan init (поле wave в задачах)
+
+## Discovery
+
+Если требование неясно:
 1. Сформулируй конкретный вопрос
 2. Покажи варианты решения с trade-offs
 3. Дождись ответа
-4. Зафиксируй в `dev-infra/memory/decisions.md`
+4. Зафиксируй в `dev-infra/memory/decisions.md` (формат ADR)
+
+## Связь с артефактами
+
+Перед началом задачи загрузить:
+- tasks.json → описание, acceptance_criteria (с метриками!), pmi_scenarios, risks, tdd_anchors
+- dev-infra/tests/acceptance/ → конкретные метрики
+- dev-infra/tests/pmi/ → процедуры тестирования
+
+Reviewer получает AC с полными метриками (не только ID).

package/templates/rules/quality-gates.md.ejs

@@ -0,0 +1,80 @@
+# Quality Gates — ворота пайплайна
+
+Формальные правила маршрутизации между этапами разработки. Team Lead проверяет verdict каждого агента и направляет пайплайн по соответствующему пути.
+
+## Матрица маршрутизации
+
+### Анализ -> Архитектура
+
+| Verdict analyst | Действие |
+|-----------------|----------|
+| COMPLETE | Передать результат architect |
+| NEEDS_DISCOVERY | Показать вопросы пользователю -> дождаться ответа -> зафиксировать в decisions.md -> повторить analyst |
+
+### Архитектура -> Reality Check
+
+Параллельно запускаются architect и reviewer(plan_review). Решение принимается по комбинации:
+
+| architect | reviewer(plan) | Действие |
+|-----------|---------------|----------|
+| READY | APPROVE | Передать skeptic |
+| READY | REQUEST_CHANGES | architect исправляет по замечаниям -> повторить оба |
+| NEEDS_INPUT | любой | Запросить данные у пользователя -> повторить architect |
+
+Конфликт architect vs reviewer: если architect считает план готовым, но reviewer видит проблемы — приоритет у reviewer. Пользователь подтверждает финальный план.
+
+### Reality Check -> Код
+
+| Verdict skeptic | Действие |
+|-----------------|----------|
+| PASS | Передать developer |
+| PASS_WITH_WARNINGS | Передать developer, включить warnings в prompt |
+| FAIL | Вернуть architect для исправления -> повторить skeptic |
+
+### Код -> Тесты -> Inspector
+
+Per-feature цикл:
+
+| Этап | Verdict | Действие |
+|------|---------|----------|
+| developer | DONE | Передать tester |
+| developer | BLOCKED | Разобрать блокировку с пользователем |
+| tester | PASS (>=80%) | Передать inspector |
+| tester | FAIL | Передать developer для исправления -> повторить tester |
+| inspector | APPROVE | Перейти к следующей фиче или к ревью |
+| inspector | REQUEST_CHANGES | Передать tester для исправления тестов -> повторить inspector |
+
+### Ревью -> Финализация
+
+| Verdict reviewer | Раунд | Действие |
+|------------------|-------|----------|
+| APPROVE | любой | Перейти к tech-debt |
+| REQUEST_CHANGES | 1-2 | developer исправляет -> reviewer повторяет (раунд N+1) |
+| REQUEST_CHANGES | 3 | Эскалация — ESCALATE |
+| ESCALATE | 3 | Показать пользователю все findings |
+
+### Эскалация (Escalation Protocol)
+
+После 3 раундов ревью с неразрешёнными CRITICAL:
+
+1. Team Lead показывает пользователю все нерешённые findings
+2. Пользователь выбирает:
+   - **(a) Принять как tech-debt** — записать TD-NNN, продолжить
+   - **(b) Исправить вручную** — пользователь правит, повторить ревью
+   - **(c) Отменить задачу** — rollback по rollback-protocol.md
+3. Решение фиксируется в `dev-infra/memory/decisions.md` (формат ADR)
+
+## Quick Review (S-задачи)
+
+S-задачи проходят облегчённое ревью (mode: quick):
+- 1 раунд (без повторов)
+- Проверяется только: security, контроль доступа, критические баги
+- MEDIUM/LOW не блокируют, идут в tech-debt
+- APPROVE / REQUEST_CHANGES (только для CRITICAL)
+
+## Правила
+
+1. Каждый verdict обрабатывается — нет «проигнорировать и продолжить»
+2. Максимум 3 retry на любом этапе (кроме discovery — без лимита)
+3. При сбое агента (garbage output) — 1 retry с уточнённым prompt, затем эскалация
+4. Checkpoint обновляется после каждого gate

package/templates/rules/rollback-protocol.md.ejs

@@ -0,0 +1,60 @@
+# Rollback Protocol — процедура отката
+
+## При ошибке агента
+
+| Тип ошибки | Действие |
+|------------|----------|
+| Compilation error | developer retry с конкретной ошибкой в prompt |
+| Tests crash (не FAIL, а crash) | tester диагностирует -> developer исправляет |
+| Agent returns garbage | 1 retry с уточнённым prompt -> при повторе — эскалация |
+| Agent timeout | Retry с меньшим scope (разбить задачу) |
+| Repeated failure (3+) | Остановить пайплайн, показать пользователю, спросить |
+
+## При отмене задачи mid-pipeline
+
+1. Проверить uncommitted changes: `git status`
+2. Если есть изменения — `git stash` с описательным сообщением:
+   ```
+   git stash push -m "WIP: [task_id] — отмена на шаге [step]"
+   ```
+3. Обновить checkpoint:
+   ```yaml
+   active: false
+   status: aborted
+   abort_reason: "причина"
+   stash_ref: "stash@{0}"  # если был stash
+   ```
+4. Обновить tasks.json: status -> `todo` (не оставлять `in_progress`)
+5. Обновить active-context.md: убрать текущую задачу
+6. Уведомить пользователя о результате отката
+
+## При восстановлении после отмены
+
+1. Прочитать checkpoint — найти abort_reason и stash_ref
+2. Предложить пользователю:
+   - **(a) Восстановить** — `git stash pop`, продолжить с checkpoint
+   - **(b) Отбросить** — `git stash drop`, начать задачу заново
+   - **(c) Отложить** — оставить stash, взять другую задачу
+
+## Decision Tree
+
+```
+Ошибка возникла?
+|-- Агент вернул ошибку
+|   |-- Понятная ошибка (compilation, test fail)
+|   |   '-- Передать ошибку developer/tester -> retry
+|   '-- Непонятная ошибка (garbage, timeout)
+|       |-- Retry #1 с уточнённым prompt
+|       '-- Retry failed -> показать пользователю
+|-- Пользователь отменил задачу
+|   '-- Stash -> checkpoint(aborted) -> tasks(todo)
+'-- Сессия оборвалась (crash, disconnect)
+    '-- Checkpoint сохраняет состояние -> при /take-task предложит восстановление
+```
+
+## Правила
+
+1. Никогда не использовать `git reset --hard` без явного запроса пользователя
+2. Всегда использовать `git stash` вместо отбрасывания изменений
+3. Checkpoint обновляется до операции отката (чтобы можно было восстановиться)
+4. Stash-сообщения всегда содержат task_id для трассировки

package/templates/rules/shared-resources.md.ejs

@@ -0,0 +1,73 @@
+# Shared Resources — реестр singleton-ресурсов
+
+## Правило
+
+Singleton-ресурсы (подключения к БД, клиенты API, логгеры, кэши) создаются ОДИН раз и переиспользуются. Дублирование singleton — баг.
+
+## Реестр
+
+| Ресурс | Файл | Тип | Описание |
+|--------|------|-----|----------|
+| _пока ресурсов нет_ | | | |
+
+## Правила создания
+
+1. **Проверь реестр** — возможно, ресурс уже существует
+2. **Создай в одном месте** — singleton factory в выделенном файле
+3. **Добавь в реестр** — обнови таблицу выше
+4. **Не создавай дубликатов** — если ресурс есть, используй существующий
+
+## Паттерн
+
+<% if (stack === 'typescript') { %>
+```typescript
+// <%= srcDir %>lib/database.ts — singleton
+let instance: Database | null = null;
+
+export function getDatabase(): Database {
+  if (!instance) {
+    instance = new Database(process.env.DATABASE_URL);
+  }
+  return instance;
+}
+```
+<% } else if (stack === 'python') { %>
+```python
+# <%= srcDir %>lib/database.py — singleton
+_instance: Database | None = None
+
+def get_database() -> Database:
+    global _instance
+    if _instance is None:
+        _instance = Database(os.environ["DATABASE_URL"])
+    return _instance
+```
+<% } else if (stack === 'go') { %>
+```go
+// <%= srcDir %>lib/database.go — singleton
+var (
+    dbOnce sync.Once
+    dbInstance *Database
+)
+
+func GetDatabase() *Database {
+    dbOnce.Do(func() {
+        dbInstance = NewDatabase(os.Getenv("DATABASE_URL"))
+    })
+    return dbInstance
+}
+```
+<% } else { %>
+```
+// Singleton pattern: создай ресурс один раз, используй везде
+```
+<% } %>
+
+## Антипаттерн
+
+```
+// НЕ ДЕЛАЙ ТАК — создание нового подключения в каждом обработчике
+function handleRequest() {
+  const db = new Database(url); // каждый запрос — новое подключение!
+}
+```

package/templates/skills/core/code/SKILL.md.ejs

@@ -0,0 +1,85 @@
+---
+name: code
+description: |
+  Ad-hoc написание кода без полного пайплайна спецификаций.
+  Plan -> Tests -> Code -> Review.
+
+  Use when: «напиши код», «write code», «code», «закодь», «реализуй»
+user-invocable: true
+argument-hint: "[description]"
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent
+---
+
+# Ad-hoc код
+
+Аргумент: `$ARGUMENTS` — описание того, что нужно написать.
+
+## Фаза 1. Быстрый план
+
+На основе описания:
+1. Определи файлы для создания/изменения
+2. Определи подход (новый модуль, расширение существующего, фикс)
+3. Покажи пользователю:
+
+```
+## План
+- Файлы: [список]
+- Подход: [описание]
+- Тесты: [что покрыть]
+```
+
+Спроси: «Выполнить?»
+
+**Checkpoint:** план утверждён.
+
+## Фаза 2. Тесты (TDD, если применимо)
+
+Если задача нетривиальная (>1 функция):
+
+```
+Agent(subagent_type="tester", prompt="
+mode: tdd
+Создай failing тесты для: [описание].
+Файлы: [expected test files].
+Директория тестов: <%= testDir %>
+Фреймворк: <%= testFramework %>
+")
+```
+
+**Checkpoint:** тесты написаны.
+
+## Фаза 3. Код
+
+```
+Agent(subagent_type="developer", prompt="
+Реализуй: [описание].
+План: [план из фазы 1].
+Failing тесты: [если есть].
+Сделай тесты GREEN.
+Запусти: <%= testCommand %>
+")
+```
+
+**Checkpoint:** код написан.
+
+## Фаза 4. Quick Review
+
+```
+Agent(subagent_type="reviewer", prompt="
+mode: quick
+Проверь: [файлы от developer].
+Security, контроль доступа, критические баги.
+")
+```
+
+**Checkpoint:** ревью пройдено.
+
+## Фаза 5. Итог
+
+Покажи: файлы, тесты, ревью. Предложи коммит.
+
+## Final Check
+
+- [ ] Код написан
+- [ ] Тесты проходят
+- [ ] Quick review пройден

package/templates/skills/core/complete-task/SKILL.md.ejs

@@ -1,6 +1,6 @@
 ---
 name: complete-task
-description: Завершить задачу. Проверяет тесты, обновляет прогресс, предлагает следующую.
+description: Завершить задачу. Проверяет тесты, smoke verification, обновляет прогресс, очищает checkpoint.
 user-invocable: true
 disable-model-invocation: false
 argument-hint: "[task-id]"
@@ -14,24 +14,37 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 ## 1. Определить задачу
 - Из аргумента или найти in_progress задачу в tasks.json
 
-## 2. Проверить готовность
+## 2. Smoke verification
+- Запусти полный набор тестов: `<%= testCommand %>`
+- Если тесты падают — **не завершай задачу**, сообщи пользователю
+
+## 3. Проверить готовность
 - **Тесты написаны?** Ищи тесты в `<%= testDir %>`
-- **Тесты проходят?** Запусти `<%= testCommand %>`
+- **Тесты проходят?** Результат из шага 2
 - **Критерии приёмки?** Проверь выполнение
 
-## 3. Проверить технический долг
+## 4. Проверить технический долг (ОБЯЗАТЕЛЕН для всех размеров — S/M/L)
 - Mock-данные вместо реальных?
 - Упрощённая логика?
 - Workaround?
 
 Если да — добавь запись в `dev-infra/memory/tech-debt.md`.
 
-## 4. Обновить систему
-```
-Agent(subagent_type="progress-tracker", prompt="Задача [ID] завершена. Обнови tasks.json, progress.md, active-context.md.")
+## 5. Обновить систему
+
+Team Lead обновляет напрямую:
+1. `dev-infra/tasks/tasks.json` — статус задачи → `done`, updated → сегодня
+2. `dev-infra/memory/progress.md` — пересчитать прогресс по milestone
+3. `dev-infra/memory/active-context.md` — обновить текущий контекст
+
+## 6. Очистить checkpoint
+
+Обнови `dev-infra/memory/checkpoint.yml`:
+```yaml
+active: false
 ```
 
-## 5. Предложить следующую задачу
+## 7. Предложить следующую задачу
 - По приоритету и зависимостям
 
-## 6. Предложить коммит
+## 8. Предложить коммит

package/templates/skills/core/done/SKILL.md.ejs

@@ -0,0 +1,66 @@
+---
+name: done
+description: |
+  Финализация фичи: обновление документации, архивация, коммит.
+
+  Use when: «фича готова», «finalize», «done», «завершить фичу», «финализируй фичу»
+user-invocable: true
+argument-hint: "[feature-name or milestone]"
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent
+---
+
+# Финализация фичи
+
+Аргумент: `$ARGUMENTS` — название фичи или milestone.
+
+## Фаза 1. Проверка состояния
+
+1. Прочитай tasks.json — все задачи фичи в статусе done?
+2. Прочитай progress.md — прогресс актуален?
+3. Прочитай tech-debt.md — есть ли незакрытый TD?
+
+Если есть незавершённые задачи — показать список, спросить.
+
+**Checkpoint:** состояние проверено.
+
+## Фаза 2. Документация
+
+```
+Agent(subagent_type="librarian", prompt="
+Проверь документацию для [фича/milestone]:
+- Memory bank актуален?
+- Progress обновлён?
+- Active-context актуален?
+- Нет устаревших ссылок?
+")
+```
+
+Если OUTDATED — обновить необходимые файлы.
+
+**Checkpoint:** документация проверена.
+
+## Фаза 3. Обновление PK Files
+
+Обнови:
+- `dev-infra/memory/progress.md` — итоговый прогресс
+- `dev-infra/memory/active-context.md` — убрать завершённые задачи
+- `dev-infra/memory/tech-debt.md` — закрыть resolved TD
+
+## Фаза 4. Завершение
+
+```
+## Фича [название] финализирована
+
+- Задач завершено: N
+- Tech-debt: K open, M resolved
+- Документация: актуальна
+```
+
+Предложи коммит.
+
+## Final Check
+
+- [ ] Все задачи done
+- [ ] Документация актуальна
+- [ ] PK files обновлены
+- [ ] Коммит предложен