13.1 Claude Code Full Experience
Claude Code is Trellis’s primary platform, with the most complete automation capabilities. Three core Hooks form the automation loop:
| Hook | Trigger Timing | Capability |
|---|
session-start.py | SessionStart | Auto-injects context (identity, history, tasks) |
inject-subagent-context.py | PreToolUse (Task) | Auto-injects precise Spec context for Agents |
ralph-loop.py | SubagentStop (check) | Auto-verifies code quality (Ralph Loop) |
- Hook auto-injection — start working immediately upon opening terminal, no manual
/start needed
- Multi-Agent Pipeline —
/parallel orchestrates multiple worktree Agents in parallel
- Ralph Loop — automatic quality gate, Check Agent auto-retries on failure
- Agent system — 6 specialized Agents (dispatch, plan, implement, check, debug, research)
13.2 Cursor Integration
trellis init automatically generates Trellis command files under .cursor/commands/:
| Claude Code Command | Cursor Equivalent |
|---|
/start | /start |
/check-backend | /trellis-check-backend |
/check-frontend | /trellis-check-frontend |
/finish-work | /trellis-finish-work |
/before-backend-dev | /trellis-before-backend-dev |
/before-frontend-dev | /trellis-before-frontend-dev |
| … | … |
- Files located at
.cursor/commands/trellis-{name}.md
- Cursor has 12 commands (no
/parallel, as Cursor doesn’t support Multi-Agent Pipeline)
- No Hook support — spec injection requires manual command invocation
- No Agent system — all work happens in the main conversation
- No Ralph Loop — check commands must be run manually
Recommended workflow for Cursor users:
# 1. Start session (required, replaces Hook auto-injection)
/start
# 2. Load relevant specs (recommended, replaces PreToolUse Hook)
/trellis-before-backend-dev # For backend tasks
/trellis-before-frontend-dev # For frontend tasks
# 3. Describe task, AI develops...
# 4. Manually check code quality (replaces Ralph Loop)
/trellis-check-backend # Backend check
/trellis-check-frontend # Frontend check
/trellis-check-cross-layer # Cross-layer check
# 5. Finish checklist
/trellis-finish-work
13.3 Codex Integration
trellis init --codex -u your-name
AGENTS.md (root directory) — Codex entry file, provides base project context (similar to CLAUDE.md).agents/skills/ — Agent Skills directory for reusable AI capability modules
13.4 Kilo Code Integration
Kilo Code is an open-source (Apache 2.0) AI coding Agent platform, available as a VS Code extension, JetBrains plugin, and CLI, with 750K+ users.
trellis init --kilo -u your-name
.kilocode/ directory:
Trellis to Kilo mapping:
| Trellis / Claude Code | Kilo Code | Description |
|---|
CLAUDE.md | AGENTS.md + .kilocode/rules/*.md | Kilo supports both the AGENTS.md open standard and its own rules directory |
.claude/commands/*.md | .kilocode/workflows/*.md | Invoked in chat as /start.md, etc. |
.claude/agents/*.md | .kilocode/skills/*/SKILL.md | Skills with YAML frontmatter, shareable across tools |
.claude/hooks/ | .kilocode/launchConfig.json (limited) | Kilo lacks a full Hook system; Auto-Launch is the closest equivalent |
| Sub-Agents (Task tool) | Orchestrator Mode + new_task() | Built-in multi-mode delegation, supports worktree parallelism |
project/
├── AGENTS.md # Open standard (cross-tool compatible)
├── .kilocode/
│ ├── rules/ # Universal rules (all modes)
│ │ └── trellis-workflow.md # Trellis workflow guide
│ ├── rules-code/ # Code mode specific rules
│ ├── rules-architect/ # Architect mode specific rules
│ ├── workflows/ # Commands (equivalent to slash commands)
│ │ ├── start.md # /start equivalent
│ │ ├── check-backend.md # /check-backend equivalent
│ │ └── finish-work.md # /finish-work equivalent
│ ├── skills/ # Agent Skills
│ │ └── trellis-dispatch/
│ │ └── SKILL.md
│ ├── mcp.json # MCP server config
│ └── launchConfig.json # Auto-launch config
# 1. Kilo auto-loads Trellis specs via .kilocode/rules/
# Or run the workflow for full context
/start.md
# 2. Switch to Orchestrator mode for complex tasks
# Kilo auto-decomposes tasks and assigns to Code/Architect modes
# 3. Describe task, AI develops...
# 4. Run check workflow
/check-backend.md
# 5. Finish
/finish-work.md
Kilo’s Orchestrator Mode shares a similar philosophy with Trellis’s Multi-Agent Pipeline, but the implementation differs:
Trellis uses git worktree physical isolation + Hook orchestration, while Kilo uses built-in mode switching + independent conversation context.
The two are complementary — Trellis’s Spec management and Task system provide structured project context for Kilo.
13.5 Kiro Integration
Kiro is an AI IDE by Amazon, built on Code OSS (VS Code open-source core), focused on Spec-Driven Development. It supports IDE, CLI, and Autonomous Agent modes.
trellis init --kiro -u your-name
.kiro/ directory:
Trellis to Kiro mapping:
| Trellis / Claude Code | Kiro | Description |
|---|
CLAUDE.md | .kiro/steering/*.md | Kiro uses multiple Markdown files as its Steering system |
.trellis/spec/ | .kiro/steering/ | Trellis specs can be mapped to Kiro steering files |
.claude/commands/*.md | .kiro/prompts/ | Invoked in chat as @start, etc. |
.claude/hooks/ | .kiro/hooks/*.kiro.hook | Kiro has a native Hook system (JSON config) |
.claude/agents/*.md | .kiro/agents/ | Kiro CLI supports custom Agent configuration |
.trellis/tasks/*/prd.md | .kiro/specs/*/requirements.md + design.md + tasks.md | Kiro splits the PRD into a three-file set |
project/
├── .kiro/
│ ├── steering/ # Project context (equivalent to CLAUDE.md)
│ │ ├── product.md # Product overview (can be auto-generated)
│ │ ├── tech.md # Tech stack (can be auto-generated)
│ │ ├── structure.md # Directory structure (can be auto-generated)
│ │ └── trellis-workflow.md # Trellis workflow guide
│ ├── hooks/ # Agent Hooks (event-driven automation)
│ │ └── check-on-save.kiro.hook # Auto-check on save
│ ├── specs/ # Spec-Driven Development
│ │ └── feature-name/
│ │ ├── requirements.md # Requirements (EARS format)
│ │ ├── design.md # Technical design
│ │ └── tasks.md # Implementation checklist
│ ├── prompts/ # Custom prompts (commands)
│ ├── agents/ # Custom Agent configuration (CLI)
│ └── settings/
│ └── mcp.json # MCP server config
# 1. Kiro auto-loads Trellis specs via .kiro/steering/
# No manual /start needed
# 2. Choose Spec mode (recommended) or Vibe mode
# Spec mode: auto-generates requirements → design → tasks
# Vibe mode: traditional freeform coding
# 3. Describe task, AI implements step by step following tasks.md...
# 4. Agent Hooks auto-trigger checks on file save
# Can also manually run prompt checks
# 5. Commit code when done
Kiro’s Spec-Driven Development is highly complementary to Trellis’s task management system:
Trellis’s prd.md can serve as input for Kiro Specs, while Kiro’s generated requirements.md / design.md / tasks.md
can feed back into Trellis’s spec/ directory. Together they enable a complete loop from requirements to delivery.
13.6 Operating System Compatibility
| OS | Support Status | Notes |
|---|
| macOS | ✅ Full support | Primary development platform, all features verified |
| Linux | ✅ Full support | All features verified |
| Windows | ✅ Full support | All scripts migrated to Python, natively supports Windows |
| Consideration | Details |
|---|
| Python scripts | Scripts under .trellis/scripts/ are Python, requiring Python 3.8+, cross-platform compatible |
| Python Hooks | Hook scripts under .claude/hooks/ require Python 3.8+, cross-platform compatible |
| Path separators | Trellis internally uses /, Python handles path conversion automatically |
| Git worktree | Multi-Agent Pipeline relies on git worktree, supported on all platforms |
13.7 Multi-Developer Collaboration
Non-conflicting parts (per-developer isolation):
workspace/{name}/ — each developer has their own directory.developer — gitignored, per-developer- Parallel task worktrees — physically isolated
Potentially conflicting parts (require coordination):
spec/ — multiple people may modify the same spec simultaneouslytasks/ — multiple people may operate on the same task
Best practices:
- Spec changes go through PR review
- Task assignments are explicit (
--assignee parameter)
- Important spec changes are discussed in team meetings
13.8 Complete worktree.yaml Configuration
# Worktree Configuration for Multi-Agent Pipeline
#───────────────────────────────────────────────────
# Paths
#───────────────────────────────────────────────────
# Worktree storage directory (relative to project root)
worktree_dir: ../trellis-worktrees
#───────────────────────────────────────────────────
# Files to Copy
#───────────────────────────────────────────────────
# Files that need independent copies in each worktree
# These files contain sensitive info or need independent config
copy:
- .env # Environment variables
- .env.local # Local environment variables
- .trellis/.developer # Developer identity
#───────────────────────────────────────────────────
# Post-Create Hooks
#───────────────────────────────────────────────────
# Commands to run after creating a worktree
# Executed sequentially in the worktree directory; aborts on failure
post_create:
- pnpm install --frozen-lockfile
# - npm install
# - yarn install --frozen-lockfile
#───────────────────────────────────────────────────
# Check Agent Verification (Ralph Loop)
#───────────────────────────────────────────────────
# Commands to verify code quality
# When configured, Ralph Loop runs these — all must pass
# Without configuration, falls back to completion markers mode
verify:
- pnpm lint
- pnpm typecheck
# - pnpm test
13.9 trellis update and Version Management
# Check current version
cat .trellis/.version
# Update to latest version
trellis update
# Preview updates (dry run)
trellis update --dry-run
# Force overwrite all files
trellis update -f
# Skip all changed files
trellis update -s
.trellis/.template-hashes.json stores the SHA-256 hash of each template file. During trellis update:
- Compute local file hashes
- Compare with recorded template hashes
- If they match — file not modified by user — safe to update
- If they differ — file was modified by user — prompt for conflict resolution
- User chooses: overwrite / skip / merge
