@wnlen/agent-execution-template 0.8.14

package/template/en/ai/template/rules/output.md

@@ -0,0 +1,51 @@
+# Output Rules
+
+Every execution must write:
+
+- `ai/project/result.json`
+- `ai/project/result.md`
+- `ai/project/metrics.json`
+
+## Status
+
+Use one of:
+
+- `success`
+- `partial`
+- `failed`
+- `blocked`
+
+Do not use `success` unless verification passed.
+
+## Result JSON
+
+`ai/project/result.json` is the authoritative machine-readable result.
+It must include scope, files read, refs read, changed files, commands,
+verification, assumptions, issues, next steps, and runtime update proposals.
+
+## Result Markdown
+
+`ai/project/result.md` is the human-readable summary. Keep it short:
+
+```md
+## Status
+success | partial | failed | blocked
+
+## Changed
+- file
+
+## Verified
+- level
+- evidence
+
+## Issues
+- issue if any
+
+## Next
+- next step
+```
+
+## Metrics
+
+`ai/project/metrics.json` records model tier, escalation trigger, strong-model
+role, token estimates, duration, success, human fix, and reuse potential.

package/template/en/ai/template/schemas/metrics.schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Agent Execution Template Metrics Schema",
+  "type": "object",
+  "required": [
+    "protocol_version",
+    "task_id",
+    "task_type",
+    "model",
+    "model_tier",
+    "escalated",
+    "escalation_reason",
+    "model_policy_followed",
+    "escalation_trigger_hit",
+    "strong_model_role",
+    "input_tokens_estimated",
+    "output_tokens_estimated",
+    "duration_minutes",
+    "success",
+    "human_fix_required",
+    "failure_reason",
+    "reuse_potential",
+    "notes"
+  ],
+  "properties": {
+    "protocol_version": {
+      "const": "0.8"
+    },
+    "task_id": {
+      "type": "string"
+    },
+    "task_type": {
+      "type": "string"
+    },
+    "model": {
+      "type": "string"
+    },
+    "model_tier": {
+      "enum": [
+        "cheap",
+        "standard",
+        "strong"
+      ]
+    },
+    "escalated": {
+      "type": "boolean"
+    },
+    "escalation_reason": {
+      "type": "string"
+    },
+    "model_policy_followed": {
+      "type": "boolean"
+    },
+    "escalation_trigger_hit": {
+      "type": "string"
+    },
+    "strong_model_role": {
+      "type": "string"
+    },
+    "input_tokens_estimated": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "output_tokens_estimated": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "duration_minutes": {
+      "type": "number",
+      "minimum": 0
+    },
+    "success": {
+      "type": "boolean"
+    },
+    "human_fix_required": {
+      "type": "boolean"
+    },
+    "failure_reason": {
+      "type": "string"
+    },
+    "reuse_potential": {
+      "enum": [
+        "low",
+        "medium",
+        "high"
+      ]
+    },
+    "notes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "escalated": {
+            "const": true
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "escalation_reason": {
+            "minLength": 1
+          },
+          "escalation_trigger_hit": {
+            "minLength": 1
+          },
+          "strong_model_role": {
+            "minLength": 1
+          }
+        }
+      }
+    }
+  ]
+}

package/template/en/ai/template/schemas/result.schema.json

@@ -0,0 +1,234 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Agent Execution Template Result Schema",
+  "type": "object",
+  "required": [
+    "protocol_version",
+    "status",
+    "scope_followed",
+    "files_read",
+    "refs_read",
+    "files_changed",
+    "commands_run",
+    "verification",
+    "assumptions",
+    "issues",
+    "next",
+    "runtime_update"
+  ],
+  "properties": {
+    "protocol_version": {
+      "const": "0.8"
+    },
+    "status": {
+      "enum": [
+        "success",
+        "partial",
+        "failed",
+        "blocked"
+      ]
+    },
+    "task_id": {
+      "type": "string"
+    },
+    "task_summary": {
+      "type": "string"
+    },
+    "scope_followed": {
+      "type": "boolean"
+    },
+    "files_read": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "refs_read": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "file",
+          "reason"
+        ],
+        "properties": {
+          "file": {
+            "type": "string"
+          },
+          "reason": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "files_changed": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "file",
+          "change_type",
+          "reason"
+        ],
+        "properties": {
+          "file": {
+            "type": "string"
+          },
+          "change_type": {
+            "enum": [
+              "created",
+              "modified",
+              "deleted"
+            ]
+          },
+          "reason": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "commands_run": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "command",
+          "result",
+          "notes"
+        ],
+        "properties": {
+          "command": {
+            "type": "string"
+          },
+          "result": {
+            "enum": [
+              "passed",
+              "failed",
+              "skipped"
+            ]
+          },
+          "notes": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "verification": {
+      "type": "object",
+      "required": [
+        "level",
+        "passed",
+        "evidence"
+      ],
+      "properties": {
+        "level": {
+          "enum": [
+            "none",
+            "read_only",
+            "static",
+            "command",
+            "test",
+            "manual"
+          ]
+        },
+        "passed": {
+          "type": "boolean"
+        },
+        "evidence": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "properties": {
+        "git_diff_summary": {
+          "type": "string"
+        },
+        "changed_files_from_git": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "command_outputs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "unverified_claims": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "assumptions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "issues": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "next": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "runtime_update": {
+      "type": "object",
+      "required": [
+        "required",
+        "changes",
+        "reason"
+      ],
+      "properties": {
+        "required": {
+          "type": "boolean"
+        },
+        "changes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "reason": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "status": {
+            "const": "success"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "verification": {
+            "properties": {
+              "passed": {
+                "const": true
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
+}

package/template/zh/ai/README.md

@@ -0,0 +1,129 @@
+# ai/ 执行层
+
+把这个目录复制到目标软件项目中。
+
+```text
+template 是协议
+project 是现场工作区
+```
+
+## 文件
+
+- `template/prompt.md`：AI 启动提示。
+- `template/bootstrap.md`：项目发现和上下文引导提示。
+- `template/reconcile.md`：把新的权威资料合并进现有项目上下文。
+- `template/VERSION`：已安装模板版本。
+- `template/protocol.md`：引导流程、执行流程、模型分工、同步规则。
+- `template/rules/core.md`：引导范围、就绪度、风险、引用、权限和运行时治理。
+- `template/rules/output.md`：结果和指标输出规则。
+- `template/schemas/`：可选的结果和指标校验。
+- `project/project.md`：稳定项目身份。
+- `project/runtime.md`：当前执行上下文。
+- `project/task.md`：当前任务契约。
+- `project/result.json`：最新权威执行结果。
+- `project/result.md`：最新人类可读执行摘要。
+- `project/metrics.json`：最新模型、token、耗时、成功和复用信号。
+- `project/refs/final-shape.md`：项目北极星说明书 / 最终形态。
+- `project/refs/module-map.md`：当前模块地图。
+- `project/refs/roadmap.md`：阶段路线图。
+- `project/refs/`：只在需要时加载的详细引用。
+- `project/inbox/ideas/`：待评估的产品、业务、架构或方向灵感。
+- `project/inbox/processed/`：已经吸收进上下文的新资料，保留用于追溯。
+- `project/inbox/raw/`：长文本、访谈、碎片材料等原始输入。
+- `project/inbox/`：待吸收的新资料，例如更权威的业务文档。
+- `project/proposals/final-shape-updates/`：北极星和路线图修订提案。
+- `project/proposals/final-shape-updates/_template.md`：方向修订提案模板。
+- `project/archive/`：历史任务和结果，默认不读取。
+
+## 常规用法
+
+第一次接入项目时，对 AI 工具说：
+
+```text
+开始初始化这个项目
+```
+
+以后常用入口：
+
+- 想让 AI 继续做事：`继续推进这个项目`
+- 有新资料要吸收：放入 `project/inbox/`，然后说 `整合 ai/project/inbox/ 里的新资料`
+- 想重新总结和优化项目上下文：运行 `npx -y @wnlen/agent-execution-template refresh`
+- 有新方向或新想法要评估：放入 `project/inbox/ideas/`，然后说 `把 ai/project/inbox/ideas/ 里的新灵感生成方向修订提案`
+- 忘了下一步怎么走：运行 `npx -y @wnlen/agent-execution-template next`
+
+判断标准：
+
+- 资料 = 已确定的事实、文档、流程、接口、业务规则。
+- 方向 = 还没决定的新想法、产品策略、架构调整、路线变化。
+
+执行后检查 `project/result.json`、`project/result.md` 和 `project/metrics.json`。
+需要时归档旧任务和结果文件。
+
+## 上下文整合
+
+当出现更完整、更权威的新资料时，先放入：
+
+```text
+ai/project/inbox/
+```
+
+然后对 AI 工具说：
+
+```text
+整合 ai/project/inbox/ 里的新资料
+```
+
+整合流程会先给出计划，等你确认后才更新 `project.md`、`runtime.md` 和
+`refs/*`。整合完成后，已处理资料统一移动到
+`ai/project/inbox/processed/`。
+
+## 方向修订
+
+北极星、模块地图和路线图属于项目方向层：
+
+```text
+ai/project/refs/final-shape.md
+ai/project/refs/module-map.md
+ai/project/refs/roadmap.md
+```
+
+普通执行任务不能直接修改这些文件。新灵感先放入：
+
+```text
+ai/project/inbox/ideas/
+```
+
+然后让 AI 生成 `strategy_update` 提案。人类确认后，再用
+`apply_strategy_update` 合并到正式方向文档。
+
+## 同步规则
+
+从模板仓库同步到真实项目：
+
+- 只覆盖 `ai/template/**`。
+- 永远不要覆盖 `ai/project/**`。
+
+从真实项目回流到模板仓库：
+
+- 只回流 `ai/template/**`。
+- 永远不要回流 `ai/project/**`。
+
+## 引导规则
+
+- 人类提供意图、硬约束和最终验收。
+- Agent 从现有文档、清单、引用和项目文件中起草 `project/project.md` 和相关 `project/refs/*`。
+- 人类提供当前任务目标后，Agent 起草 `project/task.md`。
+- 人类在执行前检查并确认项目和任务草稿。
+- 引导只能写项目上下文文件；当提供当前任务时，也可以写 `project/task.md`。
+- 引导不得编辑源码、测试、配置、依赖文件、生成文件、运行时文件、结果文件或指标文件。
+- 最多问 3 个澄清问题。
+- 只在答案会改变范围、风险、权限或验收时提问。
+- 重复出现的假设应变成 `project/runtime.md` 更新建议。
+
+## 模型分工协议
+
+- 模型策略位于 `project/task.md.model_policy`。
+- 常规执行默认使用 `cheap`。
+- 中等实现复杂度使用 `standard`。
+- 只有规划、风险判断、架构复核、失败复盘或验收判断才使用 `strong`。
+- 在 `project/metrics.json` 中记录实际档位、触发条件、角色和升级原因。

package/template/zh/ai/project/inbox/.gitkeep

@@ -0,0 +1 @@
+

package/template/zh/ai/project/inbox/ideas/.gitkeep

@@ -0,0 +1 @@
+

package/template/zh/ai/project/inbox/raw/.gitkeep

@@ -0,0 +1 @@
+

package/template/zh/ai/project/metrics.json

@@ -0,0 +1,20 @@
+{
+  "protocol_version": "0.8",
+  "task_id": "",
+  "task_type": "",
+  "model": "",
+  "model_tier": "cheap",
+  "escalated": false,
+  "escalation_reason": "",
+  "model_policy_followed": true,
+  "escalation_trigger_hit": "",
+  "strong_model_role": "",
+  "input_tokens_estimated": 0,
+  "output_tokens_estimated": 0,
+  "duration_minutes": 0,
+  "success": false,
+  "human_fix_required": false,
+  "failure_reason": "",
+  "reuse_potential": "low",
+  "notes": []
+}

package/template/zh/ai/project/project.md

@@ -0,0 +1,42 @@
+# 项目
+
+这个文件是 Agent Execution Template 使用的稳定项目身份。
+优先在引导模式中，根据现有仓库文档和清单生成，然后由人类检查。
+未知事实标记为 `Unknown`。
+
+## 身份
+
+- 名称：
+- 目的：
+- 主要用户：
+
+## 技术
+
+- 语言：
+- 框架：
+- 包管理器：
+- 测试运行器：
+
+## 结构
+
+- 源码：
+- 测试：
+- 配置：
+- 文档：
+- 方向文档：`ai/project/refs/final-shape.md`、`module-map.md`、`roadmap.md`
+
+## 稳定约束
+
+-
+
+## 未知项
+
+-
+
+## 备注
+
+这个文件只保存稳定项目身份和长期约定。
+项目方向和最终形态放在 `ai/project/refs/final-shape.md`。
+当前模块结构放在 `ai/project/refs/module-map.md`。
+阶段路线放在 `ai/project/refs/roadmap.md`。
+当前执行上下文放在 `ai/project/runtime.md`。

package/template/zh/ai/project/proposals/final-shape-updates/.gitkeep

@@ -0,0 +1 @@
+

package/template/zh/ai/project/proposals/final-shape-updates/_template.md

@@ -0,0 +1,64 @@
+---
+proposal_id: ""
+status: "proposed"
+created_at: ""
+confirmed_by: ""
+applied_at: ""
+source_ideas: []
+target_files:
+  - ai/project/refs/final-shape.md
+  - ai/project/refs/module-map.md
+  - ai/project/refs/roadmap.md
+---
+
+# 方向修订提案
+
+状态规则：
+
+- `proposed`：AI 已生成，等待人类审查。
+- `accepted`：人类明确确认，可以进入应用任务。
+- `rejected`：人类明确拒绝，保留提案用于追溯。
+- `applied`：已由 `apply_strategy_update` 合并，且填写 `applied_at`。
+
+## 1. 新灵感摘要
+
+-
+
+## 2. 与当前 final-shape 的一致点
+
+-
+
+## 3. 冲突点
+
+-
+
+## 4. 应该吸收的部分
+
+-
+
+## 5. 应该拒绝的部分
+
+-
+
+## 6. 对模块地图的影响
+
+-
+
+## 7. 对路线图的影响
+
+-
+
+## 8. 建议修改 diff
+
+```diff
+
+```
+
+## 9. 风险
+
+-
+
+## 10. 是否推荐合并
+
+- 推荐结论：
+- 原因：

package/template/zh/ai/project/refs/architecture.md

@@ -0,0 +1,23 @@
+# 架构
+
+## 系统概览
+
+只在需要时描述目标项目的系统形态。
+
+## 主要模块
+
+- 模块：
+  - 职责：
+  - 边界：
+
+## 数据流
+
+描述重要数据流。
+
+## API 流程
+
+描述重要 API 流程。
+
+## 部署形态
+
+只有当部署形态影响编码任务时才描述。