@aibyzero/byz 0.0.0 → 0.1.2

package/workflows/cm-plugin/commands/cm-plugin:ai.md

@@ -0,0 +1,75 @@
+# /cm-plugin:ai — 自动开发
+
+`$ARGUMENTS` — specs 文件夹路径 + 代码项目路径。
+
+```bash
+/cm-plugin:ai specs在~/projects/my-app-specs，代码在~/code/my-app
+/cm-plugin:ai ~/projects/specs 前端~/code/fe 后端~/code/api
+```
+
+## 流程图
+
+按此流程执行，到达每个节点时读取 `~/.claude/commands/cm-plugin-ai-nodes/` 下对应的节点文件获取详细规则。
+
+```text
+START
+  │
+  ▼
+[N1: 初始化] ── 解析输入、扫描 features、加载上下文
+  │
+  ▼
+┌─► [N2: 进入 Feature] ── 读取 specs、分析依赖、输出执行计划
+│     │
+│     ▼
+│   ┌─► [N3: 执行 Task] ── 检查 skill → 开发
+│   │     │
+│   │     ▼
+│   │   [N4: Review] ── AI 自审 → Codex Review
+│   │     │
+│   │     ▼
+│   │   [N5: 标记完成] ── tasks.md 标 [x]、写 LESSONS.md
+│   │     │
+│   │     ▼
+│   │   [N6: QA 评估] ── 评分决定是否触发 cm-plugin-qa-engineer
+│   │     │
+│   │     ▼
+│   │   [N7: 上下文管理] ── /clear → 重新加载 specs
+│   │     │
+│   │     ▼
+│   │   还有未完成 task? ──YES──┘
+│   │     │
+│   │    NO
+│   │     │
+│   │     ▼
+│   └── Feature 完成 → /clear
+│         │
+│         ▼
+│       还有下一个 Feature? ──YES──┘
+│         │
+│        NO
+│         │
+│         ▼
+      [N8: 完成] ── 调用 cm-plugin-doc-syncer → 输出总结
+        │
+        ▼
+       END
+```
+
+## 全局规则
+
+**暂停（仅灾难级）：** 不可逆破坏（删数据、动线上、不可回滚迁移）、资金/密钥/合规风险、交付形态级架构错向、环境阻塞到无法继续。
+**不暂停（多方案自主决策）：** 执行中出现多个可选方案时——技术选型、实现路径、库/工具选择、审查意见分歧——**自己分析利弊选最优解直接执行，不询问**。代价是留痕义务：把「选了什么 / 为什么 / 放弃了什么」写进任务汇报，方向性取舍追记 LESSONS.md——人可以事后翻案，但流程不为选择题停车。业务逻辑歧义按需求文档最合理解释执行并显式记录所做假设，仅当触及灾难级清单才暂停。
+**节点间不停车：** 除上述灾难级与各节点显式卡点（入口闸/降级知情/形态确认/涉合规走查）外，任何节点完成后**直接进入下一节点**——不得以"我将要…是否继续?"、"完成了 X,需要我继续吗?"这类问句收尾等待。阶段性汇报写在输出里照常可见,但回合不能停在等确认上（实跑反馈:执行器习惯性在节点末尾问一句,用户被迫每阶段点头,自动化名存实亡）。
+**度量：** 每次暂停问人，恢复后在当前任务的 METRICS.md 记录里人工介入计 1 次并注明原因（见 N5）。
+**状态落盘（供状态条/看板实时点亮节点）：** 每进入一个节点（N1–N8），覆盖写入 `{SPECS_DIR}/.cm-status.json` 单行 JSON：
+`{"node":"N4","feature":"1.xxx","task":"T-005","detail":"一句话当前动作","state":"running","at":"HH:MM:SS"}`
+——**detail 必须写大白话**，标准是"路过的非工程师扫一眼能懂"：写"正在开发数据接口"不写"cm-plugin-backend-engineer 执行 T-004"；写"第2轮代码审查"不写"对抗式子agent复审"；写"确认一下：原型里有3个按钮点了没反应,要做吗?"不写"原型死区待确认"。节点号/任务号由状态条自动放在行尾角标，detail 里不要再写。
+——暂停等人时 `state` 改为 `paused_for_human`（detail 写等什么），全部完成时 N8 写 `done`。N1 时**额外把 specs 绝对路径写入 `~/.claude/cm-plugin-current-specs`**（终端状态条据此定位）。每节点一次写入，成本可忽略，不得跳过。
+**运行日志（事后复盘与工作流优化的原始证据）：** 与状态落盘同节奏，把关键事件**追加**（不覆盖）到 `{SPECS_DIR}/运行日志.jsonl`，一行一个 JSON。**`at` 一律 ISO 8601 带时区偏移**（`date +%Y-%m-%dT%H:%M:%S%z` 风格，如 `2026-07-17T10:05:25+08:00`）——实跑发现三个项目分别用了无时区/`Z`/`+08:00` 三种格式，跨项目看板排序失真：
+`{"at":"2026-07-15T14:22:10","node":"N3","feature":"1.xxx","task":"T-005","event":"task_start","detail":"一句话大白话"}`
+**必记事件（event 取值固定）**：`node_enter`（每次进节点）、`task_start` / `task_done`（done 的 detail 记一次通过与否）、`review`（轮次+拦截数+通道: codex/子agent/自审）、`degrade`（降级及失败原文）、`pause` / `resume`（等什么、人答了什么）、`decision`（多方案自主决策: 选了什么/为什么/放弃了什么）、`error`（执行报错与重试）、`qa`（N6 结论）、`done`（N8 收尾）。
+写日志与写 .cm-status.json 同时机同成本，不得跳过；只追加不清理不截断。**反馈工作流问题时，把这份文件连同 METRICS.md 一起带回**——它是定位流程卡点、优化节点设计的第一手依据。
+
+**终端任务清单镜像：** 进入每个 feature（N2）时，把该 feature 的任务镜像到 Claude Code **内置任务清单**（TaskCreate/TodoWrite，一任务一条，含编号与标题）；N3 开始执行置 in_progress，N5 标记时同步置 completed——终端原生渲染勾选进度，无需任何外部工具。**断点恢复时**：已完成（`[x]`）任务直接以 completed 状态镜像或跳过，`[DROPPED]` 不镜像——不得重复创建条目。
+
+**执行策略：** AI 自主决策串行或并行（无依赖 + 不同项目 → 并行，否则串行）。

package/workflows/cm-plugin/commands/cm-plugin:check.md

@@ -0,0 +1,66 @@
+# /cm-plugin:check — 框架一致性自检
+
+校验 cm 工作流安装的完整性和引用一致性。**每次修改框架文件后运行一次**——历史上的缺陷（改名残留、匹配表缺项、死角色、失效命令引用）全属"引用断链"类，本命令将其机器化检查。
+
+## 检查项
+
+### 1. 角色文件存在性
+
+- `~/.claude/commands/cm-plugin-ai-nodes/N3-execute-task.md` 匹配表中引用的每个 `cm-plugin-*-engineer` / `cm-plugin-*-manager` → `~/.claude/skills/{名称}/SKILL.md` 必须存在
+- `N2-enter-feature.md` 预定义角色列表中的每个 `cm-plugin-*-agent` → `~/.claude/agents/{名称}.md` 必须存在
+- 反向检查：skills/ 与 agents/ 下存在、但 `~/.claude/commands/` 下**任何文件**（命令 + cm-plugin-ai-nodes/ 节点 + cm-plugin-prd-modes/ 模式文件）均未引用的角色 → 报告为"孤儿角色"（建了没接线）。范围不得收窄到 N2/N3——把关型 skill（cm-plugin-doc-syncer/cm-plugin-product-manager/cm-plugin-qa-engineer/cm-plugin-devops-engineer）按设计接在 cm-plugin:ai/N6/N8/cm-plugin:prd/模式文件上，只查派发路径会把它们误报成孤儿（v0.9.24 实跑教训：init 自举时靠人工甄别才排除三处假阳性）。**检查范围限定 `cm-plugin-` 前缀**——上游 cm-workflow 的 `cm-*` 角色（同机共存时存在）与非前缀独立工具（如 codebase-context）都不参与本检查的角色配对（实跑教训：v0.2.2 首次自测按 cm- 扫会把共存的上游角色误报为孤儿），但其被 cm-plugin:init/cm-plugin:prd/N8 的引用仍走第 3 组命令引用检查
+
+### 2. 命名一致性
+
+- 每个 `skills/*/SKILL.md` 的 frontmatter `name` 必须等于其目录名
+- 每个 `agents/*.md` 的 frontmatter `name` 必须等于其文件名（去 .md）
+- 全部文件中不得残留旧前缀（如 `yd-`、`yd:`、未改名的 `cm:` 命令引用）；**本条规则自身的示例文本不算残留**（实跑教训：v0.2.2 首次自测 grep 命中本文件的示例即误报）
+
+### 3. 命令间引用有效性
+
+- 所有文件中出现的 `/cm-plugin:{命令}` 引用 → `commands/cm-plugin:{命令}.md` 必须存在
+- 所有文件中出现的节点引用（N1–N8）→ `commands/cm-plugin-ai-nodes/` 下对应文件必须存在
+- cm-plugin:prd 引用的模式文件 → `commands/cm-plugin-prd-modes/{greenfield,brownfield,change-mode}.md` 三个必须齐全（v0.9.11 拆分产物,缺失即断链）
+- skill 之间的互相引用（如"→ cm-plugin-qa-engineer"）→ 目标必须存在
+
+### 4. 配套机制完整性
+
+- agent 与同工种 skill 成对：每个 `cm-X-agent` 必须有其加载的 skill
+- README 中的角色计数、目录树条目与实际文件一致
+- cm-plugin:prd 任务模板引用的产物（design-baseline、METRICS.md、RELEASES.md）在对应节点/skill 中有生成方
+- **rules 引用有生成方**：任何 skill/命令中引用的 `rules/{名称}.md`，必须在 cm-plugin:init 的「规则内容指引」（或 bootstrap 模板）中有对应生成条目——skill 读一个永远不会被生成的规则文件即为断链
+- **独立工具 skill 存在性**：cm-plugin:init/cm-plugin:prd/N8 引用了 `codebase-context` → `~/.claude/skills/codebase-context/SKILL.md` 必须存在；缺失报告为断链（旧包安装，提示重装）
+- **独立工具 skill 存在性（idea-to-prd）**：cm-plugin:idea 引用 `idea-to-prd` → `~/.claude/skills/idea-to-prd/SKILL.md` 必须存在；缺失同样报断链
+- **scout 凭证配对**：cm-plugin:scout 的 GO 对抗确认凭证（`scout-{名}-verdict-r1.md`）↔ 台账中结论为 GO 的行——台账有 GO 而报告目录无 verdict 凭证 → 报告为断链（GO 无对抗凭证 = 单模型自批）
+- **scout bakeoff 凭证配对**：cm-plugin:scout 模式 B 的对抗记录（`bakeoff-{YYYYMMDD}.md`）↔ 同目录 Codex 对抗凭证（`bakeoff-{YYYYMMDD}-verdict.md`）——有对抗记录而无 verdict 凭证 → 报告为断链（对抗结论无异源凭证 = 单模型自批）。此配对仅在选品报告目录存在时检查（该目录为用户产物区，非本仓库；本仓库内仅校验 cm-plugin:scout.md 对两文件名的引用一致）
+- **凭证/审批位链路配对**：N4 落盘的 `.reviews/` 凭证 ↔ N5 卡点与 N8 对账所引用的路径一致；cm-plugin:prd 写入的 `.cm-specs-status` ↔ N1 入口闸读取的文件名一致——四处引用两两配对（防单边改名断链）
+- **规则指引与模板配对**：cm-plugin:init「规则内容指引」中的每个条目 ↔ `~/.claude/templates/cm-plugin-rules/{名称}.md` 模板文件一一对应；缺模板报告为降级项（可运行但生成质量不稳定），多出的孤儿模板报告为未接线
+- **流程脚本配对**：命令中引用的每个 `~/.claude/templates/cm-plugin-scripts/{名称}.sh`（preflight/codex/log）↔ 实际脚本文件存在且可执行；缺失报告为降级项（命令会退化为手工执行）。当前引用点：N1 环境预检+Codex 封装、cm-plugin:rewrite R0、cm-plugin:scout 日志助手
+- **E2E harness 模板配对**：greenfield/skills 引用的 `~/.claude/templates/cm-plugin-e2e/{extension-harness.ts,smoke.spec.example.ts}` 存在；缺失报告为降级项（bootstrap T-005 会退化为 AI 手写 E2E，重踩 MV3 五坑）。引用点：greenfield bootstrap T-005、cm-plugin-qa-engineer/cm-plugin-extension-engineer skill
+
+### 5. 外部依赖可用性
+
+- **Codex（审查主通道）**：`codex --version` 探测。不可用报告为降级项并给出后果说明——N4 将落到对抗式子代理（次优），N1 开跑前还会再拦一次
+- 状态条已配置（settings.json 的 statusLine 指向 cm-plugin-statusline.sh）：未配置报告为提示项（不影响运行，仅少可视化）
+- 自动更新器（`~/.cm-plugin-workflow/cm-update.sh` 存在且 settings.json 的 SessionStart 挂载）：未配置报告为提示项（可选；配置后安装一致性由它每会话机械保障,本命令的版本检查退居兜底）
+- **安装版本**：读取 `~/.claude/templates/cm-plugin-VERSION` 并显示在结论首行。文件缺失 → 显示"版本: 未知（旧版安装，建议用最新包重装）"——版本混乱是实测踩过的坑，反馈问题必带版本号
+- **版本一致性（防混装/旧装）**：本命令文件自带基线号 → **框架版本基线: 0.5.0**（发包时与 VERSION 文件同步递增）。比对规则：
+  - 基线 = cm-plugin-VERSION → 一致，正常
+  - 基线 ≠ cm-plugin-VERSION 或 cm-plugin-VERSION 缺失 → **报"版本不一致/过旧"并建议重装**："命令文件 v{基线} / 安装标记 v{实际}——本机是混装或旧包，请用最新 zip 重跑 install.sh"（实测事故：公司机器旧包 + 家里新包，功能"消失"排查半天）
+
+## 输出格式
+
+```text
+🔍 cm-plugin:check 一致性自检  (安装版本: v{X.Y.Z} / 未知)
+
+角色存在性:   {N} 项检查 · {通过/断链清单}
+命名一致性:   {N} 项检查 · {通过/不一致清单}
+命令引用:     {N} 项检查 · {通过/失效清单}
+配套完整性:   {N} 项检查 · {通过/缺失清单}
+外部依赖:     {N} 项检查 · {Codex 可用/降级 · 状态条 已配/未配}
+版本一致性:   {一致 v{X.Y.Z} / ⚠ 不一致(命令 v{A} vs 安装标记 v{B}),请重装}
+
+结论: PASSED / {N} 处断链（逐条列出：文件:位置 → 期望 → 实际）
+```
+
+发现断链只报告不自动修——修复由人确认后执行。

package/workflows/cm-plugin/commands/cm-plugin:fix.md

@@ -0,0 +1,100 @@
+# /cm-plugin:fix — 缺陷修复小闭环
+
+**用法**：`/cm-plugin:fix {specs路径} {代码项目路径} 缺陷描述（现象/报错/截图均可）`
+
+修 bug 专用的**轻量闭环**——不走 N1–N8 全链（那是 feature 流程），也不许脱离工作流裸改（裸改没防护网没审查，修一个坏三个）。
+
+**多缺陷输入**：先对全部缺陷做第 1-2 步（复现+定位），**按根因聚类**——同根缺陷合并为一次修复（多个失败测试、一次改动、档案互链），修复顺序按严重度排,不按输入顺序。不聚类的代价：三个现象一个根因跑三个闭环,且第一个修复落地后,后两个的复现步骤可能已失效（第 1 步卡死）。
+
+**转交进场**（消费上游落盘物,不改上游流程）：缺陷描述可附上游档案引用——`/cm-plugin:refactor` 档案的未修缺陷清单、N6 业务走查报告的偏差项、观测闭环的半份档案（按 slug 在 `fixes/` 检索）。带引用进场的缺陷,第 1 步**采信上游已有证据**（位置/现象/日志原文）,仍须实际复现一次核实,但不从零摸排。
+
+**cm-plugin:ai 全局规则在本命令内同等生效**：灾难级才暂停、多方案自主决策留痕、状态落盘（node 写 `FIX`）、运行日志（事件照记）、Codex 纪律（装了就用）。
+
+## 闭环七步（每个缺陷）
+
+### 1. 复现（不能复现的 bug 不许修）
+
+- 按描述实际操作/运行一次，拿到**失败证据**（报错原文、错误截图、错误返回值）;**证据要用严格裁判**——宽容裁判会把坏产物蒙混成功（实跑:补丁类缺陷 GNU patch 的 fuzz 容错险些吞掉复现,换 git apply --check 才拿到硬证据）
+- 复现不了 → 不猜着修，走**观测闭环**（偶现 bug 专用，两段式）：
+  ① 在可疑路径加观测点（日志/埋点——观测点本身按最小改动+审查纪律入库，**观测点不是修复尝试**）
+  ② 缺陷档案先落半份，状态记 `观测中`，写清"等什么证据（哪个日志出现什么内容）"
+  ③ 本次命令正常收口退出，不挂着等——运行日志记 `done`,detail 写「观测中:等{什么证据}」;状态文件 state 复位,不留悬挂的 running
+  ④ 证据到手后再次运行 `/cm-plugin:fix` 附上证据，**按 slug 定位 `fixes/` 下的半份档案**,从第 2 步定位续跑,档案续写、状态改 `修复中`,运行日志记 `resume`(detail 注证据摘要)
+  ——**"我改了点东西你再试试"依然被禁止**
+
+### 2. 定位（先找根因，不是找改哪行能让现象消失）
+
+- 有业务地图（`docs/codebase-context/`）→ 先查 07 业务线路定位所在链路，08 修改影响映射表查波及面
+- 无地图 → 从失败点向上追调用链，找到**根因层**（现象在 UI，根因可能在数据层）
+- 输出一句话根因结论 + 波及面清单（本次修改会牵连哪些模块）——写进缺陷档案（第 7 步）
+
+### 2.5 根因与修法对抗确认（条件触发；根因错误是本流程最贵的错误,必须在防护网之前拦）
+
+任一**客观条件**命中才触发(简单缺陷零负担,判断依据同"门槛是客观项不是判断题"):波及面 ≥3 个模块 / 根因层与现象层不同层 / 观测闭环续跑的缺陷 / 拟走升级出口。
+
+- 把根因结论 + 复现证据 + 波及面清单 + **拟采用修法(含放弃的备选)** 交 Codex,提示词要义:"**假设这个根因判断是错的,找出更深层的解释;再审修法:治本还是治症?有没有更小的改动?会不会引入新耦合?**"——诊断和药方同轮审,零新增轮次(维护者要求:方案不能不审;简单缺陷由第 5 步事后审兜底)(Codex 未装走 N4 三级降级链,纪律同第 5 步)
+- **仅 1 轮**:推翻 → 回第 2 步重定位;分歧 → 交人裁决;通过 → 进第 3 步
+- 凭证落 `{SPECS_DIR}/.reviews/fix-{slug}-cause-r1.md`——**命名带 `cause` 是有意的**:不落入第 5 步 `fix-{slug}-r*.md` 的匹配域,两个卡点各自独立,根因凭证不会误满足 diff 审查卡点
+
+### 3. 防护网（先让 bug 有测试，再修）
+
+- **写一个能复现此 bug 的失败测试**（红）——它是"修好了"的客观定义，也是永久回归资产;**红的原始输出落进档案**(第 5 步审查要核对红证据,从未红过的测试转绿是空话)
+- 项目有存量测试 → 先跑一遍记录基线（修完对照，防止修 A 坏 B）
+- 写不了自动化测试的形态（如纯视觉）→ 截图/录屏留"修前"证据
+
+### 4. 修复（最小改动）
+
+- 只改根因层，**禁止顺手重构**（N3 同款纪律：看不惯的代码记 LESSONS 待触发备忘，事后走 `/cm-plugin:refactor`，不在修 bug 时动）
+- 修法有多个方案 → 自主决策选最优，`decision` 事件留痕
+- **升级出口**：定位发现是设计缺陷/需要跨模块大改 → **停止硬修**，报告根因并建议走 `/cm-plugin:prd --change` 变更模式立项——bug 命令不承接架构手术。**已建资产不弃**:第 3 步的失败测试保留入库（它是缺陷的客观复现,新方案转绿即验收）,档案状态记 `升级立项`,注明测试路径供立项后的流程直接接手
+
+### 5. 审查（Codex 纪律同 N4）
+
+- 失败测试转绿 + 存量基线不退化后，调 `codex:review` 审 diff（重点：根因是否真被修掉、有无只治了症状、波及面有无遗漏）
+- **防护网测试本身是审查对象**(实测最大问题类:测试是戏台):红的原因是否=该缺陷、断言测的是根因还是症状、有无安慰剂/前提共谋;**核对第 3 步落档的红证据**——没有红过的记录,测试可信度按不成立处理
+- 装了就用零豁免；未装/中途失效才走 N4 三级降级链；≤2 轮上限同样生效
+- **审查凭证落盘**：输出全文 tee 到 `{SPECS_DIR}/.reviews/fix-{slug}-r{轮次}.md`（纪律同 N4）——进第 6 步前**必须真跑** `ls {SPECS_DIR}/.reviews/fix-{slug}-r*.md`,命令无输出=审查未发生,退回补审;凭证文件名写进第 7 步收口输出（文字卡点拦不住是实测结论,机械命令才算数）
+
+### 6. 回归（按波及面，不是只看 bug 消失）
+
+- 跑第 3 步防护网测试（红→绿）+ 存量测试全量（对照基线）
+- 按第 2 步波及面清单逐项走一遍关键流（同 B2 口径：波及面=回归范围）
+- **回归失败的回路（显式分支,不许临场发挥）**：任何一项红 → 退回第 4 步重修,重修后**必须复审**且轮次并入第 5 步的 ≤2 轮总上限——上限耗尽仍打转 = 根因判断可疑,按升级出口处置,不许无限修-回归循环
+
+### 7. 落盘（审计链闭合）
+
+- **缺陷档案**：`{SPECS_DIR}/fixes/{YYYYMMDD}-{简短slug}.md`——现象 / 复现步骤 / 根因 / 修法（含放弃的方案）/ 波及面与回归结果 / 测试文件路径。这是缺陷知识库，同类 bug 再犯先查这里
+- **METRICS.md 追加一行**：Feature 列写 `fix`，任务列写档案文件名，其余列同口径（轮次/拦截数/人工介入）
+- 根因具普遍性（如"平台 API 返回结构变了"）→ 追记 LESSONS.md（[已结构化]/[仅记忆] 分级同 N5）
+- git commit：`fix: {一句话} (档案: fixes/xxx.md)`，审查摘要进 commit message（同 N4）
+- 运行日志事件：`task_start`/`review`/`task_done`/`done` 照记，node 字段写 `FIX`
+
+## 微缺陷快速通道（四个硬门槛全中才准走）
+
+**门槛是客观项不是判断题**——"感觉这个 bug 很小"不构成理由，四条全中才走，任一不中走完整七步：
+
+- [ ] 只改文案/样式/配置常量——**不新增、不修改任何条件分支与函数签名**
+- [ ] 单文件且 diff ≤ 10 行
+- [ ] 波及面为零（改动处无被其他模块引用的行为；有业务地图查 08 映射表核实）
+- [ ] 有截图/文案前后对照可作验收证据
+
+**快速通道可省**：第 3 步防护网测试、第 6 步全量回归（用前后对照截图代替）。
+**不可省**：Codex 审查（凭证照落）、缺陷档案（显式标注 `快速通道`）、METRICS 行（Feature 列写 `fix-lite`）。
+**快速通道的审查特化**:本道上 Codex 是唯一质量防线(防护网与全量回归都省了),审查**第一职责是复核四门槛**——diff 可直接验证项逐条验(行数 ≤10?单文件?零分支/签名变更?),波及面存疑即**打回走完整七步**。门槛是客观项,但自己量自己需要第二双眼睛。
+> fix-lite 的占比进运行日志——快速通道被滥用（占比异常高/出现分支改动混入）时收紧门槛，数据说了算。
+
+## 输出格式（每个缺陷收口时）
+
+```text
+🔧 缺陷闭环: {slug}
+根因: {一句话}
+修法: {一句话} | 放弃方案: {有则一句话,无则省}
+防护网: 新增 {测试文件}(红→绿) · 存量基线 {N} 项无退化
+审查: Codex {通过/N轮N条} | 回归: 波及面 {N} 项通过
+档案: fixes/{文件名}   METRICS 已记
+```
+
+## 边界
+
+- **不承接**：新功能（走 /cm-plugin:prd）、需求变更（走 /cm-plugin:prd --change）、架构级返工（升级出口交人立项）
+- specs 目录没有 fixes/ 子目录时自动创建；没有 specs 目录的裸项目也可用：档案落代码项目 `docs/fixes/`，**审查凭证落 `docs/fixes/.reviews/`**（第 5 步卡点同样生效），METRICS 跳过

package/workflows/cm-plugin/commands/cm-plugin:idea.md

@@ -0,0 +1,29 @@
+# /cm-plugin:idea — 点子 → PRD（流程上游入口，非 N1–N8 步骤）
+
+**用法**：`/cm-plugin:idea 一句话点子`（如 `/cm-plugin:idea 我想做个自动整理浏览器标签页的插件`）
+
+把模糊想法聊成成熟 PRD 的产品访谈搭档。**本命令只做一件事**：加载 `~/.claude/skills/idea-to-prd/SKILL.md` 并严格按其规则执行——本文件不复制不改写技能规则，技能文件是唯一事实源。
+
+## 执行
+
+1. 读取 `~/.claude/skills/idea-to-prd/SKILL.md`，未安装则提示重装最新包后中止
+2. 把 `$ARGUMENTS` 作为用户点子，进入技能的访谈流程（判定产品类型 → 一次一题 → L1 骨架 → 按用户节奏加深；涉及交易/Web3 自动加载 `references/domains/trading.md` 领域包）
+3. 全程遵守技能自身纪律（一次一题、防诱导选项、狠收敛、纯对话不联网）
+
+## 与 cm 流程的衔接（只提示，不自动执行）
+
+PRD 聊到用户满意收尾时，**追加一段提示**（这是本命令相对裸技能唯一的增量）：
+
+```text
+📄 PRD 已保存: {路径}(成熟度 {L1/L2/L3},「待明确的问题」剩 {N} 条(口径:只数 PRD 第 7 节的条目,正文散落的待补标记不计;路径用绝对路径)——带着未决问题交棒,prd 的产品角色会重新追问;想少被问就先在这里加深)
+下一步(需要你手动执行,本命令不代跑):
+  1. 建 specs 文件夹,把这份 PRD 放进 docs/
+  2. /cm-plugin:prd {specs路径}   ← 拆成规格三件套
+  3. 人审摘要卡后 /cm-plugin:ai 开始开发
+```
+
+## 边界
+
+- 不写代码、不拆任务、不调 /cm-plugin:prd——想法阶段结束就交棒
+- 已有现成需求文档的项目不需要本命令，直接 `/cm-plugin:prd`
+- 触发词自然唤起（"我有个点子…"）与本命令等效，习惯哪个用哪个

package/workflows/cm-plugin/commands/cm-plugin:init.md

@@ -0,0 +1,145 @@
+# /cm-plugin:init — 项目 .claude 初始化
+
+你是一个项目配置初始化助手。你的任务是在当前项目目录中创建 `.claude/` 文件夹及其完整配置结构。
+
+## 空目录检测（前置）
+
+当前目录为空（无项目描述文件且无源码）→ **本命令不适用，不自行搭脚手架**。提示用户：
+
+> "这是空目录——/cm-plugin:init 服务于已有项目。全新插件请走 0→1 分支：建 specs 文件夹放入需求文档后运行 `/cm-plugin:prd {specs路径}`，那里会基于需求推荐扩展脚手架（WXT / Plasmo / CRXJS 等），脚手架与规范生成都由 bootstrap 任务完成。"
+
+## 执行步骤
+
+### 1. 分析项目
+
+在生成任何文件之前，先全面分析当前项目：
+
+- 读取 `package.json`、`Cargo.toml`、`go.mod`、`pyproject.toml`、`pom.xml` 等项目描述文件，判断语言和框架
+- 扫描目录结构（重点关注 `src/`、`app/`、`lib/`、`tests/`、`migrations/` 等）
+- 读取现有的 README、CI 配置、lint 配置、tsconfig 等，提取构建/测试/运行命令
+- **识别扩展形态**：定位 manifest（源文件或 wxt.config / plasmo 约定生成），记录 manifest 版本、脚手架（WXT / Plasmo / CRXJS / 原生）、已用的表面（service worker / content_scripts / popup / options / side_panel）与权限清单
+- 识别项目是否附带配套后端 API、共享包等模块
+- **检测版本控制状态**（结果写入 CLAUDE.md 的「版本控制」字段，全流程据此降级）：
+  - 有 git 且有 remote → `remote`；有 git 无 remote → `local`（不询问，直接记录）
+  - **无 git → 询问用户一次**："初始化本地 git？（推荐——每任务提交与审计链依赖它）/ 不使用版本控制"
+  - 用户拒绝 → 记 `none`：不生成 git-workflow.md、后续 N5 跳过提交、doc-syncer 用文件扫描、hook 不适用、审计链降级为 METRICS + tasks 勾选
+
+### 1.5 代码库参考文档（自动判断，不询问）
+
+**前置**：`~/.claude/skills/codebase-context/` 未安装 → 跳过本步并提示"codebase-context skill 未安装(旧版包),业务地图功能不可用,建议用最新包重装"——不阻塞 init 其余步骤。
+
+按下列条件**自动决策**是否执行 `codebase-context` scan，不问用户，执行后在输出中汇报判断依据（形态判断优先于文件数）：
+
+- 项目**无任何项目描述文件**（package.json/Cargo.toml/go.mod/pyproject.toml/pom.xml 等）**且无 src/ 类源码结构**（如纯 prompt/文档资产库、纯配置仓库）→ **跳过**——scan 的七轮抓取目标（api/types/components/store）在此类形态下均不存在，产出多为空章节（v0.9.24 实跑教训：60 个 md 的 prompt 仓库按文件数会误判全量扫）
+- 源码文件 > 30 个 且 `{项目根}/docs/codebase-context/` **不存在** → 自动执行**全量 scan**（存量项目首扫，生成业务地图）
+- 参考文档目录**已存在** → 自动执行**增量 scan**（顺手保鲜，成本极低）
+- 源码文件 ≤ 30 个 且 无参考文档 → **跳过**（小项目直接读代码更快，建地图不划算）
+
+输出格式（四选一）：`📚 业务地图: 已全量生成(源码{N}个) / 已增量刷新(变更{N}个) / 跳过(小项目,源码仅{N}个) / 跳过(形态不适用,无项目描述文件)`
+
+**判定结果落盘**：把同一行写入**代码项目根**（即 scan 的 PROJECT_ROOT，多层仓库下不是仓库根）的 CLAUDE.md「业务地图」字段；该处无 CLAUDE.md → 写入地图 `00-index.md` 头部并在输出中说明落点——/cm-plugin:prd 据此直接行动，不重复判断、不重复建议（实测教训：25 文件的临界项目，init 说跳过、prd 又建议 scan，两处判断打架）。
+
+### 2. 生成文件结构
+
+根据分析结果，生成以下结构（只创建与项目相关的文件）：
+
+```
+.claude/
+├── CLAUDE.md                    # 项目门面，≤150 行
+├── rules/
+│   ├── coding-style.md          # 命名/缩进/import/注释规范
+│   ├── testing.md               # 测试约定、覆盖率要求
+│   ├── security.md              # 禁止事项、密钥处理
+│   ├── git-workflow.md          # 分支/commit/PR 规范
+│   ├── chrome-extension.md      # 扩展铁律：权限最小化/MV3 约束/禁远程代码（插件项目必建）
+│   ├── frontend.md              # (如有 UI 表面) popup/options/side panel 的组件规范
+│   └── backend-api.md           # (如有配套后端) paths: server/**, api/**
+```
+
+### 3. CLAUDE.md 模板
+
+CLAUDE.md 必须包含以下部分，控制在 150 行以内：
+
+```markdown
+# {项目名}
+
+{一句话简介}
+
+## 技术栈
+
+- 语言: {lang}
+- 框架: {framework}
+- 包管理: {pkg manager}
+- 版本控制: {remote | local | none}   # /cm-plugin:ai 各节点据此执行或降级 git 操作，不再重复询问
+- 交付形态: Chrome 扩展 (MV3) · {表面组合,如 side panel+content script} · {目标浏览器}   # 架构第一分叉，涉表面/浏览器的需求变更必须过人工确认
+- 扩展脚手架: {WXT | Plasmo | CRXJS+Vite | 原生}
+- 业务地图: {已全量生成 {日期} | 跳过(小项目,{N}文件) | 未初始化}   # codebase-context 判定结果，/cm-plugin:prd 据此行动不再重复询问
+
+## 常用命令
+
+- 安装依赖: `{install cmd}`
+- 开发运行: `{dev cmd}`
+- 构建: `{build cmd}`
+- 测试: `{test cmd}`
+- Lint: `{lint cmd}`
+
+## 目录结构
+
+{树形结构速览，只列关键目录，不超过 20 行}
+
+## 规则
+
+@rules/coding-style.md
+@rules/testing.md
+@rules/security.md
+@rules/git-workflow.md
+@rules/chrome-extension.md
+{以下按需引入}
+@rules/frontend.md
+@rules/backend-api.md
+```
+
+### 3.5 生成即核验(机械,写入前执行)
+
+生成的 CLAUDE.md 与 rules 中**所有可执行断言逐条实证**,核验不过的条目不许静默写入(修正或显式标注「未验证」):
+
+- 命令类(install/dev/test/lint/build):验证脚本真实存在(读 manifest scripts / Makefile),可安全 dry 的实跑一次
+- globs 类:实测匹配非空——匹配零文件的 glob 是死规则
+- 文件引用类(@rules/xxx、路径):存在性检查
+
+> 依据:实跑事故——init 生成的 testing.md 写了 Node 24 下已失效的 `node --test tests/`,带病上岗直到任务踩上去才发现。能机械验的绝不靠嘴(凭证卡点同款基因)。
+
+### 4. rules 文件格式
+
+每个 rules 文件使用以下格式：
+
+```markdown
+---
+description: { 规则一句话描述 }
+globs: { 可选，如 "src/web/**" }
+---
+
+# {规则标题}
+
+{具体规则内容，从项目实际配置中推断，简洁明了}
+```
+
+### 5. 规则内容指引
+
+**生成方式**：每个 rules 文件优先以 `~/.claude/templates/cm-plugin-rules/{名称}.md` 的模板骨架为基础——遵守模板头部的四原则（可执行 / Bad-Good 对比 / 量化 / 现代实践），将所有 `{占位符}` 替换为从项目实际推断的内容，删除不适用章节。模板不存在时按下方各条目描述自行生成（老安装降级路径）。
+
+- **coding-style.md**: 从 eslint/prettier/editorconfig/rustfmt 等配置推断命名风格、缩进、import 排序、注释规范。如无配置则根据语言社区惯例设定。
+- **testing.md**: 从测试框架配置和现有测试推断测试规范、文件命名、覆盖率要求。
+- **security.md**: 列出禁止硬编码密钥、环境变量处理、敏感文件 .gitignore 规则等。
+- **git-workflow.md**: 从 git 历史推断 commit 风格（conventional commits?），分支命名规范，PR 流程。**按版本控制字段裁剪**：`none` → 不生成本文件；`local` → 裁掉 PR/远程/保护分支章节，只留 commit 规范。
+- **chrome-extension.md**: 扩展开发铁律——权限最小化与申请理由留档、MV3 约束（service worker 无 DOM 且会休眠、禁 eval/远程代码）、上下文间消息契约集中管理、manifest 变更单独提交（插件项目必建，以模板为骨架 + 项目实际权限清单填充）。
+- **frontend.md**: popup/options/side panel 的组件规范、状态管理、样式约定；content script UI 的宿主页样式隔离（shadow DOM / CSS 前缀）（仅当项目有 UI 表面时创建）。
+- **backend-api.md**: API 设计规范、错误处理、中间件约定、扩展侧调用的 CORS 与鉴权约定等（仅当项目有配套后端时创建）。
+
+## 重要约束
+
+- 如果 `.claude/` 已存在，先告知用户并询问是否覆盖
+- 所有规则内容必须基于项目实际情况推断，不要生成空洞的通用规则
+- CLAUDE.md 严格控制在 150 行以内
+- 只创建与项目实际相关的 rules 文件，不要创建不适用的文件
+- 生成完成后，列出所有创建的文件并给出简要说明