trellis-meta

Trellis 元技能

版本兼容性

项目	值
Trellis CLI 版本	0.4.0-beta.8
技能最后更新日期	2026-03-24
最低 Claude Code 版本	1.0.0+
最低 Node.js 版本	>=18.17.0

⚠️ 版本不匹配警告：如果你的 Trellis CLI 版本与上述版本不同，某些功能可能无法按文档所述运行。运行 trellis --version 进行检查。

---

平台兼容性

功能支持矩阵

功能	Claude Code	iFlow	Cursor	OpenCode	Codex	Kilo	Kiro	Gemini CLI	Antigravity	Qoder	CodeBuddy
核心系统
工作区系统	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整
任务系统	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整
规格系统	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整
命令/技能	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 技能	✅ 完整	✅ 技能	✅ TOML	✅ 工作流	✅ 技能	✅ 完整
Agent 定义	✅ 完整	✅ 完整	⚠️ 手动	✅ 完整	✅ TOML	⚠️ 手动	⚠️ 手动	⚠️ 手动	⚠️ 手动	⚠️ 手动	⚠️ 手动
共享 Agent 技能	—	—	—	—	✅ 完整	—	—	—	—	—	—
依赖钩子的功能
SessionStart 钩子	✅ 完整	✅ 完整	❌ 无	❌ 无	⚠️ 可选	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无
PreToolUse 钩子	✅ 完整	✅ 完整	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无
SubagentStop 钩子	✅ 完整	✅ 完整	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无
自动注入上下文	✅ 完整	✅ 完整	❌ 手动	❌ 手动	❌ 手动	❌ 手动	❌ 手动	❌ 手动	❌ 手动	❌ 手动	❌ 手动
Ralph Loop	✅ 完整	✅ 完整	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无
多 Agent/会话
多 Agent（当前目录）	✅ 完整	✅ 完整	⚠️ 有限	⚠️ 有限	⚠️ 有限	⚠️ 有限	⚠️ 有限	⚠️ 有限	⚠️ 有限	⚠️ 有限	⚠️ 有限
多会话（工作树）	✅ 完整	✅ 完整	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无

图例

• ✅ 完整：功能按文档所述运行
• ⚠️ 有限/手动：功能可用，但需要手动操作
• ❌ 无/手动：不支持，或需要手动变通处理

平台类别

完整钩子支持（Claude Code、iFlow）

所有功能均按文档所述正常运行。钩子可自动注入上下文并强制执行质量标准。iFlow 与 Claude Code 使用相同的 Python 钩子系统。

部分钩子支持（Codex）

• 可用：工作区、任务、规范、技能（.codex/skills/ + .agents/skills/ 共享层）、TOML Agent 定义（.codex/agents/）、可选的 SessionStart 钩子
• 不可用：PreToolUse、SubagentStop、Ralph Loop、多会话
• 注意：SessionStart 钩子需要在 ~/.codex/config.toml 中设置 codex_hooks = true

仅支持命令（Cursor、OpenCode、Kilo、Kiro、Gemini CLI、Antigravity、Qoder、CodeBuddy）

• 可用：工作区、任务、规范、命令/技能（平台特定格式）
• 不可用：钩子、自动注入、Ralph Loop、多会话
• 变通方法：在会话开始时手动读取规范文件；没有自动质量关卡
• 注意：每个平台都使用自己的命令格式（Kiro/Qoder 使用 Skills，Gemini 使用 TOML，Antigravity 使用 Workflows，CodeBuddy 使用嵌套 Markdown 命令）

面向可移植性的设计

自定义 Trellis 时，请考虑平台兼容性：

┌─────────────────────────────────────────────────────────────┐
│                 PORTABLE (All 11 Platforms)                  │
│  - .trellis/workspace/    - .trellis/tasks/                 │
│  - .trellis/spec/         - Platform commands/skills        │
│  - File-based configs     - JSONL context files             │
│  - config.yaml            - Monorepo packages support       │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│         SHARED AGENT SKILLS (agentskills.io standard)       │
│  - .agents/skills/          (Codex + universal agent CLIs)  │
└─────────────────────────────┬───────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│              HOOK-CAPABLE (Claude Code + iFlow)              │
│  - .claude/hooks/ or .iflow/hooks/                          │
│  - settings.json hook configuration                         │
│  - Auto context injection   - SubagentStop control          │
│  - Ralph Loop               - Multi-Session worktrees       │
│  - Task lifecycle hooks     - Dynamic spec discovery        │
└─────────────────────────────────────────────────────────────┘

---

目的

这是 Trellis 的元技能——用于记录原始、未经修改的 Trellis 系统。针对特定项目自定义 Trellis 时，请在项目本地技能（trellis-local）中记录更改，并将此元技能保留为原版 Trellis 的权威参考。

技能层级

~/.claude/skills/
└── trellis-meta/              # THIS SKILL - Original Trellis documentation
                               # ⚠️ DO NOT MODIFY for project-specific changes

project/.claude/skills/
└── trellis-local/             # Project-specific customizations
                               # ✅ Record all modifications here

为何要这样区分？

• 用户可能有多个采用不同 Trellis 自定义配置的项目
• 每个项目的 trellis-local 技能都会记录其自身的修改
• 元技能保持干净，作为原始 Trellis 的参考
• 便于升级：将元技能与新版 Trellis 进行比较

---

自我迭代协议

为项目修改 Trellis 时，请遵循以下协议：

1. 检查是否已有项目技能

# Look for project-local skill
ls -la .claude/skills/trellis-local/

2. 如果缺少项目技能，则创建

如果不存在 trellis-local，请创建它：

mkdir -p .claude/skills/trellis-local

然后创建 .claude/skills/trellis-local/SKILL.md：

---
name: trellis-local
description: |
  Project-specific Trellis customizations for [PROJECT_NAME].
  This skill documents modifications made to the vanilla Trellis system
  in this project. Inherits from trellis-meta for base documentation.
---

# Trellis Local - [PROJECT_NAME]

## Base Version

Trellis version: X.X.X (from package.json or trellis --version)
Date initialized: YYYY-MM-DD

## Customizations

### Commands Added

(none yet)

### Agents Modified

(none yet)

### Hooks Changed

(none yet)

### Specs Customized

(none yet)

### Workflow Changes

(none yet)

---

## Changelog

### YYYY-MM-DD

- Initial setup

3. 记录每项修改

对 Trellis 进行任何更改时，都要更新 trellis-local/SKILL.md：

示例：添加新命令

### Commands Added

#### /trellis:my-command

- **File**: `.claude/commands/trellis/my-command.md`
- **Purpose**: [what it does]
- **Added**: 2026-01-31
- **Why**: [reason for adding]

示例：修改钩子

### Hooks Changed

#### inject-subagent-context.py

- **Change**: Added support for `my-agent` type
- **Lines modified**: 45-67
- **Date**: 2026-01-31
- **Why**: [reason]

4. 切勿因项目更改而修改元技能

仅在以下情况下更新 trellis-meta 技能：

• Trellis 发布新版本
• 修复原始文档中的错误
• 为原始功能补充缺失的文档

---

架构概览

Trellis 通过强制注入上下文，将 AI 助手转变为结构化开发伙伴。

系统层

┌─────────────────────────────────────────────────────────────────────┐
│                        USER INTERACTION                              │
│  /trellis:start  /trellis:brainstorm  /trellis:parallel             │
│  /trellis:finish-work  /trellis:before-dev  /trellis:check          │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                         SKILLS LAYER                                 │
│  .claude/commands/trellis/*.md   (17 slash commands)                │
│  .claude/agents/*.md             (6 sub-agent definitions)          │
│  .agents/skills/*/SKILL.md       (shared agent skills layer)        │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                          HOOKS LAYER                                 │
│  SessionStart      → session-start.py (workflow + context + status) │
│  PreToolUse:Agent  → inject-subagent-context.py (spec injection)    │
│  SubagentStop      → ralph-loop.py (quality enforcement)            │
│  Task Lifecycle    → config.yaml hooks (after_create/start/finish/  │
│                      archive → e.g. Linear sync)                    │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                       PERSISTENCE LAYER                              │
│  .trellis/workspace/  (journals, session history)                   │
│  .trellis/tasks/      (task tracking, context files, subtasks)      │
│  .trellis/spec/       (coding guidelines, monorepo per-package)     │
│  .trellis/config.yaml (packages, hooks, update.skip, spec_scope)   │
└─────────────────────────────────────────────────────────────────────┘

关键设计原则

原则	说明
注入规范，而非依赖记忆	钩子强制应用规范——Agent 始终能获得上下文
先读后写	编写代码前先理解指南
分层上下文	仅加载相关规范（通过 JSONL 文件）
由人提交	AI 从不提交——由人先进行验证
纯调度器	调度 Agent 只负责协调

---

核心组件

1. 工作区系统

通过按开发者隔离的方式，跨会话跟踪开发进度。

.trellis/workspace/
├── index.md                    # Global overview
└── {developer}/                # Per-developer
    ├── index.md                # Personal index (@@@auto markers)
    └── journal-N.md            # Session journals (max 2000 lines)

关键文件：.trellis/.developer（身份）、journals（会话历史）

2. 任务系统

通过基于阶段的执行、父子子任务和生命周期钩子来跟踪工作项。

.trellis/tasks/{MM-DD-slug}/
├── task.json           # Metadata, phases, branch, subtasks
├── prd.md              # Requirements
├── info.md             # Technical design (optional)
├── implement.jsonl     # Context for implement agent
├── check.jsonl         # Context for check agent
├── debug.jsonl         # Context for debug agent
├── research.jsonl      # Context for research agent (optional)
└── cr.jsonl            # Context for code review (optional)

3. 规范系统

维护并注入给 Agent 的编码标准。支持单仓库和 Monorepo 布局。

# Single repo
.trellis/spec/
├── frontend/           # Frontend guidelines
├── backend/            # Backend guidelines
└── guides/             # Thinking guides

# Monorepo (per-package)
.trellis/spec/
├── <package-name>/     # Per-package specs
│   ├── backend/
│   ├── frontend/
│   └── unit-test/
└── guides/             # Shared thinking guides

4. Hooks 系统

自动注入上下文并确保质量。

Claude Code / iFlow Hooks（settings.json）：

Hook	时机	用途
SessionStart	启动、清除、压缩事件	注入工作流、指南、任务状态
PreToolUse:Agent	启动子 Agent 前	通过 JSONL 注入规范
PreToolUse:Task	使用 Task 工具前（旧版）	与 Agent 相同（CC 将 Task 重命名为 Agent）
SubagentStop:check	检查 Agent 停止	强制验证（Ralph Loop）

任务生命周期 Hooks（config.yaml）：

事件	时机	用途
after_create	创建任务时	例如：创建 Linear 问题
after_start	开始任务时	例如：更新 Linear 状态
after_finish	完成任务时	例如：标记 Linear 为已完成
after_archive	归档任务时	例如：关闭 Linear 问题

5. Agent 系统

针对不同阶段的专用 Agent。

Agent	用途	限制
dispatch	编排流水线	纯调度器
plan	评估需求	可以拒绝不明确的需求
research	查找代码模式	只读
implement	编写代码	不得提交 git
check	审查并自行修复	由 Ralph Loop 控制
debug	修复问题	仅进行精准修复

6. 多 Agent 流水线

通过 Git worktrees 并行运行相互隔离的会话。

plan.py → start.py → Dispatch → implement → check → create-pr

---

自定义指南

添加命令

1. 创建 .claude/commands/trellis/my-command.md
2. 更新 trellis-local 技能以反映此更改

添加 Agent

1. 创建包含 YAML frontmatter 的 .claude/agents/my-agent.md
2. 更新 inject-subagent-context.py，以处理新的 Agent 类型
3. 在任务目录中创建 my-agent.jsonl
4. 更新 trellis-local 技能

修改 Hooks

1. 编辑 .claude/hooks/ 中的 Hook 脚本
2. 在 trellis-local 技能中记录此更改
3. 注明修改了哪些行以及原因

扩展规范

1. 在 .trellis/spec/my-category/ 中创建新类别
2. 添加 index.md 和指南文件
3. 在 JSONL 上下文文件中引用
4. 更新 trellis-local 技能

更改任务工作流

1. 修改 task.json 中的 next_action 数组
2. 根据需要更新 dispatch 或 Hook 脚本
3. 在 trellis-local 技能中记录

---

资源

参考文档按平台兼容性组织：

references/
├── core/              # All Platforms (Claude Code, Cursor, etc.)
├── claude-code/       # Claude Code Only
├── how-to-modify/     # Modification Guides
└── meta/              # Documentation & Templates

core/ - 所有平台

文档	内容
overview.md	核心系统介绍
files.md	所有 .trellis/ 文件及其用途
workspace.md	工作区系统、日志、开发者身份
tasks.md	任务系统、子任务、生命周期 Hooks、JSONL
specs.md	规范系统、monorepo 布局、指南
scripts.md	平台无关脚本
config.md	config.yaml 完整参考

claude-code/ - 仅限 Claude Code

文档	内容
overview.md	Claude Code 功能介绍
hooks.md	Hook 系统、上下文注入
agents.md	Agent 类型、调用方式、Task 工具
ralph-loop.md	质量保障机制
multi-session.md	并行 worktree 会话
worktree-config.md	worktree.yaml 配置
scripts.md	仅限 Claude Code 的脚本

how-to-modify/ - 修改指南

文档	场景
overview.md	所有修改的快速参考
add-command.md	添加斜杠命令
add-agent.md	添加新的 Agent 类型
add-spec.md	添加 spec 类别
add-phase.md	添加工作流阶段
modify-hook.md	修改 Hook 行为
change-verify.md	更改验证命令

meta/ - 文档

文档	内容
platform-compatibility.md	详细的平台支持矩阵
self-iteration-guide.md	如何记录自定义内容
trellis-local-template.md	项目本地技能模板

---

快速参考

关键脚本

脚本	用途
get_context.py	获取会话上下文（文本/JSON）
task.py	任务管理（16 个子命令）
add_session.py	记录会话
create_bootstrap.py	首次 spec 引导
multi_agent/start.py	启动并行 Agent
multi_agent/status.py	监控 Agent 状态
multi_agent/create_pr.py	从 worktree 创建 PR

关键路径

路径	用途
.trellis/.developer	开发者身份
.trellis/.current-task	当前任务指针
.trellis/workflow.md	主工作流文档
.trellis/config.yaml	项目配置（软件包、Hook）
.trellis/worktree.yaml	多会话配置
.claude/settings.json	Hook 配置
.agents/skills/	共享的 Agent 技能（agentskills.io）

---

升级流程

将 Trellis 升级到新版本时：

1. 比较 新版 meta-skill 与当前版本
2. 审阅 新版本中的变更
3. 检查 trellis-local 是否存在冲突
4. 谨慎合并，保留自定义内容
5. 更新 trellis-local，添加迁移说明

## Changelog

### 2026-02-01 - Upgraded to Trellis X.Y.Z

- Merged new hook behavior from meta-skill
- Kept custom agent `my-agent`
- Updated check.jsonl template