ai-project-manage-cli 5.0.14 → 5.0.16

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

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

package/template/skills/apm-deploy/SKILL.md

@@ -1,21 +1,10 @@
 ## 工作流程
 
 ### 步骤1: 阅读部署文档  
+使用**Read**工具阅读 `.apm/deploy/README.md`
 
-使用**Read**工具阅读 `.apm/deploy/README.md`（这个目录可能被忽略了，也可能不存在）
+### 步骤2: 按照文档执行部署命令，禁止猜测参数
 
-### 步骤2: 判断能否部署
-
-遇到以下情况拒绝部署，直接退出即可
+如果遇到以下情况则无需部署，直接退出部署流程
 1. 没有找到部署文档，或者部署文档没有可执行的部署命令（或者说部署不可执行）
-2. 用户没有明确部署环境
-
-### 步骤3: 按照文档执行部署
-
-**严格对照** README：顺序、工作目录（若文档指定 `cd`）、环境变量、所用 CLI（如 `rush`、`docker`、`kubectl` 等）均以文档为准；将步骤 3 得到的 **`env` 等**按 README 约定注入命令或环境（禁止凭猜测填值）。**默认在 `<repoRoot>` 执行**；
-
-## Guardrails
-
-- **gitignore 不等于不存在**：`.apm` 下文件可能不入 Git 索引；**禁止**用「搜索无结果」代替 **Read** 或磁盘校验。
-- **不臆造**：README 未写的命令、环境、目标集群/命名空间，**不补充**；工作项 YAML **未提供**的字段**不得**编造。
-- **不报假成功**：命令失败或未完成 README 目标时，结论必须为「否」或等价表述。
+2. 用户没有明确部署环境

package/template/skills/apm-dev/SKILL.md

@@ -1,11 +1,27 @@
 ## 工作流程
 
-1. 选择开发模式：**Quick/Spec**
+### 步骤 1: 获取当前版本 PRD 的内容以及协作内容
 
-**Quick 开发**（满足越多越适用）: - 影响范围局部：少量文件或单一层次（例如仅前端组件、或仅一个后端模块小改）。 - 无新表结构/大规模迁移/权限模型变更。 - PRD 验收点清晰且数量少（经验上 **≤3** 条独立验收维度）。 - 不需要跨多服务的架构裁定即可开工。
-**Spec 开发**：（命中任一条即可）： - 前后端联动、多包改造或新公共抽象。 - 新数据模型、迁移、或安全/审计/权限相关。 - PRD 范围大、条款多，或存在明显「待确认/多方案」需先规划。 - 评估认为不先产出 **proposal / design / specs / tasks** 不宜直接编码。
+1. 用 **Read** 工具阅读 `.apm/sessions/<会话ID>/docs/PRD.md`，如果不存在则开发失败，退出流程。
+2. 按需阅读 `.apm/sessions/<会话ID>/docs`下的其他文档，比如前后端联调的文档
 
-2. 如果为 **Quick 开发**（子 Agent 中）执行：
+### 步骤 2: 明确开发模式
+
+**Quick 开发**（满足越多越适用）:
+
+- 影响范围局部：少量文件或单一层次（例如仅前端组件、或仅一个后端模块小改）。
+- 无新表结构/大规模迁移/权限模型变更。
+- PRD 验收点清晰且数量少（经验上 **≤3** 条独立验收维度）。
+- 不需要跨多服务的架构裁定即可开工。
+
+**Spec 开发**：（命中任一条即可）：
+
+- 前后端联动、多包改造或新公共抽象。
+- 新数据模型、迁移、或安全/审计/权限相关。
+- PRD 范围大、条款多，或存在明显「待确认/多方案」需先规划。
+- 评估认为不先产出 **proposal / design / specs / tasks** 不宜直接编码。
+
+### 步骤 3: 如果前一步判定为 **Quick 开发** 才（在子 Agent 中）执行本步骤，否则执行下一步：
 
 - 父 Agent 已通过 **Read** 掌握 `PRD.md`；若启动新子 Agent，在委派提示中写明会话 ID、消息 ID、工作项路径、以及「实现须严格对照 PRD，改动范围最小化；完成后若有代码改动须单独 `git commit`」。
 - 使用 **Task** 工具，`subagent_type: generalPurpose`，**readonly: false**，委派子 Agent：
@@ -14,14 +30,14 @@
   - **Git**：实现与自洽验收通过后，若有代码改动，**立即 `git add` + `git commit` 一次**（Quick 通常为单次交付，**一次实现 = 一个 commit**；勿拆成无意义碎 commit）。提交信息建议包含 `seesionId`（可从 `session.yaml` 或 PRD 获取）与 PRD 摘要或验收点简述。
   - 完成后在返回中说明：改了哪些路径、如何对照验收、是否通过本地可执行的检查（若子 Agent 跑了 `rushx build` / 测试等则写明结果）；若有 commit，写明 **short-sha** 与 **subject**，无代码改动则注明跳过 commit。
 
-3. 如果为 **Spec 开发** （子 Agent 中）执行：
+### 步骤 4: 如果前一步判定为 **Spec 开发** 才（在子 Agent 中）执行本步骤，否则执行下一步：
 
-- 父 Agent **Read** **apm-propose**、**apm-apply-change** 的 `SKILL.md`（**仅** `.apm/skills/` 下路径，见上节）。
-- **子 Agent A（规划）**：Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-propose/SKILL.md` 并完整遵循：在 `.apm/sessions/<sessionId>/` 生成 **proposal、design、specs、tasks** 等工件（顺序与依赖以 SKILL 为准）。
-- **子 Agent B（实现）**：待 A 成功落盘后，再 Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-apply-change/SKILL.md` 并完整遵循：按 **`tasks.md`** 驱动实现与勾选；遵守该技能中的停止条件与 commit 约定。
-- 若 **apm-propose** 未产出可用 **`tasks.md`**，不得强行进入 **apm-apply-change**；表格中标记阻塞原因。
+1. 父 Agent **Read** `.apm/skills/apm-propose/SKILL.md` 和 `.apm/skills/apm-apply-change/SKILL.md`
+2. **子 Agent A（规划）**：Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-propose/SKILL.md` 并完整遵循：在 `plans/` 下生成 **proposal、design、specs、tasks** 等工件。
+3. **子 Agent B（实现）**：待 A 成功落盘后，再 Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-apply-change/SKILL.md` 并完整遵循：按 **`plans/tasks.md`** 驱动实现与勾选；遵守该技能中的停止条件与 commit 约定。
+4. 若 **apm-propose** 未产出可用 **`plans/tasks.md`**，不得强行进入 **apm-apply-change**；表格中标记阻塞原因。
 
-4. 提交并 push 代码
+### 步骤 5: 提交并 push 代码，保证工作区干净
 
 - Quick / Spec 子 Agent 完成且本地已有 commit 时，父 Agent **立即 `git push`**（当前分支首次 push 用 `git push -u origin HEAD`）。
 - 无本地 commit、无远程或未配置 upstream 时说明原因，勿强行 push。

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

@@ -1,191 +1,52 @@
-# APM 工作项：规划工件
+## 文档说明
 
-在 `.apm/sessions/<sessionId>/docs/PRD.md` 上生成 **proposal → design / specs → tasks** 四类规划工件。各工件写什么、依赖谁，见下方对应章节；**不要**把 SKILL 说明或内部推理写进产出文件。
+从 **PRD** 为事实来源，在 `plans/` 下产出四份规划工件（`docs/PRD.md` 除外），供 **apm-apply-change** 按 `plans/tasks.md` 勾选推进实现。
 
----
-
-## 输入
-
-| 字段            | 规则                                                   |
-| --------------- | ------------------------------------------------------ |
-| **`sessionId`** | **必填**。与 `.apm/sessions/<sessionId>/` 目录名一致。 |
-| **需求正文**    | **唯一权威**：`.apm/sessions/<sessionId>/docs/PRD.md`。 |
-
-用户补充仅在与 PRD 兼容时写入，并标注 **「会话补充（PRD 未载明）」**。PRD 未写明的**不反问用户**，写入后续工件的假设 / 待确认。
-
----
-
-## 流程
-
-**顺序**：`proposal` → `design` 与 `specs`（可并行，均依赖 proposal；specs 不依赖 design）→ `tasks`（依赖 design 与 specs 均已落盘）。
-
-用 **TodoWrite** 跟踪四工件（`ready` / `blocked` / `done`），**每完成一工件即落盘并标 `done`**；依赖未满足时**不得**写下一工件。
-
-1. **Read `docs/PRD.md` 全文**（路径：`.apm/sessions/<sessionId>/docs/PRD.md`）；必要时 **SemanticSearch** / **Read** 仓库代码，便于 tasks 中 **预期改动路径** 可落地。
-2. 按解锁顺序撰写各工件（见下方章节）。
-3. 全部完成后汇总：工作项路径、已创建文件、PRD 与各工件的对应关系（一两句）；回复含各工件一句话用途。
-
-### 单会话读取策略
-
-同一会话连续跑完时，可省略重复 Read，但**不得**省略依赖关系；断点续写或新会话须按各工件「依赖」重新 Read 磁盘文件。
-
-| 文件                   | 建议                                                              |
-| ---------------------- | ----------------------------------------------------------------- |
-| `docs/PRD.md`          | 进入流程时至少读一次全文；后续按需再读。                          |
-| `proposal.md`          | 落盘后写 design/specs 时，若会话内已有刚写入的全文可不重复 Read。 |
-| `design.md` / `specs/` | 写 tasks 时若无可靠记忆须 Read；以落盘文件为准。                  |
-
----
-
-## proposal 工件
-
-**路径**：`.apm/sessions/<sessionId>/proposal.md`
+**工作项根目录**：`.apm/sessions/<sessionId>/`（下文路径均相对该目录）
 
-**依赖**：`docs/PRD.md`（全文）
+| 工件        | 落盘路径                | 作用                                                                               | 依赖                                            | 撰写规范                 |
+| ----------- | ----------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------ |
+| PRD（输入） | `docs/PRD.md`           | 需求与验收的事实来源                                                               | —                                               | —                        |
+| proposal    | `plans/proposal.md`     | **Why / What**；**Capabilities** 与 `plans/specs/` 的契约；不写实现细节            | PRD                                             | **Read** `./proposal.md` |
+| design      | `plans/design.md`       | **How**：架构与决策；不写逐行代码，不替代 `plans/tasks.md`                         | PRD、proposal                                   | **Read** `./design.md`   |
+| specs       | `plans/specs/<name>.md` | 系统**应做什么**；与 **Capabilities** 逐条对齐，不得虚构 PRD/proposal 未出现的能力 | PRD、proposal（**不**依赖 design）              | **Read** `./specs.md`    |
+| tasks       | `plans/tasks.md`        | 将 specs + design 拆为 `- [ ]` 可勾选任务                                          | PRD、proposal、design、specs（至少 1 个 `.md`） | **Read** `./tasks.md`    |
 
-以 PRD 为事实来源写变更提案（**Why**，不写实现细节）。精短即可。
-
-**Capabilities** 是 proposal 与 specs 的契约：每一项须在后续 `specs/` 可追溯。
-
-- **New Capabilities**：每条对应 `specs/<kebab-name>.md`（如 `user-auth`）。
-- **Modified Capabilities**：规格层行为变更；无则写「无」。
-
-```markdown
-## Why
-
-<!-- 1～2 句：解决什么、为何是现在 -->
-
-## What Changes
-
-<!-- 变更要点；破坏性变更标注 BREAKING -->
-
-## Capabilities
-
-### New Capabilities
-
-- `<name>`: <brief description>
-
-### Modified Capabilities
-
-- `<existing-name>`: <what requirement behavior changes> <!-- 无则写 无 -->
-
-## Impact
-
-<!-- 受影响代码、API、依赖、系统 -->
-```
+**撰写顺序**：`proposal` → `design` 与 `specs`（可并行）→ `tasks`（须等 design 与 specs 均已落盘）。
 
 ---
 
-## design 工件
-
-**路径**：`.apm/sessions/<sessionId>/design.md`
-
-**依赖**：`docs/PRD.md`、`proposal.md`
-
-说明 **如何实现**（HOW）：架构与决策，不写逐行代码，不替代 tasks 里的步骤枚举。
-
-跨模块、新依赖、安全/性能/迁移复杂或方案待拍板时写完整版；否则可精简，但保留 **Context** 与 **Decisions**。
+## 工作流程
 
-```markdown
-## Context
-
-## Goals / Non-Goals
-
-**Goals:**
-**Non-Goals:**
-
-## Decisions
-
-<!-- 每项：备选 + 取舍理由 -->
-
-## Risks / Trade-offs
-
-<!-- [风险] → 缓解 -->
-
-## Migration Plan
-
-<!-- 无则写 无 / 不适用 -->
-
-## Open Questions
-
-<!-- 无则写 无 -->
-```
-
----
-
-## specs 工件
-
-**路径**：`.apm/sessions/<sessionId>/specs/`
-
-**依赖**：`docs/PRD.md`、`proposal.md`（不依赖 design）
-
-定义系统 **应做什么**；与 proposal **Capabilities** 逐条对齐，**不得**虚构 PRD/proposal 未出现的能力。
-
-**文件组织**：一能力一文件 `specs/<短横线名称>.md`（或 `specs/<名称>/规格.md`，同一工作项内择一，勿混用）。
-
-**结构**：
-
-- 分块（`##`）：**新增需求** / **变更需求** / **移除需求** / **重命名需求**（按需组合；纯新增只用「新增需求」）。
-- 需求：`**### 需求：<名称>**`；行为用 **须、必须**。
-- 场景：`**#### 场景：<名称>**`（固定四个 `#`）；正文 `- **当** …` / `- **则** …`。
-- **每条需求至少一个场景**；变更需求须写**完整替换段落**（从需求到全部场景），禁止只贴片段。
-
-```markdown
-## 新增需求
-
-### 需求：<名称>
-
-系统须 …
-
-#### 场景：<名称>
-
-- **当** …
-- **则** …
-
-## 变更需求
-
-<!-- 完整替换后的需求 + 全部场景 -->
-
-## 移除需求
-
-### 需求：<名称>
-
-**原因**：… **迁移说明**：…
-
-## 重命名需求
-
-- **原名称：** … **新名称：** …
-```
-
----
+### 步骤 1：读取 PRD 与协作上下文
 
-## tasks 工件
+1. **Read** `docs/PRD.md`；不存在则失败并退出。
+2. 按需 **Read** `docs/` 下其他文档（如联调说明）。
 
-**路径**：`.apm/sessions/<sessionId>/tasks.md`
+### 步骤 2：按顺序落盘四工件
 
-**依赖**：`docs/PRD.md`、`proposal.md`、`design.md`、`specs/`
+遵循上表**撰写顺序**与**依赖**；每完成一工件即写入对应**落盘路径**。
 
-拆成可勾选待办；**apm-apply-change** 依赖 `- [ ]` / `- [x]` 推进。
+### 步骤 3：跟踪与收尾
 
-**格式**：
+1. 用 **TodoWrite** 跟踪四工件（`ready` / `blocked` / `done`）；依赖未满足时**不得**写下一工件。
+2. 撰写前 **Read** 依赖项及该工件**撰写规范**列中的 `./*.md`；写 `tasks` 前必要时 **SemanticSearch** / **Read** 仓库代码，使**预期改动路径**可落地。
+3. 全部完成后汇总：工作项路径、已创建文件、PRD 与各工件对应关系（一两句）；回复含各工件一句话用途。
 
-- 行首 **`- [ ]`**；分组 **`## 1. 名称`**；编号 **`- [ ] 1.1 说明`**（组号.序号）。
-- 每项下方缩进子列表：**需求编号**（对应 specs 中需求/场景）、**预期改动路径**、**验证用例编号**（可选）、**完成标准**。
-- **做什么**以 specs 为准，**改哪里**以 design 为准；按技术依赖排序。
+#### 单会话读取策略
 
-```markdown
-## 1. 数据层
+同一会话连续跑完时可省略重复 Read，但**不得**省略依赖关系；断点续写或新会话须按上表**依赖**列重新 Read 磁盘文件。
 
-- [ ] 1.1 新增合同状态字段
-  - **需求编号**：需求：合同状态同步（见 specs/contract.md）
-  - **预期改动路径**：`servers/be/prisma/schema.prisma`
-  - **完成标准**：迁移可执行；已有合同默认状态正确
-```
+| 文件                               | 建议                                                  |
+| ---------------------------------- | ----------------------------------------------------- |
+| `docs/PRD.md`                      | 进入流程时至少读一次全文                              |
+| `plans/proposal.md`                | 写 design/specs 时，若本会话刚写入全文可不重复 Read   |
+| `plans/design.md` / `plans/specs/` | 写 `plans/tasks.md` 时若无可靠记忆须 Read；以落盘为准 |
 
 ---
 
 ## Guardrails
 
 - 后写须与 PRD 及已落盘前序文件一致。
-- 四个工件缺一不可（specs 至少一个 `.md`）；落盘非空后再进下一工件。
+- 四工件缺一不可（`plans/specs/` 至少一个 `.md`）；落盘非空后再进下一工件。
 - **默认不覆盖**已有规划文件；用户明确要求「整目录覆盖重生成」时除外。

package/template/skills/apm-propose/design.md

@@ -0,0 +1,37 @@
+## 撰写说明
+
+跨模块、新依赖、安全/性能/迁移复杂或方案待拍板时写完整版；否则可精简，但保留 **Context** 与 **Decisions**。
+
+## 模板
+
+```markdown
+## Context
+
+<!-- 背景、约束、与 PRD / proposal 的衔接 -->
+
+## Goals / Non-Goals
+
+**Goals:**
+
+<!-- 本设计要达成的目标 -->
+
+**Non-Goals:**
+
+<!-- 明确不在本设计范围内的事项 -->
+
+## Decisions
+
+<!-- 每项：备选 + 取舍理由 -->
+
+## Risks / Trade-offs
+
+<!-- [风险] → 缓解 -->
+
+## Migration Plan
+
+<!-- 无则写 无 / 不适用 -->
+
+## Open Questions
+
+<!-- 无则写 无 -->
+```

package/template/skills/apm-propose/proposal.md

@@ -0,0 +1,31 @@
+## 模板
+
+```markdown
+## Why
+
+<!-- 1～2 句：解决什么、为何是现在 -->
+
+## What Changes
+
+<!-- 变更要点；破坏性变更标注 BREAKING -->
+
+## Capabilities
+
+<!-- proposal 与 specs 的契约：每一项须在后续 `plans/specs/` 可追溯 -->
+
+### New Capabilities
+
+<!-- 每条对应 `plans/specs/<kebab-name>.md`（如 `user-auth`）。 -->
+
+- `<name>`: <brief description>
+
+### Modified Capabilities
+
+<!-- 规格层行为变更；无则写「无」 -->
+
+- `<existing-name>`: <what requirement behavior changes>
+
+## Impact
+
+<!-- 受影响代码、API、依赖、系统 -->
+```

package/template/skills/apm-propose/specs.md

@@ -0,0 +1,39 @@
+## 文件组织
+
+一能力一文件 `plans/specs/<短横线名称>.md`（或 `plans/specs/<名称>/规格.md`，同一工作项内择一，勿混用）。
+
+## 结构约定
+
+- 分块（`##`）：**新增需求** / **变更需求** / **移除需求** / **重命名需求**（按需组合；纯新增只用「新增需求」）。
+- 需求：`**### 需求：<名称>**`；行为用 **须、必须**。
+- 场景：`**#### 场景：<名称>**`（固定四个 `#`）；正文 `- **当** …` / `- **则** …`。
+- **每条需求至少一个场景**；变更需求须写**完整替换段落**（从需求到全部场景），禁止只贴片段。
+
+## 模板
+
+```markdown
+## 新增需求
+
+### 需求：<名称>
+
+系统须 …
+
+#### 场景：<名称>
+
+- **当** …
+- **则** …
+
+## 变更需求
+
+<!-- 完整替换后的需求 + 全部场景 -->
+
+## 移除需求
+
+### 需求：<名称>
+
+**原因**：… **迁移说明**：…
+
+## 重命名需求
+
+- **原名称：** … **新名称：** …
+```