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

# v0.5.0

> 2026-05-06

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.

<Tip>
  **`/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](#/continue-command)" section below.
</Tip>

<Note>
  **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`.
</Note>

<Warning>
  **Known Codex upstream issues (not fixable from Trellis):**

  * **Hook context rendered in terminal ([#191](https://github.com/mindfold-ai/Trellis/issues/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`.
</Warning>

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

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

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:

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

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

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

iFlow platform dropped (CLI unmaintained upstream).

### 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` |

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

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

```bash theme={null}
trellis update --migrate
```

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`):

```bash theme={null}
trellis update
```

Plain `trellis update` — clean version bump, no flag needed.

Install:

```bash theme={null}
npm install -g @mindfoldhq/trellis
```