A multi-platform AI coding framework that rules
_{Supports Claude Code, Cursor, OpenCode, iFlow, Codex, Kilo, Kiro, Gemini CLI, Antigravity, Windsurf, Qoder, CodeBuddy, GitHub Copilot, and Factory Droid.}

简体中文 • Docs • Quick Start • Supported Platforms • Use Cases

Why Trellis?

Capability	What it changes
Auto-injected specs	Write conventions once in .trellis/spec/, then let Trellis inject the relevant context into each session instead of repeating yourself.
Task-centered workflow	Keep PRDs, implementation context, review context, and task status in .trellis/tasks/ so AI work stays structured.
Parallel agent execution	Run multiple AI tasks side by side with git worktrees instead of turning one branch into a traffic jam.
Project memory	Journals in .trellis/workspace/ preserve what happened last time, so each new session starts with real context.
Team-shared standards	Specs live in the repo, so one person’s hard-won workflow or rule can benefit the whole team.
Multi-platform setup	Bring the same Trellis structure to 14 AI coding platforms instead of rebuilding your workflow per tool.

Prerequisites

• Node.js ≥ 18
• Python ≥ 3.10 (required for hooks and automation scripts)

Quick Start

# 1. Install Trellis
npm install -g @mindfoldhq/trellis@latest

# 2. Initialize in your repo
trellis init -u your-name

# 3. Or initialize with the platforms you actually use
trellis init --cursor --opencode --codex -u your-name

• -u your-name creates .trellis/workspace/your-name/ for personal journals and session continuity.
• Platform flags can be mixed and matched. Current options include --cursor, --opencode, --iflow, --codex, --kilo, --kiro, --gemini, --antigravity, --windsurf, --qoder, --codebuddy, --copilot, and --droid.

Commands

Command	What it does
/start	Load project context into the session. Run once at the beginning — on platforms with hooks (Claude Code, iFlow, OpenCode, Codex, GitHub Copilot) this happens automatically.
/brainstorm	Walk through requirements and produce a PRD. Use when starting a new feature or when the scope is unclear.
/before-dev	Read the relevant specs before you start coding (auto-detects frontend/backend). Run after /brainstorm and before writing any code.
/check	Review your changes against project specs and auto-fix violations (auto-detects frontend/backend). Run after implementation, before committing.
/finish-work	Pre-commit checklist covering lint, tests, docs, and API changes. Run right before git commit as a final gate.
/parallel	Spin up multiple agents in isolated git worktrees. Use for large tasks that can be split into independent subtasks.
/record-session	Save a session summary to the workspace journal. Run after the human has tested and committed the code.
/update-spec	Capture a new pattern or convention into spec files. Run whenever you discover a rule worth preserving for future sessions.

Use Cases

"AI keeps ignoring our conventions"

You write a database naming rule once in .trellis/spec/backend/database-guidelines.md. From that point on, every session — whether started by you, a teammate, or a parallel agent — gets that rule injected automatically. No more pasting the same instructions into every chat window.

"I need three features done by Friday"

Run /parallel to spin up three agents, each in its own git worktree with its own branch. They implement, self-check, and open draft PRs independently. You review and merge when ready — no waiting, no branch conflicts.

"New session, zero context"

When you /record-session at the end of a workday, the current session summary lands in your workspace journal. When you start a new session the next day, the startup hook picks it up automatically, so the AI already knows what you shipped, what broke, and what’s left.

"Half the team uses Cursor, half uses Claude Code"

Run trellis init --cursor --claude once. Both tools read the same .trellis/spec/ and .trellis/tasks/. A spec improvement made in a Claude Code session is available in Cursor the next time someone opens the project.

How It Works

Trellis keeps the core workflow in .trellis/ and generates the platform-specific entry points you need around it.

.trellis/
├── spec/                    # Project standards, patterns, and guides
├── tasks/                   # Task PRDs, context files, and status
├── workspace/               # Journals and developer-specific continuity
├── workflow.md              # Shared workflow rules
└── scripts/                 # Utilities that power the workflow

Depending on the platforms you enable, Trellis also creates tool-specific integration files such as .claude/, .cursor/, AGENTS.md, .agents/, .codex/, .kilocode/, .kiro/skills/, .gemini/, .agent/workflows/ (Antigravity), .windsurf/workflows/, .qoder/, .codebuddy/, .github/copilot/, .github/hooks/, .github/prompts/, and .factory/ (Droid). For Codex, Trellis also installs project skills under .agents/skills/ (shared with Cursor, Gemini CLI, GitHub Copilot, Amp, and Kimi Code).

At a high level, the workflow is simple:

1. Define standards in specs.
2. Start or refine work from a task PRD.
3. Let Trellis inject the right context for the current task.
4. Use checks, journals, and worktrees to keep quality and continuity intact.

Spec Templates & Marketplace

Specs ship as empty templates by default — they are meant to be customized for your project's stack and conventions. You can fill them from scratch, or start from a community template:

# Fetch templates from a custom registry
trellis init --registry https://github.com/your-org/your-spec-templates

Browse available templates and learn how to publish your own on the Spec Templates page.

What's New

• v0.4.0: command consolidation (before-backend-dev + before-frontend-dev → before-dev, check-backend + check-frontend → check), new /update-spec command for capturing knowledge into specs, internal Python scripts refactoring.
• v0.3.6: task lifecycle hooks, custom template registries (--registry), parent-child subtasks, fix PreToolUse hook for CC v2.1.63+.
• v0.3.5: hotfix for delete migration manifest field name (Kilo workflows).
• v0.3.4: Qoder platform support, Kilo workflows migration, record-session task awareness.
• v0.3.1: background watch mode for trellis update, improved .gitignore handling, docs refresh.
• v0.3.0: platform support expanded from 2 to 10, Windows compatibility, remote spec templates, /trellis:brainstorm.

FAQ

How is this different from CLAUDE.md, AGENTS.md, or .cursorrules?

Those files are useful, but they tend to become monolithic. Trellis adds structure around them: layered specs, task context, workspace memory, and platform-aware workflow wiring.

Is Trellis only for Claude Code?

No. Trellis supports 14 platforms today. See the Supported Platforms guide for the full list and per-tool setup.

Do I have to write every spec file manually?

No. Many teams start by letting AI draft specs from existing code and then tighten the important parts by hand. Trellis works best when you keep the high-signal rules explicit and versioned.

Can teams use this without constant conflicts?

Yes. Personal workspace journals stay separate per developer, while shared specs and tasks stay in the repo where they can be reviewed and improved like any other project artifact.

Star History

Community & Resources

• Official Docs - Product docs, setup guides, and architecture
• Quick Start - Get Trellis running in a repo fast
• Supported Platforms - Platform-specific setup and command details
• Real-World Scenarios - See how the workflow plays out in practice
• Changelog - Track current releases and updates
• Tech Blog - Product thinking and technical writeups
• GitHub Issues - Report bugs or request features
• Discord - Join the community

Official Repository • AGPL-3.0 License • Built by Mindfold