trellis-meta

What this skill does

# 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

```bash
# Look for project-local skill
ls -la .claude/skills/trellis-local/
```

### 2. Create Project Skill if Missing

If no `trellis-local` exists, create it:

```bash
mkdir -p .claude/skills/trellis-local
```

Then create `.claude/skills/trellis-local/SKILL.md`:

```markdown
---
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 ve