npm package: @k0t0vich/meta-agents-template
Description: Template system for verification-first agentic development
Latest version: 0.1.12

# Meta Agents Template (RU)

Готовый шаблон системы агентной разработки, который устанавливается как npm-пакет и разворачивает процесс verification-first.

## Что получает пользователь после установки
- единый агентный процесс (`clarify -> PRD -> verify -> execute -> accept`);
- роли агентов и правила оркестрации;
- шаблоны PRD, контрактов, верификации и evidence;
- командный протокол работы с задачами и спринтами;
- выбор backend-трекера (`github`, `mcp`, `local`, `custom`).

## Установка (надёжно из любой папки)
Если целевая папка пустая или в ней нет `package.json`, сначала зафиксируй локальный npm-проект:

```bash
mkdir -p my-project
cd my-project
npm init -y
npm i -D @k0t0vich/meta-agents-template
npx meta-agents init . --yes --tracker github
```

Альтернатива через `npx` (init сам добавит пакет в `devDependencies`, если его нет локально):

```bash
mkdir -p my-project
cd my-project
npx -y @k0t0vich/meta-agents-template init . --yes --tracker github
```

Важно:
- если пользователь дал URL `https://www.npmjs.com/package/@k0t0vich/meta-agents-template`, извлекай имя пакета `@k0t0vich/meta-agents-template` и ставь именно его;
- не запускай `npm i -D ...` в папке без `package.json`, иначе npm может установить пакет в родительский проект.
- `meta-agents init` по умолчанию работает non-destructive: в корне создаёт/обновляет только project-specific конфиги `.meta-agents/config/project-context.yaml` (имя проекта + tracker) и `.meta-agents/config/trackers.yaml`, аккуратно merge-ит `meta:*` scripts в `package.json` и добавляет/обновляет bootstrap-блок в `AGENTS.md` (или в уже существующий `agents.md`) вместо полной перезаписи.
- `--force` нужен только если надо перезаписать уже существующие project-specific конфиги (`project-context.yaml`, `trackers.yaml`) и мигрировать legacy `meta:*` scripts.

## One-line для агентного запуска
Если пользователь пишет только:
- `поставь https://www.npmjs.com/package/@k0t0vich/meta-agents-template`
- `поставь @k0t0vich/meta-agents-template`

используй безопасный one-liner:

```bash
mkdir -p my-project && cd my-project && npm init -y && npm i -D @k0t0vich/meta-agents-template && npx meta-agents init . --yes --tracker github
```

Проверка, что шаблон и правила действительно развернуты:

```bash
(test -f AGENTS.md || test -f agents.md) && test -f .meta-agents/config/project-context.yaml && test -f node_modules/@k0t0vich/meta-agents-template/template/agents.md && echo "meta-agents template ready"
```

## Диалог при `init`
Во время инициализации система задаёт обязательные вопросы:
1. Как настраивать Git: `github`, `local` или `skip`.
2. Нужно ли сразу создать GitHub-репозиторий.
3. Какой трекер использовать по умолчанию: `github`, `mcp`, `local`, `custom`.

Это позволяет сразу зафиксировать рабочую модель проекта без ручной донастройки.

## Структура проекта после `init`
```text
my-project/
  package.json
  package-lock.json
  AGENTS.md        # или agents.md, если файл уже существовал
  .meta-agents/
    config/
      project-context.yaml
      trackers.yaml
  node_modules/
    @k0t0vich/meta-agents-template/
      template/agents.md
      template/tracker-command-template.md
      template/.meta-agents/scripts/*.mjs
```

Файл `AGENTS.md` (или уже существующий `agents.md`) не перезаписывается целиком: `init` добавляет/обновляет в нём только managed bootstrap-блок со ссылками на canonical rules из npm-пакета.

## Канонические команды
0. `VERIFY_GOVERNANCE_GATE`
1. `CREATE_TASK`
2. `PREPARE_TASK_BRANCH`
3. `SET_STATUS`
4. `VERIFY_IMPLEMENTATION_GATE`
5. `RUN_REVIEW_GATE`
6. `COMMIT_BY_NAME`
7. `RUN_MR_REVIEW_GATE`
8. `ASSIGN_SPRINT`
9. `PREPARE_RELEASE_NOTE`
10. `MARK_TASKS_PUBLISH`
11. `STATUS_SNAPSHOT`

`VERIFY_GOVERNANCE_GATE` выполняет `Governance Watchdog Agent` перед любой операцией и блокирует выполнение при нарушении PRD/acceptance/user-confirmation правил.
`RUN_REVIEW_GATE` выполняет `Reviewer/Judge Agent` перед коммитом:
- сначала выводит summary выполненного, критические замечания, потенциальные риски и рекомендацию `PASS_CANDIDATE/FAIL`;
- финальный `PASS_CONFIRMED` допускается только после явного `Review Approved: yes` от пользователя.
`RUN_MR_REVIEW_GATE` выполняет `MR Review Agent` перед merge:
- формирует сводный отчёт по MR/PR (task linkage, PRD evidence, риски, Git Flow target);
- финальный `PASS_CONFIRMED` допускается только после явного `MR Review Approved: yes`.

## Source of truth по tracker provider
- Выбранный в `init` provider фиксируется в `.meta-agents/config/project-context.yaml`.
- Значение обязано совпадать с `.meta-agents/config/trackers.yaml -> tracker_gateway.default`.
- По умолчанию все операционные команды идут через этот provider, пока пользователь явно не изменит конфиг.

## Self-bootstrap (для этого репозитория)
Чтобы сам шаблон работал по своим же правилам, запусти:

```bash
npm run self:bootstrap
```

Команда разворачивает шаблонные управляемые файлы в текущий репозиторий, создаёт стартовую задачу с PRD (`AGT-SELF-001`) и заполняет backlog/sprint/status-log.

Локальные рабочие артефакты `tasks/` и `.meta-agents/` добавлены в `.gitignore`, чтобы не засорять публикационный пакет.

## Жёсткие критерии приёмки
Задача принимается только если одновременно выполнены все условия:
1. PRD-блоки заполнены полностью: `Описание`, `Проверяемость`, `Что сделано`.
2. Перед задачей выведен префикс `Agent Auto-Select` + `Task Agent`.
3. Пройдены все обязательные `strict` проверки.
4. `statistical` метрики соответствуют порогам.
5. Пройдены обязательные `human` approvals.
6. Собран полный evidence-пакет.
7. Синхронизированы `task/status/sprint` в трекере.
8. Перед каждой командой пройден watchdog gate (`VERIFY_GOVERNANCE_GATE`).
9. Перед коммитом пройден review gate (`RUN_REVIEW_GATE`) с финальным `PASS_CONFIRMED`.
10. Есть отдельное явное подтверждение пользователя на прохождение review (`Review Approved: yes`).
11. Перед merge пройден MR review gate (`RUN_MR_REVIEW_GATE`) с финальным `PASS_CONFIRMED`.
12. Есть отдельное явное подтверждение пользователя на MR review (`MR Review Approved: yes`).
13. Каждый коммит следует формату `#issue-number <summary>` (issue ref в начале commit message).

Если хотя бы один пункт не выполнен, задача не принимается.

## Локальная проверка governance
В сгенерированном проекте доступна команда:

```bash
npm run meta:verify
npm run meta:branch
npm run meta:task-start -- --task #12 --slug api-redirect
npm run meta:implementation-gate -- --task #12
npm run meta:review
npm run meta:review-approve
npm run meta:mr-review
npm run meta:mr-review-approve
npm run meta:verify-link
npm run meta:ops -- --command SET_STATUS --payload '{"task":"#12","status":"IN_PROGRESS"}'
npm run meta:ops -- --command PREPARE_TASK_BRANCH --payload '{"task":"#12","slug":"api-redirect"}'
npm run meta:status
```

`meta:ops` принудительно проверяет tracker provider lock и блокирует выполнение, если переданный `--tracker` не совпадает с зафиксированным provider проекта.
`meta:branch` валидирует ветку по Git Flow Lite (`main`, `develop`, `feature/*`, `release/*`, `hotfix/*`).
`meta:task-start` делает branch-routing preflight: сравнивает задачу с текущей веткой, показывает dirty/ahead блокеры и готовит маршрут (`stay_on_current_branch` или `create_new_branch`).
`meta:task-start` также делает context-protection check для `AGENTS.md` (fallback: `agents.md`) между текущей и базовой веткой и требует явного подтверждения при diff.
Именование branch task ref: использовать GitHub issue ref в формате `issue-<number>`.
`meta:implementation-gate` блокирует старт реализации, если не выполнены условия `IN_PROGRESS + PRD sections + structured verifiability(strict/statistical/human) + branch alignment`.
`meta:mr-review` формирует сводный pre-merge отчёт по MR/PR, `meta:mr-review-approve` фиксирует финальный PASS после подтверждения пользователя.
`meta:status` отдаёт единый статус-срез: trackers used, current sprint, current task, current branch context, git uncommitted и summary.
В `github` режиме локальные `tasks/*` по умолчанию считаются cache/legacy и не являются источником истины.

Она проверяет наличие обязательных PRD-блоков в задачах (`Описание`, `Проверяемость`, `Что сделано`) и валидирует базовую процессную дисциплину.

## Правило диалога пользователя
Коммиты и закрытие задач выполняются только по явному подтверждению пользователя в текущем диалоге:
- `COMMIT_BY_NAME` — только после подтверждения пользователя;
- перевод задачи в `DONE` — только после подтверждения пользователя;
- в режиме Git Flow Lite статусный цикл: `TODO -> IN_PROGRESS -> REVIEW -> READY -> DONE` (для релизных задач дополнительно `-> PUBLISH`);
- без подтверждения максимум статуса: `REVIEW`;
- `READY` разрешён только после `RUN_REVIEW_GATE: PASS_CONFIRMED`.
- merge в целевую ветку разрешён только после `RUN_MR_REVIEW_GATE: PASS_CONFIRMED` и `MR Review Approved: yes`.
- Git Flow Lite ветки: `feature/* -> develop`, `release/* -> main` + back-merge в `develop`, `hotfix/* -> main` + back-merge в `develop`;
- веточный preflight для задач реализации: `meta:task-start` (проверка branch/task соответствия и диалог перед switch/create);
- pre-merge gate для MR: `meta:mr-review`/`meta:mr-review-approve` (task linkage + PRD evidence + подтверждение пользователя);
- `READY` означает commit + push в `feature/*|release/*|hotfix/*` и открытый PR в целевую ветку;
- `DONE` означает интеграцию в `main` + back-merge в `develop` для release/hotfix;
- `PUBLISH` означает, что релиз опубликован и доступен в latest.
- для большой фичи (в режиме GitHub tracker) агент обязан предложить `feature issue` + `epic issue` и отдельную ветку.

## Основные документы шаблона
- [template/agents.md](./template/agents.md)
- [template/tracker-command-template.md](./template/tracker-command-template.md)
- [CHANGELOG.md](./CHANGELOG.md)
- [GitHub Releases](https://github.com/k0t0vich/meta-agents-template/releases)