trellis-meta

Trellis Meta-Skill

Version Compatibility

Item	Value
Trellis CLI Version	0.3.0-beta.5
Skill Last Updated	2026-01-31
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	Cursor	OpenCode (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

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)

All features work as documented. Hooks provide automatic context injection and quality enforcement.

Cursor (Partial Support)

• 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

OpenCode (Future Consideration)

• Need to evaluate OpenCode's extension/hook capabilities
• May require adapter layer for hook compatibility
• Core file-based systems should work once integrated

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         │
└─────────────────────────────────────────────────────────────┘

---

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: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 Gi

---

Content truncated.