flower-trellis 0.1.0

package/enhancements/0.6/.agents/skills/trellis-plan-version/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: trellis-plan-version
+description: "Generate a version development plan from a source requirements doc: requirements list, effort estimate, and team assignment."
+---
+# 版本开发计划 — 从需求文档到任务拆分
+
+从原始需求文档出发，生成版本开发计划（需求清单 + 工时评估 + 人员分工），内置覆盖度校验确保不遗漏需求。
+
+---
+
+## 核心原则
+
+1. **需求文档是唯一真相** — 需求清单必须从文档全文提取，不能只看目录/总表
+2. **先扫后拆** — 先完成覆盖度扫描，确认无遗漏后再做工时评估和分工
+3. **可追溯** — 每个任务可追溯到原始文档的具体位置（行号/章节）
+
+---
+
+## 输入
+
+用户需提供：
+- **原始需求文档路径**
+- **版本号或迭代标识**
+- **开发团队信息**（人数、角色分工模式）
+
+---
+
+## 执行步骤
+
+### Step 1: 理解文档结构 + 全文扫描
+
+#### 1.0 先读后扫
+
+读取文档，识别其组织方式：
+- 需求的划分单元是什么？（编号体系 / 章节 / 功能模块 / 用户故事）
+- 有无需求总表或变更日志？
+- 版本变更如何标记？（显式标记 / 总表版本列 / 变更日志章节 / 无标记）
+
+> **不要假设文档有特定格式**，先读再判断。
+
+#### 1.1 多策略识别本版本变更
+
+根据文档实际结构，组合使用以下策略：
+
+| 策略 | 方法 |
+|------|------|
+| **标记扫描** | grep 搜索版本相关标记，**包括段落中间嵌入的** |
+| **需求总表** | 读取需求列表中版本相关列，提取本版本的条目 |
+| **全文通读** | 逐章扫描「新增」「变更」「调整」等动作词 |
+
+#### 1.2 归组到需求单元
+
+每个变更点定位到所属的需求单元，记录：
+- 需求单元标识（编号、名称或章节）
+- 变更内容摘要
+- 在文档中的位置
+- 变更类型：整体新增 / 局部变更 / 字段级嵌入
+
+> **[!] 关键：必须识别出「字段级嵌入变更」。**
+> 有些需求单元整体是旧版本的，但内部某个字段/段落属于新版本变更。
+> 仅看需求单元标题会遗漏这类变更。
+
+#### 1.3 识别散射型变更
+
+检查是否有同一功能点散布在多个需求单元中：
+- 同一字段在不同页面的展示/编辑/导出
+- 同一业务规则在不同入口的复用
+- 标记每组散射变更，确保后续分工时归同一人
+
+### Step 2: 输出需求清单 — 覆盖度确认
+
+输出完整的需求清单，请用户确认无遗漏：
+
+```markdown
+## <版本> 需求清单
+
+### 扫描统计
+- 需求总表中本版本条目: X 个
+- 全文扫描发现的变更: Y 个
+- 去重后独立需求单元: Z 个
+
+### 需求列表
+
+| # | 需求单元 | 功能点 | 变更类型 | 变更摘要 | 文档位置 |
+|---|---------|--------|---------|---------|---------|
+
+### 散射型变更（同一功能点跨多个需求单元）
+
+| 功能点 | 涉及的需求单元 | 建议处理 |
+|--------|--------------|---------|
+
+### 需求总表 vs 全文扫描差异
+
+| 来源 | 仅在总表 | 仅在全文 | 两者都有 |
+|------|---------|---------|---------|
+
+> 仅在全文中的变更 = 总表未收录的嵌入式变更，最易遗漏。
+```
+
+**等待用户确认后再继续。**
+
+### Step 3: 工时评估
+
+基于确认后的需求清单，评估每个需求的工时。
+
+输出表格的列结构**根据项目实际的角色分工来定**（如前端/后端/全栈/测试等），不要预设。
+
+评估原则：
+- 如有 AI 编程辅助，标注基准（AI 辅助 vs 纯人工）
+- 复用关系明确标注
+- 优先级以需求文档为准
+
+### Step 4: 人员分工
+
+按模块边界分工，遵循：
+- 复用链归同一人
+- 散射型变更归同一人
+- 尽量无交集
+
+输出分工表和排期建议。
+
+### Step 5: 生成产物文件
+
+在 `doc/` 目录下生成：
+
+```
+doc/
+├── <版本>-需求清单.md            # Step 2 的完整输出（含覆盖度校验）
+├── <版本>-开发计划-工时评估.md    # Step 3 + Step 4
+```
+
+---
+
+## 反模式
+
+- ❌ 只从需求总表提取需求（会漏掉嵌入式变更）
+- ❌ 跳过覆盖度确认直接做工时评估
+- ❌ 散射型变更分给不同的人
+- ❌ 假设文档有特定格式或特定的角色分工模式
+- ❌ 当多个来源的优先级冲突时不明确说明以哪个为准

package/enhancements/0.6/.agents/skills/trellis-push/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: trellis-push
+description: "Commit + push across configured repos with optional merge-to-target."
+---
+# Push — 提交并推送（可选合并到目标分支）
+
+一键完成 commit → push → 可选 merge 到目标分支（通常是测试线）→ push 目标分支 → 切回。
+
+支持多仓库（frontend / backend），merge 目标分支记录在 `.trellis/config.yaml` 的 `packages.<name>.merge_target` 中。
+
+---
+
+## 配置
+
+目标分支存储在 `.trellis/config.yaml` 的 packages 配置中：
+
+```yaml
+packages:
+  frontend:
+    path: iqs-front-human
+    git: true
+    merge_target: test      # 首次 push 时询问后自动写入
+  backend:
+    path: iqs
+    git: true
+    merge_target: test
+```
+
+> 首次运行时如果 `merge_target` 不存在，会在 merge 步骤询问目标分支并回写到 `config.yaml`。
+> 如需修改，直接编辑 `config.yaml` 或通过 `/trellis-push` 传入 `--reconfigure` 语义。
+
+---
+
+## 执行步骤
+
+### Step 0: 读取配置
+
+读取 `.trellis/config.yaml` 中的 `packages` 配置，识别所有 `git: true` 的仓库及其 `merge_target`（如果已配置）。
+
+### Step 0.5: 读取活动任务上下文（可选）
+
+为后续 Step 3「写入任务进度快照」准备输入。本步骤**不阻塞**主流程：任何读取失败都按"无任务上下文"继续，不要中断 push。
+
+```bash
+# 在仓库根目录（含 .trellis/ 的项目根，不是 package 子目录）
+python3 ./.trellis/scripts/task.py current
+```
+
+- **无活动任务**（命令退出码非 0 或输出为空）：在内存里标记 `active_task=None`，**跳过 Step 3**，把本次 push 当作纯 chore push 处理。
+- **有活动任务**：解析输出拿到 task 路径（形如 `.trellis/tasks/MM-DD-name/`），并读取下列内容供 Step 3 使用：
+  - `<task_dir>/implement.md`（如有）— 步骤清单，AI 推断进度的主依据
+  - `<task_dir>/task.json` 的 `last_push_snapshot` 字段（如有）— 上次推送时的进度基线
+  - `<task_dir>/task.json` 的 `base_branch` 字段 — 用于 `git log <base_branch>..HEAD` 圈定本任务的 commit 范围
+
+> 本步骤只读不写。如果读取异常（task.json 损坏、implement.md 缺失等），Step 3 退化为"完全靠用户口述进度"，不影响 push 主流程。
+
+### Step 1: 检测变更
+
+读取 `.trellis/config.yaml` 中的 `packages` 配置，对每个 git 仓库检测变更：
+
+```bash
+# 对每个 package
+cd <package_path>
+git status --short
+```
+
+列出有变更的仓库。如果所有仓库都没有变更，提示用户并终止。
+
+如果只有部分仓库有变更，只处理有变更的仓库。
+
+### Step 2: 逐仓库处理
+
+对每个有变更的仓库，依次执行以下操作：
+
+#### 2.1 展示变更摘要
+
+```bash
+cd <package_path>
+git diff --stat
+git diff --name-only
+```
+
+#### 2.2 暂存文件
+
+展示要暂存的文件列表，**获得用户确认后**再暂存。
+
+```bash
+git add <具体文件列表>
+```
+
+> **[!] 禁止使用 `git add -A` 或 `git add .`**
+> 必须明确列出文件，避免误提交敏感文件（.env、credentials 等）。
+
+#### 2.3 生成 commit message 并提交
+
+分析变更内容，生成符合项目风格的 commit message：
+- 读取最近 5 条 commit 参考风格
+- 类型前缀：`feat` / `fix` / `chore` / `refactor` 等
+- 简短描述变更内容
+- 使用中文描述
+
+```bash
+git commit -m "<type>(<scope>): <description>"
+```
+
+#### 2.4 Push 当前分支
+
+```bash
+git push origin <current_branch>
+```
+
+如果远程没有该分支，使用 `-u` 建立跟踪：
+
+```bash
+git push -u origin <current_branch>
+```
+
+#### 2.5 询问是否 Merge 到目标分支（可选）
+
+Push 完成后，检查该 package 是否已配置 `merge_target`：
+
+**已配置 `merge_target`**：
+
+```markdown
+<package> 已推送到 <current_branch>。是否合并到 <merge_target>？
+
+1. 是，合并到 <merge_target>
+2. 否，跳过
+```
+
+**未配置 `merge_target`（首次）**：
+
+```markdown
+<package> 已推送到 <current_branch>。是否需要合并到其他分支（如测试线）？
+
+1. 是，请输入目标分支名
+2. 否，跳过
+```
+
+如果用户输入了目标分支名，**将其回写到 `.trellis/config.yaml`** 对应 package 的 `merge_target` 字段，下次自动使用。
+
+**如果用户选择合并**：
+
+```bash
+# 切换到目标分支并拉取最新
+git checkout <target_branch>
+git pull origin <target_branch>
+
+# 合并当前开发分支
+git merge <current_branch> --no-edit
+
+# Push 目标分支
+git push origin <target_branch>
+
+# 切回开发分支
+git checkout <current_branch>
+```
+
+> **[!] 如果 merge 出现冲突：**
+> 1. 立即停止，展示冲突文件列表
+> 2. 询问用户：手动解决 / 中止 merge
+> 3. **绝对不能** `git merge --abort` 后静默跳过
+
+**如果用户选择跳过**：直接进入下一个仓库或输出结果。
+
+### Step 3: 写入任务进度快照（可选）
+
+仅当 Step 0.5 识别到活动任务时执行；否则跳过本步直接进入 Step 4。
+
+**目的**：让下次新会话进来时能感知"任务做到哪一步了"。配套机制由 `.trellis/workflow.md` 的 `[workflow-state:no_task]` 块里的 `push-progress-recovery` guard 触发（见 3.4）。
+
+**架构说明**：`.trellis/tasks/<task>/task.json` 在**父仓**（含 `.trellis/` 的项目根目录）的 git 跟踪范围内，与子仓（frontend / backend）独立。因此本 Step 完成后必须**额外 commit + push 父仓**（见 3.3），才能让 snapshot 真正落到 remote，跨机器恢复有效，且不留脏工作区。
+
+#### 3.1 AI 推断进度
+
+收集以下信号：
+
+- Step 0.5 读到的 `implement.md` 步骤清单（如缺失则只能靠 commit history 粗略推断）
+- 各子仓 `git log <base_branch>..HEAD --oneline`（任务分支自分叉以来的所有 commit，含本次刚 push 的）
+- 上次 `last_push_snapshot`（如有）— 作为基线，重点判断"上次之后又做了什么"
+
+基于以上信号，AI **主动给出一个 draft**（不要让用户从零列步骤），例如：
+
+```markdown
+任务进度推断（请确认）：
+
+- ✅ Step 1-3 已完成（frontend abc1234 / backend def5678 覆盖了对应改动）
+- 🟡 Step 4 部分完成 — 看到 README.md 改了 2 处，implement.md 写要改 4 处
+- ⬜ Step 5 未跑
+
+本次 push 后停在 **Step 4（部分）**，下一步 **Step 5（校验）**。
+
+确认（yes）/ 调整（说明具体改动）/ 跳过快照（skip）
+```
+
+#### 3.2 写入 task.json
+
+用户确认（yes 或调整后的版本）→ 在 `<task_dir>/task.json` 写入 / 更新 `last_push_snapshot` 字段：
+
+```json
+"last_push_snapshot": {
+  "snapshot_at": "<ISO 8601 时间戳>",
+  "branch": "<任务分支名>",
+  "pushed_commits": {
+    "frontend": "abc1234",
+    "backend": "def5678"
+  },
+  "completed_steps": ["Step 1", "Step 2", "Step 3"],
+  "partial_step": "Step 4 (README 改了 2/4 处)",
+  "next_step": "Step 5 (校验)",
+  "notes": "<可选：用户补充说明>"
+}
+```
+
+字段语义：
+- `snapshot_at`：写快照的时间戳（必填）
+- `branch`：任务分支名（必填，多仓不同分支时改成字典 `{"frontend": "...", "backend": "..."}`）
+- `pushed_commits`：本次刚 push 的最新 commit 短 hash，按 package 名分键（必填）
+- `completed_steps`：implement.md 中已完成的 step 名数组（必填）
+- `partial_step` / `next_step` / `notes`：可选
+
+写入方式：读 `task.json` → 解析 JSON → 设置 `last_push_snapshot` 字段 → 保留其它字段原样 → 写回（保持原有 indent，通常 2 空格）。**不要**覆盖整个 task.json，只更新一个字段。
+
+> 用户回复 `skip` 时不写入 task.json，**整个 Step 3 终止**（包括跳过 3.3 父仓提交），直接进 Step 4。
+
+#### 3.3 父仓 commit + push（同步到 remote）
+
+写完 task.json 后，**必须**把这个改动 commit + push 到父仓 remote，否则：
+- 工作区残留脏 task.json
+- 跨机器 / 重新 clone 时拿不到 snapshot
+- 父仓 git log 缺失任务进度的演进记录
+
+```bash
+# 切到父仓根目录（含 .trellis/ 的目录，不是 package 子目录）
+cd <project_root>
+
+# 先看父仓 status，确认变更只有 task.json
+git status --short
+```
+
+**[!] 如果父仓 status 显示 task.json 之外还有其他改动**：停下来询问用户：是否一并提交 / 拆分 / 暂存？不要静默打包。
+
+```bash
+# 仅 stage 这一个文件，避免误带父仓其他改动
+git add .trellis/tasks/<task_dir>/task.json
+
+# commit（message 参考项目现有风格，如 chore(task): / [UPDATE] 等）
+git commit -m "chore(task): update <task_name> push snapshot"
+```
+
+检查父仓是否配置 remote：
+
+```bash
+git remote -v | grep -E "^origin\s+"
+```
+
+- **有 remote**：`git push origin <current_branch>`（首次用 `git push -u origin <current_branch>`）
+- **无 remote**：仅本地 commit，跳过 push 步骤，提示用户"父仓未配 remote，snapshot 仅本地保存"
+
+#### 3.4 新会话恢复（被动机制，无需在本步操作）
+
+写入并 push 后，下次新会话进来时：
+
+1. SessionStart 检测到无 active task pointer → 输出 `<task-status>Status: NO ACTIVE TASK</task-status>`
+2. UserPromptSubmit 每轮注入 `[workflow-state:no_task]` 块，含 skill-garden 的 `push-progress-recovery` guard
+3. AI 看到 guard → 扫描 `.trellis/tasks/*/task.json` 找 `status=in_progress` 的任务 → 读 `last_push_snapshot` → 主动告诉用户「发现未完成任务 X，上次 push 完成到 Step Y，下一步 Z」并建议 `task.py start <task>` 恢复
+
+### Step 4: 输出结果
+
+```markdown
+## Push 结果
+
+| 仓库 | 分支 | 目标 | commit | 状态 |
+|------|------|------|--------|------|
+| frontend | v1.3 | test | abc1234 feat(...): ... | ✅ 已合并 |
+| backend | v1.3 | test | def5678 fix(...): ... | ⏭️ 跳过合并 |
+
+所有变更已推送到目标分支。
+```
+
+若 Step 3 写入了 `last_push_snapshot`，在结果末尾追加一行：
+
+```markdown
+任务进度快照已写入 `<task_dir>/task.json`：完成 Step 1-3，下一步 Step 5。
+```
+
+---
+
+## 语义参数（通过自然语 / skill args 传入）
+
+| 语义 | 说明 | 用户怎么说 |
+|------|------|-----------|
+| 默认 | 自动检测所有有变更的仓库并处理 | `/trellis-push` |
+| 指定仓库 | 只处理指定仓库 | 「只 push 前端」/「push frontend」 |
+| 重新配置 | 重新询问目标分支 | 「重新配置 push 目标分支」/「reconfigure push」 |
+| 临时目标 | 临时指定目标分支（不修改配置） | 「push 到 hotfix 分支」 |
+
+---
+
+## 安全机制
+
+1. **暂存确认** — 每个仓库暂存前展示文件列表，用户确认
+2. **commit message 确认** — 展示生成的 message，用户可修改
+3. **merge 冲突处理** — 冲突时暂停，不静默跳过
+4. **不碰主分支** — 如果目标分支是 `master` / `main`，额外警告确认
+5. **不使用 force push** — 始终使用普通 push
+
+---
+
+## 反模式（避免）
+
+- ❌ `git add -A`（可能误提交敏感文件）
+- ❌ merge 冲突后静默 abort（用户需要知道）
+- ❌ 未经确认直接 commit（必须让用户看到 message）
+- ❌ force push 到目标分支
+- ❌ 在目标分支上直接开发（只 merge，不在目标分支上改代码）

package/enhancements/0.6/.agents/skills/trellis-route/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: trellis-route
+description: |
+  Route trellis-implement / trellis-check execution mode by asking the user to choose inline or subagent.
+  For check, additionally choose between trellis-check (lightweight) and trellis-check-all (comprehensive,
+  default pre-commit). Invoked from Phase 2.1 / 2.2 of the routing-aware workflow. Skip in non-trellis
+  projects (no .trellis/). Not for other subagents (trellis-research / trellis-debug).
+---
+
+# Trellis 路由器：implement / check 执行模式选择
+
+主 agent 进入 Phase 2.1 / 2.2 时调用本 skill，询问用户选择执行模式（inline / subagent / check-all）后输出执行指令。implement 支持本会话偏好（4h 内连续 dispatch 不重复问）。
+
+---
+
+## Step 1.5: 检查会话偏好（仅 target=implement）
+
+读 `.trellis/.route-prefs.tmp`（4h mtime 内有效）：
+
+```bash
+PREF_FILE=".trellis/.route-prefs.tmp"
+if [ -f "$PREF_FILE" ]; then
+  MTIME=$(stat -c %Y "$PREF_FILE" 2>/dev/null || stat -f %m "$PREF_FILE" 2>/dev/null)
+  if [ -n "$MTIME" ] && [ $(( $(date +%s) - MTIME )) -lt 14400 ]; then
+    cat "$PREF_FILE"
+  else
+    rm -f "$PREF_FILE"
+  fi
+fi
+```
+
+输出 `inline` 或 `subagent` → **跳过 Step 2**，直接 Step 3 按记忆走，输出指令前加一行 `📌 来自本会话偏好（4h 内不再问；rm .trellis/.route-prefs.tmp 可重置）`。
+
+target=check **跳过本步**，每次都询问。
+
+## Step 1.7: 上下文判断与推荐（无偏好命中时强制执行）
+
+Step 1.5 未命中偏好时，主 agent 在调用 `AskUserQuestion` **之前**必须基于当前任务上下文做一次判断，**自己**挑出最合适的选项并写 1-2 句中文推荐理由。**SKILL.md 不硬编码"哪个是推荐项"也不限定判断维度——主 agent 用自己的判断力。**
+
+将推荐选项编号 + 1-2 句中文理由作为 Step 2 `question` 字段的**首句**，例如：
+
+- implement: "任务只改 1 个 vue 文件且 PRD 清晰，建议 #1 inline。本次 implement 走哪种模式？"
+- check: "改动跨前后端 + DB 且即将提交，建议 #1 check-all inline。本次 check 走哪种模式？"
+
+option label 里**不写"（推荐）"后缀**——推荐落点通过 question 文案体现，用户能看到判断依据并否决。
+
+## Step 2: 询问用户
+
+优先调用 `AskUserQuestion`。**选项 label 前缀 1/2/3/4，方便用户直接打数字快速选**。`question` 字段首句必须是 Step 1.7 输出的推荐理由（1-2 句中文），**不可省略**。
+
+如果当前平台或模式没有 `AskUserQuestion` / `request_user_input`，不要选择 inline 或 subagent 继续。改用普通聊天消息原样呈现同一组编号选项，并停止等待用户回复；用户回复数字后再进入 Step 2.5 / 2.6 / 3。禁止写"request_user_input 当前不可用，所以记录为 inline/subagent 路径并继续"。
+
+### target = implement（4 选项）
+
+- **question**: "[Step 1.7 推荐理由 1-2 句] 本次 implement 走哪种模式？"
+- **header**: "Impl 模式"
+- **options**:
+  1. label "1. Inline", description "本次主 agent 直接执行，更快，共享上下文"
+  2. label "2. Subagent", description "本次 dispatch 子 agent，隔离独立思考"
+  3. label "3. Inline 本会话", description "本次 + 4h 内所有 implement 都 inline，不再问"
+  4. label "4. Subagent 本会话", description "本次 + 4h 内所有 implement 都 dispatch 子 agent，不再问"
+
+### target = check（4 选项）
+
+- **question**: "[Step 1.7 推荐理由 1-2 句] 本次 check 走哪种模式？"
+- **header**: "Check 模式"
+- **options**:
+  1. label "1. Check-all inline", description "全面检查（PRD 对照 + 5 维 + spec），主 agent 执行"
+  2. label "2. Check-all subagent", description "全面检查，dispatch 子 agent"
+  3. label "3. Check inline", description "轻量检查（lint/type/spec），主 agent 执行"
+  4. label "4. Check subagent", description "轻量检查，dispatch 子 agent"
+
+## Step 2.5: 读 subagent_skip_compile（仅 implement + subagent 时）
+
+```bash
+if [ -f .trellis/config.yaml ]; then
+  grep -E "^\s*subagent_skip_compile:\s*true\b" .trellis/config.yaml > /dev/null && echo true || echo false
+fi
+```
+
+为 `true` 时，Step 3 的 implement subagent 指令会附加"跳过编译"prompt 段。其他路径不读此配置。
+
+## Step 2.6: 持久化偏好（仅 implement 选项 3/4 时）
+
+```bash
+mkdir -p .trellis
+# 选项 3 (Inline 本会话)
+echo "inline" > .trellis/.route-prefs.tmp
+
+# 选项 4 (Subagent 本会话)
+echo "subagent" > .trellis/.route-prefs.tmp
+```
+
+文件名 `.tmp` 后缀被 trellis `.gitignore` 默认 `*.tmp` 规则自动忽略，无需额外配置。选项 1/2 不写文件。
+
+## Step 3: 输出执行指令
+
+本 skill 不调用 Skill / Agent 工具，而是输出指令让主 agent 在下一轮执行。
+
+### 路由表
+
+| 用户选择 | 主 agent 应执行 |
+|---------|----------------|
+| **inline implement**（选项 1 或 3，或来自偏好） | `Skill({skill: "trellis-before-dev"})` 加载 spec → 读 prd.md → 主线程实施 → 跑 lint/type-check |
+| **subagent implement**（选项 2 或 4，或来自偏好） | `Agent({subagent_type: "trellis-implement"})`；若 `subagent_skip_compile=true`，dispatch prompt 附加"跳过 mvn install / npm run build / tsc 等耗时编译类检查（已由主 agent 验证或最终统一执行）" |
+| **inline check**（选项 3） | `Skill({skill: "trellis-check"})` |
+| **inline check-all**（选项 1） | `Skill({skill: "trellis-check-all"})` |
+| **subagent check**（选项 4） | `Agent({subagent_type: "trellis-check"})` |
+| **subagent check-all**（选项 2） | 优先 `Agent({subagent_type: "trellis-check-all"})`；不存在时 fallback `Agent({subagent_type: "trellis-check"})` + dispatch prompt 含 trellis-check-all 全流程要求（PRD 对照 → 5 维断言 → 跨层 → 委托 trellis-check 收尾） |
+
+### 输出模板
+
+```markdown
+路由决定：<inline/subagent> <implement | check | check-all>
+[📌 来自本会话偏好（4h 内不再问；rm .trellis/.route-prefs.tmp 可重置）]
+
+接下来主 agent 应当：
+- <路由表里对应的工具调用形式>
+- [若 implement subagent 且 subagent_skip_compile=true：附加"跳过编译"prompt 段]
+
+不要：
+- <要避免的工具调用>
+```
+
+中括号内行为条件性出现：仅命中本会话偏好时显示第二行；仅 implement subagent + skip_compile=true 时附加"跳过编译"段。
+
+---
+
+## 核心原则
+
+1. **决策与执行分离**：本 skill 只输出指令，下一轮由主 agent 调工具
+2. **严格执行用户选择**：路由结论一旦输出，主 agent 必须按指令执行，不可"出于谨慎"再换路径
+3. **无偏好命中必问，无自动 fallback**：Step 1.5 未命中偏好时，Step 2 询问是强制步骤；缺工具/权限时必须退化为普通聊天询问并等待用户回复，**不是**绕过询问或自行选择路径的合法理由
+4. **推荐由主 agent 上下文判断生成**（Step 1.7），不在 SKILL.md 里硬编码"哪个是推荐项"——避免静态偏好和当下任务实际不匹配
+5. **本会话偏好仅 implement 适用**：check 每次询问（避免累积偏好导致提交前漏跑 check-all）
+6. **config 联动仅 implement subagent 路径**：`subagent_skip_compile` 仅在 target=implement + 选 subagent 时读取并注入 prompt
+
+---
+
+## 反模式
+
+- ❌ 本 skill 内部直接调用 `Agent` / `Skill` 工具（违反"决策与执行分离"）
+- ❌ 自行编造"工具/权限/平台不支持子代理"等理由跳过 Step 2 询问（**无偏好命中时必须询问用户**；交互工具不可用时用普通聊天询问并等待，不能绕过路由）
+- ❌ `AskUserQuestion` / `request_user_input` 不可用时，记录为 inline 或 subagent 路径并继续
+- ❌ Step 1.7 推荐理由空着、随便写一句敷衍、或不放进 question 文案（推荐必须基于当前任务的具体上下文，给用户可判断依据）
+- ❌ check 端默认降级到轻量 trellis-check，特别是 pre-commit Phase 3.1（除非 Step 1.7 已显式说明"改动仅 lint/重命名级别"才走 check）
+- ❌ check-all 选项被错误降级为普通 trellis-check（必须优先 trellis-check-all skill / subagent）
+- ❌ 给 check 任何模式附加"跳过编译"指令（check 的核心职责就是跑编译/typecheck）
+- ❌ 询问后忽视用户答案默认 subagent
+- ❌ check 端读 `.route-prefs.tmp`（仅 implement 适用本会话偏好）
+- ❌ implement 偏好命中后还询问用户（违反"4h 内不再问"承诺）
+
+---
+
+## 边界
+
+- **非 trellis 项目**（无 `.trellis/`）：输出"非 trellis 项目，跳过路由"，不阻断流程
+- **config.yaml 缺失或字段缺失**：视为 false，不附加跳过编译指令
+- **.route-prefs.tmp 内容损坏**（非 inline/subagent）：忽略偏好，删除文件，正常询问