| name | plan-prd-feature |
| description | ⭐显式触发的【增量需求规划器】（MVP 已交付后做功能迭代用）。触发后【第一动作必须 call EnterPlanMode 工具】（不许先做任何其他动作）。plan 内：规范体检 → 锁基线（status/gates/prd 历史）→ codegraph 四路侦察（explore 读现状 + impact 算传递闭包半径 + files 对账目录 + affected 算测试面，前置新鲜度保险）→ 需求逐点三态判定（已实现/无冲突/有冲突）→ 冲突逐条硬门控裁决 → 输出三件套（逻辑图+原型双联+带落盘路由的差异表）→ 逐点循环至通顺 → 主人验收后 ExitPlanMode → 按层路由分批切角色落盘。⛔禁批量决策清单、禁塞单一文件、禁用 codegraph 生成 L1/L2/L4、禁碰 gates.md 与代码。不找 bug、不写代码。 |
| allowed-tools | Read, Write, Edit, Bash, Glob, Grep, EnterPlanMode, ExitPlanMode, ToolSearch, mcp__codegraph__codegraph_explore, mcp__codegraph__codegraph_search, mcp__codegraph__codegraph_node, mcp__codegraph__codegraph_callers |
| disable-model-invocation | true |
/cc-code:plan-prd-feature — 增量需求规划器（第一动作即 plan 模式）
⭐⭐⭐ 触发后第一动作 = call EnterPlanMode 工具。
所有体检 / 侦察 / 三件套 / 交谈都在 plan 模式内做，没有 plan 外窗口。
适用场景：MVP 已交付，在既有实现上做功能迭代。 0→1 定全量请用 /cc-code:plan-prd-mvp。
⛔ 六条铁律（违反任一即本次规划无效）
铁律 1：第一动作 call EnterPlanMode
触发后，在 call EnterPlanMode 之前，不许做任何动作：
- ❌ 不许先 Read
Agent.md / status.md
- ❌ 不许先 codegraph 探测
- ❌ 不许先输出三件套
- ❌ 不许先输出「请主人审阅决策清单」
- ✅ 唯一允许的第一动作：call
EnterPlanMode 工具
铁律 2：codegraph 只准校准 L3，永不许生成 L1 / L2 / L4
这是插件信息流铁律，本 skill 最易踩的坑 —— 迭代场景下代码已存在，AI 会本能地"读代码推需求"，那是需求层被实现层反向污染。
codegraph 的产出只许流向三处：
✅ 判定「已实现 / 未实现」 —— 纯事实陈述
✅ 算改动爆炸半径（impact / callers） —— 纯事实陈述
✅ 校准 L3 契约的实现状态标记 —— Architect 契约纪律授权
⛔ 绝不许反推「所以需求应该是 X」 —— L1 唯一来源 = 主人的话
⛔ 绝不许反推「所以断言应该是 Y」 —— L1 / L4 禁生成
⛔ 绝不许反推「所以界面应该长 Z」 —— L2 唯一来源 = 主人的话
新需求的逻辑与原型只能从【与主人的对话】长出来。
codegraph 只提供「现状那一半」，用于双联对比与冲突取证。
铁律 3：契约漂移禁沉默
codegraph 撞出「代码 ≠ active/api.md / active/data.md 契约」时，立即停下逐条请主人二选一：改代码回归契约 / 修契约并记录。禁止默默按代码算、也禁止默默按契约算。
铁律 4：禁批量决策清单
⛔ 禁止「全量输出决策清单，可全量接受 / 逐项修订 / 否决某项」。
必须逐点提问：一次只问一个模糊点或一条冲突，等主人答，再问下一个。
铁律 5：禁塞单一文件
⛔ 禁止把所有产出一股脑写进 active/prd.md。必须按内容性质路由到对应层的文件，一层一文件一角色（见「五、落盘路由表」）。
铁律 6：越权红线
⛔ active/gates.md —— QA 唯一域，本 skill 绝不写
⛔ src/ 与测试目录 —— Dev 唯一域，本 skill 绝不写
⛔ active/Agent.md 权限路由表 —— 人的域，一个字不许动
✅ active/Agent.md「当前激活角色」一行 —— 仅在主人当场确认后代笔改
一、生命周期总览
触发 /cc-code:plan-prd-feature "<新需求>"
│
Step0 ⭐ call EnterPlanMode（第一动作，Write/Edit 当场锁死）
│ ══════════════ 以下全程 plan 模式内（只读 + 文字输出）══════════════
Step0.5 规范体检门
│ 项目 active/Agent.md ⟷ 插件规范比对
│ 宪法比规范薄 → ⚠️提醒升级，不阻断，按插件规范推进
│ 目录形态偏离 → ⛔停手，要求先跑 /cc-code:init
│
Step1 基线锁定（只读，守上下文最小化）
│ Agent.md → 锁角色权限路由表
│ status.md → 里程碑=已开发 · 下一步=已规划未开发 · Blockers
│ prd.md → 章节标题 + 模块清单 + 断言最大编号 + Out of Scope
│ gates.md → 已 PASS / FAIL / UNVERIFIABLE / ESCALATE
│
Step2 codegraph 侦察（受铁律 2 约束，只取事实）
│ ⓪ 新鲜度保险 → status --json：pendingChanges 非 0 则先 sync
│ ① explore(需求原话) → query(实体名) → node(读符号)
│ ② impact(核心符号) → 传递闭包真半径（比 callers 一层准）
│ ③ files → 目录树现状 ⟷ project.md §三 目录规约 对账
│ ④ affected(涉及文件) → 测试影响面，写进差异表
│ 顺手撞契约漂移 → 触发铁律 3
│
Step3 需求逐点三态判定（禁悬空，每点必须落格）
│ ✅已实现 / ⚪未实现无冲突 / ⛔未实现有冲突
│
Step4 冲突逐条硬门控（一次一条，四选一，未裁决完禁 ExitPlanMode）
│
Step5 输出三件套（ascii）
│ ① 逻辑图 ② 原型双联 ③ 差异表（带落盘路由列）
│
Step6 逐点循环至通顺（⛔禁批量决策清单）
│ 否 → 问下一个 → 回 Step5 刷新
│
Step7 三门齐开才 call ExitPlanMode
│ ══════════════ 退出 plan 模式 ══════════════
Step8 按层分批切角色落盘（PM 批 → Architect 批）
│
Step9 顺手更新 status.md 坐标 → 提示走 /cc-code:agent-to-mvp
二、Step0.5 规范体检门
以插件规范为唯一标尺，项目 .cc_code/ 的形态不作为依据。
| 体检项 | 规范态（templates/Agent.md） | 缺失时的动作 |
|---|
| 文件分层表 | L0~L4 五层 + 唯一写者 | ⚠️提醒升级，缺的按规范当默认生效 |
| 信息流铁律 | L1→L2→L3→代码，L4 只拿 L1/L2 当尺子 | ⚠️同上 |
| codegraph 纪律 | 只准校准 L3，永不生成 L1/L2/L4 | ⚠️同上（本 skill 无论如何强制生效） |
| PM 两产物边界 | prd.md 规则 / ux.md 界面；断言 A 序列永久稳定 | ⚠️同上 |
| Architect 契约纪律 | 契约漂移禁沉默 | ⚠️同上 |
| QA 灰盒定义 | 需求只来自 L1/L2/api，代码永不重定义需求 | ⚠️同上 |
提醒话术（命中任一即报，只报一次，不啰嗦）：
⚠️ 本项目 .cc_code 为旧版形态，缺 <项>。
建议：/plugin update cc-code → 重跑 /cc-code:init 升级
本次规划仍按插件规范推进。
目录形态偏离 → 停手（防写坏文件）：
规范路径缺失（如无 active/ux.md、prd.md 不在 active/ 下、L3 三件缺项）
⛔ 停：「规范路径 <X> 不存在，请先跑 /cc-code:init 归正目录形态，
否则增量章节会落错文件造成版本冲突。」
→ 仅当主人明示「就落 <实际文件>」才落，落完再提醒一次升级
二·五、Step2 codegraph 侦察规格（0.10.0 扩容）
受铁律 2 约束：本步只取事实，一个字都不许流向 L1 / L2 / L4。
CLI 未装 → 全步降级为 Glob / Grep 表层扫描，并在三件套里标注「半径为估算」。
⓪ 新鲜度保险（必做第一件事）
codegraph status --json
pendingChanges 非 0 → 先跑一次 codegraph sync 再侦察
为什么: daemon 空闲 5min 自杀, 期间的改动无人追写。
catch-up 只在 daemon 复活时跑, 存在「拿到旧数据」的竞态窗口。
规划阶段读到旧索引 → 半径算错 → 冲突漏判, 代价最大。
initialized:false → 报一行, 本次降级为表层扫描（⛔ 不自动重建）
①~④ 四路侦察（各有分工，不可互相替代）
| 序 | 能力 | 回答什么 | 产出流向 |
|---|
| ① | explore → query → node | 「这块现在怎么实现的」 | Step3 三态判定的「已实现」判据 + 原型双联的「现状」那一半 |
| ② | impact <核心符号> | 「改它会炸到哪」传递闭包 | 差异表「爆炸半径」列 |
| ③ | files | 「目录树现状」 | 与 project.md §三 目录规约对账，偏离即触发铁律 3 |
| ④ | affected <涉及文件> | 「该补/该跑哪些测试」 | 差异表「测试影响」列，供 Dev 段落地 |
② 为什么必须用 impact 而非只用 callers：
callers 只回答「谁直接调它」 —— 一层
impact 回答「改它的传递影响面」 —— 闭包（depth 默认 2，可调）
一层视野会把跨层级的连带改动漏掉 → 半径估小 → 规划时以为「改一处」
实际动到五处 → Dev 段爆炸 → 返工。两者并用: impact 定面, callers 定点。
④ affected 返回空的处置（报一行，不做前置检测）：
① 测试代码是否被 .gitignore 屏蔽（被 ignore 则不进索引）② 测试是否 import 被测源码（纯 HTTP 型无 import 边）③ 命名是否需 --filter "<project.md §六 登记的 glob>"。
三、Step3 三态判定与冲突源
每个需求点必须落进一格，禁悬空、禁一点跨两格（跨了就是需求点没拆够，先拆）。
┌──────────────┬─────────────────────────────────────────────┐
│ ✅ 已实现 │ codegraph 找到等价实现 │
│ │ → 报「已有，位置 <file:line>」，问主人是否改口径│
├──────────────┼─────────────────────────────────────────────┤
│ ⚪ 未实现无冲突│ 不与任何已 PASS 断言 / 规则 / Out of Scope 抵触│
│ │ → 直接进新增逻辑 │
├──────────────┼─────────────────────────────────────────────┤
│ ⛔ 未实现有冲突│ 与下表任一冲突源抵触 → 押进 Step4 │
└──────────────┴─────────────────────────────────────────────┘
冲突源必扫八处，一处不许跳：
| # | 冲突源 | 在哪查 | 层 |
|---|
| 1 | 已 PASS 验收断言 | active/gates.md 实测结果 | L4 |
| 2 | 模块核心规则 R | active/prd.md 逐模块规格 | L1 |
| 3 | 全局规则 G | active/prd.md 全局规则 | L1 |
| 4 | 明确不做 | active/prd.md Out of Scope | L1 |
| 5 | 已作废/已删功能 | active/prd.md 的 ~~作废~~ 断言 + 各文件文末变更台账（顺台账链翻 docs/plans/F-n-*.md 的冲突收敛表） | L1 |
| 6 | 交互五态 | active/ux.md 五态矩阵 | L2 |
| 7 | 数据契约 | active/data.md interface ↔ DB 列 | L3 |
| 8 | 接口契约 + 架构决策 | active/api.md / active/project.md Needs Decision | L3 |
四、Step4 冲突硬门控
一次只摆一条，四选一，未拿到裁决禁止进 Step5：
⛔ 冲突 n/N 待裁决
旧：<来源文件 §章节> <旧值原文>
新：<需求点>
四选一：
[1] 覆盖旧值 → 旧断言号加 ~~删除线~~ + 注明被谁取代，绝不重排绝不复用
[2] 新旧共存 → 必须给出可判真假的分支判据，模糊判据不算裁决
[3] 放弃新需求 → 本条移出范围，写进 prd.md Out of Scope
[4] 延后 → 写进 prd.md 待澄清，不进本次断言
五、落盘路由表（唯一权责边界）
⛔ 落盘第一纪律：就地收敛，禁追加章节
active = 最新 + 最完整 + 最纯净
❌ 旧协议(0.8.0 及以前): 各层文件尾部新开「## 增量 F-n」章节
→ N 次增量后, 同一个 interface / path / 规则 散成 N 段补丁
→ Dev 得读 N 处自行拼接才知道「现在长什么样」
→ active 行数随迭代线性膨胀, 且无收敛出口
✅ 新协议(0.9.0 起): 就地改写 + 台账留痕 + 过程外置
├─ 变更内容 ──► 直接改写 active 里对应小节（原位覆盖）
├─ 新断言 ──► 续编进 prd.md §1.5 主表 / ux.md §2.3 矩阵
├─ 过程产物 ──► docs/plans/F-n-<需求名>.md
├─ 变更留痕 ──► 各文件文末「变更台账」追加 1 行
└─ 历史版本 ──► 靠 git（.cc_code 已在版本控制内，不另存快照）
写入前三问（任一不通过即停手重判）：
| # | 自查 | 不通过怎么办 |
|---|
| 1 | active 里已有对应小节吗？ | 有 → 就地改写，⛔ 禁新开章节 |
| 2 | 这段在回答「现在是什么」吗？ | 不是（是「当时怎么决定的」）→ 落 docs/plans/ |
| 3 | 别的层已经有了吗？ | 有 → 不写，只留指针（跨层唯一源） |
落哪个文件、写什么
| 层 | 规范文件 | 唯一写者 | 本 skill 落什么（就地改写） | 绝不写 |
|---|
| L1 | active/prd.md | PM | 模块规则（改写对应模块小节）· 验收断言 A 序列续编进 §1.5 主表 · 业务状态机 | 线框、字段类型、接口参数、增量章节 |
| L2 | active/ux.md | PM | 视觉规格（改写对应页面小节，只留目标态）· 交互五态矩阵 U 序列续编 · 组件清单 | 业务规则、字段类型、增量章节 |
| L3 | active/project.md | Architect | 架构决策 · 技术选型 · 目录（改写对应章节） | 需求、线框、增量章节 |
| L3 | active/data.md | Architect | 数据契约（改写该 interface / 该表小节） | 需求、线框、增量章节 |
| L3 | active/api.md | Architect | method / path / 入参 / 出参 / 错误码（改写该 path 小节） | 需求、线框、验收断言、增量章节 |
| — | docs/plans/F-n-<需求名>.md | 本 skill | ⭐过程产物集中地：需求清单 R · 冲突收敛表 · 裁决记录 · 契约漂移登记 · 迁移检查清单 · 现状态原型 · 待澄清 | 当前态规格（那些进 active） |
| L0 | active/status.md | 当前角色 AI | 坐标 + 下一步（规范协议第 4 条授权顺手写） | 里程碑（QA PASS 后才写） |
| L0 | active/Agent.md | 人 | ⛔ 仅代笔改「当前激活角色」一行 | 权限路由表任何一字 |
| L4 | active/gates.md | QA | ⛔ 绝不碰 | — |
| — | src/ + 测试目录 | Dev | ⛔ 绝不碰 | — |
判据速查： 能脱离界面存在的 → L1；离开界面就没意义的 → L2；只有工程师关心的 → L3；回答「当时怎么决定的」→ docs/plans/。
增量批次号（F-n）： 读各层文件**文末「变更台账」**已有最大 F-n → 本次取 F-(n+1)。同一需求在所有命中文件用同一个 F 号，台账行 + docs/plans/F-n-*.md 共同构成跨文件追溯链。
⚠️ 台账不是章节：台账是文末一张表，每次增量只加一行（F 号 / 日期 / 改了什么一句 / 冲突裁决 / 详情链接）。它顶替旧协议里 ## 增量 F-n 章节的追溯职能，代价从数十行降到 1 行。
三件套的落盘去向（避免重复，守 DRY）：
| 三件套 | 落哪 | 说明 |
|---|
| ① 逻辑图 · 业务状态机 | L1 prd.md（改写对应模块状态机段） | 业务流转 |
| ① 逻辑图 · 页面流转 | L2 ux.md（改写对应页面五态段） | 交互五态 |
| ② 原型双联 · 目标态 | L2 ux.md（覆盖原页面线框） | 只留目标态 |
| ② 原型双联 · 现状态 | docs/plans/F-n-*.md | 服务裁决留档，不进 active |
| ③ 差异表 / 冲突收敛表 | docs/plans/F-n-*.md | ⭐改动点：不再进 prd.md，避免 active 堆历史 |
六、Step7 出关三门（缺一不许 ExitPlanMode）
| 门 | 判据 |
|---|
| 门 1 | 所有冲突均已拿到主人四选一裁决 |
| 门 2 | 三件套已输出，且主人明确说验收通过（沉默 / "嗯" 不算） |
| 门 3 | 差异表每一行都填了「落盘文件」+「权责角色」，无空格 |
通顺三判据（Step6 循环的收敛条件）：
- 逻辑通顺 —— 每条流转有明确触发与结果，无悬空分支、无孤儿状态
- 配置通顺 —— 新增配置项有默认值 / 取值范围 / 生效时机
- 断言可判真假 —— 禁「优化 / 友好 / 更好 / 提升体验」等无法判真假的词
七、Step8 分批切角色落盘
8.1 从差异表聚合批次：角色 → 待落文件（按 PM → Architect 顺序，严守串行）
8.2 ⭐先落过程产物（无需切角色，docs/ 不属任何角色专属域）：
└─ 写 docs/plans/F-n-<需求名>.md：需求清单 R · 冲突收敛表 · 裁决记录
· 契约漂移登记 · 迁移检查清单 · 现状态原型 · 待澄清
8.3 for 每个批次：
├─ 报本批：角色 / 文件清单 / 每文件**要改写哪个小节**
├─ 请示主人：「确认切到 <角色>？」 ⛔ 未确认不许动任何文件
├─ 主人确认 → Edit active/Agent.md「当前激活角色」→ <角色>（只改这一行）
├─ 重新 Read active/Agent.md 加载新权限表
├─ 校验：本批文件 ⊆ 该角色【可写】域？越界即停并报错，绝不硬写
├─ ⭐就地收敛写入（过写入前三问）：
│ ├─ 有对应小节 → Edit 改写该小节（原位覆盖）
│ ├─ 无对应小节 → 在该文件**语义正确的位置**新建小节（不是文件尾巴）
│ ├─ 新断言 → 续编进 prd.md §1.5 主表 / ux.md §2.3 U 矩阵
│ └─ ⛔ 禁新开「## 增量 F-n」章节
├─ 文末「变更台账」追加 1 行（F 号 / 日期 / 改了什么 / 裁决 / docs/plans 链接）
└─ 报本批产物清单（含「改写了哪些小节」明细，便于主人核对）
8.4 落完报「Dev / QA 域未动」，提示主人走 /cc-code:agent-to-mvp
⭐ 就地改写 ≠ 丢历史：.cc_code 在 git 内，git log -p active/prd.md 即完整变更史。台账行 + docs/plans/F-n-*.md 提供语义级追溯。三者叠加，比堆积增量章节更完整且不污染 active。
⚠️ 切角色前严禁预读下一角色的禁读文件 —— 侦察阶段（Step1/Step2）的全域只读是具名例外，落盘阶段必须回到严格角色权限。
八、与 plan-prd-mvp 的分工
| 维度 | plan-prd-mvp | plan-prd-feature（本 skill） |
|---|
| 场景 | 0→1 定 MVP 全量 | MVP 已交付，功能迭代 |
| 基线 | 粗探项目 | 硬锁 status + gates + prd 历史 + 断言最大号 |
| 代码理解 | Glob / Grep 表层 | codegraph 四路侦察：explore/node 读现状 · impact 算传递闭包半径 · files 对账目录 · affected 算测试面（受铁律 2 约束） |
| 冲突处理 | 无（首版无历史） | 八处冲突源 + 逐条硬门控裁决 |
| 契约漂移 | 不涉及 | 撞出即停，逐条二选一 |
| 产出 | 覆写 prd.md（旧版归档 backup/） | 就地收敛改写命中层文件对应小节 + 台账 1 行 + 过程落 docs/plans/ |
| 落盘层 | 仅 L1 | L1 + L2 + L3 动态命中 |
| 角色 | 单一 PM 域 | PM 批 → Architect 批，逐批请示切换 |
| 断言 | A1..An 全新 | A 序列续编进 §1.5 主表，作废加删除线；UI 侧 U 序列续编进 ux.md §2.3 |
| 出关 | 逻辑+配置通顺 | 通顺 且 冲突全裁决 且 主人明确验收 |
九、关键约束速查
| 约束 | 说明 |
|---|
| ⭐ 第一动作 call EnterPlanMode | 触发后不许先做别的 |
| 无 plan 外窗口 | 体检/侦察/三件套/交谈全在 plan 内 |
| 规范唯一源 = 插件 | 项目 .cc_code 形态不作依据；落后即提醒升级 + 重跑 /cc-code:init |
| codegraph 只校准 L3 | 永不生成 L1/L2/L4 |
| 契约漂移禁沉默 | 逐条二选一 |
| ⛔ 禁批量决策清单 | 一次一个模糊点 |
| 冲突未裁决完禁出关 | 硬门控 |
| ⛔ 禁塞单一文件 | 按层路由，一层一文件一角色 |
| ⛔ 禁追加增量章节 | 就地收敛改写对应小节；过程落 docs/plans/；台账 1 行留痕 |
| 切角色须请示 | Agent.md 只许改「当前激活角色」一行 |
| plan 内只读 | 一切写入等 ExitPlanMode 后 |
| 不找 bug | bug 是 QA 职责 |
| 不写代码 | 代码是 Dev 职责 |
十、与主线的关系
plan-prd-feature（支线） cc-code 主线
────────────────────── ──────────────────────
Step0 EnterPlanMode /cc-code:agent-to-mvp
Step0.5 规范体检 ├─ PM（细化 L1/L2）
Step1-2 基线 + codegraph 侦察 ├─ Architect（补齐 L3）
Step3-4 三态判定 + 冲突裁决 ├─ Dev（编码）
Step5-6 三件套 + 逐点交谈 └─ QA（验收 → gates.md）
Step7 ExitPlanMode approve
Step8 分批切角色落 L1/L2/L3 ────► /cc-code:whole-qa（收口全量验收）
Step9 status.md 坐标 + 提示下一步
十一、触发后首步动作
⭐ 第一个动作：call EnterPlanMode 工具。不许先做任何其他事。
进入 plan 模式后，按 Step0.5 → Step9 执行。
