Trellis

Outcome-Driven Development for AI coding agents.

A planning and build harness for domain experts who are building serious software with AI — and want to understand exactly what they're doing and why.

Works with Claude Code, OpenCode, and Codex.

What this is

Trellis turns your AI coding agent into a guided harness for planning and building real software systems: from school context and governance, to personas and outcomes, to safety controls, delivery choices, and verified build work.

You don't need to write code. You need to understand your domain. That's the skill that matters now.

"The AI is the most capable junior engineer who ever lived. It can build anything you describe. It will build exactly what you describe. It will not tell you that what you described is the wrong thing to build. That judgement remains entirely yours."

Trellis is the companion tool to The ODD Way to Build Software with Agentic AI — the book that teaches Outcome-Driven Development from first principles (book available on Amazon - https://www.amazon.co.uk/dp/B0GHT5T371). Every step in the tool references the relevant chapter. You'll understand the method as you use it, not just follow instructions.

Install

For Claude Code

Add the following into Terminal inside your project folder, NOT your system root folder.

npx trellis-cli init

For OpenCode (with Ollama / local models)

npx trellis-cli init --agent opencode

For Codex

npx trellis-cli init --agent codex

In Codex, start Trellis with a natural-language kickoff such as use Trellis, start Trellis, or begin Trellis. For a state check, use Trellis status. To continue building, use Trellis build. To debug without leaving the active outcome flow, use Trellis debug. Trellis now ships Codex skill-discovery metadata so these prompts can match the plugin directly instead of relying only on AGENTS.md.

If this project was originally set up for Claude Code or OpenCode and you want to add Codex later, run:

npx trellis-cli upgrade --agent codex

For Claude Code and OpenCode on the same machine

npx trellis-cli init --agent both

For every supported agent on the same machine

npx trellis-cli init --agent all

Everything is installed into your project folder. Nothing is written to your home directory or installed globally.

That single command:

• Detects your installed AI coding agent (or uses --agent to specify)
• Scaffolds your project structure (docs/, .odd/, instruction files)
• Installs the Trellis harness into the matching project-local agent surface (.claude/, .opencode/, or plugins/trellis/)
• Configures odd-flow MCP server for cross-session memory in the matching agent config
• Initialises git with an initial commit

Then open your project in your AI coding agent and start Trellis:

Claude Code / OpenCode: /trellis
Codex: `use Trellis`

Supported agents

| Agent | How Trellis integrates | Model support | |-------|-------------------|---------------| | Claude Code | Project-local skills (.claude/skills/), hooks (.claude/settings.local.json), odd-flow MCP (.mcp.json) | Claude (Opus, Sonnet, Haiku) | | OpenCode | Project-local commands (.opencode/commands/), JS plugin (.opencode/plugins/), odd-flow MCP (opencode.json) | Any provider — Ollama (Qwen3-Coder, MiniMax M2.7, DeepSeek), OpenAI, Anthropic, Google, Groq, and 75+ more | | Codex | Project-local plugin (plugins/trellis/), skill-discovery metadata in SKILL.md, local marketplace registration (.agents/plugins/marketplace.json), plugin MCP (plugins/trellis/.mcp.json) | Codex |

All supported agents get the same methodology, the same safety enforcement, and the same odd-flow-powered cross-session memory. The only difference is the delivery mechanism.

What happens when you start Trellis

Your AI coding agent loads the Trellis orchestrator. It checks whether you have an existing project in progress (via your local .odd/state.json and odd-flow memory) and either:

• New project: Starts with a compact kickoff and begins planning one focused question at a time.
• Returning project: Shows you exactly where you left off and resumes from there. Nothing is lost between sessions.

The default interaction mode is intentionally tight:

• one focused question at a time
• short summaries
• explicit next action
• deeper explanation only when you ask *why

From there, use the dedicated direct commands in Claude Code or OpenCode, natural-language Trellis prompts in Codex, or type sub-commands inside the active Trellis session once it is running.

For the fastest handoff back into planning, run:

npx trellis-cli status

Trellis will show the current stage, the exact next trellis planning-action ... command, and a starter payload scaffold.

The planning flow

Trellis guides planning in this order. Each stage produces artifacts and canonical state before the next one begins.

1. Context and governance
2. Personas
3. Outcomes
4. Contracts
5. Architecture
6. UI and UX
7. Compliance and safeguarding
8. Delivery decisions
9. Operations and handover
10. Build plan
11. Verification design
12. Inspection pack

The build phase comes after this planning flow is complete. Trellis then uses the plan, outcomes, contracts, and verification design to direct build work safely.

Key outputs include:

• docs/governance/
• docs/personas/
• docs/outcomes/
• docs/contracts/
• docs/architecture/
• docs/ui/
• docs/compliance/
• docs/delivery/
• docs/operations/
• docs/verification/
• docs/inspection/
• .odd/trellis-state.json

The safety layer

Trellis installs safety gates that run automatically throughout your build. The implementation differs by agent, but the enforcement is identical:

| Gate | When | What it does | |------|------|-------------| | Brief gate | Before agent spawning | Blocks build agents until the session brief is confirmed | | Swarm write gate | Before file writes | Blocks writes during swarm builds unless from an assigned agent | | Verify gate | Before state edits | Blocks premature outcome confirmation | | odd-flow build gate | Before agent spawning | Blocks builds without odd-flow sync | | Outcome quality | After writing outcomes | Checks all 6 fields present; flags banned technical vocabulary | | Persona quality | After writing personas | Checks all 7 dimensions are present | | Code elegance | After writing source files | Checks file length against Trellis limits | | Security baseline | After writing source files | Flags hardcoded secrets, insecure auth/session patterns, and unsafe rendering/network shortcuts | | Session save | After git commit | Auto-saves project state for session continuity |

Claude Code: Implemented as shell hooks registered in .claude/settings.local.json (project-local). OpenCode: Implemented as a JS plugin (trellis-plugin.js) in .opencode/plugins/ (project-local). Codex: Implemented as a project-local plugin in plugins/trellis/ with hooks.json, plugin-local skills, and Codex skill-discovery metadata for prompts such as use Trellis, Trellis status, and Trellis build.

The build layer (odd-flow)

When you're ready to build, Trellis initialises an odd-flow swarm — a team of parallel specialist agents that build your outcomes concurrently:

• Coordinator — reads your contracts, publishes shared technical contracts before parallel building begins
• Backend agent — implements data layer and business logic per your outcome specifications
• UI agent — implements the frontend using shadcn/ui, Tailwind CSS v4, and Framer Motion, against WCAG 2.1 AA accessibility standards
• QA agent — runs your verification steps and reports failures in your language, not technical error messages

odd-flow MCP is configured automatically in your project-local agent config — .mcp.json for Claude Code, opencode.json for OpenCode, and plugins/trellis/.mcp.json for Codex. Every agent knows the full project state, regardless of which sessions they were spawned in.

When verification fails, use *debug instead of leaving the Trellis flow. Trellis records the failure, selects an explicit debug strategy, keeps the outcome active, and routes the work back into verification once the defect is fixed.

Using OpenCode with local models

OpenCode connects to any Ollama-hosted model. Recommended models for Trellis builds:

| Model | Active params | Context | Best for | |-------|-------------|---------|----------| | Qwen3-Coder | 3.3B | 256K | Fast local builds on consumer hardware | | Qwen 3.6 Plus | MoE | 1M | Full codebase understanding, complex outcomes | | MiniMax M2.7 | ~10B | 204K | Self-improving agent scaffolds, strong skill adherence | | MiniMax M2.1 | ~10B | 1M | Long-context builds, multilingual projects | | GLM-5 | 32-40B | 205K | Frontier-class reasoning and coding | | DeepSeek V3 | MoE | 128K | Cost-effective API alternative to running local |

Install a model via Ollama and configure it in your opencode.json:

ollama pull qwen3-coder

Trellis's structured methodology — narrow outcome specs, pre-defined contracts, external enforcement via the plugin — means even smaller models produce reliable builds. The methodology compensates for model limitations.

Default tech stack

Trellis configures a considered default stack that handles 90% of projects well:

| Layer | Technology | Why | |-------|-----------|-----| | Framework | Next.js (App Router) + TypeScript | Server-rendered, fast, well-supported | | Styling | Tailwind CSS v4 | Consistent design without custom CSS | | Components | shadcn/ui | Beautiful, accessible, you own the code | | Primitives | Radix UI | Keyboard navigation and ARIA built in | | Animation | Framer Motion | Micro-interactions without complexity | | Database | PostgreSQL via Drizzle | Type-safe, lightweight, agents know exact data shape | | Testing | Vitest | Fast watch mode, automated business rule testing | | Auth | NextAuth.js | Handles the complexity you don't want to | | Payments | Stripe | The right choice for most use cases | | Email | Resend | Modern, reliable, developer-friendly | | Deploy | Vercel | Zero-configuration deployment |

The AI proposes the stack based on your outcomes. You approve it based on consequences, not technical details. If your outcomes require something different, tell the AI in domain terms and it will adapt.

Project structure

After npx trellis-cli init, your project looks like this:

my-project/
├── CLAUDE.md                        ← Trellis build rules (Claude Code)
├── AGENTS.md                        ← Trellis build rules (OpenCode and Codex)
├── .mcp.json                        ← odd-flow MCP config (Claude Code)
├── .odd/
│   ├── state.json                   ← Compatibility state (updated automatically)
│   └── trellis-state.json           ← Canonical Trellis planning state
├── .claude/                         ← Claude Code config (project-local)
│   ├── skills/trellis/                  ← /trellis skill and sub-commands
│   ├── skills/excalidraw/           ← /excalidraw wireframing skill
│   ├── hooks/trellis.sh          ← Safety gate script
│   └── settings.local.json          ← Hook registrations
├── .opencode/                       ← OpenCode config (project-local)
│   ├── commands/                    ← /trellis command files
│   ├── plugins/trellis-plugin.js ← Safety gate plugin
│   └── trellis/                         ← Skill knowledge base
├── .agents/plugins/marketplace.json ← Codex local marketplace registration
├── plugins/trellis/              ← Codex project-local plugin
│   ├── .codex-plugin/plugin.json    ← Codex plugin manifest
│   ├── commands/trellis.md              ← Codex /trellis command entrypoint
│   ├── skills/                      ← Trellis skills for Codex
│   ├── hooks/trellis.sh          ← Safety gate hook script
│   ├── hooks.json                   ← Codex hook registration
│   └── .mcp.json                    ← odd-flow MCP config for Codex
└── docs/
    ├── plan.md                      ← Master Implementation Plan
    ├── contract-map.md              ← Contracts and dependency graph
    ├── governance/                  ← Ownership, approvals, school context
    ├── personas/                    ← One file per user type
    ├── outcomes/                    ← One file per workflow
    ├── contracts/                   ← Canonical contract docs
    ├── architecture/                ← System shape and storage decisions
    ├── ui/                          ← UI specifications per outcome
    ├── compliance/                  ← Regime profile, manifest, review gates
    ├── delivery/                    ← Stack and testing decisions
    ├── operations/                  ← Backup, rollover, handover
    ├── verification/                ← Outcome and contract checks
    └── inspection/                  ← Inspection-pack outputs

Only the config directories for your target agent are generated (.claude/, .opencode/, plugins/trellis/, or a supported combination).

Direct Commands

These are the top-level direct commands you can invoke in Claude Code or OpenCode:

| Command | What it does | |---------|-------------| | /trellis | Start or resume a Trellis project — the main planning and build orchestrator | | /trellis-plan | Start or continue the planning flow | | /trellis-build | Start or continue a build session — reads project state and executes the build protocol | | /trellis-debug | Start or continue controlled debugging inside the active outcome — chooses ui-behaviour, full-stack, auth-security, integration-contract, background-process, or performance-state before any fix | | /trellis-status | Show current project state, phase progress, and the exact next action scaffold | | /trellis-swarm | Build all independent outcomes in the current phase simultaneously using odd-flow parallel agents | | /trellis-deploy | Verify all outcomes are confirmed, then deploy the current phase to production | | /trellis-sync | Sync project state to odd-flow memory (required before building) |

Sub-commands inside /trellis

Once Trellis is active, you can use these sub-commands in Claude Code, OpenCode, or Codex:

*persona       Work on personas with Diana
*outcome       Write outcomes with Marcus
*contracts     Map contracts with Theo
*debug         Keep a failing build inside Trellis and route it through an explicit debug strategy
*phase-plan    Jump to implementation planning with Rachel
*ui            Load UI excellence layer briefing
*agent         Create a custom agent for a domain-specific concern
*export        Generate Phase Brief → docs/session-brief-[N].md
*chapter [n]   Load coaching from relevant book chapter
*why           Explain why the current step matters
*kb            Load full Trellis knowledge base
*help          Show all commands
*reset         Clear state and start over (asks for confirmation)

During planning, the operational path is:

1. Ask the next focused question
2. Confirm the answer
3. Persist the stage with trellis planning-action ...
4. Move to the next stage

When verification fails

Stay inside the Trellis flow:

1. Describe the failure in domain language
2. Run *debug inside /trellis, or use /trellis-debug in Claude Code or OpenCode, or say Trellis debug in Codex
3. Let Trellis classify the failure before fixing it:
   • ui-behaviour
   • full-stack
   • auth-security
   • integration-contract
   • background-process
   • performance-state
4. Verify again only after the fix returns the build to verify mode

Example:

“The creator saves the price change, but the course page still shows the old amount.”

That should route to full-stack, because the defect crosses UI action, server handling, and persisted state. The harness now blocks quick fixes until the failure has been classified and the debug mode is recorded in .odd/state.json.

CLI commands

npx trellis-cli init [name]           # Scaffold a new Trellis project
npx trellis-cli init --agent opencode # Scaffold for OpenCode (local models)
npx trellis-cli init --agent codex    # Scaffold for Codex
npx trellis-cli init --agent both     # Scaffold for both agents
npx trellis-cli init --agent all      # Scaffold for Claude Code, OpenCode, and Codex
npx trellis-cli init --skip-git       # Scaffold without git init or the initial commit
npx trellis-cli status                # Show current state plus next action scaffold (run from project dir)
npx trellis-cli planning-action ...   # Persist a confirmed planning stage into canonical state
npx trellis-cli upgrade               # Update skills, hooks, and odd-flow config (run from project dir)
npx trellis-cli uninstall             # Remove Trellis agent assets from the project
npx trellis-cli export                # Instructions for exporting the Session Brief

Upgrading

Run from inside your existing Trellis project:

npx trellis-cli@latest upgrade

This updates skills, hooks, plugins, and odd-flow config in your project folder. No global files are modified.

What you'll learn

By the time you've built your first system with Trellis, you'll understand:

• Why your users' constraints — not their preferences — determine good software design
• Why the connections between features matter more than the features themselves
• How to describe what you want precisely enough that an AI builds it correctly
• How to verify that what was built matches what you intended
• How to direct a build across multiple sessions without losing context
• How to catch problems before they become expensive to fix

These are the skills that make you effective at building with AI — permanently, not just for this project.

The book

Trellis implements the methodology from The ODD Way to Build Software with Agentic AI (https://www.amazon.co.uk/dp/B0GHT5T371). Each step in the tool references the chapter that explains the underlying principle. The book and the tool are the same learning experience — you can start with either.

Requirements

• Node.js 18+
• One of:
  • Claude Code installed (npm install -g @anthropic-ai/claude-code)
  • OpenCode installed (npm install -g opencode or brew install opencode)
  • Codex installed
• odd-flow MCP is configured automatically by npx trellis-cli init

For local model builds (OpenCode)

• Ollama installed
• A capable model pulled (e.g. ollama pull qwen3-coder)

License

MIT