trellis-overview

Table Of Contents

  1. trellis-overview
    1. 一、原理
      1. 1.1 核心原则
      2. 1.2 三阶段工作流
      3. 1.3 三个持久化子系统
      4. 1.4 上下文注入机制
    2. 二、使用
      1. 2.1 快速使用
      2. 2.2 使用工作流
      3. 2.3 命令与 skill 速查
      4. 2.4 流程逃逸
    3. 三、与 Superpowers 的差异
      1. 3.1 定位
      2. 3.2 机制差异
    4. 四、与 OpenSpec 的差异
      1. 4.1 定位
      2. 4.2 OpenSpec artifact 结构（对照）
    5. 五、选型参考

trellis-overview

Trellis 是一套作用于 AI coding 工作流的项目层基础设施。它在 agent 与代码库之间插入 Spec、Task、Workflow 三层持久化结构，并通过各平台 hook 在每轮会话中强制注入 workflow 状态与 spec 上下文——不依赖 agent 记忆或主动检索。由此，AI 开发从”单次会话内的口头对齐”升级为”跨会话、跨平台、可归档、可回流”的工程化流程。

一、原理

1.1 核心原则

原则 含义
Plan before code 先明确做什么，再写代码
Specs injected, not remembered 规范通过 hook/skill 强制注入，不依赖 agent 记忆
Persist everything 研究、决策、经验写入文件；对话会被压缩，文件不会
Incremental development 一次一个 task，边界清晰
Capture learnings 任务结束后将新认知写回 spec，形成项目累积

1.2 三阶段工作流

Phase 1: Plan    → brainstorm + research → prd.md + jsonl 上下文
Phase 2: Execute → implement → check
Phase 3: Finish  → update-spec → commit → finish-work

Phase 1 细化为：

1.0  task.py create          ← 创建任务目录，status=planning
1.1  brainstorm              ← 逐题澄清需求，写入 prd.md
1.2  research（可选）         ← trellis-research 子代理调研
1.3  配置 implement/check.jsonl ← 编排 sub-agent 所需 spec 与研究文件
1.4  task.py start           ← status → in_progress，进入执行

Phase 2 细化为：

2.1  trellis-implement       ← 子代理写代码（默认不 commit）
2.2  trellis-check           ← 子代理对照 spec + lint/type/test 验证
2.3  rollback（按需）         ← 实现偏离 PRD 时回退至 Plan

Phase 3 细化为：

3.1  质量复核
3.2  调试复盘（按需）
3.3  trellis-update-spec     ← 将本轮经验沉淀回 .trellis/spec/
3.4  git commit              ← 主会话驱动提交
3.5  /trellis-finish-work    ← 归档任务 + 写入 journal

1.3 三个持久化子系统

Spec 系统（.trellis/spec/）

  • 按 package/layer 组织编码规范
  • 入口为各层 index.md，含 Pre-Development Checklist 与 Quality Check
  • 通过 hook/skill 按任务 scope 注入，非全局 prompt 堆砌

Task 系统（.trellis/tasks/）

  • 每个任务独立目录：prd.md、implement.jsonl、check.jsonl、task.json
  • 状态机：planning → in_progress → completed（archive）
  • 支持 parent/child 层级、branch 绑定、PR 创建

Workspace 系统（.trellis/workspace/<developer>/）

  • journal-N.md 记录每次 AI 会话（单文件上限 2000 行自动轮转）
  • 跨 session 保留工作脉络，新会话可接续上下文

1.4 上下文注入机制

Trellis 通过平台 hook 在每轮对话注入 workflow breadcrumb，告知 agent 当前 phase 与下一步动作。Sub-agent 平台（Cursor、Claude Code 等）通过 implement.jsonl / check.jsonl 向 trellis-implement / trellis-check 注入精选 spec 与研究文件，避免主会话 context 膨胀。

二、使用

2.1 快速使用

安装

npm install -g @mindfoldhq/trellis@latest

初始化

# 或仅初始化实际使用的平台
trellis init --cursor --opencode --codex -u workspace-name

每个项目一次。生成 .trellis/ 及对应平台的 hooks、skills、agents、commands。

2.2 使用工作流

描述需求
        │
        ▼
trellis-brainstorm          ← skill，逐题澄清，写 prd.md
        │
        ▼
trellis-research（可选）     ← sub-agent，产出 research/*.md
        │
        ▼
trellis-implement           ← sub-agent，按 PRD 写代码
        │
        ▼
trellis-check               ← sub-agent，spec 合规 + lint/type/test
        │
        ▼
trellis-update-spec         ← skill，经验沉淀回 .trellis/spec/
        │
        ▼
/trellis-finish-work        ← command，归档 task + 写 journal

跨会话续作：/trellis-continue（command，从当前 task 的断点继续）

卡点排查：trellis-break-loop（skill，同一 bug 反复出现时）

hook 在每轮对话注入 workflow 状态，驱动 agent 按上述顺序加载 skill / dispatch sub-agent；用户通常只需描述需求，无需手动逐步调用。

/trellis-finish-work 前须 git commit，否则 command 拒绝执行。

2.3 命令与 skill 速查

commands 作用
/trellis-continue 续作当前任务
/trellis-finish-work 归档 task + 写 journal（需先 commit）
Skills / Sub-agents 作用
trellis-brainstorm 需求澄清，写 prd.md
trellis-implement 子代理实现
trellis-check 子代理质量验证
trellis-update-spec 经验沉淀回 spec
trellis-break-loop 反复修同一 bug 时的根因分析

2.4 流程逃逸

Trellis 默认对所有实现类工作强制走 task 流程。以下短语触发 per-turn 逃逸（仅当轮生效）：

意图 触发短语
跳过 task 流程，主会话直接改 “直接改” / “跳过 trellis” / “小修一下”
不 dispatch 子代理 “你直接改” / “别派 sub-agent”

三、与 Superpowers 的差异

相关笔记详见 superpowers-overview

3.1 定位

Trellis Superpowers
层级 项目基础设施 Skills 方法论
核心单元 Spec + Task + Workflow Phase 独立 SKILL.md
规范注入 Hook 强制注入 jsonl 编排的 spec Session hook + agent 主动搜索 skill
工作流 Plan → Implement → Check → Update-spec Brainstorm → Write-plan → Execute-plan
子代理 固定角色（research / implement / check） 动态分派，并行 agent
记忆 workspace journal + spec 回流 episodic-memory 插件（向量搜索）
团队 设计目标含多开发者、spec 版本化 偏个人使用

3.2 机制差异

Trellis：“规范由系统注入”——hook 每轮推送 breadcrumb，phase 状态机约束 [required] 步骤不可跳过。

Superpowers：“规范由 agent 主动发现”——session start 注入 using-superpowers，agent 运行脚本搜索适用 skill；部分 skill 构成断言式门禁（TDD、verification-before-completion 等）。

计划粒度：Superpowers 将计划拆为 2-5 分钟任务并设 review checkpoint；Trellis 以 PRD 驱动，research 可选，粒度由 brainstorm 产出决定。

Skill 有效性验证：Superpowers 用压力场景 subagent 测试 agent 是否遵守 skill；Trellis 依赖 trellis-check 子代理 + lint/type/test + spec 合规检查。

四、与 OpenSpec 的差异

相关笔记详见 openspec-overview

4.1 定位

Trellis OpenSpec
层级 完整 AI 开发生命周期 Spec-Driven Development 变更管线
规划产物 单一 prd.md（向 design/tasks 拆分演进中） 4 个独立 artifact + delta specs
Spec 管理 静态 spec 目录 + 任务结束 ad-hoc 更新 delta specs → verify → merge 回 main specs
探索阶段 research 可选，无专门 explore 模式 /opsx:explore 明确禁止写代码

4.2 OpenSpec artifact 结构（对照）

openspec/changes/<change>/
├── proposal.md    ← 为什么做
├── specs/         ← delta specs
├── design.md      ← 怎么做
└── tasks.md       ← 执行清单

Trellis 当前以 prd.md 承载 Goal + Requirements + AC + Technical Notes。项目内部已识别差距，规划引入 design.md + tasks.md 拆分、check agent 增加 AC 逐项验证、explore 模式等 OpenSpec 模式。

五、选型参考

Trellis 的差异化不在单项能力最强，而在 多平台 + 项目持久化 + phase 门禁 的组合覆盖。其演进方向明确吸收 Superpowers 的 workflow enforcement 与 skill 结构、OpenSpec 的 artifact 拆分与 spec 验证。

笔者认为除了需要严肃TDD开发或希望开发保证质量的场景需要使用Superpowers，Trellis的设计更优。