@k0t0vich/meta-agents-template 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# Meta Agents Template (RU)
+
+Готовый шаблон системы агентной разработки, который устанавливается как npm-пакет и разворачивает процесс verification-first.
+
+## Что получает пользователь после установки
+- единый агентный процесс (`clarify -> PRD -> verify -> execute -> accept`);
+- роли агентов и правила оркестрации;
+- шаблоны PRD, контрактов, верификации и evidence;
+- командный протокол работы с задачами и спринтами;
+- выбор backend-трекера (`github`, `mcp`, `local`, `custom`).
+
+## Установка
+```bash
+npm i -D @k0t0vich/meta-agents-template
+npx meta-agents init my-project
+```
+
+или
+
+```bash
+npm i -D git+https://github.com/k0t0vich/meta-agents-template.git
+npx meta-agents init my-project
+```
+
+## Диалог при `init`
+Во время инициализации система задаёт обязательные вопросы:
+1. Как настраивать Git: `github`, `local` или `skip`.
+2. Нужно ли сразу создать GitHub-репозиторий.
+3. Какой трекер использовать по умолчанию: `github`, `mcp`, `local`, `custom`.
+
+Это позволяет сразу зафиксировать рабочую модель проекта без ручной донастройки.
+
+## Структура проекта после `init`
+```text
+my-project/
+  package.json
+  README.md
+  agents.md
+  tracker-command-template.md
+  .meta-agents/
+    config/
+      system.yaml
+      roles.yaml
+      trackers.yaml
+    templates/
+      prd-step.md
+      agent-work-contract.md
+      verification-plan.md
+      evidence-pack.md
+      sprint-template.md
+      task-template.md
+    prompts/
+      clarifier.md
+      architect.md
+      verifier-designer.md
+      decomposer.md
+      reviewer-judge.md
+      agile-manager.md
+    scripts/
+      init.mjs
+      sync-status.mjs
+      generate-prd-step.mjs
+      tracker/
+        local.mjs
+        github.mjs
+        mcp.mjs
+        custom.mjs
+  tasks/
+    backlog.md
+    sprint-1.md
+    task-status-log.md
+```
+
+## Канонические команды
+1. `CREATE_TASK`
+2. `SET_STATUS`
+3. `COMMIT_BY_NAME`
+4. `ASSIGN_SPRINT`
+
+## Жёсткие критерии приёмки
+Задача принимается только если одновременно выполнены все условия:
+1. PRD-блоки заполнены полностью: `Описание`, `Проверяемость`, `Что сделано`.
+2. Перед задачей выведен префикс `Agent Auto-Select` + `Task Agent`.
+3. Пройдены все обязательные `strict` проверки.
+4. `statistical` метрики соответствуют порогам.
+5. Пройдены обязательные `human` approvals.
+6. Собран полный evidence-пакет.
+7. Синхронизированы `task/status/sprint` в трекере.
+
+Если хотя бы один пункт не выполнен, задача не принимается.
+
+## Правило диалога пользователя
+Коммиты и закрытие задач выполняются только по явному подтверждению пользователя в текущем диалоге:
+- `COMMIT_BY_NAME` — только после подтверждения пользователя;
+- перевод задачи в `DONE` — только после подтверждения пользователя;
+- без подтверждения максимум статуса: `READY`.
+
+## Публикация через Trusted Publishing (рекомендуется)
+В репозитории настроен workflow:
+- [.github/workflows/publish.yml](./.github/workflows/publish.yml)
+- Подробный регламент публикации: [PUBLISHING.md](./PUBLISHING.md)
+
+Он публикует пакет по тегу `v*` или вручную через `workflow_dispatch` и использует OIDC (`id-token: write`) вместо long-lived npm токена.
+
+Что нужно сделать в npm UI (один раз):
+1. Открой `npmjs.com -> Packages -> @k0t0vich/meta-agents-template -> Settings -> Trusted publishing`.
+2. Добавь trusted publisher типа `GitHub Actions` с полями:
+  - Organization/User: `k0t0vich`
+  - Repository: `meta-agents-template`
+  - Workflow filename: `publish.yml`
+3. Сохрани настройки.
+
+Как выпускать релиз:
+```bash
+git tag v0.1.1
+git push origin v0.1.1
+```
+
+После этого GitHub Actions выполнит `npm publish --access public` автоматически.
+
+Примечание:
+- если Trusted Publisher ещё не настроен, публикация из workflow не пройдет;
+- для максимальной безопасности после включения trusted publishing рекомендуется запретить publish через токены в настройках пакета.
+
+## Основные документы шаблона
+- [agents.md](./agents.md)
+- [tracker-command-template.md](./tracker-command-template.md)

package/agents.md

@@ -0,0 +1,141 @@
+# agents.md
+
+## 1) Назначение системы
+Система работает как мета-оркестрация разработки: сначала формализуем задачу и проверяемость, потом делаем реализацию.
+
+Базовый поток:
+`clarify -> PRD step -> verification design -> decomposition -> execution -> evidence -> acceptance`
+
+Главный принцип:
+`acceptance-first` и `verification-first`.
+
+## 2) Обязательный PRD на каждом шаге
+Каждый этап (уточнение, архитектура, декомпозиция, реализация, ревью) обязан иметь PRD-запись в строгом порядке:
+
+1. `Описание`.
+2. `Проверяемость`.
+3. `Что сделано`.
+
+Правило запуска этапа:
+- если не заполнены `Описание` и `Проверяемость`, этап не стартует.
+
+## 3) Роли агентов
+- `Chief of Staff Agent`: оркестрация цепочки, приоритеты, блокеры, эскалации.
+- `Agile Manager Agent`: операции по задачам/спринтам/статусам/коммитам через трекер.
+- `Product Manager Agent`: формулирует PRD и критерии приёмки.
+- `Solution Architect Agent`: проектирует архитектуру и контракты компонентов.
+- `Verifier Designer Agent`: проектирует модель валидации и evidence-план.
+- `Decomposer Agent`: режет систему на проверяемые компоненты.
+- `Engineering Agent`: реализация по контракту.
+- `QA Agent`: проверка выполнения критериев и качество тестового покрытия.
+- `Reviewer/Judge Agent`: независимая приёмка по заранее согласованным правилам.
+- `Documentation Agent`: поддержка и синхронизация артефактов.
+
+## 4) Жёсткий Auto-Select и показ имени агента
+Автовыбор агента обязателен перед каждой задачей и перед каждой командой (`CREATE_TASK`, `SET_STATUS`, `COMMIT_BY_NAME`, `ASSIGN_SPRINT`).
+
+Обязательный префикс:
+```text
+[Agent Auto-Select]
+Selected: <agent role>
+Reason: <short reason>
+
+[Task Agent]
+Name: <agent role>
+```
+
+Правило исполнения:
+- если префикс не выведен, задача/команда не выполняется;
+- если пользователь явно указал роль, она используется, но блок `Task Agent` обязателен.
+
+## 5) Единица работы: Verified Component
+Каждый компонент обязан иметь:
+- цель;
+- входы/выходы;
+- ограничения и инварианты;
+- критерии приёмки;
+- стратегию проверки;
+- required evidence;
+- владельца компонента;
+- ссылку на PRD-этап.
+
+## 6) Типы валидации
+- `strict`: схемы, типы, правила, инварианты, policy, state transitions.
+- `statistical`: benchmark/метрики/judge score/пороговые значения.
+- `human`: review/approval в рискованных и неоднозначных точках.
+
+## 7) AgentWorkContract
+Перед передачей задачи Executor-агенту фиксируется контракт:
+- scope;
+- допустимая свобода решений;
+- required outputs;
+- required evidence;
+- acceptance criteria;
+- failure/escalation правила;
+- трекерная привязка (`task_id`, `tracker_provider`, `sprint`).
+
+Без контракта делегирование запрещено.
+
+## 8) TrackerGateway
+Трекер выделяется в отдельный адаптерный слой, независимый от ролей агентов.
+
+`TrackerGateway` поддерживает провайдеры:
+- `local`;
+- `github`;
+- `mcp` (alias `mpc`);
+- `custom`.
+
+Режим по умолчанию для командной работы: `github` (или другой внешний трекер). `local` используется как fallback.
+
+## 9) Канонические команды
+Все рабочие операции проходят через `Agile Manager Agent` + `TrackerGateway`.
+Операционные шаблоны команд: [tracker-command-template.md](./tracker-command-template.md).
+
+1. `CREATE_TASK`
+2. `SET_STATUS`
+3. `COMMIT_BY_NAME`
+4. `ASSIGN_SPRINT`
+
+## 10) Коммиты и закрытие задач: только по подтверждению пользователя
+Запрещено выполнять автоматически:
+- `COMMIT_BY_NAME`;
+- перевод задачи в `DONE`.
+
+Обязательное правило:
+- `COMMIT_BY_NAME` выполняется только после явного подтверждения пользователя в текущем диалоге;
+- `SET_STATUS -> DONE` выполняется только после явного подтверждения пользователя в текущем диалоге;
+- без подтверждения пользователя максимум допустимого статуса: `READY`.
+
+## 11) Жёсткие критерии приёмки (все обязательны)
+Задача принимается только если одновременно выполнены все условия:
+1. Заполнены все PRD-блоки этапа: `Описание`, `Проверяемость`, `Что сделано`.
+2. Выполнен обязательный префикс `Agent Auto-Select` + `Task Agent`.
+3. Пройдены все обязательные `strict` проверки.
+4. `statistical` метрики не ниже зафиксированных порогов.
+5. Пройдены обязательные `human` approvals.
+6. Собран полный evidence-пакет (артефакты, логи, ссылки на проверки).
+7. Синхронизированы `task/status/sprint` в трекере.
+8. Если был коммит, есть явное подтверждение пользователя на коммит.
+9. Если задача закрыта в `DONE`, есть явное подтверждение пользователя на закрытие.
+
+Если хотя бы один критерий не выполнен, задача не принимается.
+
+## 12) Verification-first gate
+Реализация не начинается, пока не определены:
+- acceptance criteria;
+- метрики и пороги;
+- инварианты и ограничения;
+- процедуры проверки;
+- зоны неопределённости и правила эскалации;
+- способ фиксации в трекере.
+
+## 13) Реакция на провал проверки
+Допустимые сценарии:
+- `retry` с корректировками;
+- пересмотр архитектуры;
+- уточнение критериев;
+- эскалация пользователю/founder;
+- возврат статуса задачи в `IN_PROGRESS` или `BLOCKED`.
+
+## 14) Главный инвариант
+Нельзя делегировать работу и нельзя закрывать задачу без формализованных критериев приёмки, PRD-блока `Проверяемость` и требуемых доказательств в трекере.

package/bin/meta-agents.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.mjs";
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(`meta-agents: ${error.message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@k0t0vich/meta-agents-template",
+  "version": "0.1.0",
+  "description": "Template system for verification-first agentic development",
+  "type": "module",
+  "bin": {
+    "meta-agents": "bin/meta-agents.js"
+  },
+  "scripts": {
+    "start": "node bin/meta-agents.js --help"
+  },
+  "files": [
+    "README.md",
+    "agents.md",
+    "tracker-command-template.md",
+    "bin",
+    "src",
+    "template"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/k0t0vich/meta-agents-template.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "agents",
+    "template",
+    "workflow",
+    "prd",
+    "verification"
+  ],
+  "license": "MIT"
+}

package/src/cli.mjs

@@ -0,0 +1,266 @@
+import path from "node:path";
+import process from "node:process";
+import readline from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { initProject } from "./init.mjs";
+import { syncTemplate } from "./sync.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const templateRoot = path.resolve(__dirname, "..", "template");
+
+function parseOptions(args) {
+  const options = {
+    force: false,
+    tracker: "github",
+    trackerProvided: false,
+    help: false,
+    yes: false,
+  };
+  const positional = [];
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (arg === "--force") {
+      options.force = true;
+      continue;
+    }
+    if (arg === "--yes") {
+      options.yes = true;
+      continue;
+    }
+    if (arg === "--tracker") {
+      const value = args[i + 1];
+      if (!value) {
+        throw new Error("missing value for --tracker");
+      }
+      options.tracker = value;
+      options.trackerProvided = true;
+      i += 1;
+      continue;
+    }
+    positional.push(arg);
+  }
+
+  return { options, positional };
+}
+
+function printHelp() {
+  const lines = [
+    "meta-agents CLI",
+    "",
+    "Usage:",
+    "  meta-agents init [project-dir] [--tracker github|mcp|local|custom] [--force] [--yes]",
+    "  meta-agents sync [project-dir] [--force]",
+    "  meta-agents upgrade [project-dir] [--force]",
+    "  meta-agents --help",
+    "",
+    "Commands:",
+    "  init     Initialize a project from template",
+    "  sync     Update managed template files in an existing project",
+    "  upgrade  Alias for sync",
+    "",
+    "Init dialog:",
+    "  By default, 'init' asks about Git mode and tracker provider.",
+    "  Use --yes to skip dialog and use defaults/flags.",
+  ];
+  console.log(lines.join("\n"));
+}
+
+function normalizeTracker(raw) {
+  if (raw === "mpc") {
+    return "mcp";
+  }
+  return raw;
+}
+
+function ensureTrackerSupported(tracker) {
+  const allowed = new Set(["github", "mcp", "local", "custom"]);
+  if (!allowed.has(tracker)) {
+    throw new Error(`unsupported tracker '${tracker}'. Allowed: github, mcp, local, custom`);
+  }
+}
+
+function ensureGitModeSupported(mode) {
+  const allowed = new Set(["github", "local", "skip"]);
+  if (!allowed.has(mode)) {
+    throw new Error(`unsupported git mode '${mode}'. Allowed: github, local, skip`);
+  }
+}
+
+function normalizeVisibility(raw) {
+  const value = raw.trim().toLowerCase();
+  if (value === "public" || value === "private") {
+    return value;
+  }
+  throw new Error("visibility must be 'public' or 'private'");
+}
+
+function parseYesNo(value, defaultValue) {
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) {
+    return defaultValue;
+  }
+  if (["y", "yes", "да", "д"].includes(normalized)) {
+    return true;
+  }
+  if (["n", "no", "нет", "н"].includes(normalized)) {
+    return false;
+  }
+  throw new Error("answer must be yes or no");
+}
+
+function defaultTrackerForGitMode(mode) {
+  if (mode === "github") {
+    return "github";
+  }
+  if (mode === "local") {
+    return "local";
+  }
+  return "github";
+}
+
+async function askWithDefault(rl, label, defaultValue) {
+  const answer = await rl.question(`${label} [${defaultValue}]: `);
+  return answer.trim() || defaultValue;
+}
+
+async function runInitDialog({ target, trackerDefault }) {
+  const projectName = path.basename(path.resolve(process.cwd(), target));
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    console.log("");
+    console.log("Настройка init: Git + трекер");
+    console.log("Выбери режим Git и провайдера трекера для проекта.");
+    console.log("");
+
+    const gitModeRaw = await askWithDefault(
+      rl,
+      "Режим Git (github/local/skip)",
+      "github",
+    );
+    const gitMode = gitModeRaw.toLowerCase();
+    ensureGitModeSupported(gitMode);
+
+    const trackerRaw = await askWithDefault(
+      rl,
+      "Провайдер трекера (github/mcp/local/custom)",
+      trackerDefault || defaultTrackerForGitMode(gitMode),
+    );
+    const tracker = normalizeTracker(trackerRaw.toLowerCase());
+    ensureTrackerSupported(tracker);
+
+    let createGithubRepo = false;
+    let githubRepo = "";
+    let githubVisibility = "private";
+
+    if (gitMode === "github") {
+      const createRepoRaw = await askWithDefault(
+        rl,
+        "Создать GitHub-репозиторий сейчас? (yes/no)",
+        "yes",
+      );
+      createGithubRepo = parseYesNo(createRepoRaw, true);
+
+      if (createGithubRepo) {
+        githubRepo = await askWithDefault(
+          rl,
+          "GitHub-репозиторий (name или owner/name)",
+          projectName,
+        );
+        githubVisibility = normalizeVisibility(
+          await askWithDefault(rl, "Видимость репозитория (private/public)", "private"),
+        );
+      }
+    }
+
+    return {
+      tracker,
+      gitSetup: {
+        mode: gitMode,
+        createGithubRepo,
+        githubRepo,
+        githubVisibility,
+      },
+    };
+  } finally {
+    rl.close();
+  }
+}
+
+export async function main(argv) {
+  const [command = "--help", ...rest] = argv;
+  const { options, positional } = parseOptions(rest);
+
+  if (command === "--help" || command === "-h" || options.help) {
+    printHelp();
+    return;
+  }
+
+  if (command === "init") {
+    const target = positional[0] ?? ".";
+    let tracker = normalizeTracker(options.tracker);
+    ensureTrackerSupported(tracker);
+
+    let gitSetup = {
+      mode: tracker === "github" ? "github" : "local",
+      createGithubRepo: false,
+      githubRepo: "",
+      githubVisibility: "private",
+    };
+
+    if (!options.yes && process.stdin.isTTY && process.stdout.isTTY) {
+      const dialogResult = await runInitDialog({
+        target,
+        trackerDefault: options.trackerProvided ? tracker : "",
+      });
+      tracker = dialogResult.tracker;
+      gitSetup = dialogResult.gitSetup;
+    }
+
+    const result = await initProject({
+      cwd: process.cwd(),
+      templateRoot,
+      target,
+      tracker,
+      force: options.force,
+      gitSetup,
+    });
+
+    console.log(`Initialized meta-agents project at: ${result.targetDir}`);
+    console.log(`Default tracker: ${tracker}`);
+    console.log(`Git mode: ${result.git.mode}`);
+    if (result.git.actions.length > 0) {
+      console.log(`Git actions: ${result.git.actions.join("; ")}`);
+    }
+    if (result.git.warnings.length > 0) {
+      console.log(`Git warnings: ${result.git.warnings.join(" | ")}`);
+    }
+    return;
+  }
+
+  if (command === "sync" || command === "upgrade") {
+    const target = positional[0] ?? ".";
+    const result = await syncTemplate({
+      cwd: process.cwd(),
+      templateRoot,
+      target,
+      force: options.force,
+    });
+
+    console.log(`Synced template-managed files at: ${result.targetDir}`);
+    console.log(`Updated files: ${result.updated.join(", ") || "none"}`);
+    console.log(`Skipped files: ${result.skipped.join(", ") || "none"}`);
+    return;
+  }
+
+  throw new Error(`unknown command '${command}'. Run 'meta-agents --help'`);
+}