> ## Documentation Index
> Fetch the complete documentation index at: https://gnero.genetind.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Platform and Team Configuration

## Multi-Platform and Team Configuration

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

**Claude Code exclusive features**:

* 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` |
| ...                    | ...                            |

**Differences from Claude Code**:

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

```bash theme={null}
# 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

```bash theme={null}
trellis init --codex -u your-name
```

Generates the following configuration:

* **`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](https://kilo.ai) is an open-source (Apache 2.0) AI coding Agent platform, available as a VS Code extension, JetBrains plugin, and CLI, with 750K+ users.

```bash theme={null}
trellis init --kilo -u your-name
```

Generates configuration under the `.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              |

**Kilo configuration directory structure**:

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

**Recommended workflow for Kilo users**:

```bash theme={null}
# 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
```

<Info>
  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.
</Info>

### 13.5 Kiro Integration

[Kiro](https://kiro.dev) 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.

```bash theme={null}
trellis init --kiro -u your-name
```

Generates configuration under the `.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                |

**Kiro configuration directory structure**:

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

**Recommended workflow for Kiro users**:

```bash theme={null}
# 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
```

<Info>
  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.
</Info>

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

**Cross-platform notes**:

| 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 simultaneously
* `tasks/` — 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

```yaml theme={null}
# 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

```bash theme={null}
# 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
```

**Template hash mechanism**:

`.trellis/.template-hashes.json` stores the SHA-256 hash of each template file. During `trellis update`:

1. Compute local file hashes
2. Compare with recorded template hashes
3. If they match — file not modified by user — safe to update
4. If they differ — file was modified by user — prompt for conflict resolution
5. User chooses: overwrite / skip / merge

***