ai-project-manage-cli 2.0.9 → 2.0.11

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**，直至全部完成或遇硬阻塞。不依赖 OpenSpec CLI；上下文以 **`.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 set pendingTest <需求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/{bug-fix → apm-fixbug}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: bug-fix
-description: 基于分支名和缺陷描述执行标准化的缺陷修复流程：先做工作区检查点提交，再切换分支、完成修复、生成发布检查清单、落盘 bugfix 留痕，并提交推送分支；主 Agent 须在最终回复用表格汇总各步骤执行情况。适用于用户明确要求按流程修 bug，或提到修复流程、分支修复、创建 bug-fix 任务等场景。
+name: apm-fixbug
+description: 基于分支名和缺陷描述执行标准化的缺陷修复流程：先做工作区检查点提交，再切换分支、完成修复、生成发布检查清单、落盘 bugfix 留痕，并提交推送分支；当用户明确声明使用该技能是触发。
 ---
 
 # 缺陷修复流程

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

@@ -0,0 +1,123 @@
+---
+name: apm-propose
+description: 由 PRD 在 .apm/workitems/<requirementId>/ 按依赖顺序生成 proposal、design、specs、tasks，当用于主动声明使用该技能时触发。
+---
+
+# APM 工作项：规划工件
+
+在 **`.apm/workitems/<requirementId>/prd.md`** 上生成实现前规划工件。每个文件**生成前须读哪些依赖、与谁对齐**，以对应 **`propose-instruction.md` / `design-instruction.md` / `specs-instruction.md` / `tasks-instruction.md`** 里的 **「依赖」** 小节为**唯一清单**（本 SKILL 不重复展开）。本 SKILL 只约定**撰写顺序**与 **「单会话读取策略」**；落笔前须已掌握该工件 instruction 所列依赖（是否重复全文 Read 见策略）。
+
+---
+
+## 输入
+
+| 字段 | 规则 |
+| --- | --- |
+| **`requirementId`** | **必填**。与 `.apm/workitems/<requirementId>/` 目录名一致。 |
+| **需求正文** | **唯一权威**：`.apm/workitems/<requirementId>/prd.md`。进入流程时须至少 **Read** 一次全文（是否在同一会话中重复读见「单会话读取策略」）。 |
+
+若 `prd.md` 不存在或不可读：先在仓库根目录执行 **`apm get requirement <requirementId>`**，该命令会下载最新的需求文档，再 **`Read`** 一次；仍不存在则**停止**并说明。**不要**用开放式提问代替 PRD；**不要**在缺 PRD 时继续生成工件。
+
+用户在本轮对话中的补充：仅在与 PRD 兼容时写入；若写入，在相关段落标注 **「会话补充（PRD 未载明）」**。
+
+---
+
+## Steps
+
+### 1. 锚定工作项与 PRD
+
+- 根路径：`.apm/workitems/<requirementId>/`。
+- 若尚无 `prd.md`：在仓库根目录执行 **`apm get requirement <requirementId>`**，再 **`Read` `prd.md` 全文**。若仍缺失则停止。
+- 已有则直接 `Read`：`prd.md` 全文。提取：目标用户/场景、范围、非目标、约束、验收口径。
+- PRD 未写明的：**不反问用户**；在后续工件的「假设 / 风险 / 待确认」中写明。
+- 必要时 **SemanticSearch** / **Read** 仓库代码，便于 `tasks.md` 中 **预期改动路径** 可落地；**不要**臆造 PRD 未给出的业务范围。
+
+### 2. 编排顺序与依赖出处
+
+- **依赖明细**（每个产出写入前须掌握哪些文件、不读哪些）：**只以**各 **`*-instruction.md`** 的 **「依赖」** 为准；不要在未读 instruction 的情况下凭记忆补依赖。
+- **撰写顺序（编排）**：
+  1. 先 **`proposal`**；再 **`design`** 与 **`specs`**（二者均只在 **`proposal` 落盘之后**撰写，**无**先后顺序要求，**互不**等待；**`specs` 是否读 `design`** 以 **`specs-instruction.md`** 为准）。
+  2. 最后 **`tasks`**：解锁条件以 **`tasks-instruction.md`**「依赖」为准（通常为 **`design` 与 `specs` 均已就绪**）。
+- **何时调用 Read**、如何避免重复读：下节 **「单会话读取策略」**。
+
+### 单会话读取策略（推荐）
+
+同一 Agent **连续一次跑完** proposal → design/specs → tasks 时，在**不违背各 instruction「依赖」、不少引用**的前提下减少重复 Read：
+
+| 类型 | 建议 |
+| --- | --- |
+| **`prd.md`** | 进入流程时 **Read 至少一次全文**。若本会话内已完整读过且无疑虑，写后续工件时**不必**为仪式感再次全文 Read；若 PRD **很长**、会话已很长、或需核对某条款，可对相关段落 **Read（偏移）** 或再读全文。 |
+| **`proposal.md`** | 落盘后，后续步骤以**磁盘文件**为准；若会话内已含刚写入的 proposal 全文，写 **design / specs** 时**可不重复 Read**，除非发现与磁盘不一致或需对账 Capabilities。 |
+| **`design.md` / `specs/`** | 写完并落盘后，写 **tasks** 时若会话内已无可靠记忆，应对 **`design.md`** 与 **`specs/` 下有关文件**执行 **Read**（至少覆盖 tasks 要引用的需求编号与路径）；若会话内仍完整持有二者内容，可直接撰写 tasks，**以落盘文件为最终依据**。 |
+| **`*-instruction.md`** | 每类工件在**首次**进入该工件撰写前 **Read** 对应 instruction **全文**一次即可；**不要**在同一轮流程里重复 Read 同一 instruction 文件，除非文件曾被改动或你从其他会话恢复。 |
+| **新会话 / 断点续写** | **不以**上表省略 Read：按各 **`*-instruction.md`「依赖」** 对**缺失或未确认的**文件重新 **Read**（通常以磁盘为准）。 |
+
+**不变原则**：**省略的是重复 Read**，不是省略各 instruction 写明的依赖关系；若本 SKILL 的编排顺序与某 **`*-instruction.md`「依赖」**冲突，**以该 instruction 为准**。
+
+使用 **TodoWrite** 跟踪四工件状态（`ready` / `blocked` / `done`）；**每完成一工件即落盘并标 `done`**，再解锁下一可写工件。**tasks** 条目中如何对照 specs、对齐 design 路径，以 **`tasks-instruction.md`** 为准。
+
+### 3. 生成各工件（按依赖解锁顺序）
+
+对当前工件：
+
+a. **掌握依赖内容**（见当前工件对应的 **`*-instruction.md`「依赖」** 与「单会话读取策略」）：按需 **Read**；**不要**把内部思考用标签（如 `<context>`）写进产出文件。
+
+b. **按各类工件的说明与模板**组织正文，内容严格以 **PRD** 为范围；说明文字**不**复制进产出文件。
+
+#### `proposal` → `proposal.md`
+
+- **Instruction**：按「单会话读取策略」读取 **`.cursor/skills/apm-propose/propose-instruction.md`**（每个流程一次）。
+- **依赖**：以该文件 **「依赖」** 为准（**Read** 时机见「单会话读取策略」）。
+- **再写**：`.apm/workitems/<requirementId>/proposal.md`，严格遵循其中的 **Instruction** 与 **Template**（Why / What Changes / Capabilities / Impact）。
+- **Capabilities** 与后续 **`specs/*.md`** 一一可追溯；填写前可 **Read** `.apm/product-capability-inventory/` 等本仓库能力文档，避免与既有 CAP/命名冲突（路径以仓库实际为准）。
+- PRD 中有但 instruction 未列出的要点：在 **What Changes** 或 **Impact** 中体现；缺口/假设写在 **Why** 或 **Capabilities** 注释性短句中，**不反问用户**。
+
+#### `design` → `design.md`
+
+- **Instruction**：**`.cursor/skills/apm-propose/design-instruction.md`**（每个流程一次）。
+- **依赖**：以该文件 **「依赖」** 为准（**Read** 时机见「单会话读取策略」）。
+- **再写**：`.apm/workitems/<requirementId>/design.md`，严格遵循其中的 **Instruction** 与 **Template**（Context、Goals/Non-Goals、Decisions、Risks/Trade-offs、Migration Plan、Open Questions）。
+- 说明「何时写满 / 可写精简版」的条件以 **design-instruction** 为准；与本仓库 **`tasks.md`** 的分工是：design 定方案与取舍，tasks 拆可执行步与 **预期改动路径**。
+
+#### `specs` → `specs/*.md`
+
+- **Instruction**：**`.cursor/skills/apm-propose/specs-instruction.md`**（每个流程一次）。
+- **依赖**：以该文件 **「依赖」** 为准（**Read** 时机见「单会话读取策略」）。
+- **再写**：`.apm/workitems/<requirementId>/specs/` 下文件，严格遵循 **specs-instruction** 中的写作说明与模板（新增/变更/移除/重命名分块、`### 需求` / `#### 场景`、须/必须、**当**/**则** 等）。
+- **与 proposal 对齐**：**proposal** 能力列表中每一项须在 `specs/` 有对应；命名与 **`propose-instruction.md`** 短横线文件名约定一致；细则以 **specs-instruction** 为准。
+
+#### `tasks` → `tasks.md`
+
+- **Instruction**：**`.cursor/skills/apm-propose/tasks-instruction.md`**（每个流程一次）。
+- **依赖**：以该文件 **「依赖」** 为准；写 **tasks** 时对**需求编号、路径、spec 条目**须有可靠依据，若会话内记忆不足则按「单会话读取策略」对相关落盘文件 **Read**。
+- **再写**：`.apm/workitems/<requirementId>/tasks.md`，严格遵循 **tasks-instruction**（**`- [ ]`**、分组 **`## 1.`**、编号 **1.1 / 2.1**、四条元数据子列表等）。
+- **口径**：做什么以 **specs** 为准，落在哪里以 **design** 为准；**预期改动路径** 与 design 一致。
+
+c. 每完成一个工件并落盘后，简短提示，如：`已创建 proposal` / `design` / `specs` / `tasks`。
+
+d. **不要**在依赖未满足时写下一工件（例如：`tasks` 不能在 `design` 或 `specs` 任一缺失时开写）。
+
+### 4. 全部就绪
+
+当 TodoWrite 中四个工件均为完成态，且无缺文件：
+
+- 汇总：工作项路径、已创建文件、PRD 与各工件的对应关系（一两句）。
+---
+
+## Output（对话中）
+
+完成全部工件后，回复须包含：
+- **工件列表**及各自一句话用途
+- **PRD 如何**映射到 proposal / design / specs / tasks
+
+---
+
+## Guardrails（对应原 Guardrails）
+
+- **跨工件一致**：后写须与 **PRD** 及已落盘的前序规划文件一致；各文件写什么、依赖谁、如何对齐 **proposal/specs/design**，**只以**各 **`*-instruction.md`** 为准（与 §3 相同来源，此处不重复展开）。
+- **产出纯净**：工作项下的 Markdown **不**夹带本 SKILL/对话中的内部推理、标签式草稿（参见 §3 步骤 a）。
+- **四个工件缺一不可**（specs 至少一个 `.md`）；遗漏则补全后再宣布完成。
+- **每写一个文件**：确认路径存在、内容非空后再进入下一工件。
+- **默认不覆盖**已存在的规划文件；若用户明确要求「整目录覆盖重生成」，可重写并声明覆盖范围。
+- **同名工作项目录**：以 `requirementId` 为唯一锚点。
+- **不向用户追问**需求细节以推进度；歧义写入假设或「待确认」。