@k0t0vich/meta-agents-template

v0.1.12

Published

a month ago

Template system for verification-first agentic development

Downloads

134

0High
0Medium
0Low

k0t0vich

agents template workflow prd verification

Meta Agents Template (RU)

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

Что получает пользователь после установки

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

Установка (надёжно из любой папки)

Если целевая папка пустая или в ней нет package.json, сначала зафиксируй локальный npm-проект:

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, если его нет локально):

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:

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

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

(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`

Во время инициализации система задаёт обязательные вопросы:

Как настраивать Git: github, local или skip.
Нужно ли сразу создать GitHub-репозиторий.
Какой трекер использовать по умолчанию: github, mcp, local, custom.

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

Структура проекта после `init`

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-пакета.

Канонические команды

VERIFY_GOVERNANCE_GATE
CREATE_TASK
PREPARE_TASK_BRANCH
SET_STATUS
VERIFY_IMPLEMENTATION_GATE
RUN_REVIEW_GATE
COMMIT_BY_NAME
RUN_MR_REVIEW_GATE
ASSIGN_SPRINT
PREPARE_RELEASE_NOTE
MARK_TASKS_PUBLISH
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 (для этого репозитория)

Чтобы сам шаблон работал по своим же правилам, запусти:

npm run self:bootstrap

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

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

Жёсткие критерии приёмки

Задача принимается только если одновременно выполнены все условия:

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

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

Локальная проверка governance

В сгенерированном проекте доступна команда:

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 и отдельную ветку.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme