Back to Details

trellis-meta

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Trellis Meta-Skill

Trellis 元技能

Version Compatibility

版本兼容性

ItemValue
Trellis CLI Version0.3.0-beta.5
Skill Last Updated2026-01-31
Min Claude Code Version1.0.0+
⚠️ Version Mismatch Warning: If your Trellis CLI version differs from above, some features may not work as documented. Run 
trellis --version
to check.
项值
Trellis CLI 版本0.3.0-beta.5
技能最后更新时间2026-01-31
最低 Claude Code 版本1.0.0+
⚠️ 版本不匹配警告：如果你的Trellis CLI版本与上述版本不同，部分功能可能无法按文档所述工作。运行
trellis --version
进行检查。

Platform Compatibility

平台兼容性

Feature Support Matrix

功能支持矩阵

FeatureClaude CodeCursorOpenCode (Future)
Core Systems
Workspace system✅ Full✅ Full✅ Planned
Task system✅ Full✅ Full✅ Planned
Spec system✅ Full✅ Full✅ Planned
Slash commands✅ Full✅ Full⏳ TBD
Agent definitions✅ Full⚠️ Manual⏳ TBD
Hook-Dependent Features
SessionStart hook✅ Full❌ None⏳ TBD
PreToolUse hook✅ Full❌ None⏳ TBD
SubagentStop hook✅ Full❌ None⏳ TBD
Auto context injection✅ Full❌ Manual⏳ TBD
Ralph Loop✅ Full❌ None⏳ TBD
Multi-Agent/Session
Multi-Agent (current dir)✅ Full⚠️ Limited⏳ TBD
Multi-Session (worktrees)✅ Full❌ None⏳ TBD
claude --resume
✅ Full❌ None⏳ TBD
功能Claude CodeCursorOpenCode（未来）
核心系统
工作区系统✅ 完全支持✅ 完全支持✅ 计划支持
任务系统✅ 完全支持✅ 完全支持✅ 计划支持
规范系统✅ 完全支持✅ 完全支持✅ 计划支持
斜杠命令✅ 完全支持✅ 完全支持⏳ 待定
Agent 定义✅ 完全支持⚠️ 手动支持⏳ 待定
依赖钩子的功能
SessionStart 钩子✅ 完全支持❌ 不支持⏳ 待定
PreToolUse 钩子✅ 完全支持❌ 不支持⏳ 待定
SubagentStop 钩子✅ 完全支持❌ 不支持⏳ 待定
自动上下文注入✅ 完全支持❌ 手动操作⏳ 待定
Ralph Loop✅ 完全支持❌ 不支持⏳ 待定
多Agent/会话
多Agent（当前目录）✅ 完全支持⚠️ 有限支持⏳ 待定
多会话（工作树）✅ 完全支持❌ 不支持⏳ 待定
claude --resume
✅ 完全支持❌ 不支持⏳ 待定

Legend

图例

  • ✅ Full: Feature works as documented
  • ⚠️ Limited/Manual: Works but requires manual steps
  • ❌ None: Not supported on this platform
  • ⏳ TBD: Under consideration for future support
  • ✅ 完全支持：功能按文档所述正常工作
  • ⚠️ 有限/手动支持：可工作但需要手动步骤
  • ❌ 不支持：该平台不支持此功能
  • ⏳ 待定：正在考虑未来支持

Platform-Specific Notes

平台特定说明

Claude Code (Full Support)

Claude Code（完全支持）

All features work as documented. Hooks provide automatic context injection and quality enforcement.
所有功能均按文档所述工作。钩子提供自动上下文注入和质量管控。

Cursor (Partial Support)

Cursor（部分支持）

  • Works: Workspace, tasks, specs, commands (read manually)
  • Doesn't work: Hooks, auto-injection, Ralph Loop, Multi-Session
  • Workaround: Manually read spec files at session start; no automatic quality gates
  • 可用功能：工作区、任务、规范、命令（需手动读取）
  • 不可用功能：钩子、自动注入、Ralph Loop、多会话
  • 解决方法：会话开始时手动读取规范文件；无自动质量关卡

OpenCode (Future Consideration)

OpenCode（未来考虑）

  • Need to evaluate OpenCode's extension/hook capabilities
  • May require adapter layer for hook compatibility
  • Core file-based systems should work once integrated
  • 需要评估OpenCode的扩展/钩子能力
  • 可能需要适配层以实现钩子兼容性
  • 核心基于文件的系统集成后应可正常工作

Designing for Portability

可移植性设计

When customizing Trellis, consider platform compatibility:
┌─────────────────────────────────────────────────────────────┐
│                    PORTABLE (All Platforms)                  │
│  - .trellis/workspace/    - .trellis/tasks/                 │
│  - .trellis/spec/         - .claude/commands/               │
│  - File-based configs     - JSONL context files             │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                  CLAUDE CODE ONLY                            │
│  - .claude/hooks/         - .claude/settings.json hooks     │
│  - SubagentStop control   - Auto context injection          │
│  - Ralph Loop             - Multi-Session worktrees         │
│  - claude CLI features    - --resume, --agent flags         │
└─────────────────────────────────────────────────────────────┘
自定义Trellis时，请考虑平台兼容性：
┌─────────────────────────────────────────────────────────────┐
│                    可移植（全平台）                            │
│  - .trellis/workspace/    - .trellis/tasks/                 │
│  - .trellis/spec/         - .claude/commands/               │
│  - 基于文件的配置     - JSONL 上下文文件             │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                  仅支持CLAUDE CODE                            │
│  - .claude/hooks/         - .claude/settings.json hooks     │
│  - SubagentStop 控制   - 自动上下文注入          │
│  - Ralph Loop             - 多会话工作树         │
│  - claude CLI 功能    - --resume, --agent 标志         │
└─────────────────────────────────────────────────────────────┘

Purpose

用途

This is the meta-skill for Trellis - it documents the original, unmodified Trellis system. When customizing Trellis for a specific project, record changes in a project-local skill (
trellis-local
), keeping this meta-skill as the authoritative reference for vanilla Trellis.
这是Trellis的元技能——它记录了原始、未修改的Trellis系统。针对特定项目自定义Trellis时，请将更改记录在项目本地技能（
trellis-local
）中，保持本元技能作为原生Trellis的权威参考。

Skill Hierarchy

技能层级

~/.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
Why this separation?
  • User may have multiple projects with different Trellis customizations
  • Each project's 
    trellis-local
    skill tracks ITS OWN modifications
  • The meta-skill remains clean as the reference for original Trellis
  • Enables easy upgrades: compare meta-skill with new Trellis version
~/.claude/skills/
└── trellis-meta/              # 本技能 - 原始Trellis文档
                               # ⚠️ 请勿针对项目特定修改进行更改

project/.claude/skills/
└── trellis-local/             # 项目特定自定义
                               # ✅ 所有修改均记录于此
为何采用这种分离方式？
  • 用户可能有多个项目，每个项目的Trellis自定义不同
  • 每个项目的
    trellis-local
    技能跟踪其自身的修改
  • 元技能保持整洁，作为原始Trellis的参考
  • 便于升级：将元技能与新版本Trellis进行对比

Self-Iteration Protocol

自迭代协议

When modifying Trellis for a project, follow this protocol:
针对项目修改Trellis时，请遵循以下协议：

1. Check for Existing Project Skill

1. 检查是否存在项目技能

bash
undefined
bash
undefined

Look for project-local skill

查找项目本地技能

ls -la .claude/skills/trellis-local/
undefined
ls -la .claude/skills/trellis-local/
undefined

2. Create Project Skill if Missing

2. 若缺失则创建项目技能

If no 
trellis-local
exists, create it:
bash
mkdir -p .claude/skills/trellis-local
Then create 
.claude/skills/trellis-local/SKILL.md
:
markdown
---
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
不存在，创建它：
bash
mkdir -p .claude/skills/trellis-local
然后创建
.claude/skills/trellis-local/SKILL.md
：
markdown
---
name: trellis-local
description: |
  针对[PROJECT_NAME]的项目特定Trellis自定义。
  本技能记录了本项目中对原生Trellis系统所做的修改。继承自trellis-meta以获取基础文档。
---

Trellis Local - [PROJECT_NAME]

Trellis Local - [PROJECT_NAME]

Base Version

基础版本

Trellis version: X.X.X (from package.json or trellis --version) Date initialized: YYYY-MM-DD
Trellis版本: X.X.X（来自package.json或trellis --version） 初始化日期: YYYY-MM-DD

Customizations

自定义内容

Commands Added

添加的命令

(none yet)
(暂无)

Agents Modified

修改的Agent

(none yet)
(暂无)

Hooks Changed

更改的钩子

(none yet)
(暂无)

Specs Customized

自定义的规范

(none yet)
(暂无)

Workflow Changes

工作流更改

(none yet)
(暂无)

Changelog

更新日志

YYYY-MM-DD

YYYY-MM-DD

  • Initial setup
undefined
  • 初始设置
undefined

3. Record Every Modification

3. 记录每一项修改

When making ANY change to Trellis, update 
trellis-local/SKILL.md
:
对Trellis进行任何更改时，更新
trellis-local/SKILL.md
：

Example: Adding a new command

示例：添加新命令

markdown
undefined
markdown
undefined

Commands Added

添加的命令

/trellis:my-command

/trellis:my-command

  • File: 
    .claude/commands/trellis/my-command.md
  • Purpose: [what it does]
  • Added: 2026-01-31
  • Why: [reason for adding]
undefined
  • 文件: 
    .claude/commands/trellis/my-command.md
  • 用途: [功能说明]
  • 添加时间: 2026-01-31
  • 原因: [添加理由]
undefined

Example: Modifying a hook

示例：修改钩子

markdown
undefined
markdown
undefined

Hooks Changed

更改的钩子

inject-subagent-context.py

inject-subagent-context.py

  • Change: Added support for 
    my-agent
    type
  • Lines modified: 45-67
  • Date: 2026-01-31
  • Why: [reason]
undefined
  • 更改: 新增对
    my-agent
    类型的支持
  • 修改行: 45-67
  • 日期: 2026-01-31
  • 原因: [修改理由]
undefined

4. Never Modify Meta-Skill for Project Changes

4. 请勿为项目修改元技能

The 
trellis-meta
skill should ONLY be updated when:
  • Trellis releases a new version
  • Fixing documentation errors in the original
  • Adding missing documentation for original features
trellis-meta
技能仅在以下情况更新：
  • Trellis发布新版本
  • 修复原始文档中的错误
  • 为原始功能添加缺失的文档

Architecture Overview

架构概述

Trellis transforms AI assistants into structured development partners through enforced context injection.
Trellis通过强制上下文注入将AI助手转变为结构化的开发伙伴。

System Layers

系统层级

┌─────────────────────────────────────────────────────────────────────┐
│                        USER INTERACTION                              │
│  /trellis:start  /trellis:parallel  /trellis:finish-work            │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                         SKILLS LAYER                                 │
│  .claude/commands/trellis/*.md   (slash commands)                   │
│  .claude/agents/*.md             (sub-agent definitions)            │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                          HOOKS LAYER                                 │
│  SessionStart     → session-start.py (injects workflow + context)   │
│  PreToolUse:Task  → inject-subagent-context.py (spec injection)     │
│  SubagentStop     → ralph-loop.py (quality enforcement)             │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                       PERSISTENCE LAYER                              │
│  .trellis/workspace/  (journals, session history)                   │
│  .trellis/tasks/      (task tracking, context files)                │
│  .trellis/spec/       (coding guidelines)                           │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│                        用户交互                              │
│  /trellis:start  /trellis:parallel  /trellis:finish-work            │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                         技能层                                 │
│  .claude/commands/trellis/*.md   (斜杠命令)                   │
│  .claude/agents/*.md             (子Agent定义)            │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                          钩子层                                 │
│  SessionStart     → session-start.py (注入工作流 + 上下文)   │
│  PreToolUse:Task  → inject-subagent-context.py (规范注入)     │
│  SubagentStop     → ralph-loop.py (质量管控)             │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                       持久化层                              │
│  .trellis/workspace/  (日志、会话历史)                   │
│  .trellis/tasks/      (任务跟踪、上下文文件)                │
│  .trellis/spec/       (编码规范)                           │
└─────────────────────────────────────────────────────────────────────┘

Key Design Principles

核心设计原则

PrincipleDescription
Specs Injected, Not RememberedHooks enforce specs - agents always receive context
Read Before WriteUnderstand guidelines before writing code
Layered ContextOnly relevant specs load (via JSONL files)
Human CommitsAI never commits - human validates first
Pure DispatcherDispatch agent only orchestrates
原则描述
规范注入，而非记忆钩子强制注入规范 - Agent始终接收上下文
先读再写编写代码前先理解规范
分层上下文仅加载相关规范（通过JSONL文件）
人工提交AI从不提交代码 - 需人工先验证
纯调度器调度Agent仅负责协调

Core Components

核心组件

1. Workspace System

1. 工作区系统

Track development progress across sessions with per-developer isolation.
.trellis/workspace/
├── index.md                    # Global overview
└── {developer}/                # Per-developer
    ├── index.md                # Personal index (@@@auto markers)
    └── journal-N.md            # Session journals (max 2000 lines)
Key files: 
.trellis/.developer
(identity), journals (session history)
按开发者隔离跟踪跨会话的开发进度。
.trellis/workspace/
├── index.md                    | 全局概览
└── {developer}/                | 按开发者划分
    ├── index.md                | 个人索引（@@@auto标记）
    └── journal-N.md            | 会话日志（最多2000行）
关键文件：
.trellis/.developer
（身份标识）、日志（会话历史）

2. Task System

2. 任务系统

Track work items with phase-based execution.
.trellis/tasks/{MM-DD-slug-assignee}/
├── task.json           # Metadata, phases, branch
├── prd.md              # Requirements
├── implement.jsonl     # Context for implement agent
├── check.jsonl         # Context for check agent
└── debug.jsonl         # Context for debug agent
按阶段执行跟踪工作项。
.trellis/tasks/{MM-DD-slug-assignee}/
├── task.json           | 元数据、阶段、分支
├── prd.md              | 需求文档
├── implement.jsonl     | 实现Agent的上下文
├── check.jsonl         | 检查Agent的上下文
└── debug.jsonl         | 调试Agent的上下文

3. Spec System

3. 规范系统

Maintain coding standards that get injected to agents.
.trellis/spec/
├── frontend/           # Frontend guidelines
├── backend/            # Backend guidelines
└── guides/             # Thinking guides
维护将注入Agent的编码标准。
.trellis/spec/
├── frontend/           | 前端规范
├── backend/            | 后端规范
└── guides/             | 思考指南

4. Hooks System

4. 钩子系统

Automatically inject context and enforce quality.
HookWhenPurpose
SessionStart
Session beginsInject workflow, guidelines
PreToolUse:Task
Before sub-agentInject specs via JSONL
SubagentStop:check
Check agent stopsEnforce verification (Ralph Loop)
自动注入上下文并执行质量管控。
钩子触发时机用途
SessionStart
会话开始时注入工作流、规范
PreToolUse:Task
子Agent执行前通过JSONL注入规范
SubagentStop:check
检查Agent停止时执行验证（Ralph Loop）

5. Agent System

5. Agent系统

Specialized agents for different phases.
AgentPurposeRestriction
dispatch
Orchestrate pipelinePure dispatcher
plan
Evaluate requirementsCan reject unclear reqs
research
Find code patternsRead-only
implement
Write codeNo git commit
check
Review and self-fixRalph Loop controlled
debug
Fix issuesPrecise fixes only
针对不同阶段的专用Agent。
Agent用途限制
dispatch
协调流水线纯调度器
plan
评估需求可拒绝不明确的需求
research
查找代码模式只读
implement
编写代码不执行Git提交
check
评审并自修复受Ralph Loop控制
debug
修复问题仅精确修复

6. Multi-Agent Pipeline

6. 多Agent流水线

Run parallel isolated sessions via Git worktrees.
plan.py → start.py → Dispatch → implement → check → create-pr
通过Git工作树运行并行隔离会话。
plan.py → start.py → Dispatch → implement → check → create-pr

Customization Guide

自定义指南

Adding a Command

添加命令

  1. Create 
    .claude/commands/trellis/my-command.md
  2. Update 
    trellis-local
    skill with the change
  1. 创建
    .claude/commands/trellis/my-command.md
  2. 在
    trellis-local
    技能中记录此更改

Adding an Agent

添加Agent

  1. Create 
    .claude/agents/my-agent.md
    with YAML frontmatter
  2. Update 
    inject-subagent-context.py
    to handle new agent type
  3. Create 
    my-agent.jsonl
    in task directories
  4. Update 
    trellis-local
    skill
  1. 创建带YAML前置内容的
    .claude/agents/my-agent.md
  2. 更新
    inject-subagent-context.py
    以支持新Agent类型
  3. 在任务目录中创建
    my-agent.jsonl
  4. 更新
    trellis-local
    技能

Modifying Hooks

修改钩子

  1. Edit the hook script in 
    .claude/hooks/
  2. Document the change in 
    trellis-local
    skill
  3. Note which lines were modified and why
  1. 编辑
    .claude/hooks/
    中的钩子脚本
  2. 在
    trellis-local
    技能中记录更改
  3. 注明修改的行号及原因

Extending Specs

扩展规范

  1. Create new category in 
    .trellis/spec/my-category/
  2. Add 
    index.md
    and guideline files
  3. Reference in JSONL context files
  4. Update 
    trellis-local
    skill
  1. 在
    .trellis/spec/my-category/
    中创建新分类
  2. 添加
    index.md
    和规范文件
  3. 在JSONL上下文文件中引用
  4. 更新
    trellis-local
    技能

Changing Task Workflow

修改任务工作流

  1. Modify 
    next_action
    array in 
    task.json
  2. Update dispatch or hook scripts as needed
  3. Document in 
    trellis-local
    skill
  1. 修改
    task.json
    中的
    next_action
    数组
  2. 根据需要更新调度或钩子脚本
  3. 在
    trellis-local
    技能中记录

Resources

资源

Reference documents are organized by platform compatibility:
references/
├── core/              # All Platforms (Claude Code, Cursor, etc.)
├── claude-code/       # Claude Code Only
├── how-to-modify/     # Modification Guides
└── meta/              # Documentation & Templates
参考文档按平台兼容性组织：
references/
├── core/              | 全平台（Claude Code、Cursor等）
├── claude-code/       | 仅Claude Code
├── how-to-modify/     | 修改指南
└── meta/              | 文档与模板

core/
- All Platforms

core/
- 全平台

DocumentContent
overview.md
Core systems introduction
files.md
All 
.trellis/
files with purposes
workspace.md
Workspace system, journals, developer identity
tasks.md
Task system, directories, JSONL context files
specs.md
Spec system, guidelines organization
scripts.md
Platform-independent scripts
文档内容
overview.md
核心系统介绍
files.md
所有
.trellis/
文件及其用途
workspace.md
工作区系统、日志、开发者身份
tasks.md
任务系统、目录、JSONL上下文文件
specs.md
规范系统、规范组织
scripts.md
平台无关脚本

claude-code/
- Claude Code Only

claude-code/
- 仅Claude Code

DocumentContent
overview.md
Claude Code features introduction
hooks.md
Hook system, context injection
agents.md
Agent types, invocation, Task tool
ralph-loop.md
Quality enforcement mechanism
multi-session.md
Parallel worktree sessions
worktree-config.md
worktree.yaml configuration
scripts.md
Claude Code only scripts
文档内容
overview.md
Claude Code功能介绍
hooks.md
钩子系统、上下文注入
agents.md
Agent类型、调用、Task工具
ralph-loop.md
质量管控机制
multi-session.md
并行工作树会话
worktree-config.md
worktree.yaml配置
scripts.md
仅Claude Code可用脚本

how-to-modify/
- Modification Guides

how-to-modify/
- 修改指南

DocumentScenario
overview.md
Quick reference for all modifications
add-command.md
Adding slash commands
add-agent.md
Adding new agent types
add-spec.md
Adding spec categories
add-phase.md
Adding workflow phases
modify-hook.md
Modifying hook behavior
change-verify.md
Changing verify commands
文档场景
overview.md
所有修改的快速参考
add-command.md
添加斜杠命令
add-agent.md
添加新Agent类型
add-spec.md
添加规范分类
add-phase.md
添加工作流阶段
modify-hook.md
修改钩子行为
change-verify.md
修改验证命令

meta/
- Documentation

meta/
- 文档

DocumentContent
platform-compatibility.md
Detailed platform support matrix
self-iteration-guide.md
How to document customizations
trellis-local-template.md
Template for project-local skill
文档内容
platform-compatibility.md
详细平台支持矩阵
self-iteration-guide.md
如何记录自定义内容
trellis-local-template.md
项目本地技能模板

Quick Reference

快速参考

Key Scripts

关键脚本

ScriptPurpose
get_context.py
Get session context
task.py
Task management
add_session.py
Record session
multi_agent/start.py
Start parallel agent
脚本用途
get_context.py
获取会话上下文
task.py
任务管理
add_session.py
记录会话
multi_agent/start.py
启动并行Agent

Key Paths

关键路径

PathPurpose
.trellis/.developer
Developer identity
.trellis/.current-task
Active task pointer
.trellis/workflow.md
Main workflow docs
.claude/settings.json
Hook configuration
路径用途
.trellis/.developer
开发者身份标识
.trellis/.current-task
活动任务指针
.trellis/workflow.md
主工作流文档
.claude/settings.json
钩子配置

Upgrade Protocol

升级协议

When upgrading Trellis to a new version:
  1. Compare new meta-skill with current
  2. Review changes in new version
  3. Check 
    trellis-local
    for conflicts
  4. Merge carefully, preserving customizations
  5. Update 
    trellis-local
    with migration notes
markdown
undefined
将Trellis升级到新版本时：
  1. 对比新版本元技能与当前版本
  2. 查看新版本中的更改
  3. 检查
    trellis-local
    是否存在冲突
  4. 谨慎合并，保留自定义内容
  5. 更新
    trellis-local
    并添加迁移说明
markdown
undefined

Changelog

更新日志

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

2026-02-01 - 升级到Trellis X.Y.Z

  • Merged new hook behavior from meta-skill
  • Kept custom agent 
    my-agent
  • Updated check.jsonl template
undefined
  • 合并了元技能中的新钩子行为
  • 保留了自定义Agent 
    my-agent
  • 更新了check.jsonl模板
undefined