@ibotor/smart-trellis 0.5.23 → 0.5.24

package/dist/templates/common/bundled-skills/trellis-dev-preflight/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: trellis-dev-preflight
+description: Use when starting frontend feature work, bug fixes, UI refactors, Vue or React changes, or any request that says to avoid unrelated code, preserve copy, keep diffs small, define component boundaries, or prepare before implementation.
+---
+
+# Frontend Dev Preflight
+
+## Overview
+
+在前端写代码前先锁定范围、边界、文案、格式和验证方式。这个 skill 是 `trellis-quality-review` 的前置版：它不做完成后 review，而是在动手前减少 scope creep、组件堆叠、无关文案改动和格式化噪音。
+
+## When to Use
+
+用于开始任何前端实现前，尤其是：
+- Vue、React、Next、Vite、Pinia、Vue Router、组件、样式、表单、表格、弹窗、状态、hook/composable 改动；
+- 用户说“轻量改动”“别动无关代码”“只改当前需求”“不要重构”“不要改文案”；
+- 任务可能涉及多个文件、组件拆分、API/types、mock 数据或验证命令；
+- 实现前需要先判断是否应简化 workflow，而不是进入完整大型流程。
+
+不用于纯后端任务。若前端实现已经完成并需要交付前复核，改用 `trellis-quality-review`。
+
+## Required Sub-Skills
+
+- **REQUIRED:** 先使用 `using-superpowers`，除非已经激活。
+- **REQUIRED for Vue:** 涉及 `.vue`、Vue Router、Pinia、Vite Vue 时使用 `vue-best-practices`。
+- **REQUIRED for React/Next:** 涉及 React 或 Next.js 时使用 `vercel-react-best-practices`。
+- **AFTER IMPLEMENTATION:** 前端实现完成后，使用 `trellis-quality-review` 或轻量 inline review。
+- **BEFORE FINAL CLAIM:** 完成声明前使用 `verification-before-completion`。
+
+## Preflight Gate
+
+写代码前完成这个门禁。轻量任务可以用 4-6 行，复杂任务再展开。
+
+```text
+本次目标：
+本次不做：
+允许修改：
+禁止修改：
+验证计划：
+```
+
+如果当前需求不清楚，最多问一个阻塞实现的问题；不要把非阻塞细节变成问卷。
+
+## Scope Lock
+
+默认只修改：
+1. 直接实现当前需求的代码；
+2. 为了让当前需求正确、类型安全、lint-clean、buildable 所必需的邻近代码。
+
+默认不修改：
+- 无关旧代码；
+- 历史 lint/type 问题；
+- 无关样式、布局、路由、接口形状；
+- 无需求支撑的重命名、重构、抽象、文件移动；
+- 无关文档、README、CI、依赖配置。
+
+如果必须触碰邻近代码，在动手前把它归类为“必要邻近修改”。如果归类不清楚，询问用户。
+
+## Boundary Map
+
+中型以上前端任务，写代码前给出简短边界图：
+
+```text
+route/page：页面编排，只组合区块和路由级状态
+container：业务区块组合，连接数据和组件
+component：单一 UI 区块，typed props/emits 或 typed props/callbacks
+composable/hook：状态、副作用、请求流程、订阅、缓存
+api/types：接口边界和 DTO/VO 类型
+helper：当前 feature 内纯逻辑，只有复用明确时才抽出
+mock：集中放在 mock adapter 或本地 mock 文件，不散落在正式组件里
+```
+
+轻量修复不强制拆分文件；优先最小 diff。只有当一个文件同时承担编排、多个 UI 区块、状态副作用、格式化逻辑并影响当前需求时，才考虑拆分。
+
+## Copy Fidelity Before Coding
+
+用户可见文案是产品行为。除非需求明确要求，不要修改：
+- label、placeholder、tooltip、helper text；
+- 按钮、弹窗、空状态、表格列标题；
+- 校验提示、确认文案、错误提示；
+- radio/checkbox/select 的选项文案、描述和顺序。
+
+如果新增文案不可避免，优先使用需求原文；没有原文时使用最小必要文案，并在总结中说明。
+
+## Formatting Fidelity Before Coding
+
+格式变化也是代码变化。默认：
+- 不运行会重排旧代码的大范围 formatter 或 `eslint --fix`；
+- 不为了统一风格重排无关旧代码；
+- 只格式化新增代码和当前必要修改块；
+- 如果 formatter 与范围控制冲突，优先保护 scope，并报告冲突。
+
+## Existing State First
+
+修复 UI 状态、loading、表单、请求、弹窗、筛选、分页前，先查是否已有来源：
+- form library 的 submitting/validating 状态；
+- mutation/query hook 的 loading/error/success 状态；
+- 组件 props、store、route query、现有 composable/hook；
+- 已有 formatter、validator、table/modal/upload helper。
+
+不要重复造状态。只有现有来源不满足当前需求时，才新增状态或 helper。
+
+## Verification Plan
+
+实现前先决定最小验证，不需要马上运行：
+- scoped lint；
+- typecheck；
+- 相关单测；
+- 相关 build；
+- 手动交互路径或浏览器验证，若任务依赖 UI 行为。
+
+如果预计全量验证会被历史问题阻塞，计划中说明将使用 scoped 验证，并在最终总结中区分历史失败和当前改动。
+
+## Quick Templates
+
+### 轻量任务
+
+```text
+本次目标：[一句话]
+本次不做：不重构、不改无关文案、不格式化旧代码
+允许修改：[文件/目录]
+禁止修改：[文件/目录/类型]
+验证计划：[最小命令]
+```
+
+### 中型任务
+
+```text
+本次目标：[一句话]
+本次不做：[明确排除项]
+允许修改：[route/page/component/composable/api/types/mock]
+禁止修改：[无关模块、全局组件、依赖、CI、文档等]
+边界图：
+- route/page：
+- component：
+- composable/hook：
+- api/types：
+- mock：
+验证计划：
+```
+
+## Common Mistakes
+
+| Mistake | Correction |
+| --- | --- |
+| 一上来写代码 | 先锁定目标、不做事项、允许/禁止修改、验证计划 |
+| 把 review skill 当前置 skill | 前置只做约束和设计，完成后再用 `trellis-quality-review` |
+| 轻量任务也拆很多文件 | 轻量任务优先最小 diff，只在边界明显失控时拆分 |
+| 顺手修历史 lint | 历史问题记录在 Notes，除非阻塞当前需求 |
+| 顺手润色文案 | 文案是产品行为，没有需求就不改 |
+| 运行 broad formatter | 只格式化新增或必要修改块 |
+| 新增重复 loading/form 状态 | 先找已有 form/mutation/store/composable 状态 |
+| mock 数据散落在组件里 | 放入明确 mock adapter 或本地 mock 文件 |
+
+## Final Handoff Reminder
+
+实现完成后，用 `trellis-quality-review` 检查：
+- Scope 是否越界；
+- Formatting Fidelity 是否保真；
+- Copy Fidelity 是否保真；
+- 是否有当前改动引入的死代码；
+- 验证命令和结果是否明确。

package/dist/templates/common/bundled-skills/trellis-quality-review/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: trellis-quality-review
+description: Use after frontend implementation or refactor work when changed code needs senior-level review for requirement scope control, component boundaries, dead code, copy/formatting fidelity, framework conventions, and verification before handoff.
+---
+
+# Trellis Quality Review
+
+## Overview
+
+Review finished frontend changes like a senior frontend engineer. Protect the requested requirement from scope creep first, then improve structure only where it directly helps the current change, remove current-work dead code, preserve user-visible behavior, and verify before claiming completion.
+
+## When to Use
+
+Use after frontend implementation or refactor, especially when:
+
+- components, composables, hooks, routes, styles, or UI state changed
+- code feels piled into one file
+- the user asks for review, cleanup, encapsulation, component splitting, or dead-code removal
+- handoff requires confidence that lint/typecheck/tests still pass
+- the diff may contain unrelated formatting, copy, or broad cleanup churn
+
+Do not use for purely backend-only changes.
+
+## Required Sub-Skills
+
+- Use `using-superpowers` first if not already active.
+- For Vue, `.vue`, Vue Router, Pinia, or Vite Vue changes, use `vue-best-practices`.
+- For React or Next.js changes, use `vercel-react-best-practices`.
+- Before final completion claims, use `verification-before-completion`.
+
+## Reference Routing
+
+Use `references/decision-tree.md` after reading this file to decide which deeper references are required. Read only the reference files triggered by the current diff:
+
+- `docs/overview.md` — read when the user asks for a human-facing explanation of this skill's architecture, workflow, and maintenance model.
+- `references/decision-tree.md` — always read first; routes fast path, framework, copy, formatting, suspicious-pattern, verification, and report checks.
+- `references/small-change-fast-path.md` — read when the request looks like a tiny localized UI, copy, style, or config change.
+- `references/scope-control.md` — always read when frontend diff exists and the fast path does not apply; defines the requirement boundary and out-of-scope handling.
+- `references/formatting-fidelity.md` — read when modified existing files may include whitespace, wrapping, indentation, or formatter churn.
+- `references/copy-fidelity.md` — read when user-visible text, labels, placeholders, helper text, option order, or messages changed.
+- `references/framework-rules.md` — read for Vue, React, Next.js, routing, store, composable, hook, component, or styling conventions.
+- `references/safe-refactor-boundaries.md` — read before splitting components, extracting composables/hooks, moving helpers, or changing ownership.
+- `references/severity.md` — read before deciding whether to fix, defer, or only note findings.
+- `references/verification-selection.md` — read before choosing lint, typecheck, test, build, or diff-only verification.
+- `references/report-format.md` — read before final response.
+
+Use `scripts/diff_scans.sh` when available to collect changed frontend files and high-signal diff-only checks. Treat script output as review input, not as automatic proof.
+
+## Review Workflow
+
+1. Restate the current requirement in one sentence.
+2. Inspect `git status` and `git diff HEAD` before editing.
+3. Follow `references/decision-tree.md` to load only the required deeper references.
+4. If the change qualifies for `references/small-change-fast-path.md`, keep review to diff inspection and report the limited verification.
+5. Otherwise, apply the scope-control gate from `references/scope-control.md`.
+6. Inspect changed files and adjacent dependencies only as needed for the requirement.
+7. Run or manually reproduce the diff-only scans from `scripts/diff_scans.sh`.
+8. Apply formatting fidelity and copy fidelity checks when their triggers are present.
+9. Build a short responsibility map for in-scope code:
+   - route/page/container: orchestration only
+   - component: one UI section with typed props/emits
+   - composable/hook: stateful logic and side effects
+   - helper: pure feature-local logic
+10. Read `references/safe-refactor-boundaries.md` before any component split, composable/hook extraction, helper move, or ownership change.
+11. Read `references/severity.md` and classify findings before deciding whether to fix, defer, or only note them.
+12. Apply targeted fixes inside the requirement boundary:
+   - remove dead code introduced or exposed by current work
+   - split or merge files only when it clarifies this requirement
+   - fix newly introduced lint/type issues on changed lines
+   - restore out-of-scope formatting or copy changes when safe
+   - add concise comments only for non-obvious business rules or side effects
+13. Read `references/verification-selection.md` before choosing lint, typecheck, test, build, or diff-only verification.
+14. Re-run relevant verification and read outputs.
+15. Final response must follow `references/report-format.md`.
+
+## Operating Principles
+
+- Requirement scope wins over opportunistic cleanup.
+- User-visible copy and option order are product behavior.
+- Formatting-only diffs are still code changes.
+- Fix current-work issues; do not expand into unrelated legacy cleanup.
+- Prefer small, behavior-preserving edits unless the user explicitly asks for broader refactoring.

package/dist/templates/common/bundled-skills/trellis-quality-review/docs/overview.md

@@ -0,0 +1,331 @@
+# Trellis Quality Review 介绍
+
+## 目的
+
+`trellis-quality-review` 是一个用于前端实现或重构完成后的结构化 review skill。它的目标是让 agent 像资深前端工程师一样审查当前前端 diff：保护需求范围、防止 scope creep、识别当前改动引入的质量问题、避免无关清理、选择合适的验证方式，并输出有证据支撑的交付报告。
+
+这个 skill 的设计是克制的。它不是为了把整个代码库变得更干净，而是为了让**当前这一次前端改动**变得安全、聚焦、可维护、可验证。
+
+## 两个核心思想
+
+### 1. 克制感：当前需求边界 > 代码洁癖
+
+这是这个 skill 最重要的设计取向。
+
+很多 review 流程的问题是：一旦发现旧代码不优雅、组件太大、命名不统一、历史 lint 不干净，就会顺手扩大修改范围。`trellis-quality-review` 反过来要求 agent 先判断问题是否属于当前 diff：
+
+- 当前 diff 引入的问题，可以按严重程度处理。
+- 为当前需求正确性所必需的相邻问题，可以作为 necessary adjacent 处理。
+- 历史问题、未触碰代码、来源不明的用户改动，默认只记录为 Note Only。
+- 即使代码可以更优雅，也不能为了“代码洁癖”扩大本次 diff。
+
+因此它的默认心智模型是：**发现问题不等于立刻修复；先判断边界，再决定行动。**
+
+### 2. 封装思想：合理拆分，不制造抽象噪音
+
+这个 skill 支持组件拆分、composable/hook 抽取、helper 移动和类型边界整理，但它反对“为了拆而拆”。
+
+它判断封装是否合理时，会优先看职责是否清晰、边界是否由当前需求触发、抽取后接口是否更小：
+
+- page / route / container 应主要负责路由、数据加载和页面编排。
+- component 应负责一个可命名的 UI 区块。
+- composable / hook 应承载状态、副作用、异步流程和派生状态。
+- helper 应承载纯格式化、映射、校验和计算逻辑。
+- api / types 应表达外部接口和共享契约边界。
+
+安全封装的判断不是“文件大不大”，而是：当前 diff 是否让某个职责变得独立、可命名、可验证。如果抽取会带来大量 props 透传、移动未触碰代码、改变 copy/layout/event timing，或者只是制造 `Common`、`Base`、`Utils` 这类模糊抽象，就应该停止，并把它记录为后续建议。
+
+一句话总结：**该拆时拆出清晰职责，不该拆时保持局部，避免把扎堆变成过度工程。**
+
+## 什么时候使用
+
+当前端工作已经实现或重构完成后，可以使用这个 skill，尤其是 diff 涉及：
+
+- Vue、React、Next.js、组件、路由、store、composable、hook 或 UI 状态
+- 表单、表格、弹窗、抽屉、上传流程、校验逻辑、API payload 映射
+- 用户可见文案、label、placeholder、选项顺序、helper text、提示信息
+- 容易混入无关格式化变更的文件
+- 交付前需要说明 lint、typecheck、测试或 build 状态的改动
+
+纯后端改动不适合使用这个 skill。对于非常小的前端改动，它内置了“微改快速通道”，在合适时只做 diff inspection，不进入完整 review。
+
+## 设计原则
+
+下面的设计原则是对上面两个核心思想的展开：先保持克制，再做安全封装。
+
+### 1. 需求范围优先
+
+skill 会先复述当前需求，并把需求和当前 diff 对比。每个变更块都应该被分类为：
+
+- **In requirement**：直接实现或验证用户要求的改动
+- **Necessary adjacent**：为了让当前改动正确、类型通过、lint 通过或可构建而必要的相邻改动
+- **Out of scope**：无关格式化、文案润色、宽泛重构、历史清理、重命名抽象、非必要行为变更
+
+这可以避免常见的 review 失败模式：agent 顺手优化无关代码，导致 diff 被扩大。
+
+### 2. 当前 diff 边界
+
+默认 review 边界是当前未提交 diff：`git diff HEAD`，包含 staged 和 unstaged 改动。
+
+如果用户要求只 review staged 内容，边界变成 `git diff --cached`。如果用户要求按分支或 PR 风格 review，边界可以是指定 base ref，例如 `main`。
+
+历史问题和未触碰文件通常归为 **Note Only**。除非它们阻塞当前需求，否则不应在本次 review 中修复。
+
+### 3. 文案和格式化都很敏感
+
+用户可见文案和选项顺序是产品行为，不是无害字符串。格式化-only diff 也是代码变更，因为它会增加 review 难度，并可能掩盖逻辑变化。
+
+因此这个 skill 把 copy fidelity 和 formatting fidelity 从普通代码质量检查中单独拆出来，避免 agent 无意中保留无关 churn。
+
+### 4. 安全重构，而不是过度重构
+
+这个 skill 支持组件拆分和逻辑抽取，但只在当前 diff 形成明确职责边界时进行。文件大本身不是拆分理由。
+
+一个安全的 refactor 至少需要满足：被抽出的职责由当前需求触碰；边界可以清楚命名；新接口比隐藏的复杂度更小；行为、文案、布局和公开契约保持不变。
+
+### 5. 先分级，再修复
+
+发现问题后先分级，再决定是否修复：
+
+- **Blocker**：交付前必须修
+- **Must Fix Before Handoff**：当前 diff 引入、不能带入交付的问题
+- **Should Fix If In Scope**：真实问题，但只有在范围内且改动小才修
+- **Note Only**：历史、未触碰、来源不明或超出范围的问题
+
+这能让 review 更像资深工程师：真正重要的问题不会被淹没，历史问题也不会劫持当前任务。
+
+### 6. 验证方式匹配风险
+
+这个 skill 避免两个极端：既不盲目跑所有命令，也不会对有意义的逻辑改动跳过验证。
+
+验证方式应根据当前 diff 的风险选择：
+
+- 细小 UI / copy / style / config 改动：diff inspection 可能足够
+- 类型、model、payload 改动：优先 typecheck 和相关测试
+- Vue SFC 改动：优先 lint 和 Vue/typecheck 脚本
+- React/Next route 或 server/client 边界改动：lint/typecheck，必要时 build
+- 历史失败：单独报告，不要声称全部通过
+
+## 目录结构
+
+```text
+trellis-quality-review/
+├── SKILL.md
+├── docs/
+│   └── overview.md
+├── references/
+│   ├── decision-tree.md
+│   ├── small-change-fast-path.md
+│   ├── scope-control.md
+│   ├── formatting-fidelity.md
+│   ├── copy-fidelity.md
+│   ├── framework-rules.md
+│   ├── safe-refactor-boundaries.md
+│   ├── severity.md
+│   ├── verification-selection.md
+│   └── report-format.md
+├── scripts/
+│   └── diff_scans.sh
+└── evals/
+    └── evals.json
+```
+
+## 文件职责
+
+### `SKILL.md`
+
+入口文件。它定义 skill 的使用场景、依赖的子 skill、reference 路由模型、整体 workflow 和操作原则。
+
+它应该保持简短。详细规则应放在 `references/` 中。
+
+### `docs/overview.md`
+
+给人看的说明文档。它解释这个 skill 的架构、设计意图、执行流程和维护方式。它适合用于分享、交接和理解整体设计，不是每次运行时都必须读取的执行规则。
+
+### `references/decision-tree.md`
+
+执行路由器。它根据 diff 中的信号决定 agent 应该继续读取哪些更细的 reference，例如：
+
+- 是否是微改
+- 是否涉及 Vue / React / Next
+- 是否有组件边界问题
+- 是否有格式化 churn
+- 是否有文案变化
+- 是否有可疑前端模式
+- 是否需要 severity 分级
+- 是否需要选择验证命令和最终报告格式
+
+这个文件的作用是减少漏检查。
+
+### `references/small-change-fast-path.md`
+
+定义什么时候前端改动足够小，可以不进入完整 review，也不默认跑 broad lint/typecheck/test/build。
+
+典型例子包括单行间距、宽度、颜色、明确要求的文案、小范围样式改动，并且不能涉及 API、状态流、类型、校验或数据转换。
+
+使用该路径时，最终报告必须说明为什么只做了有限验证。
+
+### `references/scope-control.md`
+
+定义需求边界和变更块分类方式。它是防止 scope creep 的核心护栏。
+
+### `references/formatting-fidelity.md`
+
+说明如何识别和处理 formatting-only churn，例如对比普通 diff 和忽略空白 diff：
+
+```bash
+git diff HEAD -- path/to/file
+git diff -w HEAD -- path/to/file
+```
+
+### `references/copy-fidelity.md`
+
+说明如何 review 用户可见文案和选项顺序。覆盖 label、placeholder、helper text、button text、validation message、modal title、table column title、本地化字符串等。
+
+### `references/framework-rules.md`
+
+提供 Vue、React、Next.js、样式、路由、store、composable、hook 和组件边界相关的前端 review 规则。
+
+它不会复制完整框架最佳实践，而是把更深入的 Vue 和 React/Next 细节交给专门的 `vue-best-practices` 和 `vercel-react-best-practices` skill。
+
+### `references/safe-refactor-boundaries.md`
+
+定义什么时候可以安全拆组件、抽 composable/hook、移动 helper 或改变 ownership。它同时防止“职责扎堆”和“过度封装”。
+
+### `references/severity.md`
+
+定义 review 严重程度模型：
+
+- Blocker
+- Must Fix Before Handoff
+- Should Fix If In Scope
+- Note Only
+
+它帮助 agent 判断哪些问题现在必须修，哪些应该延后，哪些只需要记录。
+
+### `references/verification-selection.md`
+
+定义如何根据 diff 风险选择验证命令。它说明如何发现 package scripts，如何选择 lint/typecheck/test/build，如何处理命令不存在，以及如何报告历史失败。
+
+### `references/report-format.md`
+
+定义最终交付报告格式：
+
+- Scope Check
+- Severity
+- Formatting Fidelity
+- Copy Fidelity
+- Changed
+- Removed
+- Verified
+- Notes
+
+### `scripts/diff_scans.sh`
+
+高信号 diff 扫描脚本。支持：
+
+```bash
+scripts/diff_scans.sh
+scripts/diff_scans.sh --files
+scripts/diff_scans.sh --cached
+scripts/diff_scans.sh --base main
+scripts/diff_scans.sh --json
+```
+
+它会扫描前端变更文件、调试代码、TypeScript 风险、Vue 风险、React/Next 浏览器边界风险，以及潜在 copy/accessibility 变化。
+
+扫描命中只是信号，不是自动缺陷。agent 必须结合上下文再决定是否修复。
+
+### `evals/evals.json`
+
+skill 的评估场景。覆盖 scope control、copy/formatting fidelity、small-change fast path、staged-only review、severity classification、verification selection、diff scans 和 safe refactor boundaries。
+
+## 典型 review 流程
+
+一次正常 review 通常按这个顺序进行：
+
+1. 复述当前需求。
+2. 检查当前 review 边界，通常是 `git status` 和 `git diff HEAD`。
+3. 读取 `decision-tree.md`，决定后续需要哪些检查。
+4. 如果 diff 符合微改条件，走 small-change fast path。
+5. 否则进入 scope control。
+6. 运行或手动复现 `diff_scans.sh`。
+7. 如果触发，执行 formatting fidelity 和 copy fidelity 检查。
+8. 如果涉及结构性 review，应用 framework rules 和 safe refactor boundaries。
+9. 对发现的问题做 severity 分级。
+10. 只修复当前范围内的问题。
+11. 选择并运行合适的验证命令。
+12. 按规定格式输出最终报告。
+
+## 示例场景
+
+### 细小 UI 改动
+
+表格列宽从 `120` 改为 `140`。
+
+期望行为：
+
+- 使用 small-change fast path
+- 只检查局部 diff
+- 默认跳过 broad lint/typecheck/test/build
+- 报告本次只使用 diff inspection 作为有限验证
+
+### 逻辑改动中混入文案 churn
+
+需求是增加一个必填 domain 字段，但 diff 同时改写了 radio helper text 并调整了选项顺序。
+
+期望行为：
+
+- 保留 domain 字段相关改动
+- 在安全时恢复无关 helper text 和选项顺序
+- 将 out-of-scope copy change 分类为 Must Fix Before Handoff
+- 报告 copy fidelity 检查结果
+
+### 安全抽取弹窗
+
+一个 Vue 页面改动新增了 edit modal，里面包含字段、校验、提交处理、loading 状态和 API mapping，并且这些逻辑都塞进了一个已经很大的页面。
+
+期望行为：
+
+- 识别 modal 是当前 diff 引入的、可命名的独立职责
+- 只考虑抽取 modal 边界
+- 不重构未触碰的 table/search 区域
+- 报告为什么这个抽取是安全的
+
+### 历史类型错误
+
+当前 diff 新增了一个 `console.log`，改了一个与需求无关的 placeholder，同时项目原本就在未触碰的 legacy 文件里有 `vue-tsc` 错误。
+
+期望行为：
+
+- 移除当前 diff 新增的 `console.log`
+- 恢复无关 placeholder
+- 将历史 `vue-tsc` 错误分类为 Note Only
+- 不修改 legacy 文件
+
+## 与 hooks 的关系
+
+这个 skill 不依赖 hooks。它是一个给 agent 使用的判断型 workflow。
+
+hooks 可以作为补充，用来自动扫描或强制简单规则，例如：
+
+- commit 前运行 `diff_scans.sh --cached`
+- 阻止 staged diff 中出现 `console.log` 或 `debugger`
+- 当前端文件发生变化但没有 review 时给出提醒
+- 输出 JSON 扫描结果给自动化流程使用
+
+hooks 通常应该负责检测和提示，不应该自动执行结构性重构或文案修改。
+
+## 维护建议
+
+保持这个 skill 模块化：
+
+- 运行时执行规则放到 `references/`
+- 给人看的说明放到 `docs/`
+- 确定性的辅助工具放到 `scripts/`
+- 评估场景放到 `evals/`
+- `SKILL.md` 保持为简短路由器
+
+不要把宽泛的前端最佳实践百科塞进这里。更深入的框架规则应该交给专门 skill，例如 `vue-best-practices` 和 `vercel-react-best-practices`。
+
+扩展这个 skill 时，优先添加一个聚焦规则，并配套一个 eval 场景；不要添加没有测试覆盖的大型 checklist。

package/dist/templates/common/bundled-skills/trellis-quality-review/evals/evals.json

@@ -0,0 +1,50 @@
+{
+  "skill_name": "trellis-quality-review",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Review my Vue form changes. The request was only to add a required domain field, but the diff also changed radio helper text, option order, and some line wrapping. Clean up only what belongs to the request and report verification.",
+      "expected_output": "The skill should identify out-of-scope copy and formatting changes, restore them when safe, keep the required domain field work, and report scope/copy/formatting checks."
+    },
+    {
+      "id": 2,
+      "prompt": "I finished a React settings page refactor. Please do a frontend quality review. Watch for unnecessary component splits, dead code from the current diff, and whether lint/typecheck should be run.",
+      "expected_output": "The skill should review component boundaries, remove current-work dead code only, avoid broad legacy cleanup, and provide exact verification commands and results."
+    },
+    {
+      "id": 3,
+      "prompt": "Check this frontend diff before handoff. It includes a new Vue table feature plus a couple of console.log and @ts-ignore lines added while debugging. Do not touch unrelated old warnings.",
+      "expected_output": "The skill should use diff-only scans, fix newly introduced suspicious lines, avoid unrelated legacy issues, and summarize skipped findings."
+    },
+    {
+      "id": 4,
+      "prompt": "Review a Next.js page change where the route component now owns data fetching, modal state, validation, and three UI sections. Decide if the current change needs component or hook extraction without over-abstracting.",
+      "expected_output": "The skill should apply framework rules, build a responsibility map, propose or perform targeted extraction only if it clarifies the current requirement, and verify behavior."
+    },
+    {
+      "id": 5,
+      "prompt": "This is a tiny Vue UI tweak: I only changed one table column width from 120 to 140. Please review it, but don't run the full lint/typecheck/build unless needed.",
+      "expected_output": "The skill should use the small-change fast path, inspect the localized diff, avoid full review and broad verification by default, and explicitly report limited diff-only verification."
+    },
+    {
+      "id": 6,
+      "prompt": "Review this Vue form validation change before handoff. It changes a required rule, a TypeScript form model, and one submit payload mapping. Pick the right verification commands without blindly running every script.",
+      "expected_output": "The skill should read verification-selection, choose typecheck plus relevant lint/tests when available, avoid unnecessary full build unless justified, and report exact commands, exit status, and any unrelated failures clearly."
+    },
+    {
+      "id": 7,
+      "prompt": "Review the staged frontend changes only. They include a Next.js TSX edit with a new use client directive, window access, an as any cast, and a label change. Use the diff scan helper if available and don't inspect unstaged work.",
+      "expected_output": "The skill should use diff_scans.sh --cached, treat scan hits as signals, inspect only staged current-work risks, route label changes to copy fidelity, and avoid touching unstaged or unrelated code."
+    },
+    {
+      "id": 8,
+      "prompt": "Review my current frontend diff. It adds one console.log, changes a placeholder unrelated to the request, and the project already has old vue-tsc errors in untouched legacy files. Classify what must be fixed versus what should only be noted.",
+      "expected_output": "The skill should read severity, classify added console.log and out-of-scope placeholder as Must Fix, classify unrelated historical vue-tsc errors as Note Only, avoid fixing legacy files, and report severity clearly."
+    },
+    {
+      "id": 9,
+      "prompt": "Review this Vue page diff. The current request added an edit modal with its own fields, validation, submit handler, loading state, and API mapping inside an already large page. Decide whether to extract it without touching the old table and search sections.",
+      "expected_output": "The skill should read safe-refactor-boundaries, identify the modal as a nameable current-diff responsibility, extract or recommend extracting only that boundary if safe, avoid refactoring untouched table/search code, and report why the boundary is safe."
+    }
+  ]
+}