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.4.0-beta.8
Skill Last Updated2026-03-24
Min Claude Code Version1.0.0+
Min Node.js Version>=18.17.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.4.0-beta.8
技能最后更新时间2026-03-24
最低 Claude Code 版本1.0.0+
最低 Node.js 版本>=18.17.0
⚠️ 版本不匹配警告: 如果你的Trellis CLI版本与上述版本不同，部分功能可能无法按文档正常工作。运行 
trellis --version
进行检查。

Platform Compatibility

平台兼容性

Feature Support Matrix

功能支持矩阵

FeatureClaude CodeiFlowCursorOpenCodeCodexKiloKiroGemini CLIAntigravityQoderCodeBuddy
Core Systems
Workspace system✅ Full✅ Full✅ Full✅ Full✅ Full✅ Full✅ Full✅ Full✅ Full✅ Full✅ Full
Task system✅ Full✅ Full✅ Full✅ Full✅ Full✅ Full✅ Full✅ Full✅ Full✅ Full✅ Full
Spec system✅ Full✅ Full✅ Full✅ Full✅ Full✅ Full✅ Full✅ Full✅ Full✅ Full✅ Full
Commands/Skills✅ Full✅ Full✅ Full✅ Full✅ Skills✅ Full✅ Skills✅ TOML✅ Workflows✅ Skills✅ Full
Agent definitions✅ Full✅ Full⚠️ Manual✅ Full✅ TOML⚠️ Manual⚠️ Manual⚠️ Manual⚠️ Manual⚠️ Manual⚠️ Manual
Shared agent skills————✅ Full——————
Hook-Dependent Features
SessionStart hook✅ Full✅ Full❌ None❌ None⚠️ Optional❌ None❌ None❌ None❌ None❌ None❌ None
PreToolUse hook✅ Full✅ Full❌ None❌ None❌ None❌ None❌ None❌ None❌ None❌ None❌ None
SubagentStop hook✅ Full✅ Full❌ None❌ None❌ None❌ None❌ None❌ None❌ None❌ None❌ None
Auto context injection✅ Full✅ Full❌ Manual❌ Manual❌ Manual❌ Manual❌ Manual❌ Manual❌ Manual❌ Manual❌ Manual
Ralph Loop✅ Full✅ Full❌ None❌ None❌ None❌ None❌ None❌ None❌ None❌ None❌ None
Multi-Agent/Session
Multi-Agent (current dir)✅ Full✅ Full⚠️ Limited⚠️ Limited⚠️ Limited⚠️ Limited⚠️ Limited⚠️ Limited⚠️ Limited⚠️ Limited⚠️ Limited
Multi-Session (worktrees)✅ Full✅ Full❌ None❌ None❌ None❌ None❌ None❌ None❌ None❌ None❌ None
功能Claude CodeiFlowCursorOpenCodeCodexKiloKiroGemini CLIAntigravityQoderCodeBuddy
核心系统
工作区系统✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持
任务系统✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持
规范系统✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持
命令/技能✅ 完全支持✅ 完全支持✅ 完全支持✅ 完全支持✅ 技能支持✅ 完全支持✅ 技能支持✅ TOML配置支持✅ 工作流支持✅ 技能支持✅ 完全支持
Agent 定义✅ 完全支持✅ 完全支持⚠️ 需手动配置✅ 完全支持✅ TOML配置支持⚠️ 需手动配置⚠️ 需手动配置⚠️ 需手动配置⚠️ 需手动配置⚠️ 需手动配置⚠️ 需手动配置
共享Agent技能————✅ 完全支持——————
依赖钩子的功能
SessionStart 钩子✅ 完全支持✅ 完全支持❌ 不支持❌ 不支持⚠️ 可选支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持
PreToolUse 钩子✅ 完全支持✅ 完全支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持
SubagentStop 钩子✅ 完全支持✅ 完全支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持
自动上下文注入✅ 完全支持✅ 完全支持❌ 需手动配置❌ 需手动配置❌ 需手动配置❌ 需手动配置❌ 需手动配置❌ 需手动配置❌ 需手动配置❌ 需手动配置❌ 需手动配置
Ralph Loop✅ 完全支持✅ 完全支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持
多Agent/多会话
多Agent（当前目录）✅ 完全支持✅ 完全支持⚠️ 有限支持⚠️ 有限支持⚠️ 有限支持⚠️ 有限支持⚠️ 有限支持⚠️ 有限支持⚠️ 有限支持⚠️ 有限支持⚠️ 有限支持
多会话（工作树）✅ 完全支持✅ 完全支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持

Legend

图例

  • ✅ Full: Feature works as documented
  • ⚠️ Limited/Manual: Works but requires manual steps
  • ❌ None/Manual: Not supported or requires manual workaround
  • ✅ 完全支持: 功能按文档正常工作
  • ⚠️ 有限/手动支持: 可工作但需手动操作
  • ❌ 无/手动支持: 不支持或需手动变通

Platform Categories

平台分类

Full Hook Support (Claude Code, iFlow)

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

All features work as documented. Hooks provide automatic context injection and quality enforcement. iFlow shares the same Python hook system as Claude Code.
所有功能按文档正常工作。钩子提供自动上下文注入和质量管控。iFlow与Claude Code使用相同的Python钩子系统。

Partial Hook Support (Codex)

部分支持钩子（Codex）

  • Works: Workspace, tasks, specs, skills (
    .codex/skills/
    + 
    .agents/skills/
    shared layer), TOML agent definitions (
    .codex/agents/
    ), optional SessionStart hook
  • Doesn't work: PreToolUse, SubagentStop, Ralph Loop, Multi-Session
  • Note: SessionStart hook requires 
    codex_hooks = true
    in 
    ~/.codex/config.toml
  • 支持: 工作区、任务、规范、技能（
    .codex/skills/
    + 
    .agents/skills/
    共享层）、TOML Agent定义（
    .codex/agents/
    ）、可选SessionStart钩子
  • 不支持: PreToolUse、SubagentStop、Ralph Loop、多会话
  • 注意: SessionStart钩子需要在
    ~/.codex/config.toml
    中设置
    codex_hooks = true

Commands Only (Cursor, OpenCode, Kilo, Kiro, Gemini CLI, Antigravity, Qoder, CodeBuddy)

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

  • Works: Workspace, tasks, specs, commands/skills (platform-specific format)
  • Doesn't work: Hooks, auto-injection, Ralph Loop, Multi-Session
  • Workaround: Manually read spec files at session start; no automatic quality gates
  • Note: Each platform uses its own command format (Kiro/Qoder use Skills, Gemini uses TOML, Antigravity uses Workflows, CodeBuddy uses nested Markdown commands)
  • 支持: 工作区、任务、规范、命令/技能（平台特定格式）
  • 不支持: 钩子、自动注入、Ralph Loop、多会话
  • 变通方案: 在会话开始时手动读取规范文件；无自动质量管控
  • 注意: 每个平台使用自己的命令格式（Kiro/Qoder使用Skills，Gemini使用TOML，Antigravity使用Workflows，CodeBuddy使用嵌套Markdown命令）

Designing for Portability

可移植性设计

When customizing Trellis, consider platform compatibility:
┌─────────────────────────────────────────────────────────────┐
│                 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时，请考虑平台兼容性：
┌─────────────────────────────────────────────────────────────┐
│                 可移植（全11个平台）                  │
│  - .trellis/workspace/    - .trellis/tasks/                 │
│  - .trellis/spec/         - 平台命令/技能        │
│  - 基于文件的配置     - JSONL上下文文件             │
│  - config.yaml            - 单体仓库包支持       │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│         共享Agent技能（agentskills.io标准）       │
│  - .agents/skills/          (Codex + 通用Agent CLI)  │
└─────────────────────────────┬───────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│              支持钩子（Claude Code + iFlow）              │
│  - .claude/hooks/ 或 .iflow/hooks/                          │
│  - settings.json钩子配置                         │
│  - 自动上下文注入   - SubagentStop控制          │
│  - Ralph Loop               - 多会话工作树       │
│  - 任务生命周期钩子     - 动态规范发现        │
└─────────────────────────────────────────────────────────────┘

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: |
  [项目名称]的项目特定Trellis定制。
  本技能记录了在该项目中对原生Trellis系统所做的修改。继承trellis-meta作为基础文档。
---

Trellis Local - [PROJECT_NAME]

Trellis Local - [项目名称]

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: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)   │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│                        用户交互                              │
│  /trellis:start  /trellis:brainstorm  /trellis:parallel             │
│  /trellis:finish-work  /trellis:before-dev  /trellis:check          │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                         技能层                                 │
│  .claude/commands/trellis/*.md   (17条斜杠命令)                │
│  .claude/agents/*.md             (6个子Agent定义)          │
│  .agents/skills/*/SKILL.md       (共享Agent技能层)        │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                          钩子层                                 │
│  SessionStart      → session-start.py (工作流 + 上下文 + 状态) │
│  PreToolUse:Agent  → inject-subagent-context.py (规范注入)    │
│  SubagentStop      → ralph-loop.py (质量管控)            │
│  Task Lifecycle    → config.yaml钩子 (after_create/start/finish/  │
│                      archive → 例如Linear同步)                    │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                       持久化层                              │
│  .trellis/workspace/  (日志、会话历史)                   │
│  .trellis/tasks/      (任务跟踪、上下文文件、子任务)      │
│  .trellis/spec/       (编码规范、单体仓库包级规范)     │
│  .trellis/config.yaml (包、钩子、update.skip、spec_scope)   │
└─────────────────────────────────────────────────────────────────────┘

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, parent-child subtasks, and lifecycle hooks.
.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)
通过阶段式执行、父子子任务和生命周期钩子跟踪工作项。
.trellis/tasks/{MM-DD-slug}/
├── task.json           # 元数据、阶段、分支、子任务
├── prd.md              # 需求文档
├── info.md             # 技术设计（可选）
├── implement.jsonl     # 实现Agent的上下文
├── check.jsonl         # 检查Agent的上下文
├── debug.jsonl         # 调试Agent的上下文
├── research.jsonl      # 调研Agent的上下文（可选）
└── cr.jsonl            # 代码审查的上下文（可选）

3. Spec System

3. 规范系统

Maintain coding standards that get injected to agents. Supports both single-repo and monorepo layouts.
undefined
维护可注入Agent的编码规范，支持单仓库和单体仓库布局。
undefined

Single repo

单仓库

.trellis/spec/ ├── frontend/ # Frontend guidelines ├── backend/ # Backend guidelines └── guides/ # Thinking guides
.trellis/spec/ ├── frontend/ # 前端规范 ├── backend/ # 后端规范 └── guides/ # 思维指南

Monorepo (per-package)

单体仓库（按包划分）

.trellis/spec/ ├── <package-name>/ # Per-package specs │ ├── backend/ │ ├── frontend/ │ └── unit-test/ └── guides/ # Shared thinking guides
undefined
.trellis/spec/ ├── <package-name>/ # 包级规范 │ ├── backend/ │ ├── frontend/ │ └── unit-test/ └── guides/ # 共享思维指南
undefined

4. Hooks System

4. 钩子系统

Automatically inject context and enforce quality.
Claude Code / iFlow Hooks (settings.json):
HookWhenPurpose
SessionStart
startup, clear, compact eventsInject workflow, guidelines, task status
PreToolUse:Agent
Before sub-agent launchInject specs via JSONL
PreToolUse:Task
Before Task tool (legacy)Same as Agent (CC renamed Task→Agent)
SubagentStop:check
Check agent stopsEnforce verification (Ralph Loop)
Task Lifecycle Hooks (config.yaml):
EventWhenPurpose
after_create
Task createde.g. create Linear issue
after_start
Task startede.g. update Linear status
after_finish
Task finishede.g. mark Linear complete
after_archive
Task archivede.g. close Linear issue
自动注入上下文并管控质量。
Claude Code / iFlow 钩子 (settings.json):
钩子触发时机用途
SessionStart
启动、清除、压缩事件时注入工作流、规范、任务状态
PreToolUse:Agent
子Agent启动前通过JSONL注入规范
PreToolUse:Task
任务工具启动前（旧版）与Agent钩子功能相同（CC已将Task重命名为Agent）
SubagentStop:check
检查Agent停止时强制验证（Ralph Loop）
任务生命周期钩子 (config.yaml):
事件触发时机用途
after_create
任务创建时例如创建Linear工单
after_start
任务启动时例如更新Linear状态
after_finish
任务完成时例如标记Linear完成
after_archive
任务归档时例如关闭Linear工单

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, subtasks, lifecycle hooks, JSONL
specs.md
Spec system, monorepo layout, guidelines
scripts.md
Platform-independent scripts
config.md
config.yaml full reference
文档内容
overview.md
核心系统介绍
files.md
所有
.trellis/
文件及其用途
workspace.md
工作区系统、日志、开发者身份
tasks.md
任务系统、子任务、生命周期钩子、JSONL
specs.md
规范系统、单体仓库布局、指南
scripts.md
平台无关脚本
config.md
config.yaml完整参考

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类型、调用、任务工具
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 (text/JSON)
task.py
Task management (16 subcommands)
add_session.py
Record session
create_bootstrap.py
First-time spec bootstrap
multi_agent/start.py
Start parallel agent
multi_agent/status.py
Monitor agent status
multi_agent/create_pr.py
Create PR from worktree
脚本用途
get_context.py
获取会话上下文（文本/JSON）
task.py
任务管理（16个子命令）
add_session.py
记录会话
create_bootstrap.py
首次规范初始化
multi_agent/start.py
启动并行Agent
multi_agent/status.py
监控Agent状态
multi_agent/create_pr.py
从工作树创建PR

Key Paths

关键路径

PathPurpose
.trellis/.developer
Developer identity
.trellis/.current-task
Active task pointer
.trellis/workflow.md
Main workflow docs
.trellis/config.yaml
Project config (packages, hooks)
.trellis/worktree.yaml
Multi-session config
.claude/settings.json
Hook configuration
.agents/skills/
Shared agent skills (agentskills.io)
路径用途
.trellis/.developer
开发者身份
.trellis/.current-task
活跃任务指针
.trellis/workflow.md
主工作流文档
.trellis/config.yaml
项目配置（包、钩子）
.trellis/worktree.yaml
多会话配置
.claude/settings.json
钩子配置
.agents/skills/
共享Agent技能（agentskills.io）

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