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

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

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.

5. Agent System

Specialized agents for different phases.

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

claude-code/ – Claude Code Only

how-to-modify/ – Modification Guides

meta/ – Documentation

Quick Reference

Key Scripts

Key Paths

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