trellis
e-onux/trellis
Trellis: a capability-first, evidence-governed standard that keeps AI-generated software understandable, testable and maintainable as it grows. Agent-independent (Claude Code, Codex, Copilot, Cursor, Windsurf, Gemini).
Instalação
npx convez-ai e-onux/trellis1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Trellis
A capability-first, evidence-governed standard that keeps AI-generated software understandable, testable and maintainable as it grows.
Let AI-built software grow without sprawling.
🌐 trellis.sidre.site - try the wizard
A trellis doesn't make a plant grow - it keeps it from sprawling. Trellis does the same for software an AI agent builds: it lets the codebase grow while keeping it bounded, verifiable and explainable.
Why Trellis exists
Generating code is now trivial. Keeping it under control is not. When an agent builds feature after feature, the codebase tends to:
- grow without bound - duplicated responsibilities, runaway dependencies, ballooning files;
- drift from its own architecture - locally sensible changes that are globally inconsistent;
- lose the why - decisions live in chat history, not in the repository;
- hide its tests - only engineers can see whether a feature actually works;
- forget its sources - technical choices outlive the evidence that justified them.
In 2026, AI writes a large share of production code - but without governance, studies report materially more security defects and far higher long-term maintenance cost. Spec-driven tools tell an agent what to build. Trellis preserves why it was built that way, how each piece is verified, how much it is allowed to grow, and when it must be reconsidered.
What Trellis is
Trellis is not another coding agent. It is an agent-independent repository standard plus a small toolchain that layers on top of the agent you already use (Claude Code, Codex, GitHub Copilot, Cursor, Windsurf, Gemini CLI…).
It is built from parts that exist separately elsewhere - but combines them into one standard that no single tool offers today:
| Pillar | What it does | Where it lives |
|---|---|---|
| 🧠 Repository-native memory | Decisions, sources and contracts live in the repo, not in chat history | governance/, tech/ |
| 📐 Capability contracts | Every meaningful behavior has a machine-checkable input/output contract | capabilities/*/contract.yaml |
| 📊 Capability budgets | Technical and semantic limits (files, LOC, deps, responsibilities) - enforced | budgets: + trellis budget-check |
| 🔍 Evidence graph | Source → Claim → Decision → Capability → Test → User validation | sources/, ADR evidence: |
| 🗂️ Decision lifecycle | ADRs with assumptions, review intervals and re-evaluation triggers | tech/decisions/ |
| 🧩 Extension contracts | Directory-local rules listing the files an extension must register | EXTENSIONS.md, extension-registry.yaml |
| 🖥️ User-facing test cockpit | Non-engineers compare expected vs actual output per capability | /__capabilities (Phase 2) |
| 🛑 Obligation to not write code | Machine-readable stop conditions; agent proposes split/refactor/ADR instead | governance/agent-authority.md |
| 🚦 Quality gates | CI gates: contract, budget, drift, evidence, regression | .github/workflows/, quality/quality-gates.yaml |
| ⏳ Technology lifecycle | Upgrade & refactor triggers so decisions don't silently rot | tech/technology-radar.md |
Multi-platform support
Trellis treats AGENTS.md - now stewarded by the Linux Foundation's Agentic AI Foundation and read by 20+ tools - as the canonical instruction surface, and generates thin per-tool pointer files so there is a single source of truth:
| Platform | File generated | Role |
|---|---|---|
| Codex / Jules / Aider / Zed | AGENTS.md | Native (canonical) |
| Claude Code | CLAUDE.md | Pointer → AGENTS.md |
| GitHub Copilot | .github/copilot-instructions.md | Pointer → AGENTS.md |
| Cursor | .cursor/rules/trellis.mdc | Pointer → AGENTS.md |
| Windsurf | .windsurf/rules/trellis.md | Pointer → AGENTS.md |
| Gemini CLI | GEMINI.md | Pointer → AGENTS.md |
The repository itself dogfoods this: see AGENTS.md, CLAUDE.md, .github/copilot-instructions.md.
Quickstart
There are three ways to adopt Trellis. All produce the same governed structure.
Option A0 - Single prompt (truly zero-touch) ⭐⭐
Paste one prompt into your agent — no files to download, no wizard to visit:
"Fetch https://raw.githubusercontent.com/e-onux/trellis/main/INSTALL.md and follow its instructions."
The agent fetches INSTALL.md, analyzes your project, downloads and applies
TRELLIS.md, scaffolds governance, and discards the install file when done. Your project ends up
with only the governed structure — no installation artifacts.
Option A - Agent-native (one curl) ⭐
Copy the bootstrap manifesto into your repo and tell your agent to follow it:
curl -o TRELLIS.md https://raw.githubusercontent.com/e-onux/trellis/main/TRELLIS.md
"Read
TRELLIS.mdand bootstrap this repository according to it."
The agent reads TRELLIS.md, analyzes the repo, and scaffolds the governance directories, capability contracts and agent adapters itself.
Option B - CLI (deterministic / CI-friendly)
# from this monorepo
npm install
node packages/cli/bin/trellis.js --help
# in a target project (once published to npm)
npx @e-onux/trellis init --profile backend --agents claude,codex,copilot --preset standard
npx @e-onux/trellis validate # contract + budget + drift checks
npx @e-onux/trellis budget-check # capability size/dependency budgets
npx @e-onux/trellis audit # whole-repo health report
npx @e-onux/trellis extension validate # extension completeness gate
Progressive adoption
You don't adopt all of Trellis on day one:
Level 1 Governance + ADRs (project memory)
Level 2 Capability contracts (executable specs)
Level 3 Automated tests (unit/contract/property)
Level 4 User test cockpit (human-verifiable surface)
Level 5 Capability & architecture budgets (anti-bloat enforcement)
Level 6 Lifecycle + upgrade automation (decisions that don't rot)
Repository layout
trellis/
├── TRELLIS.md ← single bootstrap manifesto (agent-independent)
├── AGENTS.md ← canonical agent instructions
├── CLAUDE.md GEMINI.md .cursor/ .windsurf/ .github/ ← per-tool adapters
├── standard/ ← the open standard
│ ├── README.md ← spec overview + adoption levels
│ ├── schemas/ ← JSON Schemas (contract, ADR, source, gates, radar, extension)
│ ├── templates/ ← ADR, capability, source, refactor/split/extension templates
│ ├── profiles/ ← backend / frontend / data-pipeline / llm-app defaults
│ └── repo-skeleton/ ← the governed directory tree scaffolded into your repo
├── packages/
│ ├── core/ ← engine: compose (browser-safe), scaffold, budgets, contract & extension validation, audit
│ └── cli/ ← `trellis` command (wraps core)
├── examples/
│ └── calculate-shipping-cost/ ← a fully worked capability
├── capabilities/ tech/decisions/ sources/ quality/ ← this repo governed by its own standard
└── docs/
├── comparison.md ← how Trellis relates to Spec Kit, OpenSpec, BMAD, Kiro, Tessl, AGENTS.md
├── integrations/ ← per-tool guides (Claude Code, Codex, Copilot, Cursor, Windsurf, Gemini)
└── founding-design.md ← the original concept this project grew from
The landing page + wizard (trellis.sidre.site) is maintained in a separate website workspace that builds from a checkout of this repository (see ADR-0003); this repo stays the bare standard + toolchain.
Self-hosted
Trellis applies its own standard to this repository: the engine's behaviors are
capability contracts whose budgets measure the real source files,
decisions live in ADRs backed by sources,
and CI runs trellis audit --root . on every push. A worked end-to-end example app lives at
e-onux/trellis-example-app.
Docs
- Getting started
- How Trellis relates to other tools
- Integration guides: Claude Code · Codex · Copilot · Cursor · Windsurf · Gemini
- Roadmap · Changelog
Roadmap
- ✅ Phase 1 - open standard, schemas, templates, profiles, multi-platform adapters, worked example, and a working CLI (
init/validate/budget-check/audit/extension). - ✅ Phase 2 - web wizard & landing site (live at trellis.sidre.site, maintained in a separate website workspace): a static browser wizard that, from your choices (platforms, profile, greenfield/brownfield, strictness, modules), produces three outputs from the same
composeengine the CLI uses: copy the tailored AI spec, copy annpxcommand, or download a.zipstarter. - ✅ v0.2 - honest gate reporting (unevaluated gates are visible, never silently green), real import scanning for budgets, evidence-graph reference validation, npm packaging, self-hosted governance.
- ⏳ Next - see ROADMAP.md: decision/source scaffolding commands, wired test gate, brownfield discovery, then the test cockpit MVP.
Status
Early but real. The standard and toolchain are usable today; APIs and schemas may change before 1.0. Issues and proposals welcome - see CONTRIBUTING.md.
License
Apache-2.0 © Trellis Framework contributors.