Trellisx Spec

立即执行: Spec 破坏式优化

本 skill 触发后, main 直接按以下 5 步流程执行, 不要 fork 到 sub-agent (sub-agent 无法走 AskUserQuestion 审批门)。立即开始, 无需等待进一步指令。

第 1 步: 检测项目环境与模式

推荐配套: optimize/sediment 模式做破坏式重构前, 可先 /trellisx-grill 对现有 spec 审一轮 (轴 C 验证可执行性 / H 触发准确性 / I token / J 自举矛盾 / K 诚实边界), grill 出的弱点喂给下方诊断, 避免重构时丢关键约束。grill 可在任意阶段调用 (非仅前置)。

# 1.1 确认 .trellis/ 存在
ls -la .trellis/ 2>/dev/null
# 不存在则报错退出: "当前目录非 trellis 项目, 终止"

# 1.2 列 .trellis/spec/ 内容
find .trellis/spec -type f 2>/dev/null

# 1.3 查当前 active task (用于 sediment 模式判定)
python3 ./.trellis/scripts/task.py current 2>/dev/null || true

模式自动判定 (按 1.2 / 1.3 结果):

参数 $范围 (skill 启动时传入): 限制本次处理范围 (目录 glob / 文件路径 / all)。缺省 = all。

spec 主动化 (两端: hook 被动可见 + gate 主动检索/判定):

• planning 加载 (gate, owner = trellisx-orchestrate step 1, 独家): orchestrate step 1 必做 grep .trellis/spec/guides/index.md 按主题找 relevant guide 注入 PRD 上下文 (有相关 spec 才加载, 无则跳过); flow 不重复加载。被动可见: 该 gate 文本由 trellis 原生每轮注入 context (AI 每轮知 spec 存在 + index 路径, 不靠记忆); relevant guide 检索归 orchestrate 主动 grep (model 驱动, 非脚本全自动; 无独立 per-turn hook, config.yaml 仅 lifecycle 事件)。本 skill 不负责加载, 仅提供 spec 内容供加载 + sediment 时同步 index.md。
• finish 前 sediment 判定 (gate, 非软约束): trellisx-flow finish 步按下述 checklist 逐项判本 task 有无 spec 增量, 任一正向 ✅ → 触发本 skill sediment 模式 (提案→审批→写盘+同步 index.md); 全否跳过。正向: ① 新命令式契约 ② 踩坑 ≥2 轮 ③ 反复 ≥2 task ④ 跨任务可复用决策 ⑤ 验收基准; 排除: 一次性 bug / 私有细节 / 已覆盖。非用户主动调, 是流程判定 (判定归 AI 非脚本, 语义判断脚本做不了)。
• sediment ≠ cortex: sediment 是 spec 自身增量沉淀 (命令式契约), 非 cortex 知识库归档。两者并存, 各管各的。

第 2 步: 按模式读 references + 准备提案

分支 2A (init 模式)

读 references/init-mode.md + references/rewrite-style.md + references/propose.md。

按 init-mode.md 模板生成首版提案 (NEW 类型变更), 输出到主会话:

spec init 模式首版提案 (共 N 项 NEW)
─────────────────────────────────
#1 NEW .trellis/spec/index.md
#2 NEW .trellis/spec/guides/<file>.md
...

跳到第 3 步。

分支 2B (optimize 模式)

读 references/diagnose.md 跑体检, 输出体检报告到主会话 (不写盘):

spec 体检报告
─────────────
文件清单 + 行数
命令式比例: X% (达标 ≥ 60%)
描述式残留: Y 处
死链: Z 处
建议提案: ...

读 references/propose.md + references/rewrite-style.md, 按诊断结果生成提案 (DELETE / REWRITE / MERGE / SPLIT / EXTRACT / PATCH 类型)。

跳到第 3 步。

分支 2C (sediment 模式)

读 references/sediment-mode.md + references/propose.md。

读 active task 的 prd.md / design.md / implement.md / journal-*.md, 按 flow step 6 sediment checklist (5 正向: 新命令式契约 / 踩坑 ≥2 轮 / 反复 ≥2 task / 跨任务可复用决策 / 验收基准; 3 排除: 一次性 bug / 私有细节 / 已覆盖) 判增量是否值得沉淀, 提炼"本任务非平凡发现", 按 sediment-mode.md 模板生成提案 (PATCH / NEW 为主)。

跳到第 3 步。

第 3 步: 直接调 AskUserQuestion 审批 (硬停)

硬停审批门: 写盘前硬性停在此。立即调用 AskUserQuestion 工具弹选项, 禁在文本里写"是否同意?"等回复。未经工具明确批准 → 0 写盘。

读 references/approve.md 设计问句结构 (单一批准 / 选择性多选 / 高风险二次确认)。

用户在工具内选 "取消" / 未明确批准 → 立即停, 返回 "0 变更, 用户驳回"。 用户选 "全部批准" 或 "按编号选择 (选中项)" → 进入第 4 步。

禁止:

• 用文本提问代替工具调用 (用户无法用工具 UI 选择 = 失去审批门设计)
• 等待用户在对话里打字回复 (走文本回复 = 拖慢 + 易误解)

第 4 步: 一次性写盘 + 同步

用户批准后, 读 references/execute.md 执行:

• 一次写盘 (避免中间状态)
• 每文件附 frontmatter (updated / rewrite-version / supersedes / authored-by: trellisx-spec / mode)
• 同步 .trellis/spec/guides/index.md (新/改 spec append 标题 + 1 行摘要) —— 硬性: orchestrate step 1 gate grep 读此文件找 relevant guide, 不同步 → 新 spec 不在 index → gate grep 漏 → load 失效。同步 index / 锚点 / 导航
• grep 受影响 task manifest (implement.jsonl / check.jsonl), 列引用清单 (本 skill 不动 manifest)

第 5 步: 自检 + 返回报告

读 references/selfcheck.md 跑自检 (命令式比例 / 描述式残留 / 死链 / 首段说明 / frontmatter / index 锚点对齐)。

返回主会话最终报告:

spec 变更执行报告
═════════════════
模式: <init | optimize | sediment>
范围: <$范围>
批准 N 项, 执行 M 项
新增 / 修改 / 删除文件清单
受影响 task manifest: <count>
自检结果: <达标 / 未达标项>

边界硬规

• 仅读写 .trellis/spec/**; 禁触碰 .trellis/tasks/** / .trellis/workspace/** / 源码
• 仅 grep implement.jsonl / check.jsonl (只读), 列引用清单给用户, 禁直接编辑 task manifest
• AskUserQuestion 不可跳过, 不接受纯文本批准
• 多文件写盘中途失败 → 全部回滚 (git checkout 或 backup)

反例黑名单 (禁做 → 改为)

命中任一条即停, 按"改为"修正后再继续。只写应做、不列禁做即视为流程缺陷。

立场 (写 spec 条款时遵守)

失败处理

• 工具瞬时错误 → 重试 1 次
• 用户驳回审批 → 立即停, 返回 "0 变更, 用户驳回"
• 阶段 1 诊断无问题 (健康度全达标) → 跳到结束, 返回 "spec 健康, 无变更建议"
• 多文件写盘中途失败 → 回滚已写文件, 返回失败原因
• 当前目录非 trellis 项目 → 立即停, 返回 "非 trellis 项目, 终止"

References 索引 (按需读)