Skip to main content

​
Appendix F: FAQ

​
Q1: Should I trigger anything at the start of a session?

On platforms with a SessionStart hook (Claude Code, Cursor, OpenCode, Gemini CLI, Qoder, CodeBuddy, Copilot, Droid — plus Codex if you set codex_hooks = true), context is injected automatically, so the answer is “no, just describe your task”. On platforms without a SessionStart hook (Kiro, Kilo, Antigravity, Windsurf), run /trellis:start (or @trellis:start on Kiro) to load the full context report.

​
Q2: How do I make the AI verify quality before I commit?

That’s what the trellis-check sub-agent does. After the implementation phase, the main session spawns it (or, on platforms without sub-agents, the skill runs inline). It reads the relevant specs, runs lint / typecheck / test, compares the diff against the quality checklist, and self-fixes violations. No external retry loop is involved.

​
Q3: What should I do after trellis-break-loop analyzes a bug?

The skill analyzes the root cause and proposes prevention mechanisms. Route the findings into the trellis-update-spec skill, which writes them into .trellis/spec/. Next time anyone works in that area, the updated spec is injected automatically.

​
Q4: Where is session history stored?

.trellis/workspace/
├── index.md              # Master index across all developers
└── {your-name}/
    ├── index.md          # Personal index
    └── journal-N.md      # Session journal (new file every ~2000 lines)

​
Q5: How detailed should specs be?

Aim for 200-500 lines per file, 20-50 lines per section. Concrete code examples beat abstract rules. Update specs as soon as something is out of date.

​
Q6: Will multiple developers using Trellis cause conflicts?

Per-developer state is isolated (workspace/{name}/, .developer, .current-task). Shared state is .trellis/spec/ and .trellis/tasks/; they go through PR review like any code. Use --assignee when creating a task to avoid collisions.

​
Q7: How do I migrate an existing project to Trellis?

  1. npm install -g @mindfoldhq/trellis@beta
  2. trellis init -u your-name in the project root (auto-creates a bootstrap task).
  3. Run /trellis:start; the brainstorm skill helps fill initial specs.
  4. Manually supplement core specs based on your conventions.
  5. Add .trellis/ and whichever .{platform}/ directories you use to git and commit.
  6. Teammates pull, then run trellis init -u their-name.

​
Q8: How do I update Trellis without losing my customizations?

trellis update --dry-run   # preview
trellis update             # apply
Trellis hashes every template file at install time. Files you’ve modified are detected on update: unmodified files are overwritten; modified files prompt you (overwrite / skip). Use -f to force overwrite or -s to skip globally. For major versions, add --migrate to apply rename / delete entries from the migration manifest. Without --migrate, a breaking manifest will exit with instructions rather than silently renaming files.

​
Q9: Can Cursor users get the same automation as Claude Code?

Mostly. Cursor doesn’t have a SessionStart hook, but .cursor/rules/trellis.mdc is an alwaysApply rule that carries the Trellis prelude into every conversation. Sub-agents don’t exist in Cursor, so the work that would happen in trellis-implement / trellis-check runs inline in the main session instead. Skills are delivered as rule content and matched by Cursor’s rule system.

​
Q10: How do Windows users install Trellis?

All Trellis scripts are Python, cross-platform: 
# 1. Install Node.js 18+ and Python 3.10+
# 2. Install Trellis
npm install -g @mindfoldhq/trellis@beta
# 3. Initialize
cd your-project
trellis init -u your-name
trellis init writes CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 into .claude/settings.json automatically (since 0.5.0-beta.8). That env var keeps the Bash tool’s cwd stable so hook scripts resolve paths correctly on Windows — no manual setup required.

​
Q11: Do I need to reconfigure when I switch between AI coding tools?

No. trellis init with multiple platform flags writes all of them. If you started with Cursor only and later add Claude Code, re-run: 
trellis init -u your-name --claude
The .trellis/ directory (spec, workspace, tasks) is shared across all tools; only the .{platform}/ directory is new.

​
Q12: What’s the difference between a command, a skill, and a sub-agent?

PrimitiveTriggered byTypical use
CommandUser (/trellis:*)Session boundaries (start, finish-work, continue)
SkillPlatform (auto-match)Phase-level workflows (brainstorm, before-dev, check, update-spec, break-loop)
Sub-agentMain session (spawn)Isolated roles (implement, check, research)
See chapters 9–12 for guidance on picking the right primitive.

​
Q13: Are shared skills (.agents/skills/) still a thing?

Yes. The Codex configurator writes all five Trellis skills to .agents/skills/ as a cross-platform shared layer following the agentskills.io standard. Any agent that reads that location (Amp, Cline, Deep Agents, Firebender, Kimi Code CLI, Warp, etc.) picks them up without needing a dedicated configurator.

​
Q14: What changed from 0.4 → 0.5?

The headline changes:
  • Skill-first: brainstorm / before-dev / check / update-spec / break-loop moved from slash commands to auto-trigger skills that the platform matches based on user intent.
  • workflow.md is the single source of truth: Phase definitions, skill routing, and per-turn workflow-state reminders all live in .trellis/workflow.md. Fork the workflow by editing one markdown file — no Python or hook changes needed (see chapter 8).
  • Per-turn workflow-state breadcrumbs: a new inject-workflow-state.py hook fires on every user message and injects a <workflow-state> block driven by the current task’s status, keeping the AI aligned with the Plan → Execute → Finish phases.
  • Three sub-agents replaced six: trellis-research / trellis-implement / trellis-check. dispatch / plan / debug were removed; Ralph Loop and its SubagentStop hook were removed (the check sub-agent owns its retry loop now).
  • Seven platforms upgraded to agent-capable: Cursor / OpenCode / Gemini CLI / Qoder / CodeBuddy / Copilot / Droid all got sub-agents and hooks; .trellis/ core is unchanged across 13 platforms.
  • Multi-Agent Pipeline, /parallel, worktree.yaml removed: native worktree support in modern agent CLIs replaces them.
  • Forced migration gate: breaking releases require trellis update --migrate and exit with instructions instead of silently leaving half-migrated files.
For the full list, read the changelog for v0.5.0-beta.0.