@k0t0vich/meta-agents-template 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this package are documented in this file.
 
+## 0.1.7 - 2026-03-20
+
+### Changed
+- Switched `meta-agents init` to non-destructive bootstrap: root now gets only `.meta-agents/config/*`, while automation rules are consumed from `node_modules/@k0t0vich/meta-agents-template`.
+- Prevented accidental overwrite of existing project `agents.md`: init now appends/updates only a managed links block instead of replacing full content.
+- Reworked package setup in existing projects: `package.json` is merged (not replaced), preserving existing scripts while adding `meta:*` commands and `devDependencies` entry.
+- Added runtime package self-install during init when package files are not present locally (safe `npx` path).
+- Updated public README with robust one-line onboarding for npm URL/package-name prompts and new post-init layout.
+- Updated local post-publish smoke to validate the new config-only root flow.
+
+## 0.1.6 - 2026-03-20
+
+### Changed
+- Switched governance/process docs to a single canonical task reference: GitHub `#issue`.
+- Removed mixed prefixed task-id examples (`GOV-*`, `REL-*`, `DOC-*`, `DEV-*`) from workflow commands and policy text.
+- Synchronized current project and template agent artifacts for canonical `#issue` usage (`agents.md`, `tracker-command-template.md`, prompts, branch-router warning, commit-link validation, release docs examples).
+
 ## 0.1.5 - 2026-03-20
 
 ### Changed

package/README.md

@@ -9,17 +9,46 @@
 - командный протокол работы с задачами и спринтами;
 - выбор 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 my-project
+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: в корне создаёт/обновляет только `.meta-agents/config/*`, аккуратно merge-ит `meta:*` scripts в `package.json` и добавляет ссылочный блок в `agents.md` вместо полной перезаписи.
+- `--force` нужен только если надо перезаписать уже существующие `.meta-agents/config/*` и мигрировать 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
-npm i -D git+https://github.com/k0t0vich/meta-agents-template.git
-npx meta-agents init my-project
+test -f agents.md && test -f .meta-agents/config/project-context.yaml && test -f node_modules/@k0t0vich/meta-agents-template/agents.md && echo "meta-agents template ready"
 ```
 
 ## Диалог при `init`
@@ -33,55 +62,24 @@ npx meta-agents init my-project
 ## Структура проекта после `init`
 ```text
 my-project/
-  .github/
-    workflows/
-      gitflow-lite-verify.yml
   package.json
-  README.md
+  package-lock.json
   agents.md
-  tracker-command-template.md
   .meta-agents/
     config/
       system.yaml
       roles.yaml
       trackers.yaml
       project-context.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
-      mr-review-agent.md
-      agile-manager.md
-      publishing-agent.md
-      status-agent.md
-    scripts/
-      init.mjs
-      sync-status.mjs
-      verify-branch-strategy.mjs
-      task-branch-router.mjs
-      run-mr-review-gate.mjs
-      generate-prd-step.mjs
-      tracker/
-        local.mjs
-        github.mjs
-        mcp.mjs
-        custom.mjs
-      tracker-gateway.mjs
-  tasks/
-    backlog.md
-    sprint-1.md
-    task-status-log.md
+  node_modules/
+    @k0t0vich/meta-agents-template/
+      agents.md
+      tracker-command-template.md
+      template/.meta-agents/scripts/*.mjs
 ```
 
+`agents.md` в проекте не перезаписывается целиком: `init` добавляет/обновляет в нём только ссылочный блок на правила из npm-пакета.
+
 ## Канонические команды
 0. `VERIFY_GOVERNANCE_GATE`
 1. `CREATE_TASK`
@@ -133,7 +131,7 @@ npm run self:bootstrap
 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/task (`TASK-ID` и/или `#issue` в commit message).
+13. Каждый коммит связан с issue (`#issue` в commit message).
 
 Если хотя бы один пункт не выполнен, задача не принимается.
 
@@ -143,14 +141,14 @@ npm run self:bootstrap
 ```bash
 npm run meta:verify
 npm run meta:branch
-npm run meta:task-start -- --task GOV-1 --slug api-redirect
+npm run meta:task-start -- --task #12 --slug api-redirect
 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":"DEV-12","status":"IN_PROGRESS"}'
-npm run meta:ops -- --command PREPARE_TASK_BRANCH --payload '{"task":"GOV-1","slug":"api-redirect"}'
+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
 ```
 
@@ -158,7 +156,7 @@ npm run meta:status
 `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` между текущей и базовой веткой и требует явного подтверждения при diff.
-Именование branch task ref: по умолчанию использовать префиксные ID (`GOV-1`, `REL-1`, `DOC-1`, `DEV-1`); для чистого GitHub issue fallback формат `issue-<number>`.
+Именование branch task ref: использовать GitHub issue ref в формате `issue-<number>`.
 `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 и не являются источником истины.

package/agents.md

@@ -148,7 +148,7 @@ Name: <agent role>
 - без подтверждения пользователя максимум допустимого статуса: `REVIEW`.
 - `SET_STATUS -> READY` разрешён только после `RUN_REVIEW_GATE: PASS_CONFIRMED`.
 - для задач реализации по умолчанию используется отдельная ветка `feature/*`; прямой рабочий поток на `develop`/`main` не допускается.
-- сообщение коммита обязано содержать ссылку на задачу (`TASK-ID` и/или `#issue-number`).
+- сообщение коммита обязано содержать ссылку на задачу (`#issue-number`).
 - `READY` означает: коммит сделан и отправлен (`push`) в `feature/*`, `release/*` или `hotfix/*` с открытым PR по правилам ветвления.
 - `DONE` означает: изменения интегрированы в `main`; для `release/*` и `hotfix/*` подтверждён back-merge в `develop`.
 - `PUBLISH` означает: релиз опубликован и доступен в последней версии пакета.
@@ -165,8 +165,8 @@ Name: <agent role>
 ## 10.2) Обязательная маршрутизация ветки для Agile Manager Agent
 Перед началом реализации агент обязан:
 1. Проверить веточный контекст через `meta:status`.
-2. Запустить branch-routing preflight через `meta:task-start -- --task <TASK-ID|#issue> --slug <slug> --kind atomic|feature|release|hotfix`.
-3. В названии рабочей ветки использовать task ref с префиксом (`GOV-1`, `REL-1`, `DOC-1`, `DEV-1`); если есть только issue number, использовать `issue-<number>`.
+2. Запустить branch-routing preflight через `meta:task-start -- --task <#issue> --slug <slug> --kind atomic|feature|release|hotfix`.
+3. В названии рабочей ветки использовать GitHub issue ref в формате `issue-<number>` (например, `feature/issue-21-canonical-github-issue-id`).
 4. Если задача относится к текущей feature-ветке (атомарная подзадача), продолжить в этой ветке только после подтверждения пользователя.
 5. Если задача не относится к текущей ветке, проверить незакоммиченные изменения и непушенные коммиты.
 6. Согласовать с пользователем способ обработки (`commit/stash/discard/push`).
@@ -199,7 +199,7 @@ Name: <agent role>
 19. Для статуса `DONE` подтверждена интеграция в `main`; для `release/*` и `hotfix/*` подтверждён back-merge в `develop`.
 20. Для статуса `PUBLISH` подтверждена публикация в последней версии.
 21. Для релиза обновлён публичный `CHANGELOG.md`.
-22. Коммит содержит ссылку на issue/task (`TASK-ID` или `#issue`).
+22. Коммит содержит ссылку на issue (`#issue`).
 23. Для branch routing собран e2e evidence по двум сценариям: `same feature` и `different feature`.
 24. Перед `--apply` подтверждена консистентность контекста `agents.md` (или явно подтверждён осознанный switch при diff).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k0t0vich/meta-agents-template",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Template system for verification-first agentic development",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import readline from "node:readline/promises";
@@ -8,6 +9,25 @@ import { syncTemplate } from "./sync.mjs";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const templateRoot = path.resolve(__dirname, "..", "template");
+const packageManifestPath = path.resolve(__dirname, "..", "package.json");
+
+function readSelfPackageIdentity() {
+  try {
+    const raw = fs.readFileSync(packageManifestPath, "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+      name: String(parsed.name || "@k0t0vich/meta-agents-template"),
+      version: String(parsed.version || ""),
+    };
+  } catch {
+    return {
+      name: "@k0t0vich/meta-agents-template",
+      version: "",
+    };
+  }
+}
+
+const selfPackage = readSelfPackageIdentity();
 
 function parseOptions(args) {
   const options = {
@@ -60,13 +80,14 @@ function printHelp() {
     "  meta-agents --help",
     "",
     "Commands:",
-    "  init     Initialize a project from template",
+    "  init     Initialize a project (config-only in root, npm-linked rules)",
     "  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.",
+    "  --force overwrites existing .meta-agents/config files and updates legacy meta:* scripts.",
   ];
   console.log(lines.join("\n"));
 }
@@ -233,11 +254,38 @@ export async function main(argv) {
       tracker,
       force: options.force,
       gitSetup,
+      packageName: selfPackage.name,
+      packageVersion: selfPackage.version,
     });
 
     console.log(`Initialized meta-agents project at: ${result.targetDir}`);
     console.log(`Default tracker: ${tracker}`);
     console.log(`Git mode: ${result.git.mode}`);
+    if (result.packageJson.created) {
+      console.log("Package manifest: created package.json");
+    }
+    if (result.packageJson.dependencyAdded) {
+      console.log(`Package dependency: added ${selfPackage.name} to devDependencies`);
+    }
+    if (result.packageJson.updatedScripts.length > 0) {
+      console.log(`Meta scripts updated: ${result.packageJson.updatedScripts.join(", ")}`);
+    }
+    if (result.runtimePackage.installedNow) {
+      console.log(`Runtime package installed: ${selfPackage.name}`);
+    }
+    if (result.config.updated.length > 0) {
+      console.log(`Config files written: ${result.config.updated.join(", ")}`);
+    }
+    if (result.config.skipped.length > 0) {
+      console.log(`Config files kept: ${result.config.skipped.join(", ")}`);
+    }
+    if (result.agents.created) {
+      console.log("agents.md: created with npm links to template rules");
+    } else if (result.agents.updated) {
+      console.log("agents.md: appended/updated npm links block");
+    } else {
+      console.log("agents.md: npm links block already up to date");
+    }
     if (result.git.actions.length > 0) {
       console.log(`Git actions: ${result.git.actions.join("; ")}`);
     }

package/src/init.mjs

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
+import process from "node:process";
 
 const TEXT_EXTENSIONS = new Set([
   ".md",
@@ -12,10 +13,25 @@ const TEXT_EXTENSIONS = new Set([
   ".js",
 ]);
 
+const AGENTS_LINK_BLOCK_START = "<!-- meta-agents-template:links:start -->";
+const AGENTS_LINK_BLOCK_END = "<!-- meta-agents-template:links:end -->";
+
 function resolveTargetDir(cwd, target) {
   return path.resolve(cwd, target);
 }
 
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function replaceTemplatePlaceholders(input, values) {
+  let output = input;
+  for (const [key, value] of Object.entries(values)) {
+    output = output.replaceAll(`__${key}__`, value);
+  }
+  return output;
+}
+
 async function runCommand(command, args, cwd, allowFailure = false) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
@@ -51,6 +67,15 @@ async function runCommand(command, args, cwd, allowFailure = false) {
   });
 }
 
+async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function directoryExists(dir) {
   try {
     const stat = await fs.stat(dir);
@@ -60,11 +85,6 @@ async function directoryExists(dir) {
   }
 }
 
-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) {
@@ -82,25 +102,198 @@ function shouldReplacePlaceholders(filePath) {
   return TEXT_EXTENSIONS.has(path.extname(filePath));
 }
 
-async function replacePlaceholders(rootDir, values) {
-  const files = await walkFiles(rootDir);
+function buildMetaScripts(packageName) {
+  const base = `node ./node_modules/${packageName}/template/.meta-agents/scripts`;
+  return {
+    "meta:status": `${base}/sync-status.mjs`,
+    "meta:branch": `${base}/verify-branch-strategy.mjs`,
+    "meta:task-start": `${base}/task-branch-router.mjs`,
+    "meta:verify": `${base}/verify-governance.mjs`,
+    "meta:review": `${base}/run-review-gate.mjs`,
+    "meta:review-approve": `${base}/run-review-gate.mjs --approve yes`,
+    "meta:mr-review": `${base}/run-mr-review-gate.mjs`,
+    "meta:mr-review-approve": `${base}/run-mr-review-gate.mjs --approve yes`,
+    "meta:verify-link": `${base}/verify-commit-link.mjs`,
+    "meta:ops": `${base}/tracker-gateway.mjs`,
+  };
+}
+
+function isLegacyMetaScript(value) {
+  return (
+    value.includes(".meta-agents/scripts/") ||
+    value.includes("meta-agents-template/template/.meta-agents/scripts/")
+  );
+}
+
+function defaultPackageNameFromDir(targetDir) {
+  const raw = path.basename(targetDir).toLowerCase();
+  const sanitized = raw.replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return sanitized || "meta-agents-project";
+}
+
+async function ensurePackageJson(targetDir) {
+  const packageJsonPath = path.join(targetDir, "package.json");
+  if (await pathExists(packageJsonPath)) {
+    const input = await fs.readFile(packageJsonPath, "utf8");
+    try {
+      return {
+        path: packageJsonPath,
+        data: JSON.parse(input),
+        created: false,
+      };
+    } catch (error) {
+      throw new Error(`invalid package.json at ${packageJsonPath}: ${error.message}`);
+    }
+  }
+
+  const data = {
+    name: defaultPackageNameFromDir(targetDir),
+    version: "0.1.0",
+    private: true,
+    scripts: {},
+    devDependencies: {},
+  };
+  return {
+    path: packageJsonPath,
+    data,
+    created: true,
+  };
+}
+
+async function mergePackageJsonMeta({
+  targetDir,
+  packageName,
+  packageVersion,
+  force,
+}) {
+  const packageJson = await ensurePackageJson(targetDir);
+  const data = packageJson.data || {};
+  data.scripts = data.scripts && typeof data.scripts === "object" ? data.scripts : {};
+  data.devDependencies =
+    data.devDependencies && typeof data.devDependencies === "object" ? data.devDependencies : {};
+
+  const desiredScripts = buildMetaScripts(packageName);
+  const updatedScripts = [];
+  const skippedScripts = [];
 
-  for (const file of files) {
-    if (!shouldReplacePlaceholders(file)) {
+  for (const [key, value] of Object.entries(desiredScripts)) {
+    const current = data.scripts[key];
+    if (!current) {
+      data.scripts[key] = value;
+      updatedScripts.push(key);
       continue;
     }
 
-    const input = await fs.readFile(file, "utf8");
-    let output = input;
+    if (current !== value && (force || isLegacyMetaScript(current))) {
+      data.scripts[key] = value;
+      updatedScripts.push(key);
+      continue;
+    }
+
+    skippedScripts.push(key);
+  }
+
+  let dependencyAdded = false;
+  if (!data.devDependencies[packageName]) {
+    const spec = packageVersion ? `^${packageVersion}` : "latest";
+    data.devDependencies[packageName] = spec;
+    dependencyAdded = true;
+  }
+
+  if (packageJson.created || updatedScripts.length > 0 || dependencyAdded) {
+    await fs.writeFile(packageJson.path, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+  }
 
-    for (const [key, value] of Object.entries(values)) {
-      output = output.replaceAll(`__${key}__`, value);
+  return {
+    created: packageJson.created,
+    updatedScripts,
+    skippedScripts,
+    dependencyAdded,
+    packageJsonPath: packageJson.path,
+  };
+}
+
+function buildAgentsLinkBlock(packageName) {
+  const packageRoot = `./node_modules/${packageName}`;
+  const lines = [
+    AGENTS_LINK_BLOCK_START,
+    "## Meta Agents Template (npm-linked)",
+    "Базовые правила шаблона:",
+    `- [Template agents.md](${packageRoot}/agents.md)`,
+    `- [Template tracker-command-template.md](${packageRoot}/tracker-command-template.md)`,
+    "Локальные конфиги проекта:",
+    "- [.meta-agents/config/project-context.yaml](./.meta-agents/config/project-context.yaml)",
+    "- [.meta-agents/config/trackers.yaml](./.meta-agents/config/trackers.yaml)",
+    "- [.meta-agents/config/system.yaml](./.meta-agents/config/system.yaml)",
+    AGENTS_LINK_BLOCK_END,
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+async function upsertAgentsLinks(targetDir, packageName) {
+  const agentsPath = path.join(targetDir, "agents.md");
+  const block = buildAgentsLinkBlock(packageName);
+
+  if (!(await pathExists(agentsPath))) {
+    const content = ["# agents.md", "", block].join("\n");
+    await fs.writeFile(agentsPath, content, "utf8");
+    return { created: true, updated: false, path: agentsPath };
+  }
+
+  const input = await fs.readFile(agentsPath, "utf8");
+  const blockRegex = new RegExp(
+    `${escapeRegExp(AGENTS_LINK_BLOCK_START)}[\\s\\S]*?${escapeRegExp(AGENTS_LINK_BLOCK_END)}\\n?`,
+    "m",
+  );
+
+  let output = input;
+  let updated = false;
+
+  if (blockRegex.test(input)) {
+    output = input.replace(blockRegex, block);
+    updated = output !== input;
+  } else {
+    const glue = input.endsWith("\n") ? "\n" : "\n\n";
+    output = `${input}${glue}${block}`;
+    updated = true;
+  }
+
+  if (updated) {
+    await fs.writeFile(agentsPath, output, "utf8");
+  }
+
+  return { created: false, updated, path: agentsPath };
+}
+
+async function syncConfigFiles({ templateRoot, targetDir, values, force }) {
+  const sourceConfigRoot = path.join(templateRoot, ".meta-agents", "config");
+  const targetConfigRoot = path.join(targetDir, ".meta-agents", "config");
+  const sourceFiles = await walkFiles(sourceConfigRoot);
+
+  const updated = [];
+  const skipped = [];
+
+  for (const sourceFile of sourceFiles) {
+    const relative = path.relative(sourceConfigRoot, sourceFile);
+    const destination = path.join(targetConfigRoot, relative);
+
+    if (!force && (await pathExists(destination))) {
+      skipped.push(path.join(".meta-agents", "config", relative));
+      continue;
     }
 
-    if (output !== input) {
-      await fs.writeFile(file, output, "utf8");
+    await fs.mkdir(path.dirname(destination), { recursive: true });
+    if (shouldReplacePlaceholders(sourceFile)) {
+      const raw = await fs.readFile(sourceFile, "utf8");
+      const rendered = replaceTemplatePlaceholders(raw, values);
+      await fs.writeFile(destination, rendered, "utf8");
+    } else {
+      await fs.copyFile(sourceFile, destination);
     }
+    updated.push(path.join(".meta-agents", "config", relative));
   }
+
+  return { updated, skipped };
 }
 
 async function setupGit(targetDir, gitSetup) {
@@ -167,31 +360,70 @@ async function setupGit(targetDir, gitSetup) {
   return { mode: setup.mode, actions, warnings };
 }
 
-export async function initProject({ cwd, templateRoot, target, tracker, force, gitSetup }) {
+function packageDirFromName(targetDir, packageName) {
+  return path.join(targetDir, "node_modules", ...packageName.split("/"));
+}
+
+async function ensureRuntimePackageInstalled({ targetDir, packageName, packageVersion }) {
+  const installDir = packageDirFromName(targetDir, packageName);
+  if (await directoryExists(installDir)) {
+    return { installedNow: false, installDir };
+  }
+
+  const spec = packageVersion ? `${packageName}@${packageVersion}` : packageName;
+  const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+  await runCommand(npmCommand, ["install", "-D", spec], targetDir);
+  return { installedNow: true, installDir };
+}
+
+export async function initProject({
+  cwd,
+  templateRoot,
+  target,
+  tracker,
+  force,
+  gitSetup,
+  packageName = "@k0t0vich/meta-agents-template",
+  packageVersion = "",
+}) {
   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 {
+  if (!exists) {
     await fs.mkdir(targetDir, { recursive: true });
   }
 
-  await fs.cp(templateRoot, targetDir, {
-    recursive: true,
+  const packageJson = await mergePackageJsonMeta({
+    targetDir,
+    packageName,
+    packageVersion,
     force,
-    errorOnExist: !force,
+  });
+  const runtimePackage = await ensureRuntimePackageInstalled({
+    targetDir,
+    packageName,
+    packageVersion,
   });
 
   const projectName = path.basename(targetDir);
-  await replacePlaceholders(targetDir, {
-    PROJECT_NAME: projectName,
-    DEFAULT_TRACKER: tracker,
+  const config = await syncConfigFiles({
+    templateRoot,
+    targetDir,
+    values: {
+      PROJECT_NAME: projectName,
+      DEFAULT_TRACKER: tracker,
+    },
+    force,
   });
 
+  const agents = await upsertAgentsLinks(targetDir, packageName);
   const git = await setupGit(targetDir, gitSetup);
-  return { targetDir, git };
+
+  return {
+    targetDir,
+    git,
+    packageJson,
+    runtimePackage,
+    config,
+    agents,
+  };
 }

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

@@ -87,12 +87,8 @@ system:
           release: "release/vX.Y.Z"
           hotfix: "hotfix/<task-ref>-<slug>"
         task_ref_policy:
-          preferred_format:
-            - "GOV-<n>"
-            - "REL-<n>"
-            - "DOC-<n>"
-            - "DEV-<n>"
-          issue_fallback_format: "issue-<number>"
+          canonical_format: "#<number>"
+          branch_format: "issue-<number>"
         allowed_branch_patterns:
           - "^main$"
           - "^develop$"
@@ -212,7 +208,6 @@ system:
     commit_linkage:
       required: true
       accepted_patterns:
-        - "TASK-ID"
         - "#issue"
     publish_flow:
       changelog_required: true

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

@@ -7,7 +7,7 @@ Rule: для большой фичи в GitHub tracker сначала предл
 
 Branch routing protocol (обязателен для задач реализации):
 1. Сначала снять контекст: `npm run meta:status -- --json`.
-2. Проверить маршрут ветки: `npm run meta:task-start -- --task <TASK-ID|#issue> --slug <slug> --kind atomic`.
+2. Проверить маршрут ветки: `npm run meta:task-start -- --task <#issue> --slug <slug> --kind atomic`.
 3. Если `route=stay_on_current_branch`, задача считается атомарной внутри текущей feature-ветки.
 4. Если `route=create_new_branch`, перед началом реализации обязательно перейти на базовую ветку (`develop` для feature/release, `main` для hotfix), обновить её и создать новую рабочую ветку.
 5. Создание/переключение ветки выполнять только после явного подтверждения пользователя (`--apply`).
@@ -19,8 +19,8 @@ Mandatory user dialogue before branch switch:
 - подтвердить финальный switch/create.
 
 Task ref naming rule:
-- для веток использовать task ref с префиксом (`GOV-1`, `REL-5`, `DOC-2`, `DEV-12`);
-- если есть только номер issue, использовать fallback `issue-<number>` в имени ветки.
+- использовать GitHub issue ref как единственный канонический идентификатор (`#<number>`);
+- в имени ветки использовать формат `issue-<number>`.
 
 Pre-merge rule:
 - после commit+push и открытия PR обязательно выполнить `RUN_MR_REVIEW_GATE`;

package/template/.meta-agents/prompts/status-agent.md

@@ -21,7 +21,7 @@ Output format (обязательный):
 Tooling:
 - Основной путь: `npm run meta:status`.
 - Для machine-readable вывода можно использовать `npm run meta:status -- --json`.
-- Для веточного preflight по конкретной задаче: `npm run meta:task-start -- --task <TASK-ID|#issue> --slug <slug>`.
+- Для веточного preflight по конкретной задаче: `npm run meta:task-start -- --task <#issue> --slug <slug>`.
 
 Rule:
 - В `github` режиме локальные `tasks/*` не считать авторитетным источником по умолчанию; рассматривать только как cache/legacy artifacts.

package/template/.meta-agents/scripts/task-branch-router.mjs

@@ -390,9 +390,9 @@ function buildPlan(options, gitContext) {
     );
   }
 
-  if (/^ISSUE-\d+$/.test(taskRef)) {
+  if (!/^ISSUE-\d+$/.test(taskRef)) {
     namingWarnings.push(
-      "Task ref is issue-based. Branch name will use issue-<number>; prefer domain task refs like GOV-1/REL-1/DOC-1 when available.",
+      "Canonical task ref should be GitHub issue number (#<number>) so branch naming stays issue-<number>.",
     );
   }
 

package/template/.meta-agents/scripts/verify-commit-link.mjs

@@ -8,8 +8,7 @@ function readLastCommitSubject(ref = "HEAD") {
 
 function validateMessage(message) {
   const hasIssueNumber = /#\d+\b/.test(message);
-  const hasTaskId = /\b[A-Z][A-Z0-9_]*-\d+\b/.test(message);
-  return hasIssueNumber || hasTaskId;
+  return hasIssueNumber;
 }
 
 function parseArgs(argv) {
@@ -49,7 +48,7 @@ function main() {
     }
 
     if (!validateMessage(message)) {
-      console.error("Commit link FAIL: message must contain TASK-ID or #issue.");
+      console.error("Commit link FAIL: message must contain #issue.");
       console.error(`Message: ${message}`);
       process.exit(1);
     }

package/template/README.md

@@ -50,14 +50,14 @@
 ```bash
 npm run meta:verify
 npm run meta:branch
-npm run meta:task-start -- --task GOV-1 --slug api-redirect
+npm run meta:task-start -- --task #12 --slug api-redirect
 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":"DEV-12","status":"IN_PROGRESS"}'
-npm run meta:ops -- --command PREPARE_TASK_BRANCH --payload '{"task":"GOV-1","slug":"api-redirect"}'
+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
 ```
 
@@ -66,7 +66,7 @@ npm run meta:status
 `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` между текущей и базовой веткой и требует явного подтверждения при diff.
-Именование branch task ref: по умолчанию использовать префиксные ID (`GOV-1`, `REL-1`, `DOC-1`, `DEV-1`); для чистого GitHub issue fallback формат `issue-<number>`.
+Именование branch task ref: использовать GitHub issue ref в формате `issue-<number>`.
 `meta:mr-review` формирует сводный pre-merge отчёт по MR/PR, `meta:mr-review-approve` фиксирует финальный PASS после подтверждения пользователя.
 
 `meta:status` выдаёт сводный статус:

package/template/agents.md

@@ -148,7 +148,7 @@ Name: <agent role>
 - без подтверждения пользователя максимум допустимого статуса: `REVIEW`.
 - `SET_STATUS -> READY` разрешён только после `RUN_REVIEW_GATE: PASS_CONFIRMED`.
 - для задач реализации по умолчанию используется отдельная ветка `feature/*`; прямой рабочий поток на `develop`/`main` не допускается.
-- сообщение коммита обязано содержать ссылку на задачу (`TASK-ID` и/или `#issue-number`).
+- сообщение коммита обязано содержать ссылку на задачу (`#issue-number`).
 - `READY` означает: коммит сделан и отправлен (`push`) в `feature/*`, `release/*` или `hotfix/*` с открытым PR по правилам ветвления.
 - `DONE` означает: изменения интегрированы в `main`; для `release/*` и `hotfix/*` подтверждён back-merge в `develop`.
 - `PUBLISH` означает: релиз опубликован и доступен в последней версии пакета.
@@ -165,8 +165,8 @@ Name: <agent role>
 ## 10.2) Обязательная маршрутизация ветки для Agile Manager Agent
 Перед началом реализации агент обязан:
 1. Проверить веточный контекст через `meta:status`.
-2. Запустить branch-routing preflight через `meta:task-start -- --task <TASK-ID|#issue> --slug <slug> --kind atomic|feature|release|hotfix`.
-3. В названии рабочей ветки использовать task ref с префиксом (`GOV-1`, `REL-1`, `DOC-1`, `DEV-1`); если есть только issue number, использовать `issue-<number>`.
+2. Запустить branch-routing preflight через `meta:task-start -- --task <#issue> --slug <slug> --kind atomic|feature|release|hotfix`.
+3. В названии рабочей ветки использовать GitHub issue ref в формате `issue-<number>` (например, `feature/issue-21-canonical-github-issue-id`).
 4. Если задача относится к текущей feature-ветке (атомарная подзадача), продолжить в этой ветке только после подтверждения пользователя.
 5. Если задача не относится к текущей ветке, проверить незакоммиченные изменения и непушенные коммиты.
 6. Согласовать с пользователем способ обработки (`commit/stash/discard/push`).
@@ -199,7 +199,7 @@ Name: <agent role>
 19. Для статуса `DONE` подтверждена интеграция в `main`; для `release/*` и `hotfix/*` подтверждён back-merge в `develop`.
 20. Для статуса `PUBLISH` подтверждена публикация в последней версии.
 21. Для релиза обновлён публичный `CHANGELOG.md`.
-22. Коммит содержит ссылку на issue/task (`TASK-ID` или `#issue`).
+22. Коммит содержит ссылку на issue (`#issue`).
 23. Для branch routing собран e2e evidence по двум сценариям: `same feature` и `different feature`.
 24. Перед `--apply` подтверждена консистентность контекста `agents.md` (или явно подтверждён осознанный switch при diff).
 

package/template/tasks/task-status-log.md

@@ -1,3 +1,3 @@
 # Task Status Log
 
-- Format: YYYY-MM-DD | TASK-ID | STATUS | short note
+- Format: YYYY-MM-DD | #issue | STATUS | short note

package/template/tracker-command-template.md

@@ -26,7 +26,7 @@ Reason: Обязательная проверка соблюдения PRD и к
 Name: Governance Watchdog Agent
 
 Governance Watchdog Agent: verify governance gate,
-task <TASK-ID>,
+task <#issue>,
 required checks "prd_sections_complete, acceptance_defined, user_confirmation_policy_respected",
 result PASS
 ```
@@ -64,11 +64,11 @@ result PASS
 - merge разрешён только после `RUN_MR_REVIEW_GATE: PASS_CONFIRMED`;
 - для задач реализации по умолчанию используется отдельная ветка `feature/*`; прямой поток на `develop`/`main` запрещён;
 - перед началом реализации обязателен `PREPARE_TASK_BRANCH` (веточный preflight и user dialogue);
-- branch naming policy: использовать task ref с префиксом (`GOV-1`,`REL-1`,`DOC-1`,`DEV-1`); для issue-only задач использовать `issue-<number>`;
+- branch naming policy: использовать только GitHub issue ref в формате `issue-<number>`;
 - если задача атомарная и относится к текущей feature-ветке, допускается выполнение в текущей ветке после явного подтверждения пользователя;
 - если задача не относится к текущей ветке, требуется: проверить dirty/ahead, согласовать действие с пользователем, перейти на `develop` (или `main` для hotfix), обновить и создать новую ветку;
 - перед `--apply` обязателен контекстный check: сравнить `agents.md` текущей и базовой ветки, при diff запросить явное подтверждение пользователя;
-- сообщение коммита обязательно содержит `TASK-ID` и/или `#issue-number`.
+- сообщение коммита обязательно содержит `#issue-number`.
 
 Для GitHub трекера статус issue задаётся label-ом (одновременно только один статус из набора):
 - `TODO`
@@ -100,7 +100,7 @@ Reason: Нужна обязательная preflight-проверка проц
 Name: Governance Watchdog Agent
 
 Governance Watchdog Agent: verify governance gate,
-task DEV-12,
+task #12,
 checklist "PRD(Описание+Проверяемость), hard criteria, user confirmation policy",
 result PASS
 ```
@@ -115,7 +115,7 @@ Reason: Нужен обязательный pre-commit review.
 Name: Reviewer/Judge Agent
 
 Reviewer/Judge Agent: run review gate,
-task DEV-12,
+task #12,
 checklist "what_done_summary, critical_findings, potential_risks, issue_link_presence",
 result PASS_CANDIDATE,
 report "posted to issue #12"
@@ -133,7 +133,7 @@ Reason: Подтверждение review пользователем получ
 Name: Reviewer/Judge Agent
 
 Reviewer/Judge Agent: run review gate,
-task DEV-12,
+task #12,
 approve yes,
 result PASS_CONFIRMED
 ```
@@ -168,7 +168,7 @@ Name: Agile Manager Agent
 
 Agile Manager Agent: set status,
 tracker __DEFAULT_TRACKER__,
-task DEV-12,
+task #12,
 status IN_PROGRESS,
 reason "начата реализация"
 ```
@@ -184,9 +184,9 @@ Name: Agile Manager Agent
 
 Agile Manager Agent: prepare task branch,
 tracker __DEFAULT_TRACKER__,
-task "GOV-1",
+task "#12",
 task kind "atomic",
-command "npm run meta:task-start -- --task GOV-1 --slug api-redirect",
+command "npm run meta:task-start -- --task #12 --slug api-redirect",
 user dialogue "confirm branch context + dirty/ahead handling + agents.md context warning + switch decision"
 ```
 
@@ -201,7 +201,7 @@ Name: Agile Manager Agent
 
 Agile Manager Agent: set status,
 tracker __DEFAULT_TRACKER__,
-task DEV-12,
+task #12,
 status REVIEW,
 reason "готово к review gate"
 ```
@@ -257,9 +257,9 @@ Agile Manager Agent: commit by name,
 tracker __DEFAULT_TRACKER__,
 task "API редирект офферов",
 issue 12,
-commit message "DEV-12 | API редирект офферов (#12)",
+commit message "#12 | API редирект офферов",
 push yes,
-branch "feature/DEV-12-api-redirect",
+branch "feature/issue-12-api-redirect",
 open mr "optional",
 target status READY,
 what done "добавлен endpoint, тесты, обработка ошибок"
@@ -275,7 +275,7 @@ Reason: Нужен обязательный pre-merge review по MR/PR с пр
 Name: MR Review Agent
 
 MR Review Agent: run MR review gate,
-task DEV-12,
+task #12,
 pr 34,
 checklist "mr_context, task_linkage, prd_evidence, critical_findings, potential_risks",
 result PASS_CANDIDATE
@@ -293,7 +293,7 @@ Reason: Подтверждение MR review пользователем полу
 Name: MR Review Agent
 
 MR Review Agent: run MR review gate,
-task DEV-12,
+task #12,
 pr 34,
 approve yes,
 result PASS_CONFIRMED
@@ -310,7 +310,7 @@ Name: Agile Manager Agent
 
 Agile Manager Agent: set status,
 tracker __DEFAULT_TRACKER__,
-task DEV-12,
+task #12,
 status PUBLISH,
 reason "релиз опубликован в latest"
 ```
@@ -329,7 +329,7 @@ Close Task Approved: yes
 
 Agile Manager Agent: set status,
 tracker __DEFAULT_TRACKER__,
-task DEV-12,
+task #12,
 status DONE,
 reason "пользователь подтвердил закрытие"
 ```
@@ -345,7 +345,7 @@ Name: Agile Manager Agent
 
 Agile Manager Agent: assign sprint,
 tracker __DEFAULT_TRACKER__,
-task DEV-12,
+task #12,
 sprint SPRINT-3
 ```
 

package/tracker-command-template.md

@@ -26,7 +26,7 @@ Reason: Обязательная проверка соблюдения PRD и к
 Name: Governance Watchdog Agent
 
 Governance Watchdog Agent: verify governance gate,
-task <TASK-ID>,
+task <#issue>,
 required checks "prd_sections_complete, acceptance_defined, user_confirmation_policy_respected",
 result PASS
 ```
@@ -64,11 +64,11 @@ result PASS
 - merge разрешён только после `RUN_MR_REVIEW_GATE: PASS_CONFIRMED`;
 - для задач реализации по умолчанию используется отдельная ветка `feature/*`; прямой поток на `develop`/`main` запрещён;
 - перед началом реализации обязателен `PREPARE_TASK_BRANCH` (веточный preflight и user dialogue);
-- branch naming policy: использовать task ref с префиксом (`GOV-1`,`REL-1`,`DOC-1`,`DEV-1`); для issue-only задач использовать `issue-<number>`;
+- branch naming policy: использовать только GitHub issue ref в формате `issue-<number>`;
 - если задача атомарная и относится к текущей feature-ветке, допускается выполнение в текущей ветке после явного подтверждения пользователя;
 - если задача не относится к текущей ветке, требуется: проверить dirty/ahead, согласовать действие с пользователем, перейти на `develop` (или `main` для hotfix), обновить и создать новую ветку;
 - перед `--apply` обязателен контекстный check: сравнить `agents.md` текущей и базовой ветки, при diff запросить явное подтверждение пользователя;
-- сообщение коммита обязательно содержит `TASK-ID` и/или `#issue-number`.
+- сообщение коммита обязательно содержит `#issue-number`.
 
 Для GitHub трекера статус issue задаётся label-ом (одновременно только один статус из набора):
 - `TODO`
@@ -100,7 +100,7 @@ Reason: Нужна обязательная preflight-проверка проц
 Name: Governance Watchdog Agent
 
 Governance Watchdog Agent: verify governance gate,
-task DEV-12,
+task #12,
 checklist "PRD(Описание+Проверяемость), hard criteria, user confirmation policy",
 result PASS
 ```
@@ -115,7 +115,7 @@ Reason: Нужен обязательный pre-commit review.
 Name: Reviewer/Judge Agent
 
 Reviewer/Judge Agent: run review gate,
-task DEV-12,
+task #12,
 checklist "what_done_summary, critical_findings, potential_risks, issue_link_presence",
 result PASS_CANDIDATE,
 report "posted to issue #12"
@@ -133,7 +133,7 @@ Reason: Подтверждение review пользователем получ
 Name: Reviewer/Judge Agent
 
 Reviewer/Judge Agent: run review gate,
-task DEV-12,
+task #12,
 approve yes,
 result PASS_CONFIRMED
 ```
@@ -168,7 +168,7 @@ Name: Agile Manager Agent
 
 Agile Manager Agent: set status,
 tracker github,
-task DEV-12,
+task #12,
 status IN_PROGRESS,
 reason "начата реализация"
 ```
@@ -184,9 +184,9 @@ Name: Agile Manager Agent
 
 Agile Manager Agent: prepare task branch,
 tracker github,
-task "GOV-1",
+task "#12",
 task kind "atomic",
-command "npm run meta:task-start -- --task GOV-1 --slug api-redirect",
+command "npm run meta:task-start -- --task #12 --slug api-redirect",
 user dialogue "confirm branch context + dirty/ahead handling + agents.md context warning + switch decision"
 ```
 
@@ -201,7 +201,7 @@ Name: Agile Manager Agent
 
 Agile Manager Agent: set status,
 tracker github,
-task DEV-12,
+task #12,
 status REVIEW,
 reason "готово к review gate"
 ```
@@ -257,9 +257,9 @@ Agile Manager Agent: commit by name,
 tracker github,
 task "API редирект офферов",
 issue 12,
-commit message "DEV-12 | API редирект офферов (#12)",
+commit message "#12 | API редирект офферов",
 push yes,
-branch "feature/DEV-12-api-redirect",
+branch "feature/issue-12-api-redirect",
 open mr "optional",
 target status READY,
 what done "добавлен endpoint, тесты, обработка ошибок"
@@ -275,7 +275,7 @@ Reason: Нужен обязательный pre-merge review по MR/PR с пр
 Name: MR Review Agent
 
 MR Review Agent: run MR review gate,
-task DEV-12,
+task #12,
 pr 34,
 checklist "mr_context, task_linkage, prd_evidence, critical_findings, potential_risks",
 result PASS_CANDIDATE
@@ -293,7 +293,7 @@ Reason: Подтверждение MR review пользователем полу
 Name: MR Review Agent
 
 MR Review Agent: run MR review gate,
-task DEV-12,
+task #12,
 pr 34,
 approve yes,
 result PASS_CONFIRMED
@@ -310,7 +310,7 @@ Name: Agile Manager Agent
 
 Agile Manager Agent: set status,
 tracker github,
-task DEV-12,
+task #12,
 status PUBLISH,
 reason "релиз опубликован в latest"
 ```
@@ -329,7 +329,7 @@ Close Task Approved: yes
 
 Agile Manager Agent: set status,
 tracker github,
-task DEV-12,
+task #12,
 status DONE,
 reason "пользователь подтвердил закрытие"
 ```
@@ -345,7 +345,7 @@ Name: Agile Manager Agent
 
 Agile Manager Agent: assign sprint,
 tracker github,
-task DEV-12,
+task #12,
 sprint SPRINT-3
 ```
 
@@ -362,7 +362,7 @@ Status Agent: status snapshot,
 tracker github,
 source policy "github/mcp/custom -> external tracker first, local -> tasks first",
 include "trackers_used,current_sprint,current_task,current_branch_context,git_uncommitted,summary",
-command "node .meta-agents/scripts/sync-status.mjs"
+command "npm run meta:status"
 ```
 
 ### PREPARE_RELEASE_NOTE