@k0t0vich/meta-agents-template 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this package are documented in this file.
 
+## 0.1.10 - 2026-03-20
+
+### Fixed
+- Implemented GitHub TrackerGateway adapter operations instead of `not implemented` stubs (`CREATE_TASK`, `SET_STATUS`, `ASSIGN_SPRINT`, `COMMIT_BY_NAME`).
+- Added safe `dryRun` support for GitHub tracker operations to validate flows without side effects.
+- Added smoke regression check for `meta:ops CREATE_TASK` (dry-run) to prevent future regressions where command exists but adapter is stubbed.
+
+## 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.10",
   "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/.meta-agents/scripts/tracker/github.mjs

@@ -1,4 +1,549 @@
-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"); }
+import { execFileSync } from "node:child_process";
+import process from "node:process";
+
+const STATUS_LABELS = ["TODO", "IN_PROGRESS", "REVIEW", "READY", "BLOCKED", "DONE", "PUBLISH"];
+const STATUS_COLORS = {
+  IN_PROGRESS: "FBCA04",
+  REVIEW: "5319E7",
+  READY: "0E8A16",
+  BLOCKED: "B60205",
+  DONE: "1D76DB",
+  PUBLISH: "0052CC",
+};
+STATUS_COLORS.TODO = "D4C5F9";
+const FALLBACK_COLORS = {
+  type: "C2E0C6",
+  owner: "0E8A16",
+  tracker: "0052CC",
+  sprint: "F9D0C4",
+  default: "BFDADC",
+};
+
+function run(command, args, allowFailure = false) {
+  try {
+    return execFileSync(command, args, {
+      cwd: process.cwd(),
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+  } catch (error) {
+    if (allowFailure) {
+      return "";
+    }
+    const stderr = String(error?.stderr || "").trim();
+    const stdout = String(error?.stdout || "").trim();
+    throw new Error(`${command} ${args.join(" ")} failed: ${stderr || stdout || error.message}`);
+  }
+}
+
+function readJson(command, args, allowFailure = false) {
+  const raw = run(command, args, allowFailure);
+  if (!raw) {
+    return null;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`failed to parse JSON from '${command} ${args.join(" ")}': ${error.message}`);
+  }
+}
+
+function ensureGhReady() {
+  run("gh", ["--version"], false);
+  const auth = run("gh", ["auth", "status"], true);
+  if (!auth) {
+    throw new Error("gh is not authenticated. Run 'gh auth login' first.");
+  }
+}
+
+function toRepoArgs(repo) {
+  if (!repo) {
+    return [];
+  }
+  return ["--repo", String(repo)];
+}
+
+function toNonEmptyString(value) {
+  if (value === null || value === undefined) {
+    return "";
+  }
+  return String(value).trim();
+}
+
+function pickFirstNonEmpty(...values) {
+  for (const value of values) {
+    const normalized = toNonEmptyString(value);
+    if (normalized) {
+      return normalized;
+    }
+  }
+  return "";
+}
+
+function parseIssueNumber(value) {
+  if (typeof value === "number" && Number.isInteger(value) && value > 0) {
+    return String(value);
+  }
+
+  const source = toNonEmptyString(value);
+  if (!source) {
+    return "";
+  }
+
+  const direct = source.match(/^#?(\d+)$/);
+  if (direct) {
+    return direct[1];
+  }
+
+  const issueToken = source.match(/(?:^|[\/\s])issue-(\d+)(?:-|$|\s)/i);
+  if (issueToken) {
+    return issueToken[1];
+  }
+
+  const githubUrl = source.match(/\/issues\/(\d+)(?:$|[/?#])/i);
+  if (githubUrl) {
+    return githubUrl[1];
+  }
+
+  const ref = source.match(/#(\d+)/);
+  if (ref) {
+    return ref[1];
+  }
+
+  return "";
+}
+
+function normalizeStatus(value, fallback = "TODO") {
+  const normalized = toNonEmptyString(value).toUpperCase() || fallback;
+  if (!STATUS_LABELS.includes(normalized)) {
+    throw new Error(
+      `unsupported status '${normalized}'. Allowed: ${STATUS_LABELS.join(", ")}`,
+    );
+  }
+  return normalized;
+}
+
+function normalizeSprintLabel(value) {
+  const sprint = toNonEmptyString(value);
+  if (!sprint) {
+    return "";
+  }
+  if (/^sprint:/i.test(sprint)) {
+    return sprint.replace(/^sprint:/i, "sprint:");
+  }
+  return `sprint:${sprint}`;
+}
+
+function normalizeOwnerLabel(value) {
+  const owner = toNonEmptyString(value);
+  if (!owner) {
+    return "owner:Engineering Agent";
+  }
+  if (/^owner:/i.test(owner)) {
+    return owner.replace(/^owner:/i, "owner:");
+  }
+  return `owner:${owner}`;
+}
+
+function normalizeTypeLabel(value) {
+  const kind = toNonEmptyString(value).toLowerCase() || "task";
+  if (kind.startsWith("type:")) {
+    return kind;
+  }
+  return `type:${kind}`;
+}
+
+function parseLabelsInput(value) {
+  if (!value) {
+    return [];
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => toNonEmptyString(item)).filter(Boolean);
+  }
+
+  return String(value)
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function labelColor(name) {
+  if (STATUS_COLORS[name]) {
+    return STATUS_COLORS[name];
+  }
+
+  const lower = toNonEmptyString(name).toLowerCase();
+  if (lower.startsWith("type:")) {
+    return FALLBACK_COLORS.type;
+  }
+  if (lower.startsWith("owner:")) {
+    return FALLBACK_COLORS.owner;
+  }
+  if (lower.startsWith("tracker:")) {
+    return FALLBACK_COLORS.tracker;
+  }
+  if (lower.startsWith("sprint:")) {
+    return FALLBACK_COLORS.sprint;
+  }
+  return FALLBACK_COLORS.default;
+}
+
+function mergeUnique(values) {
+  return Array.from(new Set(values.map((item) => toNonEmptyString(item)).filter(Boolean)));
+}
+
+function buildCreateTaskLabels(payload) {
+  const status = normalizeStatus(payload.status || "TODO");
+  const labels = [
+    ...parseLabelsInput(payload.labels),
+    status,
+    normalizeTypeLabel(payload.type),
+    normalizeOwnerLabel(payload.owner || payload.ownerRole),
+    "tracker:github",
+  ];
+
+  const sprintLabel = normalizeSprintLabel(payload.sprint);
+  if (sprintLabel) {
+    labels.push(sprintLabel);
+  }
+
+  return mergeUnique(labels);
+}
+
+function renderBulletedValue(value, fallbackText) {
+  const text = toNonEmptyString(value);
+  if (!text) {
+    return `- ${fallbackText}`;
+  }
+  if (text.includes("\n")) {
+    const lines = text
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean);
+    if (lines.length === 0) {
+      return `- ${fallbackText}`;
+    }
+    return lines.map((line) => `- ${line}`).join("\n");
+  }
+  return `- ${text}`;
+}
+
+function renderCreateTaskBody(payload, labels) {
+  const description = renderBulletedValue(
+    payload.description,
+    "заполнить описание задачи",
+  );
+  const verifiability = renderBulletedValue(
+    payload.verifiability || payload.verification,
+    "strict: TBD; statistical: TBD; human: TBD",
+  );
+  const doneBlock = renderBulletedValue(
+    payload.done,
+    "[ ] Не начато",
+  );
+
+  const metadata = [];
+  metadata.push(`- tracker: github`);
+  metadata.push(`- labels: ${labels.join(", ")}`);
+  const sprintLabel = normalizeSprintLabel(payload.sprint);
+  if (sprintLabel) {
+    metadata.push(`- sprint: ${sprintLabel.replace(/^sprint:/i, "")}`);
+  }
+  const epicRef = parseIssueNumber(payload.epic || payload.linkToEpic || payload.parent);
+  if (epicRef) {
+    metadata.push(`- epic: #${epicRef}`);
+  }
+
+  return [
+    "## PRD Step",
+    "",
+    "### Описание",
+    description,
+    "",
+    "### Проверяемость",
+    verifiability,
+    "",
+    "### Что сделано",
+    doneBlock,
+    "",
+    "## Metadata",
+    ...metadata,
+  ].join("\n");
+}
+
+function ensureLabelExists(name, repo) {
+  const repoArgs = toRepoArgs(repo);
+  const exists = readJson(
+    "gh",
+    ["label", "list", ...repoArgs, "--search", name, "--limit", "100", "--json", "name"],
+    true,
+  );
+
+  if (Array.isArray(exists) && exists.some((item) => item?.name === name)) {
+    return;
+  }
+
+  const color = labelColor(name);
+  const description = "Auto-created by meta:ops github adapter";
+  const created = run(
+    "gh",
+    ["label", "create", name, "--color", color, "--description", description, ...repoArgs],
+    true,
+  );
+
+  if (!created) {
+    const existsAfter = readJson(
+      "gh",
+      ["label", "list", ...repoArgs, "--search", name, "--limit", "100", "--json", "name"],
+      true,
+    );
+    if (!(Array.isArray(existsAfter) && existsAfter.some((item) => item?.name === name))) {
+      throw new Error(`failed to create label '${name}'`);
+    }
+  }
+}
+
+function ensureLabelsExist(labels, repo) {
+  for (const label of labels) {
+    ensureLabelExists(label, repo);
+  }
+}
+
+function resolveTaskIssue(payload) {
+  const issue = parseIssueNumber(payload.task || payload.issue || payload.taskId || payload.id);
+  if (!issue) {
+    throw new Error("missing issue reference in payload (task/issue/taskId/id)");
+  }
+  return issue;
+}
+
+function getIssueLabels(issue, repo) {
+  const repoArgs = toRepoArgs(repo);
+  const issueData = readJson(
+    "gh",
+    ["issue", "view", String(issue), "--json", "labels", ...repoArgs],
+    false,
+  );
+  const labels = issueData?.labels || [];
+  return labels.map((item) => toNonEmptyString(item?.name)).filter(Boolean);
+}
+
+function removeAndAddIssueLabels(issue, repo, labelsToRemove, labelsToAdd) {
+  const repoArgs = toRepoArgs(repo);
+  const args = ["issue", "edit", String(issue), ...repoArgs];
+
+  for (const label of labelsToRemove) {
+    args.push("--remove-label", label);
+  }
+  for (const label of labelsToAdd) {
+    args.push("--add-label", label);
+  }
+
+  run("gh", args, false);
+}
+
+function commentIssue(issue, repo, body) {
+  const content = toNonEmptyString(body);
+  if (!content) {
+    return;
+  }
+  const repoArgs = toRepoArgs(repo);
+  run("gh", ["issue", "comment", String(issue), "--body", content, ...repoArgs], false);
+}
+
+function gitCurrentBranch() {
+  return run("git", ["rev-parse", "--abbrev-ref", "HEAD"], true);
+}
+
+function gitAdd(files) {
+  if (Array.isArray(files) && files.length > 0) {
+    run("git", ["add", ...files.map((item) => String(item))], false);
+    return;
+  }
+  run("git", ["add", "-A"], false);
+}
+
+function ensureStagedChanges() {
+  const staged = run("git", ["diff", "--cached", "--name-only"], true);
+  if (!staged) {
+    throw new Error("no staged changes to commit");
+  }
+}
+
+function buildCommitMessage(payload) {
+  const explicit = pickFirstNonEmpty(payload.message, payload.commitMessage);
+  if (explicit) {
+    return explicit;
+  }
+
+  const issue = parseIssueNumber(payload.task || payload.issue || payload.taskId || payload.id);
+  if (!issue) {
+    throw new Error(
+      "missing commit message. Provide payload.message or payload.issue/task to build '#<issue> <summary>'",
+    );
+  }
+
+  const summary = pickFirstNonEmpty(payload.shortName, payload.title, payload.name, "update");
+  return `#${issue} ${summary}`;
+}
+
+export async function createTask(payload = {}) {
+  const title = pickFirstNonEmpty(payload.shortName, payload.title, payload.name);
+  if (!title) {
+    throw new Error("missing task title (shortName/title/name)");
+  }
+
+  const repo = pickFirstNonEmpty(payload.repo);
+  const labels = buildCreateTaskLabels(payload);
+  const body = renderCreateTaskBody(payload, labels);
+
+  if (payload.dryRun) {
+    console.log(
+      JSON.stringify(
+        {
+          command: "CREATE_TASK",
+          mode: "dry-run",
+          repo: repo || "current",
+          title,
+          labels,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  ensureGhReady();
+  ensureLabelsExist(labels, repo);
+
+  const repoArgs = toRepoArgs(repo);
+  const args = ["issue", "create", "--title", title, "--body", body, ...repoArgs];
+  for (const label of labels) {
+    args.push("--label", label);
+  }
+
+  const issueUrl = run("gh", args, false);
+  const issue = parseIssueNumber(issueUrl);
+  const epic = parseIssueNumber(payload.epic || payload.linkToEpic || payload.parent);
+  if (issue && epic) {
+    commentIssue(issue, repo, `Linked to epic #${epic}.`);
+  }
+
+  console.log(`github CREATE_TASK: ${issueUrl}`);
+}
+
+export async function setStatus(payload = {}) {
+  const issue = resolveTaskIssue(payload);
+  const repo = pickFirstNonEmpty(payload.repo);
+  const targetStatus = normalizeStatus(payload.status);
+
+  if (payload.dryRun) {
+    console.log(
+      JSON.stringify(
+        {
+          command: "SET_STATUS",
+          mode: "dry-run",
+          repo: repo || "current",
+          issue,
+          status: targetStatus,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  ensureGhReady();
+  ensureLabelsExist([targetStatus], repo);
+
+  const currentLabels = getIssueLabels(issue, repo);
+  const removeStatuses = currentLabels.filter(
+    (label) => STATUS_LABELS.includes(label) && label !== targetStatus,
+  );
+
+  removeAndAddIssueLabels(issue, repo, removeStatuses, [targetStatus]);
+  const reason = pickFirstNonEmpty(payload.reason);
+  if (reason) {
+    commentIssue(issue, repo, `Status -> ${targetStatus}. Reason: ${reason}`);
+  }
+
+  console.log(`github SET_STATUS: #${issue} -> ${targetStatus}`);
+}
+
+export async function commitByName(payload = {}) {
+  const branch = gitCurrentBranch();
+  const expectedBranch = pickFirstNonEmpty(payload.branch);
+  if (expectedBranch && branch && branch !== expectedBranch) {
+    throw new Error(`branch mismatch: current '${branch}', expected '${expectedBranch}'`);
+  }
+
+  const message = buildCommitMessage(payload);
+  const files = Array.isArray(payload.files) ? payload.files : [];
+
+  if (payload.dryRun) {
+    console.log(
+      JSON.stringify(
+        {
+          command: "COMMIT_BY_NAME",
+          mode: "dry-run",
+          branch: branch || "unknown",
+          message,
+          files: files.length > 0 ? files : ["-A"],
+          push: Boolean(payload.push),
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  gitAdd(files);
+  ensureStagedChanges();
+  run("git", ["commit", "-m", message], false);
+  if (payload.push) {
+    run("git", ["push"], false);
+  }
+
+  console.log(`github COMMIT_BY_NAME: ${message}`);
+}
+
+export async function assignSprint(payload = {}) {
+  const issue = resolveTaskIssue(payload);
+  const repo = pickFirstNonEmpty(payload.repo);
+  const sprintLabel = normalizeSprintLabel(payload.sprint);
+  if (!sprintLabel) {
+    throw new Error("missing sprint in payload");
+  }
+
+  if (payload.dryRun) {
+    console.log(
+      JSON.stringify(
+        {
+          command: "ASSIGN_SPRINT",
+          mode: "dry-run",
+          repo: repo || "current",
+          issue,
+          sprint: sprintLabel,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  ensureGhReady();
+  ensureLabelsExist([sprintLabel], repo);
+
+  const currentLabels = getIssueLabels(issue, repo);
+  const removeSprints = currentLabels.filter(
+    (label) => label.toLowerCase().startsWith("sprint:") && label !== sprintLabel,
+  );
+  removeAndAddIssueLabels(issue, repo, removeSprints, [sprintLabel]);
+
+  console.log(`github ASSIGN_SPRINT: #${issue} -> ${sprintLabel}`);
+}

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)