name: trellis-meta description: | Trellis的元技能，用于理解和定制Mindfold Trellis——为Claude Code和Cursor设计的AI工作流系统。此技能记录了原始的Trellis系统设计。当用户自定义其Trellis安装时，修改应记录在项目本地的`trellis-local`技能中，而不是在此元技能中。在以下情况下使用此技能：(1) 理解Trellis架构，(2) 定制Trellis工作流，(3) 添加命令/代理/钩子，(4) 故障排除问题，或(5) 将Trellis适配到特定项目。

Trellis 元技能

版本兼容性

项目	值
Trellis CLI 版本	0.3.0-beta.5
技能最后更新	2026-01-31
最低 Claude Code 版本	1.0.0+

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

平台兼容性

功能支持矩阵

功能	Claude Code	Cursor	OpenCode（未来）
核心系统
工作空间系统	✅ 完整	✅ 完整	✅ 计划中
任务系统	✅ 完整	✅ 完整	✅ 计划中
规范系统	✅ 完整	✅ 完整	✅ 计划中
斜杠命令	✅ 完整	✅ 完整	⏳ 待定
代理定义	✅ 完整	⚠️ 手动	⏳ 待定
钩子依赖功能
SessionStart钩子	✅ 完整	❌ 无	⏳ 待定
PreToolUse钩子	✅ 完整	❌ 无	⏳ 待定
SubagentStop钩子	✅ 完整	❌ 无	⏳ 待定
自动上下文注入	✅ 完整	❌ 手动	⏳ 待定
Ralph循环	✅ 完整	❌ 无	⏳ 待定
多代理/会话
多代理（当前目录）	✅ 完整	⚠️ 有限	⏳ 待定
多会话（工作树）	✅ 完整	❌ 无	⏳ 待定
`claude --resume`	✅ 完整	❌ 无	⏳ 待定

图例

✅ 完整：功能按文档工作
⚠️ 有限/手动：工作但需要手动步骤
❌ 无：此平台不支持
⏳ 待定：未来支持考虑中

平台特定说明

Claude Code（完整支持）

所有功能按文档工作。钩子提供自动上下文注入和质量执行。

Cursor（部分支持）

工作：工作空间、任务、规范、命令（手动读取）
不工作：钩子、自动注入、Ralph循环、多会话
变通方法：会话开始时手动读取规范文件；无自动质量门

OpenCode（未来考虑）

需要评估OpenCode的扩展/钩子能力
可能需要适配层以兼容钩子
核心基于文件的系统一旦集成应能工作

设计可移植性

定制Trellis时，考虑平台兼容性：

┌─────────────────────────────────────────────────────────────┐
│                    可移植（所有平台）                        │
│  - .trellis/workspace/    - .trellis/tasks/                 │
│  - .trellis/spec/         - .claude/commands/               │
│  - 基于文件的配置         - JSONL上下文文件                 │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                  仅限 Claude Code                            │
│  - .claude/hooks/         - .claude/settings.json 钩子      │
│  - SubagentStop控制       - 自动上下文注入                  │
│  - Ralph循环             - 多会话工作树                     │
│  - claude CLI 功能       - --resume, --agent 标志           │
└─────────────────────────────────────────────────────────────┘

目的

这是Trellis的元技能——它记录了原始的、未经修改的Trellis系统。当为特定项目定制Trellis时，在项目本地技能（trellis-local）中记录更改，将此元技能作为原版Trellis的权威参考。

技能层次结构

~/.claude/skills/
└── trellis-meta/              # 此技能 - 原始Trellis文档
                               # ⚠️ 不要修改以进行项目特定更改

project/.claude/skills/
└── trellis-local/             # 项目特定定制
                               # ✅ 在此记录所有修改

为什么这样分离？

用户可能有多个项目，每个项目有不同的Trellis定制
每个项目的trellis-local技能跟踪其自己的修改
元技能保持清洁，作为原始Trellis的参考
便于升级：比较元技能与新Trellis版本

自迭代协议

当为项目修改Trellis时，遵循此协议：

1. 检查现有项目技能

# 查找项目本地技能
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: |
  为[项目名称]的Trellis项目特定定制。
  此技能记录了对此项目中原版Trellis系统的修改。从trellis-meta继承基础文档。
---

# Trellis 本地 - [项目名称]

## 基础版本
Trellis版本：X.X.X（来自package.json或trellis --version）
初始化日期：YYYY-MM-DD

## 定制

### 添加的命令
（暂无）

### 修改的代理
（暂无）

### 更改的钩子
（暂无）

### 定制的规范
（暂无）

### 工作流更改
（暂无）

---

## 变更日志

### YYYY-MM-DD
- 初始设置

3. 记录每次修改

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

示例：添加新命令

### 添加的命令

#### /trellis:my-command
- **文件**：`.claude/commands/trellis/my-command.md`
- **目的**：[它做什么]
- **添加**：2026-01-31
- **原因**：[添加原因]

示例：修改钩子

### 更改的钩子

#### inject-subagent-context.py
- **更改**：添加了对`my-agent`类型的支持
- **修改的行**：45-67
- **日期**：2026-01-31
- **原因**：[原因]

4. 永远不为项目更改修改元技能

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

Trellis发布新版本
修复原始文档错误
添加原始功能的缺失文档

架构概述

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

系统层

┌─────────────────────────────────────────────────────────────────────┐
│                        用户交互                                      │
│  /trellis:start  /trellis:parallel  /trellis:finish-work            │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                         技能层                                       │
│  .claude/commands/trellis/*.md   （斜杠命令）                       │
│  .claude/agents/*.md             （子代理定义）                     │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                          钩子层                                      │
│  SessionStart     → session-start.py （注入工作流 + 上下文）        │
│  PreToolUse:Task  → inject-subagent-context.py （规范注入）          │
│  SubagentStop     → ralph-loop.py （质量执行）                      │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                       持久层                                         │
│  .trellis/workspace/  （日志、会话历史）                             │
│  .trellis/tasks/      （任务跟踪、上下文文件）                       │
│  .trellis/spec/       （编码指南）                                   │
└─────────────────────────────────────────────────────────────────────┘

关键设计原则

原则	描述
规范注入，非记忆	钩子强制执行规范——代理始终接收上下文
先读后写	在编写代码前理解指南
分层上下文	仅加载相关规范（通过JSONL文件）
人工提交	AI从不提交——人工先验证
纯调度器	调度代理仅编排

核心组件

1. 工作空间系统

跟踪跨会话的开发进度，每个开发者隔离。

.trellis/workspace/
├── index.md                    # 全局概述
└── {开发者}/                   # 每个开发者
    ├── index.md                # 个人索引（@@@auto标记）
    └── journal-N.md            # 会话日志（最多2000行）

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

2. 任务系统

跟踪工作项，基于阶段执行。

.trellis/tasks/{MM-DD-slug-分配者}/
├── task.json           # 元数据、阶段、分支
├── prd.md              # 需求
├── implement.jsonl     # 实现代理的上下文
├── check.jsonl         # 检查代理的上下文
└── debug.jsonl         # 调试代理的上下文

3. 规范系统

维护注入到代理的编码标准。

.trellis/spec/
├── frontend/           # 前端指南
├── backend/            # 后端指南
└── guides/             # 思考指南

4. 钩子系统

自动注入上下文并执行质量。

钩子	时机	目的
`SessionStart`	会话开始	注入工作流、指南
`PreToolUse:Task`	子代理前	通过JSONL注入规范
`SubagentStop:check`	检查代理停止	执行验证（Ralph循环）

5. 代理系统

不同阶段的专门代理。

代理	目的	限制
`dispatch`	编排流水线	纯调度器
`plan`	评估需求	可拒绝不清晰需求
`research`	查找代码模式	只读
`implement`	编写代码	无git提交
`check`	审查和自我修复	Ralph循环控制
`debug`	修复问题	仅精确修复

6. 多代理流水线

通过Git工作树运行并行隔离会话。

plan.py → start.py → 调度 → 实现 → 检查 → 创建pr

定制指南

添加命令

创建.claude/commands/trellis/my-command.md
在trellis-local技能中更新更改

添加代理

创建带有YAML frontmatter的.claude/agents/my-agent.md
更新inject-subagent-context.py以处理新代理类型
在任务目录中创建my-agent.jsonl
更新trellis-local技能

修改钩子

编辑.claude/hooks/中的钩子脚本
在trellis-local技能中记录更改
注明修改了哪些行及原因

扩展规范

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

更改任务工作流

修改task.json中的next_action数组
根据需要更新调度或钩子脚本
在trellis-local技能中记录

资源

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

参考资料/
├── core/              # 所有平台（Claude Code、Cursor等）
├── claude-code/       # 仅Claude Code
├── how-to-modify/     # 修改指南
└── meta/              # 文档与模板

`core/` - 所有平台

文档	内容
`overview.md`	核心系统介绍
`files.md`	所有`.trellis/`文件及其目的
`workspace.md`	工作空间系统、日志、开发者身份
`tasks.md`	任务系统、目录、JSONL上下文文件
`specs.md`	规范系统、指南组织
`scripts.md`	平台独立脚本

`claude-code/` - 仅Claude Code

文档	内容
`overview.md`	Claude Code功能介绍
`hooks.md`	钩子系统、上下文注入
`agents.md`	代理类型、调用、Task工具
`ralph-loop.md`	质量执行机制
`multi-session.md`	并行工作树会话
`worktree-config.md`	worktree.yaml配置
`scripts.md`	仅Claude Code脚本

`how-to-modify/` - 修改指南

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

`meta/` - 文档

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

快速参考

关键脚本

脚本	目的
`get_context.py`	获取会话上下文
`task.py`	任务管理
`add_session.py`	记录会话
`multi_agent/start.py`	启动并行代理

关键路径

路径	目的
`.trellis/.developer`	开发者身份
`.trellis/.current-task`	活动任务指针
`.trellis/workflow.md`	主工作流文档
`.claude/settings.json`	钩子配置

升级协议

当升级Trellis到新版本时：

比较新元技能与当前
审查新版本的更改
检查trellis-local是否有冲突
仔细合并，保留定制
更新trellis-local并添加迁移说明

## 变更日志

### 2026-02-01 - 升级到Trellis X.Y.Z
- 从元技能合并了新钩子行为
- 保留了自定义代理`my-agent`
- 更新了check.jsonl模板