Install & First Task

Quick Start

Installation

# Global install (beta channel)
npm install -g @mindfoldhq/trellis@latest

# Navigate to your project directory
cd your-project

Requirements: Mac, Linux, and Windows are fully supported. Requires Node.js 18+ and Python 3.9+.

trellis init auto-detects installed platforms. You can also specify them explicitly via flags. Each platform needs to be init’d at least once. Pick any combination:

# Interactive: detects installed platforms and asks which to configure
trellis init -u your-name

# Explicit: configure one or more platforms
trellis init -u your-name --claude
trellis init -u your-name --claude --cursor --opencode
trellis init -u your-name --codex --gemini
trellis init -u your-name --pi

your-name becomes your developer identity and creates your personal workspace at .trellis/workspace/your-name/. Supported flags: --claude, --cursor, --opencode, --codex, --kiro, --gemini, --qoder, --codebuddy, --copilot, --droid, --pi, --antigravity, --devin (alias: --windsurf, deprecated), --kilo, --reasonix, --zcode, --omp. Beyond these 17 configured platforms, any AI coding agent that reads the .agents/skills/ standard (Amp, Cline, Deep Agents, Firebender, Kimi Code CLI, Warp, and more) can also consume Trellis: Codex writes its skills there, and the files are directly usable by the rest of that ecosystem.

Upgrading

Upgrading is two steps — the CLI and your project’s .trellis/ templates are versioned separately:

trellis upgrade   # 1. upgrade the global CLI package
trellis update    # 2. inside each project: sync .trellis/ + platform files to the new CLI

If trellis update reports MIGRATION REQUIRED (breaking changes between your project’s version and the CLI), run trellis update --migrate — otherwise files renamed or relocated by breaking releases stay at their stale old paths.

See Commands §1.2 for the full upgrade / update / --migrate reference.

Platform Configuration

trellis init writes platform-specific config directories. Core concepts (.trellis/) are identical across platforms; the differences sit in how commands, skills, sub-agents, and hooks are delivered.

Platform	Config Directory
Claude Code	`.claude/commands/trellis/`, `agents/`, `skills/`, `hooks/`
Cursor	`.cursor/commands/`, `agents/`, `skills/`, `hooks/`
OpenCode	`.opencode/commands/trellis/`, `agents/`, `skills/`, `plugins/`
Codex	`.codex/agents/`, `skills/`, `hooks/` + root `AGENTS.md`
Kiro	`.kiro/agents/`, `skills/`, `hooks/`
Gemini CLI	`.gemini/commands/trellis/`, `agents/`, `skills/`, `hooks/`
Qoder	`.qoder/commands/`, `agents/`, `skills/`, `hooks/`
CodeBuddy	`.codebuddy/commands/trellis/`, `agents/`, `skills/`, `hooks/`
Copilot	`.github/copilot/`, `prompts/`, `agents/`, `skills/`, `hooks/`
Droid	`.factory/commands/trellis/`, `droids/`, `skills/`, `hooks/`
Pi Agent	`.pi/prompts/`, `skills/`, `agents/`, `extensions/trellis/`, `settings.json`
Oh My Pi	`.omp/commands/`, `skills/`, `agents/`, `extensions/trellis/`
Kilo	`.kilocode/workflows/`, `skills/`
Antigravity	`.agent/workflows/`, `skills/`
Devin	`.devin/workflows/`, `skills/`

.agents/skills/ is a shared cross-platform layer (agentskills.io standard). trellis init writes all skills into it too, so any agent that reads the .agents/skills/ standard (Amp, Cline, Deep Agents, Firebender, Kimi Code CLI, Warp, etc.) can consume them.

init Scenarios

trellis init dispatches on the presence of .trellis/ and .trellis/.developer. Match your situation to the command:

Scenario	Command	Result
First-time project init	`trellis init -u your-name --claude`	Creates `.trellis/` + bootstrap task `00-bootstrap-guidelines` that walks you through filling project spec
Add a new platform to an existing project	`trellis init --cursor` (or no-arg interactive — it lists unconfigured platforms)	Writes the new platform’s config dir on top of the existing `.trellis/`; no task generated
New developer joining an existing project	`trellis init -u their-name`	Generates the joiner onboarding task `00-join-<slug>` and guides reading workflow + spec; start it in the current AI session when ready
Same developer on a new machine	Same as above	Also generates a joiner task (because `.developer` isn’t committed). Archive it if you don’t need the refresher.
Same dev, same machine, re-run init	`trellis init -u your-name`	No-op — both `.trellis/` and `.developer` already exist

--force / --skip-existing only affect how file conflicts are resolved (overwrite vs skip); they don’t change the dispatch logic itself.

Dispatch signal: .trellis/.developer is a gitignored per-checkout identity file (by design, never committed), so a fresh clone never has one — this is the clean signal for “new developer on this checkout”. .trellis/workspace/<name>/ is committed and cannot serve this role.

Basic Flow

Describe what you want to do. The AI first classifies the turn. Simple conversation and small inline tasks do not automatically create Trellis tasks; the AI asks whether this turn should create a task. Complex work gets a separate consent question before Trellis creates a task and enters planning.

# 1. Describe what you want
"Add user login feature"

# 2. AI classifies the turn and asks for task-creation consent when needed

# 3. If this is a Trellis task, AI runs Plan → Execute → Finish per workflow.md

# 4. After the work commit exists
/trellis:finish-work

Agent-capable platforms load Trellis context through a mix of SessionStart hooks, prompt hooks, extensions, agent files, and skills. Codex is different from Claude-style platforms: it relies on AGENTS.md plus the UserPromptSubmit hook, and the no-task breadcrumb can tell the AI to read trellis-start. Only agent-less platforms (Kilo, Antigravity, Devin) ship /trellis:start (or /start.md) as an explicit entry point.

Directory Structure

Below is the layout after trellis init with Claude Code. Other platforms write to their own sub-directories but share the same .trellis/ core.

your-project/
├── .trellis/                          # Trellis core (platform-independent)
│   ├── .developer                     # Developer identity (gitignored)
│   ├── .version                       # Trellis version
│   ├── .template-hashes.json          # Template file hashes (for update)
│   ├── workflow.md                    # Development workflow guide
│   ├── config.yaml                    # Project config (packages, update.skip, hooks)
│   │
│   ├── .runtime/                      # Session-scoped runtime state (gitignored)
│   │   └── sessions/                  #   Active task per AI session/window
│   │       └── <session-key>.json
│   │
│   ├── spec/                          # Project spec library
│   │   ├── frontend/                  #   Frontend specs (or per-package in monorepo)
│   │   ├── backend/                   #   Backend specs
│   │   └── guides/                    #   Thinking guides
│   │
│   ├── workspace/                     # Developer workspaces
│   │   ├── index.md
│   │   └── {developer-name}/
│   │       ├── index.md
│   │       └── journal-N.md
│   │
│   ├── tasks/                         # Task directory
│   │   ├── {MM-DD-task-name}/         #   Active tasks
│   │   │   ├── task.json              #     Task metadata
│   │   │   ├── prd.md                 #     Requirements document
│   │   │   ├── design.md              #     Technical design for complex tasks
│   │   │   ├── implement.md           #     Implementation plan for complex tasks
│   │   │   ├── implement.jsonl        #     Spec/research manifest for implementation
│   │   │   ├── check.jsonl            #     Spec/research manifest for review
│   │   │   └── research/              #     Durable investigation notes
│   │   └── archive/                   #   Archived tasks
│   │       └── {YYYY-MM}/
│   │
│   └── scripts/                       # Automation scripts (Python)
│       ├── task.py                    #   Task management
│       ├── get_context.py             #   Session context
│       ├── add_session.py             #   Record session
│       ├── create_bootstrap.py        #   First-time spec bootstrap
│       └── common/                    #   Shared libraries
│
├── .claude/                           # Claude Code configuration
│   ├── settings.json                  #   Hook and permission config
│   ├── commands/trellis/              #   Explicit commands
│   │   ├── start.md
│   │   ├── finish-work.md
│   │   └── continue.md
│   ├── agents/                        #   Sub-agent definitions
│   │   ├── trellis-implement.md
│   │   ├── trellis-check.md
│   │   └── trellis-research.md
│   ├── skills/                        #   Auto-trigger skills
│   │   ├── trellis-brainstorm/
│   │   ├── trellis-before-dev/
│   │   ├── trellis-check/
│   │   ├── trellis-update-spec/
│   │   └── trellis-break-loop/
│   └── hooks/                         #   Hook scripts
│       ├── session-start.py
│       ├── inject-subagent-context.py
│       └── inject-workflow-state.py
│
├── .cursor/           # Cursor: commands/ + rules/
├── .opencode/         # OpenCode: commands/trellis/, agents/, skills/, plugins/
├── .codex/            # Codex: prompts/, skills/ + AGENTS.md at repo root
├── .kiro/             # Kiro: steering/, prompts/, skills/
├── .gemini/           # Gemini CLI: commands/trellis/
├── .qoder/            # Qoder: commands/, skills/, agents/, hooks/
├── .codebuddy/        # CodeBuddy: commands/trellis/
├── .factory/          # Droid: commands/trellis/, skills/, hooks/
├── .pi/               # Pi Agent: prompts/, skills/, agents/, extensions/trellis/
└── .github/           # Copilot: copilot-instructions.md, prompts/

Your First Task

Starting a Session

General
Codex
Kiro
Kilo / Antigravity / Devin

Open the terminal. On hook-backed platforms, the compact SessionStart payload gives the AI enough Trellis context to route the next turn:

compact Phase Index from workflow.md
Identity, git status, active task list
Spec index paths
task artifact context order

Just describe your task.If you suspect auto-injection didn’t run or you want to reload context, open a new session or ask the AI to read the trellis-start skill once. These platforms usually do not expose /trellis:start as a slash command because the startup path already handles orientation.

You must enable hooks in ~/.codex/config.toml, or typing / in the chat won’t surface Trellis’s three commands (/start, /finish-work, /continue) and you can’t launch a session with /start.

[features]
hooks = true   # Codex 0.129+. Older versions: `codex_hooks = true`.

Codex 0.129+ also gates each installed hook behind a one-time /hooks TUI review. Open Codex once, run /hooks, and approve the Trellis UserPromptSubmit hook. Until you do, the hooks stay inactive, Trellis’s commands/skills won’t appear in the / menu, and the workflow breadcrumb won’t auto-inject. Even without them, a fallback (the AGENTS.md prelude) lets the AI read the trellis-start skill manually so context is still there — but you can’t invoke Trellis commands from /, which is a noticeably worse experience.After that, describe your task directly. Codex reads AGENTS.md automatically, and the UserPromptSubmit hook injects the current workflow-state breadcrumb. When there is no active task, that breadcrumb may include a <trellis-bootstrap> reminder telling the AI to read trellis-start once.

Kiro delivers Trellis content via its .kiro/ agent / skill files. Kiro’s Agent Hooks are user-configured (triggered on file save, build success, etc.); Trellis does not ship any Agent Hook wiring. Describe your task and Kiro’s skill matcher enters the brainstorm flow; run @trellis:start when you want a full context report.

These three platforms have workflows + skills only, no hooks and no sub-agents. Entry:

Kilo: /start.md
Antigravity: open .agent/workflows/start.md
Devin: /trellis-start

The AI follows the workflow: reads workflow.md, runs get_context.py, reads spec indexes, asks what you want to do. The subsequent implement / check phases run inline in the main session instead of spawning sub-agents.

Example: Starting a New Project from Scratch

This is the first Trellis loop for a new product, service, SDK, package, or internal tool. Real situation: you are starting a B2B dashboard with login, team management, billing, and analytics. AI can help move fast, but each session should not reinvent the directory structure, API style, component pattern, and testing rules. Starting prompt:

I am starting a new B2B dashboard from scratch. Help me set up Trellis for the first week of work.

First, ask for the missing product and tech-stack decisions. Then create a small first task and the minimum specs needed for frontend structure, API shape, error handling, and test strategy.

Workflow:

After project initialization, run trellis init. It writes default spec templates under .trellis/spec/ (about 17 placeholder files across backend/, frontend/, and guides, covering directory structure, error handling, logging, component guidelines, cross-layer thinking, and similar rules), and creates the 00-bootstrap-guidelines task.
Use the bootstrap task to discuss product requirements and the project tech stack with AI, so the AI has enough context before writing code.
Optional: use the bundled trellis-spec-bootstarp skill so AI can draft first-pass specs from the real codebase. It is installed with Trellis, so there is no extra marketplace download step.
Fill the default specs produced by trellis init first, based on what you know now. Do not design the entire project upfront.
Review the generated spec quality by hand.
Create the smallest task that can run end to end.
Continue with /trellis:continue; Trellis will move the task through check, update-spec, commit, and finish.

AI Creates the Task and Develops

You say: “Add user login feature”. The AI first decides this is complex enough for a Trellis task and asks whether it may create a task and enter planning. If you agree, it walks the three phases from workflow.md:

Phase 1 — Plan (interactive)
 1.0 task.py create creates the task directory and default prd.md
 1.1 AI activates the trellis-brainstorm skill and walks through the requirement
     one question at a time, iterating prd.md
 1.2 For complex tasks, AI writes design.md and implement.md before implementation
 1.3 When research is needed, findings land in research/
 1.4 Sub-agent mode curates implement.jsonl / check.jsonl with spec + research
     paths only, not source paths
 1.5 After review, task.py start flips status to in_progress

Phase 2 — Execute
 2.1 AI implements against prd.md, design.md if present, implement.md if present,
     and relevant specs. Depending on platform/mode, this may be a sub-agent
     or inline main-session work.
 2.2 AI runs trellis-check → reviews diff vs artifacts + specs and runs
     lint / typecheck / test, self-fixing when possible

Phase 3 — Finish
 3.1 AI activates the trellis-check skill for final verification
 3.2 (on demand) AI activates the trellis-break-loop skill for debug retrospective
 3.3 AI activates the trellis-update-spec skill and writes new learnings to
     .trellis/spec/
 3.4 AI proposes the work commit plan, commits approved batches, then runs
     /trellis:finish-work for archive and journal bookkeeping

When AI stalls or is skipping ahead: run /trellis:continue. AI uses the active task’s status, artifact presence, and the per-turn workflow-state breadcrumb to figure out the next step, then loads the relevant workflow detail before continuing.

Finishing the Session

/trellis:finish-work

finish-work calls add_session.py to append a journal entry and update your personal index. If the task is actually done (code merged, acceptance criteria met), it also archives the task via task.py archive.

Cross-Session Memory

Next time you open a session, the SessionStart hook (or the platform’s prelude) reads your workspace journal and active task list, so AI can recall what you did last:

AI: "Hi Alice — last session you finished the user login feature (commit abc1234),
     covering the LoginForm component, JWT middleware, and users table.
     What next?"

Journals live under .trellis/workspace/{name}/journal-N.md; every /trellis:finish-work appends one. Trellis tracks each AI session’s active task internally so you can pick it up next time; task.py finish clears that pointer.

Remote Spec Templates

Instead of writing specs from scratch, 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.

Start Here

Advanced

Use Cases

Resource Marketplace

Community

Quick Start

Installation

Upgrading

Platform Configuration

init Scenarios

Basic Flow

Directory Structure

Your First Task

Starting a Session

Example: Starting a New Project from Scratch

AI Creates the Task and Develops

Finishing the Session

Cross-Session Memory

Remote Spec Templates

Official Marketplace

Custom Registry (`--registry`)

Handling Existing Specs

Building a Custom Marketplace

Private Repositories

​Quick Start

​Installation

​Upgrading

​Platform Configuration

​init Scenarios

​Basic Flow

​Directory Structure

​Your First Task

​Starting a Session

​Example: Starting a New Project from Scratch

​AI Creates the Task and Develops

​Finishing the Session

​Cross-Session Memory

​Remote Spec Templates

​Official Marketplace

​Custom Registry (--registry)

​Handling Existing Specs

​Building a Custom Marketplace

​Private Repositories

Quick Start

Installation

Upgrading

Platform Configuration

init Scenarios

Basic Flow

Directory Structure

Your First Task

Starting a Session

Example: Starting a New Project from Scratch

AI Creates the Task and Develops

Finishing the Session

Cross-Session Memory

Remote Spec Templates

Official Marketplace

Custom Registry (`--registry`)

Handling Existing Specs

Building a Custom Marketplace

Private Repositories