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.
Stable promotion of 0.5.0-rc.6 with no new src/ changes. v0.5.0 is a breaking release from 0.4.x — skill-first architecture, 7 platforms upgraded to agent-capable, workflow.md as the single source of truth for the workflow.
/start is no longer a required entry point. Just describe what you want in natural language — you’re already in the Trellis workflow. /continue <what you want to do> works as an explicit kickoff if you want it. If you’d rather manually start a session before chatting, /trellis:continue now serves as the kickoff command in place of /start. See the “/continue command” section below.Codex users — beta-feedback fix in 0.5.0:
multi_agent_v2 default-on (rc.5) — .codex/config.toml template writes the feature block instead of leaving it commented. The min_wait_timeout_ms = 480000 (8 min) wait() floor stops the parent thread from busy-polling subagent status. Requires Codex CLI ≥ v0.128.0 — older Codex will fail with Error loading config.toml: data did not match any variant of untagged enum FeatureToml in features.multi_agent_v2.
Known Codex upstream issues (not fixable from Trellis):
- Hook context rendered in terminal (#191) — Codex prints SessionStart hook context to the terminal on every turn. No toggle to suppress it for now (the Codex desktop app avoids this).
- Sub-agent startup hangs on a slow / failing MCP server — sub-agent init can stall waiting on an MCP that never returns. Reported since Codex
multi_agent_v1, still present in v2.
Architecture
Skill-first templates
5 commands migrated to auto-triggered skills:
before-dev / brainstorm / break-loop / check / update-spec
Commands and skills consolidated to packages/cli/src/templates/common/ (single source — drift across N platform copies eliminated). /start, /continue, /finish-work remain as user-invoked slash commands.
workflow.md as single source of truth
The workflow definition lives in .trellis/workflow.md:
- Phase 1 / 2 / 3 step bodies (AI reads instructions from here)
[workflow-state:STATUS] tag blocks for per-turn breadcrumb content- Skill routing table
task.py 16-subcommand reference (lifecycle / context / metadata / hierarchy / PR)
Fork the workflow = edit one markdown file. No Python, no hook code, no template regeneration.
/continue command
/continue is intra-task continue, not cross-task. It eliminates the user’s need to learn the Trellis workflow.
Before: the user manually picks the next slash command at each step — brainstorm writes PRD → discuss → tell AI to write implement.jsonl → dispatch sub-agent → check → check-cross-layer → finish-work → record-session. The learning burden is on the user.
After:
- Natural-language conversation enters brainstorm, creates the task
- After planning, AI confirms PRD with you; type
continue once you’re OK
- AI knows the next step is curating
implement.jsonl; reconfirms when done
- You
continue — AI dispatches sub-agents for implement + check
- You
continue — AI runs update-spec
- You
continue — AI commits + runs finish-work
Just natural language + continue — no workflow to learn, no slash commands to memorize.
Mechanism: /continue reads task.json.status + artifact state (prd.md, implement.jsonl curation) and loads the matching step’s how-to via get_context.py --mode phase --step X.X. Also handles post-compact recovery, new-session resume on an in_progress task, and cases where AI is unsure of the current position.
Session-scoped task state: parallel windows no longer stomp each other
The active-task pointer moved from the global .trellis/.current-task file to per-session .trellis/.runtime/sessions/<context-key>.json.
| Old | New |
|---|
Single global .current-task file | One session file per host session |
Parallel windows: window A’s task.py start clobbers window B | Each window has its own active task; no interference |
| Bootstrap / joiner tasks wrote the global pointer (polluting it) | Bootstrap / joiner skip the pointer; PRD instructs AI to start from a session with Trellis identity |
TRELLIS_CONTEXT_ID via CLAUDE_ENV_FILE; Codex uses CODEX_SESSION_ID / CODEX_THREAD_ID; Cursor uses beforeShellExecution tickets; OpenCode uses a Bash command prefix; Pi injects into Bash and nested pi --mode json runs.
Joiner onboarding: new developer cloning an existing Trellis project
trellis init now three-way dispatches based on .trellis/ × .trellis/.developer presence:
| Project state | Task |
|---|
No .trellis/ | Creator bootstrap (existing path) |
.trellis/ exists, no .developer | Joiner (new): 00-join-<slug> |
| Both exist | no-op |
.developer is gitignored — clean per-checkout signal. workspace/<name>/ can’t be used because it’s committed to git.
Bootstrap and joiner PRDs are rewritten as AI-facing instructions (no longer user-facing “Welcome, do X” docs): runtime-mechanics explainer (SessionStart hook, <workflow-state> tag, implement/check sub-agents, jsonl manifests) and a suggested opening line. Same content, much smoother first-session UX.
Qoder, CodeBuddy, Factory Droid, Cursor, Gemini CLI, Kiro, GitHub Copilot — from commands-only to full sub-agent + hook integration.
| Layer | Implementation |
|---|
| Sub-agent defs | Native format per platform (Claude-like Markdown, Kiro JSON, Gemini settings.json, Copilot agent.md, …) |
| Hooks | shared-hooks/ Python scripts (session-start, inject-subagent-context, statusline) + per-platform output adapter |
| Claude Code | Migrated from 1,435-line proprietary set to shared-hooks |
Sub-agent context injection: class-1 hook vs class-2 pull-based
| Class | Platforms | Mechanism |
|---|
| Class-1 | Claude / Cursor / OpenCode / Kiro / CodeBuddy / Droid | Hook-based push: SessionStart / inject-subagent-context rewrites sub-agent prompt |
| Class-2 | Codex / Copilot / Gemini / Qoder | Pull-based prelude: sub-agent definition reads .current-task + prd.md + implement.jsonl |
Per-turn workflow breadcrumb
inject-workflow-state.py fires on every user prompt (8 platforms via UserPromptSubmit; OpenCode via Bun plugin chat.message). Injects ~200-byte <workflow-state> block keyed on task.json.status (no_task / planning / in_progress / completed). Tag content pulled from workflow.md [workflow-state:STATUS] blocks.
SessionStart payload restructure
| Section | Before | After |
|---|
<workflow> | 2.7 KB | 9.5 KB |
<guidelines> | 10.9 KB | 4.6 KB |
| Total | ~16 KB | 16.7 KB |
<workflow> grew by inlining Phase 1/2/3 step bodies — AI has step-level how-to up front instead of lazy-loading via get_context.py --mode phase --step X.Y. <guidelines> shrunk by listing spec/<pkg>/<layer>/index.md as paths only (sub-agents pull specific specs via jsonl injection). Total stays under Claude Code’s ~20 KB truncate threshold.
Migration & update flow
| Behavior | Before 0.5.0 | 0.5.0 |
|---|
| Breaking-change gate | Silent partial migration (rename/delete entries skipped) | trellis update exits 1, requires --migrate |
config.yaml update.skip on breaking | Half-migrated state (old paths kept, new templates not written) | Auto-bypass for safe-file-delete / new file writes / template updates |
| Confirm prompt | Generic “Modified by you, [k]eep / [r]eplace?” | Shows What (the migration action) + Why prompted (per-entry reason field) + per-option recommendation and consequences |
| Backup contents | Included .claude/worktrees/, .cursor/worktrees/, .gemini/worktrees/ (could balloon to hundreds of MB) | Excluded |
--dry-run bypasses the gate, so you can preview the full migration plan before committing to it.
Cleanup
138-entry safe-file-delete migration, hash-verified — local customizations preserved with a warning, only pristine Trellis-written files removed.
| Removed | Reason |
|---|
| iFlow platform | CLI unmaintained upstream |
| Multi-agent pipeline | Replaced by native worktree support across major CLIs |
| Ralph Loop hook | SubagentStop + exit-code-2 not portable; check self-fix loop sufficient |
parallel command | Superseded by native worktree support |
onboard command | Low usage |
create-command | Low usage |
integrate-skill | Low usage |
check-cross-layer | Merged into check |
record-session | Merged into finish-work Step 3 |
dispatch / debug / plan sub-agents | Replaced by skill routing |
RC stabilization (rc.0 → rc.6)
| Version | Change |
|---|
| rc.0 | Non-interactive init recovery; breadcrumb reads from workflow.md |
| rc.1 | OpenCode trellis-research write perms (#211); session-start.js 1.2.x loader (#212) |
| rc.2 | trellis uninstall command (#221); Windows python3 → python write replacement (#218); Copilot custom-agent frontmatter normalization (#210) |
| rc.3 | Gemini CLI 0.40.x template compat (#224) |
| rc.4 | TRELLIS_HOOKS env var for runtime disable |
| rc.5 | Codex multi_agent_v2 default-on, 8-min wait floor; AGENTS.md wait tool rules |
| rc.6 | Windows session-start.py normalizes MSYS/Cygwin/WSL paths (#226); finish-work Step 2 classifies dirty paths |
Upgrade
From 0.4.x:
The --migrate flag is REQUIRED — the breaking-change gate from 0.5.0-beta.0 fires when traversing the migration chain. 138-entry safe-file-delete is hash-verified; local customizations are preserved with a warning. Per-prompt reason field explains version-specific nuances inline.
From any 0.5.0 prerelease (beta.X / rc.X):
Plain trellis update — clean version bump, no flag needed.
Install:
npm install -g @mindfoldhq/trellis
