Skip to main content
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:
  1. Natural-language conversation enters brainstorm, creates the task
  2. After planning, AI confirms PRD with you; type continue once you’re OK
  3. AI knows the next step is curating implement.jsonl; reconfirms when done
  4. You continue — AI dispatches sub-agents for implement + check
  5. You continue — AI runs update-spec
  6. 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. Per-platform session-key sources: Claude Code writes 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: .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.

​
Platform coverage

​
7 platforms upgraded to agent-capable

Qoder, CodeBuddy, Factory Droid, Cursor, Gemini CLI, Kiro, GitHub Copilot — from commands-only to full sub-agent + hook integration. iFlow platform dropped (CLI unmaintained upstream).

​
Sub-agent context injection: class-1 hook vs class-2 pull-based

Both paths in shared infrastructure; new platforms pick one.

​
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

<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

--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.

​
RC stabilization (rc.0 → rc.6)

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