Trellis Meta-Skill

Version Compatibility

⚠️ 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

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)

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

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

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

• 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

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

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.

SessionStart

PreToolUse:Task

SubagentStop:check

5. Agent System

Specialized agents for different phases.

dispatch

plan

research

implement

check

debug

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

1. Create

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

2. Update

   trellis-local

   skill with the change

Adding an 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

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

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

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

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

overview.md

files.md

.trellis/

workspace.md

tasks.md

specs.md

scripts.md

claude-code/

- Claude Code Only

overview.md

hooks.md

agents.md

ralph-loop.md

multi-session.md

worktree-config.md

scripts.md

how-to-modify/

- Modification Guides

overview.md

add-command.md

add-agent.md

add-spec.md

add-phase.md

modify-hook.md

change-verify.md

meta/

- Documentation

platform-compatibility.md

self-iteration-guide.md

trellis-local-template.md

Quick Reference

Key Scripts

get_context.py

task.py

add_session.py

multi_agent/start.py

Key Paths

.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

## 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