@k0t0vich/meta-agents-template 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to this package are documented in this file.
 
+## 0.1.9 - 2026-03-20
+
+### Fixed
+- `meta-agents init` now creates `AGENTS.md` by default for new projects, so agent runtimes that expect uppercase bootstrap filename can load rules reliably.
+- Existing projects with pre-created `agents.md` remain non-destructive: init still updates only managed links block instead of replacing full file.
+- Bootstrap block now includes explicit required instruction to read canonical rules from npm-linked template files.
+- Branch context protection for `meta:task-start` now checks `AGENTS.md` with fallback to `agents.md`.
+- Local smoke now validates `AGENTS.md` presence and required bootstrap instruction in empty-folder install scenario.
+
 ## 0.1.8 - 2026-03-20
 
 ### Changed

package/README.md

@@ -31,7 +31,7 @@ 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` и добавляет ссылочный блок в `agents.md` вместо полной перезаписи.
+- `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 для агентного запуска
@@ -48,7 +48,7 @@ mkdir -p my-project && cd my-project && npm init -y && npm i -D @k0t0vich/meta-a
 Проверка, что шаблон и правила действительно развернуты:
 
 ```bash
-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"
+(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`
@@ -64,7 +64,7 @@ test -f agents.md && test -f .meta-agents/config/project-context.yaml && test -f
 my-project/
   package.json
   package-lock.json
-  agents.md
+  AGENTS.md        # или agents.md, если файл уже существовал
   .meta-agents/
     config/
       project-context.yaml
@@ -76,7 +76,7 @@ my-project/
       template/.meta-agents/scripts/*.mjs
 ```
 
-`agents.md` в проекте не перезаписывается целиком: `init` добавляет/обновляет в нём только ссылочный блок на правила из npm-пакета.
+Файл `AGENTS.md` (или уже существующий `agents.md`) не перезаписывается целиком: `init` добавляет/обновляет в нём только managed bootstrap-блок со ссылками на canonical rules из npm-пакета.
 
 ## Канонические команды
 0. `VERIFY_GOVERNANCE_GATE`
@@ -153,7 +153,7 @@ 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` между текущей и базовой веткой и требует явного подтверждения при diff.
+`meta:task-start` также делает context-protection check для `AGENTS.md` (fallback: `agents.md`) между текущей и базовой веткой и требует явного подтверждения при diff.
 Именование 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.

package/package.json

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

package/src/cli.mjs

@@ -279,12 +279,26 @@ export async function main(argv) {
     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.agents.created.length > 0) {
+      console.log(
+        `Agent bootstrap created: ${result.agents.created
+          .map((item) => path.basename(item))
+          .join(", ")}`,
+      );
+    }
+    if (result.agents.updated.length > 0) {
+      console.log(
+        `Agent bootstrap updated: ${result.agents.updated
+          .map((item) => path.basename(item))
+          .join(", ")}`,
+      );
+    }
+    if (result.agents.created.length === 0 && result.agents.updated.length === 0) {
+      console.log(
+        `Agent bootstrap already up to date: ${result.agents.unchanged
+          .map((item) => path.basename(item))
+          .join(", ")}`,
+      );
     }
     if (result.git.actions.length > 0) {
       console.log(`Git actions: ${result.git.actions.join("; ")}`);

package/src/init.mjs

@@ -13,6 +13,7 @@ const TEXT_EXTENSIONS = new Set([
   ".js",
 ]);
 const ROOT_CONFIG_FILES = ["project-context.yaml", "trackers.yaml"];
+const DEFAULT_AGENTS_FILENAME = "AGENTS.md";
 
 const AGENTS_LINK_BLOCK_START = "<!-- meta-agents-template:links:start -->";
 const AGENTS_LINK_BLOCK_END = "<!-- meta-agents-template:links:end -->";
@@ -219,6 +220,8 @@ function buildAgentsLinkBlock(packageName) {
   const lines = [
     AGENTS_LINK_BLOCK_START,
     "## Meta Agents Template (npm-linked)",
+    "ОБЯЗАТЕЛЬНО: перед выполнением любой команды сначала прочитай canonical rules по ссылкам ниже.",
+    "При конфликте локального текста и шаблона приоритет у canonical files из node_modules.",
     "Базовые правила шаблона:",
     `- [Template agents.md](${packageRoot}/template/agents.md)`,
     `- [Template tracker-command-template.md](${packageRoot}/template/tracker-command-template.md)`,
@@ -230,12 +233,22 @@ function buildAgentsLinkBlock(packageName) {
   return `${lines.join("\n")}\n`;
 }
 
-async function upsertAgentsLinks(targetDir, packageName) {
-  const agentsPath = path.join(targetDir, "agents.md");
+function buildAgentsBootstrapContent(fileName, block) {
+  return [
+    `# ${fileName}`,
+    "",
+    "Bootstrap file for agent runtime.",
+    "Before any task, read canonical rules from the npm-linked files in the block below.",
+    "",
+    block,
+  ].join("\n");
+}
+
+async function upsertAgentsLinksInFile(agentsPath, packageName) {
   const block = buildAgentsLinkBlock(packageName);
 
   if (!(await pathExists(agentsPath))) {
-    const content = ["# agents.md", "", block].join("\n");
+    const content = buildAgentsBootstrapContent(path.basename(agentsPath), block);
     await fs.writeFile(agentsPath, content, "utf8");
     return { created: true, updated: false, path: agentsPath };
   }
@@ -265,6 +278,31 @@ async function upsertAgentsLinks(targetDir, packageName) {
   return { created: false, updated, path: agentsPath };
 }
 
+async function detectAgentsFilePath(targetDir) {
+  try {
+    const entries = await fs.readdir(targetDir, { withFileTypes: true });
+    const match = entries.find(
+      (entry) => entry.isFile() && entry.name.toLowerCase() === "agents.md",
+    );
+    if (match) {
+      return path.join(targetDir, match.name);
+    }
+  } catch {
+    // target directory may not exist yet
+  }
+  return path.join(targetDir, DEFAULT_AGENTS_FILENAME);
+}
+
+async function upsertAgentsLinks(targetDir, packageName) {
+  const agentsPath = await detectAgentsFilePath(targetDir);
+  const result = await upsertAgentsLinksInFile(agentsPath, packageName);
+  return {
+    created: result.created ? [result.path] : [],
+    updated: result.updated ? [result.path] : [],
+    unchanged: !result.created && !result.updated ? [result.path] : [],
+  };
+}
+
 async function syncConfigFiles({ templateRoot, targetDir, values, force }) {
   const sourceConfigRoot = path.join(templateRoot, ".meta-agents", "config");
   const targetConfigRoot = path.join(targetDir, ".meta-agents", "config");

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

@@ -15,6 +15,7 @@ const TASK_KIND_MAP = {
   release: "release",
   hotfix: "hotfix",
 };
+const GOVERNANCE_CONTEXT_FILES = ["AGENTS.md", "agents.md"];
 
 function git(args, allowFailure = false) {
   try {
@@ -266,6 +267,16 @@ function readFileAtRef(ref, filePath) {
   return git(["show", `${ref}:${filePath}`], true);
 }
 
+function readGovernanceContextAtRef(ref) {
+  for (const filePath of GOVERNANCE_CONTEXT_FILES) {
+    const content = readFileAtRef(ref, filePath);
+    if (content) {
+      return { filePath, content };
+    }
+  }
+  return null;
+}
+
 function getContextWarnings(baseBranch) {
   const warnings = [];
   if (!baseBranch) {
@@ -280,19 +291,19 @@ function getContextWarnings(baseBranch) {
     return warnings;
   }
 
-  const currentAgents = readFileAtRef("HEAD", "agents.md");
-  const baseAgents = readFileAtRef(baseBranch, "agents.md");
+  const currentAgents = readGovernanceContextAtRef("HEAD");
+  const baseAgents = readGovernanceContextAtRef(baseBranch);
 
   if (!currentAgents || !baseAgents) {
     warnings.push(
-      "Cannot compare governance context file 'agents.md' between current and base branch (missing in one of refs).",
+      "Cannot compare governance context file 'AGENTS.md/agents.md' between current and base branch (missing in one of refs).",
     );
     return warnings;
   }
 
-  if (currentAgents !== baseAgents) {
+  if (currentAgents.content !== baseAgents.content) {
     warnings.push(
-      `Governance context differs: 'agents.md' in current branch is not equal to '${baseBranch}:agents.md'. Confirm switch before apply.`,
+      `Governance context differs: '${currentAgents.filePath}' in current branch is not equal to '${baseBranch}:${baseAgents.filePath}'. Confirm switch before apply.`,
     );
   }
 

package/template/README.md

@@ -3,7 +3,7 @@
 Проект инициализирован шаблоном `meta-agents-template`.
 
 ## Что уже подключено
-- `agents.md`: локальный входной файл с ссылками на canonical правила в npm-пакете;
+- `AGENTS.md` (или существующий `agents.md`): локальный bootstrap-файл с ссылками на canonical правила в npm-пакете;
 - `.meta-agents/config/project-context.yaml`: project name + выбранный tracker provider;
 - `.meta-agents/config/trackers.yaml`: lock tracker provider и доступные providers;
 - `meta:*` npm scripts, которые запускают canonical tooling из `node_modules/@k0t0vich/meta-agents-template/template/.meta-agents/scripts/*`.
@@ -64,7 +64,7 @@ npm run meta:status
 Если передать `--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` между текущей и базовой веткой и требует явного подтверждения при diff.
+`meta:task-start` также делает context-protection check для `AGENTS.md` (fallback: `agents.md`) между текущей и базовой веткой и требует явного подтверждения при diff.
 Именование branch task ref: использовать GitHub issue ref в формате `issue-<number>`.
 `meta:mr-review` формирует сводный pre-merge отчёт по MR/PR, `meta:mr-review-approve` фиксирует финальный PASS после подтверждения пользователя.
 

package/template/agents.md

@@ -172,7 +172,7 @@ Name: <agent role>
 6. Согласовать с пользователем способ обработки (`commit/stash/discard/push`).
 7. Переключиться на базовую ветку (`develop` или `main`) и обновить её.
 8. Создать новую рабочую ветку по Git Flow Lite.
-9. Перед переключением проверить консистентность `agents.md` между текущей и базовой веткой; при отличиях показать явное предупреждение и запросить подтверждение пользователя.
+9. Перед переключением проверить консистентность `AGENTS.md` (fallback: `agents.md`) между текущей и базовой веткой; при отличиях показать явное предупреждение и запросить подтверждение пользователя.
 
 Без этого preflight выполнение реализации запрещено.
 
@@ -201,7 +201,7 @@ Name: <agent role>
 21. Для релиза обновлён публичный `CHANGELOG.md`.
 22. Коммит следует формату `#issue-number <summary>` (issue ref в начале сообщения).
 23. Для branch routing собран e2e evidence по двум сценариям: `same feature` и `different feature`.
-24. Перед `--apply` подтверждена консистентность контекста `agents.md` (или явно подтверждён осознанный switch при diff).
+24. Перед `--apply` подтверждена консистентность контекста `AGENTS.md` (fallback: `agents.md`) или явно подтверждён осознанный switch при diff.
 
 Если хотя бы один критерий не выполнен, задача не принимается.
 

package/template/tracker-command-template.md

@@ -67,7 +67,7 @@ result PASS
 - branch naming policy: использовать только GitHub issue ref в формате `issue-<number>`;
 - если задача атомарная и относится к текущей feature-ветке, допускается выполнение в текущей ветке после явного подтверждения пользователя;
 - если задача не относится к текущей ветке, требуется: проверить dirty/ahead, согласовать действие с пользователем, перейти на `develop` (или `main` для hotfix), обновить и создать новую ветку;
-- перед `--apply` обязателен контекстный check: сравнить `agents.md` текущей и базовой ветки, при diff запросить явное подтверждение пользователя;
+- перед `--apply` обязателен контекстный check: сравнить `AGENTS.md` (fallback: `agents.md`) текущей и базовой ветки, при diff запросить явное подтверждение пользователя;
 - сообщение коммита обязательно следует формату `#issue-number <summary>` (issue ref в начале).
 
 Для GitHub трекера статус issue задаётся label-ом (одновременно только один статус из набора):
@@ -187,7 +187,7 @@ tracker __DEFAULT_TRACKER__,
 task "#12",
 task kind "atomic",
 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"
+user dialogue "confirm branch context + dirty/ahead handling + AGENTS.md context warning + switch decision"
 ```
 
 ### SET_STATUS -> REVIEW (обязателен перед review gate)