flower-trellis 0.1.0

package/README.md

@@ -0,0 +1,113 @@
+# 🌸 flower-trellis
+
+> 一条命令装好 [Trellis](https://docs.trytrellis.app/) 工程框架,并自动融合 **skill-garden** 的强化包。
+
+## 这是什么
+
+`flower-trellis` 是一个 Node CLI(npm 包),把原本要分两步做的事合并成一键完成:
+
+1. **装/升级 Trellis 本体** —— [trytrellis.app](https://docs.trytrellis.app/) 出品的 AI 编程工程框架,
+   把 specs / tasks / memory 持久化进你的仓库,让任意 AI 编程 Agent 都遵循你的工程规范。
+   底层调用官方 `@mindfoldhq/trellis` 的 `init` / `update`。
+2. **叠加强化包** —— 自动套用 skill-garden 的强化补充包
+   (按目标项目的 Trellis 版本智能选择 `old / 0.5 / 0.6` variant),
+   内含一组 `trellis-*` 技能与 workflow override。强化包随本包发布,安装零网络。
+
+> **命名由来**:取自 skill-garden 的「园艺」主题 —— trellis 是花园里供藤蔓攀爬的棚架,
+> `flower-trellis` 即「开满花的棚架」:框架装好、强化包到位,即开即用。
+
+## 用法
+
+```bash
+# 交互安装:flower 平台菜单(默认勾 codex + claude)→ Trellis 原生模板/monorepo 菜单
+npx flower-trellis init -u your-name
+
+# 指定平台(透传 trellis,跳过平台菜单),例如只装 claude
+npx flower-trellis init -u your-name --claude
+
+# 完全非交互(平台默认 codex + claude;模板用空白默认)
+npx flower-trellis init -u your-name -y
+
+# 升级 Trellis 并按新版本重新套用强化包
+npx flower-trellis update
+
+# 卸载:移除 Trellis 本体并清理强化包残留
+npx flower-trellis uninstall
+
+# 只装 Trellis 不叠加强化包 / 已有项目只重叠加
+npx flower-trellis init --no-enhance
+npx flower-trellis init --enhance-only
+
+# 其它 trellis 子命令一律透传(面向未来,零维护)
+npx flower-trellis <任意 trellis 命令>
+
+# 查看版本(flower-trellis 自身 + 捆绑的 Trellis)
+npx flower-trellis -v
+```
+
+## 交互流程(`init`)
+
+```
+🌸 FLOWER 品牌头部(ASCII logo + 👤 Developer)
+   ↓
+? 选择 AI 工具(flower 菜单,默认勾 Claude Code + Codex)
+   ↓
+? Select a spec template / monorepo 识别 …(Trellis 原生交互,原样保留)
+   ↓
+叠加 skill-garden 强化包 + codex 后处理 → 完成
+```
+
+全程**只有 flower 一个 banner**:Trellis 子进程在伪终端(node-pty)里运行,
+它原生的模板 / monorepo / 冲突等交互完整保留,而它重复打印的启动 banner / Developer 被过滤掉。
+
+## 状态
+
+✅ **可用** —— 核心功能已实现并端到端验证。当前捆绑 Trellis `0.6.0-beta.8`。
+
+## 功能
+
+- [x] `init` / `update` / `uninstall`,其它 trellis 子命令兜底透传
+- [x] flower 品牌 banner(`init` 交互 + `update`)
+- [x] flower 平台多选菜单,默认勾 **codex + claude**;或 `-y` 用默认、传 `--claude/--codex/--cursor` 等指定
+- [x] 用 **node-pty** 在伪终端运行 trellis,完整保留其模板 / monorepo / 冲突等原生交互,同时过滤掉重复 banner / Developer
+- [x] 自动识别 Trellis 版本,选择匹配的强化包 variant(`old / 0.5 / 0.6`)
+- [x] 强化 skill 跟随平台铺设(claude→`.claude/skills`,codex/gemini 等→`.agents/skills`)
+- [x] codex 后处理:注释 `config.toml` 的 `[features.multi_agent_v2]`、补全 `hooks.json` 的 `SessionStart`
+- [x] workflow override 幂等注入(先清旧块再注入 + 备份 `.bak`)
+- [x] 升级时清理过期强化项(`0.5`/`old` → `0.6` 删除淘汰的 skill/command,基于 flower manifest,只删自己铺过的)
+- [x] `Ctrl+C` 安全中止(取消时不会继续叠加)
+- [x] `-v` 同时打印 flower-trellis 与捆绑 Trellis 版本
+- [x] 幂等执行:重复运行安全
+
+## 强化包与更新机制
+
+强化包以**快照**形式打包在本仓库 `enhancements/`(由 `npm run sync` 从 skill-garden 同步),随 npm 发布,安装零网络。因此:
+
+- **Trellis 本体**:`update` 实时升级(trellis 自己拉最新)。
+- **强化包**:用当前安装的 flower-trellis 版本里的那份快照。要跟上 skill-garden 后续迭代,流程为:
+  `skill-garden 改动 → npm run sync + 发新版 → npm i -g flower-trellis@latest → flower-trellis update`。
+
+**重复安装 / 升级的正确性**(已实测,不会出现重复块或残留):
+
+1. **skill 文件**:覆盖式铺设 + `.trellis/.flower-manifest.json` 记录上次铺过的路径,删除本次不再包含的项。
+2. **`workflow.md`**:每次注入前先 strip 掉所有旧的 skill-garden 块(按 `BEGIN/END` 标记整段删),再重注入 —— 块数恒定、绝不翻倍;首次注入前备份 `.bak`。
+3. **升级清理**:跨 variant / 跨快照版本删除淘汰的 skill / command。
+
+> ⚠️ **维护约束**:`workflow.md` 的 strip 依赖 `src/lib/workflow-inject.js` 里硬编码的 sentinel 名单。改现有块的**内容**无需动名单;但 skill-garden **新增一种 workflow 块类型**(新的 `BEGIN/END` 名)时,必须同步更新该名单,否则旧块清不掉。
+
+## 开发
+
+```bash
+npm install                 # 安装依赖
+npm run sync                # 从 skill-garden 同步强化包快照到 enhancements/
+node bin/flower-trellis.js init -u you --target /某测试目录   # 本地试跑(勿在本仓库根直接 init)
+```
+
+运行时依赖:`@mindfoldhq/trellis`(捆绑的 Trellis 本体)、`node-pty`(伪终端,保留 trellis 交互)、`inquirer`(平台菜单)、`figlet` + `chalk`(banner)。
+
+## 相关项目
+
+| 项目 | 作用 |
+|------|------|
+| [Trellis](https://docs.trytrellis.app/)(`@mindfoldhq/trellis`) | AI 编程工程框架本体,本包作为 wrapper 调用其 `init`/`update`/`uninstall` 等 |
+| skill-garden | 强化补充包的来源(`.trellis/` 下 `old/0.5/0.6` 各 variant) |

package/bin/flower-trellis.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// flower-trellis CLI 入口。
+// 仅做一件事:加载真正的 CLI 实现。保持极薄,便于 ESM 动态加载。
+import("../src/cli.js");

package/enhancements/0.5/.agents/skills/trellis-analyze-task/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: trellis-analyze-task
+description: "Analyze and refine an existing task under .trellis/tasks/: read task.json + prd.md + related code, output scope/risks/ambiguities report, then ask clarifying questions one at a time to update prd.md/task.json in real-time. Triggers: 「分析任务」「细化任务」「这个任务怎么做」. For brand-new features without a task yet, use trellis-brainstorm."
+---
+# 任务深度分析与细化
+
+对 `.trellis/tasks/` 下的已有任务进行深入分析，提供全景预览、识别风险点，并通过交互式问答细化任务内容。
+
+---
+
+## 适用场景
+
+- 已有 task 但需求不够清晰，需要拆解成可执行步骤
+- 任务拿到后还不确定影响面、风险点或不明确处
+- 开发前的深度细化环节
+
+---
+
+## 执行步骤
+
+### Step 1: 定位任务
+
+参数：`task-slug`（可选）。提供时直接定位，未提供时列出所有活跃任务让用户选择。
+
+```bash
+# 未指定任务时，列出所有活跃任务
+python3 ./.trellis/scripts/task.py list
+```
+
+- 如果用户未指定任务，展示任务列表并用 `AskUserQuestion` 让用户选择
+- 定位后，读取任务目录下的 `task.json` 和 `prd.md`（如果存在）
+
+### Step 2: 上下文收集（静默执行，不问用户）
+
+在分析之前，自动收集信息：
+
+1. **任务文件**：读取 `task.json`、`prd.md`（如果有）
+2. **相关代码**：如果任务涉及具体模块，快速扫描相关代码结构
+3. **依赖任务**：检查是否有关联或依赖的任务
+4. **历史记录**：检查 journal 中是否有该任务的相关记录
+
+### Step 3: 输出分析报告
+
+以下列结构输出分析报告：
+
+```markdown
+## 任务分析报告: <任务标题>
+
+### 概述
+<用 2-3 句话总结这个任务要做什么、为什么要做>
+
+### 工作预览
+预计需要做的事情：
+1. <步骤 1>
+2. <步骤 2>
+3. ...
+
+### 涉及范围
+- **模块/文件**: <涉及哪些模块或文件>
+- **影响面**: <这个变更会影响到什么>
+- **依赖**: <需要什么前置条件>
+
+### 风险点
+1. <风险 1>: <说明 + 可能的后果>
+2. <风险 2>: <说明 + 可能的后果>
+
+### 不明确的地方
+1. <问题 1>: <为什么这个需要澄清>
+2. <问题 2>: <为什么这个需要澄清>
+
+### 建议
+- <可选的改进建议或替代方案>
+```
+
+### Step 4: 交互式反问
+
+报告输出后，**逐个**向用户提出不明确的问题（每次只问一个）。
+
+使用 `AskUserQuestion` 工具提问，优先提供选项：
+
+```markdown
+关于 <问题主题>，你倾向于哪种方式？
+
+1. **选项 A** — <含义 + 利弊>
+2. **选项 B** — <含义 + 利弊>
+3. **其他** — 你来说明
+```
+
+### Step 5: 根据反馈更新任务
+
+每收到一个回答后：
+1. **立即更新** `prd.md`（如果存在）或创建新的 `prd.md`
+2. **更新** `task.json` 中的相关字段（如优先级、描述等）
+3. 继续下一个问题，直到所有不明确的地方都澄清
+
+### Step 6: 输出细化结果
+
+所有问题回答完毕后，输出最终的细化摘要：
+
+```markdown
+## 任务细化完成
+
+### 变更摘要
+- <列出 prd.md / task.json 的变更内容>
+
+### 下一步
+- 如果准备开发：运行 `trellis-continue` 进入/继续开发流程
+- 如果需要进一步讨论：继续对话
+```
+
+---
+
+## 核心原则
+
+| 原则 | 说明 |
+|------|------|
+| **先分析后提问** | 先展示你的分析和理解，再提问 |
+| **每次只问一个问题** | 不要用问题列表轰炸用户 |
+| **提供选项** | 尽量给出可选方案而非开放式问题 |
+| **即时更新** | 每次收到回答立即更新文档 |
+| **识别真正的风险** | 区分「可能的风险」和「确定的风险」 |
+| **YAGNI** | 挑战不必要的复杂度，聚焦真正需要的 |
+
+---
+
+## 与其他入口的区别
+
+| 入口 | 形态 | 用途 | 输入 |
+|------|------|------|------|
+| `trellis-brainstorm` | skill | 从模糊想法出发，发现需求 | 用户的初始想法（尚无 task） |
+| `trellis-analyze-task` | skill（本技能） | 对已有任务深入分析和细化 | 已存在的 task |
+| `trellis-continue` | 命令 | 进入/继续开发流程 | 已有 prd.md 的任务 |
+
+---
+
+## 反模式（避免）
+
+- ❌ 直接输出一大堆问题让用户回答
+- ❌ 不看代码就做分析（先收集上下文）
+- ❌ 分析报告过于笼统（要具体到文件和模块）
+- ❌ 过度细化不重要的细节
+- ❌ 忽略跨模块影响

package/enhancements/0.5/.agents/skills/trellis-check-all/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: trellis-check-all
+description: "Full pre-commit/PR review in 3 steps: PRD-implementation correctness → 5-dim assumption validation (API, component context, data history/flow, tests) → cross-layer completeness + spec compliance (delegates to trellis-check). Pauses on ❌. Triggers: 「全面检查」「提交前检查」「check-all」「从 PRD 到代码过一遍」. For lint/spec-only, use trellis-check directly."
+---
+# Check All — 全维度代码检查
+
+依次执行三个维度的代码检查，一次性完成全维度质量验证。
+
+> 顺序逻辑：**正确性 → 假设验证 → 完整性+规范性**
+> 先保证"做对了"，再保证"做全了"，最后保证"写好了"。
+
+---
+
+## 执行模式
+
+**各 Step 的具体 check 在主对话中直接展开执行，不要用 Agent 工具委派给子 agent 跑。**
+
+原因：
+- 各 Step 中存在"发现问题立即暂停询问用户"的交互点，子 agent 无法交互式暂停
+- 检查结果的具体细节（哪一行、哪个假设错了）对后续修复很关键，子 agent 的摘要式返回会丢失细节
+
+**例外**：仅当用户显式要求"用子 agent 跑各 Step"或"并行执行"时，才使用 Agent 工具委派。
+
+---
+
+## 三个维度（按顺序执行）
+
+| 顺序 | 维度 | 检查什么 | 对照物 |
+|------|------|---------|--------|
+| 1 | PRD 实现 | 实现对不对 | PRD |
+| 2 | 假设验证 | 假设对不对 | 源码/真实数据 |
+| 3 | 完整性+规范性（trellis-check） | 改全了没 + 写得规范吗 | git diff 影响范围 + spec 开发规范 |
+
+---
+
+## Step 0: 确认变更范围
+
+```bash
+git diff --name-only
+git log --oneline -10
+```
+
+如果无变更，提示用户并终止。
+
+读取当前任务的 `prd.md`（由 trellis 的 session hook 自动加载，或手动确认任务目录）。如果没有 PRD，跳过 Step 1 从 Step 2 开始。
+
+---
+
+## Step 1: 对照 PRD 检查实现
+
+**重点**：PRD 中的每条需求和 AC 是否都正确实现了？有没有行为偏差、功能缺失、文案不一致？
+
+### 1.1 核心原则（不可违反）
+
+1. **PRD 是验收标准** — 每条 Requirement 和 AC 都必须在代码中找到对应实现，找不到即为缺失
+2. **逐条追踪，不跳不漏** — 不能只看 happy path，PRD 中提到的边界条件、异常处理、空值场景都要追踪
+3. **读代码，不猜代码** — 必须实际读到实现代码，不能因为"应该写了"就标记通过
+4. **文案逐字比对** — PRD 中的 UI 文案（按钮、提示语、Toast、弹窗、表头、placeholder）必须与代码中的字面值**完全一致**
+5. **只报事实，不加发挥** — 报告中只陈述 PRD 要求 vs 代码实现的差异，不要加入 PRD 之外的建议
+
+### 1.2 分解 PRD 为可验证条目
+
+从 PRD 中提取（按优先级）：
+1. **Acceptance Criteria** — 最直接的验证条目
+2. **Requirements** — 每条需求对应的行为
+3. **业务规则** — 条件判断、计算逻辑、状态流转
+4. **UI 文案** — 所有用户可见文字
+5. **边界/异常场景** — 空值处理、上限、错误提示等
+
+每条记录格式：`[条目ID] <PRD 原文摘要> — 来源：<PRD 中位置>`
+
+### 1.3 逐条追踪代码实现
+
+根据条目类型定位实现：
+
+| 条目类型 | 搜索方法 |
+|---------|---------|
+| API 接口行为 | Controller → Service → DAO，追踪完整链路 |
+| 前端交互行为 | 组件文件，事件处理、状态管理 |
+| 数据校验规则 | 前端 rules + 后端 validator/service，两端都查 |
+| UI 文案 | grep 关键字，前端代码精确匹配 |
+| 计算/转换逻辑 | service 层，读具体算法 |
+| 状态流转 | 状态枚举 + 转换条件代码 |
+
+对每条标记状态：
+
+| 状态 | 含义 |
+|------|------|
+| ✅ 已实现 | 代码正确实现了 PRD 要求（已读代码确认） |
+| ❌ 实现偏差 | 代码实现了，但行为与 PRD 描述不一致 |
+| 🔴 未实现 | 代码中找不到对应实现 |
+| ⚠️ 部分实现 | 核心逻辑有，但缺少边界/异常处理 |
+| 🟡 文案不一致 | UI 文案与 PRD 不逐字一致 |
+
+### 1.4 重点检查场景（最容易漏）
+
+- **条件判断** — PRD 说"当 X 时做 Y"，if 条件是否完整？是否漏边界值？
+- **空值/零值** — PRD 提到的字段，代码在该字段为空时是否有处理？
+- **列表为空** — 列表展示是否有空状态/提示？
+- **并发/时序** — 多步操作是否处理了中间状态？
+- **权限控制** — PRD 提到的按钮/操作，是否加了权限判断？
+- **前后端一致** — 同一条规则前后端是否都实现了？
+
+### 1.5 问题记录模板
+
+发现问题时按如下格式逐条记录（供最终汇总报告引用）：
+
+**❌ 实现偏差 / 🔴 未实现 / ⚠️ 部分实现**：
+
+```markdown
+##### [条目ID] <PRD 原文摘要>
+- **PRD 要求**：<原文>
+- **实际实现**：<代码行为描述>
+- **代码位置**：<文件路径:行号>
+- **偏差/缺失说明**：<具体差异或缺失点>
+```
+
+**🟡 文案不一致**（用表格汇总）：
+
+| PRD 文案 | 代码文案 | 代码位置 |
+|---------|---------|---------|
+
+> **如果发现 ❌ 实现偏差或 🔴 未实现，立即暂停**，展示问题并询问用户：
+> - 先修复再继续后续检查？
+> - 还是先跑完全部检查，最后统一修复？
+
+---
+
+## Step 2: 实现假设验证
+
+**重点**：API 响应结构、组件生命周期、历史数据兼容性等假设是否正确？大多数实现 bug 不是逻辑错误，而是前提假设错了。
+
+根据变更类型选择适用的 Dimension 检查：
+
+### Dimension A: API Contract（调用了已有 API 时）
+
+**Trigger**：前端新增/修改了对后端 API 的调用
+
+**Checklist**：
+- [ ] 读过 Controller/Handler 源码，确认实际响应结构？
+- [ ] 找到项目中已有的同 API 调用代码作为参考？
+- [ ] 请求参数名、类型、默认值从源码确认（非凭记忆）？
+- [ ] 分页接口：确认了分页字段名和起始页码？
+
+**典型错误假设**：
+
+| 错误假设 | 实际情况 |
+|---------|---------|
+| `res.data.data` 是数组 | 实际是 `{ items: [], total }` 分页结构 |
+| 参数名是 `page` | 实际是 `p`，且从 1 开始 |
+| 响应直接是业务数据 | 实际包了一层 `{ success, message, data }` |
+
+### Dimension B: Component Context（在容器内使用组件时）
+
+**Trigger**：在 Modal / Drawer / Tab / 条件渲染块内使用有状态组件
+
+**Checklist**：
+- [ ] 确认容器关闭/切换时是否销毁子组件？
+- [ ] 如需保持状态：是否用了 keepDOM / destroyOnClose={false} 等配置？
+- [ ] 受控组件的 value 与外部 state 是否正确绑定？
+- [ ] 找到项目中同容器内的组件用法作为参考？
+
+**典型错误假设**：
+
+| 错误假设 | 实际情况 |
+|---------|---------|
+| Modal 关闭后表单状态保留 | 默认销毁子组件，再开状态丢失 |
+| value 传了就是受控 | 某些组件需 initValue + value 配合 |
+| 组件在任何地方行为一致 | 容器上下文会影响挂载/卸载行为 |
+
+### Dimension C: Data History（修改了数据模型时）
+
+**Trigger**：数据库表新增/修改了字段
+
+**Checklist**：
+- [ ] 历史记录的新字段值是什么（空/零值/null）？
+- [ ] 用新字段过滤时，历史数据能否被正确查到？
+- [ ] 是否需要降级查询路径（如从其他表补查历史数据）？
+- [ ] 写入链路中新字段的值从哪来？来源是否可靠？
+
+**典型错误假设**：
+
+| 错误假设 | 实际情况 |
+|---------|---------|
+| 加了字段就有数据 | 旧记录新字段全是零值/空值 |
+| 只查聚合表就够了 | 聚合表缺维度，需从明细表降级查询 |
+| 字段值肯定有 | 某些调用链路中该值可能为空 |
+
+### Dimension D: Data Flow Trace（跨层变更时）
+
+**Trigger**：变更涉及 前端 ↔ API ↔ 数据库 的数据传递
+
+**Checklist**：
+- [ ] 模拟一条完整请求路径：前端发什么 → 后端收什么 → 查出什么 → 返回什么 → 前端解析什么？
+- [ ] 前端参数名 === 后端 Query/Body 参数名？
+- [ ] 后端返回结构 === 前端解析结构？
+- [ ] 空值/零值场景：不填该字段时，每一层的行为是否正确？
+
+**典型错误假设**：
+
+| 错误假设 | 实际情况 |
+|---------|---------|
+| 代码看起来对就能跑 | 参数名差一个字母、嵌套差一层 |
+| 只检查非空路径 | 空值路径才是出 bug 最多的地方 |
+| 前后端分别看都没问题 | 放一起跑时数据对不上 |
+
+### Dimension E: Verification Tests（验证关键假设的测试）
+
+**Trigger**：任何涉及 Dimension A-D 的变更
+
+光靠肉眼审查不够，关键假设必须有可运行的验证手段：
+
+- **API Contract 验证**：写请求测试验证实际响应结构与解析匹配，覆盖 happy + 空值/零值
+- **数据模型验证**：用真实数据（含历史旧记录）验证过滤/聚合结果
+- **跨层数据流验证**：端到端测试完整路径，覆盖空参数、特殊字符、零值
+
+**验证原则**：
+- 不要求高覆盖率，但每个 Dimension 中发现的关键假设至少有一个测试保护
+- 优先写能暴露"想当然"问题的测试，而非走过场的 happy path
+- 如果无法写自动化测试，记录手动验证步骤和预期结果
+
+**典型错误做法**：
+
+| 错误做法 | 正确做法 |
+|---------|---------|
+| 只写 happy path 测试 | 优先覆盖假设最脆弱的路径 |
+| 测试写了但没跑 | 测试必须实际运行并通过 |
+| "这个太简单不用测" | 越简单的假设越容易错（参数名、嵌套层级） |
+
+### Common Issues Quick Reference（假设类 bug 速查）
+
+| Issue | Root Cause | Prevention |
+|-------|------------|------------|
+| API 调用返回 undefined | 响应结构假设错误 | 读 Controller 确认 |
+| 组件状态莫名丢失 | 容器销毁了子组件 | 检查容器生命周期 |
+| 筛选后数据为空 | 历史记录缺字段 | 验证旧数据查询路径 |
+| 参数传了但后端没收到 | 参数名不匹配 | 源码级确认参数名 |
+| 看着对但跑不通 | 只做了静态审查 | 模拟完整数据流 |
+
+> **如果发现假设错误**，同样立即暂停询问用户（先修复 or 跑完再统一修）。
+
+---
+
+## Step 3: 跨层完整性与代码规范检查
+
+按 `.agents/skills/trellis-check/SKILL.md` 执行。
+
+**重点**：变更涉及的所有层、所有引用点是否都同步更新了？代码是否符合项目 spec 中的编码规范？lint 和 typecheck 是否通过？
+
+---
+
+## 输出：汇总报告
+
+所有检查完成后，输出一份汇总报告：
+
+```markdown
+## Check All 汇总报告
+
+### 任务: <任务名称>
+
+---
+
+### 各维度结果
+
+| 维度 | 状态 | 问题数 | 关键问题 |
+|------|------|--------|---------|
+| PRD 实现 | ✅/❌ | N | <最严重的问题摘要> |
+| 假设验证 | ✅/❌ | N | <最严重的问题摘要> |
+| 跨层完整+规范 | ✅/❌ | N | <最严重的问题摘要> |
+
+### 问题清单（按优先级排序）
+
+#### P0 — 功能性 BUG（来自 Step 1 / Step 2）
+<PRD 实现偏差 / 🔴 未实现 / 假设错误>
+
+#### P1 — 完整性+规范问题（来自 Step 3）
+<跨层遗漏 / lint / typecheck / 规范违反>
+
+### 结论
+- <总体评价：整体完成度>
+- <建议修复顺序：P0 先修，P1 可视情况合并修>
+```
+
+---
+
+## 修复问题（需用户确认）
+
+如果发现问题，**先展示报告，获得用户确认后再修复**。
+
+修复时遵循：
+- **按严重程度排序**：❌ 实现偏差 > 🔴 未实现 > ⚠️ 部分实现 > 🟡 文案不一致 > P1 完整性/规范
+- **每修一条标注 PRD 条目 ID 或问题位置**
+- **修复后重新验证该条目**
+
+---
+
+## 使用时机
+
+- **开发完成后、提交前** — 作为 `trellis-finish-work` 之前的全面检查
+- **Code Review 前** — 自查一遍再提交 MR
+- **不确定改动质量时** — 跑一遍全量检查心里有底
+
+---
+
+## 注意事项
+
+- 每个维度独立输出报告，最后汇总
+- 如果某个维度发现严重问题（❌ / 🔴），会暂停询问是否先修复
+- 如果当前任务没有 PRD，自动跳过 Step 1，从 Step 2 开始
+- 只想快速检查某一维度：
+  - 只查规范/跨层：直接用 `trellis-check` skill
+  - 只查 PRD 或假设：在 prompt 里指定"只做 Step 1"或"只做 Step 2"
+
+---
+
+## 反模式（避免）
+
+- ❌ 不读代码，凭"应该实现了"就标记通过
+- ❌ 只检查 happy path，忽略 PRD 提到的边界/异常场景
+- ❌ 文案只看"意思对"就通过（必须逐字一致）
+- ❌ 只查后端不查前端，或反之
+- ❌ 检查报告中加入 PRD 之外的改进建议（只对照 PRD，不发挥）
+- ❌ 发现问题直接改，不经用户确认
+- ❌ 委派给子 agent 跑各 Step（见执行模式段）