@xgent-ai/skills 0.5.0 → 0.6.0

package/README.md

@@ -32,11 +32,11 @@ npx @xgent-ai/skills install
 | `--no-impeccable` | 跳过 impeccable,仍安装 XGENT 的 hooks 与 settings |
 | `--xgent-init` | 直接创建仓根 `AGENTS.md` (已有则跳过),不再询问 |
 | `--no-xgent-init` | 跳过创建 `AGENTS.md`,不再询问 |
-| `--context-goal-guard` | 直接安装 Codex goal 上下文收尾提醒,不再询问;需要 Python 3.9+ |
-| `--no-context-goal-guard` | 跳过 Codex goal guard,不再询问;已有 guard 保留 |
+| `--context-goal-guard` | 显式安装 Codex goal 上下文收尾提醒(默认不安装);需要 Python 3.9+ |
+| `--no-context-goal-guard` | 跳过 Codex goal guard(默认行为);已有 guard 保留 |
 | `--context-goal-guard-threshold=N` | Codex guard 的触发阈值百分比(1–99 整数,默认 65),同时表示安装;重装不给则沿用已装的值 |
-| `--claude-context-goal-guard` | 直接安装 Claude Code goal 上下文收尾提醒,不再询问 |
-| `--no-claude-context-goal-guard` | 跳过 Claude Code goal guard,不再询问;已有 guard 保留 |
+| `--claude-context-goal-guard` | 显式安装 Claude Code goal 上下文收尾提醒(默认不安装) |
+| `--no-claude-context-goal-guard` | 跳过 Claude Code goal guard(默认行为);已有 guard 保留 |
 | `--claude-context-goal-guard-threshold=N` | Claude Code guard 的触发阈值百分比(1–99 整数,默认 70),同时表示安装;重装不给则沿用已装的值 |
 | `--providers=a,b` | 指定 impeccable 装进哪些 harness 目录(如 `--providers=.claude,.cursor`);默认按项目里已有的目录判断,一个都没有时只装 `.claude` |
 | `--force` | 强制重装,并允许覆盖非法 JSON 的 hook 配置(先存 `.bak`);不覆盖已有 `AGENTS.md` |
@@ -47,7 +47,7 @@ npx @xgent-ai/skills install
 
 非交互环境默认跳过,可用 `--xgent-init` 显式创建,或用 `--no-xgent-init` 跳过询问。文件位于仓根,不受 `--providers` 影响。模板没有待填占位,通用编码准则支持不同 coding agent;Portal App 的 onebox 联调与有前端改动时的真实浏览器验收分别按适用条件执行。
 
-`install` 还会询问是否安装 Codex goal 上下文收尾提醒,输入 `y` 或 `yes` 安装,回车和非交互环境默认跳过。此选项不受 `--providers` 或 `--no-impeccable` 影响。确认后先检查含 SQLite 标准库的 Python 3.9+,复制脚本到 `.codex/hooks/context-goal-guard.py`,合并 `.codex/hooks.json` 的同步 `PreToolUse` / `Stop` handler（3 秒超时）,保留其他 hooks 与配置;重复安装只更新 guard,不重复添加。
+`install` 默认不安装 Codex goal 上下文收尾提醒,也不询问;仅在显式传入 `--context-goal-guard` 或 `--context-goal-guard-threshold=N` 时安装。此选项不受 `--providers` 或 `--no-impeccable` 影响。请安装到 Git 仓库根目录;Codex 运行环境需要 git 和 Python 3.9+。显式安装时先检查含 SQLite 标准库的 Python 3.9+,复制脚本到 `.codex/hooks/context-goal-guard.py`,合并 `.codex/hooks.json` 的同步 `PreToolUse` / `Stop` handler（3 秒超时）,运行时从 Git 根目录定位脚本,配置不包含本机项目绝对路径,保留其他 hooks 与配置;重复安装只更新 guard,不重复添加。
 
 安装后会显示用户必须完成的步骤:从目标项目启动 Codex、信任项目 `.codex/` 层,在 `/hooks` 中审阅、信任并启用两个 handler,对**当前 goal** 明确超过阈值(默认 65%)时先保存进度和交接、再暂停的策略。安装输出提供可复制的指令;安装和信任本身不构成暂停授权。恢复 goal 或新开对话后需重新明确策略。当前仅验证 Codex 0.160.0、macOS arm64,完整限制与停用方法见 [启用说明](docs/codex-context-goal-guard.md)。
 
@@ -57,7 +57,7 @@ Codex guard 已接入源码与 npm 打包清单,尚未发布到 npm;发布后可
 node bin/xgent-skills.js install /absolute/path/to/project --context-goal-guard
 ```
 
-`install` 随后询问是否安装 Claude Code goal 上下文收尾提醒,同样输入 `y` 或 `yes` 安装,回车和非交互环境默认跳过,不受 `--providers` 或 `--no-impeccable` 影响。确认后复制脚本到 `.claude/hooks/context-goal-guard.js`,在个人的 `.claude/settings.local.json` 合并 `PostToolBatch` / `Stop` 两个 handler(5 秒超时),保留其他 hooks 与设置;重复安装只更新 guard。guard 只读当前会话记录:本会话 `/goal` 仍 active 且估算上下文严格超过阈值(默认 70%)时提醒 agent 按既有约定更新进度并交接,回合结束时由 Stop hook 结束回合,Claude Code 原生把 goal 置为 Goal paused,再由你在同一项目目录新开对话或 `/clear` 后重新设置 goal。hook 不写任何文件,也不清除或转移 goal。
+`install` 默认不安装 Claude Code goal 上下文收尾提醒,也不询问;仅在显式传入 `--claude-context-goal-guard` 或 `--claude-context-goal-guard-threshold=N` 时安装,不受 `--providers` 或 `--no-impeccable` 影响。显式安装时复制脚本到 `.claude/hooks/context-goal-guard.js`,在个人的 `.claude/settings.local.json` 合并 `PostToolBatch` / `Stop` 两个 handler(5 秒超时),保留其他 hooks 与设置;重复安装只更新 guard。guard 只读当前会话记录:本会话 `/goal` 仍 active 且估算上下文严格超过阈值(默认 70%)时提醒 agent 按既有约定更新进度并交接,回合结束时由 Stop hook 结束回合,Claude Code 原生把 goal 置为 Goal paused,再由你在同一项目目录新开对话或 `/clear` 后重新设置 goal。hook 不写任何文件,也不清除或转移 goal。
 
 安装后需重启会话、信任工作区,并在 `/hooks` 中确认两个 handler 来源为 local settings。当前仅验证 Claude Code 2.1.288 交互式 CLI、macOS arm64 与 Opus 5.5 / Sonnet 5.5 / Haiku 4.5,完整限制、接续与停用方法见 [启用说明](docs/claude-context-goal-guard.md)。从源码安装:`node bin/xgent-skills.js install /absolute/path/to/project --claude-context-goal-guard`。
 
@@ -101,6 +101,7 @@ node scripts/publish-vendor-r2.mjs    # engine 传 R2,下载地址回写 VERSION
 | Skill | 说明 |
 | --- | --- |
 | [prd](skills/prd/SKILL.md) | 撰写或优化 PRD，明确产品目标、FR/NFR、UAT、分期与终验，可按授权录入 SPMS |
+| [crd](skills/crd/SKILL.md) | 以整份 CRD 往返协作：起草需求、文末追加答复、整合对方返回版本并维护 Q&A |
 | [dev-plan](skills/dev-plan/SKILL.md) | 基于需求、仓库规则与代码事实撰写或评审可执行、可跨对话续做的开发计划 |
 | [test-plan](skills/test-plan/SKILL.md) | 从需求与验收标准生成测试用例，覆盖正常、边界、权限和并发场景，可按授权写入 SPMS |
 | [story-points](skills/story-points/SKILL.md) | 按客观因子估算故事点，回写 SPMS 规划点数并复核 Sprint 容量 |
@@ -109,10 +110,70 @@ node scripts/publish-vendor-r2.mjs    # engine 传 R2,下载地址回写 VERSION
 | [review-code](skills/review-code/SKILL.md) | 评审未提交变更、commit 或分支差异，可对照开发计划，输出有证据的代码评审报告 |
 | [review-prd-dev-gaps](skills/review-prd-dev-gaps/SKILL.md) | 核对 PRD 与开发交付，将遗漏、合理变更和待拍板差异分流，交互 Triage 后按需调用 dev-plan 生成 gaps plan |
 | [apply-code-review](skills/apply-code-review/SKILL.md) | 核实代码评审意见，实施合理修复、验证结果并回写实现记录与必要进度 |
-| [apply-doc-review](skills/apply-doc-review/SKILL.md) | 根据 PRD 或开发计划评审报告修订原文，复核关联内容并记录逐条处置结果 |
+| [apply-doc-review](skills/apply-doc-review/SKILL.md) | 可只传评审报告，沿报告的原文档引用定位并修订 PRD 或开发计划，复核并记录逐条处置结果 |
 
 把上述 skill 串成完整交付流水线（想法 → PRD → 分期 → 每期开发与并行测试 → 交付）的方法见 [AI Native SDLC](docs/ai-native-sdlc.md)，含各环节产物路径约定与测试线待补环节的现状核对。
 
+在任意阶段通过 `$agi-mode sdlc <问题>` 或自然语言获取 [SDLC 指引](skills/agi-mode/playbooks/sdlc.md)：解释 PRD、CRD、计划与测试的分工，判断交接条件，选择下一步。手册随 agi-mode 分发；咨询默认只读，涉及项目现状时复用 what-next 核对证据，实际能力以当前项目和已安装技能为准。
+
+这 10 个 SDLC skill 及 `agi-mode` 均在 `SKILL.md` 的 `argument-hint` 中提供参数提示。`<…>` 表示任务所需输入，可沿已有上下文或文档引用定位；`[…]` 是可选补充，`/` 分隔同一位置的备选，不是要求照抄的参数或新增命令解析器。例如：
+
+```text
+$review-prd <PRD路径/链接/内容> [上轮报告] [复审/完整评审] [问题ID/范围] [报告路径] [仅聊天]
+$review-code [未提交/commit/A..B/基准分支] [上轮报告] [复审/完整评审] [问题ID/文件范围] [开发计划] [报告路径] [仅聊天]
+$apply-doc-review <文档评审报告> [原文路径] [上轮报告/处置记录] [修复/仅复核] [问题ID/范围]
+$agi-mode <任务描述> 或 sdlc [流程/阶段/问题] 或 init-sdlc [PRD/计划/范围] 或 what-next [查询/更新] [PRD/计划/范围]
+```
+
+提示的展示取决于客户端：[Claude Code](https://code.claude.com/docs/en/skills#frontmatter-reference) 在 `/skill` 补全中支持 `argument-hint`；Codex 的 `$skill` 参数预览仍有[未关闭的功能请求](https://github.com/openai/codex/issues/31014)，不能仅凭新增字段保证弹出提示。未展示时可直接参考上述用法或各技能的 frontmatter。
+
+4 个 `review-*` 支持“对照上轮报告复审修复效果”：逐项保留来源 ID，区分已解决、仍存在、部分解决、回归、待核实、不再适用和本轮未复核；新增问题单列，默认另存报告。代码旧问题的复核不受本次修复 diff 限制。`review-prd-dev-gaps` 会先核对已有 gaps plan，支持“仅报告”，避免重复规划。
+
+2 个 `apply-*` 支持“继续修复”与“仅复核”：前者处理剩余问题，后者保留目标产物并保存必要处置记录；完全只读则仅聊天交付。重复执行先核对已有证据，无实质变化不改文件或时间；apply 的复核不自动成为新一轮独立 review。
+
+项目状态与下一步能力已合并到 `agi-mode` 的 [what-next 流程](skills/agi-mode/playbooks/what-next.md)，不再单独发布 `what-next` skill。查询默认只读；初始化/更新才保存，既有执行授权继续有效。
+
+```text
+使用 $agi-mode sdlc，解释从需求、CRD 往返到开发、验收和发布的交接。
+使用 $agi-mode init-sdlc 初始化项目状态跟进。
+使用 $agi-mode what-next 看当前项目状态和下一步。
+使用 $agi-mode what-next 更新状态，核对并行计划和最近几轮评审。
+```
+
+`init-sdlc` 按需创建状态目录和索引，核实并登记现有材料；可重复运行，沿用已有台账并补齐缺项，不重置历史。兼容原有 `what-next 初始化` 写法。其他 SDLC skill 在台账启用后维护相关状态，首次启用可直接运行上述初始化入口。
+
+[状态目录约定](skills/agi-mode/references/workspace-layout.md)使用仓根 `.xgent-ai/sdlc/` **只保存开发状态**。PRD、开发计划、评审报告、实施/验收记录和证据继续按用户习惯存放，台账通过链接引用，不改变其路径或复制正文。
+
+```text
+.xgent-ai/
+  index.md                          工作状态总入口
+  sdlc/
+    index.md                        本层导航与当前重点
+    protocol.md                     状态回写和索引维护协议
+    state-model.md                  固定状态、证据门槛和自愈规则
+    event-template.md               状态变化模板
+    status/
+      index.md                      类型入口
+      <prd|plan|review>/
+        index.md                    对象目录
+        <对象UUID>.md               各 PRD、计划、评审的状态
+    events/
+      index.md                      事件类型入口
+      <类型>/
+        index.md                    对象入口
+        <对象UUID>/
+          index.md                  事件清单
+          <事件UUID>.md             单次变化
+```
+
+每个实际创建的状态目录都有 `index.md`，非开发任务的 `tasks/` 及任务子目录也一样；不预建空目录。索引只列本层内容，数量增多后可按领域/年份分片。写入者按[索引维护规范](skills/agi-mode/assets/sdlc/protocol.md#目录索引维护)同步受影响入口，无变化不重写；多机合并保留双方条目并核对实际文件，查询只报告缺项。索引文件不算事件。
+
+状态按对象拆分、历史按需读取。PRD 与计划保持多对多关系，每轮评审有独立状态 ID，原报告文件名不必改变。UUID 事件保留并发记录，冲突待核对，不用机器时间覆盖。
+
+[固定状态模型](skills/agi-mode/assets/sdlc/state-model.md)将文档就绪、计划实施、每轮评审及处置分开：例如 `dev-plan-ready` 表示可开工，`dev-plan-completed` 表示实施范围和规定验证已完成。what-next 会从 `.review.md`、`.codereview.md`、`.code-review.md` 等候选补查漏记评审，并从报告处置节、`.applied.md` 或实施记录核实整改。原计划状态可能滞后，足够的实现/验证证据可纠正 SDLC 状态；原文自述、差异及证据质量仍保留。查询只读重算，更新才保存修复；证据不足用 `unknown`，独立验收线枚举暂为 TBD。
+
+相关撰写、评审、修复技能和计划实施模板仅增加状态回写规则，原产物落盘方式保持原有约定。已有台账可继续使用，不自动迁移或双写。状态协议随仓同步，另一台机器无需安装所有技能也能回写；状态已同步不代表原文和证据已同步。安装 `agi-mode`：`npx skills add XGENT-ai/skills --skill agi-mode`。
+
 ### 开发、调试与质量
 
 | Skill | 说明 |
@@ -131,16 +192,19 @@ node scripts/publish-vendor-r2.mjs    # engine 传 R2,下载地址回写 VERSION
 
 | Skill | 说明 |
 | --- | --- |
-| [agi-mode](skills/agi-mode/SKILL.md) | 以结果契约、主动实验、反证验证和可恢复执行，自主推进复杂任务到可验证交付 |
+| [agi-mode](skills/agi-mode/SKILL.md) | 自主推进复杂任务到可验证交付；含 SDLC 阶段指引、项目状态/what-next 与分类状态记录 |
 | [arena](skills/arena/SKILL.md) | agi-mode 的多候选比较兼容入口，选择基础版本并重新验证合成结果 |
 | [swarm](skills/swarm/SKILL.md) | 为任务选择多 agent 协作机制，设计角色、分工、执行与收尾流程 |
 | [autoresearch](skills/autoresearch/SKILL.md) | agi-mode 的 Hillclimb 兼容入口，在固定协议下搜索并确认改进 |
 | [reflect](skills/reflect/SKILL.md) | agi-mode 的 Reflection 兼容入口，从会话证据提炼并验证改进假设 |
+| [experience-capture](skills/experience-capture/SKILL.md) | 开发中轻量收集踩坑、纠正及自动化线索，供用户随后发起复盘 |
 
 自进化流程集中在 `agi-mode` 内：[Eval](skills/agi-mode/playbooks/eval.md) 建立可信判定，[Hillclimb](skills/agi-mode/playbooks/hillclimb.md) 管理搜索，[Arena](skills/agi-mode/playbooks/arena.md) 提供不同候选，[Reflection](skills/agi-mode/playbooks/reflection.md) 提炼教训。协作与记录约定见 [技能演化](skills/agi-mode/references/skill-evolution.md)。
 
 只需安装 `agi-mode` 即可使用上述流程；保留的 `autoresearch`、`arena`、`reflect` 名称是兼容入口，需要同时安装 `agi-mode`。它们不再独立维护执行规则。
 
+`experience-capture` 可独立安装，默认允许自动选择；本仓 `AGENTS.md` 也提供触发约定。它只在开发的自然间隙，把当前上下文已有的线索用 3–4 行保存到 `.xgent-ai/experience/`，不打断主任务，不额外检索取证或回读完整记录；没有合适间隙则跳过，纯咨询和只读任务不落盘。自动选择不等于可靠的后台事件监听；其他项目可在自己的 `AGENTS.md` 中约定出现这些信号时读取已安装的 skill。任务结束后用 `$agi-mode 复盘` 或 `$agi-mode reflect` 深入挖掘、查找和核对证据；默认给出建议，明确授权沉淀时落实到 know-how、playbook、principle 或自动化工具，并回写处置。
+
 整体方法见 [agi-mode 自进化方法论](docs/agi-mode-evolution-methodology.md)，说明样本沉淀、重放、进化实践和能力评估，以及通用方法与业务实践案例的边界。
 
 ### 文档、表达与图示
@@ -179,6 +243,10 @@ node scripts/publish-vendor-r2.mjs    # engine 传 R2,下载地址回写 VERSION
 
 每个 skill 位于 `skills/<name>/` 目录下,包含一个带 `name` 与 `description` frontmatter 的 `SKILL.md`:
 
+`description` 用于加载前的技能选择,按「触发条件与关键排除条件 → 核心产出」组织。整条建议不超过 200 字符,中文尽量在 100 字符左右;前 100 字符应能独立表达适用边界。这是本仓库的编辑目标,不是所有 coding agent 的统一截断上限。
+
+容易混淆的限制要紧跟触发条件,例如「仅写/评审计划,不用于按计划实施」,不能放在长段落末尾或只留在正文。操作步骤、完整错误码清单、工具细节和重复的双语说明放入正文或 references;精简后检查前缀是否仍表达原意,不要直接机械截字。
+
 ```
 skills/
 └── dev-plan/

package/bin/xgent-skills.js

@@ -570,8 +570,8 @@ function installContextGoalGuard(targetDir, force, threshold) {
     hooks[event] = kept;
   }
   const limit = threshold ?? previous ?? CONTEXT_GOAL_GUARD_DEFAULT_THRESHOLD;
-  // POSIX 单引号同时保护空格、美元符号、反引号及项目路径中的单引号。
-  const command = `python3 '${scriptPath.replace(/'/g, "'\\''")}' --threshold ${limit}`;
+  // 运行时从 Git 根目录定位,避免配置绑定安装机器或会话子目录。
+  const command = `python3 "$(git rev-parse --show-toplevel)/.codex/hooks/context-goal-guard.py" --threshold ${limit}`;
   for (const event of ['PreToolUse', 'Stop']) hooks[event].push({ hooks: [{ type: 'command', command, timeout: 3 }] });
   const script = fs.readFileSync(CONTEXT_GOAL_GUARD_SRC);
   const manifest = Buffer.from(JSON.stringify({ ...existing, hooks }, null, 2) + '\n');
@@ -597,7 +597,8 @@ Codex goal guard 已部署,请完成以下操作后使用:
   4. 先用测试 goal 验证提醒与真实 paused 状态。/goal resume 撤销先前暂停请求,
      需重新明确策略;新开对话也需手动设置新 goal 并重新明确策略。
      暂停失败时在原对话输入 /goal pause;临时停用可在 /hooks 中禁用这两个 handler。
-  提示: Python 3.9+ 必须在 Codex 运行环境可用;没有 active goal 时不会触发。
+  提示: 请安装到 Git 仓库根目录;Codex 运行环境必须能找到 git 和 Python 3.9+。
+        hook 运行时从 Git 根目录定位脚本;没有 active goal 时不会触发。
 `);
 }
 
@@ -689,20 +690,20 @@ function usage() {
   install [dir]   为目标项目(默认当前目录)安装 .claude/hooks 下的全部
                   hook,在 .claude/settings.json 中启用对应配置,并装上
                   vendor 的 impeccable(skills + hooks,以及按需下载的
-                  engine 二进制),并询问是否创建通用的 AGENTS.md
-                  与安装 Codex / Claude Code goal 上下文收尾提醒
+                  engine 二进制),并询问是否创建通用的 AGENTS.md;
+                  Codex / Claude Code goal 上下文收尾提醒默认不安装
   help            显示本帮助
 
 install 选项:
   --no-impeccable       跳过 impeccable,仍安装 XGENT 的 hooks 与 settings
   --xgent-init          创建 AGENTS.md (已有则跳过),不再询问
   --no-xgent-init       跳过 AGENTS.md,不再询问
-  --context-goal-guard  安装 Codex goal guard,不再询问(需要 Python 3.9+)
-  --no-context-goal-guard 跳过 Codex goal guard,不再询问
+  --context-goal-guard  显式安装 Codex goal guard(默认不安装,需要 Python 3.9+)
+  --no-context-goal-guard 跳过 Codex goal guard(默认行为,保留已有 guard)
   --context-goal-guard-threshold=N  Codex guard 的阈值百分比(1–99 整数,默认 ${CONTEXT_GOAL_GUARD_DEFAULT_THRESHOLD};
                         重装时不给则沿用已装的值),同时表示安装
-  --claude-context-goal-guard 安装 Claude Code goal guard,不再询问
-  --no-claude-context-goal-guard 跳过 Claude Code goal guard,不再询问
+  --claude-context-goal-guard 显式安装 Claude Code goal guard(默认不安装)
+  --no-claude-context-goal-guard 跳过 Claude Code goal guard(默认行为,保留已有 guard)
   --claude-context-goal-guard-threshold=N  Claude Code guard 的阈值百分比(1–99 整数,
                         默认 ${CLAUDE_CONTEXT_GOAL_GUARD_DEFAULT_THRESHOLD};重装时不给则沿用已装的值),同时表示安装
   --providers=a,b       指定 impeccable 装进哪些 harness 目录(默认按项目里
@@ -768,28 +769,17 @@ async function install(args) {
   if (options.providers) resolveProviders(options.detected, options.providers);
   const agentsExists = fs.existsSync(path.join(targetDir, 'AGENTS.md'));
   const askAgents = !flags.includes('--xgent-init') && !flags.includes('--no-xgent-init') && !agentsExists;
-  const askGuard = !flags.includes('--context-goal-guard') && !flags.includes('--no-context-goal-guard')
-    && codexThreshold === undefined;
-  const askClaudeGuard = !flags.includes('--claude-context-goal-guard') && !flags.includes('--no-claude-context-goal-guard')
-    && claudeThreshold === undefined;
-  // 各询问共享输入迭代器,避免前一问提前读掉后一问的回答。
-  const rl = process.stdin.isTTY && (askAgents || askGuard || askClaudeGuard)
+  const guard = flags.includes('--context-goal-guard') || codexThreshold !== undefined;
+  const claudeGuard = flags.includes('--claude-context-goal-guard') || claudeThreshold !== undefined;
+  const rl = process.stdin.isTTY && askAgents
     ? readline.createInterface({ input: process.stdin, output: process.stdout }) : null;
   const answers = rl?.[Symbol.asyncIterator]();
   rl?.once('SIGINT', () => { rl.close(); process.exit(130); });
   let agents;
-  let guard;
-  let claudeGuard;
   try {
     agents = flags.includes('--xgent-init') || (askAgents && await confirm(
       '是否同时创建通用的 AGENTS.md (含 Portal 联调与前端验收约定)? [y/N] ',
       '  跳过  AGENTS.md:非交互环境,可加 --xgent-init 创建', answers));
-    guard = flags.includes('--context-goal-guard') || codexThreshold !== undefined || (askGuard && await confirm(
-      `是否安装 Codex goal 上下文收尾提醒 (默认超过 ${CONTEXT_GOAL_GUARD_DEFAULT_THRESHOLD}% 时提醒收尾,需 Python 3.9+ 与 Codex 内手动信任)? [y/N] `,
-      '  跳过  Codex goal guard:非交互环境,可加 --context-goal-guard 安装', answers));
-    claudeGuard = flags.includes('--claude-context-goal-guard') || claudeThreshold !== undefined || (askClaudeGuard && await confirm(
-      `是否安装 Claude Code goal 上下文收尾提醒 (默认超过 ${CLAUDE_CONTEXT_GOAL_GUARD_DEFAULT_THRESHOLD}% 时提醒收尾并在回合结束时暂停 goal,需重启会话并信任工作区)? [y/N] `,
-      '  跳过  Claude Code goal guard:非交互环境,可加 --claude-context-goal-guard 安装', answers));
   } finally {
     rl?.close();
   }

package/docs/claude-context-goal-guard.md

@@ -33,13 +33,12 @@ Claude Code 界面右下角的「NN% context used」按扣除输出预留后的
 ### 使用 install
 
 ```sh
-# 从本仓库源码安装（发布到 npm 后可用 npx @xgent-ai/skills install）
-node bin/xgent-skills.js install /absolute/path/to/project
-# 显式安装，不再询问
+# 默认不安装 guard；从本仓库源码显式安装
+# 发布到 npm 后可用 npx @xgent-ai/skills install --claude-context-goal-guard
 node bin/xgent-skills.js install /absolute/path/to/project --claude-context-goal-guard
 ```
 
-交互安装会在 Codex guard 之后询问是否安装 Claude Code goal 上下文收尾提醒，输入 `y` 或 `yes` 确认；回车和非交互环境默认跳过。`--claude-context-goal-guard` 显式安装，`--no-claude-context-goal-guard` 跳过询问并保留已有 guard，两者不能同时使用。这个选项与 `--providers`、`--no-impeccable`、`--xgent-init` 及 Codex guard 的选项互不影响。
+交互和非交互安装均默认跳过 guard，不再询问。仅在显式传入 `--claude-context-goal-guard` 或 `--claude-context-goal-guard-threshold=N` 时安装；`--no-claude-context-goal-guard` 显式跳过并保留已有 guard，不能与安装参数同时使用。这个选项与 `--providers`、`--no-impeccable`、`--xgent-init` 及 Codex guard 的选项互不影响。
 
 安装器会：
 

package/docs/codex-context-goal-guard.md

@@ -17,16 +17,15 @@
 功能已接入 `install` 源码和 npm 打包清单，尚未发布到 npm。当前从本仓库根目录运行：
 
 ```sh
-node bin/xgent-skills.js install /absolute/path/to/project
-# 显式选择安装，不再询问此选项
+# 默认不安装 guard；需要时显式选择安装
 node bin/xgent-skills.js install /absolute/path/to/project --context-goal-guard
 ```
 
-发布包含此功能的新版本后，可用 `npx @xgent-ai/skills install`。交互安装会询问是否安装 Codex goal 上下文收尾提醒，输入 `y` 或 `yes` 确认；回车或非交互环境默认跳过。`--context-goal-guard` 显式安装，`--no-context-goal-guard` 跳过询问并保留已有 guard；两者不能同时使用。此选择独立于 `--providers`、`--no-impeccable` 和 `--xgent-init`。
+发布包含此功能的新版本后，可用 `npx @xgent-ai/skills install --context-goal-guard`。交互和非交互安装均默认跳过 guard，不再询问。仅在显式传入 `--context-goal-guard` 或 `--context-goal-guard-threshold=N` 时安装；`--no-context-goal-guard` 显式跳过并保留已有 guard，不能与安装参数同时使用。此选择独立于 `--providers`、`--no-impeccable` 和 `--xgent-init`。
 
-安装器检查 `python3` 为 3.9+ 且包含 SQLite 标准库，然后复制脚本到目标项目 `.codex/hooks/context-goal-guard.py`，将两个同步 handler 合并到 `.codex/hooks.json`，使用项目规范绝对路径和 3 秒超时。其他事件、handler、matcher 和顶层字段保留；重复安装更新 guard，不重复添加。非法 JSON 默认报错，`--force` 可先备份为 `.bak` 再覆盖；合法 JSON 的未知结构需手动修复。
+请安装到目标 Git 仓库根目录。安装器检查 `python3` 为 3.9+ 且包含 SQLite 标准库，然后复制脚本到目标项目 `.codex/hooks/context-goal-guard.py`，将两个同步 handler 合并到 `.codex/hooks.json`，使用 `$(git rev-parse --show-toplevel)` 在运行时定位脚本，超时设为 3 秒，配置不包含本机项目绝对路径。其他事件、handler、matcher 和顶层字段保留；重复安装更新 guard，不重复添加，也会替换旧版 guard 的绝对路径命令。非法 JSON 默认报错，`--force` 可先备份为 `.bak` 再覆盖；合法 JSON 的未知结构需手动修复。
 
-Python 缺失或版本不足时，按安装器提示先安装 Python 并运行 `python3 --version` 核对，再重试；也可用 `--no-context-goal-guard` 完成其他安装。Codex 运行环境也必须能解析 `python3`，否则按下方手动配置说明改为解释器绝对路径。
+Python 缺失或版本不足时，按安装器提示先安装 Python 并运行 `python3 --version` 核对，再重试；也可用 `--no-context-goal-guard` 完成其他安装。Codex 运行环境必须能解析 `git` 和 `python3`；后者无法解析时，按下方手动配置说明改为解释器绝对路径。
 
 安装结束会打印下方「信任与生效确认」的操作步骤及可复制的当前 goal 暂停策略。**脚本已部署不等于已生效**：用户仍需在 Codex 内信任项目、审阅并信任启用两个 handler、明确当前 goal 的暂停策略，并用测试 goal 验证真实暂停。安装器不代替用户完成这些步骤。
 
@@ -49,7 +48,7 @@ git clone /absolute/path/to/skills /tmp/skills-guard-source
 git -C /tmp/skills-guard-source checkout <M3记录中的本地验证revision>
 ```
 
-先核对 `codex --version` 和 `python3 --version`。以下路径均替换为实际目录；从项目根目录取得规范绝对路径（例如 `pwd -P`），避免 `/var` 与 `/private/var` 等别名导致信任来源不一致。
+先核对 `codex --version`、`python3 --version` 和 `git --version`。以下复制命令中的目标目录替换为实际 Git 仓库根目录；可在目标项目运行 `git rev-parse --show-toplevel` 确认。
 
 ```sh
 mkdir -p "/absolute/path/to/My Project/.codex/hooks"
@@ -58,13 +57,13 @@ cp "/tmp/skills-guard-source/hooks/codex/context-goal-guard.py" "/absolute/path/
 
 打开目标项目 `.codex/hooks.json`，将 [配置示例](../hooks/codex/hooks.example.json)中的两组 handler **追加**到已有 `PreToolUse` 和 `Stop` 数组；没有文件或事件时才新建对应对象。保留其他事件、handler、matcher 和顶层字段。不要用整个示例覆盖已有 manifest。
 
-将两个 command 中的 `/path/to/My Project` 替换为项目规范绝对路径，保留 JSON 内转义的双引号：
+两个 command 保留以下写法及 JSON 内转义的双引号，无需填入本机目录；运行时按 Git 根目录解析，可从仓库子目录启动，也可随仓库迁移：[官方 Hooks 路径约定](https://learn.chatgpt.com/docs/hooks)。
 
 ```json
-{"type": "command", "command": "python3 \"/absolute/path/to/My Project/.codex/hooks/context-goal-guard.py\" --threshold 65", "timeout": 3}
+{"type": "command", "command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/context-goal-guard.py\" --threshold 65", "timeout": 3}
 ```
 
-若 Codex 环境无法解析 `python3`，将其换为已核对的 Python 3 可执行文件绝对路径，也保留必要引号。普通含空格路径已列入验收；包含 shell 元字符的路径应另行正确引用并验证，不直接粘贴到 command。同步超时为 3 秒。
+若 Codex 环境无法解析 `python3`，将其换为已核对的 Python 3 可执行文件绝对路径，也保留必要引号。Git 根目录的命令替换结果置于双引号内，含空格或 shell 元字符的项目路径仍作为单个参数传入。同步超时为 3 秒。非 Git 目录不适用此写法，需手动配置脚本绝对路径。
 
 ## 信任与生效确认
 
@@ -72,7 +71,7 @@ cp "/tmp/skills-guard-source/hooks/codex/context-goal-guard.py" "/absolute/path/
 2. 打开 `/hooks`，找到来源为本项目 `.codex/hooks.json` 的两个 guard handler；审阅命令、路径、事件与超时，分别信任并启用。
 3. 再次确认两个 handler 的来源、启用和信任状态；确认其他 hooks 仍在列表中。未信任时会被跳过，安静无告警不能证明已生效。
 4. 修改 hook 定义或 command 路径后，重新在 `/hooks` 审阅信任。信任绑定定义 hash，不伪造 hash。替换脚本内容也需自行重新审阅；不要假定定义 hash 会检测脚本内容变化。
-5. 在隔离项目、测试 goal 中验证提示和真实暂停后，再用于日常任务。可从项目子目录启动，command 的绝对路径仍有效。
+5. 在隔离项目、测试 goal 中验证提示和真实暂停后，再用于日常任务。可从仓库子目录启动，command 仍从 Git 根目录定位脚本。
 
 安装、信任和阅读说明都不构成暂停授权。在**当前 goal** 的用户指令里明确，例如：
 
@@ -92,7 +91,7 @@ cp "/tmp/skills-guard-source/hooks/codex/context-goal-guard.py" "/absolute/path/
 
 | 表现 | 检查与处理 |
 | --- | --- |
-| `/hooks` 没有 guard 或显示待审/禁用 | 核对项目层信任、来源、manifest JSON、绝对 command 路径；重新审阅信任并启用 |
+| `/hooks` 没有 guard 或显示待审/禁用 | 核对项目层信任、来源、manifest JSON，以及 `git rev-parse --show-toplevel` 下的脚本路径；重新审阅信任并启用 |
 | “检测不可用” | 核对 Codex 版本、进程实际 `CODEX_HOME`、会话和 `goals_1.sqlite` 的存在与读权限；不手工补库或改状态。格式/schema/锁异常持续时在 `/hooks` 停用 guard |
 | hook 超时/失败提示 | 本次检测失效，工具可能继续。检查 Python、文件读取与存储延迟，在隔离环境重验后再调整 3 秒上限 |
 | 超过阈值但没有提示 | 核对当前根线程是否有 active goal、新统计是否已记录及工具事件覆盖；不能用 UI 百分比直接代替本地统计 |

package/hooks/codex/hooks.example.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 \"/path/to/My Project/.codex/hooks/context-goal-guard.py\" --threshold 65",
+            "command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/context-goal-guard.py\" --threshold 65",
             "timeout": 3
           }
         ]
@@ -16,7 +16,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 \"/path/to/My Project/.codex/hooks/context-goal-guard.py\" --threshold 65",
+            "command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/context-goal-guard.py\" --threshold 65",
             "timeout": 3
           }
         ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xgent-ai/skills",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "XGENT skills 与 Claude Code 辅助工具:通过 npx 为项目安装 hooks、启用 settings,并安装 vendor 的 impeccable",
   "keywords": [
     "claude-code",

package/skills/agi-mode/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: agi-mode
-description: "以结果契约、主动实验、反证验证和可恢复执行推进复杂任务。用于 agi-mode、AGI 模式，或用户要求自主攻克难题、持续推进到可验证交付、失败后换策略继续解决的任务。可用于开发、调查、设计、优化与技能自进化；普通问答与局部小改动无需加载完整流程。"
+argument-hint: "<任务描述> 或 复盘 / reflect [材料/范围/沉淀目标] 或 sdlc [流程/阶段/问题] 或 init-sdlc [PRD/计划/范围] 或 what-next [查询/更新] [PRD/计划/范围]"
+description: "用于 AGI 模式、自主复杂任务、SDLC 流程指引、init-sdlc 初始化或 what-next 状态与续做；咨询查询只读，不自动实施。按阶段指导交接，以实验和证据推进交付。"
 disable-model-invocation: true
 ---
 
@@ -10,6 +11,28 @@ disable-model-invocation: true
 
 AGI 是这个工作模式的名字，不是能力声明。流程强度随不确定性、失败代价和任务跨度增加；简单任务直接完成并验证，不为运行本模式制造流程。
 
+## 快捷指令
+
+`$agi-mode 复盘` 与 `$agi-mode reflect` 等价，直接读取并执行 [Reflection：证据复盘](playbooks/reflection.md)。默认回顾当前会话及已授权的经验记录，提炼踩坑教训和重复操作的自动化机会，给出沉淀建议；已有修改授权时直接落实。可在指令后补充材料路径、复盘范围或沉淀目标。
+
+## SDLC 咨询与阶段指引
+
+用户在任意阶段询问开发流程、产物分工、技能选择、交接条件或如何推进时，读取 [SDLC 指引](playbooks/sdlc.md)。支持 `$agi-mode sdlc [问题]`，也支持直接用自然语言提问，不要求记住子命令。概念咨询直接解释；涉及当前项目判断时由 what-next 核实相关事实，再给有依据的建议。只咨询不启动写作、评审、实施或状态初始化。
+
+明确要求执行的任务仍进入对应流程，已有执行授权继续有效；中途询问 SDLC 时简答后接续原任务。单独安装 agi-mode 即可获得全生命周期指引，专用技能按需读取，缺少时说明等价动作与限制。
+
+## 工作目录与状态入口
+
+需要持久状态时读 [状态目录约定](references/workspace-layout.md)：开发生命周期状态保存在仓根 `.xgent-ai/sdlc/`，按类型和对象分开，链接对应原文及证据。该目录只放状态；PRD、开发计划、评审报告、实施记录等原产物继续按用户习惯和项目约定保存，不因启用模式改变位置或复制正文。
+
+`.xgent-ai/` 下每个实际创建的目录都有 `index.md`；写入者按目录约定同步本层索引及入口变化的祖先，查询只报告缺失或陈旧，不自动修复。
+
+询问“当前项目状态 / 下一步 / what-next”或维护项目跟进表时，直接走 [项目状态与下一步](playbooks/what-next.md)，只加载该流程及需要的目录/协议参考，不进入后面的实施闭环。默认查询只读；初始化/更新才保存按对象拆分的状态页。正在执行的已授权任务收到状态询问，回答后继续原任务，不重新请求开工。
+
+`$agi-mode init-sdlc [PRD/计划/范围]` 是显式初始化入口，走同一流程的写入模式：按需建立台账并登记已核实的现有材料。重复调用沿用已有台账、补齐缺项，不重置历史。兼容 `what-next 初始化`；日常查询用 `what-next`，保存最新状态用 `what-next 更新`。
+
+what-next 用固定状态码和证据质量表达判断，主动发现关联评审与处置，核对原计划状态是否滞后；自愈按 [状态模型](assets/sdlc/state-model.md) 修复跟进，不从文件名推导评审通过或开发完成。
+
 ## Principles
 
 原则负责决定取舍，playbook 负责执行顺序。遇到下表的触发条件时读取对应原则全文，再作相关决定；playbook 内的原则入口是提示，不要求每次全部加载。原则文件是本 skill 的内部资源，不作为独立全局 skill 注册。
@@ -61,6 +84,8 @@ AGI 是这个工作模式的名字，不是能力声明。流程强度随不确
 
 | 当前任务 | Playbook | 完成标志 |
 | --- | --- | --- |
+| SDLC 知识、PRD/CRD/计划/测试分工、阶段交接、技能选择或流程建议 | [SDLC 指引](playbooks/sdlc.md) | 有依据的阶段解释、下一步输入/动作/判据；咨询保持只读 |
+| init-sdlc 初始化、项目状态、what-next、多计划进度、跨机盘点或维护跟进表 | [项目状态与下一步](playbooks/what-next.md) | 有来源的分类状态、冲突/同步边界与具体下一步；仅写入模式维护台账 |
 | 解释机制、只读调查、比较方案 | [调查与诊断](playbooks/investigation.md) | 有出处的答案、因果证据或明确的未知 |
 | 活进程异常、CPU / heap / trace / spindump 取证 | [运行时与离线取证](playbooks/forensics.md) | 从原始信号到代码位置的可追溯诊断 |
 | 设计方案、实施计划、用原型决定方向 | [设计与原型](playbooks/design-prototype.md) | 可实施的决策或已验证的原型结论 |
@@ -70,7 +95,7 @@ AGI 是这个工作模式的名字，不是能力声明。流程强度随不确
 | 比较 skill、prompt、模型、工具配置或执行流程 | [Eval：可信评测](playbooks/eval.md) | 隔离、可比的真实结果支持采用、拒绝或证据不足 |
 | 持续改进代码、指标或 agent 行为，autoresearch | [Hillclimb：持续进化](playbooks/hillclimb.md) | 实验记录完整，最佳候选经最终确认，目标状态明确 |
 | 比较多种结构并合成产物，arena | [Arena：多候选比较](playbooks/arena.md) | 匿名比较有依据，合成版本重新验证 |
-| 从会话提炼教训，reflect | [Reflection：证据复盘](playbooks/reflection.md) | 有出处的改进假设，按授权落实并标明验证等级 |
+| 从会话或经验记录提炼教训，复盘 / reflect | [Reflection：证据复盘](playbooks/reflection.md) | 有出处的改进假设，按授权落实并标明验证等级 |
 | 行为不变的重构、接口或数据迁移 | [重构与迁移](playbooks/migration-refactoring.md) | 行为约束成立，调用方和数据状态完成核对 |
 | 页面、交互、视觉还原或跨端适配 | [界面交付](playbooks/ui-delivery.md) | 实际界面与交互证据符合目标 |
 | 审查代码、方案或外部审查意见 | [评审与处置](playbooks/review.md) | 有证据的发现及处置，不把意见数量当成果 |

package/skills/agi-mode/assets/directory-index.md

@@ -0,0 +1,18 @@
+# <目录名称> 索引
+
+用途：<本目录保存什么状态；原文和证据仍在用户约定位置。>
+覆盖：本目录直接文件与子目录；不含本索引自身。<分片时列明范围与全部分片入口。>
+
+| 文件 / 子目录 | 用途 / 对象 ID | 入口 |
+| --- | --- | --- |
+
+<!-- 按相对路径稳定排序；文件链到自身，子目录链到其 index.md。事件叶目录一事件一行，列 event_id 与 facet/scope，不复制结论。只填真实条目，空目录写“暂无登记”。 -->
+
+## 维护约定
+
+- 改变本目录内容的执行者负责维护：先保存状态文件，再更新本索引；创建子目录时同时创建其索引。父索引仅在入口增删、移动或说明变化时更新，无变化不重写或刷新时间。
+- 索引只作导航；状态内容更新不必改索引。归档须有依据并保留入口，移动保持对象 ID；缺失目标先标待核对，不因当前机器缺文件删除记录或历史。索引维护不授权搬迁、删除原文。
+- 合并时按 ID 与路径核对本地实际文件，保留双方新增项及未解决冲突，不按时间覆盖；修补漏项、重复和断链，保留人工说明。查询只报告问题，维护模式才修复。
+- 新增归档/分片目录同样有 index.md；大索引用 index-<分片名>.md 分片，首页列全范围，每项恰属一个分片。index.md 与 index-*.md 不作为事件读取或计数。
+
+<!-- SDLC 目录另链接仓内 protocol.md 的“目录索引维护”一节，按本文件位置计算相对路径；不保留安装机器路径。非开发任务保留上述自包含规则即可。 -->

package/skills/agi-mode/assets/sdlc/event.md

@@ -0,0 +1,33 @@
+---
+schema_version: 3
+event_id: "<新 UUID，与文件名相同>"
+object_id: "<沿用对象 UUID；新对象才生成>"
+kind: "<prd / plan / review>"
+title: "<可读标题>"
+artifact: "<仓根相对路径或稳定 URL>"
+facet: "<document / readiness / implementation / review / disposition 等>"
+scope: "<稳定范围，如 plan、M2、F-01>"
+state: "<state-model.md 对应 kind/facet 的固定状态码，不能确认用 unknown>"
+source_state: null
+evidence_status: "<confirmed / provisional / stale / conflict / unknown>"
+observed_at: "<ISO 8601，带时区>"
+predecessors: []
+baseline:
+  head: "<完整 SHA 或 unknown>"
+  branch: "<分支、detached 或 unknown>"
+  worktree: "<clean / dirty / unknown>"
+sources:
+  - path: "<仓根相对路径或稳定 URL>"
+    revision: "<Git 版本、sha256:内容指纹或 unknown>"
+    anchor: "<稳定章节/检查/问题定位>"
+relations: []
+---
+
+# <本次事实摘要>
+
+- 事实与证据：<本次读到/验证了什么；评审写种类、所审对象版本和范围，区别于观察 checkout>
+- 校准依据：<规范状态与来源自述的差异、证据覆盖与原文滞后；一致时简述依据>
+- 未完项与限制：<缺证、未同步、待决；没有则写无，不填猜测>
+- 下一步及解除条件：<动作 + 可观察完成判据；无后续则说明>
+
+<!-- 创建事件时替换占位并移除此注释。source_state 有原文状态则保留其文字，否则 null；可选 candidate_state 只能写模型中的对应枚举。kind=review 时补 review_type: prd / dev-plan / code / other。sources.path、artifact 均按仓根解析；正文 Markdown 链接按本文件目录解析。relations 如 {type: covers, target: 对象UUID, scope: FR-1}；评审对所审对象用 reviews，复审对前轮用 rechecks。 -->

package/skills/agi-mode/assets/sdlc/index.md

@@ -0,0 +1,17 @@
+# SDLC 工作导航
+
+本页列直接文件、子目录入口与当前重点，不自列。本目录只保存按对象拆分的状态；PRD、计划、报告及证据保留在用户原有位置，通过来源链接读取。
+
+- 回写规则：[协议](protocol.md)
+- 状态定义与自愈：[固定状态模型](state-model.md)
+- 记录格式：[事件模板](event-template.md)
+- 对象状态：[类型导航](status/index.md)
+- 状态历史：[事件导航](events/index.md)
+
+由改变本目录内容的执行者按[目录索引维护规则](protocol.md#目录索引维护)同步入口；下级状态变化不逐级重写本页。分类或对象快捷链接可按需放在当前重点，不代替完整目录入口。
+
+## 当前重点
+
+<只链接当前需要跟进的对象状态页，说明首选下一步与全局阻塞；完整活动项见分类索引。没有可确认活动项时如实说明。>
+
+<!-- 初始化时只链接实际存在的索引；未创建的类别写“暂无登记”，不要留断链。 -->

package/skills/agi-mode/assets/sdlc/object-status.md

@@ -0,0 +1,25 @@
+# <对象标题> · 状态
+
+- 对象 ID / 类型：<完整 UUID / prd、plan、review>
+- 状态模型：<协议 v3 / state-model v1；评审对象另写 review_type>
+- 来源：<实际文档/报告链接，版本>
+- 核查时间：<带时区时间>
+- 可见范围：<分支/HEAD/dirty、所核实范围及同步限制>
+
+## 当前事实与下一步
+
+| 维度 / 范围 | 固定状态码 | 来源自述 | 证据质量 | 证据 / 对应事件 | 差异、缺证或阻塞 | 下一步及完成判据 |
+| --- | --- | --- | --- | --- | --- | --- |
+
+<!-- 状态码按仓内 state-model.md；无法确认用 unknown，候选另列不冒充当前事实。原计划状态滞后时保留自述及纠正依据；开发完成不代表验收或发布。 -->
+
+## 关联
+
+| 关系 | 目标对象 / 状态页 | 需求、里程碑或问题范围 |
+| --- | --- | --- |
+
+<!-- PRD 链到承接计划；计划链到 PRD、实施记录及各轮评审状态页；评审链到所审对象、前轮与整改证据。复审不覆盖原轮结论。关联不明就写待关联，不靠同名猜测。 -->
+
+## 已纳入事件
+
+<!-- 只列本对象全部已纳入事件 UUID 及链接，按 ID 排序；包括历史事件，排序不代表执行顺序。可折叠；其他对象事件在各自状态页维护。 -->