Trellis Meta-Skill

Version Compatibility

Item

Value

Trellis CLI Version

0.3.0

Skill Last Updated

2026-02-28

Min Claude Code Version

1.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.

Platform Compatibility

Feature Support Matrix

Feature

Claude Code

iFlow

Cursor

OpenCode

Codex

Kilo

Kiro

Gemini CLI

Antigravity

Core Systems

Workspace system

✅ Full

✅ Full

✅ Full

✅ Full

✅ Full

✅ Full

✅ Full

✅ Full

✅ Full

Task system

✅ Full

✅ Full

✅ Full

✅ Full

✅ Full

✅ Full

✅ Full

✅ Full

✅ Full

Spec system

✅ Full

✅ Full

✅ Full

✅ Full

✅ Full

✅ Full

✅ Full

✅ Full

✅ Full

Commands/Skills

✅ Full

✅ Full

✅ Full

✅ Full

✅ Skills

✅ Full

✅ Skills

✅ TOML

✅ Workflows

Agent definitions

✅ Full

✅ Full

⚠️ Manual

✅ Full

⚠️ Manual

⚠️ Manual

⚠️ Manual

⚠️ Manual

⚠️ Manual

Hook-Dependent Features

SessionStart hook

✅ Full

✅ Full

❌ None

❌ None

❌ None

❌ None

❌ None

❌ None

❌ None

PreToolUse hook

✅ Full

✅ Full

❌ None

❌ None

❌ None

❌ None

❌ None

❌ None

❌ None

SubagentStop hook

✅ Full

✅ Full

❌ None

❌ None

❌ None

❌ None

❌ None

❌ None

❌ None

Auto context injection

✅ Full

✅ Full

❌ Manual

❌ Manual

❌ Manual

❌ Manual

❌ Manual

❌ Manual

❌ Manual

Ralph Loop

✅ Full

✅ Full

❌ None

❌ None

❌ None

❌ None

❌ None

❌ None

❌ None

Multi-Agent/Session

Multi-Agent (current dir)

✅ Full

✅ Full

⚠️ Limited

⚠️ Limited

⚠️ Limited

⚠️ Limited

⚠️ Limited

⚠️ Limited

⚠️ Limited

Multi-Session (worktrees)

✅ Full

✅ Full

❌ None

❌ None

❌ None

❌ None

❌ None

❌ None

❌ None

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)

All features work as documented. Hooks provide automatic context injection and quality enforcement. iFlow shares the same Python hook system as Claude Code.

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

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 (Codex uses Skills, Gemini uses TOML, Antigravity uses Workflows) Designing for Portability When customizing Trellis, consider platform compatibility: ┌─────────────────────────────────────────────────────────────┐ │ PORTABLE (All 9 Platforms) │ │ - .trellis/workspace/ - .trellis/tasks/ │ │ - .trellis/spec/ - Platform commands/skills │ │ - File-based configs - JSONL context files │ └─────────────────────────────────────────────────────────────┘ │ ┌─────────────────────────────▼───────────────────────────────┐ │ HOOK-CAPABLE (Claude Code + iFlow) │ │ - .claude/hooks/ or .iflow/hooks/ │ │ - settings.json hook configuration │ │ - Auto context injection - SubagentStop control │ │ - Ralph Loop - Multi-Session worktrees │ └─────────────────────────────────────────────────────────────┘ 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. 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 Self-Iteration Protocol When modifying Trellis for a project, follow this protocol: 1. Check for Existing Project Skill

Look for project-local skill

ls -la .claude/skills/trellis-local/ 2. Create Project Skill if Missing If no trellis-local exists, create it: mkdir -p .claude/skills/trellis-local Then create .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. Record Every Modification When making ANY change to Trellis, update trellis-local/SKILL.md : Example: Adding a new command

Commands Added

/trellis:my-command

**

File

**

:

.claude/commands/trellis/my-command.md

-

**

Purpose

**

[what it does]

**

Added

**

2026-01-31

**

Why

**

[reason for adding] Example: Modifying a hook

Hooks Changed

inject-subagent-context.py

**

Change

**

Added support for

my-agent

type

-

**

Lines modified

**

45-67

**

Date

**

2026-01-31

**

Why

**

[reason] 4. Never Modify Meta-Skill for Project Changes 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 Architecture Overview Trellis transforms AI assistants into structured development partners through enforced context injection . System Layers ┌─────────────────────────────────────────────────────────────────────┐ │ USER INTERACTION │ │ /trellis:start /trellis:brainstorm /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) │ └─────────────────────────────────────────────────────────────────────┘ Key Design Principles Principle Description Specs Injected, Not Remembered Hooks enforce specs - agents always receive context Read Before Write Understand guidelines before writing code Layered Context Only relevant specs load (via JSONL files) Human Commits AI never commits - human validates first Pure Dispatcher Dispatch agent only orchestrates Core Components 1. Workspace System 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) 2. Task System 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 3. Spec System Maintain coding standards that get injected to agents. .trellis/spec/ ├── frontend/ # Frontend guidelines ├── backend/ # Backend guidelines └── guides/ # Thinking guides 4. Hooks System Automatically inject context and enforce quality. Hook When Purpose SessionStart Session begins Inject workflow, guidelines PreToolUse:Task Before sub-agent Inject specs via JSONL SubagentStop:check Check agent stops Enforce verification (Ralph Loop) 5. Agent System Specialized agents for different phases. Agent Purpose Restriction dispatch Orchestrate pipeline Pure dispatcher plan Evaluate requirements Can reject unclear reqs research Find code patterns Read-only implement Write code No git commit check Review and self-fix Ralph Loop controlled debug Fix issues Precise fixes only 6. Multi-Agent Pipeline Run parallel isolated sessions via Git worktrees. plan.py → start.py → Dispatch → implement → check → create-pr Customization Guide Adding a Command Create .claude/commands/trellis/my-command.md Update trellis-local skill with the change Adding an Agent Create .claude/agents/my-agent.md with YAML frontmatter Update inject-subagent-context.py to handle new agent type Create my-agent.jsonl in task directories Update trellis-local skill Modifying Hooks Edit the hook script in .claude/hooks/ Document the change in trellis-local skill Note which lines were modified and why Extending Specs Create new category in .trellis/spec/my-category/ Add index.md and guideline files Reference in JSONL context files Update trellis-local skill Changing Task Workflow Modify next_action array in task.json Update dispatch or hook scripts as needed Document in trellis-local skill 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 core/ - All Platforms Document Content 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 claude-code/ - Claude Code Only Document Content 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 how-to-modify/ - Modification Guides Document Scenario 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 meta/ - Documentation Document Content platform-compatibility.md Detailed platform support matrix self-iteration-guide.md How to document customizations trellis-local-template.md Template for project-local skill Quick Reference Key Scripts Script Purpose get_context.py Get session context task.py Task management add_session.py Record session multi_agent/start.py Start parallel agent Key Paths Path Purpose .trellis/.developer Developer identity .trellis/.current-task Active task pointer .trellis/workflow.md Main workflow docs .claude/settings.json Hook configuration Upgrade Protocol When upgrading Trellis to a new version: Compare new meta-skill with current Review changes in new version Check trellis-local for conflicts Merge carefully, preserving customizations Update trellis-local with migration notes

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