Trellisx Apply

trellisx-apply — 把 trellisx worktree/收尾/看板机制内化进 .trellis

把 worktree 隔离 + 闭环收尾 + task.md 看板 三维增量注入 .trellis/ (config.yaml 生命周期 hook + 独立脚本 + 可选 finish-work 命令注入)。各维度注入内容与落地位置见下方「注入维度」表。

铁律 (贯穿全程)

• 🎯 结果导向, 行为闭环为准 (约束 RESULT 非 HOW): 不限制注入方式 —— writer 可替换/重构/追加任意脚本与配置。唯一硬门是 writer 写盘自验的行为闭环验证: 最终 .trellis MUST 满足 ① worktree 生命周期 hook 在位 (after_start 建 / after_archive 销) ② 收尾链完整 (task.py finish → commit→merge→archive→销 worktree) ③ task.md 看板 hook 在位。

  可执行断言 (writer 自验最小集, 任一 ✗ → 回滚重做):

  # ① worktree + 收尾 hook 在位 (config.yaml 仍含 trellisx hook 注入)
  grep -q "trellisx-worktree" .trellis/config.yaml && grep -q "trellisx-finish" .trellis/config.yaml
  # ② 脚本语法合法 + 公共模块可导入
  python3 -c "import ast; ast.parse(open('.trellis/scripts/trellisx-finish.py').read())"
  # ③ session_auto_commit 实值 true (archive 自动提交闭环依赖)
  python3 -c "import sys; sys.path.insert(0,'.trellis/scripts'); from common.config import get_session_auto_commit; assert get_session_auto_commit() is True"
  

  完整断言集 + 行为闭环验证步骤见 references/apply-verify.md; writer MUST 至少跑上述 3 条自验才报告 ok=true。

  注入用 marker 包裹保幂等; 不带病写盘 (来由见下方「教训」)。

• 🪶 worktree + 收尾 hook 确定性强制:

  • worktree 与闭环收尾 = trellis 原生生命周期 hook 确定性强制, 不靠 AI 记得跑脚本: task.py start → after_start 自动建 worktree; task.py finish → after_finish 跑 trellisx-finish.py 自动 commit→merge --no-ff→archive→销 worktree (commit 为 owner 授权的强制动作, 不停在"提醒用户运行命令")。冲突则脚本 abort + finish 打 WARN, AI 须检告警转手动; 未 archive 禁宣告 Done。
  • worktree 隔离单位 = task (防并发多 task 冲突)。"task 在其 worktree 内执行"仍是软约束 (未上 PreToolUse 拦截); 需更硬的平台拦截使用者另加, apply 不做。

执行模型 (main 编排 + 并行 subagent 执行)

main 不执行任何 repo 操作 (不 Read/Edit/Write/Bash/git 改盘), 只做两类不可派的事: AskUserQuestion 审批门 (用户交互, 夹在 plan/write 两阶段之间) + 编排决策 (汇总/派发/修复循环)。

main 用 Agent 工具把扇出编排成两阶段 (Phase A 并行规划 read-only → main 审批 → Phase B 并行写盘+自验+回滚)。维度收敛为 3 个 (spec/hook/finishcmd) + 诊断, writer 写完自验 (无独立验证阶段)。详见 references/agent-orchestration.md。

立场

前置检查

ls .trellis/ || { echo "非 trellis 项目, 终止"; exit 1; }
ls .trellis/spec/ 2>/dev/null    # spec 目标
ls .trellis/config.yaml          # trellis 生命周期 hook 注入目标
ls .claude/commands/trellis/finish-work.md 2>/dev/null   # finish-work 全链注入目标 (无则 hook 路兜底)

产物语言固定中文 (无探测)。非 trellis 项目 → 报错终止。

工作流 (subagent 编排, 审批夹在中间)

载体见上「执行模型」; 完整模型/6 字段 prompt/文件集分区见 references/agent-orchestration.md。

硬停审批门 (审批): 改 .trellis/ 前 MUST 由 main 展示 diff plan + 经 AskUserQuestion 批准才进步 3。审批门禁派 agent (全局硬规: agent 不得直接问用户) —— 故 plan 与 write 拆成两阶段, 审批夹在中间; 禁纯文本"是否同意"代替工具; 用户未明确批准 → 0 写入, 终止。 🔒 git stash 备份/回滚在 write 阶段由 prep-backup/rollback agent 串行执行 (main 不亲碰 git)。

注入维度 (注入方式不限, 行为闭环达标即可)

🔒 教训 (行为闭环为准的来由): 早期 worktree 逻辑在 worktree.py 与 finish.py 各写一份路径/命名, 差一点就失配 —— 真正的坑是功能失效 (合并目标算错 / 漏拷公共模块 ImportError)。所以约束 RESULT 而非 HOW: writer 自验 MUST 行为验证 ① worktree hook 在位 ② 收尾链完整 ③ 脚本语法/导入 OK。任一 ✗ 即回滚。

反例黑名单 (禁做)

每条都是真实踩过的坑。每次 apply 写盘前对照一次, 命中即改方案。

失败处理 (触发 → 一线修复 → 仍失败兜底)

参考集 (按需读)

相关 skill

• trellisx-orchestrate — planning 阶段编排 PRD/design/implement/subtask
• trellisx-spec — spec 破坏式优化
• trellisx-workspace — 维护 .trellis/task.md 任务看板 (含 depends_on → 前置列)
• trellisx-flow — 消费看板前置列 (task.json depends_on) 做 task 级 DAG 调度 (冲突自算边 ∪ 显式前置边); apply 注入的 taskmd 前置列即其调度输入