Skip to main content

​
General

Skills are optional — the AI might skip them, leading to inconsistent quality. Trellis enforces specifications through injection. Every session gets the specs whether the AI “feels like it” or not.
AI typically generates specs from your instructions. But you should contribute when you have architectural insights that AI can’t figure out on its own — things like “we always use this error format because of X legacy reason” or “this pattern exists because of Y constraint.”
Those formats load all content every time. If you have 50 pages of specs, every session reads all 50 pages.Trellis uses layered architecture with context compression. JSONL files specify which specs to load for which task. Your auth feature loads auth specs. Your UI component loads frontend specs. Less noise, more signal.
No. Each team member has an isolated workspace at .trellis/workspace/{name}/. Your journals are yours. Your teammate’s journals are theirs.Specs are shared, which is the point — everyone follows the same conventions.
Use /trellis:record-session to have AI write summaries to journal files. On the next session start, it reads recent journals and git info to restore context.It’s not magic memory. It’s explicit journaling. You control what gets remembered.
The core systems (specs, tasks, workspace) work. You read spec files and follow them.Hooks: Cursor now supports hooks natively, but Trellis hasn’t implemented Cursor hook support yet (planned for future). For now, you’ll need to manually reference spec files at session start.Multi-Agent (same dir): Limited support, requires manual coordination.Multi-Session (worktree isolation): Not supported.

​
Specs

Short enough to skim in 30 seconds. If it takes longer, split into multiple files.The AI reads the whole spec but pays less attention to each part when specs are long.
Common causes:
  1. Too vague — “Use good error handling” means nothing. Add specific patterns with code examples.
  2. No examples — Show actual code. AI learns better from examples than descriptions.
  3. Outdated paths — If you reference files that don’t exist, the spec becomes confusing.
  4. Conflicting rules — Two specs say different things. Pick one.
Test it: new session, ask for code the spec covers, check if rules are followed.
Yes. Documentation style, commit message format, PR templates, API design patterns — anything you want consistent.

​
Tasks & Workspace

No. Tasks help when you need tracking and context isolation. Quick fixes don’t need a task. Multi-day features benefit from one.
Session runs without task-specific context. Specs still load from defaults, but the AI won’t know your PRD or task-specific files.For task-specific work, use /trellis:start to begin a session.
Each line specifies a file to include:
{"file": ".trellis/spec/backend/index.md", "reason": "Backend coding standards"}
{"file": "src/api/users.ts", "reason": "API implementation context"}
Different agents get different files. Implement agent might need more context than check agent.

​
Multi-agent

No hard limit, but practically:
  • API credits (each agent uses tokens)
  • Your ability to review output
3-5 agents is manageable. More gets hard to track.
Depends on the mode:
  • Multi-Agent (same dir): Agents share the same directory and can conflict. Plan tasks to avoid file overlap.
  • Multi-Session (worktree): Each agent works in an isolated Git worktree. No conflicts during development, resolve when merging PRs.

​
Troubleshooting

Trellis works in the background. No UI changes.Verify:
  1. .trellis/ directory exists
  2. .claude/settings.json has hook configs
  3. Start a session — specs should appear in context
Several possible causes:
  1. Specs not loaded: Check file paths in .trellis/spec/ and JSONL context files
  2. Context too long: AI may “forget” specs in long conversations. Start fresh session or remind it
  3. Spec clarity: More specific specs work better than vague ones
Trellis improves consistency but isn’t a silver bullet. AI still makes mistakes.
Update the CLI:
npm install -g @mindfoldhq/trellis@latest
Then update your project:
trellis update
This only touches unmodified files. Your customizations stay intact. A timestamped backup is created automatically at .trellis/.backup-{timestamp}/ before any changes.When there are breaking changes (like directory restructuring), run with --migrate:
trellis update --migrate
This executes file migrations — renames and deletes old files to match the new structure. Modified files prompt for confirmation before migrating.