---

AI coding agents don't fail from lack of intelligence. They fail from execution bottlenecks:

• Exploratory Context Tax: Agents discover and read internal engine scripts, consuming 5+ minutes and thousands of tokens before writing any product code.
• The "Ghost Fleet" Illusion: Multi-agent frameworks create worktree directories without spawning detached processes, leaving a single agent hopping between folders sequentially.
• Brittle Write-Set Collisions: Rigid path partitioners reject natural cross-component composition in modern full-stack codebases.
• Unintegrated Staging Merges: Code merged without cross-module typechecking introduces silent interface breakage.

Trellis resolves all four with an isolated engine, a single root CLI, real tmux parallel execution, and a 3-layer mechanical verification gate.

npx create-trellis

Zero runtime dependencies. Native Git worktrees. Works out-of-the-box with Google Antigravity, Claude Code, Cursor, Windsurf, and GitHub Copilot.

---

⚡ The 4-Step Lifecycle

# 1. Plan & Scaffold (Creates task DAG & docs/implementation_plan.md in < 15s)
./trellis new "Build Apple-native PWA storefront with Motion.dev & Aceternity UI"

# 2. Parallel Dispatch (Spawns concurrent worker processes in detached tmux sessions)
./trellis dispatch

# 3. Mechanical Gates & Staging Integration (Runs as workers complete)
./trellis gate <task_id>                  # Tier-1 Floor Gate (Positive AST Delta, clean syntax)
./trellis integrate <task_id> <branch>    # Tier-2 Staging Gate (Serial merge + global typecheck)
./trellis verify <repro_script>           # Tier-3 Adversarial Oracle (Exit 0 verification)

# 4. Release & Sign-Off
./trellis merge-all                       # Fast-forward master release
./trellis walkthrough                     # Auto-render docs/walkthrough.md

---

🏛️ System Architecture

Why Schedulers Beat Swarms

Traditional multi-agent swarms rely on LLM-to-LLM chatter over shared chat contexts. In practice, conversational coordination quickly suffers from context drift and unverified hallucinated merges.

Trellis replaces conversational negotiation with deterministic Helm-level scheduling:

trellis                           → Single executable Helm CLI (new, dispatch, integrate)
AGENTS.md                         → Operating distro standards & engine isolation rules
.agents/
└── rules/
    ├── GROUNDING.md              → 4 cognitive invariants
    ├── IDENTITY.md               → Project boundaries & test commands
    └── FLEET.md                  → Multi-agent verification standards
.trellis/                         → Isolated engine internals (Zero agent exploration)
├── compiler/
│   └── conductor.py              → DAG compiler, state engine & doc generator
├── gates/
│   ├── floor_gate.py             → Tier-1 Floor Gate (Positive AST Delta)
│   ├── integration_gate.sh       → Tier-2 Staging Integration Gate
│   └── adversarial_oracle.py     → Tier-3 Adversarial Oracle
└── schema/
    └── orchestration_state.json  → Single source of truth state machine

---

🛡️ The 3-Layer Verification Sandwich

Every pull request or task branch generated by fleet workers passes through three mechanical verification tiers before touching master:

1. Tier-1 (Floor Gate): Guarantees positive syntactic progress ($|\Delta\text{AST}| > 0$), checks clean syntax, and logs advisory write-set domain crossings.
2. Tier-2 (Staging Integration Gate): Merges the worker branch into an isolated staging/integration tree and executes full project typechecks (tsc --noEmit, mypy, cargo check).
3. Tier-3 (Adversarial Oracle): Executes candidate reproduction test scripts to mathematically prove bug resolution (Exit 0).

---

🚀 Quickstart

Interactive (5 seconds)

npx create-trellis

Prompts for project name, parallel worker count, and test command, then installs the Trellis engine and rules.

Manual (Clone Template)

npx degit chama-x/Trellis/template .

---

📊 Comparison Matrix

Feature	Raw Prompts	Chatty Swarms (CrewAI / AutoGen)	Trellis
Agent Startup Time	~1-2 min	~3-5 min (context chatter)	< 15 seconds
Worker Parallelism	None	Simulated / API-bound	True tmux Processes
Workspace Isolation	Dirty tree collisions	Memory leaks	Git Worktrees
Write-Set Philosophy	Unconstrained	Hallucinated scope	Advisory + Staging Gates
Merge Verification	Manual	Unverified	3-Tier Mechanical Gate
Engine Exploration Overhead	High	Severe	Zero (.trellis/ isolated)

---

🌐 Universal Portability

Trellis manages no closed cloud subscriptions, runs no opaque background servers, and requires no specialized language runtime beyond Bash and standard Python.

Whether your team codes with Antigravity, Claude Code, Cursor, Windsurf, or Copilot, every agent executes through the exact same deterministic CLI.

---

Contributing · Code of Conduct · Changelog · License