convez.ai
Agente
e-onux

trellis

e-onux/trellis

Ver no GitHub
InicialPluginScore · de 0 a 100

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/trellis

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 3 semanas
Versão
—
Issues abertas
5
Contribuidores
1

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.

License: Apache 2.0 Standard Agent-independent

🌐 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:

PillarWhat it doesWhere it lives
🧠 Repository-native memoryDecisions, sources and contracts live in the repo, not in chat historygovernance/, tech/
📐 Capability contractsEvery meaningful behavior has a machine-checkable input/output contractcapabilities/*/contract.yaml
📊 Capability budgetsTechnical and semantic limits (files, LOC, deps, responsibilities) - enforcedbudgets: + trellis budget-check
🔍 Evidence graphSource → Claim → Decision → Capability → Test → User validationsources/, ADR evidence:
🗂️ Decision lifecycleADRs with assumptions, review intervals and re-evaluation triggerstech/decisions/
🧩 Extension contractsDirectory-local rules listing the files an extension must registerEXTENSIONS.md, extension-registry.yaml
🖥️ User-facing test cockpitNon-engineers compare expected vs actual output per capability/__capabilities (Phase 2)
🛑 Obligation to not write codeMachine-readable stop conditions; agent proposes split/refactor/ADR insteadgovernance/agent-authority.md
🚦 Quality gatesCI gates: contract, budget, drift, evidence, regression.github/workflows/, quality/quality-gates.yaml
⏳ Technology lifecycleUpgrade & refactor triggers so decisions don't silently rottech/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:

PlatformFile generatedRole
Codex / Jules / Aider / ZedAGENTS.mdNative (canonical)
Claude CodeCLAUDE.mdPointer → AGENTS.md
GitHub Copilot.github/copilot-instructions.mdPointer → AGENTS.md
Cursor.cursor/rules/trellis.mdcPointer → AGENTS.md
Windsurf.windsurf/rules/trellis.mdPointer → AGENTS.md
Gemini CLIGEMINI.mdPointer → 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.md and 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

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 compose engine the CLI uses: copy the tailored AI spec, copy an npx command, or download a .zip starter.
  • ✅ 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.

Ver o original no GitHub

Bom para

Relacionados