ai-project-manage-cli 2.0.10 → 2.0.12

package/templates/skills/apm-apply-change/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: apm-apply-change
+description: 在 .apm/workitems/<requirementId>/ 按 tasks.md 逐项实现、勾选；一项任务一个 commit。遇事实性阻塞（如规划与代码严重不符）须停止执行，仅陈述事实与需用户提供的材料，不替用户决策或列方案。/opsx:apply 同此技能。
+---
+
+# APM 工作项：按任务实现
+
+根据工作项目录下的 **`tasks.md`** 驱动实现：**读规划 → 做代码 → 对账元数据 → 勾选 → 单独 commit**，直至全部完成或遇硬阻塞；上下文以 **`.apm/workitems/<requirementId>/`** 内文件为准。
+
+---
+
+## 输入
+
+| 字段 | 规则 |
+| --- | --- |
+| **`requirementId`** | **推荐显式提供**（与 `.apm/workitems/<requirementId>/` 目录名一致）。 |
+
+若本轮未提供 `requirementId`：
+
+1. 若对话中已能**唯一**确定工作项目录名，则用之。
+2. 否则查看 **`.apm/workitems/`** 下子目录：若**仅有一个**，自动采用；若**多个**，**按目录名字典序取第一个**作为本次工作项，并在回复中列出当时可见的候选名，声明 **使用工作项：`<requirementId>`** 及如何覆盖（例如下次显式给出 id）。**不要**调用 AskUserQuestion，**不要**停下来让用户当场选择。
+
+**不要**为澄清需求而反问用户。若执行中发现**无法在无决策前提下继续**的事实性问题（见上文 **「停止执行」**），**不要**用推断顶过去。
+
+---
+
+## 停止执行（优先于继续推进）
+
+若在实施过程中**发现**任一情况，**立即停止**本技能所驱动的后续实现与勾选（不再继续下一项任务），仅在会话中输出：
+
+1. **客观事实**：已读到的文件/路径、与代码或任务条目的**具体矛盾点**（可摘引，避免主观评价）。
+2. **当前进度**：处理到 `tasks.md` 的哪一条、仓库是否已有未提交改动（若有，说明范围）。
+3. **需要用户提供什么**：为继续推进所**缺的信息或决策**（例如：以何者为准、是否接受某类改动、需确认的业务口径）。用**清单**列出，**一句一项**。
+
+**禁止**：给出「建议你先改 A / 再改 B」「可选方案 1/2/3」「宜采用…」等**替用户决策**或**行动建议**；不指导用户如何改文档、不预设优先级。
+
+**允许**：描述「若不补充某信息则无法继续」的**逻辑关系**（仍不展开成方案）。
+
+---
+
+## 工作项路径与必备文件
+
+- **根路径**：**`.apm/workitems/<requirementId>/`**
+- **必备**：**`tasks.md`**（含 `- [ ]` / `- [x]` 待办）。若不存在或无可执行条目：**阻塞**，说明须先完成 **apm-propose**（或手工补齐 `tasks.md`）。
+- **强烈建议读**：**`prd.md`**（范围与验收）；实现时按需 **Read** **`proposal.md`**、**`design.md`**、**`specs/`**（与 **`tasks-instruction.md`** 中每条任务的元数据一致）。
+- **进度**：仅由 **`tasks.md`** 中复选框统计「已完成 / 总数」。
+
+### 单会话读取（可选减负）
+
+同一轮连续执行多项任务时：**`prd.md` / `design.md` / 各 spec** 若已在会话内读过且无疑虑，不必每个任务重复全文 Read；以**当前任务行**及元数据指向的 spec/设计段落为准，必要时对文件 **Read（偏移）** 或再读全文。
+
+---
+
+## Steps
+
+### 1. 锚定工作项
+
+确定 **`requirementId`** 与工作项根路径；声明 **使用工作项：`<requirementId>`**（若依上节规则自动选定，须说明如何覆盖）。
+
+### 2. 读取 `tasks.md` 并判断状态
+
+- **Read** **`.apm/workitems/<requirementId>/tasks.md`**。
+- 若文件缺失、为空、或无任何 `- [ ]`：**停止**，提示先具备可执行 `tasks`（规划阶段）。
+- 若全部已为 `- [x]`：**可**直接汇报「已全部完成」（仅作事实陈述，不建议是否提交或发 MR）。
+
+### 3. 读取实现上下文（按任务需要）
+
+开始**第一个**未勾选任务前，至少 **Read**：
+
+- **`prd.md`**（若存在；与验收相关条款）
+- 与任务相关的 **`design.md`** 片段、**`specs/`** 下对应文件（见任务条目的 **需求编号** / 描述）
+
+不要求每次任务都重读全部规划文件；以 **`tasks.md` 当前项** + **缺口再 Read** 为准。
+
+### 4. 展示当前进度
+
+在对话中简要展示：
+
+- **工作项**：`requirementId`
+- **进度**：「N/M 个任务已完成」（由 `tasks.md` 勾选统计）
+- **当前将处理**：下一条 `- [ ]` 的摘要（含组号/编号如 `2.1`）
+
+### 5. 实现任务（循环直至完成或阻塞）
+
+对每一条 **未勾选** 任务（建议按 `tasks.md` 自上而下顺序）：
+
+1. **说明**正在处理哪一项（编号 + 简述）。
+2. **实现**所需代码/配置/迁移等；改动保持**最小**、与该项描述一致。
+3. **标记完成前**在回复或备注中收集依据（与 **`tasks-instruction.md`** 子列表字段对齐即可）：
+   - **需求编号**：本实现对应 specs / tasks 中的哪条需求或场景。
+   - **预期改动路径** 与 **实际改动文件**：若有合理偏差，简要说明原因。
+   - **验证用例编号**（若任务中有）。
+   - **验证结果** / **完成标准**：如何确认本项已达成（可简短）。
+4. 仅在依据已齐、且自洽通过后，将 **`tasks.md`** 中对应行 **`- [ ]` 改为 `- [x]`**。
+5. **Git**：本待办对应的**实现 + 勾选**等改动，**单独 `git commit` 一次**（**一项待办 = 一个 commit**；勿把多项待办混在同一 commit）。提交信息建议包含 `requirementId` 与任务编号或简述。
+
+**何时停止（不继续下一项）**——与上文 **「停止执行」** 一致：
+
+- **`design` / `specs` / `tasks` 与当前代码或彼此严重不一致**，以致无法按任务字面含义在**不臆造**的前提下完成 → **按「停止执行」输出**（事实 + 需用户提供的材料），**不**建议先改哪份文档、不改哪些。
+- 命令失败、环境错误、权限等**硬阻塞** → 说明原因、失败点、已执行步骤；**不**给排障步骤或替代命令建议（除非任务本身要求执行某命令且该命令已写在任务/文档中）。
+- 用户中断。
+
+**何时仍可继续**（仅当满足）：任务表述略含糊，但可在 **prd / design / specs / tasks** 已有文字内**自洽**完成；若有**假设**，在回复中写清**假设**（仍不反问）。一旦假设会触及「以谁为准」的**产品/架构决策**，转 **「停止执行」**。
+
+### 6. 完成或暂停时展示状态
+
+- **本会话**完成了哪些任务（可列勾选项摘要）。
+- **总体进度**：「N/M 个任务已完成」。
+- 若**全部完成**：仅陈述事实（进度与勾选状态），**不**建议后续流程（MR/发布/归档等）。
+- 若**暂停**：按 **「停止执行」** 或硬阻塞格式输出，**无**「可选后续」或方案建议。
+
+---
+
+## 实现过程中的输出（示例）
+
+```
+## 正在实施：<requirementId>
+
+处理任务 3/7：2.1 实现导出接口
+[...实现过程...]
+✓ 任务完成 · commit <short-sha> <subject>
+
+处理任务 4/7：2.2 …
+```
+
+---
+
+## 全部完成时的输出（示例）
+
+```
+## 实现完成
+
+**工作项：** <requirementId>
+**进度：** 7/7 个任务已完成 ✓
+
+### 本会话已完成
+- [x] …
+- [x] …
+
+（每项待办均已对应独立 commit。）
+```
+
+---
+
+## 暂停时的输出（示例）
+
+```
+## 实现已暂停
+
+**工作项：** <requirementId>
+**进度：** 4/7 个任务已完成
+
+### 事实与原因
+<客观描述：文件/行/与任务或代码的矛盾点>
+
+### 需要用户提供（或决策）
+- …
+- …
+```
+
+（无方案列表、无「建议」；用户补充信息后可再次运行本技能。）
+
+---
+
+## 约束
+
+- 持续执行待办直至完成、**停止执行**或硬阻塞。
+- 开始前须已能对照 **`tasks.md`** 与 **`prd.md`**（及任务所需的 design/spec）；**不要**在未读清当前任务依赖时盲改。
+- 任务表述有歧义时，仅在**无需用户决策**的前提下依据 **specs / design / prd** 推断；一旦涉及**以谁为准**或**严重不一致**，**停止执行**（见上文）。
+- **不**因「发现规划与代码不符」而**主动建议**修改 `design.md` / `specs/` / `tasks.md`；**停止**并说明事实与需用户提供的材料即可。
+- 代码改动保持最小、与**当前任务**范围一致。
+- 未完成需求/验证对账前，**不要**将任务勾为完成。
+- 验证失败或依据不足时，保持 **`- [ ]`**，并明确写出缺口。
+- 若任务元数据缺失（需求编号、预期改动路径、完成标准等），在可能范围内于实现前**补全或按 tasks 模板推断**，并在说明中注明。
+- 每完成一项任务并记录依据后，**立即**更新勾选并**随即**单独 `git commit`。
+- 遇硬阻塞时暂停并说明原因（**不**给出替代命令或排查建议，除非任务/文档已写明）；
+- 需求不清且无法自洽推断时，**停止执行**并列出需用户提供的材料；**不反问用户**。
+
+---
+
+## 与规划流程的衔接
+
+- **`tasks.md`** 须由 **apm-propose**（或等价流程）生成并符合 **`tasks-instruction.md`** 格式（`- [ ]`、元数据子列表等），否则本技能无法可靠追踪。
+- 若执行中发现 **`design` / `specs` 与代码严重不一致**：**停止执行**，按上文输出事实与**需用户提供**的决策/信息；**不**建议先改哪类工件、不代用户排优先级。
+
+---
+
+## 流动工作流
+
+- **可分段调用**：可在部分任务完成后结束会话，下次同一工作项继续。
+- **规划修订**：由用户在**流程外**修订 `design.md` / `specs/` / `tasks.md` 后，再触发本技能；本技能执行中**不因发现不符**而主动改规划文件或提出修改方案。

package/templates/skills/apm-auto-dev/SKILL.md

@@ -1,30 +1,29 @@
 ---
 name: apm-auto-dev
-description: 按分支 ID、分支名、基准分支、需求 ID、版本序号全自动拉分支、更新分支状态、落盘 PRD；步骤 3 后主 Agent 据 PRD 二选一 Quick（直接实现）或 Spec（openspec-propose + openspec-apply-change）；再生成 MR 评审说明、推送、部署与分支状态更新。在用户要求全自动开发、APM 自动交付、或给出上述参数时使用。
+description: 从创建分支到需求的开发的完整流程，当用户明确声明使用本技能时触发。
 ---
 
-# APM 全自动开发（编排技能）
+# APM 全自动开发
 
-**角色**：主 Agent 只做参数传递、**串行**启动子 Agent、校验上一步产物、失败则停止并汇总（**例外见步骤 8/9**）；**禁止**在同一对话里自己执行完整 propose+apply 长流程而不用子 Agent。流程结束须输出**步骤结果汇总表**（见文末「主 Agent 汇总输出」）。
+**角色**：主 Agent 只做参数传递、**串行**启动子 Agent、校验上一步产物、失败则停止并汇总（**例外见步骤 8/9**）；**禁止**在同一对话里自己执行完整 **apm-propose + apm-apply-change** 长流程而不用子 Agent。流程结束须输出**步骤结果汇总表**（见文末「主 Agent 汇总输出」）。
 
-**输入（必填）**
+**输入（必填）** requirementId:需求 id
 
-| 字段 | 说明 |
-|------|------|
-| 分支名称 | 远程已存在、本地可无；检出目标 |
-| 基准分支 | 作为 MR 对比基线（通常由服务端 prompt 直接给出） |
-| 需求文档 ID | `--requirement-id` |
-| 需求版本序号 | `--version-seq`（与界面 v1/v2 一致） |
-| 分支记录 ID | `--branch-id`，用于更新需求分支状态 |
+## 触发条件
 
----
+用户**明确声明**使用本技能（例如在对话中 @ 本 SKILL）
+
+## 输入
+
+- **`requirementId`(必须)**：需求 ID。
+- **`baseBranchName`(可选)**: 基线分支名称，如果用户没给，那么不是 master 就是 main
 
 ## 子 Agent 强制隔离
 
-- 步骤 **1～3** 各对应一次 **Task 子 Agent**；**步骤 3 之后**主 Agent 判定 **Quick / Spec**（二选一，见下节），再启动 **仅一条**开发路径：
-  - **Quick**：一步子 Agent 完成「步骤 4（Quick）」后，直接进入步骤 6。
-  - **Spec**：步骤 **4（Spec）— openspec-propose** 与 **步骤 5（Spec）— openspec-apply-change** 各一次子 Agent，再进入步骤 6。
-- 步骤 **6～9** 各对应一次子 Agent，**严格串行**：仅当上一步子 Agent **明确结束**且主 Agent **已校验产物**后，再启动下一步（**步骤 8 发布失败时仍须启动步骤 9**，见步骤 8 说明）。
+- 步骤 **1 ～ 2** 各对应一次 **Task 子 Agent**；**步骤 2 之后**主 Agent 判定 **Quick / Spec**（二选一，见下节），再启动 **仅一条**开发路径：
+  - **Quick**：一步子 Agent 完成「步骤 3（Quick）」后，直接进入步骤 6（生成修改摘要）。
+  - **Spec**：**步骤 4（Spec）— apm-propose** 与 **步骤 5（Spec）— apm-apply-change**（产物均在 `.apm/workitems/<requirementId>/`）各一次子 Agent，再进入步骤 6（生成修改摘要）。
+- 步骤 **6 ～ 9** 各对应一次子 Agent，**严格串行**：仅当上一步子 Agent **明确结束**且主 Agent **已校验产物**后，再启动下一步（**步骤 8 发布失败时仍须启动步骤 9**，见步骤 8 说明）。
 - **禁止**并行启动多个子 Agent 执行本流程中的步骤；**禁止**同一次流程中既走 Quick 又走 Spec。
 - 子 Agent 需执行完毕：读 SKILL、跑命令、写文件、回报结构化结果（路径、变更名、成功/失败）。
 
@@ -46,63 +45,38 @@ description: 按分支 ID、分支名、基准分支、需求 ID、版本序号
 
 ---
 
-## 步骤 2 — 子 Agent：拉取需求正文并落盘
-
-1. 执行：
-
-```bash
-apm requirement version content --requirement-id <ID> --version-seq <SEQ>
-```
-
-2. 解析 **stdout** JSON：取版本对象中的 **`content`** 字段（字符串）作为 PRD 正文。
-3. 由正文推导目录名 `<name>`（**kebab-case**）：优先取第一行 Markdown 标题（去 `#`）、否则取首行摘要；小写、空格与下划线改为 `-`，移除非 URL/路径安全字符；过长则截断至约 48 字符。若 `.apm/workitems/<name>/prd.md` **已存在**，才加后缀 `-2`、`-3`… 直至找到一个 `prd.md` 不存在的目录；若仅目录存在但 `prd.md` 不存在，则直接使用该目录。
-4. 创建目录并**覆盖写入**：
-
-`.apm/workitems/<name>/prd.md`
-
-5. 将最终采用的 `<name>` 回报主 Agent（后续步骤共用同一目录）。
-
-**完成判定**：`prd.md` 存在且非空；`<name>` 已确定。
-
----
-
-## 步骤 3 — 子 Agent：更新需求分支状态为开发中
-
-1. 在仓库根目录或任意目录执行（只依赖 apm 配置，不依赖当前 cwd）：确保已通过 `apm login`，并已配置 `base-url`。
-2. 调用 CLI 更新分支状态为“开发中”，命令形如：
+## 步骤 2 — 子 Agent：开发前准备
 
-```bash
-apm requirement branch set-status --branch-id <BRANCH_ID> --status IN_DEVELOPMENT
-```
-
-3. 子 Agent 需检查命令退出码，非 0 时读取 stderr，返回失败原因并终止全流程（不要静默继续后续步骤）。
+1. 获取需求内容：执行 `apm get requirement <requirementId>`
+2. 基于分支命名规范创建一个分支，并切换到这个分支，基线分支为 <baseBranchName>
+3. 信息回传到远程：执行 `apm set branchName <branchName>`
 
 **完成判定**：命令成功返回（退出码 0），且无错误输出。
 
 ---
 
-## 开发模式判定（主 Agent，紧接步骤 3 之后）
+## 开发模式判定（主 Agent，紧接步骤 2 之后）
 
-在启动任何「步骤 4」子 Agent 之前，主 Agent 根据 **`.apm/workitems/<name>/prd.md`**（或步骤 2 回报摘要）判断本次采用 **Quick** 还是 **Spec**，**二者必选其一、互斥**：
+在启动任何「步骤 3（Quick）/ 步骤 4（Spec）」子 Agent 之前，主 Agent 根据 **`.apm/workitems/<requirementId>/prd.md`**（或步骤 2 回报摘要）判断本次采用 **Quick** 还是 **Spec**，**二者必选其一、互斥**：
 
-| 倾向 Quick | 倾向 Spec |
-|------------|-----------|
-| 逻辑面少、改动范围小、对现有行为影响面低 | 涉及多模块、协议/数据模型/权限等契约变化 |
-| 多为文案、样式、单点配置、小函数修补 | 需要可追溯规格与任务拆解、跨文件协调 |
-| 回归路径清晰、不易引入隐蔽 BUG | 歧义多或易出边界 BUG，需 propose/tasks 约束 |
+| 倾向 Quick                               | 倾向 Spec                                   |
+| ---------------------------------------- | ------------------------------------------- |
+| 逻辑面少、改动范围小、对现有行为影响面低 | 涉及多模块、协议/数据模型/权限等契约变化    |
+| 多为文案、样式、单点配置、小函数修补     | 需要可追溯规格与任务拆解、跨文件协调        |
+| 回归路径清晰、不易引入隐蔽 BUG           | 歧义多或易出边界 BUG，需 propose/tasks 约束 |
 
 **规则**：若同时满足表中「倾向 Quick」的典型特征且不满足必须走 Spec 的红线，选 **Quick**；否则选 **Spec**。判定结果须写入最终汇总表（含一句简要理由）。
 
-- 选 **Quick** → 只执行 **步骤 4（Quick）**，**跳过** openspec-propose 与 openspec-apply-change（原步骤 4/5 Spec）。
-- 选 **Spec** → **跳过**步骤 4（Quick），依次执行 **步骤 4（Spec）**、**步骤 5（Spec）**。
+- 选 **Quick** → 只执行 **步骤 3（Quick）**，**跳过** apm-propose 与 apm-apply-change（步骤 4/5 Spec）。
+- 选 **Spec** → **跳过**步骤 3（Quick），依次执行 **步骤 4（Spec）**、**步骤 5（Spec）**。
 
 ---
 
-## 步骤 4（Quick）— 子 Agent：直接实现（与 Spec 二选一）
+## 步骤 3（Quick）— 子 Agent：直接实现（与 Spec 二选一）
 
 **前置**：开发模式判定为 **Quick**；本步与「步骤 4（Spec）+ 步骤 5（Spec）」**不得**同跑。
 
-1. 读取 **`.apm/workitems/<name>/prd.md` 全文**，按 PRD 在仓库内**直接完成实现**（改代码、配置、测试等以项目惯例为准），**不**创建 `openspec/changes/` 下的变更目录，**不**调用 openspec-propose / openspec-apply-change。
+1. 读取 **`.apm/workitems/<requirementId>/prd.md` 全文**，按 PRD 在仓库内**直接完成实现**（改代码、配置、测试等以项目惯例为准），**不**写入本流程 Spec 模式下的 `proposal.md` / `design.md` / `tasks.md` 等规划工件（除非为修复所必需），**不**调用 apm-propose / apm-apply-change。
 2. 改动应可审阅：子 Agent 回报主要修改文件路径列表、自测结论（若有）；**不要**向用户追问需求细节，歧义按合理假设处理。
 3. 主 Agent 校验：工作区存在与 PRD 对应的实质变更（或子 Agent 明确说明无需改文件的合法情况）。
 
@@ -110,76 +84,50 @@ apm requirement branch set-status --branch-id <BRANCH_ID> --status IN_DEVELOPMEN
 
 ---
 
-## 步骤 4（Spec）— 子 Agent：openspec-propose（与 Quick 二选一）
+## 步骤 4（Spec）— 子 Agent：apm-propose（与 Quick 二选一）
 
 **前置**：开发模式判定为 **Spec**；若已走 Quick，**不得**执行本节。
 
-1. 读取并遵循项目内技能：`.cursor/skills/openspec-propose/SKILL.md`。
-2. **输入**：仓库内文件路径 **`.apm/workitems/<name>/prd.md`**（子 Agent 应用 Read 读全文）；变更名可据 PRD 归纳 kebab-case；**不要**向用户追问。
-3. **输出**：子 Agent 必须回报 **`openspec/changes/<change-name>/` 的绝对或仓库相对路径** 以及 **`<change-name>`**（若与 `<name>` 不同，以 openspec 目录名为准）。
+1. 读取并遵循：`.cursor/skills/apm-propose/SKILL.md`。
+2. **输入（必须）**：**`requirementId`**；**`.apm/workitems/<requirementId>/prd.md`** 须 Read 全文。**不要**追问。
+3. **输出**：回报 **`.apm/workitems/<requirementId>/`**，并确认已写入 `proposal.md`、`design.md`、`tasks.md` 与 `specs/`（按 SKILL）。
 
-**完成判定**：`openspec status --change "<change-name>"` 无「缺工件」类阻塞；`proposal.md`、`tasks.md` 等应已按该 SKILL 就绪。
+**完成判定**：上述文件存在且非空；`prd.md` 要点已反映在各工件中。
 
 ---
 
-## 步骤 5（Spec）— 子 Agent：openspec-apply-change
+## 步骤 5（Spec）— 子 Agent：apm-apply-change
 
 **前置**：仅 **Spec** 模式；步骤 4（Spec）已成功。
 
-1. 读取并遵循：`.cursor/skills/openspec-apply-change/SKILL.md`。
-2. **输入（必须）**：上一步回报的变更目录路径或 **`<change-name>`**（与 openspec-propose 产出一致）；主 Agent 必须将步骤 4（Spec）的结构化结果传入本子 Agent。
-3. 按该 SKILL 执行任务直至完成或**硬阻塞**（硬阻塞时停止全流程，汇总原因）。
+1. 读取并遵循：`.cursor/skills/apm-apply-change/SKILL.md`。
+2. **输入（必须）**：**`requirementId`**（与步骤 4 同源）；主 Agent 传入步骤 4 的结构化结果。
+3. 按 `tasks.md` 执行直至完成或硬阻塞。
 
-**完成判定**：该 SKILL 定义的完成/暂停语义达成；代码与任务勾选与仓库状态一致。
+**完成判定**：与 apm-apply-change SKILL 一致。
 
 ---
 
-## 步骤 6 — 子 Agent：MR 评审说明 → change.md
-
-1. 读取并遵循：`.cursor/skills/mr-review-brief/SKILL.md`；模板使用 **`.cursor/skills/mr-review-brief/mr-review-template.md`**（若仓库内另有 `release-checklist` 副本，以实际存在路径为准）。
-2. **对比基准**：使用**必填输入**中的 `baseBranch`。生成前先校验该分支可被 git 识别（本地或远程任一可解析）；不可解析则失败并报错，不再回退读取 `AGENTS.md`。
-3. 只读 git：`git branch --show-current`、`git log ${BASE_BRANCH}..HEAD --oneline`、`git diff ${BASE_BRANCH}..HEAD`（必要时按文件展开），按模板生成完整 Markdown（**不含**模板末尾 HTML 注释块）。
-4. **落盘（强制）**：写入 **`.apm/workitems/<name>/change.md`**，与 `prd.md` 同目录；**已存在则覆盖**。
-5. 可在对话中摘要说明已生成，但**文件以 `change.md` 为准**。
-
-**完成判定**：`change.md` 存在且含模板主要章节；`{BASE_BRANCH}` 与所选基准一致。
+## 步骤 6 — 子 Agent：生成修改摘要
 
+**执行步骤**：调用技能 `code-change-summary`，这个技能需要两个参数：对比的基线分支名称（可选）和需求ID（必选）
+**完成判定**：`change.md` 存在。
 ---
 
-## 步骤 7 — 子 Agent：全量提交并推送
+## 步骤 7 — 子 Agent：全量提交并推送代码
 
 1. `git status`：若有未跟踪或已修改文件，则 `git add -A`。
-2. 若有暂存变更：生成提交说明——**Spec** 模式可写「全自动交付 + PRD/MR 文档 + OpenSpec 实现」；**Quick** 模式写「全自动交付 + PRD/MR 文档 + 直接实现」（可附 `change-name`、requirement id、version-seq，Quick 无 openspec 时可省略 change-name），执行 `git commit`。
+2. 若有暂存变更：生成提交说明——**Spec** 模式可写「全自动交付 + PRD/MR 文档 + 工作项 tasks 实现」；**Quick** 模式写「全自动交付 + PRD/MR 文档 + 直接实现」（可附 requirement id、version-seq）。
 3. **必须** `git push -u origin "<TARGET>"`（或当前分支已设 upstream 则 `git push`）；推送失败则回报 stderr，全流程标记失败。
 
 **完成判定**：推送成功；工作区干净或仅剩用户需自理的 stash 提示。
 
 ---
 
-## 步骤 8 — 子 Agent：调用 `test-env-release` 部署测试环境
-
-1. 本步骤必须在“全部代码提交完成”后执行（即步骤 7 完成后）。
-2. 调用技能 `test-env-release`，按项目根目录 `.apm/deploy/README.md` 部署测试环境。
-3. **若部署失败**：必须输出失败原因并记录；**不得因此跳过或终止步骤 9**（仍须继续执行「待测试」状态更新）。
-
-**完成判定（本步骤自身）**：部署成功为理想结果；部署失败亦视为本步骤已结束（带失败信息），并进入步骤 9。
-
----
-
-## 步骤 9 — 子 Agent：更新需求分支状态为待测试
-
-1. 在步骤 7 完成后执行；**与步骤 8 的成败无关**（步骤 8 即使失败也必须执行本步）。
-2. 在仓库根目录或任意目录执行（只依赖 apm 配置，不依赖当前 cwd）：确保已通过 `apm login`，并已配置 `base-url`。
-3. 使用**必填输入**中的 `--branch-id`（`<BRANCH_ID>`），调用 CLI 将分支状态更新为「待测试」：
-
-```bash
-apm requirement branch set-status --branch-id <BRANCH_ID> --status PENDING_TEST
-```
-
-4. 子 Agent 需检查命令退出码，非 0 时读取 stderr，返回失败原因并终止全流程（不要静默继续后续汇总）。
-
-**完成判定**：命令成功返回（退出码 0），且无错误输出。
+## 步骤 8 — 子 Agent：部署&同步状态
 
+1. 调用技能 `code-deploy` 部署到测试环境
+2. 执行CLI命令更新需求状态 `apm status requirement <需求ID>`
 ---
 
 ## 主 Agent 汇总输出
@@ -190,26 +138,25 @@ apm requirement branch set-status --branch-id <BRANCH_ID> --status PENDING_TEST
 
 用 Markdown 表格列出**本流程实际执行的每一步**及结果（未执行的步骤标为「跳过」并简述原因）。列建议：`步骤` | `说明` | `结果` | `备注`。
 
-示例结构（主 Agent 按实况填行，不得留空表）：
+示例结构（主 Agent 按实况填行，不得留空表；**未执行**的步骤在「结果」标 **跳过** 并简述原因）：
 
 | 步骤 | 说明 | 结果 | 备注 |
-|------|------|------|------|
-| 1 | Git 分支与未提交处理 | 成功/失败 | … |
-| 2 | PRD 落盘 | … | `<name>` |
-| 3 | 分支状态 → 开发中 | … | |
-| 开发模式 | Quick 或 Spec | … | 一句判定理由 |
-| 4 | Quick 直接实现 **或** Spec propose **或** 跳过 | … | 与模式一致 |
-| 5 | Spec apply **或** 跳过 | … | Quick 时跳过 |
-| 6 | change.md | … | |
-| 7 | 提交与推送 | … | |
-| 8 | test-env-release | … | 失败仍继续步骤 9 |
-| 9 | 分支状态 → 待测试 | … | |
+| --- | --- | --- | --- |
+| 1 | Git 分支与未提交处理（`git fetch`、检出 `TARGET`、脏工作区 stash/提交） | 成功/失败/跳过 | stash 提醒等 |
+| 2 | 开发前准备（`apm get requirement`、`apm set branchName`、基于 `baseBranchName` 建分支并切换） | 成功/失败 | `requirementId`、分支名 |
+| — | **开发模式判定**（Quick **或** Spec） | 已判定 | 一句理由（见上文判定表） |
+| 3 | **Quick开发模式编码**：步骤 3 直接按 PRD 实现；**Spec**：本步跳过 | 成功/失败/跳过 | 与步骤 4～5 互斥 |
+| 4 | 生成Spec文件；**Quick**：跳过 | 成功/失败/跳过 | 产物目录 `.apm/workitems/<requirementId>/` |
+| 5 | Spec开发模式编码；**Quick**：跳过 | 成功/失败/跳过 | 与步骤 4 同源 `requirementId` |
+| 6 | 生成修改摘要 | 成功/失败 | `baseBranchName`（可选） |
+| 7 | 提交代码 | 成功/失败 | `git push` |
+| 8 | 部署 & 同步需求状态 | 成功/失败 | |
 
 ### （2）补充说明
 
 在表后以精简列表补充：
 
-- 分支名、`.apm/workitems/<name>/` 路径；**Spec** 时补充 `openspec/changes/<change-name>/`，**Quick** 时写明「未使用 OpenSpec 变更目录」。
+- 分支名、`.apm/workitems/<requirementId>/` 路径；**Spec** 时写明同目录下已生成并使用的 `proposal.md` / `design.md` / `tasks.md` / `specs/`，**Quick** 时写明「未生成工作项规划工件（或未改 tasks）」。
 - 步骤 8 测试环境部署结果（成功或失败原因；失败不阻断步骤 9）。
 - 最终 commit SHA（若有）、远程推送结果。
 - 若有 stash：提醒用户在其他分支上 `git stash pop` 时注意冲突。
@@ -218,6 +165,6 @@ apm requirement branch set-status --branch-id <BRANCH_ID> --status PENDING_TEST
 
 ## 护栏
 
-- 任一步子 Agent 失败：**不要**静默跳过；停止后续步骤，输出失败步骤与可复现命令（**例外**：步骤 8 发布失败**不**停止步骤 9）。
-- 全程**不向用户追问**澄清需求；歧义按 openspec / apply 技能中的「合理假设、不反问」处理；**Quick** 路径下同样适用合理假设、不反问。
-- **全流程交付完成**以步骤 9（分支已置为待测试）成功为准；步骤 8 发布失败仅作为告警项写入汇总，**不**单独阻断「交付完成」判定（但若步骤 9 失败，仍不得宣称全流程完成）。
+- 任一步子 Agent 失败：**不要**静默跳过；停止后续步骤，输出失败步骤与可复现命令。
+- 全程**不向用户追问**澄清需求；歧义按 **apm-propose / apm-apply-change** 中的「合理假设、不反问」处理；**Quick** 路径同样适用。
+- **全流程交付完成**以步骤 8 结束为准；步骤 8 发布失败仅作为告警项写入汇总，**不**单独阻断「交付完成」判定。

package/templates/skills/apm-fixbug/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: apm-fixbug
+description: 基于 requirementId 与 `.apm/workitems/<id>/bugs/` 下的 status.yaml、缺陷 Markdown 执行标准化缺陷修复：开发前准备 → 按「待处理」循环修复并落盘复盘 → 推送 → 调用 code-deploy 部署测试环境；当用户明确声明使用该技能时触发。
+---
+
+# 缺陷修复流程
+
+## 目的
+
+使用本技能可基于以下输入执行一致的端到端缺陷修复流程：
+- `requirementId`：需求 id（与 `.apm/workitems/<requirementId>/` 目录一致）
+- 缺陷清单以 `apm get defect <requirementId>` 同步后的本地文件为准（见步骤 1）
+
+**主 Agent 收尾（必选）**：在协调子 Agent 完成各步骤后，**必须在面向用户的最终回复中附上一张 Markdown 表格**，逐行对应每个步骤，汇总**执行状态**（如：已完成 / 已跳过 / 失败）与**简要说明**（关键结果、commit、失败原因等），便于审阅者核对流程是否闭环。
+
+## 输入
+
+**输入（必填）** `requirementId`：需求 id
+
+## 本地缺陷文件约定（必读）
+
+同步命令 `apm get defect <requirementId>` 会在如下路径落盘（**不要**臆造路径）：
+
+- 状态汇总：`.apm/workitems/<requirementId>/bugs/status.yaml`  
+  - 结构示例：根键 `defects`，下挂 `"<缺陷数字 id>"`，每项含 `status`，取值为中文：**已创建**、**待处理**、**处理中**、**待验证**、**已解决**、**重新打开**（与 CLI 生成一致）。
+- 缺陷正文：`.apm/workitems/<requirementId>/bugs/<id>.md`（`<id>` 与 `status.yaml` 中键一致）
+
+本流程**仅将「待处理」视为待修复队列**；循环直至不存在状态为「待处理」的缺陷后，进入部署步骤。
+
+## 执行步骤
+
+严格按以下顺序执行，且每一步都必须由子 Agent 独立执行并回传结果。
+
+### 步骤 1 — 子 Agent：开发前的准备
+
+1. 执行 `apm get branchName <requirementId>` 获取目标开发分支名 `branchName`。
+2. 开发工作区准备
+   1. 执行 `git fetch origin`，确保可获取最新远程分支信息。
+   2. 记录 `TARGET=<branchName>` 与当前分支 `CURRENT`，并检查工作区是否有未提交变更（staged/unstaged/untracked）。
+   3. 若 `CURRENT != TARGET` 且工作区有变更：先执行 `git stash push -u` 保存现场，再切换到 `TARGET`。
+   4. 若 `CURRENT == TARGET` 且工作区有变更：不要 stash，直接将当前改动作为「修复前检查点」提交，提交文案需明确说明这是 bugfix 前的检查点（例如：`chore: checkpoint before bugfix on <branchName>`）。
+   5. 切换到 `TARGET`：本地分支不存在时，从远程跟踪分支创建并切换。
+   6. 若在第 3 步执行过 stash，切换成功后不要自动 `stash pop`，避免与后续修复流程冲突。
+   7. 最终必须确认当前分支与 `branchName` 完全一致。
+3. 执行 `apm get defect <requirementId>` 同步 BUG 状态与内容到 `.apm/workitems/<requirementId>/bugs/`（含 `status.yaml` 与各 `<id>.md`）。
+
+**完成判定**：已在目标分支上，且本地 bugs 目录已与远端缺陷列表同步。
+
+### 步骤 2 — 子 Agent：按 bugs 清单循环修复
+
+#### 2.1 每轮开始：确定队列并登记 Todo
+
+1. 使用 **Read** 读取 `.apm/workitems/<requirementId>/bugs/status.yaml`，解析 `defects` 下各缺陷的 `status`，**仅**将状态为 **「待处理」** 的缺陷 id 列入本轮待办。
+2. 调用 **TodoWrite**，为当前所有仍处于「待处理」的缺陷各建一条 todo（标题或内容中写明缺陷 id），用于跟踪处理进度；后续每完成一个缺陷的闭环（至「待验证」并已推送）后，须将该缺陷对应 todo 标为已完成，并在下一轮开始时可按最新 `status.yaml` 刷新待办列表。
+
+若**没有任何**「待处理」缺陷：跳过 2.2，直接进入**步骤 3**。
+
+#### 2.2 单个缺陷处理（对其中一个「待处理」缺陷执行；完成后回到 2.1）
+
+1. **读取缺陷文档**：根据 `status.yaml` 中的缺陷 id，用 Read 读取同目录下的 `<id>.md`（例如 `123.md`）。
+2. **标为处理中**：将该缺陷在 `status.yaml` 中的 `status` 改为 **「处理中」**；并在同一 `<id>.md` 中同步该状态（例如在文首增加一行 `**状态**：处理中`，或新增 `## 状态` 小节——全仓库保持一致即可），保证 YAML 与 Markdown 一致。**随后**执行 `apm status defect <id>`（`<id>` 与 `status.yaml` 键、文件名一致），由服务端按当前状态自动流转（此处应为「待处理」→「处理中」）；若命令失败，不得进入本缺陷的代码修复，须先排查登录/权限或与服务端状态是否一致。
+3. **修复代码**：依据 `<id>.md` 中的缺陷描述复现、定位并实施**最小化**修复；运行相关验证（tests / lint / build 或项目最接近的校验命令），失败则迭代直至通过或明确输出阻塞信息。
+4. **复盘落盘**：在**同一** `<id>.md` 中**新增**二级标题 `## 复盘`，将根因分析、结论与必要说明写在**该标题下**（勿覆盖「缺陷内容」等与同步相关的固定段落）。
+5. **标为待验证**：将该缺陷在 `status.yaml` 中的 `status` 改为 **「待验证」**；并同步更新 `<id>.md` 中的状态展示，与 YAML 一致。**随后**执行 `apm status defect <id>`，由服务端按当前状态自动流转（此处应为「处理中」→「待验证」）；若命令失败，不得进入提交推送步骤，须先修复阻塞（含服务端状态与本流程不一致的情况）。
+6. **提交并推送**：执行 `git add -A`（或按项目规范纳入本次改动），`git commit`，提交说明须能识别对应缺陷（含 id 或标题关键词）；将当前分支推送到远程（`git push` 或 `git push -u origin "<branchName>"`）。推送失败则本流程标记失败并停止，不得宣称该缺陷已闭环。
+7. **循环**：回到 **2.1**（重新 Read `status.yaml`、更新 TodoWrite），继续处理剩余的「待处理」缺陷，直至不存在「待处理」。
+
+**完成判定**：`status.yaml` 中已无非预期的「待处理」项（全部已按流程进入「待验证」或同步结果本身无待处理项）；且每次提交均已推送成功。
+
+### 步骤 3 — 子 Agent：部署测试环境
+
+1. 本步骤须在**步骤 2 的循环结束后**执行（所有待处理缺陷已处理完毕，或同步后本就没有待处理项）。
+2. 调用技能 **`code-deploy`**，按目标项目根目录 `.apm/deploy/README.md` 执行部署；**未说明目标环境时，以 `code-deploy` 技能为准，默认部署到测试环境**。
+3. 若部署失败，输出失败原因并将流程标记为失败，不得宣称全流程完成。
+
+**完成判定**：`code-deploy` 按该技能约定执行完毕且未判定为失败。
+
+### 汇总表格式（主 Agent 最终输出）
+
+主 Agent 在流程结束时的表格应至少包含以下列，行数覆盖**步骤 1～3**：
+
+| 步骤 | 内容概要 | 状态 | 说明 |
+|------|----------|------|------|
+| 1 | 分支与工作区准备、同步 defect | 已完成 | 例：已在 `feat/xxx`，已 `apm get defect` |
+| 2 | 读取 status.yaml、TodoWrite、循环修复与推送 | 已完成 | 例：3 个缺陷已待验证，commit `abc123`，已 push |
+| 3 | code-deploy 测试环境 | 已完成 | 例：已按 `.apm/deploy/README.md` 执行 |
+
+状态列建议统一用语：`已完成`、`已跳过`（并写明跳过原因）、`失败`（并附报错或阻塞点）。
+
+## 约束
+
+- 主 Agent 交付本流程结果时，应以「步骤汇总表」为主、文字为辅；禁止仅用零散叙述代替逐步状态说明。
+- 存在未提交变更时，禁止跳过步骤 1 中的工作区与分支整理（除非该步已明确处理）。
+- 当前分支与 `branchName` 不一致时，禁止进入步骤 2 的修复循环。
+- **仅**根据 `status.yaml` 中 **「待处理」** 驱动修复队列，不要跳过 Read / TodoWrite 的登记与更新。
+- 修复须保持最小改动，并与 `<id>.md` 中的缺陷描述一致。
+- 步骤 3 完成前，不得宣称「缺陷修复与部署全流程」已完成。