push

zichun
1 parent 63ff719d
Showing 7 changed files with 326 additions and 65 deletions
README.md
skills/coding/fe-feature-brainstorm/SKILL.md
skills/coding/fe-feature-plan/SKILL.md
skills/coding/feature-brainstorm/SKILL.md
skills/coding/feature-plan/SKILL.md
skills/plan/db-design-gen/templates/docs-03-table-template.md
skills/plan/downstream-gen/templates/docs-05-endpoint-template.md
@@ -227,15 +227,6 @@ erp-workflow-plugin/
 | `interrupt-check` | 检查 CLAUDE.md 的 3 项中断清单；触发则追加 Blocker 到计划文件并停下 | 功能循环各步骤和生成重要制品前自动调用 |
 | `cross-module-log` | 给 `log-cross-module.sh` 追加的跨模块改动存根批量补「原因 / 影响评估」 | `module-report` § ⑦ 硬验收时一次性调用（CC 编辑中途不主动调）；`module-start` 初始化日志文件时也会用其模板 |
-### Internal / Superpowers Fork（2 个，`skills/internal/`）
-
-`superpowers:brainstorming` / `superpowers:writing-plans` 原版内含 `<HARD-GATE>` 与"等用户 approve 设计 / review spec / Which approach?"等用户等待点，与本插件"除真正卡死外不停"目标冲突。fork 进来剥掉门控后作为 `feature-brainstorm` / `feature-plan` 的内部实现用。
-
-| Skill | 源（superpowers 版本） | 剥掉了什么 |
-|---|---|---|
-| `superpower-brainstorming` | `superpowers:brainstorming` 5.0.7 | `<HARD-GATE>` 整块、Anti-Pattern 段、Checklist 里 Visual Companion / approve-design / review-spec 三项、User Review Gate、Visual Companion 整节、终点 `invoke writing-plans` |
-| `superpower-writing-plans` | `superpowers:writing-plans` 5.0.7 | Execution Handoff 整节（"Which approach?" 问询）、"Complete code in every step" 硬要求（改为"API 签名 + 测试意图"粒度，完整代码留给 TDD） |
-
 ## Agent 清单（2 个）
 | Agent | 源 | 用途 | 谁调用 |
 ---
 name: fe-feature-brainstorm
-description: 前端功能循环第 1 步。针对单个 FE-NN 页面（prototype/*.html）做交互式头脑风暴，产出前端功能规格到 docs/superpowers/specs/。
+description: 前端功能循环第 1 步。针对单个 FE-NN 页面（prototype/*.html）做交互式 Q&A + 写前端规格，产出到 docs/superpowers/specs/，链入 fe-feature-plan。
 user-invocable: false
-allowed-tools: Read Write Skill Glob Grep
+allowed-tools: Read Write Skill AskUserQuestion Glob Grep
 ---
 **所有输出必须使用中文。**
@@ -15,36 +15,60 @@ allowed-tools: Read Write Skill Glob Grep
 一个 FE 是**业务功能**粒度，可能关联多个 prototype 文件区域和多个 REQ。
+## 占位符规则
+
+本 skill 写的 spec 是 CC 内部推理产物，不是用户审阅文档。**不允许** `【人工填写：...】` 占位符——A 阶段标记。需要具体值时：
+
+1. **先查** `.env.local` / `docs/07-环境配置.md` / `docs/04-技术规范.md` / `docs/06-UI交互规范.md` / `CLAUDE.md` / 现有代码 / 关联 prototype。值已落地某处 → 在 spec 中引用源
+2. **再问**：查不到 → `AskUserQuestion` 问用户，记录答案到 spec
+3. **绝不**留 `【人工填写：】` 占位符
+
 ## 执行步骤
-1. 确定本次 FE 上下文（由 `frontend-start` 派发时传入 `{ fe_id, name, associated_reqs[], associated_prototypes[] }`），收集证据：
+1. **收集上下文**：确定本次 FE（由 `frontend-start` 派发时传入 `{ fe_id, name, associated_reqs[], associated_prototypes[] }`），读取证据：
    - **页面骨架**：Read 所有 `associated_prototypes[]`（如 `prototype/dashboard.html` + `prototype/dashboard.html#metrics-section`；含 anchor 时聚焦相应区域），作为本 FE 涉及页面的布局权威
    - **业务规则**：Read 所有 `associated_reqs[]` 对应的 `docs/01-需求清单/<module>/<REQ-id>.md`，提取业务校验规则、acceptance、UI 描述
    - **API 契约**：Read `docs/05-API接口契约.md`，按 `associated_reqs[]` 过滤出本 FE 消费的端点
    - **Design Tokens**：Read `docs/06-UI交互规范.md § 二`，作为色值/状态色的引用源
    - **前端组件库**：Read `docs/04-技术规范.md § 零` 找 `frontend.ui_lib`（如 Ant Design / Element Plus），决定组件选型
-2. 委托 `superpowers:brainstorming`，把上述上下文 + 落盘路径 `docs/superpowers/specs/<YYYY-MM-DD>-<fe_id>.md` 作为 caller-provided path 传入。caller-provided 上下文显式标注：
+2. **交互式 Q&A**（参考下方"Q&A 原则"，本次为**前端阶段**头脑风暴）：
+   - 关注：组件树、页面状态机、交互流程、API 调用一致性、Design Tokens 引用、业务校验前端复刻
+   - **不要**讨论 SQL / migration / controller / service / DTO（后端阶段已定）
+   - **一次一问** `AskUserQuestion`，仅对真模糊点；多选题优先
+   - trade-off 直接内嵌 spec，**不设确认 gate**
-   > 本次为前端阶段头脑风暴。关注组件树、页面状态机、交互流程、API 调用一致性、Design Tokens 引用、业务校验前端复刻。**不要**讨论 SQL / migration / controller / service / DTO。本 FE 关联的 REQ 与原型清单见上下文中 `associated_reqs` / `associated_prototypes`。
+3. **写 spec 到 `docs/superpowers/specs/<YYYY-MM-DD>-<fe_id>.md`**：
+   - 按 `${CLAUDE_SKILL_DIR}/templates/fe-feature-spec-template.md` 渲染
+   - 规格至少含：
+     - 关联 REQ + 关联原型（来自 frontend-start 派发的入参）
+     - 组件树（多个 prototype 文件 / 区域则按页面分块；推导自 prototype DOM）
+     - 页面状态机（loading / empty / error / 正常 / 表单提交中 至少 5 态；多页则按页列出）
+     - 消费的后端端点（与 docs/05 对齐，按本 FE 的 `associated_reqs[]` 过滤）
+     - 业务规则前端复刻清单（逐条，每条标注：规则描述 / 触发时机 / 报错文案 / 来源 REQ）
+     - Design Tokens 引用清单（本 FE 用到的 `var(--color-*)` 名称）
+   - 文件已存在 → 征求用户确认后覆盖
-   文件已存在 → 征求用户确认后覆盖。
+4. **Spec 自审**（inline 修，无须用户等待）：
+   - 所有顶级节非空
+   - **全文不得出现** `TBD` / `@todo` / `controller` / `SQL` / `service` / `migration` 字样——前者代表 spec 未完成，后五者属于后端范畴不应出现。命中 → 修正后重渲染
+   - **内部一致性** / **范围检查** / **歧义检查**（按 Q&A 原则）
-3. 按 `${CLAUDE_SKILL_DIR}/templates/fe-feature-spec-template.md` 渲染头脑风暴输出，写入推导路径。规格至少含：
-   - 关联 REQ + 关联原型（来自 frontend-start 派发的入参）
-   - 组件树（多个 prototype 文件 / 区域则按页面分块；推导自 prototype DOM）
-   - 页面状态机（loading / empty / error / 正常 / 表单提交中 至少 5 态；多页则按页列出）
-   - 消费的后端端点（与 docs/05 对齐，按本 FE 的 `associated_reqs[]` 过滤）
-   - 业务规则前端复刻清单（逐条，每条标注：规则描述 / 触发时机 / 报错文案 / 来源 REQ）
-   - Design Tokens 引用清单（本 FE 用到的 var(--color-*) 名称）
+5. **输出 + 链 fe-feature-plan**（**直接做这两件事，不要输出"回交父 skill / 交给 caller / 等下一步 / 准备好了请检查"之类的桥接叙述**——那些会被解读为 turn 结束信号）：
+   - 输出一行 `fe-feature-brainstorm: <fe_id> → <path>`
+   - **同一 turn 内立即** `Skill(fe-feature-plan)`
-4. **验证**：所有顶级节非空；**全文不得出现** `TBD`、`@todo`、`controller`、`SQL`、`service`、`migration` 字样——前者代表 spec 未完成，后五者属于后端范畴不应出现。命中 → 修正后重渲染。
+## Q&A 原则
-5. 输出 `fe-feature-brainstorm: <fe_id> → <path>`，立即调用 `Skill(fe-feature-plan)`。
+- **一次一问** — 不堆问题
+- **多选题优先** — 答更快
+- **仅对真模糊点问** — 不造确认问题
+- **YAGNI** — 删不必要的功能
+- **渐进理解** — 不明白就问
+- **无审批 gate** — 写 spec 即 commit
 ## 参考
 - `${CLAUDE_SKILL_DIR}/templates/fe-feature-spec-template.md`
-- 委托：`superpowers:brainstorming`（本插件 `skills/internal/superpower-brainstorming/`）
 - 上游：`frontend-start`（每个未完成 FE 派发到此）
 - 下游：`fe-feature-plan`
 ---
 name: fe-feature-plan
-description: 前端功能循环第 2 步。将 FE 规格转化为任务级实现计划（每任务 2-5 分钟，含组件路径、props 契约、测试意图），输出到 docs/superpowers/plans/。
+description: 前端功能循环第 2 步。将 FE 规格转任务级实现计划（每任务 2-5 分钟，含组件路径、props 契约、测试意图），产出到 docs/superpowers/plans/，链入 fe-feature-tdd。
 user-invocable: false
-allowed-tools: Read Write Grep Skill
+allowed-tools: Read Write Grep Skill AskUserQuestion
 ---
 **所有输出必须使用中文。**
@@ -11,32 +11,132 @@ allowed-tools: Read Write Grep Skill
 ## 阶段范围（前端）
-把当前 FE 的规格转成任务级实现计划，委托 `superpowers:writing-plans` 起草。任务粒度限定为：**组件文件 / 路由配置 / store hook / API client 包装函数**。**不允许**生成涉及后端文件（controller / service / repository / SQL）的任务。
+把当前 FE 的规格转成任务级实现计划。任务粒度限定为：**组件文件 / 路由配置 / store hook / API client 包装函数**。**不允许**生成涉及后端文件（controller / service / repository / SQL）的任务。
+
+## 计划写作原则
+
+- Plan 告诉 TDD 执行者**做什么**，不是**怎么写代码**——执行者是 `fe-feature-tdd`（同一模型，全上下文）
+- Plan 锁定**文件边界 + 测试意图 + props 契约 + 完成判据**；代码由 TDD 红绿循环产出
+- **禁止 dump 整个文件内容**（vue/react 组件源码、config 文件）到 plan
+- 每个任务标注"测试先行类型" = **jsdom 组件测试** OR **Playwright E2E**
+- DRY、YAGNI、TDD、frequent commits
+
+## 占位符规则
+
+每个 step 必须写实际内容。以下绝不出现：
+
+- `TBD` / `TODO` / `implement later` / `fill in details`
+- **`【人工填写：】`** — A 阶段标记。需要具体值时：先查 `.env.local` / `docs/07` / `docs/04` / `docs/09` / 现有代码并引用源；否则 `AskUserQuestion`
+- 涉及后端文件（`backend/` / `sql/` / `scripts/`）的任务——**硬护栏**
+- 未在任何 task 定义的组件 / hook / API client 函数
 ## 执行步骤
-1. 收集输入：
-   - 当前 FE 的规格文件 `docs/superpowers/specs/<YYYY-MM-DD>-<fe_id>.md`（不存在则报错）
+1. **收集输入**：
+   - 当前 FE 的规格 `docs/superpowers/specs/<YYYY-MM-DD>-<fe_id>.md`（不存在则报错）
    - `docs/04-技术规范.md § 一前端架构`（路由 / 状态库 / 组件目录约定 / 测试栈）
    - `docs/09-项目目录结构.md § 前端目录结构`（文件落盘位置规范）
-   - 相关代码指针（待修改的现有前端文件，通过 grep 在 `frontend/` 下定位）
+   - 相关代码指针（通过 `Grep` 在 `frontend/` 下定位现有前端文件）
+
+2. **范围检查**：spec 跨多页/多业务 → 提示拆分
-2. 委托 `superpowers:writing-plans`，把上下文 + 落盘路径 `docs/superpowers/plans/<YYYY-MM-DD>-<fe_id>.md` 作为 caller-provided path 传入。caller-provided 上下文显式标注：
+3. **文件结构推导**：
+   - 组件 / 路由 / hook / API client 各放哪里（依 docs/09 § 前端目录结构）
+   - 每个文件单一职责
+   - 同 feature 的相关文件放一起
-   > 本次为前端阶段任务计划。任务粒度 = 组件 / 路由 / hook / API client。每个任务必须含：`test_file::test_name` + `impl_file` + 完成判据。`impl_file` 必须落在 `frontend/` 目录下（具体根路径见 docs/09 § 前端目录结构）。每个任务标注"测试先行类型" = jsdom 组件测试 OR Playwright E2E。
+4. **任务粒度推导**（参考下方"任务原则"）：
+   - 每个任务 = 一个 red-green-commit 单元
+   - 4 个 step：写失败测试 → 实现最小代码 → 子会话验证 PASS → commit
+   - 任务粒度 2-5 分钟
+   - 每个任务必须含：`test_file::test_name` + `impl_file` + 完成判据 + "测试先行类型"标注
-3. 按 `${CLAUDE_SKILL_DIR}/templates/fe-feature-plan-template.md` 渲染输出，写入推导路径。
+5. **写 plan 到 `docs/superpowers/plans/<YYYY-MM-DD>-<fe_id>.md`**：
+   - 按 `${CLAUDE_SKILL_DIR}/templates/fe-feature-plan-template.md` 渲染
+   - 文件已存在 → 征求用户确认后覆盖
-4. **验证**：
+6. **Plan 自审**（inline 修，无须用户等待）：
    - 每个任务必须含 `test_file::test_name`、`impl_file`、完成标准
-   - **每个任务的 `impl_file` 路径必须以 `frontend/` 开头**（或 docs/09 声明的前端根目录），命中 `backend/` / `sql/` / `scripts/` → 修正后重渲染
-   - 全文不得出现 `TBD` / `【人工填写：...】`——查不到值用 `AskUserQuestion` 问用户
+   - **每个任务的 `impl_file` 路径必须以 `frontend/` 开头**（或 `docs/09` 声明的前端根目录）；命中 `backend/` / `sql/` / `scripts/` → 修正后重渲染
+   - **占位符扫描**：`TBD` / `【人工填写：】` → 修
+   - **Spec coverage**：spec 每节能指向至少一个 task 吗
+   - **类型一致性**：组件 props 类型 / hook 签名跨 task 一致
+
+7. **输出 + 链 fe-feature-tdd**（**直接做这两件事，不要输出"回交父 skill / 交给 caller / 等下一步 / 准备好了请检查"之类的桥接叙述**——那些会被解读为 turn 结束信号）：
+   - 输出一行 `fe-feature-plan: <fe_id> → <path>`
+   - **同一 turn 内立即** `Skill(fe-feature-tdd)`
+
+## 任务原则
+
+### Plan 文件头
+
+每个 plan 必须以以下头部开始：
+
+```markdown
+# [FE Feature Name] Implementation Plan
+
+> **Execution:** Parent skill `fe-feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** [一句话描述]
+
+**Architecture:** [2-3 句方法论]
+
+**Tech Stack:** [关键技术 / 库]
+
+---
+```
+
+### Task 结构
+
+每个 task 是 red-green-commit 单元：
+
+````markdown
+### Task N: [组件名]
+
+**Files:**
+- Create: `frontend/src/components/LoginForm.tsx`
+- Test: `frontend/src/components/LoginForm.test.tsx`
+- 测试先行类型: jsdom 组件测试
+
+**Props/API shape**（只写需要约束实现的签名）:
+- `<LoginForm onSubmit={(username: string, password: string) => Promise<void>} loading={boolean} />`
+
+- [ ] **Step 1: 写失败测试**
+  - 测试名: `LoginForm renders username and password fields`
+  - 意图: 验证组件渲染 username / password input，submit button disabled when empty
+  - 子会话确认 FAIL（组件不存在）
+
+- [ ] **Step 2: 实现最小代码**
+  - 目标: 让 Step 1 测试通过；不多做
+  - 涉及文件: `frontend/src/components/LoginForm.tsx`
+
+- [ ] **Step 3: 子会话验证 PASS**
+
+- [ ] **Step 4: Commit**
+  - `git add <文件>`
+  - `git commit -m "feat(fe): LoginForm 组件 FE-01"`
+````
+
+### 允许的代码块场景
+
+少数例外，需要写死而非让 TDD 自由发挥：
+
+- **路由配置**：`routes.ts` 中 path 注册（路径是契约级）
+- **API client 契约**：fetch 包装函数签名 + headers + 错误码 mapping
+- **Design Tokens 名称**：`var(--color-primary)` 列表（跨组件复用）
+- **测试断言形状**（可选）
+
+除此之外一律散文 + 签名描述，**不贴完整组件源码**。
+
+### 记住
-5. 输出 `fe-feature-plan: <fe_id> → <path>`，立即调用 `Skill(fe-feature-tdd)`。
+- Exact file paths always（必须以 `frontend/` 开头）
+- 测试先行类型必须明确（jsdom / Playwright）
+- 组件 props / hook 签名 / API client 函数签名 — **必须写死**
+- Internal implementation code — **不写**；留给 TDD 阶段
 ## 参考
 - `${CLAUDE_SKILL_DIR}/templates/fe-feature-plan-template.md`
-- 委托：`superpowers:writing-plans`（本插件 `skills/internal/superpower-writing-plans/`）
 - 上游：`fe-feature-brainstorm`
 - 下游：`fe-feature-tdd`
 ---
 name: feature-brainstorm
-description: 功能循环第 1 步。针对单个 REQ-XXX-NNN 进行交互式头脑风暴，产出功能规格到 docs/superpowers/specs/。
+description: 功能循环第 1 步。针对单个 REQ-XXX-NNN 做交互式 Q&A + 写规格，产出到 docs/superpowers/specs/，链入 feature-plan。
 user-invocable: false
-allowed-tools: Read Write Skill Bash(mysql *)
+allowed-tools: Read Write Skill AskUserQuestion Bash(mysql *)
 ---
 **所有输出必须使用中文。**
@@ -13,17 +13,53 @@ allowed-tools: Read Write Skill Bash(mysql *)
 本 skill 服务于**后端阶段**。产出范围限定为 controller / service / repository / DTO / 校验 / SQL migration / REST 契约。读 docs/01 REQ 卡片时**忽略 UI 描述**（输入控件类型、按钮位置、列表布局等），但**校验规则、业务规则**仍要落到后端 DTO + service。UI 实现统一推迟到前端阶段（fe-feature-*）。
-针对单个 REQ，委托 `superpower-brainstorming` 做交互式头脑风暴，把输出按规格模板渲染，产出单页功能规格。
+## 占位符规则
+
+本 skill 写的 spec 是 CC 内部推理产物，不是用户审阅文档。**不允许** `【人工填写：...】` 占位符——A 阶段 `docs/01~10` / `CLAUDE.md` / `.env.local` 才用那个标记。需要具体值时：
+
+1. **先查** `.env.local` / `docs/07-环境配置.md` / `CLAUDE.md` / 现有代码。值已落地某处 → 在 spec 中引用源（例 "JWT_SECRET 从 `.env.local` 读取，`application.yml` 用 `${JWT_SECRET}` 注入"）
+2. **再问**：查不到 → `AskUserQuestion` 问用户，记录答案到 spec
+3. **绝不**留 `【人工填写：】` 占位符；若 1 + 2 都解决不了，spec 必须写出具体阻塞点（不是泛化的人工填写标记），Q&A 继续直到解决
 ## 执行步骤
-1. 确定本次 REQ-XXX-NNN（由 module-start 派发时确定），收集上下文：REQ 卡片 `docs/01-需求清单/<module>/<req_id>.md` + 涉及的数据表定义（取自 docs/03 或实时 mysql 查询）。
-2. 委托 `superpower-brainstorming`，把上下文 + 落盘路径 `docs/superpowers/specs/<YYYY-MM-DD>-<REQ-id>.md` 作为 caller-provided path 传入。文件已存在 → 征求用户确认后覆盖。
-3. 按 `${CLAUDE_SKILL_DIR}/templates/feature-spec-template.md` 渲染头脑风暴输出，写入推导路径。
-4. **验证**：所有顶级节非空；**全文不得出现 `【人工填写：...】` 或 `TBD`**——这两类标记仅供 A 阶段文档审阅用，B 阶段 spec 必须写实际值（先在 `.env.local` / `docs/07-环境配置.md` / `CLAUDE.md` / 现有代码查找并注明来源，查不到则用 `AskUserQuestion` 问用户）。
-5. 输出 `feature-brainstorm: <REQ> → <path>`，立即调用 `Skill(feature-plan)`。
+1. **收集上下文**：确定本次 REQ-XXX-NNN（由 module-start 派发时指定），读取：
+   - REQ 卡片 `docs/01-需求清单/<module>/<req_id>.md`
+   - 涉及的数据表定义（取自 docs/03 或实时 mysql 查询）
+
+2. **交互式 Q&A**（参考下方"Q&A 原则"）：
+   - **先评估 scope**：单 spec 容纳得下吗？跨多个独立子系统（如"含登录 + 文件存储 + 计费 + 分析"）→ 先提示分解，每个子项目独立 brainstorm
+   - **一次一问** `AskUserQuestion`，仅对真模糊点；多选题优先
+   - 决策完成后挑一种 approach；trade-off 直接内嵌 spec，**不设确认 gate**
+
+3. **写 spec 到 `docs/superpowers/specs/<YYYY-MM-DD>-<REQ-id>.md`**：
+   - 按 `${CLAUDE_SKILL_DIR}/templates/feature-spec-template.md` 渲染
+   - 覆盖：goal / 输入输出 / 业务规则 / 约束 / schema / API 引用 / acceptance criteria
+   - 文件已存在 → 征求用户确认后覆盖
+
+4. **Spec 自审**（inline 修，无须用户等待）：
+   - **占位符扫描**：`TBD` / `TODO` / `【人工填写：】` / 含糊段 → 修（按"占位符规则"流程解决）
+   - **内部一致性**：节与节是否矛盾？架构是否匹配功能描述？
+   - **范围检查**：单 plan 能消化吗？还是需要分解
+   - **歧义检查**：任何 requirement 两种解读？挑一个写明
+   
+   fix inline，无须 re-review。
+
+5. **输出 + 链 feature-plan**（**直接做这两件事，不要输出"回交父 skill / 交给 caller / 等下一步 / 准备好了请检查"之类的桥接叙述**——那些会被解读为 turn 结束信号）：
+   - 输出一行 `feature-brainstorm: <REQ> → <path>`
+   - **同一 turn 内立即** `Skill(feature-plan)`
+
+## Q&A 原则
+
+- **一次一问** — 不堆问题
+- **多选题优先** — 答更快
+- **仅对真模糊点问** — 不造确认问题
+- **YAGNI** — 删 spec 中不必要的功能
+- **渐进理解** — 不明白就问
+- **无审批 gate** — 写 spec 即 commit；分歧落地为具体 Q&A 项，不靠"等用户确认"
 ## 参考
 - `${CLAUDE_SKILL_DIR}/templates/feature-spec-template.md`
-- 委托：`superpower-brainstorming`（本插件 `skills/internal/superpower-brainstorming/`）
+- 上游：`module-start`
+- 下游：`feature-plan`
 ---
 name: feature-plan
-description: 功能循环第 2 步。将规格转化为任务级计划（每任务 2-5 分钟，含文件路径和完整代码），输出到 docs/superpowers/plans/。
+description: 功能循环第 2 步。将 spec 转任务级 TDD 计划（每任务 2-5 分钟），产出到 docs/superpowers/plans/，链入 feature-tdd。
 user-invocable: false
-allowed-tools: Read Write Grep Skill
+allowed-tools: Read Write Grep Skill AskUserQuestion
 ---
 **所有输出必须使用中文。**
@@ -13,20 +13,131 @@ allowed-tools: Read Write Grep Skill
 本 skill 服务于**后端阶段**。任务粒度限定为后端模块文件：controller / service / repository / DTO / 校验 / SQL migration。**禁止**生成 `frontend/` 路径下的实现任务——UI 实现统一推迟到前端阶段（fe-feature-*）。
-把当前 REQ 的功能规格转成任务级实现计划，委托 `superpower-writing-plans` 起草，按计划模板渲染落盘。
+## 计划写作原则
+
+- Plan 告诉 TDD 执行者**做什么**，不是**怎么写代码**——执行者是 `feature-tdd`（同一模型，全上下文），不是机械复制粘贴员
+- Plan 锁定**文件边界 + 测试意图 + API 形状 + 完成判据**；代码由 TDD 红绿循环产出
+- **禁止 dump 整个文件内容**（pom.xml / entity 类 / config 文件）到 plan——plan 和代码会成为两个 source of truth 并漂移；2000+ 行 plan 浪费上下文
+- DRY、YAGNI、TDD、frequent commits
+
+## 占位符规则
+
+每个 step 必须写实际内容。以下属于 **plan failures**，绝不出现：
+
+- `TBD` / `TODO` / `implement later` / `fill in details`
+- **`【人工填写：】`** — 这是 A 阶段标记（`docs/01~10` / `CLAUDE.md` / `.env.local`），B 阶段 plan **绝不能出现**。需要具体值时：
+  1. 先查 `.env.local` / `docs/07-环境配置.md` / `CLAUDE.md` / 现有代码并在 plan 中引用源
+  2. 否则 `AskUserQuestion` 问用户并记录答案
+- "Add appropriate error handling" / "add validation"（要具体到哪些错误码 / 哪些字段）
+- "Similar to Task N"（相似任务各自写清楚测试意图 + 完成判据，不互相链接）
+- 未在任何 task 定义的 types / functions / methods（类/方法首次出现的 task 必须给出 API 签名）
+
+> 散文级"做什么"是 OK 的——执行器（`feature-tdd`）会在 TDD 循环里决定"怎么写"。plan 的义务是**约束范围**，不是**替 TDD 写代码**。
 ## 执行步骤
-1. 收集输入：
-   - 当前 REQ 的规格文件 `docs/superpowers/specs/<YYYY-MM-DD>-<REQ-id>.md`（不存在则报错）
-   - 相关代码指针（待修改的现有文件，通过 grep 发现）
+1. **收集输入**：
+   - spec 文件 `docs/superpowers/specs/<YYYY-MM-DD>-<REQ-id>.md`（不存在则报错）
+   - 相关代码指针（通过 `Grep` 在现有代码定位待修改文件）
    - `docs/04-技术规范.md` 与 `docs/09-项目目录结构.md`（编码规范 + 目录规范）
-2. 委托 `superpower-writing-plans`，把上述上下文 + 落盘路径 `docs/superpowers/plans/<YYYY-MM-DD>-<REQ-id>.md` 作为 caller-provided path 传入。
-3. 按 `${CLAUDE_SKILL_DIR}/templates/feature-plan-template.md` 渲染输出，写入推导路径。
-4. **验证**：每个任务必须含失败测试标识、实现路径与完成标准；**plan 全文不得出现 `【人工填写：...】` 或 `TBD`**——这两类标记仅供 A 阶段文档审阅用，B 阶段 plan 必须写实际值（先在 `.env.local` / `docs/07-环境配置.md` / `CLAUDE.md` / 现有代码查找并注明来源，查不到则用 `AskUserQuestion` 问用户）。
-5. 输出 `feature-plan: <REQ> → <path>`，立即调用 `Skill(feature-tdd)`。
+
+2. **范围检查**：spec 跨多个独立子系统 → 提示拆分，每个 plan 应能独立产出可工作、可测试的软件
+
+3. **文件结构推导**：
+   - 哪些文件 create / modify
+   - 每个文件单一职责，well-defined interface
+   - 一起变化的文件放一起；不按技术层切分
+
+4. **任务粒度推导**（参考下方"任务原则"）：
+   - 每个任务 = 一个 red-green-commit 单元
+   - 4 个 step：写失败测试 → 实现最小代码 → 子会话验证 PASS → commit
+   - 任务粒度 2-5 分钟
+
+5. **写 plan 到 `docs/superpowers/plans/<YYYY-MM-DD>-<REQ-id>.md`**：
+   - 按 `${CLAUDE_SKILL_DIR}/templates/feature-plan-template.md` 渲染
+   - 文件已存在 → 征求用户确认后覆盖
+
+6. **Plan 自审**（inline 修，无须用户等待）：
+   - **占位符扫描**：按"占位符规则"清单逐项 grep；命中即修
+   - **Spec coverage**：skim spec 每节，能指向至少一个 task 吗？list gaps 并补 task
+   - **类型一致性**：tasks 之间签名 / 方法名 / 属性名 / 错误码是否一致（Task 3 的 `clearLayers()` 和 Task 7 的 `clearFullLayers()` 是 bug）
+
+7. **输出 + 链 feature-tdd**（**直接做这两件事，不要输出"回交父 skill / 交给 caller / 等下一步 / 准备好了请检查"之类的桥接叙述**——那些会被解读为 turn 结束信号）：
+   - 输出一行 `feature-plan: <REQ> → <path>`
+   - **同一 turn 内立即** `Skill(feature-tdd)`
+
+## 任务原则
+
+### Plan 文件头
+
+每个 plan 必须以以下头部开始：
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** [一句话描述]
+
+**Architecture:** [2-3 句方法论]
+
+**Tech Stack:** [关键技术 / 库]
+
+---
+```
+
+### Task 结构
+
+每个 task 是 red-green-commit 单元。捕获意图和边界，代码留给 TDD：
+
+````markdown
+### Task N: [组件名]
+
+**Files:**
+- Create: `exact/path/to/File.java`
+- Modify: `exact/path/to/Existing.java:123-145`
+- Test: `tests/exact/path/to/FileTest.java`
+
+**API shape**（只写需要约束实现的签名；内部实现留给 TDD）:
+- `LoginService#login(LoginRequest req) : LoginResponse`
+- `throws AccountLockedException when iLoginFailCount ≥ 5 within tLockUntil window`
+
+- [ ] **Step 1: 写失败测试**
+  - 测试名: `LoginServiceTest#loginWithBadPassword_incrementsFailCount_returns40101`
+  - 意图: 错误密码 → `iLoginFailCount += 1`；第 5 次 → 设置 `tLockUntil = now + 15min`；返回码 40101
+  - 子会话确认 FAIL（函数/类不存在）
+
+- [ ] **Step 2: 实现最小代码**
+  - 目标: 让 Step 1 测试通过；不多做
+  - 涉及文件: `LoginService.java`, `SftLoginInfoMapper.java`
+
+- [ ] **Step 3: 子会话验证 PASS**
+
+- [ ] **Step 4: Commit**
+  - `git add <文件>`
+  - `git commit -m "feat(sys): 登录失败计数 + 锁定 REQ-SYS-001"`
+````
+
+### 允许的代码块场景
+
+少数例外，需要写死而非让 TDD 自由发挥：
+
+- **DDL / migration 文件**：`V_n__*.sql` 的 ALTER/CREATE 语句——schema 是事实源、不是 TDD 红绿产物
+- **合同级常量**：API 错误码表、JWT claim 名、Redis key 模式——跨模块消费，必须在 plan 锁定
+- **测试断言形状**（可选）：一句话说不清"测什么"时，给个 3-5 行断言 sketch 是 OK 的
+
+除此之外一律散文 + 签名描述，**不贴完整文件**。
+
+### 记住
+
+- Exact file paths always
+- Exact commands with expected output（测试运行 + git 操作）
+- API signatures / class names / error codes / contract values — **必须写死**
+- Internal implementation code — **不写**；留给 TDD 阶段
+- DRY、YAGNI、TDD、frequent commits
 ## 参考
 - `${CLAUDE_SKILL_DIR}/templates/feature-plan-template.md`
-- 委托：`superpower-writing-plans`（本插件 `skills/internal/superpower-writing-plans/`）
+- 上游：`feature-brainstorm`
+- 下游：`feature-tdd`
@@ -4,11 +4,11 @@
 | 字段 | 类型 | Nullable | 默认 | 业务含义 |
 |---|---|---|---|---|
-| `iIncrement` | int | 否 | — | 整数主键 ID（标准列） |
-| `sId` | varchar(100) | 是 | — | 业务 ID（标准列） |
-| `sBrandsId` | varchar(100) | 是 | — | 品牌 ID（多租户隔离，标准列） |
-| `sSubsidiaryId` | varchar(100) | 是 | — | 子公司 ID（组织层级隔离，标准列） |
-| `tCreateDate` | datetime | 否 | — | 创建时间（标准列） |
+| `iIncrement` | int | 否 | 自增函数 | 整数主键 ID（标准列） |
+| `sId` | varchar(100) | 是 | uuid 函数 | 业务 ID（标准列） |
+| `sBrandsId` | varchar(100) | 是 | `1111111111` | 品牌 ID（多租户隔离，标准列） |
+| `sSubsidiaryId` | varchar(100) | 是 | `1111111111` | 子公司 ID（组织层级隔离，标准列） |
+| `tCreateDate` | datetime | 否 | 当前时间 | 创建时间（标准列） |
 {{#each columns}}
 | {{name}} | {{type}} | {{nullable}} | {{default}} | {{business_meaning}} |
 {{/each}}
@@ -3,7 +3,6 @@
 - **Method**: {{method}}
 - **Path**: `{{path}}`
 - **Auth**: {{auth}}
-- **Permission**: {{permission}}
 - **请求**: {{request_summary}}
 - **响应**: {{response_summary}}