@wnlen/agent-execution-template 0.8.19 → 0.8.21

package/README.md

@@ -21,6 +21,9 @@ Start initializing this project
 ```
 
 Agent Execution Template is not another agent framework. It is the missing execution layer between your repository and tools like Codex, Claude Code, Cursor, Aider, or any other AI coding agent.
+More precisely, it is an **AI Repo Execution Protocol**: it governs how an AI reads context, confirms a task, respects file modification boundaries, verifies acceptance, and records results inside a specific repository.
+
+It does not manage workspace switching, session isolation, sandbox lifecycle, or worker scheduling. Those belong to an external workspace/session runtime.
 
 It turns AI coding from:
 
@@ -56,7 +59,7 @@ ai/template/  reusable execution protocol
 ai/project/   project-specific working context and direction layer
 ```
 
-`update` can refresh the protocol, while your project workspace stays protected.
+`update` can refresh the protocol, while your repo-local project context stays protected.
 
 ## Quick Start
 
@@ -72,6 +75,14 @@ Ask your agent to bootstrap project context from existing docs and manifests:
 Start initializing this project
 ```
 
+`init` installs compatibility managed blocks in root `AGENTS.md` and `CLAUDE.md`.
+They have the same content and are not separate protocols; they adapt to generic
+Agent / Codex and Claude Code discovery conventions. Compatible AI tools read
+`ai/template/prompt.md` first, then route bootstrap to `ai/template/bootstrap.md`.
+If your AI tool does not auto-read those root
+entrypoints, ask it to read `AGENTS.md` or `CLAUDE.md` before sending the
+initialization instruction above.
+
 The agent will generate project context and summarize what needs confirmation,
 risks, and the recommended next step in chat:
 
@@ -228,7 +239,7 @@ ai/
 The split is the core design:
 
 - `ai/template/**` is reusable protocol. It can be safely updated from this package.
-- `ai/project/**` is your project workspace. It stores local context, tasks, references, results, and metrics.
+- `ai/project/**` is your repo-local project context. It stores local context, tasks, references, results, and metrics.
 
 ## Commands
 
@@ -243,6 +254,8 @@ Creates `ai/` in the current project.
 - Updates or creates `ai/template/**`.
 - Creates missing `ai/project/**` files.
 - Keeps existing `ai/project/**` files intact.
+- Creates or updates the same compatibility managed block in root `AGENTS.md` /
+  `CLAUDE.md` so different AI tools can discover the protocol entrypoint.
 - Use `--lang zh` or omit `--lang` for the Chinese template.
 
 ### `next`
@@ -425,12 +438,16 @@ Agent Execution Template is not:
 - an IDE,
 - an agent platform,
 - a multi-agent scheduler,
+- a workspace / sandbox / session runtime,
+- a multi-repository context manager,
 - a cloud service,
 - a prompt collection,
 - a replacement for Codex, Claude Code, Cursor, or Aider.
 
 It is a small file protocol for making those tools behave more consistently inside real software projects.
 
+It does not handle workspace switching, sandbox lifecycle, session fork / rollback, or worker scheduling. Conversely, an external runtime should not replace in-repository task definitions, file modification rules, acceptance criteria, or concrete coding context.
+
 ## Specification
 
 - [Full specification](docs/SPEC.md)

package/README.zh-CN.md

@@ -27,6 +27,9 @@ npx -y @wnlen/agent-execution-template init --lang zh
 ```
 
 Agent Execution Template 不是新的 Agent 框架。它是代码仓库和 Codex、Claude Code、Cursor、Aider 等 AI Coding Agent 之间缺失的执行层。
+更准确地说，它是 **AI Repo Execution Protocol**：只约束 AI 在某个仓库内如何读取上下文、确认任务、遵守文件修改边界、验收并记录结果。
+
+它不管理 workspace 切换、Session 隔离、sandbox 生命周期或 worker 调度。这些属于外部 workspace/session runtime。
 
 它把 AI 编程从：
 
@@ -83,6 +86,12 @@ npx -y @wnlen/agent-execution-template init --lang en
 开始初始化这个项目
 ```
 
+`init` 会在仓库根目录安装 `AGENTS.md` 和 `CLAUDE.md` 兼容入口托管块。两者内容相同，
+不是两套协议；它们分别适配通用 Agent / Codex 和 Claude Code 的自动发现约定。
+支持这些入口的 AI 工具会先读取 `ai/template/prompt.md`，再路由到 `ai/template/bootstrap.md`。
+如果你的 AI 工具没有自动读取根目录入口文件，请先让它读取 `AGENTS.md` 或
+`CLAUDE.md`，再发送上面的初始化指令。
+
 Agent 会生成项目上下文，并在聊天里给出需要确认的摘要、风险和建议下一步：
 
 ```text
@@ -247,6 +256,7 @@ npx -y @wnlen/agent-execution-template init
 - 更新或创建 `ai/template/**`。
 - 创建缺失的 `ai/project/**` 文件。
 - 保留已有的 `ai/project/**` 文件。
+- 创建或更新根目录 `AGENTS.md` / `CLAUDE.md` 中的同内容兼容托管块，让不同 AI 工具能发现协议入口。
 - 默认安装中文模板；英文模板使用 `--lang en`。
 
 ### `next`
@@ -426,12 +436,16 @@ Agent Execution Template 不是：
 - IDE；
 - Agent 平台；
 - 多 Agent 调度器；
+- workspace / sandbox / session 运行时；
+- 多仓库上下文管理器；
 - 云服务；
 - 提示词合集；
 - Codex、Claude Code、Cursor 或 Aider 的替代品。
 
 它是一个小型文件协议，用来让这些工具在真实软件项目中表现得更稳定。
 
+它不负责 workspace 切换、sandbox 生命周期、session fork / rollback 或 worker 调度。反过来，外部运行时不应该替代仓库内的任务定义、文件修改规则、acceptance criteria 或具体编码上下文。
+
 ## 规格
 
 - [完整规格](docs/SPEC.md)

package/bin/agent-execution-template.js

@@ -8,6 +8,9 @@ const TEMPLATE_ROOT = path.join(PACKAGE_ROOT, "template");
 const TARGET_AI = path.join(process.cwd(), "ai");
 const DEFAULT_LANG = "zh";
 const SUPPORTED_LANGS = new Set(["zh", "en"]);
+const ROOT_ENTRYPOINT_FILES = ["AGENTS.md", "CLAUDE.md"];
+const ENTRYPOINT_BLOCK_START = "<!-- agent-execution-template:start -->";
+const ENTRYPOINT_BLOCK_END = "<!-- agent-execution-template:end -->";
 
 const REQUIRED_FILES = [
   "ai/template/LANG",
@@ -19,6 +22,8 @@ const REQUIRED_FILES = [
   "ai/template/protocol.md",
   "ai/template/rules/core.md",
   "ai/template/rules/output.md",
+  "ai/template/schemas/result.schema.json",
+  "ai/template/schemas/metrics.schema.json",
   "ai/project/inbox/.gitkeep",
   "ai/project/project.md",
   "ai/project/runtime.md",
@@ -39,11 +44,6 @@ const RECOMMENDED_FILES = [
   "ai/project/refs/roadmap.md"
 ];
 
-const JSON_HEALTH_FILES = [
-  "ai/project/result.json",
-  "ai/project/metrics.json"
-];
-
 const TASK_HEALTH_PATTERNS = [
   /^task_id:\s*/m,
   /^type:\s*/m,
@@ -77,11 +77,13 @@ const TEXT = {
 `,
     unknown: "未知",
     sourceMissing: "找不到模板来源",
-    ready: "Agent Execution Template 已就绪。",
-    initGuide: `[初始化]
-1. 直接初始化
+    ready: "Agent Execution Template 协议已安装。项目上下文尚未初始化。",
+    initGuide: `[下一步：让 AI 初始化项目上下文]
+已安装根目录 AI 兼容入口: AGENTS.md / CLAUDE.md
+
+1. 无额外资料
    对 AI 说: 开始初始化这个项目
-2. 带资料初始化
+2. 有已确定资料
    先放到: ai/project/inbox/
    对 AI 说: 开始初始化这个项目，并吸收 ai/project/inbox/ 里的资料
 
@@ -132,7 +134,10 @@ const TEXT = {
     fail: "失败",
     empty: "为空",
     invalidJson: "JSON 无效",
+    invalidSchema: "不符合协议 schema",
     taskFrontMatterIncomplete: "任务 front matter 缺少关键字段",
+    entrypointReady: "根目录 AI 兼容入口已安装: AGENTS.md / CLAUDE.md",
+    entrypointMissing: "缺少根目录 AI 兼容入口托管块；AI 可能不会自动读取 ai/template/prompt.md",
     versionMismatch: "模板版本与包版本不一致",
     runInit: "请运行 npx -y @wnlen/agent-execution-template init",
     readyWithWarnings: "已就绪，但存在警告",
@@ -186,11 +191,13 @@ Usage:
 `,
     unknown: "unknown",
     sourceMissing: "Template source not found",
-    ready: "Agent Execution Template ready.",
-    initGuide: `[Initialize]
-1. Initialize directly
+    ready: "Agent Execution Template protocol installed. Project context is not initialized yet.",
+    initGuide: `[Next: ask the AI to initialize project context]
+Installed root AI compatibility entrypoints: AGENTS.md / CLAUDE.md
+
+1. Without extra material
    Tell the AI: Start initializing this project
-2. Initialize with material
+2. With confirmed material
    Put it in: ai/project/inbox/
    Tell the AI: Start initializing this project and absorb the material in ai/project/inbox/
 
@@ -241,7 +248,10 @@ Usage:
     fail: "FAIL",
     empty: "is empty",
     invalidJson: "contains invalid JSON",
+    invalidSchema: "does not match protocol schema",
     taskFrontMatterIncomplete: "task front matter is missing required fields",
+    entrypointReady: "root AI compatibility entrypoints installed: AGENTS.md / CLAUDE.md",
+    entrypointMissing: "missing root AI compatibility entrypoint managed block; the AI may not auto-read ai/template/prompt.md",
     versionMismatch: "template version does not match package version",
     runInit: "Run npx -y @wnlen/agent-execution-template init",
     readyWithWarnings: "Ready to run with warnings",
@@ -398,6 +408,72 @@ function copyTree(sourceRoot, targetRoot, overwrite) {
   );
 }
 
+function rootEntrypointBlock(lang) {
+  if (lang === "en") {
+    return `${ENTRYPOINT_BLOCK_START}
+## Agent Execution Template
+
+This repository has Agent Execution Template installed in \`ai/\`.
+This managed block is intentionally duplicated in \`AGENTS.md\` and \`CLAUDE.md\` for different AI tool discovery conventions.
+
+Mandatory routing:
+- Before acting on any project request, first read and follow \`ai/template/prompt.md\`.
+- If the user says "Start initializing this project" or asks to initialize/bootstrap project context, do not run installs, create lockfiles, or edit app files before \`ai/template/prompt.md\` routes the workflow.
+${ENTRYPOINT_BLOCK_END}`;
+  }
+
+  return `${ENTRYPOINT_BLOCK_START}
+## Agent Execution Template
+
+本仓库已安装 Agent Execution Template，协议位于 \`ai/\`。
+此托管块会有意同时写入 \`AGENTS.md\` 和 \`CLAUDE.md\`，用于适配不同 AI 工具的自动发现约定。
+
+强制路由：
+- 处理任何项目请求前，必须先读取并遵守 \`ai/template/prompt.md\`。
+- 如果用户说“开始初始化这个项目”或要求初始化/整理项目上下文，在 \`ai/template/prompt.md\` 完成路由前，不要运行安装命令、不要创建 lockfile、不要编辑业务文件。
+${ENTRYPOINT_BLOCK_END}`;
+}
+
+function hasManagedEntrypointBlock(content) {
+  return content.includes(ENTRYPOINT_BLOCK_START) && content.includes(ENTRYPOINT_BLOCK_END);
+}
+
+function upsertManagedBlock(content, block) {
+  if (!hasManagedEntrypointBlock(content)) {
+    const separator = content.trim().length > 0 ? "\n\n" : "";
+    return `${content.replace(/\s*$/, "")}${separator}${block}\n`;
+  }
+
+  const start = content.indexOf(ENTRYPOINT_BLOCK_START);
+  const end = content.indexOf(ENTRYPOINT_BLOCK_END, start) + ENTRYPOINT_BLOCK_END.length;
+  return `${content.slice(0, start)}${block}${content.slice(end)}`;
+}
+
+function ensureRootEntrypoints(lang) {
+  const block = rootEntrypointBlock(lang);
+  const changes = [];
+  for (const file of ROOT_ENTRYPOINT_FILES) {
+    const fullPath = path.join(process.cwd(), file);
+    const existed = fs.existsSync(fullPath);
+    const current = existed ? fs.readFileSync(fullPath, "utf8") : "";
+    const next = upsertManagedBlock(current, block);
+    if (existed && current === next) {
+      changes.push({ action: "kept", path: file });
+      continue;
+    }
+    fs.writeFileSync(fullPath, next);
+    changes.push({ action: existed ? "updated" : "created", path: file });
+  }
+  return changes;
+}
+
+function hasAllRootEntrypoints() {
+  return ROOT_ENTRYPOINT_FILES.every((file) => {
+    const fullPath = path.join(process.cwd(), file);
+    return fs.existsSync(fullPath) && hasManagedEntrypointBlock(fs.readFileSync(fullPath, "utf8"));
+  });
+}
+
 function formatTimestamp(date = new Date()) {
   const pad = (value) => String(value).padStart(2, "0");
   return [
@@ -496,7 +572,7 @@ function proposalState() {
   return hasProposed ? "proposed" : null;
 }
 
-function init({ lang = DEFAULT_LANG, verbose = false, quiet = false } = {}) {
+function init({ lang = DEFAULT_LANG, verbose = false, quiet = false, manageEntrypoints = true } = {}) {
   const text = getText(lang);
   if (!SUPPORTED_LANGS.has(lang)) {
     console.error(`[${text.fail}] ${text.invalidLang}: ${lang}`);
@@ -523,6 +599,10 @@ function init({ lang = DEFAULT_LANG, verbose = false, quiet = false } = {}) {
   changes.push(...copyTree(path.join(sourceAi, "project"), path.join(TARGET_AI, "project"), false)
     .map((change) => ({ ...change, path: path.join("ai/project", change.path) })));
 
+  if (manageEntrypoints) {
+    changes.push(...ensureRootEntrypoints(lang));
+  }
+
   if (!quiet) {
     const sourceNotice = isSourceCheckout() ? `${text.sourceCheckoutNotice}\n\n` : "";
     console.log(`${text.ready}
@@ -560,7 +640,7 @@ function refresh({ lang = DEFAULT_LANG, title } = {}) {
   const backupPath = uniqueBackupPath(path.join(TARGET_AI, `project.backup.${formatTimestamp()}`));
   fs.renameSync(projectPath, backupPath);
 
-  init({ lang, verbose: false, quiet: true });
+  init({ lang, verbose: false, quiet: true, manageEntrypoints: false });
 
   const importPath = path.join(TARGET_AI, "project", "inbox", "raw", "old-project");
   ensureDir(importPath);
@@ -654,6 +734,7 @@ function update({ lang = readInstalledLang() } = {}) {
   ensureDir(targetTemplate);
   const changes = copyTree(sourceTemplate, targetTemplate, true)
     .map((change) => ({ ...change, path: path.join("ai/template", change.path) }));
+  changes.push(...ensureRootEntrypoints(lang));
   printChanges(text.updateTitle, changes, lang);
   console.log(`[${text.pass}] ${text.updated} ${readVersion(sourceTemplate) || text.unknown}. ${text.projectNotModified}`);
 }
@@ -701,6 +782,117 @@ function isPermissionError(error) {
   return error && (error.code === "EACCES" || error.code === "EPERM");
 }
 
+function parseJsonFile(file) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function valueMatchesType(value, type) {
+  if (type === "array") return Array.isArray(value);
+  if (type === "integer") return Number.isInteger(value);
+  if (type === "number") return typeof value === "number" && Number.isFinite(value);
+  if (type === "object") return value !== null && typeof value === "object" && !Array.isArray(value);
+  return typeof value === type;
+}
+
+function valuesEqual(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function validateJsonSchema(value, schema, location = "$") {
+  const errors = [];
+
+  if (schema.const !== undefined && !valuesEqual(value, schema.const)) {
+    errors.push(`${location} must be ${JSON.stringify(schema.const)}`);
+  }
+
+  if (schema.enum && !schema.enum.some((candidate) => valuesEqual(value, candidate))) {
+    errors.push(`${location} must be one of ${schema.enum.map((item) => JSON.stringify(item)).join(", ")}`);
+  }
+
+  if (schema.type && !valueMatchesType(value, schema.type)) {
+    errors.push(`${location} must be ${schema.type}`);
+    return errors;
+  }
+
+  if (schema.minimum !== undefined && typeof value === "number" && value < schema.minimum) {
+    errors.push(`${location} must be >= ${schema.minimum}`);
+  }
+
+  if (schema.minLength !== undefined && typeof value === "string" && value.length < schema.minLength) {
+    errors.push(`${location} must have length >= ${schema.minLength}`);
+  }
+
+  if (schema.required && valueMatchesType(value, "object")) {
+    for (const key of schema.required) {
+      if (!Object.prototype.hasOwnProperty.call(value, key)) {
+        errors.push(`${location}.${key} is required`);
+      }
+    }
+  }
+
+  if (schema.properties && valueMatchesType(value, "object")) {
+    for (const [key, childSchema] of Object.entries(schema.properties)) {
+      if (Object.prototype.hasOwnProperty.call(value, key)) {
+        errors.push(...validateJsonSchema(value[key], childSchema, `${location}.${key}`));
+      }
+    }
+  }
+
+  if (schema.items && Array.isArray(value)) {
+    value.forEach((item, index) => {
+      errors.push(...validateJsonSchema(item, schema.items, `${location}[${index}]`));
+    });
+  }
+
+  if (schema.allOf) {
+    for (const childSchema of schema.allOf) {
+      if (childSchema.if) {
+        if (validateJsonSchema(value, childSchema.if, location).length === 0 && childSchema.then) {
+          errors.push(...validateJsonSchema(value, childSchema.then, location));
+        }
+      } else {
+        errors.push(...validateJsonSchema(value, childSchema, location));
+      }
+    }
+  }
+
+  return errors;
+}
+
+function printSchemaValidation(file, schemaFile, text) {
+  const fullPath = path.join(process.cwd(), file);
+  const schemaPath = path.join(process.cwd(), schemaFile);
+  if (!fs.existsSync(fullPath) || !fs.existsSync(schemaPath)) {
+    return 0;
+  }
+
+  let value;
+  try {
+    value = parseJsonFile(fullPath);
+    console.log(`[${text.pass}] ${file} JSON`);
+  } catch {
+    console.log(`[${text.fail}] ${file} ${text.invalidJson}`);
+    return 1;
+  }
+
+  let schema;
+  try {
+    schema = parseJsonFile(schemaPath);
+  } catch {
+    console.log(`[${text.fail}] ${schemaFile} ${text.invalidJson}`);
+    return 1;
+  }
+
+  const errors = validateJsonSchema(value, schema);
+  if (errors.length > 0) {
+    console.log(`[${text.fail}] ${file} ${text.invalidSchema}: ${errors.slice(0, 3).join("; ")}`);
+    return 1;
+  }
+
+  console.log(`[${text.pass}] ${file} schema`);
+  return 0;
+}
+
 function printFatal(error, lang) {
   const text = getText(lang);
   if (isPermissionError(error)) {
@@ -756,18 +948,19 @@ function doctor() {
     console.log(`[${text.pass}] ${file}`);
   }
 
-  for (const file of JSON_HEALTH_FILES) {
-    const fullPath = path.join(process.cwd(), file);
-    if (!fs.existsSync(fullPath)) {
-      continue;
-    }
-    try {
-      JSON.parse(fs.readFileSync(fullPath, "utf8"));
-      console.log(`[${text.pass}] ${file} JSON`);
-    } catch {
-      console.log(`[${text.fail}] ${file} ${text.invalidJson}`);
-      missing += 1;
-    }
+  if (hasAllRootEntrypoints()) {
+    console.log(`[${text.pass}] ${text.entrypointReady}`);
+  } else {
+    console.log(`[${text.warn}] ${text.entrypointMissing}`);
+    warnings += 1;
+  }
+
+  const schemaChecks = [
+    ["ai/project/result.json", "ai/template/schemas/result.schema.json"],
+    ["ai/project/metrics.json", "ai/template/schemas/metrics.schema.json"]
+  ];
+  for (const [file, schemaFile] of schemaChecks) {
+    missing += printSchemaValidation(file, schemaFile, text);
   }
 
   const taskPath = path.join(process.cwd(), "ai/project/task.md");

package/docs/SPEC.md

@@ -8,7 +8,7 @@ Current protocol: v0.8
 
 ## 2. 一句话定位
 
-**Agent Execution Template 是一个 30 秒可安装、可升级、保护用户项目现场的 AI Coding Agent 执行协议模板。**
+**Agent Execution Template 是一个 30 秒可安装、可升级、保护用户项目现场的 AI Repo Execution Protocol。**
 
 它把 AI 编程从“聊天式执行”变成：
 
@@ -18,11 +18,13 @@ npx 安装协议 -> AI 整理项目上下文 -> 人类确认 -> AI 生成任务
 
 当前版本的核心不是做一个新的 Agent，也不是做复杂调度系统，而是给 Codex、Claude Code、Cursor、Aider 等 AI Coding Agent 提供同一套项目内执行协议。
 
+它只管 AI 在某个仓库内怎么干活：当前任务是什么、哪些文件能改、需要读哪些上下文、执行结果怎么记录、如何审计本次任务，以及 Agent 进入项目后先读什么。
+
 ## 3. 当前版本
 
 ```text
 Protocol: v0.8
-Package: @wnlen/agent-execution-template@0.8.19
+Package: @wnlen/agent-execution-template@0.8.21
 中文安装: npx -y @wnlen/agent-execution-template init
 英文安装: npx -y @wnlen/agent-execution-template init --lang en
 ```
@@ -33,6 +35,7 @@ Package: @wnlen/agent-execution-template@0.8.19
 - `init` / `next` / `refresh` / `improve-context` / `update` / `reconcile` / `strategy` / `doctor` 命令；
 - `init --lang zh|en` 双语安装入口，默认中文；
 - `template/project` 双区结构；
+- 根目录 AI 兼容入口托管块：`AGENTS.md` / `CLAUDE.md`；
 - 保护 `ai/project/**` 不被升级覆盖；
 - 模板版本文件 `ai/template/VERSION`；
 - 引导模式：通过 `ai/template/bootstrap.md` 从受控范围内的项目文档、manifest 和必要代码生成 `project.md` / refs 草稿；
@@ -70,6 +73,8 @@ Agent Execution Template 不是：
 - AI IDE；
 - Agent 平台；
 - 多 Agent 调度器；
+- workspace / sandbox / session 运行时；
+- 多仓库上下文管理器；
 - 任务队列系统；
 - 云服务；
 - Prompt Collection；
@@ -81,6 +86,20 @@ Agent Execution Template 不是：
 AI Coding Agent 在项目里工作的文件协议和安全边界。
 ```
 
+明确禁止混淆：
+
+- Agent Execution Template 不做 workspace 切换、多仓库管理、sandbox 生命周期、session fork / rollback 或 worker 调度。
+- 与外部运行时集成时，不应把业务任务定义、项目最终形态说明、仓库内文件修改规则、acceptance criteria 或具体编码上下文移出本协议。
+
+与 `openclaw-workspaces` 这类外部运行时一起使用时，推荐分工是：
+
+```text
+openclaw-workspaces = AI Workspace & Session Runtime
+agent-execution-template = AI Repo Execution Protocol
+```
+
+外部运行时负责仓库外能力，例如创建独立 workspace、切换项目上下文、保存/恢复/打包 session、管理 worker/agent 运行环境、隔离污染，以及未来承载多 Agent Task Graph。
+
 ## 6. 安装与日常使用
 
 在任意项目根目录执行：
@@ -225,6 +244,8 @@ template 是协议。
 project 是现场。
 ```
 
+这里的“项目现场”只指某个仓库内的 `ai/project/**` 执行上下文，不是跨项目 workspace/runtime。外部 workspace、session 和 sandbox 生命周期应由外部运行时管理。
+
 ## 8. template 区与 project 区
 
 ### 8.1 `ai/template/`
@@ -301,6 +322,7 @@ npx -y @wnlen/agent-execution-template init
 - 创建缺失的 `ai/project/**` 文件；
 - 不覆盖已有 `ai/project/**`；
 - 安装或覆盖 `ai/template/**`；
+- 创建或更新根目录 `AGENTS.md` / `CLAUDE.md` 中的同内容兼容托管块；
 - 支持 `--lang zh|en`，默认中文；
 - 输出下一步使用说明。
 
@@ -310,6 +332,11 @@ npx -y @wnlen/agent-execution-template init
 init 可以安装模板协议，但不能覆盖用户现场。
 ```
 
+根目录 AI 兼容入口文件只管理 `agent-execution-template` 标记块，不能覆盖用户已有
+`AGENTS.md` 或 `CLAUDE.md` 内容。两个文件中的托管块内容必须一致；这不是两套协议，
+而是分别适配通用 Agent / Codex 和 Claude Code 的自动发现约定。托管块必须要求 AI 在“开始初始化这个项目”时先读
+`ai/template/prompt.md`，再由它路由到 `ai/template/bootstrap.md`。
+
 ### 9.2 `update`
 
 ```bash
@@ -319,6 +346,7 @@ npx -y @wnlen/agent-execution-template update
 作用：
 
 - 只更新 `ai/template/**`；
+- 刷新根目录 AI 兼容入口文件中的托管块；
 - 绝不修改 `ai/project/**`；
 - 默认沿用 `ai/template/LANG` 中记录的已安装语言；
 - 输出更新文件列表和模板版本。
@@ -392,7 +420,7 @@ npx -y @wnlen/agent-execution-template doctor
 ```text
 Agent Execution Template 检查
 
-模板版本: 0.8.19
+模板版本: 0.8.21
 模板语言: zh
 
 [通过] ai/template/LANG
@@ -448,6 +476,13 @@ npx -y @wnlen/agent-execution-template reconcile
 开始初始化这个项目
 ```
 
+为了让 AI 工具能发现这个入口，`init` 会在仓库根目录安装 `AGENTS.md` 和
+`CLAUDE.md` 兼容入口托管块。两个托管块内容相同，不代表两套协议；它们分别适配不同
+AI 工具的自动发现约定。兼容这些入口的 AI 工具必须先读取托管块，再读取
+`ai/template/prompt.md`，最后由 `prompt.md` 路由到 `ai/template/bootstrap.md`。
+如果宿主工具没有自动读取根目录入口，人类应先要求它读取 `AGENTS.md` 或
+`CLAUDE.md`。
+
 面向用户的任务执行入口是：
 
 ```text
@@ -469,17 +504,18 @@ npx -y @wnlen/agent-execution-template reconcile
 内部协议入口分别由 `ai/template/bootstrap.md`、`ai/template/prompt.md` 和
 `ai/template/reconcile.md` 承载，用户不需要记忆这些文件名。
 
-执行入口固定要求 AI Agent 先读：
+执行入口采用懒加载。AI Agent 先读：
 
 ```text
-1. ai/template/protocol.md
-2. ai/template/rules/core.md
-3. ai/project/project.md
-4. ai/project/runtime.md
-5. ai/project/task.md
+0. AGENTS.md 或 CLAUDE.md 中的同内容 agent-execution-template 兼容托管块
+1. ai/template/prompt.md
 ```
 
-然后执行当前任务，并写入：
+`prompt.md` 只做模式路由：初始化时再读 `bootstrap.md`；整合时再读
+`reconcile.md`；执行任务时才读 `protocol.md`、`rules/core.md`、
+`execution-policy.md`、`project.md`、`runtime.md` 和 `task.md`。
+
+执行完成后写入：
 
 ```text
 ai/project/result.json
@@ -540,12 +576,15 @@ ai/project/task.md
 
 AI 在引导模式中负责先生成项目上下文草稿。默认读取范围包括：
 
-- 根目录文档：`README*`、`AGENTS.md`、`CLAUDE.md`、`CONTRIBUTING*`、`CHANGELOG*`；
+- 根目录文档：`README*`、`CONTRIBUTING*`、`CHANGELOG*`；
 - package/build manifest：`package.json`、`pyproject.toml`、`Cargo.toml`、`go.mod`、`pom.xml`、`build.gradle*`、`Makefile`；
 - 项目文档：`docs/**`，优先 overview、architecture、setup、testing、deployment、API、ADR、decision；
 - 已有 AI refs：`ai/project/refs/*.md`；
 - source / test / config / docs 的浅层目录结构。
 
+`AGENTS.md` 和 `CLAUDE.md` 是同内容 AI 入口路由文件，只用于宿主工具自动发现，
+不作为项目业务证据读取。
+
 如果文档和 manifest 不足，允许从业务代码做有边界推断：
 
 - 先看顶层目录和文件名；
@@ -1066,6 +1105,10 @@ git diff --check
 - 自动运行 Agent；
 - 自动切换模型；
 - 多 Agent 编排；
+- workspace 切换；
+- sandbox 生命周期；
+- session fork / rollback；
+- worker 调度；
 - 云同步；
 - IDE 插件；
 - 发布流水线。
@@ -1075,7 +1118,7 @@ git diff --check
 Agent Execution Template v0.8 已经从一个 prompt/template 原型，升级为：
 
 ```text
-低摩擦、可安装、可升级、保护用户现场的 AI 执行协议 npm 包雏形。
+低摩擦、可安装、可升级、保护用户现场的 AI Repo Execution Protocol npm 包雏形。
 ```
 
 它的长期价值不在于替代任何模型或 Agent，而在于提供一套稳定协议：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wnlen/agent-execution-template",
-  "version": "0.8.19",
+  "version": "0.8.21",
   "description": "Low-friction AI execution protocol template for coding agents.",
   "bin": {
     "agent-execution-template": "bin/agent-execution-template.js"

package/template/en/ai/README.md

@@ -4,9 +4,12 @@ Copy this folder into a target software project.
 
 ```text
 template is protocol
-project is the field workspace
+project is repo-local context
 ```
 
+Here, `project` means the repo-local `ai/project/**` context. It is not an
+external workspace, session, or sandbox runtime.
+
 ## Files
 
 - `template/prompt.md`: AI startup prompt.

package/template/en/ai/template/VERSION

@@ -1 +1 @@
-0.8.19
+0.8.21