ai-project-manage-cli 2.0.10 → 2.0.11

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` 为唯一锚点。
+- **不向用户追问**需求细节以推进度；歧义写入假设或「待确认」。

package/templates/skills/apm-propose/design-instruction.md

@@ -0,0 +1,94 @@
+# design 工件：写作说明
+
+生成 **`design.md`** 时说明 **如何实现**（HOW）：架构与决策为主，不写逐行代码。动机与范围以 **`proposal.md`** 为准，需求细节以 **`prd.md`** 与后续 **`specs/`** 为准。
+
+**工件 DAG、单会话减少重复 Read**：见 **`.cursor/skills/apm-propose/SKILL.md`**（「工件依赖」「单会话读取策略」）。
+
+---
+
+## 依赖（写入前须 Read 完）
+
+| 文件 | 说明 |
+| --- | --- |
+| `.apm/workitems/<requirementId>/prd.md` | 约束、验收、业务事实 |
+| `.apm/workitems/<requirementId>/proposal.md` | Why / What / Capabilities / Impact |
+
+若 **`proposal.md` 不存在**，**不得**单独写 `design.md`（与 DAG 一致）。
+
+---
+
+## 输出路径
+
+- **`.apm/workitems/<requirementId>/design.md`**
+
+---
+
+## 何时需要写满设计文档
+
+若以下任一条成立，应写完整 **`design.md`**；若均不成立且变更极小，可写精简版，但仍建议保留 **Context** 与 **Decisions** 要点。
+
+- 跨模块/多服务，或引入新的架构模式  
+- 新外部依赖，或数据模型/API 有显著变更  
+- 安全、性能、迁移复杂度值得关注  
+- 需要先拍板技术方案再编码的模糊点  
+
+---
+
+## Instruction
+
+撰写技术设计：**偏架构与取舍**，不要替代 **`tasks.md`** 里的实现步骤枚举。
+
+**须覆盖的小节**：
+
+- **Context**：背景、当前状态、约束、干系人（可简写）
+- **Goals / Non-Goals**：本设计要达到什么、**明确不做什么**
+- **Decisions**：关键技术与选型，**每项**说明取舍与备选方案（为何 X 而非 Y）
+- **Risks / Trade-offs**：风险与妥协，格式建议：`[风险] → 缓解措施`
+- **Migration Plan**：上线/灰度/回滚步骤（不适用则写「无」或「不适用」）
+- **Open Questions**：尚未决定或待验证项
+
+写作时：**引用 proposal 的动机**；规格层行为以 **prd / specs** 为准，不在 design 里重复抄 specs 全文。重点是决策的 **why**。
+
+---
+
+## Template（产出 `design.md` 时按此结构填空）
+
+小节标题可使用英文如下，或改为中文等价（如 **Context** → **上下文**，**Decisions** → **技术决策** 等）。
+
+```markdown
+## Context
+
+<!-- 背景、现状、约束、干系人 -->
+
+## Goals / Non-Goals
+
+**Goals:**
+
+<!-- 本设计要达成什么 -->
+
+**Non-Goals:**
+
+<!-- 明确不做的范围 -->
+
+## Decisions
+
+<!-- 关键选型：备选方案 + 取舍理由 -->
+
+## Risks / Trade-offs
+
+<!-- [风险] → 缓解 -->
+
+## Migration Plan
+
+<!-- 部署/迁移/回滚；无则说明 -->
+
+## Open Questions
+
+<!-- 待决问题；无则写 无 -->
+```
+
+---
+
+## Unlocks
+
+完成并落盘 **`design.md`** 后，与已完成的 **`specs/`** 一起解锁 **`tasks.md`**（`tasks` 须同时依赖二者）。

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

@@ -0,0 +1,81 @@
+# proposal 工件：写作说明
+
+生成 **`proposal.md`** 时须建立 **「为何要做」**，并与后续 **`specs/`** 对齐：**Capabilities** 段落是 proposal 与 specs 之间的契约。
+
+**工件 DAG、单会话减少重复 Read**：见 **`.cursor/skills/apm-propose/SKILL.md`**（「工件依赖」「单会话读取策略」）。
+
+---
+
+## 输出路径
+
+- 工作项目录：`.apm/workitems/<requirementId>/`
+- 写入：**`.apm/workitems/<requirementId>/proposal.md`**
+
+---
+
+## 依赖（写入前须 Read 完）
+
+| 文件 | 说明 |
+| --- | --- |
+| **`.apm/workitems/<requirementId>/prd.md`** | **唯一权威需求来源**；须全文阅读后再写 `proposal.md`。 |
+
+若工作项下尚无 **`prd.md`**：先在仓库根目录执行 **`apm get requirement <requirementId>`**，再 **Read**；仍缺失则**不得**生成 proposal（以 apm-propose **SKILL** 为准）。
+
+---
+
+## Instruction
+
+以 **`prd.md`** 为事实来源撰写变更提案（**Why**，不写实现细节；实现放在 `design.md`）。
+
+**篇幅**：精短，约 1～2 页等效内容均可。
+
+### 必含小节
+
+- **Why**：1～2 句话说明问题或机会——解决什么、为何是现在。
+- **What Changes**：要点列表，写清新增/修改/删除的能力；**破坏性变更**标注 **BREAKING**。
+- **Capabilities**：标明后续 **`specs/`** 要如何落文件——这是 proposal 与 specs 阶段的**契约**，填写前可检索仓库内既有能力文档（如 `.apm/product-capability-inventory/`）或相关 PRD/CAP 引用，避免与已有命名脱节。
+  - **New Capabilities**：新增能力，每一条对应本工作项下后续将新增的 **`specs/<kebab-name>.md`** 文件（例如 `user-auth`、`api-rate-limit`）。用 kebab-case 作文件名主干。
+  - **Modified Capabilities**：已有「规格层行为」将变更的能力（不仅是实现细节）。每条对应后续 **delta 规格**写法（可与 New 一样落在 `specs/<name>.md`，在文中标明相对既有行为的增量变更）。若无行为规格变化则留空或写「无」。
+- **Impact**：受影响的代码区域、API、依赖、系统或运维面。
+
+**注意**：Capabilities 里列出的每一项，都应在后续 **`specs/`** 中有可追溯对应（可一文件多条能力，但须在 specs 中写清）。
+
+---
+
+## Template（产出 `proposal.md` 时按此结构填空）
+
+小节标题可使用英文如下，或改为中文等价（如 **Why** → **背景与动机**，**What Changes** → **变更内容**，**Capabilities** → **能力范围**，**Impact** → **影响面**）。
+
+```markdown
+## Why
+
+<!-- 动机：解决什么问题？为何是现在？ -->
+
+## What Changes
+
+<!-- 具体变更要点；BREAKING 标注破坏性变更 -->
+
+## Capabilities
+
+### New Capabilities
+
+<!-- 每条对应后续 `specs/<kebab-name>.md` -->
+
+- `<name>`: <brief description>
+
+### Modified Capabilities
+
+<!-- 既有能力在规格层的行为变化；无则写 无 -->
+
+- `<existing-name>`: <what requirement behavior changes>
+
+## Impact
+
+<!-- 受影响代码、API、依赖、系统 -->
+```
+
+---
+
+## Unlocks
+
+完成并落盘 **`proposal.md`** 后，方可编写 **`design.md`** 与 **`specs/`**（二者仅依赖 proposal，可并行）。