Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.trytrellis.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Appendix F: FAQ

​
Getting started & upgrading

​
Q1: I’m used to running /trellis:start at session boundaries — what now?

Type /trellis:continue instead — it gets you the same thing. The context the old /trellis:start injected explicitly — current developer identity, git branch and status, active task, list of active tasks, workflow.md phase rules, spec index, recent journal summaries — is now injected automatically by the SessionStart hook on every new session (Claude Code, Cursor, OpenCode, Gemini CLI, Qoder, CodeBuddy, Copilot, Droid, Pi Agent, plus Codex with features.hooks = true and one-time /hooks approval; Codex < 0.129 uses the legacy codex_hooks = true). Just describe your task. When you want to re-orient the AI mid-session or push it to the next workflow step, type /trellis:continue. It reads task state + workflow.md and decides what to do. On platforms without a SessionStart hook (Kilo, Antigravity, Windsurf), still run /trellis:start or the platform’s start workflow at session start.

​
Q2: 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. Open a Trellis-enabled AI session, or run the platform’s start workflow if it has no automatic session injection; 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.

​
Q3: What’s the scratch option in trellis init template selection?

scratch means “minimal template”: when picked, trellis init writes a small set of empty / placeholder files (basic directory skeleton + index.md stubs) and lets the AI fill them in based on your actual code. Use it when no built-in template fits your stack, or when you want a clean slate for skills like cc-codex-spec-bootstrap to populate.

​
Q4: How do Windows users install Trellis?

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

​
Q5: 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.

​
Q6: Upgrading from 0.4.x to 0.5.0 — what’s the safe sequence?

Always pass --migrate for major bumps. 0.5.0 has a hard gate: trellis update exits 1 with MIGRATION REQUIRED unless you pass it. Without the gate, old behavior silently skipped rename / delete migrations and left a half-migrated state. 
trellis update --migrate --dry-run   # preview
trellis update --migrate             # apply; modified files prompt before changes
trellis update                       # verify: should say "Already up to date"
Every update creates a timestamped backup at .trellis/.backup-* first; locally edited files go through hash check and get a Modified by you prompt (skip / overwrite / abort).

​
Q7: trellis update shows 0.4.0 → 0.4.0 and nothing actually upgraded. What’s wrong?

Upgrade is two steps for two layers: 
npm install -g @mindfoldhq/trellis@beta     # 1. upgrade the CLI itself
trellis update --migrate                  # 2. sync the project to the CLI's current version
trellis update only brings the project up to the CLI’s version. If the CLI is still 0.4.0, the project can only reach 0.4.0. Bump the global CLI to @latest first, then run trellis update --migrate.

​
Core concepts

​
Q8: 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)

​
Q9: 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.

​
Q10: What’s the role of index.md in .trellis/spec/? Is it just a directory listing?

Roughly yes — index.md per spec layer is a one-line catalogue of what specs exist plus a short reason for each. The brainstorm/research phase reads only the index.md (paths + reasons), then writes the relevant entries into implement.jsonl / check.jsonl. The actual spec body files (error-handling.md, etc.) are loaded only when the JSONL lists them. So index.md is the discovery surface — keep it short, one line per spec, and put the body in the spec file itself.

​
Q11: 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.

​
Q12: What’s the difference between /trellis:start and /trellis:continue?

/trellis:start is for fresh sessions on a platform without auto-injection (Kilo / Antigravity / Windsurf). It loads the SessionStart context report explicitly. On platforms with the SessionStart hook, you don’t need it. /trellis:continue is for advancing the active task to the next workflow step. Use it at any phase boundary, or when you don’t know what to do next — the AI reads task state + workflow.md and picks the next step. Mental model: start opens a window onto the project; continue moves the cursor forward inside that window.

​
Q13: 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 holds the workflow rules: 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).
  • Eight platforms upgraded to agent-capable: Cursor / OpenCode / Gemini CLI / Qoder / CodeBuddy / Copilot / Droid / Pi Agent all got sub-agents and hooks or extension-backed equivalents; .trellis/ core is unchanged across 14 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 0.5.0 breaking-change changelog.

​
Q14: /trellis:record-session is gone. What replaces it?

Absorbed into /trellis:finish-work in 0.5.0 — same journal-writing behavior, plus task archive and quality-gate reminders. Update aliases or external scripts that referenced record-session. Other commands removed in 0.5.0 with similar replacements: /parallel (use platform-native worktree), /onboard / /create-command / /integrate-skill (low usage; replaced by skill routing or cc-codex-spec-bootstrap), /check-cross-layer (merged into check).

​
Q15: Aren’t sub-agents expensive in tokens? Is this architecture more wasteful?

Sub-agents are tools the main agent calls: each invocation is an isolated subtask that runs and returns its conclusion. Because the main agent’s context window stays clean, the overall session uses LESS token, not more, compared to “main agent does everything end-to-end and its context grows monotonically.” The trade-off is that each sub-agent has its own small context for implementation or review, but the clarity from isolation outweighs that overhead. For very short sessions (small fixes), the isolation benefit is small — let the main agent handle it directly without dispatch.

​
Platforms & multi-tool

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

Yes. Cursor now ships Trellis hooks, skills, and sub-agents. SessionStart injects the workflow at conversation start, UserPromptSubmit adds workflow-state breadcrumbs, and sub-agent context injection passes the right JSONL content into trellis-implement / trellis-check before they run.

​
Q17: 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 and Pi Agent, re-run: 
trellis init -u your-name --claude --pi
The .trellis/ directory (spec, workspace, tasks) is shared across all tools; only the .{platform}/ directory is new. If you don’t want to type flags, just run trellis init to enter the interactive picker — it offers to add a new platform, add a new developer, or reinitialize everything.

​
Usage & workflow

​
Q18: On a huge legacy repo, won’t injecting specs blow up the context window?

No, because Trellis doesn’t inject all specs every turn. Each spec covers one topic (error-handling.md, database.md, testing.md) so files stay small. During brainstorm / research, the AI picks only the specs relevant to the current task and writes their paths into implement.jsonl / check.jsonl; the hook injects only those when dispatching trellis-implement / trellis-check. The main session reads spec index pages (paths only). A 500K-line repo with 50 spec files but 4 loaded per task behaves like a 4-file repo to the AI. If specs still bloat context, the spec files themselves are too long — split them.

​
Q19: I finished a task but the result is wrong / I want to add scope. What now?

Tell the AI in plain language: task X doesn't meet the requirement, redo it or extend X to also cover Y. You don’t need to recreate the task unless the scope shift is huge. If it is, run task.py create to start a new one and reference the old prd.md as background. Don’t repair a task by editing files manually mid-flight — let the AI re-read the PRD and produce a new diff under the same task.

​
Q20: When I run multiple tasks in parallel, can their files contaminate each other?

Each task has its own directory under .trellis/tasks/<MM-DD-slug>/ with its own prd.md, research/, implement.jsonl, check.jsonl. Sub-agents only read the JSONL listed for the active task, so cross-task spec injection is scoped automatically. Per-developer journals live under .trellis/workspace/<name>/, also isolated. What’s NOT isolated: dead-end exploration notes left inside one task’s research/ will mislead a future re-read of that same task. Recommended habit: when a research file turns out to be wrong, mark it ## DEPRECATED at the top instead of leaving it ambiguous.

​
Q21: Do I have to commit code before running /trellis:finish-work to archive / record?

/trellis:finish-work writes a session journal that includes the commit hash, so commit comes first. If you only want to archive a task without recording a journal, run task.py archive <task-name> directly — no commit required. Recommended sequence: Phase 3.4 commit → /trellis:finish-work (archives + writes journal).

​
Q22: Each task creates three commits (work + archive + journal). Isn’t that redundant?

The three commits come from different layers: your own work commit (Phase 3.4); task.py archive writes a chore(task): archive ... commit; add_session.py writes a chore: record journal commit. Squash on merge is the recommended way to collapse them into one PR commit. If you’d rather keep them as separate history entries, the work commit is the meaningful one — archive and journal are housekeeping and trivial to filter via git log --invert-grep -E '^chore'.

​
Q23: AI sometimes skips the Trellis flow and just writes code. How do I pull it back?

Two pressure points:
  1. Re-state the rule explicitly. Stop. We use Trellis. Run brainstorm and create a task first. AI calibrates to the boundary you actually enforce, not the one you wished for.
  2. Strengthen the workflow-state hook. inject-workflow-state.py injects a per-turn breadcrumb based on current task status. If your team sees frequent skipping, fork workflow.md to add stricter [workflow-state:no_task] text that refuses Execute without an approved PRD.
This is a known cross-model failure — Claude, GPT, DeepSeek all do it. The framework reduces it but doesn’t eliminate it. Phase boundaries still need a human in the loop.

​
Q24: How do I use Trellis on a monorepo (frontend + backend in the same repo)?

trellis init detects monorepo and creates per-package spec directories. By default, init writes one frontend/ and one backend/ spec block. For more granular packages, organize specs as .trellis/spec/<package>/backend/ etc. and reference them from the parent index.md. The brainstorm/research phase picks the relevant package’s specs into implement.jsonl based on the paths the task touches. Reverse case: pure-frontend or pure-backend single-repo projects — trellis init detects via language signals (go.mod / package.json / *.csproj / etc.) and only creates the matching directory; it won’t force-create both.

​
Q25: How do I share knowledge between separate tasks (task A’s lessons flowing into task B)?

Three layers:
  • Spec — when task A teaches you something durable about the codebase or conventions, run /trellis:update-spec to write it into .trellis/spec/. Future tasks pick it up automatically when their implement.jsonl lists it.
  • Workspace journal — .trellis/workspace/<name>/journal-*.md carries session-level context across tasks for the same developer. SessionStart surfaces recent journals to the AI.
  • Task PRD reference — task B’s prd.md can explicitly link to task A’s prd.md or research/ files; the brainstorm phase pulls them as context.
What does NOT flow automatically: research notes inside task-A/research/ are NOT auto-injected into task B. Durable findings → lift to spec. Task-specific findings → leave them in the source task, reference explicitly.

​
Q26: Is there TDD support?

Not as a built-in workflow yet. The current default is implement → check (post-hoc), not test-first. A TDD skill template is on the roadmap for a future 0.5.x release. In the meantime, write TDD instructions into your project’s .trellis/spec/<package>/testing.md so the implement / check sub-agents follow the right test patterns. Yes. Several users have moved Trellis to long-form writing by treating prose like code: prd.md defines what the piece argues and what’s out of scope; .trellis/spec/ holds voice / structure / citation rules; implement.jsonl lists writing-agent context; check.jsonl lists editorial and fact-check rules; journal-*.md records decisions. Reported gains: 20-30% faster output for the same quality bar, mostly from removing the “remind the AI of the style guide” tax per session. Trellis won’t help with creative spark — it helps with consistency and not re-explaining yourself.

​
Team collaboration & cross-project

​
Q28: Will multiple developers using Trellis cause conflicts?

Per-developer and per-session state is isolated (workspace/{name}/, .developer, .runtime/sessions/<session-key>.json). 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.

​
Q29: What in .trellis/ should be tracked by git? What’s ignored?

Track everything by default. .trellis/ is designed as a team-shared directory:
  • .trellis/spec/ — shared conventions, tracked
  • .trellis/tasks/ — task PRDs, research, context, tracked
  • .trellis/workspace/<name>/ — personal journals, tracked (teammates can read each other’s progress)
  • .trellis/workflow.md, scripts/ — tracked
Already gitignored by .trellis/.gitignore: .developer, .current-task, .runtime/, .backup-*, *.tmp, *.pyc — runtime / personal pointer files. If you put .trellis/ itself in your project .gitignore, AI can still read it (filesystem works), but you lose the team coordination layer that is the whole point.

​
Q30: My teammates don’t all use Trellis. Will my changes (especially AGENTS.md) cause problems for them?

The conflict surface is small. AGENTS.md is the only file Trellis writes that non-Trellis users typically also touch; Trellis writes a managed block delimited by <!-- TRELLIS:START --> and <!-- TRELLIS:END --> markers, so content outside the block is preserved. If teammates don’t want Trellis content at all:
  • Skip the AGENTS.md write entirely — .trellis/ doesn’t depend on it to function.
  • Add .trellis/, .codex/, .agents/, .claude/ etc. to your local .git/info/exclude (per-clone, not committed) to keep Trellis as your private layer.
  • Or commit .trellis/spec/ only and gitignore the platform .{name}/ directories at repo level.

​
Q31: Do I have to re-write specs from scratch for every new project? How do I reuse rules across projects?

You don’t. Maintain your team’s shared rules as your own spec template repo, then pull them when starting new projects: 
trellis init -r [email protected]:your-org/trellis-spec-template.git
Supports GitHub / GitLab / Bitbucket / self-hosted GitLab (HTTPS / SSH). Coding conventions live in one place, distributed via your git infrastructure — no copy-pasting per project.

​
Customize & interop

​
Q32: Can I use other plugins / skills / MCPs (Superpowers, Context7, custom MCPs) alongside Trellis?

MCP — yes. MCPs are tools the model calls; they don’t change Trellis’s workflow injection. Heavy plugins / skill packs that own the workflow (e.g., Superpowers) — likely conflict. Trellis injects workflow via SessionStart hook + <workflow-state> breadcrumbs; another framework doing the same thing fights for the same context slot. Pick one workflow framework per session. Light single-purpose skills (one-off helpers, custom slash commands) — fine to run alongside. If you really need them to coexist (e.g., you want to pull in one specific skill from Superpowers), see Q34 (how to customize via trellis-meta) — that skill rewrites Trellis’s workflow so it doesn’t fight with your other framework.

​
Q33: Can Trellis coexist with Superpowers / OpenSpec / OMO / similar frameworks?

Not recommended. These are all workflow frameworks (not just skill collections); each has its own injection mechanism, trigger rules, and phase definitions. Running two workflow frameworks in the same session means:
  • The AI gets two sets of phase prompts and picks probabilistically — output becomes unpredictable
  • Hook / SessionStart / breadcrumb mechanisms overwrite or stack on each other, bloating context
  • Debugging gets harder because you can’t tell which framework caused a given behavior
One workflow framework per session. Switch frameworks in a fresh session, don’t mix them. If you want one specific skill from another tool (not its whole workflow), see Q34 — use trellis-meta to fold that skill into Trellis’s flow, but don’t run two phase controllers in parallel.

​
Q34: How do I customize Trellis to match my team’s habits?

Use the trellis-meta skill. It’s purpose-built for forking Trellis: remove or add phases (e.g., drop the check phase if it’s slow locally, or add a PRD admission gate / system-test gate), change skill trigger conditions, edit sub-agent prompts, customize workflow-state text — all driven by the skill, which guides you through edits to .trellis/workflow.md and related templates. Install: 
npx skills add mindfold-ai/marketplace --skill trellis-meta
More at docs.trytrellis.app/skills-market/trellis-meta. All edits are markdown — no Python or hook code involved.

​
Q35: Obsidian doesn’t show my .trellis/ directory

Obsidian hides directories starting with . by default. Two fixes. In Obsidian Settings → Files & Links, enable Detect all file extensions and Show hidden files if your version exposes the option. Otherwise symlink to a visible directory and point Obsidian there: 
ln -s .trellis trellis-vault
Separately, MM-DD-<slug>/ task names truncate in Obsidian’s file explorer.

​
Q36: Does Trellis support Chinese workflow / specs / journals?

Yes — the content layer is language-agnostic. Specs, PRDs, journals, and workflow.md are plain Markdown; write them in any language and the AI reads whatever’s there. Trellis CLI output and the default English templates are currently in English, but you can replace template content with Chinese after trellis init (or fork your own template repo, see Q31). Chinese localization for built-in skill prompts is partially shipped and on the roadmap. None of this affects the workflow logic.