AI coding agents are fast at local execution and unreliable at remembering why a project works the way it does. Trellis addresses that gap by putting durable engineering context inside the repository: scoped specifications, task artifacts, per-developer journals, workflow state, and platform-specific agent configuration.
That makes Trellis less like a model or code generator and more like an agent harness. It does not replace Claude Code, Codex, Cursor, or another coding agent. It gives those agents a shared project layer and a repeatable delivery loop.
At the time of this review, the mindfold-ai/Trellis repository had roughly 12.7k GitHub stars—12,662 when checked—and the npm package was version 0.6.7. The project uses the AGPL-3.0-only license. Its current prerequisites are Node.js 18.17 or newer for the CLI and Python 3.9 or newer for the scripts and hooks.
What Trellis stores in the repository
.trellis/ directory holds the stable project context; generated skills, hooks, and host entry files adapt that core to each coding environment.The .trellis/ directory is the stable core across supported coding tools. Four areas matter most:
spec/stores team conventions: directory structure, error handling, testing, component patterns, and other rules that should survive a chat session.tasks/stores active and archived work, including a PRD and separate context manifests for implementation and review.workspace/stores per-developer journals so a later session can recover what happened without reconstructing the entire conversation.workflow.mdand runtime state tell the agent which phase is active and what evidence it should produce next.
Trellis also generates platform-specific skills, subagent definitions, commands, hooks, and entry files such as AGENTS.md. The core artifacts stay the same, but their delivery varies by host. Claude Code, Cursor, and OpenCode expose richer hook and subagent integration; other tools may rely on pull-based context, a prompt file, or an inline main-agent path.
This distinction is important. “Supports 17 platforms” means Trellis ships configurators for 17 environments. It does not mean every environment provides identical session-start events, pre-tool hooks, slash commands, or subagent context injection. The official capability matrix should be reviewed for the exact tools a team uses.
The current four-phase loop
The current Trellis README describes a four-phase workflow:
- Plan —
trellis-brainstormclarifies the task one question at a time and writesprd.md. Research-heavy questions can be delegated totrellis-research. The plan curates which specs and research artifacts belong inimplement.jsonlandcheck.jsonl. - Implement —
trellis-implementworks from the PRD and the selected implementation context. It is instructed not to commit the change. - Verify —
trellis-checkreviews the diff against the task and specs, then runs the relevant lint, type-check, and test commands. It can self-fix small mechanical issues. - Finish — a final check runs,
trellis-update-specpromotes durable lessons into the spec library, and finishing the work archives the task and updates the developer journal.
An older source described spec update as a separate third stage and finish as a fourth. The current documentation folds spec promotion into Finish, after Plan, Implement, and Verify. That is more than naming: the knowledge update is part of closure, not an optional cleanup step detached from verification.
Specs are bootstrapped, then curated
The most consequential correction to older Trellis reviews concerns specification authoring. Trellis no longer expects every team to fill every placeholder entirely by hand. The official README says many teams let AI draft specifications from the existing codebase, then tighten important rules manually. The quick-start documentation also includes a bundled spec-bootstrap skill and an optional template marketplace.
The right mental model is AI draft, team curate:
- Use the codebase to produce a first-pass description of actual patterns.
- Delete generic advice that does not constrain a decision.
- Add concrete examples and counterexamples from the repository.
- Review high-impact rules—security, migrations, API compatibility, testing, error handling—like code.
- Keep the specs versioned and update them when a verified task establishes a better convention.
AI-generated specs are not automatically trustworthy. A model can faithfully document an accidental pattern, copy an anti-pattern that happens to be common, or turn preferences into false absolutes. Trellis provides the structure and update path; the team remains responsible for the standard.
Why context manifests are useful
Large instruction files often fail in two ways: they consume context on every turn, and unrelated rules distract the agent from the current task. Trellis instead uses task-specific JSONL context manifests.
The planning phase selects the relevant material for implementation and checking. An implementation worker might need API conventions, database rules, and the PRD. A reviewer may need those plus testing and error-handling guidance. The two manifests can differ, which helps keep each agent’s context bounded and makes the selection inspectable.
This mechanism does not guarantee lower total token use. Hooks, planning, subagents, checks, and spec updates all cost time and model work. Its value is context precision and repeatability, not free context. Teams should compare end-to-end latency and usage against their current workflow on representative tasks.
Project memory without one giant chat history
Trellis journals record what a developer completed, while task state records what remains active. On hook-backed platforms, session startup can inject identity, Git status, active tasks, spec indexes, and recent journal context. On tools without the same hook surface, an entry skill or generated prelude supplies a fallback.
This is durable memory in the engineering sense: versioned project knowledge plus developer-specific work summaries. It is not a claim that every past conversation is automatically correct or that journal context should override the repository. The current code, tests, and reviewed specs remain the source of truth.
Per-developer workspace directories reduce journal conflicts, while shared specs and tasks remain reviewable through normal pull requests. Teams should still define ownership for spec changes; otherwise, the knowledge base can accumulate contradictions as quickly as a monolithic AGENTS.md file.
Installation and a safe first pilot
Install the current CLI and initialize only the platforms you actually use:
npm install -g @mindfoldhq/trellis@0.6.7
trellis init -u your-name --claude --codexThe generic trellis init -u your-name flow can auto-detect installed platforms. Pinning the npm version makes a team trial reproducible; @latest is convenient for exploration but can change generated templates between machines.
For an existing codebase, use this pilot sequence:
- Initialize Trellis on a disposable branch.
- Let the bootstrap workflow draft a narrow set of specs from real code.
- Have maintainers review and reduce those specs to high-signal rules.
- Choose one medium-sized, reversible feature with clear acceptance criteria.
- Run the complete Plan → Implement → Verify → Finish loop.
- Inspect which files each JSONL manifest selected.
- Intentionally violate one rule and confirm the review phase catches it.
- Start a new session and verify that task and journal recovery are accurate.
- Measure repository footprint, merge noise, runtime, and model usage before expanding adoption.
Codex users need an additional platform check. Current Trellis documentation says Codex uses an AGENTS.md prelude, skills and agent files, and a UserPromptSubmit hook; hook support must be enabled and reviewed in compatible Codex releases. Subagent context injection is not identical to Claude Code’s PreToolUse path, so parity should be tested rather than assumed.
Trade-offs teams should evaluate
Repository weight
Trellis generates more than a single instruction file. Exact file counts vary by version and selected platforms, so an old “152 files” result should not be treated as a fixed product property. The meaningful question is whether those generated files stay stable, reviewable, and useful enough to justify their maintenance cost.
Platform variance
The same .trellis/ core can be shared broadly, but automation depth varies. Some platforms have full session and subagent hooks; others use skills or inline execution. A mixed-tool team should test its least-capable required platform first.
Spec quality and governance
Poor specs scale poor decisions. Teams need reviewers, ownership, deprecation rules, and a way to resolve conflicts between written standards and working code.
Workflow overhead
Planning, isolated implementation, independent checking, and spec promotion are valuable for consequential work. They can be excessive for a one-line fix or disposable prototype. Trellis’s current quick-start says small inline tasks do not have to become Trellis tasks; use that escape hatch deliberately.
License
Trellis is licensed AGPL-3.0-only, not MIT or Apache-2.0. Organizations with distribution, modification, hosted-service, or proprietary integration concerns should have the intended use reviewed against the license before standardizing the tool. This is a governance check, not a reason to avoid the project automatically.
Who should adopt Trellis?
Trellis is most compelling for a long-lived repository where multiple people or coding agents repeatedly need the same architectural knowledge. It is particularly relevant when the team has already outgrown one large AGENTS.md or CLAUDE.md, when task context needs to be reviewable, or when sessions frequently lose the reasoning behind local conventions.
It is less compelling for a small prototype, a one-person script, or a repository whose conventions are still changing faster than anyone can curate them. In those cases, a concise instruction file plus normal tests may be the simpler and more reliable harness.
The core Trellis proposition is not “AI remembers everything.” It is “the repository carries the right memory forward.” That proposition succeeds only when specs are curated, tasks are closed honestly, checks are meaningful, and each platform’s integration is verified in practice.