@aibyzero/byz 0.0.0 → 0.1.2

package/workflows/cm-plugin/commands/cm-plugin-ai-nodes/N2-enter-feature.md

@@ -0,0 +1,51 @@
+# N2: 进入 Feature
+
+1. 读取该 feature 的 requirements.md、design.md、tasks.md
+2. 断点恢复：`[x]` 已完成 → 跳过，`[DROPPED]` → 跳过，`[CHANGED]` → 按更新后描述执行。**恢复时凭证对账**：每个已 `[x]` 任务 ↔ `{SPECS_DIR}/.reviews/*-{任务号}-r*.md` 配对，缺失项输出一行 `⚠ 凭证缺失: T-xxx,...（存量欠账,如实留档,恢复起严格执行）`——不阻塞恢复，但缺失不许无声混过（实跑失守：json-keeper 7 任务全无凭证,中断前无人发现）
+3. 如该 feature 所有任务已完成 → 跳过，进入下一个 feature
+
+## 教训定向注入（防复发，两个动作）
+
+- **筛相关教训**：按本 feature 的领域/模块/技术栈关键词从 `LESSONS.md` 筛出相关条目（文件不存在或无匹配 → 注入 0 条照常继续,执行计划中输出一行说明）（`[仅记忆]` 级优先——`[已结构化]` 的已有代码防线兜底），把要点列进执行计划输出；并行派发时相关教训随 specs 摘录一并写进 agent 指令。全量加载靠注意力,定向注入才可靠（实跑教训：Infinity 防线教训在库仍复发）
+- **必扫「待触发备忘」段**：逐条判断触发条件是否与本 feature 相关——命中 → 升级为任务或在执行计划中显式认领；未命中 → 不动。扫过即在执行计划输出一行 `📌 备忘扫描: 命中 {N} 条 / 共 {N} 条`，零条也要输出（可见性纪律）
+
+## 执行计划
+
+分析 tasks.md 的依赖关系，自行决定串行或并行：
+
+| 串行 | 并行 |
+| ---- | ---- |
+| 有显式依赖 | 无依赖 |
+| 会修改同一文件/模块 | 分属不同代码项目 |
+| 涉及共享状态定义（schema、API、design token） | 天然隔离 |
+
+并行时用 Agent 工具派发子 agent，**优先使用 `cm-plugin-*-agent` 预定义角色**（cm-plugin-extension-agent / cm-plugin-ui-agent / cm-plugin-backend-agent，见 agents/ 目录）。派发指令必须包含：任务编号、该任务的 specs 摘录、design.md 中的接口契约。所有任务都有依赖时退化为全串行。
+
+**分工原则**：并行干活的用 agent（agent 管纪律：只做指定任务、不碰界外文件、不自行标记、规范汇报）；串行把关的用 skill（QA、doc-syncer 不做 agent）。agent 产出返回后，仍逐个走 N4 → N5。
+
+### 并行模式升级：Agent Teams（可选）
+
+同时满足以下条件时，将并行组升级为 Agent Teams 队友（而非子 agent）：
+
+- 环境已启用 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`
+- 并行组内的任务分属**不同代码项目**（如前端仓库 + 后端仓库）
+
+队友规则：
+
+1. **一个队友绑定一个代码项目**，绝不允许两个队友修改同一文件
+2. 生成提示中必须包含：该任务的 specs 摘录、design.md 中的接口契约、应使用的工种 skill 名称（如 `cm-plugin-extension-engineer`）
+3. 队友在**接口契约变更**时（API 字段、schema、事件格式）立即用消息通知相关队友同步，不等任务结束
+4. 队友完成后，产出仍**逐个回到 N4（审查）→ N5（标记）** 走完质量门禁，不因并行而跳过
+5. 该并行组结束后关闭所有队友，再进入下一组
+
+任一条件不满足 → 维持默认行为（Agent 工具派子 agent 或串行）。Teams 是可选加速器，不是硬依赖。
+
+输出：
+
+```text
+📂 Feature {N}/{总数} — {feature名}
+📋 执行计划：
+  串行 1: T-001 → T-002
+  并行 2: T-003 + T-004
+  串行 3: T-005 ← 依赖 T-003, T-004
+```

package/workflows/cm-plugin/commands/cm-plugin-ai-nodes/N3-execute-task.md

@@ -0,0 +1,32 @@
+# N3: 执行 Task
+
+## 开始标记
+
+```text
+🔨 Task {T-编号}: {任务描述} ~{预估时间}
+   Feature {F}/{总F} | 任务 {N}/{总数}
+```
+
+## Skill 匹配
+
+根据任务涉及的工种，查看可用的 `cm-plugin-*` skills：
+
+- 插件本体（manifest / service worker / content script / popup / options / side panel / chrome.storage / 消息通信） → `cm-plugin-extension-engineer`
+- UI 还原（有 design-baseline 的 popup/options/side panel 界面） → `cm-plugin-ui-engineer`
+- 配套后端 API（同步、鉴权、AI 代理等服务端） → `cm-plugin-backend-engineer`
+- QA/测试 → `cm-plugin-qa-engineer`
+- 打包/发布（Chrome Web Store 提审、版本管理） → `cm-plugin-devops-engineer`
+- 没有匹配 → AI 直接执行
+
+有匹配的 skill → 调用该 skill 执行。
+
+**串行 / 并行的执行方式**：串行任务由主 agent 直接按 skill 执行；并行任务（由 N2 计划决定）派发对应的 `cm-*-agent` 子 agent，agent 内部加载同名工种 skill。两种方式的产出都必须回到 N4 走审查。
+
+## 开发
+
+- 参考 design.md 技术设计和 `.claude/rules/` 规范
+- 技术选型自行选最优解，不暂停
+- 业务逻辑歧义按需求最合理解释执行并显式记录假设；**仅灾难级**（不可逆破坏/资金密钥合规/形态级错向）暂停——见 cm-plugin:ai 全局规则
+- **依赖与工具链纪律**：新引入的依赖/构建工具必须**钉版本写进 manifest**（dependencies/devDependencies），禁止在脚本里临时 `npx` 拉 latest（不可复现，锁网 CI 直接挂）；工具链改动在提交信息中单独说明，不静默混入功能变更（实跑教训：防护网脚本裸 npx esbuild 被复审抓出）
+- **二开范围纪律：只改任务范围内的代码，禁止顺手重构**——顺手"优化"老代码是存量项目的事故之源；想重构的记入 LESSONS 待触发备忘，事后走 `/cm-plugin:refactor` 单独立项、单独审查，不许夹带。改老文件跟老文件风格走，新文件才按新规范写
+- **平台专属 API 首次引入必查社区已知问题**（WebSearch"{API 名} 已知问题/踩坑"）：`chrome.*` 扩展 API 的不可靠组合官方文档不会写——MV3 service worker 休眠丢状态、offscreen document 生命周期、declarativeNetRequest 规则上限、跨浏览器 API 差异都是社区长期报告的重灾区。查证结论一行留在任务汇报里

package/workflows/cm-plugin/commands/cm-plugin-ai-nodes/N4-review.md

@@ -0,0 +1,58 @@
+# N4: Review
+
+每个 task 完成后必须执行，按**单个 task 粒度**审查。
+
+**核验类任务的处理**（产物是工具生成物或环境状态：脚手架生成、依赖安装、配置文件按模板落地）：**Codex 已安装 → 照常过 Codex，不豁免**（传生成配置与关键产物 diff，审"生成结果是否与 ADR/模板一致"）；**仅当 Codex 未安装/不可用时才跳过**——此时直接自审核验（产物存在、与 ADR/模板一致、构建/类型检查通过），不必派对抗子 agent（对生成物做对抗审查是浪费，降级链第 2 级只服务于手写代码）。手写代码任何情况下都不豁免。
+
+## 1. AI 自审
+
+检查本 task 变更的：
+
+- 代码质量：命名、结构、可读性、是否符合 `.claude/rules/`
+- 逻辑正确性：边界条件、错误处理、并发安全
+- 安全性：硬编码密钥、`.env` 误入 git、注入漏洞、OWASP Top 10
+- 性能：N+1 查询、不必要的重复计算、内存泄漏风险
+
+发现问题立即修复。不确定的点按多方案自主决策规则处理（选最合理方案并留痕），**仅触及灾难级清单**（不可逆破坏/资金密钥合规/形态级错向）才暂停——见 cm-plugin:ai 全局规则。
+
+## 2. Codex Review（强制）
+
+AI 自审通过后，调用 `codex:review`：
+
+- 传入**本 task 涉及的变更文件 diff**（不是整个 working tree）
+- 要求 Codex 审查代码质量、逻辑缺陷、安全问题
+- **本任务新增/修改的测试本身是审查对象**:断言测的是行为还是实现细节、是否安慰剂(怎么改代码都绿)、前提是否与被测代码共谋——实测最大问题类就是「测试是戏台」(七任务审查抓出最多的一类;cm-plugin:fix 第 5 步已有同款条款,此处对齐)
+- **审查产出纪律（对降级链各级同样生效）**：只报告能给出具体失败场景的问题（什么输入/状态 → 什么错误结果），按严重度排序；找不到真实问题必须明说"零发现"——凑数意见比没有审查更贵，每条都要花修复成本
+- 合理建议 → 修复后重新提交复审
+- 误报 → 记录理由后忽略
+- **审查通过后方可进入 N5**
+
+## 复审轮次上限（强制）
+
+Codex 复审**最多 2 轮**。AI 互审没有尽头——语法等价的改法无穷多，无限复审只会把代码越改越烂：
+
+- 第 2 轮后仍有分歧 → 停止复审，将分歧点和双方理由记入 LESSONS.md
+- 分歧涉及安全/数据正确性 → 暂停等人裁决
+- 分歧仅涉及风格/实现偏好 → 保留当前实现放行，进入 N5 并在进度输出中标注 `Codex review: 2轮后放行（分歧已记录）`
+
+> **三级降级路径**（按序尝试，用哪级在 N5 进度输出中标注）。**Codex 是主通道，降级是意外兜底不是备选项**——N1 预检已确认过 Codex 可用性，此处降级只发生在运行中途失效：
+> 1. `codex:review` 可用 → 双模型交叉复审（最强：跨厂商盲区互补）
+> 2. Codex 不可用 → **对抗式子 agent 复审**：派一个全新上下文的子 agent，提示词设为"假设这段 diff 有害，找出证据"——作者的上下文偏见不会带入新实例，≤2 轮上限同样生效，标注 `Codex review: 子agent对抗(N轮)`
+> 3. 子 agent 也不可用 → 单模型自审保底，标注 `跳过（环境不可用）`
+>
+> **降级门槛**：必须是本任务实际调用 Codex 失败（命令报错/超时/未登录），失败原因原文记入该任务 METRICS 行备注——"觉得可能不可用"不构成降级理由。单次超时先重试 1 次再降级；**连续 2 个任务降级 → 暂停提醒用户修复 Codex 环境**（主通道断了不是小事，不许一路降级跑完全程）。
+
+## 审查凭证落盘（防"丢审"的物理证据，强制）
+
+每轮审查的**原始输出当场落盘**——真调用比编造更省力（直接管道）：
+
+- Codex 轮：`codex ... | tee {SPECS_DIR}/.reviews/{feature}-{task}-r{轮次}.md`，文件头补一行时间戳+调用方式
+- 降级轮：同路径落盘，内容 = Codex 失败报错原文 + 子 agent 对抗结论（或核验类自审清单）
+- 返工后的复审是新一轮 → 落 `-r2` 凭证，≤2 轮上限不变
+- `.reviews/` 目录不存在则创建
+
+**无凭证文件 = 本任务审查未发生**——N5 会据此卡住标记（见 N5）。实跑教训：长会话里审查会被顺势跳过，METRICS 自填的轮次数字不构成证据，凭证文件才是。
+
+## 度量记录
+
+审查结束时记下供 N5 使用的内容：**复审轮次**（1 或 2）、**Codex 拦截数**（被采纳修复的条数；降级时记 `跳过`）写入 METRICS.md；**一句话审查摘要**（采纳/忽略条数及忽略理由）写入 N5 的 git commit message——误报的忽略理由以此落盘，不留在会话里。

package/workflows/cm-plugin/commands/cm-plugin-ai-nodes/N5-mark-done.md

@@ -0,0 +1,80 @@
+# N5: 标记完成
+
+**强制，不可跳过。** 遗漏会导致断点恢复时重复执行任务。
+
+## 步骤
+
+0. **审查凭证卡点（先于标记，必须真跑命令不许目测）**：执行 `ls {SPECS_DIR}/.reviews/*-{任务号}-r*.md`——命令无输出=**没有凭证不许标记**，退回 N4 补审。凭证是审查真实发生的唯一物理证据，METRICS 自填数字不算（实跑失守：两个项目 8 个任务在无凭证状态下被标记,文字卡点没拦住,故本步升级为强制命令执行,输出进回读行）
+0.5. **运行时观察卡点（有运行面的任务必过，标记前）**：**"编译过 + 测试绿" ≠ "真能跑"。** 任务若改动了任何**运行时可观察的产物**（扩展本体/UI/service worker/content script/脚本，即非纯文档、非纯配置、非纯类型），标记前必须**真实观察一次它按预期运行**并留证据——不是断言"我改好了"，是拿到物理产物：
+   - UI/表面 → 真实浏览器加载扩展截图（N6 形态确认同款 CfT 加载，系统 Chrome 屏蔽 `--load-extension` 用 Chrome for Testing）
+   - 行为逻辑 → 针对**本任务具体行为**的 E2E/集成测试输出（用 `templates/cm-plugin-e2e/` harness 底座，别手写 launchPersistentContext），且**必须读全 `passed` 与 `failed` 两个计数**——只看 "passed" 行会漏掉回归（实跑失守：改 UI 后 smoke 断言失效，只 grep passed 漏看 "2 failed" 连续两提交带病；另有"CfT 修复声称落盘实则在幻觉区块从未生效"——两次都是"声称完成≠真完成"，唯一解药是真跑观察）
+   - 纯逻辑函数 → 单测已覆盖即可，无需额外观察
+   证据一行进回读行（截图路径 / 测试 `N passed, M failed` 原文）。**观察不过或拿不到证据不许标记**——退回修。纯文档/配置/类型任务豁免本步。
+1. 用 Edit 工具打开 tasks.md，找到当前任务对应的行
+2. 将 `- [ ]` 改为 `- [x]`，**仅改 checkbox，不改其他内容**
+3. **立即验证**：改完后重新读取 tasks.md，确认该任务确实已标记为 `[x]`
+
+```diff
+- - [ ] T-007: 安装依赖 ~5min
++ - [x] T-007: 安装依赖 ~5min
+```
+
+## 关键约束
+
+- 每完成一个 task **立即标记**，不批量、不延后
+- Edit 失败则重试直到成功
+- `/clear` 之前必须确认标记已写入
+
+## Git 提交（每任务一次）
+
+标记验证通过后，提交本任务全部变更（代码 + tasks.md 标记）：
+
+```bash
+git add -A && git commit -m "T-{编号} {feature名}: {任务标题}
+
+审查: 自审通过 | Codex {N}轮 采纳{N}条 忽略{N}条({一句话理由})"
+```
+
+- **commit message 必须含任务编号**——"任何一行代码回溯到任务"靠这一步实现（`git log --grep "T-003"` 即可验证）
+- **一次实现天然覆盖多个任务时**（拆分过细的兜底）：message 必须列出全部编号（如 `T-005/T-006 ...`），各任务分别标记、METRICS 各记一行并备注"并入 T-xxx"——禁止只写其一导致审计链断点
+- 审查摘要来自 N4 的度量记录
+- **任务产物已在既有提交中**（典型：T-001 的产物就是脚手架自带的 initial commit）→ 用 `git commit --allow-empty` 打一条核验提交，message 照常规格式并指认产物所在的 commit sha——审计链"每任务一提交"不留空洞
+- **CLAUDE.md 版本控制字段 = `none`**（或 N1 兜底设定 NO_GIT）→ 跳过本步，METRICS 行备注 `no-git`，进度输出的 🔁 回读行中提交项写 `跳过(none)`
+
+## 度量落盘（METRICS.md）
+
+标记完成后，向 `{SPECS_DIR}/METRICS.md` 追加本任务一行（文件不存在则先创建表头）：
+
+```markdown
+| 任务 | Feature | 开始 | 结束 | 审查轮次 | Codex拦截 | QA | 人工介入(次:原因) |
+| T-003 | 1.user-auth | 10:02 | 10:41 | 2 | 1 | — | 1:业务歧义 |
+```
+
+- 审查轮次 / Codex 拦截数来自 N4；QA 列先写 `—`，N6 触发时回填
+- 人工介入：本任务执行期间每次暂停问人计 1 次并注明原因（技术选型自主决策不计）
+- 这张表是试点/灰度门槛（人工介入 ≤2 次/任务、一次通过率等）的**唯一数据源，不可跳过**
+
+## LESSONS.md
+
+如有值得记录的内容追加到 `{SPECS_DIR}/LESSONS.md`：
+
+- 架构决策及理由、踩坑记录、跨 feature 影响、环境/依赖特殊处理
+
+不记录常规开发、显而易见的事情。格式：`## {日期} — {Feature名} / {Task标题}`
+
+**条目分级（实跑教训：Infinity 防线进了 LESSONS 仍复发——纪律靠记忆不可靠）**：
+
+- 每条教训标注 `[已结构化]`（已落为测试用例/校验代码/lint 规则，防线不靠记忆）或 `[仅记忆]`（只有文字）
+- **`[仅记忆]` 是欠账**：写下时优先考虑能否顺手结构化（一条断言的成本远低于复发一次）；确实无法结构化的才保留标注，供 N2 定向注入与 N4 对照
+- **备忘/已知限制类**（"V1.x 需要……""等真实反馈再定"）不混入正文，写入文件顶部的 **`## 待触发备忘`** 段，格式：`- [挂起] {触发条件} → {事项}（来源 T-xxx）`——否则埋进只写不读的正文里，到期无人认领（实跑教训：warnings 无 UI 出口备忘无回流出口）
+
+## 输出进度
+
+```text
+✅ Feature {F}/{总F} | 任务 {N}/{总数} — {标题}
+🔍 AI review: {结果} | 🤖 Codex review: {结果}
+🔁 回读: tasks.md T-{编号}[x]已确认 | commit {短sha}含T-{编号} | METRICS 行已写 | 凭证 {ls 实际输出的文件名} | 运行观察 {截图路径 / "N passed M failed" / 豁免(纯文档)}
+📊 Feature {done}/{total} | 总体 {done_f}/{total_f}
+```
+
+**🔁 回读行是强制字段**——四项分别重新读取文件/执行命令确认后才能输出；本行缺失即视为 N5 未完成，不得进入 N6。不可见的纪律等于没有纪律（实跑事故教训：静默失败只有回读能发现）。

package/workflows/cm-plugin/commands/cm-plugin-ai-nodes/N6-qa-eval.md

@@ -0,0 +1,69 @@
+# N6: QA 评估
+
+AI 动态决策是否触发 `cm-plugin-qa-engineer`，不按固定间隔。
+
+## 评分（1-5 分，总分 ≥ 8 触发）
+
+| 维度     | 1 分                 | 5 分                  |
+| -------- | -------------------- | --------------------- |
+| 变更范围 | 单文件小改动         | 跨多模块/多项目       |
+| 风险等级 | 纯 UI 文案           | 权限/manifest/认证/支付 |
+| 累积变更 | 上次 QA 后 1 个 task | 上次 QA 后 5+ 个 task |
+| 功能边界 | 模块内部实现         | 完整用户可感知功能    |
+
+## 必须触发（无需打分）
+
+- 当前 feature 所有 task 完成
+- API 接口变更（**收尾合并豁免**：下一个任务就是本 feature 最后一个任务时，可合并至 feature 级 QA 一次执行——避免背靠背双跑全量；合并决策记运行日志 `decision` 事件。实跑教训：后端 feature 几乎每任务都改 API,逐任务触发 QA 成本失衡）
+- manifest.json 变更（permissions / host_permissions / content_scripts 匹配范围 / CSP）
+- 认证/授权/支付逻辑
+- 数据存储结构变更（chrome.storage schema、IndexedDB、后端 migration）
+- 连续 5 个 task 未触发过 QA
+
+## 跳过
+
+- 纯文档/注释/配置格式
+- 仅新增类型定义（未实现）
+- 上一个 task 刚触发过 QA 且当前变更极小
+
+**跳过也必须留痕**：无论触发还是跳过，每个任务的 N6 结论都写一条 `qa` 事件进运行日志（`触发:原因` / `跳过:评分{N}` / `合并至feature级`）——cm-plugin:ai 必记事件本就含 qa，此处重申是因为实跑失守：json-keeper 7 个任务 0 条 qa 事件，N6 被整场静默绕过，连"连续 5 个 task 未触发"的必触发条款命中了都无人知晓。**不可见的跳过等于没有 N6**
+
+## 触发格式
+
+```text
+🧪 触发 QA — 原因: {理由}
+   累积变更: {N} 个 task | 风险评估: {总分}
+```
+
+QA 通过 → 继续。发现问题 → 修复后重新 QA，最多 3 轮。
+
+**QA 新补的测试须变异自证**(机械,非审查轮):种 1-2 处行为变异必须变红,不红的测试修到红再入库——QA 测试是未来所有回归的安全网,安慰剂 QA 测试 = 永久性假安心(实跑先例:dogfood 中 QA agent 自发做过「5 个变异全被抓」,本条把自觉变成规则)。
+
+触发 QA 后，回填 METRICS.md 中对应任务行的 QA 列：`通过(覆盖率{x}%)` / `{N}轮通过(覆盖率{x}%)` / `失败上报`——覆盖率随列落盘，不留在会话里。
+
+## 形态确认卡点（仅 0.bootstrap 完成时，一次性）
+
+`0.bootstrap` 完成触发的 QA 中，**必须**执行形态确认：把构建产物**以解包扩展形式加载进真实浏览器**（`chrome://extensions` 开发者模式 Load unpacked，或 Playwright/Puppeteer 带 `--load-extension` 启动），截取扩展实际界面发给用户——
+
+```text
+📸 形态确认：这是插件当前的形态（{popup 弹窗 / side panel / options 页 / content script 注入效果}），与你要的交付形态一致吗？
+```
+
+**截图来源必须是浏览器里真实加载的扩展**（防"替代形态截图糊弄卡点"）：
+
+- popup/options/side panel → 扩展加载后打开对应界面截图；**dev server 里直接打开 popup.html 的浏览器标签页截图不作数**——脱离扩展上下文渲染的页面拿不到 `chrome.*` API，恰恰掩盖形态错配
+- content script → 打开一个匹配 `matches` 规则的真实页面，截注入效果
+- 构建产物加载报错（manifest 无效、service worker 注册失败）→ 这本身就是形态确认不通过
+
+浏览器环境不可用 → 如实上报，请用户在本机加载确认；**不得用非扩展上下文的截图过卡点**。
+
+**用户确认后才进入业务 feature**。成本是一张截图 + 3 秒确认；收益是架构错配的发现时点从"任务过半"提前到"零行业务代码"（历史事故：要 App 画成了 HTML，跑到一半才发现）。
+
+## 业务验收走查（feature 完成时）
+
+触发原因为「当前 feature 所有 task 完成」且 QA 通过后，调用 `cm-plugin-product-manager` skill 做**业务验收走查**（用户视角流程闭环 + AC 逐条对照，非技术测试）：
+
+- 小偏差 → 记录进走查报告，继续
+- 涉及需求本意的偏差 → 暂停问人，不自行认定"也可以"
+
+涉及**权限新增 / 用户数据收集 / 远程内容加载**的 feature，走查追加商店合规视角（由 `cm-plugin-qa-engineer` 的商店合规检查单执行：权限最小化、单一用途、隐私披露、禁远程代码）；**涉合规的偏差一律上报，不适用"小偏差放行"**——商店拒审的返工成本远高于一次确认。

package/workflows/cm-plugin/commands/cm-plugin-ai-nodes/N7-context.md

@@ -0,0 +1,23 @@
+# N7: 上下文管理
+
+## task 完成后
+
+**重读落盘文件即是"重载",不需要清上下文,更不需要停车**:
+
+- 当前 feature 的 specs(requirements.md、design.md、tasks.md)
+- `{SPECS_DIR}/LESSONS.md`
+- 代码项目的 `.claude/CLAUDE.md` + `.claude/rules/`
+
+重读完成后**直接继续下一个 task,不停车、不等用户、不以问句收尾**。
+
+> 历史版本此处要求"执行 /clear"——那是用户侧斜杠命令,AI 无法自行执行,写在这里的实际效果是每个任务结束都停下来等人敲命令,与本文件末行"全程自动继续"直接矛盾(实跑反馈:每个阶段都要人确认才走,根因即此)。现行 Claude Code 上下文过长会自动压缩,无需人工 /clear;**以磁盘为准重读 specs 才是防漂移的有效动作**——压缩摘要可能丢细节,落盘文件不会。
+
+## task 执行中
+
+察觉上下文被自动压缩过(前文变成摘要)→ 继续当前 task 前,重读本 feature 的 specs 与当前任务相关的 design 章节,以落盘文件校准记忆,不信摘要里的细节数字。
+
+## feature 完成后
+
+同上重读,直接进入下一个 feature。
+
+全程自动继续。**唯一合法停车点**:cm-plugin:ai 全局规则的灾难级清单 + 各节点显式卡点(入口闸/Codex 降级知情/形态确认/涉合规走查)——不在此列的停车都是违规。

package/workflows/cm-plugin/commands/cm-plugin-ai-nodes/N8-finish.md

@@ -0,0 +1,61 @@
+# N8: 完成
+
+所有 feature 的所有任务完成后：
+
+## 1. 调用 cm-plugin-doc-syncer
+
+调用 `cm-plugin-doc-syncer` skill 完成文档同步：
+
+- README 精炼更新（架构 + 业务 + 快速开始）
+- .claude/CLAUDE.md 和 rules/ 同步
+- specs CHANGELOG 按日期生成
+- 文档一致性验证
+
+## 1.5 代码库参考文档回写（存在时强制）
+
+`{项目根}/docs/codebase-context/` 存在时（skill 未安装但文档在 → 按 skill 文内的回写映射表手动执行，映射表就在文档同目录项目里；两者都无 → 跳过本步），按 `codebase-context` skill dev 模式步骤 3 的「变更类型 → 需更新文档」映射表，把本次全部 feature 的变更回写进参考文档（09-changelog 类型标 `dev回写`）——**地图必须跟着代码走，否则下次二开按过期地图改**。
+
+## 2. 生产发布待决清单
+
+**前置（与 cm-plugin:prd 的 T-012 生成条件同源）**：项目存在部署形态（Dockerfile / CI 配置 / 部署脚本，或 `{SPECS_DIR}/RELEASES.md` 已存在）才执行本步；**纯本地工具、库等无部署形态的项目 → 跳过**，总结中输出一行 `🚀 发布清单: 跳过(无部署形态)`——规格期没生成部署任务的项目，收尾也不该凭空编制发布清单（实跑教训：dogfood 中 RELEASES.md 不存在,数据源为空仍无条件调用）。
+
+调用 `cm-plugin-devops-engineer` skill **编制**（只编制，不执行生产发布）。**staging 验证状态的数据源是 `{SPECS_DIR}/RELEASES.md`**，不凭记忆：
+
+- 已通过 staging 验证的 feature 清单及版本（读 RELEASES.md）
+- 生产迁移清单与执行顺序（含备份点）
+- 新增环境变量清单（值由人在生产环境配置）
+- 回滚预案位置
+
+**生产发布由人决策触发**，不属于本流程的自动动作。
+
+## 3. 度量汇总
+
+读取 `{SPECS_DIR}/METRICS.md`，**只统计本次执行涉及的 feature 的行**（按 Feature 列过滤——防止历史批次数据混入本次门槛对照），全量历史另起一行标注"累计"。输出：
+
+```text
+📊 度量汇总
+任务: {N} 个 | 人工介入均值: {x} 次/任务 | 一次通过率(复审仅1轮): {x}%
+Codex 拦截: 共 {N} 条 | QA: 触发 {N} 次/通过 {N} | 总耗时: {x}
+💰 成本: 请运行 /cost 并把本次会话费用回填到下面度量汇总的成本行
+```
+
+**审查凭证对账**：tasks.md 全部 `[x]` 任务 ↔ `{SPECS_DIR}/.reviews/` 凭证一一对账，缺失项列入度量汇总（`⚠ 审查凭证缺失: T-xxx,...`，全齐则 `审查凭证: {N}/{N} 齐`）——中途漏网的审查，收尾必须暴露，不许无声混过。
+
+**运行日志收口**：追加 `done` 事件后，报告 `运行日志.jsonl` 的路径与行数（如 `📜 运行日志: {SPECS_DIR}/运行日志.jsonl · 共 {N} 行`）——提醒用户反馈工作流问题时连同 METRICS.md 一起带回。只报告，不清理不截断。
+
+**成本落盘（灰度门槛"单任务成本<人工工时"的数据源）**：输出汇总后提醒用户执行 `/cost`，将会话总费用与总耗时一起写入 `{SPECS_DIR}/度量汇总.md` 的成本行（`成本: ${x} / {N} 任务 ≈ ${x/N} 每任务`）。用户不回填则标注 `成本: 未采集`——宁可留空，不许编造。
+
+## 4. 输出总结
+
+```text
+🎉 全部完成
+
+📂 Features: {完成数}/{总数}
+📋 总任务: {完成数}/{总数}
+📝 文档同步: 已完成
+🚀 生产发布待决清单: 已编制，等待人工决策
+
+各 Feature 摘要:
+- 1.{name}: {N} 个任务 ✅ (staging 已验证)
+- 2.{name}: {N} 个任务 ✅ (staging 已验证)
+```

package/workflows/cm-plugin/commands/cm-plugin-prd-modes/brownfield.md

@@ -0,0 +1,13 @@
+# cm-plugin:prd 模式文件 — 二开模式（B2–B5）
+
+> 由 /cm-plugin:prd Step 4 判定「存量项目且本次需求会修改存量代码」时读取本文件。B1(加载参考文档)保留在主文件 Step 4。规则内容与主文件同源拆分,语义未变。
+
+**二开模式追加规则（GREENFIELD=false 且本次需求会修改存量代码时生效）**：
+
+- **B2 波及面分析**：对每个将被修改的存量模块，基于参考文档（03-architecture 模块关系 / 04-api-routes 调用方 / 07-business-logic 线路）+ Grep 核实，在 design.md 写「波及面」段：改哪里 → 谁调用它 → 哪些老功能可能受影响。**波及面是 QA 回归范围的数据源**
+- **B3 防护网任务**：凡 tasks.md 中包含"修改存量模块"的 feature，第一个任务固定为**防护网基线**。**项目已有测试资产**（jest/vitest 等且可运行）→ 基线 = 跑通存量全量测试并记录结果，**不重复造快照**（实跑验证：184 用例的成熟项目直接复用，前后各跑一次）；**无测试资产** → 才写现状快照测试锁住将被修改模块的当前行为（不判断对错，只锁现状）。开发后复跑基线，变红即为碰坏老行为的信号
+- **B4 specs 只覆盖增量**：不为整个存量系统补规格；只为本次改动涉及的模块建规格，存量行为"用到哪、记到哪"（记进参考文档 07，而不是 specs）
+- **B5 拆分锚定地图**：feature 与任务的边界对齐业务地图，不凭感觉切——
+  - **feature 沿业务线路拆**（07-business-logic 的线路）：需求同时触及多条线路（如"行情展示"+"导出"）→ 按线路切成多个 feature，一条线路一个 feature
+  - **任务尽量单模块**（03-architecture 的模块关系）：一个任务的改动落在一个模块内；确需跨模块的任务，描述中显式列出涉及模块清单（审查与波及面据此聚焦）
+  - **地图盲区检测**：需求涉及的逻辑在 07 中找不到对应线路 → 说明地图有盲区，先对该区域增量补扫（scan 只读相关目录）再拆分——拆错边界的成本远高于补扫

package/workflows/cm-plugin/commands/cm-plugin-prd-modes/change-mode.md

@@ -0,0 +1,130 @@
+# cm-plugin:prd 模式文件 — 变更模式
+
+> 由 /cm-plugin:prd 模式判断检测到 `--change` 时读取本文件。规则内容与主文件同源拆分,语义未变。
+
+## 变更模式
+
+当输入 `/cm-plugin:prd --change {N}.{feature-name} 变更内容` 时执行。
+
+### Step C1: 定位已有 specs
+
+在 `{SPECS_DIR}/` 中查找匹配的编号目录。
+
+如果只传了序号（如 `--change 1`），自动匹配 `1.*` 目录。
+
+找不到则报错提示。
+
+### Step C2: 读取现有 specs
+
+读取该目录下的：
+
+- `requirements.md` — 当前需求
+- `design.md` — 当前设计
+- `tasks.md` — 当前任务（注意哪些已完成 `[x]`）
+
+### Step C3: 解析变更内容
+
+变更内容可以是：
+
+- 纯文本描述变更
+- 文件路径（新的需求文档）
+- URL
+
+### Step C4: 对比分析
+
+**调用 `cm-plugin-product-manager` skill 的变更影响分析**：除识别增删改外，评估波及哪些已完成任务（返工风险）、哪些验收标准失效。
+
+变更内容涉及**新增权限 / 扩大 host_permissions / 新收集用户数据 / 加载远程内容**时，同时做商店合规预扫（检查方法以 `cm-plugin-qa-engineer` 的商店合规检查单为准）：新引入的权限逐项给用途理由，合规问题并入变更摘要供人审——权限扩张类变更提审时会触发商店重新审核，人必须知情。
+
+将变更内容与现有 requirements.md 对比，识别：
+
+- **新增**的功能需求
+- **修改**的功能需求
+- **删除**的功能需求
+- 对验收标准的影响
+
+### Step C5: 更新 requirements.md
+
+- 在「需求版本」表中追加新版本行：
+
+```markdown
+## 需求版本
+
+| 日期       | 版本 | 说明             |
+| ---------- | ---- | ---------------- |
+| 2026-04-11 | v1   | 初始需求         |
+| 2026-04-15 | v2   | 新增微信登录方式 |
+```
+
+- 在功能需求中标注变更：
+
+```markdown
+## 功能需求
+
+1. [F-001] 邮箱 + 密码登录
+2. [F-002] 手机号 + 验证码登录
+3. [F-003] Tab 切换登录方式
+4. [F-004] ~~短信验证码 5 分钟过期~~ `[v2 删除]`
+5. [F-005] 微信扫码登录 `[v2 新增]`
+6. [F-006] 表单验证 `[v2 修改: 新增微信回调校验]`
+```
+
+### Step C6: 更新 design.md
+
+- 追加设计版本
+- 新增/修改受影响的功能模块设计
+- 不动未受影响的模块
+- 标注变更原因
+
+### Step C7: 更新 tasks.md
+
+- 追加任务版本
+- 已完成的任务 `[x]` 保持不动
+- 受变更影响的未完成任务标记 `[CHANGED]` 并更新描述
+- 因变更作废的任务标记 `[DROPPED]`
+- 新增的任务标记 `[NEW]`
+
+```markdown
+## 任务列表
+
+### 功能 1: 登录表单
+
+- [x] T-001: 创建登录页面和 Tab 切换组件 ~30min
+- [x] T-002: 实现邮箱登录表单 ~30min
+- [ ] T-003: 实现手机号登录表单 ~30min `[CHANGED v2: 去掉倒计时]`
+- [ ] ~~T-004: 短信过期逻辑~~ `[DROPPED v2]`
+
+### 功能 2: 微信登录 `[NEW v2]`
+
+- [ ] T-008: [NEW] 微信 OAuth 回调处理 ~30min
+- [ ] T-009: [NEW] 微信登录按钮组件 ~15min
+```
+
+### Step C8: 输出变更摘要
+
+```
+📝 需求变更: 1.user-auth v1 → v2
+
+新增: 2 个功能需求, 2 个任务
+修改: 1 个功能需求, 1 个任务
+删除: 1 个功能需求, 1 个任务
+未受影响: 3 个已完成任务保持不动
+
+请产品审查变更后，运行 /cm-plugin:ai 继续开发（会跳过已完成任务）
+```
+
+---
+
+## 示例用法
+
+```bash
+# 新建需求 — 提供项目文件夹路径，docs/ 下放需求文档
+/cm-plugin:prd ~/projects/my-app-specs
+/cm-plugin:prd /path/to/project-specs
+
+# 需求变更 — 同样基于项目文件夹，指定要变更的 feature
+/cm-plugin:prd --change 1.user-auth 新增微信扫码登录方式
+/cm-plugin:prd --change 2 ~/projects/my-app-specs
+```
+
+**审批位重置**：变更落盘后，将 `{SPECS_DIR}/.cm-specs-status` 重置为 `awaiting_review`——改过的规格等于没审过，N1 入口闸将再次要求确认。

package/workflows/cm-plugin/commands/cm-plugin-prd-modes/greenfield.md

@@ -0,0 +1,82 @@
+# cm-plugin:prd 模式文件 — 0→1 空项目分支（GREENFIELD）
+
+> 由 /cm-plugin:prd Step 3 判定 GREENFIELD=true 时读取本文件。规则内容与主文件同源拆分,语义未变。
+
+## 0→1 空项目分支（GREENFIELD）
+
+Step 3 检测到 `GREENFIELD=true` 时叠加以下规则。核心思想：**架构决策也是需求的产物，走同一条 specs 流水线**——选型即设计，搭建即任务，享受同样的人审卡点、断点恢复和审计链。
+
+### G1: 技术选型确认（并入 Step 5.5）
+
+**先读完需求再谈选型，推荐必须从需求特征推导，不套通用默认。** 流程：
+
+0. **交付表面必问（第一问，不可默认）**：本工作流交付形态固定为**浏览器扩展（MV3）**，但表面组合是架构第一分叉：popup / options / side panel / content script / devtools 面板 / 新标签页接管 / 纯后台——需求没写就必须问，答案强制写入 ADR 和 CLAUDE.md 的「交付形态」字段（如 `Chrome 扩展 · side panel + content script`）。同时必问**目标浏览器**：仅 Chrome / Chrome+Edge / 含 Firefox（决定是否引入 webextension-polyfill 与双 manifest）。**需求方说"做个插件"时脑中的画面千差万别，表面组合看错全错**
+1. **联网校验当前最佳实践**：确认表面组合后，WebSearch 当年扩展脚手架生态（WXT / Plasmo / CRXJS 迭代和维护状态变化快，不可凭记忆推荐）；网络不可用 → 使用 `~/.claude/templates/cm-plugin-arch-reference.md` 基准表兜底，并向用户标注快照日期建议复核；联网发现基准表过时 → 顺手更新它
+2. **提取需求特征**并给出架构含义（展示推导过程，让人能审）：
+
+```text
+需求特征 → 架构含义（示例）
+- 改写/增强特定网站页面   → content script 为主,注意 isolated world 与宿主样式隔离
+- 常驻工具面板            → side panel(Chrome 114+) 优于 popup(点开即关)
+- 拦截/改写网络请求       → declarativeNetRequest(注意规则上限),MV3 已无 blocking webRequest
+- 需要账号/跨设备同步     → chrome.storage.sync 够小数据;大数据/多端 → 配套后端
+- 调用 AI/付费 API        → 密钥不得进扩展包,必须配套后端代理
+- 需要抓取/解析页面数据   → content script 提取 + service worker 汇总,注意宿主页 SPA 路由变化
+- 多浏览器发布            → webextension-polyfill + 构建期双 manifest
+- 团队约束/发布条件       → 一票否决项,压过所有技术偏好
+```
+
+3. 基于特征给出 **2-3 套定制方案**，每套包含：脚手架（WXT / Plasmo / CRXJS+Vite / 原生无框架）、UI 技术栈、取舍、**对应的脚手架命令**（如 `npx wxt@latest init`、`npm create plasmo`、`npm create vite@latest -- --template react-ts` + CRXJS），并标注推荐项及推导理由（含联网校验的来源）。**命令验证边界：只许 `--help` 核实参数、`--dry-run` 验证组合，不得实际生成项目**——生成是 T-001 的职责，G1 阶段生成会让 N1 撞上"目录非空 + T-001 未勾选"信号，凭空多一次人工确认（实测教训）
+4. 人做选择题，不做填空题；确认结果连同脚手架命令写入 ADR，bootstrap T-001 直接使用该命令。**写入 ADR 的必须是全参数命令**（含包管理器等全部选项）——缺参数的命令会在无人值守执行时停下来交互式提问；现代脚手架（如 better-t-stack）完成/dry-run 时会回显"可复现完整命令"，抄它进 ADR 是标准做法
+
+必须覆盖的提问维度：
+
+- 团队已熟悉的技术栈（这是约束，不是偏好）
+- 发布渠道（Chrome Web Store 公开上架 / unlisted / 企业内部分发 / 仅开发者模式自用——决定合规投入的量级）
+- 是否需要配套后端（账号体系、API 代理、数据同步；纯本地插件可以零后端）
+- 版本控制（默认本地 git init，写成"默认 X 如不符请指出"；用户明确不用 → bootstrap 的 CLAUDE.md 版本控制字段记 `none`，全链路降级）
+- 权限敏感度（目标用户对 host_permissions 范围的接受度；`<all_urls>` 会显著拉长商店审核并吓退用户）
+
+**选型未确认前不得进入 Step 6。**
+
+### G2: 生成 0.bootstrap feature（在业务 feature 之前）
+
+编号固定为 `0`，业务 feature 从 `1` 开始：
+
+```text
+{SPECS_DIR}/
+├── docs/
+├── 0.bootstrap/          ← 0→1 专属
+│   ├── requirements.md   # 非功能需求：团队约束、部署条件、性能要求、预算
+│   ├── design.md         # 即 ADR：候选方案对比表、最终选型、每项理由
+│   └── tasks.md          # 见下方任务模板
+└── 1.{business-feature}/
+```
+
+`design.md` 按 ADR（架构决策记录）写：候选方案对比表（方案 / 优势 / 代价 / 是否入选）+ 最终选型清单 + 每项决策的理由。**这份文件就是日后回答"当时为什么选 X"的唯一出处。**
+
+`tasks.md` 任务模板（按需裁剪）：
+
+```markdown
+- [ ] T-001: 用选定脚手架生成扩展骨架（{选定的 create 命令}），manifest 只声明本期确需的最小权限；脚手架未自带 git 时执行 git init ~15min
+- [ ] T-002: 生成 .claude/ 规范（等同 /cm-plugin:init 产出，基于已选型技术栈，必含 rules/chrome-extension.md） ~15min
+- [ ] T-003: CI 与构建骨架（lint/test/build 流水线 + 打包 zip 产物，环境变量模板） ~30min ——**计划迭代 ≥3 个 feature 的项目不得裁剪本任务**：测试是基建不是环节，第一周省下的半小时会在第五周连本带利还（实测两次 demo 裁剪 + 行业重度实践共同教训）
+- [ ] T-004: 公共底座（消息通信封装、chrome.storage 读写层、错误处理、各表面入口结构） ~30min
+- [ ] T-005: E2E 基座 ~30min ——**直接拷 `~/.claude/templates/cm-plugin-e2e/` 的久经考验底座**（`extension-harness.ts` + `smoke.spec.example.ts`），别自己写 launchPersistentContext/SW 获取（会重踩全套坑：系统 Chrome 屏蔽 --load-extension 须用 Chrome for Testing、SW 注册-停机竞态、headless:false 无头环境退化、SW idle 后 "Worker was closed"、CfT 跨架构路径——harness 里全封装好了）。换掉 `{扩展名}` 等占位后跑通"扩展能加载、SW 注册、popup 可开"。扩展的"能跑起来"只能真实浏览器验证，这条冒烟是 N6 形态确认卡点与 N5 运行观察闸的技术前提
+```
+
+### G3: 业务 feature 的生成规则
+
+业务 feature 的 design.md 基于 **G1 已确认的选型**生成（此时规范文件尚不存在，以选型结论为准）。执行时序由 /cm-plugin:ai 保证：`0.bootstrap` 最优先执行，完成后规范已落地，后续 feature 加载的就是真实的 CLAUDE.md 和 rules。
+
+### G4: 后续架构变更
+
+架构调整走已有变更模式：`/cm-plugin:prd --change 0.bootstrap 数据库从 SQLite 换 Postgres`——ADR 追加版本行，决策演进全程留痕。
+
+**执行中发现架构错配的标准处置**（如 /cm-plugin:ai 跑到一半发现交付形态/框架不对）：
+
+1. **干净停点**：当前任务走完 N5（标记+落盘）再停
+2. **形态确认与回收率评估**（先问清目标形态再动手）：换脚手架（如 Plasmo → WXT）≈80% 可回收（业务逻辑与 UI 组件可迁，入口与构建配置重写）/ 换表面（如 popup → side panel）≈90%（改入口与 manifest）/ 从扩展改成 Web 应用或反向 ≈30%（`chrome.*` 依赖层全部重写，只有纯逻辑与 specs 可复用）
+3. `/cm-plugin:prd --change 0.bootstrap 交付形态从 X 改为 Y` → ADR 记 v2，受影响任务标 `[DROPPED]`/`[NEW]`（含显式迁移任务），已完成可保留的不动
+4. **旧代码移入 `legacy/`**，可回收部分由迁移任务显式搬运；重跑 /cm-plugin:ai 时 N1 的目录信号会强制确认目录处置
+5. 断点恢复按新标记续跑