flower-trellis 0.1.0

package/enhancements/0.6/.claude/skills/trellis-check-all/SKILL.md

@@ -0,0 +1,342 @@
+---
+name: trellis-check-all
+description: "Full pre-commit/PR review in 3 steps: spec-trio implementation correctness (code ↔ prd.md / design.md / implement.md when present) → 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.md`（必读）+ `design.md` / `implement.md`（若存在） |
+| 2 | 假设验证 | 假设对不对 | 源码/真实数据 |
+| 3 | 完整性+规范性（trellis-check） | 改全了没 + 写得规范吗 | git diff 影响范围 + spec 开发规范 |
+
+---
+
+## Step 0: 确认变更范围
+
+```bash
+git diff --name-only
+git log --oneline -10
+```
+
+如果无变更，提示用户并终止。
+
+读取当前任务的规划三件套：`prd.md`（必读，没有则跳过 Step 1 从 Step 2 开始）、`design.md`（若存在）、`implement.md`（若存在）。三件套由 trellis 的 session hook 自动加载，或手动确认任务目录。
+
+> **Lightweight 任务**：通常只有 `prd.md`，Step 1 内的 Design / Implement 维度自动跳过
+> **Complex 任务**：三件套齐全，Step 1 对照矩阵覆盖三层（行为 / 契约 / 执行清单）
+
+---
+
+## Step 1: 对照规划三件套检查实现
+
+**重点**：三件套（PRD / Design / Implement）中的每条规划是否都正确实现了？有没有行为偏差、契约不一致、执行清单漏落地？
+
+### 1.1 核心原则（不可违反）
+
+1. **规划三件套都是验收依据** — PRD 的 Requirement / AC 是**行为基线**；Design（若存在）的 API 契约、数据模型、数据流、rollback 设计是**技术基线**；Implement（若存在）的有序步骤是**落地基线**。三层都要在代码中找到对应实现，找不到即为缺失
+2. **逐条追踪，不跳不漏** — 不能只看 happy path，PRD 中提到的边界条件、异常处理、空值场景都要追踪
+3. **读代码，不猜代码** — 必须实际读到实现代码，不能因为"应该写了"就标记通过
+4. **文案逐字比对** — PRD 中的 UI 文案（按钮、提示语、Toast、弹窗、表头、placeholder）必须与代码中的字面值**完全一致**
+5. **只报事实，不加发挥** — 报告中只陈述 PRD 要求 vs 代码实现的差异，不要加入 PRD 之外的建议
+
+### 1.2 分解三件套为可验证条目
+
+按优先级提取以下条目（design / implement 维度仅在对应文件存在时启用）：
+
+**来自 `prd.md`（总是启用）**：
+1. **Acceptance Criteria** — 最直接的验证条目
+2. **Requirements** — 每条需求对应的行为
+3. **业务规则** — 条件判断、计算逻辑、状态流转
+4. **UI 文案** — 所有用户可见文字
+5. **边界/异常场景** — 空值处理、上限、错误提示等
+
+**来自 `design.md`（complex 任务启用）**：
+
+6. **Design 契约** — API 路径 / 方法 / 入参 / 出参、数据模型字段名+类型+约束、数据流路径、关键 tradeoff 决策、rollout / rollback 设计
+
+**来自 `implement.md`（complex 任务启用）**：
+
+7. **Implement 执行清单** — 每个有序步骤是否落地、validation commands 的前置条件是否满足（**静态检查**；真跑命令归 Step 3 的 trellis-check 或用户执行）、review gates 是否到位、rollback points 是否实际可用
+
+每条记录格式：`[条目ID] <三件套原文摘要> — 来源：<prd / design / implement 中位置>`
+
+### 1.3 逐条追踪代码实现
+
+根据条目类型定位实现：
+
+| 条目类型 | 搜索方法 |
+|---------|---------|
+| API 接口行为 | Controller → Service → DAO，追踪完整链路 |
+| 前端交互行为 | 组件文件，事件处理、状态管理 |
+| 数据校验规则 | 前端 rules + 后端 validator/service，两端都查 |
+| UI 文案 | grep 关键字，前端代码精确匹配 |
+| 计算/转换逻辑 | service 层，读具体算法 |
+| 状态流转 | 状态枚举 + 转换条件代码 |
+| Design 契约（API / schema） | 实际 Controller / DTO / DB migration，对照路径、方法、字段名、类型、必填、默认值 |
+| Implement 执行步骤 | 代码 / 配置 / 迁移脚本是否处于 implement 步骤要求的状态（如：步骤说"加索引"则验证 migration 文件存在） |
+
+对每条标记状态：
+
+| 状态 | 含义 |
+|------|------|
+| ✅ 已实现 | 代码正确实现了 PRD 要求（已读代码确认） |
+| ❌ 实现偏差 | 代码实现了，但行为与 PRD 描述不一致 |
+| 🔴 未实现 | 代码中找不到对应实现 |
+| ⚠️ 部分实现 | 核心逻辑有，但缺少边界/异常处理 |
+| 🟡 文案不一致 | UI 文案与 PRD 不逐字一致 |
+
+### 1.4 重点检查场景（最容易漏）
+
+- **条件判断** — PRD 说"当 X 时做 Y"，if 条件是否完整？是否漏边界值？
+- **空值/零值** — PRD 提到的字段，代码在该字段为空时是否有处理？
+- **列表为空** — 列表展示是否有空状态/提示？
+- **并发/时序** — 多步操作是否处理了中间状态？
+- **权限控制** — PRD 提到的按钮/操作，是否加了权限判断？
+- **前后端一致** — 同一条规则前后端是否都实现了？
+
+### 1.5 问题记录模板
+
+发现问题时按如下格式逐条记录（供最终汇总报告引用）：
+
+**❌ 实现偏差 / 🔴 未实现 / ⚠️ 部分实现**：
+
+```markdown
+##### [条目ID] <三件套原文摘要> ｜ 来源：<prd / design / implement>
+- **规划要求**：<原文>
+- **实际实现**：<代码行为描述>
+- **代码位置**：<文件路径:行号>
+- **偏差/缺失说明**：<具体差异或缺失点>
+```
+
+**🟡 文案不一致**（用表格汇总）：
+
+| 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 汇总报告
+
+### 任务: <任务名称>
+
+---
+
+### 各维度结果
+
+| 维度 | 状态 | 问题数 | 关键问题 |
+|------|------|--------|---------|
+| 三件套实现 | ✅/❌ | 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 开始
+- Step 1 对照矩阵随任务复杂度自动扩展：lightweight 仅查 prd 五类条目；complex 在场则追加 design 契约 + implement 执行清单两类条目
+- 只想快速检查某一维度：
+  - 只查规范/跨层：直接用 `trellis-check` skill
+  - 只查 PRD 或假设：在 prompt 里指定"只做 Step 1"或"只做 Step 2"
+
+---
+
+## 反模式（避免）
+
+- ❌ 不读代码，凭"应该实现了"就标记通过
+- ❌ 只检查 happy path，忽略 PRD 提到的边界/异常场景
+- ❌ 文案只看"意思对"就通过（必须逐字一致）
+- ❌ 只查后端不查前端，或反之
+- ❌ 检查报告中加入三件套之外的改进建议（只对照规划，不发挥）
+- ❌ 发现问题直接改，不经用户确认
+- ❌ 委派给子 agent 跑各 Step（见执行模式段）
+- ❌ Complex 任务下只对照 PRD，忽略 `design.md` / `implement.md`（三层都要查）
+- ❌ 把 `implement.md` 的 validation commands 真跑算到 Step 1（Step 1 是静态对照；真跑归 Step 3 或用户执行）

package/enhancements/0.6/.claude/skills/trellis-create-command/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: trellis-create-command
+description: "Create a new trellis entry as command or skill; writes agents copy and optionally skill-garden."
+---
+# Create New Trellis Entry
+
+创建一个新的 trellis 入口。支持两种形态：斜杠命令（command）或 Claude skill。
+
+> **0.6 取舍提示**：skill-garden 0.6 包默认全部 skill 化，不再维护 `.claude/commands/` 目录。形态选 command 时，**只在目标项目落 2 份**，不分发到 skill-garden 0.6 包（强制分发时需手动维护，不建议）。新建入口推荐选 skill 形态。
+
+---
+
+## 前置参考：trellis-meta
+
+> **本 skill 是流程骨架，深层架构 / 命名 / 文件分布以 `trellis-meta` 为准。**
+
+`trellis-meta` 是 Trellis 本地架构的权威参考 skill（类似 `.trellis/spec/guides/`，但范围是 trellis 自身的架构与定制入口）。创建新入口**前**，按以下顺序加载它的 references 作为决策依据：
+
+| 决策点 | trellis-meta 参考 |
+|--------|------------------|
+| skill / command / prompt / workflow 形态怎么选 | `references/platform-files/skills-and-commands.md` |
+| skill / command 的目录、frontmatter、命名、hook 联动 | `references/customize-local/change-skills-or-commands.md` |
+| 想加入 hook / 改 settings | `references/customize-local/change-hooks.md` + `references/platform-files/hooks-and-settings.md` |
+| 想改 agent（implement / check / research）行为 | `references/customize-local/change-agents.md` + `references/platform-files/agents.md` |
+| 想改 workflow phase / breadcrumb / routing | `references/customize-local/change-workflow.md` + `references/local-architecture/workflow.md` |
+| 想改 task lifecycle / spec 结构 / context 注入 | `references/customize-local/change-task-lifecycle.md` / `change-spec-structure.md` / `change-context-loading.md` |
+| 平台目录映射（.claude / .codex / .cursor / ...） | `references/platform-files/platform-map.md` |
+
+**操作建议**：
+
+1. 在执行 Step 0 之前，先调用 `Skill({skill: "trellis-meta"})` 加载基础架构视图
+2. 根据本次要创建的入口类型，按需 `Read` 上表中对应的 references 子文档
+3. 本 SKILL.md 下面的 Step 1-8 是**操作流程**；架构 / 命名 / 边界冲突时**以 trellis-meta 为准**
+
+> **不要凭空生成**：trellis-meta 的 references 已经把可定制入口、命名约定、目录结构、hook 注入点全列清楚，create-command 的产物必须落在这套结构内，不得发明新目录或新形态。
+
+---
+
+## 适用场景
+
+- 给项目加一个新 trellis 工具入口
+- 现有命令集不覆盖某类需求，需要扩展
+- 从零设计新的工作流步骤
+
+---
+
+## 执行步骤
+
+### Step 0: 确定路径
+
+**`<target>`（落地项目）**：默认 = 当前工作目录（`pwd`）。
+
+- 若用户没有明确说"在其他项目"，直接用当前项目
+- 若用户明确要在其他项目创建，改用其指定的绝对路径；本 skill 不主动 `cd`，只记住该路径用于后续写入
+- 若目标项目就是 skill-garden 本身（在 skill-garden 仓库里 `create-command`），`<target>` 与 `<skill-garden>` 指同一路径，**避免重复写入**（只写一次）
+
+**`<skill-garden>`（分发源，scope 含 skill-garden 时必需）**：默认 `/root/project/skill-garden`。
+
+- 路径不存在或与用户期望不符 → 询问用户确认
+- 无需分发时（scope = 只装本项目）整段忽略
+
+### Step 1: 收集基本信息
+
+与用户确认：
+
+| 项 | 说明 | 示例 |
+|----|------|------|
+| **name** | kebab-case，动词或动词短语开头 | `review-pr`、`sync-data`、`check-deps` |
+| **description** | 要完成什么、产出什么 | "检查 PR 代码变更是否符合项目规范" |
+| **scope** | 只装本项目 / 也装 skill-garden | 问用户：是否要分发到其他项目？ |
+
+### Step 2: 选形态（command vs skill）
+
+| 形态 | 何时选 | 触发方式 |
+|------|--------|---------|
+| **command** | 显式动作、高风险、需确认点（如 finish-work、continue） | `/trellis:<name>` |
+| **skill** | 自然语可触发、查询 / 分析 / 检查、低破坏性（如 check-all、extract-prd、draw-uml） | Claude 自动路由 + `/trellis-<name>` |
+
+决定不了时**推荐 skill**：自然语路由更灵活，显式斜杠仍可用。反过来，后悔做成 skill 想改 command 比较费事。
+
+**0.6 偏好**：0.6 主推 skill 化，新建入口默认 skill 形态；选 command 形态时确认是否有不可替代的"显式确认"诉求。
+
+### Step 3: 生成内容骨架
+
+按形态和复杂度生成初稿：
+
+**简单 skill / command**（< 50 行）：
+
+```markdown
+<frontmatter 仅 skill 有>
+# <标题>
+
+<1-2 行简介>
+
+## 适用场景
+- <触发点 1>
+- <触发点 2>
+
+## 执行步骤
+### Step 1: <动作>
+### Step 2: <动作>
+
+## 反模式
+- ❌ <误用 1>
+- ❌ <误用 2>
+```
+
+**复杂 skill / command**（50-300 行）：
+
+```markdown
+<frontmatter>
+# <标题>
+
+<简介>
+
+## 适用场景 / 前置条件
+
+## 执行步骤
+### Step 0-N: <动作，每步可执行，带 bash/代码示例>
+
+## 输出模板（必需）
+<markdown 模板>
+
+## 核心原则
+<5 条左右，每条有 why>
+
+## 反模式
+<5-7 条具体误用>
+```
+
+> **骨架风格参考**：读一个已有的 skill（如 `trellis-extract-prd` / `trellis-check-all` / `trellis-verify-task`）作风格锚点，保持项目内一致。
+
+### Step 4: Frontmatter 规则（skill 形态必需）
+
+**skill 版 frontmatter**：
+
+```yaml
+---
+name: trellis-<name>
+description: "<what> <when> <exclusion>"
+---
+```
+
+`description` 写法取决于**触发策略**：
+
+| 策略 | 长度 | 写法 |
+|------|------|------|
+| **Auto-routing**（常用） | 80–300 字 | 三段式：What（动词开头）+ When（中英触发词）+ Exclusion（"For X, use Y instead"）。Claude 按此匹配用户意图自动加载 |
+| **Manual-only**（偶尔用的管理工具） | 15–20 tokens | 单句动作 + 产出物。只靠用户 `/trellis-<X>` 显式触发，description 不作路由依据，节省每次对话的 skill 列表 token |
+
+**选哪种**：
+- 选 **Auto-routing** 当 skill 需要在对话中被自然语触发（如 `trellis-extract-prd`、`trellis-verify-task`、`trellis-check-all`）
+- 选 **Manual-only** 当 skill 用法明确、频率低、不希望占用每次对话 skill 列表 token（如 `trellis-create-command` 自身、`trellis-plan-version`）
+
+**agents 版 frontmatter**：正文 + frontmatter 与 skill 版完全一致（包括 `name: trellis-<name>`），只是落在 `.agents/skills/trellis-<name>/` 目录。
+
+```yaml
+---
+name: trellis-<name>
+description: "<与 skill 版一致>"
+---
+```
+
+**command 版**：无 frontmatter，纯 markdown。
+
+### Step 5: 写入副本
+
+**不变量（必须遵守）**：每个 trellis 入口都成对存在 —— `.claude/<commands 或 skills>/...` 主副本 + `.agents/skills/trellis-<name>/SKILL.md` 镜像副本。漏写任一份会破坏 skill-garden install.sh 的对称分发。scope 含 skill-garden 时，skill 形态需要在 `<skill-garden>/.trellis/0.6/` 下各写一份（共 4 份）；command 形态在 0.6 中不再分发到 skill-garden（见下表注）。
+
+按形态决定落盘位置：
+
+**形态 = skill**（2 份 / scope 为 skill-garden 时 4 份）：
+
+| 位置 | frontmatter name |
+|------|------------------|
+| `<target>/.claude/skills/trellis-<name>/SKILL.md` | `trellis-<name>`（主副本） |
+| `<target>/.agents/skills/trellis-<name>/SKILL.md` | `trellis-<name>`（镜像，body + frontmatter 完全同主副本） |
+| `<skill-garden>/.trellis/0.6/.claude/skills/trellis-<name>/SKILL.md` | `trellis-<name>` |
+| `<skill-garden>/.trellis/0.6/.agents/skills/trellis-<name>/SKILL.md` | `trellis-<name>` |
+
+**形态 = command**（仅 target 2 份；scope = skill-garden 也不分发到 0.6 包）：
+
+| 位置 | 格式 |
+|------|------|
+| `<target>/.claude/commands/trellis/<name>.md` | 无 frontmatter（主副本） |
+| `<target>/.agents/skills/trellis-<name>/SKILL.md` | 带 frontmatter，`name: trellis-<name>`（镜像） |
+
+> **0.6 不分发 command 到 skill-garden**：0.6 包目录树没有 `.claude/commands/`，install.sh 也不会处理。如果你确实希望 command 形态分发给其他项目使用，请：(a) 改用 skill 形态，或 (b) 把该 command 同时放到 0.5 包（向下兼容用户），或 (c) 在 skill-garden 包外用其他机制分发。
+
+**同步技巧**：写完主版（`.claude/skills/trellis-<X>/SKILL.md` 或 `.claude/commands/trellis/<X>.md`）后，用 `cp` 派生其他副本：
+
+```bash
+# 主副本写完后，副本内容完全一致，直接 cp 即可
+cp <target>/.claude/skills/trellis-<X>/SKILL.md <target>/.agents/skills/trellis-<X>/SKILL.md
+
+# 对 skill-garden 同步（仅 skill 形态、scope 为 skill-garden 时）
+cp -r <target>/.claude/skills/trellis-<X> <skill-garden>/.trellis/0.6/.claude/skills/
+cp -r <target>/.agents/skills/trellis-<X> <skill-garden>/.trellis/0.6/.agents/skills/
+```
+
+### Step 6: 更新 skill-garden README（scope = skill-garden 时）
+
+必改：
+- "0.6+ 推荐技能" 表追加一行（名称 / 形态 / 说明 / 使用时机）
+- "0.6+ 全部技能" 段同步更新计数
+
+可选：
+- 如引入新形态约定或命名前缀：更新"新增 Trellis 技能"指引
+
+### Step 7: 验证
+
+| 检查项 | 方法 |
+|-------|------|
+| 新 skill 出现在 Claude skill list | 读 `<available-skills>` 区，确认 `trellis-<X>` 存在且 description 完整 |
+| 新 command 出现在 slash 列表 | 下拉 `/trellis:` 能看到 `<name>` |
+| scope=skill-garden：install 端到端 | `rm -rf /tmp/sg-test && mkdir -p /tmp/sg-test/.trellis && echo "0.6.0-beta.8" > /tmp/sg-test/.trellis/.version && bash <skill-garden>/scripts/install.sh /tmp/sg-test <X>` |
+| 副本内容一致 | `wc -l` 行数一致；关键段落 `diff` 确认 |
+
+### Step 8: 输出确认
+
+```markdown
+✓ 已创建 trellis 入口：<name>
+
+形态：<command | skill>
+范围：<本项目 | 本项目 + skill-garden 0.6>
+
+副本：
+  • <target>/.claude/<path>
+  • <target>/.agents/skills/trellis-<X>/SKILL.md
+  <• <skill-garden>/.trellis/0.6/ 同步位置 × 2（仅 skill 形态）>
+
+触发方式：
+  • 自然语：<触发词例子>
+  • 显式：<`/trellis:<X>` 或 `/trellis-<X>`>
+
+下一步建议：
+  • 在当前对话试一次触发，观察 Claude 是否正确路由
+  • 触发失败时调整 description（精准化 when/exclusion）
+  • 内容有遗漏时补充 Step 或 checklist
+```
+
+---
+
+## 命名约定
+
+| 类型 | 前缀 | 示例 |
+|------|------|------|
+| 会话生命周期 | — | `continue` / `finish-work` |
+| Pre-development | `before-` | `before-dev` |
+| Check | `check-` | `check-all` |
+| Verify | `verify-` | `verify-task` |
+| Extract（有源严格提取） | `extract-` | `extract-prd` |
+| Create / generate（从零创建） | `create-` | `create-command` |
+| Analyze | `analyze-` | `analyze-task` |
+| Sync / update | `sync-` / `update-` | `sync-prd` / `update-spec` |
+| 动作类 | 动词开头 | `push` / `draw-uml` |
+
+> **0.6 命名取舍**：「严格提取」类用 `extract-` 前缀（强调原文不动、禁止发挥）；「从零创建」类才用 `create-` 前缀（如 create-command）。区分这两者能让 AI 在触发时不混淆生成 vs 提取的语义。
+
+### 命名反模式
+
+- ❌ 不用 kebab-case（不要 `reviewPr` / `review_pr`）
+- ❌ 名字过于笼统（`tool` / `helper` / `util`）
+- ❌ 与现有命令冲突（先 `ls .claude/commands/trellis` 和 `.claude/skills/` 确认）
+- ❌ skill 写文件时漏 `trellis-` 前缀（影响自动路由分组）
+- ❌ "严格提取"语义的入口用 `create-` 前缀（应该用 `extract-`，避免 AI 误判为生成型）
+
+---
+
+## 内容写作约束
+
+- skill body 默认 < 300 行；超过说明该拆分或融合
+- 每个 Step 要有**具体可执行动作**（读文件、grep、写文件），避免 "Analyze the requirements" 这种模糊词
+- 输出格式必须用 markdown 模板明示
+- 反模式清单必写（帮 Claude 避免常见误用）
+- 中文注释 + 英文 description（description 中的触发词可中英混合）
+- 引用文件路径用反引号 `.claude/...`，不写裸路径
+
+---
+
+## 反模式（避免）
+
+- ❌ 写 `.cursor/commands/`（已废弃，统一 `.claude/commands/`）
+- ❌ 同时创建 command 和 skill 同名入口（触发歧义，不知选哪个）
+- ❌ 只写 `.claude/...`，漏了 `.agents/skills/trellis-<X>/`（skill-garden install 会不对称）
+- ❌ 选 Auto-routing 策略但 description 过短（< 80 字），Claude 路由不稳；Manual-only 策略无此要求
+- ❌ description 用名词开头（"A skill for..."）而不是动词开头（"Analyzes..." / "Extract..." / "Create..."）
+- ❌ 不询问 scope 直接写 skill-garden（需要用户显式确认 skill-garden 路径）
+- ❌ 不参考已有 skill 就凭空生成，导致风格不一致
+- ❌ 写完不验证（description 语法错或 frontmatter 缩进错，Claude 静默忽略）
+- ❌ command 形态硬要分发到 skill-garden 0.6 包（0.6 不维护 commands 目录，会被忽略）
+- ❌ **跳过 trellis-meta 参考、凭 SKILL.md 简版描述就开写**（trellis-meta 是本地架构权威；冲突时以它为准）
+- ❌ **发明 trellis-meta 未列出的新目录 / 新形态**（如自创 `.trellis/extensions/...` 这种结构；新需求应先去 trellis-meta 找现有入口）