@wnlen/agent-execution-template 0.8.20 → 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",
@@ -74,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/ 里的资料
 
@@ -131,6 +136,8 @@ const TEXT = {
     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: "已就绪，但存在警告",
@@ -184,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,6 +250,8 @@ Usage:
     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",
@@ -397,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 [
@@ -495,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}`);
@@ -522,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}
@@ -559,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);
@@ -653,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}`);
 }
@@ -866,6 +948,13 @@ function doctor() {
     console.log(`[${text.pass}] ${file}`);
   }
 
+  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"]

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.20",
+  "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.20
+0.8.21

package/template/en/ai/template/bootstrap.md

@@ -44,7 +44,7 @@ runtime files, result files, or metrics files during bootstrap.
 
 Read high-signal project evidence in this order:
 
-1. Root docs: `README*`, `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING*`, `CHANGELOG*`
+1. Root docs: `README*`, `CONTRIBUTING*`, `CHANGELOG*`
 2. Manifests: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`,
    `pom.xml`, `build.gradle*`, `Makefile`
 3. Project docs: `docs/**`, preferring overview, architecture, setup, testing,
@@ -62,6 +62,9 @@ bounded read:
   project purpose, module boundaries, commands, and constraints;
 - do not read the whole codebase unless the human explicitly authorizes it.
 
+Do not treat `AGENTS.md` or `CLAUDE.md` as project business evidence; they are
+AI entrypoint routing files only.
+
 Do not read dependency folders, build outputs, coverage outputs, lockfiles
 except to infer package manager, secret files, environment files, or archives
 unless the human explicitly references them.

package/template/en/ai/template/prompt.md

@@ -5,23 +5,25 @@ Execute the workflow below.
 
 You are operating inside an Agent Execution Template workspace.
 
-First read:
+This file only routes the workflow. First read minimal state:
 
-1. `ai/template/protocol.md`
-2. `ai/template/rules/core.md`
-3. `ai/template/execution-policy.md`
+1. `ai/project/project.md` if present
+2. `ai/project/task.md` if present
+3. Shallow listings of `ai/project/inbox/`, `ai/project/inbox/ideas/`, and `ai/project/proposals/final-shape-updates/`
 
 Then choose the mode:
 
 - If the user asks to update the North Star, final shape, product constitution,
   module map, roadmap, or project direction, or if
   `ai/project/inbox/ideas/` contains non-`.gitkeep` ideas waiting for
-  evaluation, draft a `strategy_update` task or produce the proposal directly,
-  then stop for human confirmation.
+  evaluation, read `ai/template/protocol.md`, `ai/template/rules/core.md`, and
+  relevant direction refs, then draft a `strategy_update` task or produce the
+  proposal directly, then stop for human confirmation.
 - If the user explicitly confirms that a proposal under
   `ai/project/proposals/final-shape-updates/*.md` may be merged, draft or
-  execute an `apply_strategy_update` task. If the proposal is still
-  `proposed`, update it to `accepted` based on that explicit confirmation.
+  execute an `apply_strategy_update` task after reading
+  `ai/template/protocol.md` and `ai/template/rules/core.md`. If the proposal is
+  still `proposed`, update it to `accepted` based on that explicit confirmation.
 - If the user says "Start initializing this project and absorb the material in ai/project/inbox/",
   or asks to initialize while also absorbing material from
   `ai/project/inbox/`, inspect `ai/project/project.md` first. If it already
@@ -54,7 +56,8 @@ Then choose the mode:
   the human hunt through files for gaps.
 - Use Execution Mode only after `ai/project/project.md` and
   `ai/project/task.md` are ready enough to define identity, goal, scope,
-  permission, and acceptance.
+  permission, and acceptance. Only then read `ai/template/protocol.md`,
+  `ai/template/rules/core.md`, and `ai/template/execution-policy.md`.
 
 ## Task Draft Handoff
 

package/template/en/ai/template/protocol.md

@@ -5,12 +5,18 @@ execution context.
 
 ```text
 ai/template/ = reusable execution protocol
-ai/project/  = current project execution workspace
+ai/project/  = current repo execution context
 ```
 
-Template is protocol. Project is the field workspace.
+Template is protocol. Project is repo-local context.
 
-The project workspace stores both execution state and direction. The direction
+Here, "repo execution context" means the repo-local `ai/project/**` context,
+not an external workspace / session / sandbox runtime. An external
+runtime may enter the repository and read this protocol, but should not replace
+`task.md`, file modification rules, acceptance criteria, or concrete coding
+context.
+
+The repo-local context stores both execution state and direction. The direction
 layer answers "why is this worth doing and where should the project grow"; the
 execution layer answers "what is this task and how will it be accepted."
 

package/template/zh/ai/README.md

@@ -7,6 +7,8 @@ template 是协议
 project 是现场工作区
 ```
 
+这里的 `project` 是仓库内 `ai/project/**` 的项目现场，不是外部 workspace、session 或 sandbox 运行时。
+
 ## 文件
 
 - `template/prompt.md`：AI 启动提示。

package/template/zh/ai/template/VERSION

@@ -1 +1 @@
-0.8.20
+0.8.21

package/template/zh/ai/template/bootstrap.md

@@ -36,7 +36,7 @@
 
 按下面顺序读取高价值项目证据：
 
-1. 根目录文档：`README*`、`AGENTS.md`、`CLAUDE.md`、`CONTRIBUTING*`、`CHANGELOG*`
+1. 根目录文档：`README*`、`CONTRIBUTING*`、`CHANGELOG*`
 2. 清单文件：`package.json`、`pyproject.toml`、`Cargo.toml`、`go.mod`、
    `pom.xml`、`build.gradle*`、`Makefile`
 3. 项目文档：`docs/**`，优先阅读概览、架构、安装、测试、部署、API、ADR 和决策文件
@@ -51,6 +51,8 @@
 - 只读取足够识别目的、模块边界、命令和约束的路由、模块、配置和测试文件；
 - 除非人类明确授权，不要读取整个代码库。
 
+不要把 `AGENTS.md` 或 `CLAUDE.md` 当作项目业务证据；它们只是 AI 入口路由文件。
+
 除非人类明确引用或授权，不要读取依赖目录、构建产物、覆盖率输出、锁文件
 （推断包管理器除外）、密钥文件、环境文件或归档目录。
 

package/template/zh/ai/template/prompt.md

@@ -3,18 +3,20 @@
 不要总结这个文件。
 按下面流程执行。你正在 Agent Execution Template 工作区内操作。
 
-先读取：
+本文件只负责路由。先读取最小状态：
 
-1. `ai/template/protocol.md`
-2. `ai/template/rules/core.md`
-3. `ai/template/execution-policy.md`
+1. `ai/project/project.md`（如果存在）
+2. `ai/project/task.md`（如果存在）
+3. `ai/project/inbox/`、`ai/project/inbox/ideas/` 和 `ai/project/proposals/final-shape-updates/` 的浅层列表
 
 选择模式：
 
 - 用户要求更新北极星、最终形态、产品宪法、模块地图、路线图或项目方向，
-  或 `ai/project/inbox/ideas/` 有待评估灵感：走 `strategy_update`，生成提案后停下确认。
+  或 `ai/project/inbox/ideas/` 有待评估灵感：读取 `ai/template/protocol.md`、
+  `ai/template/rules/core.md` 和相关方向 refs，走 `strategy_update`，生成提案后停下确认。
 - 用户明确确认某个 `ai/project/proposals/final-shape-updates/*.md` 可合并：
-  走 `apply_strategy_update`。若 proposal 仍为 `proposed`，先改为 `accepted`。
+  读取 `ai/template/protocol.md` 和 `ai/template/rules/core.md`，走
+  `apply_strategy_update`。若 proposal 仍为 `proposed`，先改为 `accepted`。
 - 如果用户说“开始初始化这个项目，并吸收 ai/project/inbox/ 里的资料”，
   或要求初始化时吸收 inbox：先检查 `ai/project/project.md`。若已存在且有效，
   执行 `ai/template/reconcile.md`，不要重新 bootstrap；若为空、占位或不完整，执行
@@ -33,7 +35,8 @@
   待确认上下文、待确认任务、失败结果、未完成任务或明显风险；给出建议或起草
   `ai/project/task.md`，不要让人类自己找问题。
 - 只有当 `project.md` 和 `task.md` 足以定义身份、目标、范围、权限和验收时，
-  才进入执行模式。
+  才读取 `ai/template/protocol.md`、`ai/template/rules/core.md`、
+  `ai/template/execution-policy.md` 并进入执行模式。
 
 ## 任务草稿交接
 

package/template/zh/ai/template/protocol.md

@@ -9,6 +9,10 @@ ai/project/  = 当前项目执行工作区
 
 `template` 是协议，`project` 是现场。
 
+这里的“项目执行工作区”只指当前仓库内的 `ai/project/**` 现场上下文，不是仓库外
+workspace / session / sandbox 运行时。外部运行时可以进入仓库并读取本协议，但不应
+替代 `task.md`、文件修改规则、验收标准或具体编码上下文。
+
 项目现场同时保存任务和方向层。方向层回答“为什么做、往哪里长”，执行层回答
 “这次做什么、如何验收”。
 

package/test/selftest.js

@@ -40,6 +40,17 @@ function write(cwd, relativePath, content) {
   fs.writeFileSync(path.join(cwd, relativePath), content);
 }
 
+function countOccurrences(content, pattern) {
+  return content.split(pattern).length - 1;
+}
+
+function managedEntrypointBlock(content) {
+  const start = content.indexOf("<!-- agent-execution-template:start -->");
+  const end = content.indexOf("<!-- agent-execution-template:end -->", start);
+  assert(start >= 0 && end >= 0, "entrypoint content should include a managed block");
+  return content.slice(start, end + "<!-- agent-execution-template:end -->".length);
+}
+
 function createTempProject(name) {
   return fs.mkdtempSync(path.join(os.tmpdir(), `${name}-`));
 }
@@ -48,6 +59,16 @@ function testInitUpdateDoctor() {
   const cwd = createTempProject("agent-execution-template-selftest");
 
   run(["init"], cwd);
+  assert(exists(cwd, "AGENTS.md"), "init should create root AGENTS.md entrypoint");
+  assert(exists(cwd, "CLAUDE.md"), "init should create root CLAUDE.md entrypoint");
+  assert(read(cwd, "AGENTS.md").includes("agent-execution-template:start"), "AGENTS.md should include managed protocol block");
+  assert(read(cwd, "AGENTS.md").includes("ai/template/prompt.md"), "AGENTS.md should route agents to the protocol prompt");
+  assert(read(cwd, "CLAUDE.md").includes("ai/template/prompt.md"), "CLAUDE.md should route Claude to the same protocol prompt");
+  assert(managedEntrypointBlock(read(cwd, "AGENTS.md")) === managedEntrypointBlock(read(cwd, "CLAUDE.md")), "AGENTS.md and CLAUDE.md should contain the same managed compatibility block");
+  assert(read(cwd, "AGENTS.md").includes("有意同时写入 `AGENTS.md` 和 `CLAUDE.md`"), "AGENTS.md should explain intentional compatibility duplication");
+  assert(read(cwd, "AGENTS.md").includes("在 `ai/template/prompt.md` 完成路由前"), "AGENTS.md should stay a short router");
+  assert(!read(cwd, "AGENTS.md").includes("ai/template/bootstrap.md"), "AGENTS.md should not duplicate bootstrap routing details");
+  assert(!read(cwd, "CLAUDE.md").includes("ai/template/bootstrap.md"), "CLAUDE.md should not duplicate bootstrap routing details");
   assert(read(cwd, "ai/template/LANG") === "zh\n", "init should default to zh template");
   assert(exists(cwd, "ai/template/VERSION"), "init should create template VERSION");
   assert(exists(cwd, "ai/template/bootstrap.md"), "init should create template bootstrap prompt");
@@ -80,7 +101,9 @@ function testInitUpdateDoctor() {
   assert(read(cwd, "ai/template/bootstrap.md").includes("未吸收资料"), "bootstrap handoff should audit unabsorbed material");
   assert(read(cwd, "ai/template/bootstrap.md").includes("冲突处理"), "bootstrap handoff should audit conflict handling");
   assert(read(cwd, "ai/template/prompt.md").includes("任务草稿交接"), "execution prompt should include task handoff");
-  assert(read(cwd, "ai/template/prompt.md").includes("ai/template/execution-policy.md"), "execution prompt should read execution policy");
+  assert(read(cwd, "ai/template/prompt.md").includes("本文件只负责路由"), "execution prompt should be a lightweight router");
+  assert(read(cwd, "ai/template/prompt.md").includes("才读取 `ai/template/protocol.md`"), "execution prompt should lazy-load execution policy only for execution");
+  assert(read(cwd, "ai/template/bootstrap.md").includes("不要把 `AGENTS.md` 或 `CLAUDE.md` 当作项目业务证据"), "bootstrap should not treat root agent entrypoints as project evidence");
   assert(read(cwd, "ai/template/execution-policy.md").includes("风险分级"), "execution policy should include risk rubric");
   assert(read(cwd, "ai/template/execution-policy.md").includes("execution_policy.task_tree"), "execution policy should require task tree persistence");
   assert(read(cwd, "ai/template/prompt.md").includes("也默认只处理 `ai/project/inbox/*.md`"), "execution prompt should narrow inbox reconciliation");
@@ -132,7 +155,9 @@ function testInitUpdateDoctor() {
   assert(read(cwd, "ai/project/proposals/final-shape-updates/_template.md").includes("`accepted`"), "proposal template should describe accepted status");
   const initOutput = run(["init"], cwd);
   assert(initOutput.includes("开始初始化这个项目"), "init output should provide compact natural bootstrap prompt");
-  assert(initOutput.includes("[初始化]"), "init output should distinguish pre-bootstrap guidance");
+  assert(initOutput.includes("根目录 AI 兼容入口: AGENTS.md / CLAUDE.md"), "init output should mention root AI compatibility entrypoints");
+  assert(initOutput.includes("协议已安装。项目上下文尚未初始化"), "init output should distinguish protocol install from project context bootstrap");
+  assert(initOutput.includes("[下一步：让 AI 初始化项目上下文]"), "init output should guide the AI bootstrap as the next step");
   assert(initOutput.includes("开始初始化这个项目，并吸收 ai/project/inbox/ 里的资料"), "init output should explain bootstrap with existing material");
   assert(initOutput.includes("整合 ai/project/inbox/ 里的新资料"), "init output should provide compact natural reconcile prompt");
   assert(initOutput.includes("优化上下文"), "init output should expose project context refresh in user language");
@@ -142,7 +167,11 @@ function testInitUpdateDoctor() {
   assert(!initOutput.includes("维护者提示"), "init output should not show source checkout guidance in user projects");
   assert(!initOutput.includes("[已更新]"), "init output should hide detailed file changes by default");
   assert(!initOutput.includes("Read ai/template/bootstrap.md"), "init output should not use weak Read bootstrap command");
+  assert(countOccurrences(read(cwd, "AGENTS.md"), "agent-execution-template:start") === 1, "init should not duplicate AGENTS.md managed blocks");
+  assert(countOccurrences(read(cwd, "CLAUDE.md"), "agent-execution-template:start") === 1, "init should not duplicate CLAUDE.md managed blocks");
   assert(run(["init", "--verbose"], cwd).includes("[已更新] ai/template/VERSION"), "init --verbose should show detailed file changes");
+  assert(countOccurrences(read(cwd, "AGENTS.md"), "agent-execution-template:start") === 1, "re-running init should keep one AGENTS.md managed block");
+  assert(countOccurrences(read(cwd, "CLAUDE.md"), "agent-execution-template:start") === 1, "re-running init should keep one CLAUDE.md managed block");
   const reconcileOutput = run(["reconcile"], cwd);
   assert(reconcileOutput.includes("Agent Execution Template 上下文整合"), "reconcile should use installed Chinese language");
   assert(reconcileOutput.includes("整合 ai/project/inbox/ 里的新资料"), "reconcile should print natural Chinese prompt");
@@ -154,8 +183,10 @@ function testInitUpdateDoctor() {
   write(cwd, "ai/project/project.md", "USER PROJECT MARKER\n");
   run(["update"], cwd);
   assert(read(cwd, "ai/project/project.md") === "USER PROJECT MARKER\n", "update must not overwrite project.md");
+  assert(read(cwd, "AGENTS.md").includes("ai/template/prompt.md"), "update should keep root agent entrypoint block installed");
 
   const doctorOutput = run(["doctor"], cwd);
+  assert(doctorOutput.includes("根目录 AI 兼容入口已安装: AGENTS.md / CLAUDE.md"), "doctor should report root AI compatibility entrypoint status");
   assert(doctorOutput.includes("ai/project/result.json JSON"), "doctor should validate result JSON");
   assert(doctorOutput.includes("ai/project/result.json schema"), "doctor should validate result schema");
   assert(doctorOutput.includes("ai/project/metrics.json JSON"), "doctor should validate metrics JSON");
@@ -167,6 +198,15 @@ function testEnglishInitUpdateDoctor() {
   const cwd = createTempProject("agent-execution-template-en");
 
   const initOutput = run(["init", "--lang", "en"], cwd);
+  assert(exists(cwd, "AGENTS.md"), "English init should create root AGENTS.md entrypoint");
+  assert(exists(cwd, "CLAUDE.md"), "English init should create root CLAUDE.md entrypoint");
+  assert(read(cwd, "AGENTS.md").includes("ai/template/prompt.md"), "English AGENTS.md should route agents to the protocol prompt");
+  assert(read(cwd, "CLAUDE.md").includes("ai/template/prompt.md"), "English CLAUDE.md should route Claude to the same protocol prompt");
+  assert(managedEntrypointBlock(read(cwd, "AGENTS.md")) === managedEntrypointBlock(read(cwd, "CLAUDE.md")), "English AGENTS.md and CLAUDE.md should contain the same managed compatibility block");
+  assert(read(cwd, "AGENTS.md").includes("intentionally duplicated in `AGENTS.md` and `CLAUDE.md`"), "English AGENTS.md should explain intentional compatibility duplication");
+  assert(read(cwd, "AGENTS.md").includes("before `ai/template/prompt.md` routes"), "English AGENTS.md should stay a short router");
+  assert(!read(cwd, "AGENTS.md").includes("ai/template/bootstrap.md"), "English AGENTS.md should not duplicate bootstrap routing details");
+  assert(!read(cwd, "CLAUDE.md").includes("ai/template/bootstrap.md"), "English CLAUDE.md should not duplicate bootstrap routing details");
   assert(read(cwd, "ai/template/LANG") === "en\n", "init --lang en should install English template");
   assert(exists(cwd, "ai/template/execution-policy.md"), "English init should create execution policy prompt");
   assert(exists(cwd, "ai/template/schemas/result.schema.json"), "English init should create result schema");
@@ -183,7 +223,9 @@ function testEnglishInitUpdateDoctor() {
   assert(read(cwd, "ai/template/bootstrap.md").includes("Unabsorbed material"), "English bootstrap handoff should audit unabsorbed material");
   assert(read(cwd, "ai/template/bootstrap.md").includes("Conflict handling"), "English bootstrap handoff should audit conflict handling");
   assert(read(cwd, "ai/template/prompt.md").includes("Start initializing this project"), "English execution prompt should route natural bootstrap entry");
-  assert(read(cwd, "ai/template/prompt.md").includes("ai/template/execution-policy.md"), "English execution prompt should read execution policy");
+  assert(read(cwd, "ai/template/prompt.md").includes("This file only routes the workflow"), "English execution prompt should be a lightweight router");
+  assert(read(cwd, "ai/template/prompt.md").includes("Only then read `ai/template/protocol.md`"), "English execution prompt should lazy-load execution policy only for execution");
+  assert(read(cwd, "ai/template/bootstrap.md").includes("Do not treat `AGENTS.md` or `CLAUDE.md` as project business evidence"), "English bootstrap should not treat root agent entrypoints as project evidence");
   assert(read(cwd, "ai/template/execution-policy.md").includes("Risk Rubric"), "English execution policy should include risk rubric");
   assert(read(cwd, "ai/template/execution-policy.md").includes("execution_policy.task_tree"), "English execution policy should require task tree persistence");
   assert(read(cwd, "ai/template/prompt.md").includes("default to only `ai/project/inbox/*.md`"), "English execution prompt should narrow inbox reconciliation");
@@ -232,7 +274,9 @@ function testEnglishInitUpdateDoctor() {
   assert(read(cwd, "ai/template/reconcile.md").includes("Unabsorbed material"), "English reconcile handoff should audit unabsorbed material");
   assert(read(cwd, "ai/template/reconcile.md").includes("Conflict handling"), "English reconcile handoff should audit conflict handling");
   assert(initOutput.includes("Start initializing this project"), "English init output should provide English bootstrap prompt");
-  assert(initOutput.includes("[Initialize]"), "English init output should distinguish pre-bootstrap guidance");
+  assert(initOutput.includes("root AI compatibility entrypoints: AGENTS.md / CLAUDE.md"), "English init output should mention root AI compatibility entrypoints");
+  assert(initOutput.includes("protocol installed. Project context is not initialized yet"), "English init output should distinguish protocol install from project context bootstrap");
+  assert(initOutput.includes("[Next: ask the AI to initialize project context]"), "English init output should guide the AI bootstrap as the next step");
   assert(initOutput.includes("Start initializing this project and absorb the material in ai/project/inbox/"), "English init output should explain bootstrap with existing material");
   assert(initOutput.includes("Reconcile the new material in ai/project/inbox/"), "English init output should provide English reconcile prompt");
   assert(initOutput.includes("Improve context"), "English init output should expose context refresh in user language");
@@ -250,6 +294,7 @@ function testEnglishInitUpdateDoctor() {
 
   const doctorOutput = run(["doctor"], cwd);
   assert(doctorOutput.includes("Template language: en"), "doctor should show installed English language");
+  assert(doctorOutput.includes("root AI compatibility entrypoints installed: AGENTS.md / CLAUDE.md"), "English doctor should report root AI compatibility entrypoint status");
   assert(doctorOutput.includes("ai/project/result.json JSON"), "English doctor should validate result JSON");
   assert(doctorOutput.includes("ai/project/result.json schema"), "English doctor should validate result schema");
   assert(doctorOutput.includes("ai/project/task.md front matter"), "English doctor should validate task front matter");
@@ -362,6 +407,32 @@ permission: {}
   assert(taskPolicyWarnOutput.includes("任务 front matter 缺少关键字段"), "doctor should warn when execution policy fields are incomplete");
 }
 
+function testRootEntrypointPreservesUserContent() {
+  const cwd = createTempProject("agent-execution-template-entrypoints");
+  write(cwd, "AGENTS.md", "# Existing agent rules\n\nKeep this user rule.\n");
+
+  run(["init"], cwd);
+  assert(read(cwd, "AGENTS.md").includes("Keep this user rule."), "init should preserve existing AGENTS.md content");
+  assert(read(cwd, "AGENTS.md").includes("agent-execution-template:start"), "init should append a managed AGENTS.md block");
+  assert(countOccurrences(read(cwd, "AGENTS.md"), "agent-execution-template:start") === 1, "init should append one AGENTS.md block");
+
+  run(["init"], cwd);
+  assert(read(cwd, "AGENTS.md").includes("Keep this user rule."), "re-running init should preserve existing AGENTS.md content");
+  assert(countOccurrences(read(cwd, "AGENTS.md"), "agent-execution-template:start") === 1, "re-running init should replace, not duplicate, the managed AGENTS.md block");
+
+  run(["update"], cwd);
+  assert(read(cwd, "AGENTS.md").includes("Keep this user rule."), "update should preserve existing AGENTS.md content");
+  assert(countOccurrences(read(cwd, "AGENTS.md"), "agent-execution-template:start") === 1, "update should keep one managed AGENTS.md block");
+
+  fs.unlinkSync(path.join(cwd, "CLAUDE.md"));
+  const missingClaudeOutput = run(["doctor"], cwd);
+  assert(missingClaudeOutput.includes("缺少根目录 AI 兼容入口托管块"), "doctor should warn when one root agent entrypoint is missing");
+
+  fs.unlinkSync(path.join(cwd, "AGENTS.md"));
+  const doctorOutput = run(["doctor"], cwd);
+  assert(doctorOutput.includes("缺少根目录 AI 兼容入口托管块"), "doctor should warn when root agent entrypoints are missing");
+}
+
 function testRefreshBacksUpAndImportsOldProject() {
   const cwd = createTempProject("agent-execution-template-refresh");
   run(["init"], cwd);
@@ -445,6 +516,7 @@ function main() {
   testInitUpdateDoctor();
   testEnglishInitUpdateDoctor();
   testDoctorFailureAndWarning();
+  testRootEntrypointPreservesUserContent();
   testRefreshBacksUpAndImportsOldProject();
   testNextCommandRoutesByProjectState();
   testPermissionErrorIsActionable();