> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trytrellis.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Install & First Task
## Quick Start
### Installation
```bash theme={null}
# 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:
```bash theme={null}
# 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:
```bash theme={null}
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](/start/everyday-use#1-2-commands) 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](https://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-` 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//` 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.
```text theme={null}
# 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
│ │ └── .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
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`.**
```toml theme={null}
[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 ``
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:
```text theme={null}
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:
1. 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.
2. Use the bootstrap task to discuss product requirements and the project tech stack with AI, so the AI has enough context before writing code.
3. 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.
4. Fill the default specs produced by `trellis init` first, based on what you know now. Do not design the entire project upfront.
5. Review the generated spec quality by hand.
6. Create the smallest task that can run end to end.
7. 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`:
```text theme={null}
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
```bash theme={null}
# 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](https://github.com/mindfold-ai/Trellis/tree/main/marketplace). Choose one or start with blank specs.
### Custom Registry (`--registry`)
Pull specs from your own GitHub, GitLab, or Bitbucket repository:
```bash theme={null}
# 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:
```json theme={null}
{
"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:
```bash theme={null}
GIGET_AUTH=ghp_xxxxx trellis init --registry gh:myorg/private-repo/specs
```
For GitHub fine-grained tokens, you need **Contents** and **Metadata** read permissions.