@k0t0vich/meta-agents-template 0.1.0

package/src/init.mjs

@@ -0,0 +1,197 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const TEXT_EXTENSIONS = new Set([
+  ".md",
+  ".txt",
+  ".json",
+  ".yaml",
+  ".yml",
+  ".mjs",
+  ".js",
+]);
+
+function resolveTargetDir(cwd, target) {
+  return path.resolve(cwd, target);
+}
+
+async function runCommand(command, args, cwd, allowFailure = false) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+
+    child.on("error", (error) => {
+      if (allowFailure) {
+        resolve({ code: 1, stdout: "", stderr: error.message });
+        return;
+      }
+      reject(error);
+    });
+
+    child.on("close", (code) => {
+      if (code === 0 || allowFailure) {
+        resolve({ code: code ?? 1, stdout, stderr });
+        return;
+      }
+      reject(
+        new Error(
+          `${command} ${args.join(" ")} failed with code ${code}: ${(stderr || stdout).trim()}`,
+        ),
+      );
+    });
+  });
+}
+
+async function directoryExists(dir) {
+  try {
+    const stat = await fs.stat(dir);
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function isDirectoryEmpty(dir) {
+  const entries = await fs.readdir(dir);
+  return entries.length === 0;
+}
+
+async function walkFiles(dir, list = []) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const entryPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await walkFiles(entryPath, list);
+    } else {
+      list.push(entryPath);
+    }
+  }
+  return list;
+}
+
+function shouldReplacePlaceholders(filePath) {
+  return TEXT_EXTENSIONS.has(path.extname(filePath));
+}
+
+async function replacePlaceholders(rootDir, values) {
+  const files = await walkFiles(rootDir);
+
+  for (const file of files) {
+    if (!shouldReplacePlaceholders(file)) {
+      continue;
+    }
+
+    const input = await fs.readFile(file, "utf8");
+    let output = input;
+
+    for (const [key, value] of Object.entries(values)) {
+      output = output.replaceAll(`__${key}__`, value);
+    }
+
+    if (output !== input) {
+      await fs.writeFile(file, output, "utf8");
+    }
+  }
+}
+
+async function setupGit(targetDir, gitSetup) {
+  const setup = gitSetup ?? {
+    mode: "skip",
+    createGithubRepo: false,
+    githubRepo: "",
+    githubVisibility: "private",
+  };
+  const actions = [];
+  const warnings = [];
+
+  if (setup.mode === "skip") {
+    return { mode: "skip", actions, warnings };
+  }
+
+  const gitDir = path.join(targetDir, ".git");
+  const hasGit = await directoryExists(gitDir);
+  if (!hasGit) {
+    await runCommand("git", ["init"], targetDir);
+    actions.push("initialized local git repository");
+    await runCommand("git", ["symbolic-ref", "HEAD", "refs/heads/main"], targetDir, true);
+  } else {
+    actions.push("local git repository already exists");
+  }
+
+  if (setup.mode !== "github" || !setup.createGithubRepo) {
+    return { mode: setup.mode, actions, warnings };
+  }
+
+  const ghInstalled = await runCommand("gh", ["--version"], targetDir, true);
+  if (ghInstalled.code !== 0) {
+    warnings.push("GitHub CLI is not installed, skipped GitHub repository creation");
+    return { mode: setup.mode, actions, warnings };
+  }
+
+  const ghAuth = await runCommand("gh", ["auth", "status"], targetDir, true);
+  if (ghAuth.code !== 0) {
+    warnings.push("GitHub CLI is not authenticated, skipped GitHub repository creation");
+    return { mode: setup.mode, actions, warnings };
+  }
+
+  const repoName = (setup.githubRepo || path.basename(targetDir)).trim();
+  const visibility =
+    setup.githubVisibility && setup.githubVisibility.toLowerCase() === "public"
+      ? "--public"
+      : "--private";
+
+  const createRepo = await runCommand(
+    "gh",
+    ["repo", "create", repoName, visibility, "--source", targetDir, "--remote", "origin"],
+    targetDir,
+    true,
+  );
+
+  if (createRepo.code === 0) {
+    actions.push(`created GitHub repository '${repoName}'`);
+  } else {
+    warnings.push(
+      `failed to create GitHub repository '${repoName}': ${(createRepo.stderr || createRepo.stdout).trim()}`,
+    );
+  }
+
+  return { mode: setup.mode, actions, warnings };
+}
+
+export async function initProject({ cwd, templateRoot, target, tracker, force, gitSetup }) {
+  const targetDir = resolveTargetDir(cwd, target);
+  const exists = await directoryExists(targetDir);
+
+  if (exists) {
+    const empty = await isDirectoryEmpty(targetDir);
+    if (!empty && !force) {
+      throw new Error(`target directory is not empty: ${targetDir}. Use --force to overwrite.`);
+    }
+  } else {
+    await fs.mkdir(targetDir, { recursive: true });
+  }
+
+  await fs.cp(templateRoot, targetDir, {
+    recursive: true,
+    force,
+    errorOnExist: !force,
+  });
+
+  const projectName = path.basename(targetDir);
+  await replacePlaceholders(targetDir, {
+    PROJECT_NAME: projectName,
+    DEFAULT_TRACKER: tracker,
+  });
+
+  const git = await setupGit(targetDir, gitSetup);
+  return { targetDir, git };
+}

package/src/sync.mjs

@@ -0,0 +1,46 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const MANAGED_PATHS = [
+  "agents.md",
+  "tracker-command-template.md",
+  ".meta-agents",
+  "tasks/backlog.md",
+  "tasks/sprint-1.md",
+  "tasks/task-status-log.md",
+];
+
+async function exists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function syncTemplate({ cwd, templateRoot, target, force }) {
+  const targetDir = path.resolve(cwd, target);
+  const updated = [];
+  const skipped = [];
+
+  for (const managedPath of MANAGED_PATHS) {
+    const source = path.join(templateRoot, managedPath);
+    const destination = path.join(targetDir, managedPath);
+    const destinationExists = await exists(destination);
+
+    if (destinationExists && !force) {
+      skipped.push(managedPath);
+      continue;
+    }
+
+    await fs.mkdir(path.dirname(destination), { recursive: true });
+    await fs.cp(source, destination, {
+      recursive: true,
+      force: true,
+    });
+    updated.push(managedPath);
+  }
+
+  return { targetDir, updated, skipped };
+}

package/template/.meta-agents/config/roles.yaml

@@ -0,0 +1,21 @@
+roles:
+  - name: "Chief of Staff Agent"
+    responsibility: "Оркестрация, блокеры, эскалации"
+  - name: "Agile Manager Agent"
+    responsibility: "CREATE_TASK/SET_STATUS/COMMIT_BY_NAME/ASSIGN_SPRINT"
+  - name: "Product Manager Agent"
+    responsibility: "PRD и acceptance criteria"
+  - name: "Solution Architect Agent"
+    responsibility: "Архитектура и контракты"
+  - name: "Verifier Designer Agent"
+    responsibility: "Модель проверки и evidence-план"
+  - name: "Decomposer Agent"
+    responsibility: "Декомпозиция на проверяемые компоненты"
+  - name: "Engineering Agent"
+    responsibility: "Реализация по контрактам"
+  - name: "QA Agent"
+    responsibility: "Верификация и тестирование"
+  - name: "Reviewer/Judge Agent"
+    responsibility: "Независимая приёмка"
+  - name: "Documentation Agent"
+    responsibility: "Синхронизация документации"

package/template/.meta-agents/config/system.yaml

@@ -0,0 +1,48 @@
+system:
+  name: "Meta Agents Verified Delivery"
+  process:
+    - clarify
+    - prd_step
+    - verification_design
+    - decomposition
+    - execution
+    - evidence
+    - acceptance
+  mandatory_prd_sections:
+    - description
+    - verifiability
+    - done
+  init_dialog:
+    required: true
+    ask_git_mode: true
+    ask_tracker_provider: true
+    git_modes:
+      - github
+      - local
+      - skip
+    offer_create_github_repo: true
+  governance:
+    user_confirmation_required_for:
+      - commit
+      - task_close_done
+    max_status_without_user_confirmation: READY
+  acceptance:
+    hard_criteria:
+      - prd_sections_complete
+      - auto_select_prefix_present
+      - strict_checks_passed
+      - statistical_thresholds_met
+      - human_approvals_passed
+      - evidence_pack_complete
+      - tracker_sync_complete
+  auto_select:
+    required: true
+    before_each_task: true
+    require_agent_name_prefix: true
+    prefix_order:
+      - agent_auto_select
+      - task_agent_name
+    prefix_format:
+      agent_auto_select: "[Agent Auto-Select] Selected: <agent role>; Reason: <short reason>"
+      task_agent_name: "[Task Agent] Name: <agent role>"
+  default_tracker: "__DEFAULT_TRACKER__"

package/template/.meta-agents/config/trackers.yaml

@@ -0,0 +1,16 @@
+tracker_gateway:
+  default: "__DEFAULT_TRACKER__"
+  providers:
+    github:
+      mode: "issues_projects"
+      enabled: true
+    mcp:
+      mode: "external_tracker_via_mcp"
+      enabled: true
+      aliases: ["mpc"]
+    custom:
+      mode: "custom_api_adapter"
+      enabled: true
+    local:
+      mode: "file_based"
+      enabled: true

package/template/.meta-agents/prompts/agile-manager.md

@@ -0,0 +1,3 @@
+Role: Agile Manager Agent
+Goal: управлять задачами и статусами через TrackerGateway.
+Commands: CREATE_TASK, SET_STATUS, COMMIT_BY_NAME, ASSIGN_SPRINT.

package/template/.meta-agents/prompts/architect.md

@@ -0,0 +1,3 @@
+Role: Solution Architect Agent
+Goal: предложить архитектуру и контракты компонентов.
+Output: Architecture rationale + verification impact.

package/template/.meta-agents/prompts/clarifier.md

@@ -0,0 +1,3 @@
+Role: Clarifier Agent
+Goal: выявить цель, ограничения, неоднозначности и критерии успеха.
+Output: PRD Step с заполненными "Описание" и "Проверяемость".

package/template/.meta-agents/prompts/decomposer.md

@@ -0,0 +1,3 @@
+Role: Decomposer Agent
+Goal: разбить систему на Verified Components.
+Output: contracts + dependency graph.

package/template/.meta-agents/prompts/reviewer-judge.md

@@ -0,0 +1,3 @@
+Role: Reviewer/Judge Agent
+Goal: независимая приёмка по критериям.
+Output: accepted/rejected + findings.

package/template/.meta-agents/prompts/verifier-designer.md

@@ -0,0 +1,3 @@
+Role: Verifier Designer Agent
+Goal: определить strict/statistical/human проверки.
+Output: verification plan и evidence mapping.

package/template/.meta-agents/scripts/generate-prd-step.mjs

@@ -0,0 +1 @@
+console.log("generate-prd-step placeholder: render PRD Step template for current stage.");

package/template/.meta-agents/scripts/init.mjs

@@ -0,0 +1 @@
+console.log("Project initialized with Meta Agents templates.");

package/template/.meta-agents/scripts/sync-status.mjs

@@ -0,0 +1 @@
+console.log("sync-status placeholder: connect to tracker and refresh local status views.");

package/template/.meta-agents/scripts/tracker/custom.mjs

@@ -0,0 +1,4 @@
+export async function createTask() { throw new Error("custom adapter: not implemented"); }
+export async function setStatus() { throw new Error("custom adapter: not implemented"); }
+export async function commitByName() { throw new Error("custom adapter: not implemented"); }
+export async function assignSprint() { throw new Error("custom adapter: not implemented"); }

package/template/.meta-agents/scripts/tracker/github.mjs

@@ -0,0 +1,4 @@
+export async function createTask() { throw new Error("github adapter: not implemented"); }
+export async function setStatus() { throw new Error("github adapter: not implemented"); }
+export async function commitByName() { throw new Error("github adapter: not implemented"); }
+export async function assignSprint() { throw new Error("github adapter: not implemented"); }

package/template/.meta-agents/scripts/tracker/local.mjs

@@ -0,0 +1,4 @@
+export async function createTask() { throw new Error("local adapter: not implemented"); }
+export async function setStatus() { throw new Error("local adapter: not implemented"); }
+export async function commitByName() { throw new Error("local adapter: not implemented"); }
+export async function assignSprint() { throw new Error("local adapter: not implemented"); }

package/template/.meta-agents/scripts/tracker/mcp.mjs

@@ -0,0 +1,4 @@
+export async function createTask() { throw new Error("mcp adapter: not implemented"); }
+export async function setStatus() { throw new Error("mcp adapter: not implemented"); }
+export async function commitByName() { throw new Error("mcp adapter: not implemented"); }
+export async function assignSprint() { throw new Error("mcp adapter: not implemented"); }

package/template/.meta-agents/templates/agent-work-contract.md

@@ -0,0 +1,12 @@
+# Agent Work Contract
+
+- Task ID:
+- Component:
+- Owner Role:
+- Scope:
+- Allowed Design Freedom:
+- Required Outputs:
+- Required Evidence:
+- Acceptance Criteria:
+- Failure/Escalation Rules:
+- Tracker Binding (task/status/sprint):

package/template/.meta-agents/templates/evidence-pack.md

@@ -0,0 +1,9 @@
+# Evidence Pack
+
+- Task ID:
+- Build/Test artifacts:
+- Eval metrics:
+- Trace/Logs:
+- Commit refs:
+- Tracker refs:
+- Residual risks:

package/template/.meta-agents/templates/prd-step.md

@@ -0,0 +1,15 @@
+## PRD Step: <stage-name>
+
+### Описание
+- Что и зачем делаем на этапе.
+
+### Проверяемость
+- strict:
+- statistical:
+- human:
+- evidence:
+
+### Что сделано
+- [ ] Не начато
+- Артефакты:
+- Проверки:

package/template/.meta-agents/templates/sprint-template.md

@@ -0,0 +1,12 @@
+# Sprint
+
+- Sprint ID:
+- Status: PLANNED
+- Goal:
+
+## Tasks
+| Task ID | Short Name | Owner | Status | Notes |
+|---|---|---|---|---|
+
+## Progress Log
+- YYYY-MM-DD: Sprint created

package/template/.meta-agents/templates/task-template.md

@@ -0,0 +1,26 @@
+# Task
+
+- Task ID:
+- Short Name:
+- Owner Role:
+- Status: TODO
+- Sprint:
+
+## PRD Step
+### Описание
+-
+### Проверяемость
+- strict:
+- statistical:
+- human:
+### Что сделано
+- [ ] Не начато
+
+## Dependencies
+-
+
+## Evidence
+-
+
+## Progress Log
+- YYYY-MM-DD: created

package/template/.meta-agents/templates/verification-plan.md

@@ -0,0 +1,15 @@
+# Verification Plan
+
+## Scope
+-
+
+## Checks
+- strict:
+- statistical:
+- human:
+
+## Metrics & Thresholds
+-
+
+## Evidence Mapping
+- criterion -> proof artifact

package/template/README.md

@@ -0,0 +1,23 @@
+# __PROJECT_NAME__
+
+Проект инициализирован шаблоном `meta-agents-template`.
+
+## Что уже подключено
+- `agents.md`: роли, правила и жёсткие критерии приёмки;
+- `tracker-command-template.md`: команды управления задачами и спринтами;
+- `.meta-agents/`: конфигурация системы и шаблоны PRD/verification;
+- `tasks/`: backlog/sprint/status-log.
+
+## Что спросит init
+1. Git режим: `github`, `local` или `skip`.
+2. Нужно ли создать GitHub-репозиторий сразу.
+3. Какой трекер выбрать по умолчанию.
+
+## Обязательные правила
+1. Каждый шаг содержит: `Описание -> Проверяемость -> Что сделано`.
+2. Перед каждой задачей обязателен вывод `[Agent Auto-Select]` и `[Task Agent]`.
+3. Коммиты и закрытие задачи в `DONE` только после явного подтверждения пользователя.
+4. Без подтверждения пользователя максимум статуса: `READY`.
+
+## Команды
+Смотри `tracker-command-template.md`.

package/template/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`.
+
+Режим по умолчанию для командной работы: `__DEFAULT_TRACKER__` (или другой внешний трекер). `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/template/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "meta:status": "node .meta-agents/scripts/sync-status.mjs"
+  }
+}

package/template/tasks/backlog.md

@@ -0,0 +1,4 @@
+# Backlog
+
+| Task ID | Short Name | Owner | Status | Notes |
+|---|---|---|---|---|