@haaaiawd/anws 1.2.3 → 1.2.5

package/README.md

@@ -24,7 +24,7 @@ A **structured workflow framework** for Agentic AI assistants, designed to solve
 | ---------------------- | ----------------------------------------------------------- | -------------------------------------------------------------- |
 | **Architecture Drift** | AI generates inconsistent patterns across the same codebase | `/genesis` forces PRD & architecture design first              |
 | **Spaghetti Code**     | AI lacks project context, writes code that doesn't fit      | Tasks include constraints & acceptance criteria                |
-| **Context Amnesia**    | New session = AI forgets all previous decisions             | `.agent/rules/agents.md` + versioned docs as persistent memory |
+| **Context Amnesia**    | New session = AI forgets all previous decisions             | `AGENTS.md` + versioned docs as persistent memory |
 | **Lack of Planning**   | Vibe Coding skips design, creates tech debt                 | Mandatory design-first workflow                                |
 
 ---
@@ -52,8 +52,8 @@ cd your-project
 anws update
 ```
 
-> `anws update` overwrites all managed workflow/skill files to the latest version while **preserving** your `agents.md`.
-> If the `agents.md` template has new content, an `agents.md.new` file will be generated for you to merge manually.
+> `anws update` overwrites all managed workflow/skill files to the latest version while **preserving** your `AGENTS.md`.
+> If the `AGENTS.md` template has new content, an `AGENTS.md.new` file will be generated for you to merge manually.
 
 ### Your First Project 🐣
 
@@ -214,9 +214,8 @@ Just speak naturally. Antigravity will automatically select and run the right wo
 
 ```
 your-project/
+├── AGENTS.md          # 🧠 AI's anchor point
 ├── .agent/
-│   ├── rules/
-│   │   └── agents.md          # 🧠 AI's anchor point
 │   ├── workflows/             # Workflow definitions
 │   │   ├── genesis.md
 │   │   ├── scout.md

package/bin/cli.js

@@ -34,11 +34,16 @@ const { values, positionals } = parseArgs({
   options: {
     version: { type: 'boolean', short: 'v', default: false },
     help:    { type: 'boolean', short: 'h', default: false },
+    yes:     { type: 'boolean', short: 'y', default: false },
   },
   strict: false,
   allowPositionals: true,
 });
 
+if (values.yes) {
+  global.__ANWS_FORCE_YES = true;
+}
+
 // ─── 命令路由 ─────────────────────────────────────────────────────────────────
 async function main() {
   if (values.version) {

package/lib/agents.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { warn, blank } = require('./output');
+
+async function pathExists(targetPath) {
+  return fs.access(targetPath).then(() => true).catch(() => false);
+}
+
+async function getAgentsState(cwd) {
+  const legacyPath = path.join(cwd, '.agent', 'rules', 'agents.md');
+  const rootPath = path.join(cwd, 'AGENTS.md');
+
+  return {
+    legacyPath,
+    rootPath,
+    legacyExists: await pathExists(legacyPath),
+    rootExists: await pathExists(rootPath)
+  };
+}
+
+async function resolveAgentsInstall({ cwd, askMigrate, forceYes = false }) {
+  const state = await getAgentsState(cwd);
+
+  if (!state.legacyExists) {
+    return { ...state, shouldWriteRootAgents: true, shouldWarnMigration: false };
+  }
+
+  const migrate = forceYes ? true : await askMigrate();
+  return {
+    ...state,
+    shouldWriteRootAgents: migrate ? !state.rootExists : false,
+    shouldWarnMigration: migrate
+  };
+}
+
+function printLegacyMigrationWarning() {
+  blank();
+  warn('Please manually copy your custom rules from .agent/rules/agents.md to the root AGENTS.md');
+  warn('After copying, you can safely delete the old .agent/rules/agents.md file.');
+  blank();
+}
+
+module.exports = {
+  getAgentsState,
+  resolveAgentsInstall,
+  printLegacyMigrationWarning,
+  pathExists
+};

package/lib/init.js

@@ -1,186 +1,221 @@
-'use strict';
-
-const fs = require('node:fs/promises');
-const path = require('node:path');
-const crypto = require('node:crypto');
-const { copyDir } = require('./copy');
-const { MANAGED_FILES, USER_PROTECTED_FILES } = require('./manifest');
-const { success, warn, info, fileLine, skippedLine, blank, logo } = require('./output');
-
-/**
- * anws init — 将工作流系统写入当前项目
- */
-async function init() {
-  const cwd = process.cwd();
-  const srcRoot = path.join(__dirname, '..', 'templates', '.agent');
-  const destRoot = path.join(cwd, '.agent');
-
-  // ── 冲突检测（T1.2.3 在此处插入冲突分支）──────────────────────────────────
-  const conflicting = await findConflicts(cwd);
-  if (conflicting.length > 0) {
-    const confirmed = await askOverwrite(conflicting.length);
-    if (!confirmed) {
-      blank();
-      info('Aborted. No files were changed.');
-      process.exit(0);
-    }
-    // 仅覆盖托管文件（用户自有文件不受影响）
-    const { written: updated, skipped } = await overwriteManaged(srcRoot, cwd);
-    await storeAgentsTemplateHash(srcRoot, cwd);
-    printSummary(updated, skipped, 'updated');
-    return;
-  }
-  // ── 无冲突:直接复制 ─────────────────────────────────────────────────────────
-
-  logo();
-  info('Initializing Antigravity Workflow System...');
-  blank();
-
-  const written = await copyDir(srcRoot, destRoot);
-
-  // 存储 agents.md 模板指纹，供后续 update 检测模板变化
-  await storeAgentsTemplateHash(srcRoot, cwd);
-
-  // 打印文件列表
-  for (const absPath of written) {
-    const rel = path.relative(cwd, absPath).replace(/\\/g, '/');
-    fileLine(rel);
-  }
-
-  blank();
-  success(`Done! ${written.length} files written to .agent/`);
-  printNextSteps();
-}
-
-// ─── 辅助函数 ──────────────────────────────────────────────────────────────────
-
-/**
- * 找出 cwd 中已存在的托管文件列表。
- * @returns {Promise<string[]>} 已存在的托管文件相对路径数组
- */
-async function findConflicts(cwd) {
-  const conflicts = [];
-  for (const rel of MANAGED_FILES) {
-    const abs = path.join(cwd, rel);
-    const exists = await fs.access(abs).then(() => true).catch(() => false);
-    if (exists) conflicts.push(rel);
-  }
-  return conflicts;
-}
-
-/**
- * 交互式询问用户是否覆盖（默认 N）。
- * 非 TTY 环境（如 CI）自动返回 false。
- * @returns {Promise<boolean>}
- */
-async function askOverwrite(count) {
-  // 非 TTY 环境：默认不覆盖，防止 CI 挂起
-  if (!process.stdin.isTTY) {
-    warn(`${count} managed file(s) already exist. Non-TTY: skipping overwrite.`);
-    return false;
-  }
-
-  const readline = require('node:readline');
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-
-  return new Promise((resolve) => {
-    rl.question(
-      `\n\u26a0  ${count} managed file(s) already exist. Overwrite? [y/N] `,
-      (answer) => {
-        rl.close();
-        resolve(answer.trim().toLowerCase() === 'y');
-      }
-    );
-  });
-}
-
-/**
- * 仅覆盖 MANAGED_FILES 清单内的文件，用户自有文件不受影响。
- * USER_PROTECTED_FILES 中的文件即便冲突也跳过，保留用户修改。
- * @returns {{ written: string[], skipped: string[] }}
- */
-async function overwriteManaged(srcRoot, cwd) {
-  const srcBase = path.dirname(srcRoot); // templates/
-  const written = [];
-  const skipped = [];
-
-  for (const rel of MANAGED_FILES) {
-    // 受保护文件：文件已存在时跳过，交给用户自行维护
-    if (USER_PROTECTED_FILES.includes(rel)) {
-      const destPath = path.join(cwd, rel);
-      const exists = await fs.access(destPath).then(() => true).catch(() => false);
-      if (exists) {
-        skipped.push(rel);
-        continue;
-      }
-    }
-
-    const srcPath = path.join(srcBase, rel);
-    const destPath = path.join(cwd, rel);
-
-    await fs.mkdir(path.dirname(destPath), { recursive: true });
-    const srcExists = await fs.access(srcPath).then(() => true).catch(() => false);
-    if (srcExists) {
-      await fs.copyFile(srcPath, destPath);
-      written.push(rel);
-    }
-  }
-
-  return { written, skipped };
-}
-
-/**
- * 打印操作摘要（更新场景）。
- * @param {string[]} files  已写入的文件
- * @param {string[]} skipped 受保护跳过的文件
- * @param {string}  action
- */
-function printSummary(files, skipped = [], action) {
-  const verb = action === 'updated' ? 'Updating' : 'Writing';
-  blank();
-  info(`${verb} files...`);
-  blank();
-  for (const rel of files) {
-    fileLine(rel.replace(/\\/g, '/'));
-  }
-  if (skipped.length > 0) {
-    blank();
-    info('Skipped (project-specific, preserved):');
-    for (const rel of skipped) {
-      skippedLine(rel.replace(/\\/g, '/'));
-    }
-  }
-  blank();
-  success(`Done! ${files.length} file(s) ${action}${skipped.length > 0 ? `, ${skipped.length} skipped` : ''}.`);
-  if (action === 'updated') {
-    info('Managed files have been updated to the latest version.');
-  }
-}
-
-function printNextSteps() {
-  blank();
-  info('Next steps:');
-  info('  1. Read .agent/rules/agents.md to understand the system');
-  info('  2. Run /quickstart in your AI assistant to analyze and start the workflow');
-}
-
-/**
- * 存储 agents.md 模板的 MD5 指纹。
- * 供 `anws update` 检测模板是否在版本间发生了变化。
- * @param {string} srcRoot  模板 .agent/ 目录绝对路径
- * @param {string} cwd      项目根目录
- */
-async function storeAgentsTemplateHash(srcRoot, cwd) {
-  const templatePath = path.join(srcRoot, 'rules', 'agents.md');
-  const hashPath = path.join(cwd, '.agent', 'rules', '.agents-template-hash');
-
-  try {
-    const content = await fs.readFile(templatePath, 'utf-8');
-    const hash = crypto.createHash('md5').update(content).digest('hex');
-    await fs.writeFile(hashPath, hash, 'utf-8');
-  } catch {
-    // 模板文件不存在时静默失败（不应该发生）
-  }
-}
-
-module.exports = init;
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { copyDir } = require('./copy');
+const { MANAGED_FILES, USER_PROTECTED_FILES } = require('./manifest');
+const { resolveAgentsInstall, printLegacyMigrationWarning, pathExists } = require('./agents');
+const { success, warn, info, fileLine, skippedLine, blank, logo } = require('./output');
+
+/**
+ * anws init — 将工作流系统写入当前项目
+ */
+async function init() {
+  const cwd = process.cwd();
+  const srcRoot = path.join(__dirname, '..', 'templates', '.agent');
+  const destRoot = path.join(cwd, '.agent');
+  const srcAgents = path.join(__dirname, '..', 'templates', 'AGENTS.md');
+
+  const agentsDecision = await resolveAgentsInstall({
+    cwd,
+    askMigrate,
+    forceYes: !!global.__ANWS_FORCE_YES
+  });
+
+  // ── 冲突检测（T1.2.3 在此处插入冲突分支）──────────────────────────────────
+  const conflicting = await findConflicts(cwd);
+  if (conflicting.length > 0) {
+    const confirmed = await askOverwrite(conflicting.length);
+    if (!confirmed) {
+      blank();
+      info('Aborted. No files were changed.');
+      process.exit(0);
+    }
+    // 仅覆盖托管文件（用户自有文件不受影响）
+    const { written: updated, skipped } = await overwriteManaged(srcRoot, cwd, {
+      srcAgents,
+      shouldWriteRootAgents: agentsDecision.shouldWriteRootAgents
+    });
+    if (agentsDecision.shouldWarnMigration) {
+      printLegacyMigrationWarning();
+    }
+    printSummary(updated, skipped, 'updated');
+    return;
+  }
+  // ── 无冲突:直接复制 ─────────────────────────────────────────────────────────
+
+  logo();
+  info('Initializing Antigravity Workflow System...');
+  blank();
+
+  const writtenFiles = await copyDir(srcRoot, destRoot);
+  const written = Array.isArray(writtenFiles) ? writtenFiles : [];
+
+  if (agentsDecision.shouldWriteRootAgents) {
+    const destAgents = path.join(cwd, 'AGENTS.md');
+    try {
+      await fs.copyFile(srcAgents, destAgents);
+      written.push(destAgents);
+    } catch (e) {
+      // 忽略
+    }
+  }
+
+  if (agentsDecision.shouldWarnMigration) {
+    printLegacyMigrationWarning();
+  }
+
+  // 打印文件列表
+  for (const absPath of written) {
+    const rel = path.relative(cwd, absPath).replace(/\\/g, '/');
+    fileLine(rel);
+  }
+
+  blank();
+  success(`Done! ${written.length} files written to .agent/`);
+  printNextSteps();
+}
+
+// ─── 辅助函数 ──────────────────────────────────────────────────────────────────
+
+/**
+ * 找出 cwd 中已存在的托管文件列表。
+ * @returns {Promise<string[]>} 已存在的托管文件相对路径数组
+ */
+async function findConflicts(cwd) {
+  const conflicts = [];
+  for (const rel of MANAGED_FILES) {
+    const abs = path.join(cwd, rel);
+    const exists = await pathExists(abs);
+    if (exists) conflicts.push(rel);
+  }
+  return conflicts;
+}
+
+/**
+ * 交互式询问用户是否覆盖（默认 N）。
+ * 非 TTY 环境（如 CI）自动返回 false。
+ * @returns {Promise<boolean>}
+ */
+async function askOverwrite(count) {
+  if (global.__ANWS_FORCE_YES) return true;
+
+  // 非 TTY 环境：默认不覆盖，防止 CI 挂起
+  if (!process.stdin.isTTY) {
+    warn(`${count} managed file(s) already exist. Non-TTY: skipping overwrite.`);
+    return false;
+  }
+
+  const readline = require('node:readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  return new Promise((resolve) => {
+    rl.question(
+      `\n\u26a0  ${count} managed file(s) already exist. Overwrite? [y/N] `,
+      (answer) => {
+        rl.close();
+        resolve(answer.trim().toLowerCase() === 'y');
+      }
+    );
+  });
+}
+
+async function askMigrate() {
+  if (global.__ANWS_FORCE_YES) return true;
+
+  if (!process.stdin.isTTY) {
+    return false;
+  }
+
+  const readline = require('node:readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  return new Promise((resolve) => {
+    rl.question(
+      '\n\u26a0 Legacy .agent/rules/agents.md detected. Do you want to migrate to root AGENTS.md? [y/N] ',
+      (answer) => {
+        rl.close();
+        resolve(answer.trim().toLowerCase() === 'y');
+      }
+    );
+  });
+}
+
+/**
+ * 仅覆盖 MANAGED_FILES 清单内的文件，用户自有文件不受影响。
+ * USER_PROTECTED_FILES 中的文件即便冲突也跳过，保留用户修改。
+ * @returns {{ written: string[], skipped: string[] }}
+ */
+async function overwriteManaged(srcRoot, cwd, options = {}) {
+  const srcBase = path.dirname(srcRoot); // templates/
+  const written = [];
+  const skipped = [];
+  const shouldWriteRootAgents = options.shouldWriteRootAgents !== false;
+  const srcAgents = options.srcAgents || path.join(srcBase, 'AGENTS.md');
+
+  for (const rel of MANAGED_FILES) {
+    if (rel === 'AGENTS.md' && !shouldWriteRootAgents) {
+      skipped.push(rel);
+      continue;
+    }
+
+    // 受保护文件：文件已存在时跳过，交给用户自行维护
+    if (USER_PROTECTED_FILES.includes(rel)) {
+      const destPath = path.join(cwd, rel);
+      const exists = await pathExists(destPath);
+      if (exists) {
+        skipped.push(rel);
+        continue;
+      }
+    }
+
+    const srcPath = rel === 'AGENTS.md' ? srcAgents : path.join(srcBase, rel);
+    const destPath = path.join(cwd, rel);
+
+    await fs.mkdir(path.dirname(destPath), { recursive: true });
+    const srcExists = await pathExists(srcPath);
+    if (srcExists) {
+      await fs.copyFile(srcPath, destPath);
+      written.push(rel);
+    }
+  }
+
+  return { written, skipped };
+}
+
+/**
+ * 打印操作摘要（更新场景）。
+ * @param {string[]} files  已写入的文件
+ * @param {string[]} skipped 受保护跳过的文件
+ * @param {string}  action
+ */
+function printSummary(files, skipped = [], action) {
+  const verb = action === 'updated' ? 'Updating' : 'Writing';
+  blank();
+  info(`${verb} files...`);
+  blank();
+  for (const rel of files) {
+    fileLine(rel.replace(/\\/g, '/'));
+  }
+  if (skipped.length > 0) {
+    blank();
+    info('Skipped (project-specific, preserved):');
+    for (const rel of skipped) {
+      skippedLine(rel.replace(/\\/g, '/'));
+    }
+  }
+  blank();
+  success(`Done! ${files.length} file(s) ${action}${skipped.length > 0 ? `, ${skipped.length} skipped` : ''}.`);
+  if (action === 'updated') {
+    info('Managed files have been updated to the latest version.');
+  }
+}
+
+function printNextSteps() {
+  blank();
+  info('Next steps:');
+  info('  1. Read AGENTS.md to understand the system');
+  info('  2. Run /quickstart in your AI assistant to analyze and start the workflow');
+}
+
+module.exports = init;

package/lib/manifest.js

@@ -6,7 +6,7 @@
  * 此数组列出 anws 包负责管理的所有文件路径（相对于目标项目根目录）。
  */
 const MANAGED_FILES = [
-  '.agent/rules/agents.md',
+  'AGENTS.md',
   '.agent/skills/build-inspector/SKILL.md',
   '.agent/skills/complexity-guard/references/anti_patterns.md',
   '.agent/skills/complexity-guard/SKILL.md',
@@ -53,7 +53,7 @@ const MANAGED_FILES = [
  * anws update 默认会跳过这些文件。
  */
 const USER_PROTECTED_FILES = [
-  '.agent/rules/agents.md'
+  'AGENTS.md'
 ];
 
 module.exports = {

package/lib/update.js

@@ -1,153 +1,147 @@
-'use strict';
-
-const fs = require('node:fs/promises');
-const path = require('node:path');
-const crypto = require('node:crypto');
-const { MANAGED_FILES, USER_PROTECTED_FILES } = require('./manifest');
-const { success, warn, error, info, fileLine, skippedLine, blank, logo } = require('./output');
-
-/**
- * anws update — 将当前项目的托管文件更新到最新版本
- */
-async function update() {
-  const cwd = process.cwd();
-  const agentDir = path.join(cwd, '.agent');
-
-  // 检查 .agent/ 是否存在
-  const agentExists = await fs.access(agentDir).then(() => true).catch(() => false);
-  if (!agentExists) {
-    logo();
-    error('No .agent/ found in current directory.');
-    info('Run `anws init` first to set up the workflow system.');
-    process.exit(1);
-  }
-
-  // 询问确认
-  const confirmed = await askUpdate();
-  if (!confirmed) {
-    blank();
-    info('Aborted. No files were changed.');
-    process.exit(0);
-  }
-
-  logo();
-  // 仅覆盖托管文件；USER_PROTECTED_FILES 永远跳过
-  const srcRoot = path.join(__dirname, '..', 'templates', '.agent');
-  const updated = [];
-  const skipped = [];
-
-  for (const rel of MANAGED_FILES) {
-    if (USER_PROTECTED_FILES.includes(rel)) {
-      skipped.push(rel);
-      continue;
-    }
-
-    const srcPath = path.join(path.dirname(srcRoot), rel);
-    const destPath = path.join(cwd, rel);
-
-    const srcExists = await fs.access(srcPath).then(() => true).catch(() => false);
-    if (!srcExists) continue;
-
-    await fs.mkdir(path.dirname(destPath), { recursive: true });
-    await fs.copyFile(srcPath, destPath);
-    updated.push(rel);
-  }
-
-  // 打印摘要
-  blank();
-  info('Updated files:');
-  blank();
-  for (const rel of updated) {
-    fileLine(rel.replace(/\\/g, '/'));
-  }
-  if (skipped.length > 0) {
-    blank();
-    info('Skipped (project-specific, preserved):');
-    for (const rel of skipped) {
-      skippedLine(rel.replace(/\\/g, '/'));
-    }
-  }
-
-  // 检查 agents.md 模板是否有变更，提供 .new 文件供用户合并
-  const agentsMerged = await checkAgentsTemplate(cwd, srcRoot);
-
-  blank();
-  success(`Done! ${updated.length} file(s) updated${skipped.length > 0 ? `, ${skipped.length} skipped` : ''}.`);
-  info('Managed files have been updated to the latest version.');
-  info('Your custom files in .agent/ were not touched.');
-
-  if (agentsMerged) {
-    blank();
-    warn('agents.md template has changed!');
-    info('A new template has been saved to:');
-    info('  .agent/rules/agents.md.new');
-    blank();
-    info('Please review and merge the changes into your agents.md.');
-    info('After merging, delete agents.md.new.');
-  }
-}
-
-/**
- * 交互式确认更新操作（默认 N）。
- */
-async function askUpdate() {
-  if (!process.stdin.isTTY) {
-    warn('Non-TTY environment detected. Skipping update to avoid accidental overwrites.');
-    return false;
-  }
-
-  const readline = require('node:readline');
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-
-  return new Promise((resolve) => {
-    rl.question(
-      '\n\u26a0 This will overwrite all managed .agent/ files. Continue? [y/N] ',
-      (answer) => {
-        rl.close();
-        resolve(answer.trim().toLowerCase() === 'y');
-      }
-    );
-  });
-}
-
-/**
- * 检查 agents.md 模板是否相比上次安装/更新有变化。
- * 用 hash 文件记录上次模板指纹，与新模板比较。
- * 如果有变化 → 写入 agents.md.new + 更新 hash。
- *
- * @param {string} cwd       项目根目录
- * @param {string} srcRoot   模板 .agent/ 目录
- * @returns {Promise<boolean>} 是否产生了 .new 文件
- */
-async function checkAgentsTemplate(cwd, srcRoot) {
-  const templatePath = path.join(path.dirname(srcRoot), '.agent', 'rules', 'agents.md');
-  const hashPath = path.join(cwd, '.agent', 'rules', '.agents-template-hash');
-  const newPath = path.join(cwd, '.agent', 'rules', 'agents.md.new');
-
-  const templateExists = await fs.access(templatePath).then(() => true).catch(() => false);
-  if (!templateExists) return false;
-
-  const templateContent = await fs.readFile(templatePath, 'utf-8');
-  const newHash = crypto.createHash('md5').update(templateContent).digest('hex');
-
-  // 读取上次存储的 hash
-  let oldHash = null;
-  try {
-    oldHash = (await fs.readFile(hashPath, 'utf-8')).trim();
-  } catch {
-    // hash 文件不存在（首次 update 或旧版本安装）
-  }
-
-  if (oldHash === newHash) {
-    return false; // 模板没变化
-  }
-
-  // 模板有变化 → 写入 .new 供用户合并
-  await fs.writeFile(newPath, templateContent, 'utf-8');
-  // 更新 hash 记录
-  await fs.writeFile(hashPath, newHash, 'utf-8');
-
-  return true;
-}
-
-module.exports = update;
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { MANAGED_FILES, USER_PROTECTED_FILES } = require('./manifest');
+const { resolveAgentsInstall, printLegacyMigrationWarning, pathExists } = require('./agents');
+const { success, warn, error, info, fileLine, skippedLine, blank, logo } = require('./output');
+
+/**
+ * anws update — 将当前项目的托管文件更新到最新版本
+ */
+async function update() {
+  const cwd = process.cwd();
+  const agentDir = path.join(cwd, '.agent');
+
+  // 检查 .agent/ 是否存在
+  const agentExists = await pathExists(agentDir);
+  if (!agentExists) {
+    logo();
+    error('No .agent/ found in current directory.');
+    info('Run `anws init` first to set up the workflow system.');
+    process.exit(1);
+  }
+
+  // 询问确认
+  const confirmed = await askUpdate();
+  if (!confirmed) {
+    blank();
+    info('Aborted. No files were changed.');
+    process.exit(0);
+  }
+
+  logo();
+  // 仅覆盖托管文件；USER_PROTECTED_FILES 永远跳过
+  const srcRoot = path.join(__dirname, '..', 'templates', '.agent');
+  const srcAgents = path.join(__dirname, '..', 'templates', 'AGENTS.md');
+  const agentsDecision = await resolveAgentsInstall({
+    cwd,
+    askMigrate,
+    forceYes: !!global.__ANWS_FORCE_YES
+  });
+
+  if (!agentsDecision.shouldWriteRootAgents && agentsDecision.legacyExists) {
+    info('Keeping legacy .agent/rules/agents.md. Will not pull root AGENTS.md.');
+  }
+  if (agentsDecision.shouldWarnMigration) {
+    printLegacyMigrationWarning();
+  }
+
+  const updated = [];
+  const skipped = [];
+
+  for (const rel of MANAGED_FILES) {
+    if (rel === 'AGENTS.md' && !agentsDecision.shouldWriteRootAgents) {
+      skipped.push(rel);
+      continue;
+    }
+
+    if (USER_PROTECTED_FILES.includes(rel)) {
+      if (!(rel === 'AGENTS.md' && agentsDecision.shouldWriteRootAgents && !agentsDecision.rootExists)) {
+        skipped.push(rel);
+        continue;
+      }
+    }
+
+    const srcPath = rel === 'AGENTS.md' ? srcAgents : path.join(path.dirname(srcRoot), rel);
+    const destPath = path.join(cwd, rel);
+
+    const srcExists = await pathExists(srcPath);
+    if (!srcExists) continue;
+
+    await fs.mkdir(path.dirname(destPath), { recursive: true });
+    await fs.copyFile(srcPath, destPath);
+    updated.push(rel);
+  }
+
+  // 打印摘要
+  blank();
+  info('Updated files:');
+  blank();
+  for (const rel of updated) {
+    fileLine(rel.replace(/\\/g, '/'));
+  }
+  if (skipped.length > 0) {
+    blank();
+    info('Skipped (project-specific, preserved):');
+    for (const rel of skipped) {
+      skippedLine(rel.replace(/\\/g, '/'));
+    }
+  }
+
+  blank();
+  success(`Done! ${updated.length} file(s) updated${skipped.length > 0 ? `, ${skipped.length} skipped` : ''}.`);
+  info('Managed files have been updated to the latest version.');
+  info('Your custom files in .agent/ were not touched.');
+}
+
+/**
+ * 交互式确认更新操作（默认 N）。
+ */
+async function askUpdate() {
+  if (global.__ANWS_FORCE_YES) return true;
+
+  if (!process.stdin.isTTY) {
+    warn('Non-TTY environment detected. Skipping update to avoid accidental overwrites.');
+    return false;
+  }
+
+  const readline = require('node:readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  return new Promise((resolve) => {
+    rl.question(
+      '\n\u26a0 This will overwrite all managed .agent/ files. Continue? [y/N] ',
+      (answer) => {
+        rl.close();
+        resolve(answer.trim().toLowerCase() === 'y');
+      }
+    );
+  });
+}
+
+/**
+ * 询问用户是否同意迁移 agents.md
+ */
+async function askMigrate() {
+  if (global.__ANWS_FORCE_YES) return true;
+
+  if (!process.stdin.isTTY) {
+    return false;
+  }
+
+  const readline = require('node:readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  return new Promise((resolve) => {
+    rl.question(
+      '\n\u26a0 Legacy .agent/rules/agents.md detected. Do you want to migrate to root AGENTS.md? [y/N] ',
+      (answer) => {
+        rl.close();
+        resolve(answer.trim().toLowerCase() === 'y');
+      }
+    );
+  });
+}
+
+module.exports = update;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haaaiawd/anws",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "A spec-driven workflow framework for AI-assisted development. Empowers prompt engineers to build production-ready software through structured PRD → Architecture → Task decomposition. Designed for Antigravity to enforce design-first principles and prevent architectural drift in vibe coding.",
   "keywords": [
     "antigravity",

package/templates/.agent/workflows/blueprint.md

@@ -232,11 +232,11 @@ graph TD
 
 ## Step 6: 生成文档
 
-**目标**: 保存最终的任务清单，并**更新 .agent/rules/agents.md**。
+**目标**: 保存最终的任务清单，并**更新 AGENTS.md**。
 
 1.  **保存**: 将内容保存到 `genesis/v{N}/05_TASKS.md`
 2.  **验证**: 确保文件包含所有任务、验收标准和依赖图。
-3.  **更新 .agent/rules/agents.md "当前状态"**:
+3.  **更新 AGENTS.md "当前状态"**:
     - 活动任务清单: `genesis/v{N}/05_TASKS.md`
     - 最近一次更新: `{Today}`
     - 写入初始波次建议，让 `/forge` 可以直接启动：
@@ -254,7 +254,7 @@ graph TD
 - ✅ 任务间的输入/输出是否对齐（接口追溯）？
 - ✅ 是否生成了 Mermaid 依赖图？
 - ✅ User Story Overlay 已生成，覆盖 GAP 已补充？
-- ✅ 已更新 .agent/rules/agents.md（含初始波次建议）？
+- ✅ 已更新 AGENTS.md（含初始波次建议）？
 
 ---
 
@@ -282,7 +282,7 @@ graph TD
 
 ### Agent Context 自更新
 
-**更新 `.agent/rules/agents.md` 的 `AUTO:BEGIN` ~ `AUTO:END` 区块**:
+**更新 `AGENTS.md` 的 `AUTO:BEGIN` ~ `AUTO:END` 区块**:
 
 在 `### 当前任务状态` 下写入：
 
@@ -305,8 +305,8 @@ graph TD
 - ✅ 每个 Sprint 有退出标准和 INT 集成验证任务
 - ✅ 生成了 Mermaid 依赖图
 - ✅ User Story Overlay 已生成并验证覆盖完整性
-- ✅ 已更新 .agent/rules/agents.md（含初始波次建议）
-- ✅ 更新了 agents.md AUTO:BEGIN 区块 (当前任务状态)
+- ✅ 已更新 AGENTS.md（含初始波次建议）
+- ✅ 更新了 AGENTS.md AUTO:BEGIN 区块 (当前任务状态)
 - ✅ 用户已确认
 </completion_criteria>
 
@@ -317,4 +317,4 @@ graph TD
 完成本工作流后，根据情况选择：
 
 - **质疑设计与任务** → `/challenge` — 对设计和任务清单进行系统性审查
-- **开始编码执行** → `/forge` — 按任务清单开始波次执行
+- **开始编码执行** → `/forge` — 按任务清单开始波次执行

package/templates/.agent/workflows/change.md

@@ -227,7 +227,7 @@ description: 处理微调级变更请求，通过 7 问题法严格评估，仅
       - PRD 追溯: [REQ-XXX]
     ```
 
-3.  **更新 .agent/rules/agents.md**:
+3.  **更新 AGENTS.md**:
     - 更新 `最近一次更新` 日期。
     - (注意: 微调不改变待办任务数)
 

package/templates/.agent/workflows/craft.md

@@ -569,7 +569,7 @@ description: 当用户需要 [具体触发场景] 时使用。[一句话核心
 - [ ] Markdown 格式正确无误
 
 **输出后建议**:
-- 如果是 Workflow，考虑将其添加到 `.agent/rules/agents.md` 的工作流注册表（如果是通用工作流）
+- 如果是 Workflow，考虑将其添加到 `AGENTS.md` 的工作流注册表（如果是通用工作流）
 - 如果是 Skill，确保相关 Workflow 知道如何调用它
 
 ---

package/templates/.agent/workflows/design-system.md

@@ -502,7 +502,7 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 
 ### Agent Context 自更新
 
-**更新 `.agent/rules/agents.md` 的 `AUTO:BEGIN` ~ `AUTO:END` 区块**:
+**更新 `AGENTS.md` 的 `AUTO:BEGIN` ~ `AUTO:END` 区块**:
 
 在 `### 系统边界` 下追加或更新当前设计系统的信息：
 
@@ -522,7 +522,7 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 - ✅ 调研已完成 (/explore)
 - ✅ 设计已完成 (sequentialthinking 5-7步)
 - ✅ 文档已生成 (使用模板)
-- ✅ 更新了 agents.md AUTO:BEGIN 区块 (系统边界)
+- ✅ 更新了 AGENTS.md AUTO:BEGIN 区块 (系统边界)
 - ✅ 用户已确认
 </completion_criteria>
 

package/templates/.agent/workflows/explore.md

@@ -313,4 +313,4 @@ description: 深度探索复杂问题，通过"向外搜索 + 向内发散"双
 
 ---
 
-// turbo-all
+// turbo-all

package/templates/.agent/workflows/forge.md

@@ -44,7 +44,7 @@ description: 按照架构文档和任务清单将设计锻造为代码，通过
 > | 更新 `05_TASKS.md` 的 checkbox | ✅ | |
 > | 运行测试和 lint | ✅ | |
 > | Git commit 已完成的任务 | ✅ | |
-> | 更新 `.agent/rules/agents.md` 当前状态 | ✅ | |
+> | 更新 `AGENTS.md` 当前状态 | ✅ | |
 > | **修改 `genesis/` 下任何设计文档** | | ❌ |
 > | **创建 TASKS.md 中不存在的功能** | | ❌ |
 > | **降级或跳过验收标准** | | ❌ |
@@ -108,7 +108,7 @@ description: 按照架构文档和任务清单将设计锻造为代码，通过
 5. **如果必需文件缺失**: 报错并提示运行 `/genesis` + `/blueprint`。
 
 6. **断点续做判定**:
-   - 读取 `.agent/rules/agents.md` 的 `🌊 Wave` 块
+   - 读取 `AGENTS.md` 的 `🌊 Wave` 块
    - 如果存在波次信息：
      - 查看波次任务列表，对照 `05_TASKS.md` 中的 checkbox
      - 如有未完成任务 → **断点续做** → 跳入 Step 3 继续未完成的任务
@@ -160,7 +160,7 @@ description: 按照架构文档和任务清单将设计锻造为代码，通过
 确认此波次？或调整任务组合？
 ```
 
-**人类检查点** ⚠️: 用户确认后，将确认的波次写入 `.agent/rules/agents.md` 的 `🌊 Wave` 块：
+**人类检查点** ⚠️: 用户确认后，将确认的波次写入 `AGENTS.md` 的 `🌊 Wave` 块：
 
 ```markdown
 ### 🌊 Wave {N} — {波次目标简述}
@@ -323,7 +323,7 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
    > **每完成一个 task 并通过验证，立即回写 `05_TASKS.md`**。
    > 这是进度持久化的核心机制——即使 AI 上下文丢失或会话崩溃，
    > 下次加载 TASKS.md 就能看到精确进度。
-   > 配合 agents.md 的 Wave 块形成**双层恢复机制**: 粗粒度(Wave) + 细粒度(Task checkbox)。
+   > 配合 AGENTS.md 的 Wave 块形成**双层恢复机制**: 粗粒度(Wave) + 细粒度(Task checkbox)。
 
    - 将该任务的 `- [ ]` 改为 `- [x]`
    - 确保回写后的 `05_TASKS.md` 与实际进度一致
@@ -338,7 +338,7 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 
 ### 4.1 更新状态
 
-**更新 `.agent/rules/agents.md`**:
+**更新 `AGENTS.md`**:
 
 1. 更新 `🌊 Wave` 块为下一波的初始状态（如果已知下一波任务），或标记当前波已完成：
 ```markdown
@@ -393,7 +393,7 @@ chore: Wave {N} settlement — update task progress
 - ✅ 每个任务的遵从性检查全部通过
 - ✅ 所有代码已 git commit，message 包含 Task ID
 - ✅ 05_TASKS.md checkbox 已更新
-- ✅ .agent/rules/agents.md 当前状态已更新
+- ✅ AGENTS.md 当前状态已更新
 - ✅ 用户已确认波次完成
 </completion_criteria>
 

package/templates/.agent/workflows/genesis.md

@@ -198,15 +198,15 @@ description: 从 0 到代码的项目启动全流程，将模糊想法转化为
 
 ## Step 7: 完成总结 (Completion Summary)
 
-**目标**: 总结产出，并**更新 .agent/rules/agents.md** 以反映新版本。
+**目标**: 总结产出，并**更新 AGENTS.md** 以反映新版本。
 
 > [!IMPORTANT]
 > **必须完成以下 3 个更新动作**:
-> 1. 更新 .agent/rules/agents.md "当前状态"
-> 2. 更新 .agent/rules/agents.md "项目结构"
-> 3. 更新 .agent/rules/agents.md "导航指南"
+> 1. 更新 AGENTS.md "当前状态"
+> 2. 更新 AGENTS.md "项目结构"
+> 3. 更新 AGENTS.md "导航指南"
 
-### 7.1 更新 .agent/rules/agents.md
+### 7.1 更新 AGENTS.md
 
 使用 `replace_file_content` 或 `multi_replace_file_content`:
 
@@ -254,7 +254,7 @@ description: 从 0 到代码的项目启动全流程，将模糊想法转化为
 
 ### 7.3 Agent Context 自更新
 
-**更新 `.agent/rules/agents.md` 的 `AUTO:BEGIN` ~ `AUTO:END` 区块**:
+**更新 `AGENTS.md` 的 `AUTO:BEGIN` ~ `AUTO:END` 区块**:
 
 仅修改 `<!-- AUTO:BEGIN -->` 和 `<!-- AUTO:END -->` 之间的内容，保留手动添加的内容不变。
 
@@ -283,8 +283,8 @@ description: 从 0 到代码的项目启动全流程，将模糊想法转化为
 - ✅ 创建了 `genesis/v{N}/00_MANIFEST.md`
 - ✅ 创建了 `genesis/v{N}/06_CHANGELOG.md`
 - ✅ 生成了 PRD, Architecture Overview, ADRs
-- ✅ 更新了 .agent/rules/agents.md (当前状态、项目结构、导航指南)
-- ✅ 更新了 agents.md AUTO:BEGIN 区块 (技术栈、系统边界、活跃 ADR)
+- ✅ 更新了 AGENTS.md (当前状态、项目结构、导航指南)
+- ✅ 更新了 AGENTS.md AUTO:BEGIN 区块 (技术栈、系统边界、活跃 ADR)
 - ✅ 用户已在人类检查点确认
 </completion_criteria>
 
@@ -296,4 +296,4 @@ description: 从 0 到代码的项目启动全流程，将模糊想法转化为
 
 - **设计系统详细架构** → `/design-system` — 为 {system-id} 设计详细架构 *(项目包含复杂系统时)*
 - **生成任务清单** → `/blueprint` — 将架构拆解为可执行任务
-- **质疑设计决策** → `/challenge` — 对当前设计进行系统性挑战
+- **质疑设计决策** → `/challenge` — 对当前设计进行系统性挑战

package/templates/.agent/workflows/scout.md

@@ -136,4 +136,4 @@ Scout 的发现将作为**输入**反馈给 Architectural Overview。
 
 完成本工作流后，根据情况选择：
 
-- **启动新版本架构** → `/genesis` — 基于侦察发现启动架构重构 *(发现需要重大重构时)*
+- **启动新版本架构** → `/genesis` — 基于侦察发现启动架构重构 *(发现需要重大重构时)*

package/templates/{.agent/rules/agents.md → AGENTS.md}

@@ -11,7 +11,7 @@
 
 **当你开始新会话或感到"迷失"时，立即执行**:
 
-1. **读取 .agent/rules/agents.md** → 获取项目地图
+1. **读取根目录的 AGENTS.md** → 获取项目地图
 2. **查看下方"当前状态"** → 找到最新架构版本
 3. **读取 `genesis/v{N}/05_TASKS.md`** → 了解当前待办
 4. **开始工作**
@@ -73,11 +73,11 @@ _尚未开始执行_
 | `/genesis` | 新项目 / 重大重构 | PRD, Architecture, ADRs |
 | `/scout` | 变更前 / 接手项目 | `genesis/v{N}/00_SCOUT_REPORT.md` |
 | `/design-system` | genesis 后 | 04_SYSTEM_DESIGN/*.md |
-| `/blueprint` | genesis 后 | 05_TASKS.md + agents.md 初始 Wave |
+| `/blueprint` | genesis 后 | 05_TASKS.md + AGENTS.md 初始 Wave |
 | `/change` | 微调已有任务 | 更新 TASKS + SYSTEM_DESIGN (仅修改) + CHANGELOG |
 | `/explore` | 调研时 | 探索报告 |
 | `/challenge` | 决策前质疑 | 07_CHALLENGE_REPORT.md (含问题总览目录) |
-| `/forge` | 编码执行 | 代码 + 更新 agents.md Wave 块 |
+| `/forge` | 编码执行 | 代码 + 更新 AGENTS.md Wave 块 |
 | `/craft` | 创建工作流/技能/提示词 | Workflow / Skill / Prompt 文档 |
 
 ---
@@ -110,3 +110,4 @@ _尚未开始执行_
 
 ---
 > **状态自检**: 准备好了？提醒用户运行 `/quickstart` 开始吧。
+\n# TEST NEW CONTENT\n

package/templates/.agent/rules/.agents-template-hash

@@ -1 +0,0 @@
-0b7931a8ef4374d59141cdc919d4bc47

package/templates/.agent/rules/agents.md.new

@@ -1,112 +0,0 @@
-# AGENTS.md - AI 协作协议
-
-> **"如果你正在阅读此文档，你就是那个智能体 (The Intelligence)。"**
-> 
-> 这个文件是你的**锚点 (Anchor)**。它定义了项目的法则、领地的地图，以及记忆协议。
-> 当你唤醒（开始新会话）时，**请首先阅读此文件**。
-
----
-
-## 🧠 30秒恢复协议 (Quick Recovery)
-
-**当你开始新会话或感到"迷失"时，立即执行**:
-
-1. **读取 .agent/rules/agents.md** → 获取项目地图
-2. **查看下方"当前状态"** → 找到最新架构版本
-3. **读取 `genesis/v{N}/05_TASKS.md`** → 了解当前待办
-4. **开始工作**
-
----
-
-## 🗺️ 地图 (领地感知)
-
-以下是这个项目的组织方式：
-
-| 路径 | 描述 | 访问协议 |
-|------|------|----------|
-| `src/` | **实现层**。实际的代码库。 | 通过 Task 读/写。 |
-| `genesis/` | **设计演进史**。版本化架构状态 (v1, v2...)。 | **只读**(旧版) / **写一次**(新版)。 |
-| `genesis/v{N}/` | **当前真理**。最新的架构定义。 | 永远寻找最大的 `v{N}`。 |
-| `.agent/workflows/` | **工作流**。`/genesis`, `/blueprint` 等。 | 通过 `view_file` 阅读。 |
-| `.agent/skills/` | **技能库**。原子能力。 | 通过 `view_file` 调用。 |
-
----
-
-## 📍 当前状态 (由 Workflow 自动更新)
-
-> **注意**: 此部分由 `/genesis`、`/blueprint` 和 `/forge` 自动维护。
-
-- **最新架构版本**: `尚未初始化`
-- **活动任务清单**: `尚未生成`
-- **待办任务数**: -
-- **最近一次更新**: `-`
-
-### 🌊 Wave 1 — 待 /blueprint 或 /forge 设置
-_尚未开始执行_
-
----
-
-## 🌳 项目结构 (Project Tree)
-
-> **注意**: 此部分由 `/genesis` 维护。
-
-```text
-(等待 Genesis 初始化结构树...)
-```
-
----
-
-## 🧭 导航指南 (Navigation Guide)
-
-> **注意**: 此部分由 `/genesis` 维护。
-
-- **在新架构就绪前**: 请勿大规模修改代码。
-- **遇到架构问题**: 请查阅 `genesis/v{N}/03_ADR/`。
-
----
-
-## 🛠️ 工作流注册表
-
-| 工作流 | 触发时机 | 产出 |
-|--------|---------|------|
-| `/quickstart` | 新用户入口 / 不知道从哪开始 | 编排其他工作流 |
-| `/genesis` | 新项目 / 重大重构 | PRD, Architecture, ADRs |
-| `/scout` | 变更前 / 接手项目 | `genesis/v{N}/00_SCOUT_REPORT.md` |
-| `/design-system` | genesis 后 | 04_SYSTEM_DESIGN/*.md |
-| `/blueprint` | genesis 后 | 05_TASKS.md + agents.md 初始 Wave |
-| `/change` | 微调已有任务 | 更新 TASKS + SYSTEM_DESIGN (仅修改) + CHANGELOG |
-| `/explore` | 调研时 | 探索报告 |
-| `/challenge` | 决策前质疑 | 07_CHALLENGE_REPORT.md (含问题总览目录) |
-| `/forge` | 编码执行 | 代码 + 更新 agents.md Wave 块 |
-| `/craft` | 创建工作流/技能/提示词 | Workflow / Skill / Prompt 文档 |
-
----
-
-## 📜 宪法 (The Constitution)
-
-1. **版本即法律**: 不"修补"架构文档，只"演进"。变更必须创建新版本。
-2. **显式上下文**: 决策写入 ADR，不留在"聊天记忆"里。
-3. **交叉验证**: 编码前对照 `05_TASKS.md`。我在做计划好的事吗？
-4. **美学**: 文档应该是美的。善用 Markdown 和 Emoji。
-
----
-## 🔄 Auto-Updated Context
-
-<!-- AUTO:BEGIN — 由工作流自动维护，请勿手动编辑此区块 -->
-
-### 技术栈决策
-- [由 genesis/tech-evaluator 自动填充]
-
-### 系统边界
-- [由 genesis/system-architect 自动填充]
-
-### 活跃 ADR
-- [由 genesis 自动填充 ADR 摘要]
-
-### 当前任务状态
-- [由 blueprint/forge 自动更新]
-
-<!-- AUTO:END -->
-
----
-> **状态自检**: 准备好了？提醒用户运行 `/quickstart` 开始吧。