Trellis: Keeping Specs, Tasks and Project Memory in the Repository
Purpose, mechanisms, getting started and boundaries
Source: mindfold-ai/Trellis · mindfold-ai
User Problem
Positioning and task fitCoding agents can produce changes quickly, yet a new session may lack team conventions and earlier decisions. Trellis stores specifications, task context and journals in the repository, organizing work around planning, implementation, verification and completion. It is a project engineering layer: the model reasons while Trellis prepares and preserves working context.
- Maintain one project across sessions
- Share conventions and acceptance criteria
- Preserve workflow across coding agents
Product Mechanism
Capabilities and execution- Reviewable specificationsConventions live in .trellis/spec/ and relevant context is injected for the task. Instead of repeatedly copying a long prompt, a team can review rule changes in Git, remove obsolete requirements and trace implementation decisions. Source
- Tasks carry implementation and review contextTask directories hold the PRD, status and context lists for implementation and checking. Both the requested change and its verification basis can be handed over together rather than scattered across chat history. Source
- Journals preserve continuityWorkspace journals record earlier work, with separate developer journals and shared specifications. Persistence is only as useful as its contents: an unreviewed mistake can also propagate to the next session. Source
- Verify before promoting lessonsThe documented flow separates Implement from Check, then promotes reusable lessons during Finish. The implementation subagent does not automatically commit, so verification and version control still need explicit ownership. Source
Workflow
Start with a small task- Prepare the environmentCheck README requirements for Node.js and Python, and install the CLI in a repository where changes can be reviewed. Record existing instruction files before initialization.
- Initialize the platforms you useRun trellis init for the platforms and developer identity you actually use. Inspect generated directories and establish the essential build commands, conventions and test rules.
- Converge on a PRDDescribe a bounded change, clarify requirements and inspect the PRD and context lists. Acceptance criteria should describe behavior rather than vague improvements in appearance or elegance.
- Verify and finishReview the diff and lint, type-check and test evidence before finishing the task and updating journals. Promote reusable lessons, not temporary exceptions, into permanent rules.
The trial sequence and checks are editorial guidance. Entry commands follow official documentation; this project was not executed for the article. Source
Official entry example
npm install -g @mindfoldhq/trellis@latest
trellis init -u your-nameComplete the prerequisites above first. Examples contain no real credentials.
Limits and Boundaries
Constraints and selection| Boundary | Meaning | Suggested action |
|---|---|---|
| Initialization is not finished configuration | Generated files provide structure; project standards still need maintenance. Source | Review AI-drafted specifications before the team relies on them. |
| Portability is not identical behavior | Hosts differ in hooks, skill activation and generated integration files. Source | Check the supported-platform guide for the actual host. |
Scroll horizontally to view the full table
Trellis suits projects with repeated handoffs and shared standards. For a disposable script, maintaining specifications and journals may cost more than it saves.
How to Evaluate Adoption
Trial scenario and verificationStart with an API input-validation fix. Put invalid-input behavior in the PRD, relevant routes and error conventions in implementation context, and regression tests and the API contract in review context. After completion, ask a new session why that validation approach was chosen. Finding the answer in tasks and journals demonstrates useful project continuity.
Check directory placement, a readable task PRD, actual execution of verification commands and updated journals after finishing. A model statement that checks passed is not test output.
Evidence: Pinned README · Current repository。
Source fetched (UTC): 2026-11-02T07:26:37.520Z；snapshot commit: f089cb328607。The source date denotes the repository snapshot commit, not the project’s original launch.