Trellis Meta-Skill
Version Compatibility
| Item |
Value |
| Trellis CLI Version |
0.4.0-beta.8 |
| Skill Last Updated |
2026-03-24 |
| Min Claude Code Version |
1.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.
Platform Compatibility
Feature Support Matrix
| Feature |
Claude Code |
iFlow |
Cursor |
OpenCode |
Codex |
Kilo |
Kiro |
Gemini CLI |
Antigravity |
Qoder |
CodeBuddy |
| 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 |
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.
Partial Hook Support (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
Commands Only (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)
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 β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
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
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 /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) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
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, 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)
3. Spec System
Maintain coding standards that get injected to agents. Supports both single-repo and monorepo layouts.
# Single repo
.trellis/spec/
βββ frontend/ # Frontend guidelines
βββ backend/ # Backend guidelines
βββ guides/ # Thinking guides
# Monorepo (per-package)
.trellis/spec/