Install & First Task

Quick Start

Installation

# Global install
npm install -g @mindfoldhq/trellis@latest

# Navigate to your project directory
cd your-project

OS Requirements: Mac, Linux, and Windows are fully supported. All scripts have been migrated to Python for cross-platform compatibility.

Choose the init command based on your platform:

trellis init -u your-name — auto-detects Claude Code and configures .claude/ (commands, agents, hooks).

trellis init -u your-name — auto-detects Cursor and configures .cursor/commands/.

trellis init --opencode -u your-name — writes .opencode/commands/trellis/, .opencode/agents/, .opencode/plugins/ (session-start hook).

trellis init --codex -u your-name — writes AGENTS.md, .agents/skills/, .codex/agents/, .codex/hooks/. Enable codex_hooks = true in ~/.codex/config.toml for full hook support.

trellis init --iflow -u your-name — writes .iflow/commands/trellis/ + .iflow/hooks/session-start.py (same Python hook family as Claude Code).

trellis init --gemini -u your-name — writes TOML command files under .gemini/commands/trellis/ + shared .agents/skills/.

trellis init --kilo -u your-name — writes workflow files under .kilocode/workflows/ (invoked as /start.md, etc.).

trellis init --kiro -u your-name — writes skill-based commands under .kiro/skills/.

trellis init --qoder -u your-name — writes .qoder/skills/{name}/SKILL.md (all 12 Trellis commands as auto-trigger skills; no .qoder/commands/ so Qoder’s Custom Commands space stays free for your own use).

trellis init --copilot -u your-name — writes .github/copilot-instructions.md + .github/prompts/trellis-{name}.prompt.md.

trellis init --windsurf -u your-name — writes .windsurf/workflows/trellis-{name}.md + .windsurf/rules/trellis.md.

trellis init --codebuddy -u your-name — writes 12 slash commands under .codebuddy/commands/trellis/.

trellis init --antigravity -u your-name — writes Trellis workflows under .agent/workflows/ (invoked via Antigravity’s workflow picker).

trellis init --droid -u your-name — writes .factory/commands/trellis/ + .factory/agents/ + .factory/hooks/session-start.py.

You can pass multiple platform flags in one command: trellis init --codex --gemini --copilot -u your-name. your-name becomes your developer identity and creates your personal workspace at .trellis/workspace/your-name/.

Platform Configuration

trellis init automatically detects and configures installed platforms:

Platform	Config Directory	Command Format
Claude Code	`.claude/commands/trellis/`, `.claude/agents/`, `.claude/hooks/`	`/trellis:start`
Cursor	`.cursor/commands/*.md`	`/trellis-start`
OpenCode	`.opencode/commands/trellis/`, `.opencode/agents/`, `.opencode/plugins/`	`/trellis:start`
Codex	`AGENTS.md`, `.agents/skills/`, `.codex/agents/`, `.codex/hooks/`	`$start`
iFlow	`.iflow/commands/trellis/`, `.iflow/hooks/`	`/trellis:start`
Gemini CLI	`.gemini/commands/trellis/*.toml`	`/trellis:start`
Kilo	`.kilocode/workflows/`	`/start.md`
Kiro	`.kiro/skills/*/SKILL.md`	`@start`
Qoder	`.qoder/skills/`	skill auto-match
GitHub Copilot	`.github/copilot-instructions.md`, `.github/prompts/`	Run Prompt
Windsurf	`.windsurf/workflows/`, `.windsurf/rules/`	workflow picker
CodeBuddy	`.codebuddy/commands/trellis/*.md`	`/trellis:start`
Antigravity	`.agent/workflows/*.md`	workflow picker
Factory Droid	`.factory/commands/trellis/`, `.factory/agents/`, `.factory/hooks/`	`/trellis:start`

Platform Capability Comparison (0.4.0 GA — 14 platforms)

Capability	CC	Cursor	OpenCode	Codex	iFlow	Gemini	Kilo	Kiro	Qoder	Copilot	Windsurf	CodeBuddy	Antigravity	Droid
Session auto-injection	✅	❌	✅	⚡	✅	❌	⚡	⚡	⚡	⚡	⚡	❌	❌	✅
Sub-Agent spec injection	✅	❌	✅	⚡	✅	❌	❌	⚡	❌	❌	❌	❌	❌	✅
Ralph Loop quality gate	✅	❌	⚡	❌	✅	❌	❌	⚡	❌	❌	❌	❌	❌	⚡
Multi-Agent Pipeline	✅	❌	✅	❌	❌	❌	✅	✅	❌	❌	❌	❌	❌	❌

CC = Claude Code. Legend: ✅ full / ⚡ partial / ❌ not supported. “Partial” means the capability exists via a manual invocation or an opt-in platform flag rather than built-in automation.

Three Steps to Get Started

# Step 1: Open the Claude Code terminal
# Hook auto-injects context — you can describe your task directly (or run /start to see the full flow)

# Step 2: Describe what you want to do

"Add user login feature"

# Step 3: AI works automatically

# AI reads specs → creates task → invokes Agent to implement → self-checks

# Once done, you test, commit, and record the session

# Step 1: Open Cursor, you must first run
/start

# Step 2: Describe what you want to do
"Add user login feature"

# Step 3: AI works automatically
# AI reads specs → creates task → implements → you manually run /trellis-check to check
# Once done, you test, commit, and record the session

# Step 1: Codex provides base context via AGENTS.md
# Run $start for full context

# Step 2: Describe what you want to do

"Add user login feature"

# Step 3: AI works automatically

# Once done, you test, commit, and record the session

# Step 1: Open the OpenCode terminal
# Hook auto-injects context — you can describe your task directly (or run /start to see the full flow)

# Step 2: Describe what you want to do
"Add user login feature"

# Step 3: AI works automatically
# Once done, you test, commit, and record the session

# Step 1: Kilo auto-loads project specs via .kilocode/rules/
# Run the /start.md workflow for full context

# Step 2: Describe what you want to do

"Add user login feature"

# Step 3: AI works automatically

# Kilo Orchestrator Mode breaks down tasks and assigns them to Code/Architect modes

# Once done, you test, commit, and record the session

# Step 1: Kiro auto-loads project specs via .kiro/steering/
# Choose Spec mode to generate requirements → design → tasks

# Step 2: Describe what you want to do
"Add user login feature"

# Step 3: AI works automatically
# Kiro implements step by step following the tasks.md checklist
# Agent Hooks can auto-trigger checks on file save
# Once done, you test, commit, and record the session

Tabs above show the most-used platforms. The other 8 platforms (Gemini CLI, iFlow, Qoder, GitHub Copilot, Windsurf, CodeBuddy, Antigravity, Factory Droid) follow the same Claude-Code-style workflow once installed — see chapter 13 for per-platform details.

Remote Spec Templates

Instead of writing specs from scratch, you can pull pre-built spec templates during init.

Official Marketplace

# Interactive: browse and pick from available templates
trellis init -u your-name

# Non-interactive: specify a template by ID
trellis init -u your-name --template electron-fullstack

The interactive picker shows all templates from the official marketplace. Choose one or start with blank specs.

Custom Registry (`--registry`)

Pull specs from your own GitHub, GitLab, or Bitbucket repository:

# Direct download: repo directory becomes .trellis/spec/
trellis init --registry gh:myorg/myrepo/my-team-spec

# Marketplace mode: repo has index.json with multiple templates
trellis init --registry gh:myorg/myrepo/marketplace

# Pick a specific template from a custom marketplace
trellis init --registry gh:myorg/myrepo/marketplace --template my-template

# Specify a branch
trellis init --registry gh:myorg/myrepo/specs#develop

# GitLab or Bitbucket
trellis init --registry gitlab:myorg/myrepo/specs
trellis init --registry bitbucket:myorg/myrepo/specs

Source format: provider:user/repo[/subdir][#ref]

Provider	Prefix
GitHub	`gh:` or `github:`
GitLab	`gitlab:`
Bitbucket	`bitbucket:`

The ref (branch/tag) defaults to main if omitted.

Handling Existing Specs

When .trellis/spec/ already exists, use a strategy flag:

Flag	Behavior
`--overwrite`	Delete existing spec directory, then download
`--append`	Only copy files that don’t already exist
(neither)	Interactive prompt asks what to do

Building a Custom Marketplace

Create an index.json in your repository:

{
  "version": 1,
  "templates": [
    {
      "id": "my-backend-spec",
      "type": "spec",
      "name": "My Backend Spec",
      "description": "Backend conventions for our team",
      "path": "marketplace/specs/my-backend-spec",
      "tags": ["backend", "node"]
    }
  ]
}

The path field is relative to the repository root. Only type: "spec" is supported currently.

Private Repositories

For private repos, set the GIGET_AUTH environment variable with a personal access token:

GIGET_AUTH=ghp_xxxxx trellis init --registry gh:myorg/private-repo/specs

For GitHub fine-grained tokens, you need Contents and Metadata read permissions.

Full Directory Structure

your-project/
├── .trellis/                          # Trellis core directory
│   ├── .developer                     # Developer identity (gitignored)
│   ├── .current-task                  # Active task pointer
│   ├── .version                       # Trellis version number
│   ├── .template-hashes.json          # Template file hashes (for update)
│   ├── workflow.md                    # Development workflow guide
│   ├── worktree.yaml                  # Multi-Agent worktree config
│   │
│   ├── spec/                          # Project spec library
│   │   ├── frontend/                  #   Frontend specs
│   │   │   ├── index.md               #     Spec index
│   │   │   ├── component-guidelines.md
│   │   │   ├── hook-guidelines.md
│   │   │   ├── state-management.md
│   │   │   ├── type-safety.md
│   │   │   ├── quality-guidelines.md
│   │   │   └── directory-structure.md
│   │   ├── backend/                   #   Backend specs
│   │   │   ├── index.md
│   │   │   ├── database-guidelines.md
│   │   │   ├── error-handling.md
│   │   │   ├── logging-guidelines.md
│   │   │   ├── quality-guidelines.md
│   │   │   └── directory-structure.md
│   │   └── guides/                    #   Thinking guides
│   │       ├── index.md
│   │       ├── cross-layer-thinking-guide.md
│   │       └── code-reuse-thinking-guide.md
│   │
│   ├── workspace/                     # Developer workspace
│   │   ├── index.md                   #   Workspace master index
│   │   └── {developer-name}/          #   Per-developer directory
│   │       ├── index.md               #     Personal index
│   │       └── journal-N.md           #     Session journal
│   │
│   ├── tasks/                         # Task directory
│   │   ├── {MM-DD-task-name}/         #   Active tasks
│   │   │   ├── task.json              #     Task metadata
│   │   │   ├── prd.md                 #     Requirements document
│   │   │   ├── info.md                #     Technical design (optional)
│   │   │   ├── implement.jsonl        #     Implement Agent context
│   │   │   ├── check.jsonl            #     Check Agent context
│   │   │   └── debug.jsonl            #     Debug Agent context
│   │   └── archive/                   #   Archived tasks
│   │       └── {YYYY-MM}/
│   │
│   └── scripts/                       # Automation scripts
│       ├── task.py                    #   Task management (14 subcommands)
│       ├── get-context.py             #   Get session context
│       ├── get-developer.py           #   Get developer identity
│       ├── init-developer.py          #   Initialize developer
│       ├── add-session.py             #   Record session
│       ├── common/                    #   Shared libraries
│       │   ├── paths.py
│       │   ├── developer.py
│       │   ├── git-context.py
│       │   ├── task-utils.py
│       │   ├── task-queue.py
│       │   ├── phase.py
│       │   ├── registry.py
│       │   └── worktree.py
│       └── multi-agent/               #   Parallel development scripts
│           ├── plan.py
│           ├── start.py
│           ├── status.py
│           ├── create-pr.py
│           └── cleanup.py
│
├── .claude/                           # Claude Code configuration
│   ├── settings.json                  #   Hook and permission config
│   ├── commands/                      #   Slash commands
│   │   └── trellis/                   #     Trellis command set
│   │       ├── start.md
│   │       ├── parallel.md
│   │       ├── record-session.md
│   │       ├── finish-work.md
│   │       ├── onboard.md
│   │       ├── before-dev.md
│   │       ├── before-dev.md
│   │       ├── check.md
│   │       ├── check.md
│   │       ├── check-cross-layer.md
│   │       ├── break-loop.md
│   │       ├── create-command.md
│   │       └── integrate-skill.md
│   ├── agents/                        #   Agent definitions
│   │   ├── dispatch.md
│   │   ├── plan.md
│   │   ├── implement.md
│   │   ├── check.md
│   │   ├── debug.md
│   │   └── research.md
│   ├── hooks/                         #   Hook scripts
│   │   ├── session-start.py
│   │   ├── inject-subagent-context.py
│   │   └── ralph-loop.py
│   └── skills/                        #   Skill directory
│
├── .cursor/                           # Cursor configuration
│   └── commands/
│       └── trellis-*.md               #   Cursor command set
│
├── AGENTS.md                          # Codex entry file
├── .agents/                           # Agent Skills (Codex / OpenCode)
│   └── skills/
│
├── .kilocode/                         # Kilo Code configuration
│   ├── rules/                         #   Project rules (all modes)
│   ├── workflows/                     #   Workflow commands
│   └── skills/                        #   Agent Skills
│
├── .kiro/                             # Kiro configuration
│   ├── steering/                      #   Project context (Steering system)
│   ├── hooks/                         #   Agent Hooks (event-driven automation)
│   ├── prompts/                       #   Custom prompts
│   └── specs/                         #   Spec-Driven Development docs
│
├── .iflow/                            # iFlow configuration
│   ├── commands/trellis/              #   Slash commands
│   └── hooks/                         #   SessionStart hook
│
├── .gemini/                           # Gemini CLI configuration
│   └── commands/trellis/              #   TOML commands
│
├── .qoder/                            # Qoder configuration
│   └── skills/                        #   12 auto-trigger skills
│
├── .github/                           # GitHub Copilot configuration
│   ├── copilot-instructions.md        #   Always-loaded prelude
│   └── prompts/                       #   Per-command prompts
│
├── .windsurf/                         # Windsurf configuration
│   ├── workflows/                     #   Command workflows
│   └── rules/                         #   Always-on prelude
│
├── .codebuddy/                        # CodeBuddy configuration
│   └── commands/trellis/              #   12 slash commands
│
├── .agent/                            # Antigravity configuration
│   └── workflows/                     #   Workflow files
│
└── .factory/                          # Factory Droid configuration
    ├── commands/trellis/              #   Slash commands
    ├── agents/                        #   Sub-agent definitions
    └── hooks/                         #   SessionStart hook

Your First Task

Starting a Session

Claude Code
Cursor
Codex
OpenCode

Open the Claude Code terminal. The session-start.py Hook fires automatically and context is injected. You can describe your task directly, or run /start to see the full flow.The AI automatically performs the following:

Reads workflow.md to understand the development workflow
Runs get-context.py to get current state (your identity, Git status, active tasks)
Reads spec/frontend/index.md and spec/backend/index.md to understand project specs
Asks you: “What would you like to work on?”

Open Cursor. You must first enter:

/start

Only then will the AI load context. Cursor’s Hook support is still in development, so context loading currently requires manual command invocation.

Codex provides base context via AGENTS.md, but you need to run $start to get full project context (identity, Git status, active tasks, etc.).

OpenCode’s Hook system auto-injects context at session start, no need to manually run /start. Users can describe tasks immediately after opening the terminal. Optionally run /start for a more detailed context report.

AI Creates the Task and Develops

You say: “Add user login feature”. The AI will:

1. Invoke Research Agent to analyze the codebase
   → Find relevant spec files and code patterns

2. Create a task directory
   → .trellis/tasks/02-27-user-login/
   → Generate task.json, prd.md, implement.jsonl, etc.

3. Activate the task
   → task.py start (set .current-task)

4. Invoke Implement Agent
   → Hook auto-injects all specs configured in implement.jsonl
   → Agent implements the feature following specs

5. Invoke Check Agent
   → Hook injects check specs configured in check.jsonl
   → Agent checks code quality and auto-fixes issues
   → Ralph Loop ensures lint/typecheck passes

Testing and Committing

After the AI finishes, it will prompt you:

# Run project tests
pnpm lint && pnpm typecheck && pnpm test

# Commit after confirming everything works
git add src/components/LoginForm.tsx src/api/auth.ts
git commit -m "feat(auth): add user login feature"

Recording the Session

/record-session

The AI calls add-session.py to append the session content to your journal file and update your personal index.

Coming Back the Next Day — Cross-Session Memory

The next day, open a new session and enter /start:

AI: "Hi Alice! Yesterday you completed the user login feature (commit abc1234),
     including: LoginForm component, JWT middleware, users table.
     What would you like to work on today?"

The AI reads your workspace journal through the session-start.py Hook, remembering what you worked on last time.

Platform differences: Claude Code and OpenCode automatically read journals via Hooks for cross-session memory. Cursor and Codex users need to manually trigger context loading via /start (or $start) to get cross-session memory.

Start Here

Advanced

Use Cases

Resource Marketplace

Community

Quick Start

Installation

Platform Configuration

Platform Capability Comparison (0.4.0 GA — 14 platforms)

Three Steps to Get Started

Remote Spec Templates

Official Marketplace

Custom Registry (`--registry`)

Handling Existing Specs

Building a Custom Marketplace

Private Repositories

Full Directory Structure

Your First Task

Starting a Session

AI Creates the Task and Develops

Testing and Committing

Recording the Session

Coming Back the Next Day — Cross-Session Memory

Start Here

Advanced

Use Cases

Resource Marketplace

Community

​Quick Start

​Installation

​Platform Configuration

​Platform Capability Comparison (0.4.0 GA — 14 platforms)

​Three Steps to Get Started

​Remote Spec Templates

​Official Marketplace

​Custom Registry (--registry)

​Handling Existing Specs

​Building a Custom Marketplace

​Private Repositories

​Full Directory Structure

​Your First Task

​Starting a Session

​AI Creates the Task and Develops

​Testing and Committing

​Recording the Session

​Coming Back the Next Day — Cross-Session Memory

Quick Start

Installation

Platform Configuration

Platform Capability Comparison (0.4.0 GA — 14 platforms)

Three Steps to Get Started

Remote Spec Templates

Official Marketplace

Custom Registry (`--registry`)

Handling Existing Specs

Building a Custom Marketplace

Private Repositories

Full Directory Structure

Your First Task

Starting a Session

AI Creates the Task and Develops

Testing and Committing

Recording the Session

Coming Back the Next Day — Cross-Session Memory