trellis

Opinionated project scaffolder and validator for the AI-coding era.

What is trellis?

trellis turns your methodology into an executable CLI. You and your AI agents scaffold, extend, and validate projects from the same opinionated playbooks — so structure stays consistent whether a human or an agent writes the code.

• Three built-in playbooks: cli-tool / b2b-saas / ai-rag-platform
• trellis new bootstraps a new project through a short interview
• trellis add extends an existing project with idempotent fragments
• trellis check / trellis doctor enforce architecture rules and doc–code consistency

Quick start

npm i -g @woghks096/trellis
trellis new my-project

One-off (no global install):

npx @woghks096/trellis new my-project

Commands

trellis new <dir>           # Interview → match playbook → scaffold + .trellis/spec.json
trellis add <type> <name>   # Add a fragment (idempotent, multi-slot patch)
trellis remove <type> <name> # Remove a fragment (reverse of add, idempotent)
trellis list [type]         # Browse available fragments (--json for scripting)
trellis upgrade [dir]       # Migrate project to the latest trellis (slot inserts + spec.json bump)
trellis check <dir>         # Detect layered-architecture violations
trellis doctor <dir>        # Check doc / code / playbook consistency

All commands support --json for AI / script consumption.

Fragment Patches

Fragments extend your project in two ways:

• Block-style markers — Templates declare // trellis:slot:<name>:start/end blocks where fragment entries are inserted (idempotent by entryKey).
• AST patches (P15) — Fragments with astPatches use ts-morph selectors (arrayPush, objectKey, importAdd) to update exports without markers. Enables external fragment catalogs without modifying base templates.

Both mechanisms coexist — a single fragment can use markers + AST patches together.

Why

Predictable quality matters most when you code with AI agents. Instead of asking humans and agents to re-interpret methodology documents every time, trellis makes the rules executable:

• One CLI command reproduces the same structure every time
• Architecture violations are caught automatically (trellis check . passes on this repo itself)
• Methodology becomes self-validating, not just documented

Status

v0.12.1 on npm — L5 maturity (public-adoption gate), L6 enabling tech in place.

P0–P15 complete: scaffolding, interview, generator, validator, doctor, trellis add (fragment + multi-slot patch), trellis remove (idempotent reverse of add — round-trips), trellis list (list / detail / --json), trellis upgrade (migration manifest, idempotent slot inserts, --dry-run/--force), cli-tool dogfooding fragments (command + service-module), and the ts-morph AST patch system (arrayPush / objectKey / importAdd — marker-free, coexists with block markers). All commands include --json, actionable error hints, and doctor 8-rules.

release-please automates version bumps on feat:/fix: commits (version-constant sync via extra-files); npm publish runs through Trusted Publishing (OIDC + provenance).

Roadmap: docs/plans/

Supported playbooks

| Playbook | Description | |---|---| | cli-tool | Single-binary CLI — this repo follows it | | b2b-saas | Auth + multi-tenant SaaS (sidebar + authed route group) | | ai-rag-platform | Document upload + RAG + LLM pipeline (sidebar included) |

Development

npm install
npm run build
npm run test
npm run lint

Korean version

한국어 README →

License

MIT — see LICENSE.