# Appendix A: Key File Paths Quick Reference
Source: https://docs.trytrellis.app/beta/advanced/appendix-a
## Appendix A: Key File Paths Quick Reference
This appendix uses **Claude Code**'s directory layout as the example (`.claude/commands/`,
`.claude/agents/`, `.claude/skills/`, `.claude/hooks/`). See the "Other platforms" section below,
or chapter 13 for the full per-platform layout.
### Core files
| File | Description | Read on |
| ----------------------------------------------- | ------------------------------------- | --------------------------------- |
| `.trellis/workflow.md` | Development workflow contract | Every session start |
| `.trellis/config.yaml` | Packages, update.skip, task hooks | Init and updates |
| `.trellis/.version` | Current Trellis version | Updates |
| `.trellis/.template-hashes.json` | Template file hashes | Updates |
| `.trellis/.developer` | Developer identity | Every session |
| `.trellis/.runtime/sessions/.json` | Active task for one AI session/window | Continue, hooks, sub-agent launch |
### Shipped commands (Claude Code)
| File | Invoked as |
| ----------------------------------------- | ---------------------- |
| `.claude/commands/trellis/finish-work.md` | `/trellis:finish-work` |
| `.claude/commands/trellis/continue.md` | `/trellis:continue` |
On platforms where SessionStart is automatic, `start` is not installed as a user-facing command. Agent-less platforms still ship a manual start workflow.
### Shipped sub-agents (Claude Code)
| File | Sub-agent | Role |
| ------------------------------------- | ------------------- | ---------------------------- |
| `.claude/agents/trellis-implement.md` | `trellis-implement` | Writes code, no `git commit` |
| `.claude/agents/trellis-check.md` | `trellis-check` | Verify + self-fix |
| `.claude/agents/trellis-research.md` | `trellis-research` | Read-only codebase search |
### Shipped skills (Claude Code)
| File | Skill | Triggers when… |
| --------------------------------------------- | --------------------- | ---------------------------------------- |
| `.claude/skills/trellis-brainstorm/SKILL.md` | `trellis-brainstorm` | User describes a feature / bug / request |
| `.claude/skills/trellis-before-dev/SKILL.md` | `trellis-before-dev` | About to write code in an active task |
| `.claude/skills/trellis-check/SKILL.md` | `trellis-check` | Implementation finished |
| `.claude/skills/trellis-update-spec/SKILL.md` | `trellis-update-spec` | Worth capturing a learning |
| `.claude/skills/trellis-break-loop/SKILL.md` | `trellis-break-loop` | A tricky bug was just resolved |
### Hook scripts (Claude Code)
| File | Trigger | Function |
| ------------------------------------------ | ----------------- | ------------------------- |
| `.claude/hooks/session-start.py` | SessionStart | Auto-inject context |
| `.claude/hooks/inject-workflow-state.py` | UserPromptSubmit | Workflow-state breadcrumb |
| `.claude/hooks/inject-subagent-context.py` | PreToolUse (Task) | Spec injection engine |
### Other platforms
Each platform writes into its own directory (see chapter 13 for the full layout):
* `.cursor/commands/`, `.cursor/skills/`, `.cursor/agents/`, `.cursor/hooks/`, `.cursor/hooks.json`, `.cursor/rules/trellis.mdc`
* `.opencode/commands/trellis/`, `.opencode/agents/`, `.opencode/skills/`, `.opencode/plugins/`
* `.codex/skills/`, `.codex/agents/` (TOML), `.codex/hooks/`, `AGENTS.md`
* `.kiro/steering/`, `.kiro/prompts/`, `.kiro/skills/`, `.kiro/agents/`
* `.gemini/commands/trellis/` (TOML), `.gemini/agents/`, `.gemini/hooks/`
* `.qoder/commands/`, `.qoder/skills/`, `.qoder/agents/`, `.qoder/hooks/`
* `.codebuddy/commands/trellis/`, `.codebuddy/skills/`, `.codebuddy/agents/`, `.codebuddy/hooks/`
* `.factory/commands/trellis/`, `.factory/droids/`, `.factory/skills/`, `.factory/hooks/`
* `.github/copilot-instructions.md`, `.github/prompts/`, `.github/skills/`, `.github/agents/`, `.github/copilot/hooks/`
* `.pi/prompts/`, `.pi/agents/`, `.pi/extensions/trellis/`, `.pi/settings.json`
* `.kilocode/workflows/`, `.kilocode/skills/`
* `.agent/workflows/`, `.agent/skills/` (Antigravity)
* `.devin/workflows/`, `.devin/skills/`
* `.agents/skills/` (shared cross-platform layer)
### Scripts
| Script | Function |
| -------------------------------------- | -------------------------- |
| `.trellis/scripts/task.py` | Task management |
| `.trellis/scripts/get_context.py` | Session context |
| `.trellis/scripts/add_session.py` | Record session |
| `.trellis/scripts/create_bootstrap.py` | First-time spec bootstrap |
| `.trellis/scripts/get_developer.py` | Developer identity utility |
| `.trellis/scripts/init_developer.py` | Developer initialization |
***
# Appendix B: Command & Skill Cheat Sheet
Source: https://docs.trytrellis.app/beta/advanced/appendix-b
## Appendix B: Command & Skill Cheat Sheet
Trellis ships only a small session-boundary command surface. Everything else is an auto-trigger skill or a sub-agent. This is intentional: commands are for explicit user boundaries; the rest of the workflow runs itself.
### Slash Commands (per platform)
`finish-work` and `continue` are the normal user-invoked commands. `start` is only user-facing on platforms that do not auto-inject session context.
| Platform | Start | Finish | Continue | Delivery form |
| ------------------------------------------------------- | ------------------------------------------------------------------------- | ---------------------- | -------------------- | -------------------------------------- |
| Claude Code / OpenCode / Gemini CLI / CodeBuddy / Droid | automatic SessionStart hook | `/trellis:finish-work` | `/trellis:continue` | Slash command |
| Cursor / Pi Agent / Qoder | automatic SessionStart hook or extension | `/trellis-finish-work` | `/trellis-continue` | Native command / prompt |
| Kiro | `@trellis:start` | `@trellis:finish-work` | `@trellis:continue` | Skill via `@` picker |
| Kilo | `/start.md` | `/finish-work.md` | `/continue.md` | Workflow file (`.kilocode/workflows/`) |
| Antigravity / Devin | workflow picker → `start` / `finish-work` / `continue` | | | Workflow file |
| GitHub Copilot | Run Prompt → `trellis-start` / `trellis-finish-work` / `trellis-continue` | | | Prompt file (`.github/prompts/`) |
| Codex | automatic `AGENTS.md` prelude; optional UserPromptSubmit hook | skill / prompt entry | skill / prompt entry | Skills + hooks |
### Auto-trigger Skills
These are matched by the platform based on user intent: no explicit invocation required. Trigger them manually with your platform's skill invocation syntax if needed.
| Skill | Triggers when… | What it does |
| --------------------- | ------------------------------------------------------ | --------------------------------------------------- |
| `trellis-brainstorm` | User describes a feature / bug / ambiguous request | Produces task + `prd.md`, spawns research as needed |
| `trellis-before-dev` | Task is in\_progress and the AI is about to write code | Reads relevant spec files for the package |
| `trellis-check` | Implementation phase finished | Diff review, lint / typecheck / test, self-fix loop |
| `trellis-update-spec` | A learning / decision / gotcha is worth capturing | Adds an entry to the right spec file |
| `trellis-break-loop` | A tricky bug was just resolved | 5-dimension root-cause + prevention analysis |
### Sub-agents
Spawned by the main session via the platform's sub-agent / Task primitive.
| Sub-agent | Role | Restriction |
| ------------------- | --------------------- | ---------------------- |
| `trellis-research` | Codebase / doc search | Read-only |
| `trellis-implement` | Coding | No `git commit` |
| `trellis-check` | Verify + self-fix | Has its own retry loop |
Available as real sub-agents on Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini CLI, Qoder, CodeBuddy, Copilot, Droid, and Pi Agent. Kilo, Antigravity, and Devin run the same work inline in the main session. Context is hook/extension-injected on Claude Code, Cursor, OpenCode, CodeBuddy, Droid, and Pi Agent; the other sub-agent platforms use a pull-based prelude.
### Global CLI Commands
| Command | Purpose | Usage |
| ----------------- | ---------------------------------------------------- | ---------------------------------------------- |
| `trellis upgrade` | Upgrade the globally installed Trellis CLI package | `trellis upgrade [--tag ]` |
| `trellis update` | Sync the current project's Trellis files to this CLI | `trellis update [--dry-run] [--migrate] [...]` |
### `task.py` Subcommands
| Subcommand | Purpose | Usage |
| ----------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `create` | Create task (also seeds `implement.jsonl` / `check.jsonl` when a sub-agent platform is installed) | `task.py create "title" [--slug name] [-a assignee] [-p priority]` |
| `add-context` | Add context entry (primary way to populate jsonl after `create`) | `task.py add-context "$DIR" "" ""` |
| `validate` | Validate JSONL | `task.py validate "$DIR"` |
| `list-context` | View all entries | `task.py list-context "$DIR"` |
| `start` | Set as current task for this AI session/window | `task.py start "$DIR"` |
| `finish` | Clear current task for this AI session/window | `task.py finish` |
| `set-branch` | Set branch name | `task.py set-branch "$DIR" "feature/xxx"` |
| `set-base-branch` | Set PR target branch | `task.py set-base-branch "$DIR" "main"` |
| `set-scope` | Set scope | `task.py set-scope "$DIR" "auth"` |
| `add-subtask` | Link child to parent | `task.py add-subtask ` |
| `remove-subtask` | Unlink child from parent | `task.py remove-subtask ` |
| `archive` | Archive task | `task.py archive ` |
| `list` | List active tasks | `task.py list [--mine] [--status ]` |
| `list-archive` | List archived tasks | `task.py list-archive [YYYY-MM]` |
### Python Scripts
```bash theme={null}
# Context
./.trellis/scripts/get_context.py # Full context
./.trellis/scripts/get_context.py --json # JSON
./.trellis/scripts/get_context.py --mode packages # Per-package spec layers (monorepo)
./.trellis/scripts/get_context.py --mode record # For /trellis:finish-work
# Session
./.trellis/scripts/add_session.py --title "..." --commit "..." --summary "..."
# Spec bootstrap (first-time)
./.trellis/scripts/create_bootstrap.py
```
***
# Appendix C: task.json Schema Reference
Source: https://docs.trytrellis.app/beta/advanced/appendix-c
## Appendix C: `task.json` Schema Reference
Matches `task.py create` in `.trellis/scripts/common/task_store.py`:
```json theme={null}
{
"id": "string", // Task ID (= slug, e.g., 02-27-user-login)
"name": "string", // Slug name (same as id in single-repo; monorepo may differ)
"title": "string", // Task title
"description": "string", // Description ("" if --description omitted)
"status": "string", // planning (default) | in_progress | completed; task.py list --status also accepts review
"dev_type": "string", // backend | frontend | fullstack | test | docs (null until set manually or by a custom hook; see note below)
"scope": "string", // Commit scope, e.g. "auth" (null until set-scope)
"package": "string", // Monorepo package name (null in single-repo)
"priority": "string", // P0 | P1 | P2 | P3 (default P2)
"creator": "string", // Creator developer id
"assignee": "string", // Assignee developer id
"createdAt": "string", // YYYY-MM-DD creation date
"completedAt": "string", // YYYY-MM-DD completion date (null if not done)
"branch": "string", // Feature branch name (null until set-branch)
"base_branch": "string", // PR target branch (captured from current branch at create time)
"worktree_path": "string", // Schema slot — written as null on create; no script fills it
"commit": "string", // Schema slot — written as null on create; no script fills it
"pr_url": "string", // Schema slot — written as null on create; no script fills it
"subtasks": [], // Intra-task todo checklist ({name, status} pairs) — unrelated to children
"children": [], // Child task directory names (parent → child link)
"parent": "string", // Parent task directory name (null if top-level)
"relatedFiles": [], // Related files list
"notes": "string", // Notes ("" by default)
"meta": {} // Arbitrary per-project metadata (e.g. Linear issue id)
}
```
Field order above matches `.trellis/scripts/common/task_store.py` verbatim — `task.py` writes them in this order.
`worktree_path` / `commit` / `pr_url` are schema placeholders — written as null on create, and no
Trellis script updates them afterward. Store commit hashes / PR URLs under `meta: {}` as custom
keys, or write them back from an `after_archive` hook.
Older tasks may be missing newer fields (e.g., pre-`package` tasks have no `"package"` key); `task.py` treats missing keys as null.
### Parent-child vs `subtasks` — know the difference
| Field | Purpose |
| ---------- | ------------------------------------------------------------------------------------------------------------- |
| `parent` | Directory name of the parent task, or `null` if top-level. Set by `task.py create --parent` or `add-subtask`. |
| `children` | Array of child task directory names. Maintained bidirectionally with the child's `parent`. |
| `subtasks` | A **within-task** todo checklist of `{name, status}` items. Used by bootstrap; unrelated to child tasks. |
***
# Appendix D: JSONL Configuration Format Reference
Source: https://docs.trytrellis.app/beta/advanced/appendix-d
## Appendix D: JSONL Configuration Format Reference
JSONL entries should point at **spec files** (`.trellis/spec/**`) or the task's **research outputs** (`{TASK_DIR}/research/*.md`) — things the sub-agent needs to read *before* writing code (rules + background). Don't add raw source files or directories (`src/services/foo.ts`, `packages//`, etc.) — sub-agents already have `Read` / `Grep` and will fetch code when they need it. Injecting code into context just burns tokens.
### File entry
```jsonl theme={null}
{
"file": ".trellis/spec/backend/index.md",
"reason": "Backend development guide"
}
```
### Directory entry
```jsonl theme={null}
{
"file": ".trellis/tasks/02-27-user-login/research/",
"type": "directory",
"reason": "Research outputs for this task"
}
```
For directory entries, the hook reads all `.md` files in the directory, up to 20. Common use: point at the task's own `research/` directory so the sub-agent picks up any upstream investigations.
### Complete example (fullstack `implement.jsonl`)
```jsonl theme={null}
{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
{"file": ".trellis/spec/backend/api-module.md", "reason": "API module conventions"}
{"file": ".trellis/spec/backend/quality.md", "reason": "Code quality requirements"}
{"file": ".trellis/spec/frontend/index.md", "reason": "Frontend development guide"}
{"file": ".trellis/spec/frontend/components.md", "reason": "Component conventions"}
{"file": ".trellis/tasks/02-27-user-login/research/", "type": "directory", "reason": "Research outputs for this task"}
```
### JSONL files used by each sub-agent
| File | Sub-agent | Typical content |
| ----------------- | ------------------- | --------------------------------------------------------- |
| `implement.jsonl` | `trellis-implement` | workflow + relevant spec indexes + task `research/` dir |
| `check.jsonl` | `trellis-check` | quality-related specs + finish-work / check command specs |
`trellis-research` writes durable findings into the task's `research/` directory. Trellis does not require a separate default research manifest; investigation context comes from the current request, existing specs, task history, and any explicit research instructions.
***
# Appendix F: FAQ
Source: https://docs.trytrellis.app/beta/advanced/appendix-f
## Appendix F: FAQ
## Getting started & upgrading
### Q1: I'm used to running `/trellis:start` at session boundaries — what now?
For a new request, just describe the work in natural language. Use
`/trellis:continue` when an active task already exists and you want the AI to
advance to the next workflow step.
The context the old `/trellis:start` injected explicitly — current developer
identity, git branch and status, active task, list of active tasks,
`workflow.md` phase index, spec index paths, recent journal summaries — is now
delivered by each platform's startup path. Claude-style platforms use
SessionStart hooks or extensions. Codex uses `AGENTS.md` plus the
`UserPromptSubmit` breadcrumb; when no task is active, the breadcrumb can direct
the AI to read `trellis-start` once.
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, artifact presence, and
`workflow.md`, then decides what to do.
On platforms without a SessionStart hook (Kilo, Antigravity, Devin), 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:
```bash theme={null}
# 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?
Upgrade the global CLI first:
```bash theme={null}
trellis upgrade # CLI 0.6.0+
npm install -g @mindfoldhq/trellis@beta # CLI 0.5.x or older (no `upgrade` command yet)
```
Then sync the project files:
```bash theme={null}
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.
```bash theme={null}
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:
```bash theme={null}
trellis upgrade # 1. upgrade the CLI itself (CLI 0.6.0+)
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. Join the beta channel first, then run `trellis update --migrate`.
If your CLI predates 0.6.0 the `trellis upgrade` command does not exist — do step 1 with `npm install -g @mindfoldhq/trellis@beta` instead, then `trellis upgrade` follows the beta channel for later bumps.
## 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?
| Primitive | Triggered by | Typical use |
| --------- | --------------------- | ------------------------------------------------------------------------------ |
| Command | User (`/trellis:*`) | Session boundaries (start, finish-work, continue) |
| Skill | Platform (auto-match) | Phase-level workflows (brainstorm, before-dev, check, update-spec, break-loop) |
| Sub-agent | Main 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 automatic startup
context (Kilo / Antigravity / Devin). It loads Trellis orientation
explicitly. On platforms with a startup hook, extension, `AGENTS.md`, or
prompt-hook bootstrap, you usually 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, artifact presence, and `workflow.md`, then 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 `` 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 every platform.
* **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:
```bash theme={null}
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//` 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//`, 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 ` 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. Classify the request and ask for task-creation consent before entering planning.` 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//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//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//testing.md` so the implement / check sub-agents follow the right test patterns.
### Q27: Can Trellis be used for non-code work — writing, legal docs, research?
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.
### Q28: How do I disable auto-commit when `.trellis/` is in `.gitignore`?
When `.gitignore` excludes `.trellis/`, scripts respect it — they print a warning and skip `git add` / `git commit`. The journal and task-archive files still write to disk; they just don't enter git.
To turn auto-commit off explicitly (regardless of `.gitignore`), set in `.trellis/config.yaml`:
```yaml theme={null}
session_auto_commit: false
```
Default `true`. Accepts `true / false / yes / no / 1 / 0 / on / off`. Affects `add_session.py` (journal) and `task.py archive` (task archival).
## Team collaboration & cross-project
### Q29: Will multiple developers using Trellis cause conflicts?
Per-developer and per-session state is isolated (`workspace/{name}/`, `.developer`, `.runtime/sessions/.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.
### Q30: 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//` — 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.
### Q31: 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 `` and `` 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.
### Q32: 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:
```bash theme={null}
trellis init -r git@github.com: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
### Q33: 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 + `` 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.
### Q34: 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.
### Q35: 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:
```bash theme={null}
npx skills add mindfold-ai/marketplace --skill trellis-meta
```
More at [`docs.trytrellis.app/skills-market/trellis-meta`](https://docs.trytrellis.app/skills-market/trellis-meta). All edits are markdown — no Python or hook code involved.
### Q36: 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:
```bash theme={null}
ln -s .trellis trellis-vault
```
Separately, `MM-DD-/` task names truncate in Obsidian's file explorer.
### Q37: 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.
***
# Architecture Overview
Source: https://docs.trytrellis.app/beta/advanced/architecture
Trellis is a **Team-level Agent Harness with built-in LLM wiki**.
In implementation terms, that means two systems share the same project files:
* **Agent Harness**: workflow state, hooks, skills, sub-agents, and platform adapters that control how AI coding work moves.
* **Built-in LLM wiki**: specs, tasks, research, and journals stored in the repository so AI sessions can reload project knowledge from files.
* **Team-level layer**: git-tracked workflow/spec/task files plus per-developer workspace memory, so multiple people and multiple AI tools operate against the same conventions.
This document maps that idea to the current Trellis feature set, the modules that implement each feature, and the files to inspect when customizing a generated project. For the user flow, see [How It Works](/start/how-it-works).
> Trellis is AGPL-3.0 licensed. Internal team use is permitted. Commercial use of a Trellis-derived product or service requires prior contact: **[klein@mindfold.ai](mailto:klein@mindfold.ai)**.
## Design principles
Trellis treats AI coding as a workflow and knowledge-management problem, not a single chat session.
| Principle | Implementation rule |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Make workflow state explicit | Task `status` and `[workflow-state:STATUS]` blocks tell the main session what phase it is in. |
| Store durable knowledge in files | Requirements, specs, research, and journals live under `.trellis/`, not only in conversation history. |
| Split work by responsibility | Research, implementation, and checking use separate agents or skills depending on platform capability. |
| Keep context scoped | JSONL manifests list the spec/research files needed for the current task instead of dumping the whole repo. |
| Preserve the review boundary | Implement/check agents produce a clean diff; the main session proposes commits, and `/trellis:finish-work` only archives and journals. |
| Support teams and tool diversity | The same `.trellis/` model is adapted into Claude Code, Cursor, Codex, OpenCode, Kiro, Gemini, Qoder, Copilot, Droid, Pi, Kilo, Antigravity, Devin, and related tools. |
## Feature overview
### Agent Harness
| Feature | What it does |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Three-phase workflow | Defines Plan, Execute, and Finish in `.trellis/workflow.md`. |
| Per-turn workflow-state breadcrumb | Injects the current next-action rule into the main session on hook-capable platforms. |
| Task lifecycle | Stores requirements, status, assignee, branch, PR metadata, and subtask relationships in `.trellis/tasks//`. |
| Research / implement / check roles | Separates investigation, code writing, and verification. |
| Read-before-write enforcement | Makes implement/check paths read PRD and relevant specs before changing files. |
| Finish boundary | Separates final verification, spec update, work commit, task archive, and journal writing. |
### Built-in LLM wiki
| Feature | What it stores |
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
| Spec library | Project conventions and thinking guides under `.trellis/spec/`. |
| Task knowledge | PRDs, technical designs, implementation plans, research, and JSONL manifests under `.trellis/tasks/`. |
| Workspace memory | Per-developer journals under `.trellis/workspace//`. |
| Workflow documentation | The executable workflow contract in `.trellis/workflow.md`. |
| Local customization map | Bundled `trellis-meta` references explaining which generated files own each behavior. |
### Team-level behavior
| Feature | What it enables |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| Git-tracked workflow/spec/task files | New team members clone the same workflow and conventions. |
| Per-session active task pointers | Multiple windows can work on different tasks without sharing one global current task. |
| Subtask trees | Parent tasks can hold shared requirements while child tasks run their own Plan -> Execute -> Finish loop. |
| Cross-platform adapters | Teams can use different AI tools while keeping the same `.trellis/` facts. |
| Spec distillation | Lessons from one task can be promoted into `.trellis/spec/` for future tasks. |
## Feature to module map
| Feature | Primary module | Local files to inspect |
| ---------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Workflow phases and routing | Workflow module | `.trellis/workflow.md` |
| Per-turn next-action injection | Workflow-state module | `[workflow-state:STATUS]` blocks, `inject-workflow-state.py` or equivalent plugin |
| Task creation, status, archive | Task store module | `.trellis/tasks//task.json`, `.trellis/scripts/task.py`, `.trellis/scripts/common/task_store.py` |
| Session-scoped current task | Active-task runtime | `.trellis/.runtime/sessions/.json`, `.trellis/scripts/common/active_task.py` |
| Planning artifact/spec injection | Context-loading module | `prd.md`, `design.md`, `implement.md`, `implement.jsonl`, `check.jsonl`, `inject-subagent-context.py`, platform agent preludes |
| Research / implement / check roles | Agent and skill module | Platform `agents/`, `skills/`, prompts, workflows |
| Team convention memory | Spec module | `.trellis/spec/**/index.md`, guideline files |
| Developer memory | Workspace module | `.trellis/workspace//journal-*.md` |
| Platform support | Platform adapter module | `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.github/`, `.pi/`, and related settings |
| Finish and archive | Finish module | `/trellis:finish-work`, `.trellis/scripts/add_session.py`, task archive scripts |
## Workflow module
`.trellis/workflow.md` is the source of truth for Trellis's Plan -> Execute -> Finish contract.
```text theme={null}
Phase 1: Plan -> classify the turn, get task-creation consent, write planning artifacts
Phase 2: Execute -> implement, check, and repeat until green
Phase 3: Finish -> final verification, spec update, work commit, archive
```
The file owns three things:
* phase definitions and numbered steps
* skill / sub-agent routing by platform capability
* `[workflow-state:STATUS]` blocks used by the per-turn breadcrumb hook
Changing workflow behavior starts here. Platform commands, skills, and agent files may also need wording updates if they describe the same flow, but the workflow contract itself belongs in `.trellis/workflow.md`.
## Workflow-state module
On hook-capable platforms, `inject-workflow-state.py` or the equivalent plugin runs on each user prompt.
The runtime contract is:
1. Resolve the Trellis root from `cwd`.
2. Resolve the active task for the current session.
3. Read `task.json.status`, or synthesize `no_task` when no task is active.
4. Parse `.trellis/workflow.md`.
5. Inject the matching `[workflow-state:STATUS]` body into `...`.
Marker syntax:
```text theme={null}
[workflow-state:planning]
...
[/workflow-state:planning]
```
The hook scripts are parser-only. They do not contain fallback copies of the breadcrumb text. If a matching block is missing, the hook emits `Refer to workflow.md for current step.`
Default statuses:
| Status | Writer | Notes |
| ------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `no_task` | Synthesized by the hook | No active task pointer for the current session. |
| `planning` | `task.py create` | Requirements and planning artifacts are active; lightweight tasks can be PRD-only, while complex tasks need `design.md` and `implement.md` before start. |
| `in_progress` | `task.py start` | Implementation, checking, and finish steps are active. |
| `completed` | `task.py archive` | Written immediately before archive move; not normally visible as a live breadcrumb. |
`task.py create` best-effort sets the current session's active-task pointer, so `planning` is reachable during brainstorm and JSONL curation.
## Task store module
Each task is one directory:
```text theme={null}
.trellis/tasks//
├── task.json
├── prd.md
├── design.md
├── implement.md
├── implement.jsonl
├── check.jsonl
└── research/
```
Important files:
| File | Purpose |
| ----------------- | -------------------------------------------------------------------------------------------------------- |
| `task.json` | Status, priority, assignee, branch, PR URL, parent/child relationships, and extension metadata. |
| `prd.md` | Requirements, constraints, acceptance criteria, and out-of-scope items. |
| `design.md` | Technical design for complex tasks: boundaries, contracts, data flow, compatibility, tradeoffs. |
| `implement.md` | Execution plan for complex tasks: ordered checklist, validation commands, review gates, rollback points. |
| `implement.jsonl` | Spec and research manifest for implementation context. |
| `check.jsonl` | Spec and research manifest for review and verification context. |
| `research/` | Research artifacts written by `trellis-research` or the main planning flow. |
Task lifecycle hooks are command events, not generic status watchers:
| Lifecycle event | Fires when | Meaning |
| --------------- | ------------------------------------------- | -------------------------------------------------------------------------------------- |
| `after_create` | `task.py create` finishes | A task directory exists. |
| `after_start` | `task.py start` finishes | The task entered `in_progress`. |
| `after_finish` | `task.py finish` clears the session pointer | The current AI session detached from the task; the task may still be active elsewhere. |
| `after_archive` | `task.py archive` finishes | The task is archived; use this for external "done" sync. |
## Active-task runtime module
The current task is session-scoped:
```text theme={null}
.trellis/.runtime/sessions/.json
```
That file points one AI session or window at one task. Different windows can work on different tasks in the same repository.
`.trellis/.current-task` is a fallback for command-line contexts. Session-scoped runtime pointers take precedence when the platform provides a session identity.
## Context-loading module
Trellis loads context through three paths:
| Context type | Source | Used by |
| -------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| Startup context | `.trellis/scripts/get_context.py` | Main session startup report. |
| Per-turn workflow state | `.trellis/workflow.md` blocks | Main session next-action guidance. |
| Task artifact/spec context | `prd.md`, `design.md`, `implement.md`, `implement.jsonl`, `check.jsonl`, research files | Research, implement, check roles, and inline skill flows. |
JSONL rows are plain file references:
```text theme={null}
{"file": ".trellis/spec/docs-site/docs/style-guide.md", "reason": "Docs writing style"}
```
In the standard flow, task artifacts are read separately from JSONL manifests.
The shared order is `jsonl entries -> prd.md -> design.md if present ->
implement.md if present`. `implement.jsonl` and `check.jsonl` list spec and
research files. Seed rows without a `file` field are ignored. Source files are
read during implementation and review, not pre-registered in JSONL.
## Platform adapter module
Trellis uses each platform's available primitives. The generated project files are the source of truth for an actual repository, but the default capability groups are:
| Group | Platforms | Startup context | Per-turn workflow-state | Implementation/check context |
| ----------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Hook + hook-push sub-agent | Claude Code, Cursor, OpenCode, CodeBuddy, Droid, Pi | Hook, plugin, or extension | Hook or equivalent | Hook injects JSONL entries, `prd.md`, `design.md` if present, and `implement.md` if present. |
| Hook + pull-prelude sub-agent | Gemini CLI, Qoder, Copilot | Hook | Hook | Sub-agent reads JSONL entries and task artifacts itself on startup. |
| Codex | Codex | `AGENTS.md`; `UserPromptSubmit` can inject a no-task bootstrap reminder | Optional hook when enabled (0.129+ also requires `/hooks` review) | Inline mode reads artifacts through skills; sub-agent mode uses pull-based preludes. |
| Kiro | Kiro | Skill files under `.kiro/` | No Trellis per-turn hook by default | Agent/skill files read Trellis context. |
| Main-session workflow/skill | Kilo, Antigravity, Devin | Manual workflow or skill entry | No Trellis per-turn hook by default | Main session reads specs and task files inline. |
If the local settings file disagrees with this table, follow the local settings file. Trellis projects are intentionally customizable.
## Agent and skill module
Trellis ships three sub-agent roles when the platform supports sub-agents:
| Sub-agent | Role | Primary context |
| ------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `trellis-research` | Investigate code, docs, APIs, and alternatives; write findings under `research/`. | Research prompt plus task/repo context as needed. |
| `trellis-implement` | Write the change against the planning artifacts and relevant specs. | `implement.jsonl`, `prd.md`, optional `design.md`, optional `implement.md`. |
| `trellis-check` | Review, run checks, and self-fix findings. | `check.jsonl`, `prd.md`, optional `design.md`, optional `implement.md`, changed files. |
Skills cover phases where the main session needs guidance: brainstorm, before-dev, check, update-spec, finish-work, and meta customization. On platforms without sub-agents, skills carry more of the execution path directly in the main session.
Removed 0.4 mechanisms:
* `dispatch`, `plan`, and `debug` sub-agents were replaced by skill routing.
* The SubagentStop-based Ralph Loop was replaced by `trellis-check` owning its retry loop.
* Trellis no longer ships its own `/parallel` worktree orchestrator; use the platform's native worktree support.
## LLM wiki modules
The wiki side is a set of repository files that AI sessions can reread.
| Module | Path | Contents |
| ---------------------- | --------------------------------- | ---------------------------------------------------------------------------------- |
| Spec library | `.trellis/spec/` | Team conventions, package/layer rules, thinking guides. |
| Task knowledge | `.trellis/tasks/` | PRDs, technical designs, implementation plans, research, JSONL manifests, archive. |
| Workspace memory | `.trellis/workspace//` | Per-developer journals and indexes. |
| Workflow reference | `.trellis/workflow.md` | The workflow contract and next-action prompt blocks. |
| Trellis meta reference | bundled `trellis-meta` skill | Local architecture and customization map for generated Trellis files. |
Stable team rules belong in `.trellis/spec/`. Task-specific facts belong in the task directory. Session notes belong in `.trellis/workspace//`.
## Finish module
Trellis separates implementation, work commits, and bookkeeping:
1. Implement/check agents produce a clean diff.
2. The main session runs final verification and `trellis-update-spec`.
3. Phase 3.4 proposes a batched commit plan, waits for one user confirmation, stages the listed files, and runs `git commit`. It does not amend and does not push.
4. `/trellis:finish-work` classifies dirty paths, stops if current-task work is still uncommitted, archives the task, and writes the workspace journal.
`/trellis:finish-work` is not the command that commits feature code. Work commits happen first; archive and journal commits are bookkeeping after that.
## Generated and protected files
`trellis init` and `trellis update` generate local files, but local edits matter:
| Path | Rule of thumb |
| -------------------------------- | ------------------------------------------------------------------ |
| `.trellis/workflow.md` | Project workflow source of truth; update deliberately. |
| `.trellis/spec/` | Team-owned; template updates do not overwrite package/layer specs. |
| `.trellis/tasks/` | Work history; avoid manually deleting active tasks. |
| Platform directories | Tool adapters; inspect local settings before changing behavior. |
| `.trellis/.template-hashes.json` | Managed hash index; edit only when repairing update state. |
| `.trellis/.runtime/` | Runtime state; normally not edited by hand. |
For local customization, use the bundled `trellis-meta` skill as the map. It tells an AI to read local architecture references first, inspect actual project files, and modify the project copy instead of changing `node_modules` or a global install.
## Customization map
| Goal | First file to inspect |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Change phase order, required steps, or next-action wording | `.trellis/workflow.md` |
| Change task creation, status, archive, or lifecycle sync | `.trellis/scripts/common/task_store.py`, `.trellis/scripts/task.py`, `.trellis/config.yaml` |
| Change spec loading or JSONL rules | `.trellis/workflow.md`, `.trellis/scripts/common/task_context.py`, platform agent/prelude files |
| Change hook behavior | Platform hook settings plus `.trellis/scripts/` hook implementations |
| Change implement/check agent behavior | Platform agent files and task JSONL context rules |
| Add team-specific coding rules | `.trellis/spec/` or a project-local skill |
# Multi-agent Collaboration with Channel
Source: https://docs.trytrellis.app/beta/advanced/channel
Coordinate Claude and Codex workers through durable chat or forum channels, with explicit context, routing, waits, interrupts, and cleanup.
`trellis channel` is Trellis's local multi-agent collaboration runtime. It lets a main agent start Claude or Codex workers, give each worker explicit context, exchange messages through a durable event log, and inspect or redirect work while it is running.
Use Channel when the work needs a conversation or an audit trail—not just one isolated sub-agent call.
```text theme={null}
main agent
|
| create / send / wait / interrupt
v
durable channel event log
| |
v v
Claude worker Codex worker
```
Channel state is stored under `~/.trellis/channels/`. The default scope is the current project; `--scope global` creates a cross-project channel.
## When to use Channel
| Need | Channel pattern |
| -------------------------------- | -------------------------------------------------------------- |
| A second opinion | Run a one-shot worker with `channel run`. |
| Multi-round design discussion | Create, spawn, send, wait, then send follow-up pressure tests. |
| Independent implementation/check | Spawn a worker with task files or a JSONL context manifest. |
| Parallel review | Spawn named workers and wait for all of them. |
| Correct work already in flight | Use `channel interrupt` without discarding the session. |
| Durable topics or issue feedback | Create a `--type forum` channel with threads. |
Do not use Channel as long-term conversation memory. Use `trellis mem` for history search. A normal platform sub-agent call is also simpler when you only need one static result and do not need durable messages, progress inspection, or redirection.
## Let the AI operate Channel
`trellis init` and `trellis update` install the bundled `trellis-channel` skill on supported platforms. You can describe the collaboration outcome instead of assembling every command yourself:
```text theme={null}
Use trellis-channel to ask a Codex reviewer to challenge this design.
Give it the PRD and design only, run at least two pressure-test rounds,
then summarize the blockers without changing code.
```
The skill chooses the matching Channel workflow and CLI commands. Use the CLI directly when scripting, inspecting events, or debugging a worker.
## One-shot question
`channel run` creates an ephemeral channel, starts one worker, sends the prompt, prints the final answer, and removes the channel on success:
```bash theme={null}
trellis channel run \
--provider codex \
--message "Review this design boundary and name the top three risks." \
--timeout 10m
```
If the run fails or times out, Trellis keeps the channel so you can inspect its events and worker log.
## Multi-round review
The most useful Channel workflow is an iterative review. Give the worker only the files it needs, wait on Trellis-emitted events, then challenge the first answer instead of treating it as final.
```bash theme={null}
TASK=.trellis/tasks/06-01-example-feature
trellis channel create architecture-review \
--task "$TASK" \
--by main
trellis channel spawn architecture-review \
--provider codex \
--as reviewer \
--cwd "$PWD" \
--file "$TASK/prd.md" \
--file "$TASK/design.md" \
--timeout 30m
cat <<'EOF' | trellis channel send architecture-review \
--as main \
--to reviewer \
--stdin \
--delivery-mode requireRunningWorker
Review the proposed design. Verify its assumptions against the repository,
identify blocking risks, and cite the relevant files. Do not implement it.
EOF
trellis channel wait architecture-review \
--as main \
--from reviewer \
--kind turn_finished \
--timeout 15m
trellis channel messages architecture-review \
--from reviewer \
--kind message \
--last 1 \
--raw
```
Continue with a focused second round:
```bash theme={null}
cat <<'EOF' | trellis channel send architecture-review \
--as main \
--to reviewer \
--stdin
Pressure-test the MVP boundary. Which deferred capability would force a
redesign if omitted now, and which concerns can safely wait?
EOF
trellis channel wait architecture-review \
--as main \
--from reviewer \
--kind turn_finished \
--timeout 15m
```
A productive review usually covers the direction, MVP boundary, data contract, CLI or UX contract, failure handling, and an opposition round. One answer plus a confirmation is a review, not a brainstorm.
## Context and routing
Workers do not automatically receive every project file.
* Use repeatable `spawn --file ` flags for a few explicit files.
* Use repeatable `spawn --jsonl ` flags for Trellis context manifests.
* Use `--as ` to give each worker a stable address.
* Use `send --to ` to wake a worker. Spawned workers are explicit-only by default.
* Use `--delivery-mode requireRunningWorker` when silently appending a message to a stopped worker would be an error.
* Use `--stdin` or `--text-file` for long prompts so the shell does not reinterpret punctuation.
`send` always writes a `message` event. It has no custom `--tag` or `--kind` flag. Wait for system events such as `turn_finished`, `done`, `error`, or `killed` instead of asking the model to emit a magic completion string.
## Parallel reviewers
Give workers distinct names, send each one a targeted brief, and use `wait --all`:
```bash theme={null}
trellis channel create design-review --by main --ephemeral
trellis channel spawn design-review --provider claude --as reviewer-claude --timeout 15m
trellis channel spawn design-review --provider codex --as reviewer-codex --timeout 15m
echo "Review correctness and identify release blockers." \
| trellis channel send design-review --as main --to reviewer-claude --stdin
echo "Challenge the design assumptions and propose a smaller solution." \
| trellis channel send design-review --as main --to reviewer-codex --stdin
trellis channel wait design-review \
--as main \
--from reviewer-claude,reviewer-codex \
--kind turn_finished \
--all \
--timeout 15m
```
`--all` requires every worker listed in `--from` to produce a matching event. A timeout exits with code `124` and reports which workers are still missing.
## Redirect a worker
Use a soft interrupt when the worker should abandon its current turn and follow replacement instructions while keeping its provider session:
```bash theme={null}
echo "Stop the refactor. Reproduce the failing test first." \
| trellis channel interrupt implementation \
--as main \
--to implementer \
--stdin
```
Use `channel kill --as ` only when the worker must stop immediately or does not honor the interrupt. Session identifiers and logs remain available for diagnosis and `spawn --resume`.
## Forum channels
A forum channel is a durable board of independent threads rather than a flat chat timeline:
```bash theme={null}
trellis channel create release-feedback \
--type forum \
--description "Release feedback and follow-up decisions." \
--by main
trellis channel post release-feedback opened \
--as main \
--thread documentation-gap \
--title "Document the collaboration runtime" \
--description "Track the missing user guide and its resolution." \
--text "The feature currently appears only in release notes."
trellis channel forum release-feedback
trellis channel thread release-feedback documentation-gap
```
Use `channel context add` for background that should remain visible whenever a channel or thread is read. Use `post ... status` and `post ... summary` to record the resolution. Forum history is event-sourced, so inspect it with `forum`, `thread`, and `messages --thread` instead of parsing `events.jsonl` directly.
## Inspect and clean up
```bash theme={null}
trellis channel list --all
trellis channel messages architecture-review --raw --last 50
trellis channel messages architecture-review --raw --kind progress --last 80
trellis channel rm architecture-review
```
Pretty message output is an operator view and may shorten progress payloads. Use `--raw` when auditing streamed output or diagnosing a stalled tool call.
Spawned workers have an idle cleanup TTL of `5m` and a default live-worker budget of `6`. Override them per spawn with `--idle-timeout` and `--max-live-workers`, or configure `channel.worker_guard` in `.trellis/config.yaml`.
## Command map
| Command | Purpose |
| ---------------------------- | ----------------------------------------------------- |
| `channel create` | Create a durable chat or forum channel. |
| `channel run` | Run one ephemeral worker and print its answer. |
| `channel spawn` | Start a Claude or Codex worker with explicit context. |
| `channel send` / `wait` | Route work and wait for matching events. |
| `channel messages` | Inspect, filter, or follow the event stream. |
| `channel interrupt` / `kill` | Redirect a turn or stop a worker. |
| `channel forum` / `thread` | Read reduced forum state and one thread timeline. |
| `channel context` / `title` | Manage durable context and presentation metadata. |
| `channel rm` / `prune` | Remove one channel or preview and apply bulk cleanup. |
Run `trellis channel --help` for the complete flags supported by your installed CLI version.
# Configure .trellis/config.yaml
Source: https://docs.trytrellis.app/beta/advanced/configuration
Learn how Trellis reads .trellis/config.yaml, which keys matter, and how updates add new configuration sections safely.
## Configure `.trellis/config.yaml`
`.trellis/config.yaml` is the project-level configuration file for Trellis runtime behavior. It controls session journal commits, task lifecycle hooks, package mapping, and Codex dispatch mode.
Track this file with the repo. Treat it as shared team configuration, not as a place for per-machine identity or secrets. Per-machine identity belongs in `.trellis/.developer`; credentials should stay in environment variables or your normal secret manager.
## Edit safely
Most sections are optional. Leave commented examples commented until you need them, and edit only the keys your project actually uses.
Use normal YAML values:
```yaml theme={null}
session_commit_message: 'chore: record journal'
max_journal_lines: 2000
session_auto_commit: false
```
When a key is absent, Trellis uses its built-in default. Keep indentation consistent for nested blocks such as `hooks`, `packages`, and `codex`.
Hook commands live in tracked project configuration. Do not put tokens, API keys, or
machine-specific absolute paths in `.trellis/config.yaml`.
## Current keys
| Key | Default | What it controls |
| ------------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `session_commit_message` | `"chore: record journal"` | Commit message used by `add_session.py` when it auto-commits journal and index changes. |
| `max_journal_lines` | `2000` | Maximum lines per journal file before Trellis rotates to the next journal file. |
| `session_auto_commit` | `true` | Whether `add_session.py` and `task.py archive` auto-stage and auto-commit Trellis journal / task archive changes. |
| `hooks` | unset | Shell commands that run after task lifecycle events. |
| `packages` | unset | Package declarations for monorepos, submodules, and polyrepo-style directories. |
| `default_package` | unset | Fallback package when a command or task does not specify one. |
| `update.skip` | unset | Legacy update exclusion list that `trellis update` still honors during normal updates. |
| `codex.dispatch_mode` | `inline` | Codex-only choice between main-agent implementation and legacy `trellis-*` sub-agent dispatch. |
### Session recording
`session_commit_message` and `max_journal_lines` apply to session journal recording:
```yaml theme={null}
session_commit_message: 'chore: record journal'
max_journal_lines: 2000
```
Use `session_commit_message` if your repo has a conventional commit style for Trellis journal commits. Use `max_journal_lines` to keep `.trellis/workspace//journal-N.md` files at a reviewable size.
### Session auto-commit
`session_auto_commit` controls whether Trellis scripts touch git for journal and task archive bookkeeping:
```yaml theme={null}
session_auto_commit: false
```
Default `true` preserves the normal behavior: `add_session.py` and `task.py archive` write files, stage the Trellis changes, and create bookkeeping commits. Set it to `false` when `.trellis/` is intentionally gitignored or when your team wants to review and commit Trellis bookkeeping manually.
Accepted values are `true`, `false`, `yes`, `no`, `1`, `0`, `on`, and `off` (case-insensitive). Invalid values fall back to `true` and print a warning.
### Task lifecycle hooks
`hooks` runs shell commands after task lifecycle events. Each command receives `TASK_JSON_PATH`, pointing at the task's `task.json`.
```yaml theme={null}
hooks:
after_create:
- "echo 'Task created'"
after_start:
- "echo 'Task started'"
after_finish:
- "echo 'Task finished'"
after_archive:
- "echo 'Task archived'"
```
Supported events are `after_create`, `after_start`, `after_finish`, and `after_archive`. Hook failures print a warning but do not block the main task operation.
### Packages and default package
`packages` declares project structure for monorepos and repos with multiple working directories:
```yaml theme={null}
packages:
frontend:
path: packages/frontend
backend:
path: packages/backend
docs:
path: docs-site
type: submodule
webapp:
path: ./webapp
git: true
default_package: frontend
```
Use `type: submodule` for git submodules. Use `git: true` when a subdirectory is its own independent git repository, as in polyrepo or meta-repo layouts.
`default_package` must match a key under `packages`. Trellis uses it when a task or command does not specify a package.
### Update skip compatibility
`update.skip` is still supported for projects that already use it, even though the current template no longer includes a commented example:
```yaml theme={null}
update:
skip:
- .claude/commands/
- docs-site/
```
During normal `trellis update` runs, skipped paths are excluded from template writes and safe-file-delete cleanup. During breaking migrations that you run with `--migrate`, Trellis can bypass `update.skip` for migration-required cleanup so the project does not stay half-updated; the update command prints a warning before doing this.
### Codex dispatch mode
`codex.dispatch_mode` is only read by Codex workflows. Other platforms ignore it.
```yaml theme={null}
codex:
dispatch_mode: inline # or "sub-agent" to dispatch trellis-* sub-agents
```
`inline` keeps implementation and checking in the main Codex agent. `sub-agent` opts into the older dispatch model where the main agent launches `trellis-implement`, `trellis-check`, or `trellis-research` sub-agents.
The default is `inline` because Codex sub-agents run in isolated turns and cannot inherit the parent session's full task context. Use `sub-agent` only when you explicitly want that legacy split.
## Update behavior
`trellis init` writes the current template for new projects. For existing projects, `trellis update` preserves local edits to `.trellis/config.yaml` instead of replacing the file wholesale.
When a release adds a new config section, the migration manifest can declare it through `configSectionsAdded`. During `trellis update`, Trellis checks whether the configured sentinel text already appears in the target file. If the sentinel is missing, Trellis appends the matching section from the bundled template to the end of `.trellis/config.yaml`.
This append-only path is idempotent and preserves your existing values. The `session_auto_commit` section was delivered this way for existing projects: if `session_auto_commit:` was missing, `trellis update` appended the commented section; if it was already present, update skipped it.
After an update, review any appended commented section and uncomment only the keys you want to activate.
# Custom Sub-agents
Source: https://docs.trytrellis.app/beta/advanced/custom-agents
## Custom Sub-agents
Trellis ships three sub-agents (`trellis-implement`, `trellis-check`, `trellis-research`). You can modify them or add your own. This chapter walks through the Claude Code format as the main example, then lists the frontmatter differences on other platforms.
Sub-agents ship on 19 of 22 configured platforms: Claude Code, Cursor, OpenCode, Codex, Kiro,
Gemini CLI, Qoder, CodeBuddy, Copilot, Droid, Pi Agent, Oh My Pi, Reasonix, ZCode, Trae, Grok
Build, Kimi Code, Snow CLI, DeepSeek Harness. The agent file format varies by platform (Markdown /
TOML / JSON), and on platforms without a `PreToolUse` hook or extension equivalent the sub-agents
read their JSONL manifest plus `prd.md`, `design.md` if present, and `implement.md` if present via
a pull-based prelude instead of having that context injected. Codex can also run in inline mode,
where the main session reads the same artifacts through skills. DeepSeek Harness dispatches native
continuable `subagent` children and gives each child one non-user-invocable `trellis-agent-*` role
skill; the optional `dsh-trellis` companion provides event-driven `trellis_wait`, with an initial
foreground dispatch fallback when the plugin is absent. Kilo, Antigravity, and Devin do not expose
a sub-agent primitive — their implement / check work runs inline in the main session.
### Sub-agent definition (Claude Code example)
A sub-agent definition file lives at `.claude/agents/{name}.md` and uses YAML frontmatter:
```markdown theme={null}
---
name: agent-name
description: |
One-line description of what this sub-agent does, used by the platform to decide when to spawn it.
tools: Read, Write, Edit, Bash, Glob, Grep
---
# Agent Name
Instructions for the sub-agent go here. Treat it as the sub-agent's system prompt.
```
Key frontmatter fields on Claude Code:
| Field | Meaning |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name` | Sub-agent identifier used in `Task(subagent_type="...")` calls |
| `description` | Used by the main session to decide when to spawn this sub-agent |
| `tools` | Comma-separated list of tools the sub-agent may call |
| `model` | Optional model override. Omit to inherit the session model; this is the current recommendation so Cursor users and similar are not billed on a forced Opus default |
### Sub-agent file format is platform-specific
The file extension, frontmatter shape, and tool-declaration syntax differ per platform:
| Platform | File | Tool / permission field | Example value |
| ----------- | -------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------ |
| Claude Code | `.claude/agents/{name}.md` | `tools:` (comma list) | `Read, Write, Edit, Bash, Glob, Grep, Task, Skill` |
| Claude Code | (MCP tools) | same field, prefixed names | `mcp__exa__web_search_exa`, `mcp__chrome-devtools__*` |
| Cursor | `.cursor/agents/{name}.md` | CC-style `tools:` comma list | `Read, Write, Edit, Bash` |
| OpenCode | `.opencode/agents/{name}.md` | `permission:` (object) | `{ read: allow, write: allow, bash: allow, "mcp__exa__*": allow }` |
| Codex | `.codex/agents/{name}.toml` | TOML `sandbox_mode` + tool toggles | `sandbox_mode = "workspace-write"` |
| Kiro | `.kiro/agents/{name}.json` | JSON `tools:` (lowercase array) | `["read", "write", "bash"]` |
| Gemini CLI | `.gemini/agents/{name}.md` | CC-style `tools:` comma list | `Read, Write, Edit, Bash` |
| Qoder | `.qoder/agents/{name}.md` | CC-style `tools:` comma list | `Read, Write, Edit, Bash` |
| CodeBuddy | `.codebuddy/agents/{name}.md` | CC-style `tools:` comma list | `Read, Write, Edit, Bash` |
| Copilot | `.github/agents/{name}.agent.md` | CC-style `tools:` comma list | `Read, Write, Edit, Bash` |
| Droid | `.factory/droids/{name}.md` | CC-style `tools:` comma list | `Read, Write, Edit, Bash` |
| Pi Agent | `.pi/agents/{name}.md` | CC-style `tools:` comma list + extension context | `Read, Write, Edit, Bash` |
### Pi Agent model and thinking config
Pi sub-agent definitions live under `.pi/agents/{name}.md`. They use Markdown with YAML frontmatter, like Claude-style agents, plus optional Pi run configuration:
```markdown theme={null}
---
name: trellis-review
description: |
Reviews the current diff and reports correctness issues.
tools: Read, Write, Edit, Bash, Glob, Grep
model: anthropic/claude-sonnet-4
thinking: high
fallbackModels:
- openai/gpt-5-mini
---
# trellis-review
Review the current diff against the active Trellis task and project specs.
```
The Pi extension reads this frontmatter before it launches the child Pi process. It starts nested agents in text/no-session mode, forwards the current Trellis context id, and maps run config to Pi CLI args:
| Config | Child Pi args |
| -------------------- | --------------------------------------------------------------------------- |
| `model` + `thinking` | `--model :` unless the model already has a thinking suffix |
| `model` only | `--model ` |
| `thinking` only | `--thinking ` |
Per-call `model` / `thinking` passed to the Pi `subagent` tool overrides frontmatter for that one child run. `fallbackModels` / `fallback_models` is parsed for pi-subagents-compatible files, but Trellis does not pass it to Pi CLI because Pi has no documented stable fallback-model flag.
For custom context injection, use a task-local JSONL file convention and extend `.pi/extensions/trellis/index.ts` to handle the new sub-agent name. Pi Agent does not load Python hook scripts.
If you author a sub-agent that should work on multiple platforms, put the canonical Claude-Code version in `packages/cli/src/templates/claude/agents/` and add platform adapters in `packages/cli/src/configurators/` that translate the frontmatter into each platform's native syntax. Trellis already does this for the shipped `trellis-implement` / `trellis-check` / `trellis-research`.
### Modifying a shipped sub-agent
Example: add a timeout and a stricter tool budget to `trellis-check`.
```markdown theme={null}
---
name: trellis-check
description: |
Code quality check expert. Reviews diffs against specs, runs lint/typecheck/test, self-fixes.
tools: Read, Write, Edit, Bash, Glob, Grep
timeout: 600000
---
```
If you plan to roll this out across your team, put the change in `.trellis/spec/backend/` (or wherever your convention lives) instead of the agent definition, so the sub-agent's behavior changes through spec injection rather than a fork.
### Creating a new sub-agent
Example: a `trellis-test` sub-agent that writes tests for the current diff.
````markdown theme={null}
---
name: trellis-test
description: |
Writes comprehensive tests for the current diff. Runs them and reports pass/fail.
tools: Read, Write, Edit, Bash, Glob, Grep
---
# trellis-test
You are the trellis-test sub-agent in the Trellis workflow.
## Responsibilities
1. Analyze the current diff to identify testable units.
2. Write unit tests for new functions and components.
3. Write integration tests for cross-module interactions.
4. Run the test suite and report results.
## Flow
#### Get changes
```bash
git diff --name-only HEAD
```
#### Identify testable code
For each changed file, identify functions or components that need tests.
#### Write tests
Follow the existing test patterns in the repository. Do not invent a new test style.
#### Run tests
```bash
pnpm test
```
````
### Context injection
If you want your sub-agent to receive task and spec context the way the shipped
ones do:
1. Accept a JSONL name convention (e.g. `test.jsonl`) in each task directory.
2. Load the JSONL entries first, then `prd.md`, then `design.md` if present, then `implement.md` if present.
3. On platforms with a `PreToolUse` (sub-agent) hook or extension equivalent — Claude Code, Cursor, OpenCode, CodeBuddy, Droid, Pi Agent — edit `inject-subagent-context` or the Pi extension to handle the new sub-agent type.
4. On platforms without that injection point (Codex, Kiro, Gemini, Qoder, Copilot), follow the pull-based prelude pattern the shipped sub-agents use: prepend a block at the top of the agent file telling the sub-agent to `Read` its JSONL and task artifacts before acting.
For a detailed walkthrough, see chapter 11 on hooks.
***
# Custom Slash Commands
Source: https://docs.trytrellis.app/beta/advanced/custom-commands
## Custom Slash Commands
Trellis ships a deliberately small set of slash commands. On agent-capable platforms (Claude Code, OpenCode, Cursor, Codex, Pi Agent, etc.), only `finish-work` and `continue` are installed. `start` is usually not user-facing because startup context is loaded through a SessionStart hook, extension, `AGENTS.md`, or prompt-hook bootstrap at the top of the session. Agent-less platforms (Kilo, Antigravity, Devin) have no hook, so `start` is shipped there as a slash command. Everything else that used to be a command has moved to auto-trigger skills (see [Custom Skills](./custom-skills)). Add your own slash command when you have a specific entry point you want the user to invoke on demand.
### Command File Format and Location
Trellis groups the 22 configured platforms into three delivery models:
**Explicit slash commands** — the user types `/trellis:`; the platform injects the command file's content as a prompt.
| Platform | Location | Invoked as |
| ----------- | ------------------------------------------ | ---------------------------------- |
| Claude Code | `.claude/commands/trellis/{name}.md` | `/trellis:{name}` |
| Cursor | `.cursor/commands/trellis-{name}.md` | `/trellis-{name}` |
| OpenCode | `.opencode/commands/trellis/{name}.md` | `/trellis:{name}` |
| Codex | `.agents/skills/trellis-{name}/SKILL.md` | `/trellis-{name}` |
| Gemini CLI | `.gemini/commands/trellis/{name}.toml` | `/trellis:{name}` |
| Qoder | `.qoder/commands/trellis-{name}.md` | `/trellis-{name}` (Qoder CLI only) |
| CodeBuddy | `.codebuddy/commands/trellis/{name}.md` | `/trellis:{name}` |
| Droid | `.factory/commands/trellis/{name}.md` | `/trellis:{name}` |
| Pi Agent | `.pi/prompts/trellis-{name}.md` | `/trellis-{name}` |
| Copilot | `.github/prompts/trellis-{name}.prompt.md` | prompt-file picker |
Command files are Markdown; Gemini uses TOML (with a `prompt = """..."""` field).
**Workflow files** — platforms without a dedicated slash-command primitive; the user runs a "workflow" by name.
| Platform | Location | Invoked as |
| ----------- | ------------------------------------ | --------------------------------- |
| Kilo | `.kilocode/workflows/{name}.md` | `/{name}.md` (Kilo's workflow UI) |
| Antigravity | `.agent/workflows/{name}.md` | opened from `.agent/workflows/` |
| Devin | `.devin/workflows/trellis-{name}.md` | `/trellis-{name}` |
**Skill-only** — platforms that do not expose a slash-command primitive at all; `start` / `finish-work` / `continue` are shipped as auto-trigger skills.
| Platform | `start` / `finish-work` / `continue` as… | Invoked as |
| -------- | ---------------------------------------- | ---------------------------------- |
| Kiro | `.kiro/skills/trellis-{name}/SKILL.md` | skill match (or `@trellis:{name}`) |
### When to use a command vs. a skill
| Use a slash command when… | Use a skill when… |
| ----------------------------------------------------------- | ----------------------------------------------------------- |
| The user should decide when to run it | The AI should trigger it automatically based on intent |
| It marks a session boundary (start, finish, resume) | It's a phase inside a task (before-dev, check, update-spec) |
| There's no natural trigger phrase that would match reliably | There's a predictable user intent you can match on |
| You need it available even when no task is active | It only makes sense in the context of an active task |
If the answer is "both", ship a skill and expose a command that manually triggers the skill.
### Writing a command
A good command file:
1. Starts with a one-line description of what will happen.
2. Lists the steps the AI should take, in order.
3. Specifies files the AI should read before acting.
4. Defines the expected output format (report, checklist, diff, etc.).
Template:
````markdown theme={null}
# Command Name
Brief description of what this command does.
## Read context
```bash
cat .trellis/spec/relevant-spec.md
```
## Analyze
Describe what to analyze and against which rules.
## Report
Output format and fields.
````
### Example: a `/trellis:deploy-check` command
`.claude/commands/trellis/deploy-check.md`:
````markdown theme={null}
# Deploy Check
Pre-deployment verification checklist.
## Read deployment config
```bash
cat deploy.config.js
cat .env.production
```
## Verify
Check these items:
- [ ] All tests pass
- [ ] No TODO comments in production code
- [ ] Environment variables are set
- [ ] Database migrations are up to date
- [ ] API endpoints are documented
## Report
Output a deployment readiness report.
````
To ship the same command on other platforms, create parallel files in the platform-specific locations from the table above. If you want Trellis to distribute the command as part of its update flow, place a canonical copy under `packages/cli/src/templates/common/commands/` and add platform adapters in `packages/cli/src/configurators/`.
***
# Custom Hooks
Source: https://docs.trytrellis.app/beta/advanced/custom-hooks
## Custom Hooks
Hook support varies by platform and by event — see the per-event matrix below.
* **`SessionStart` hook / extension** ships on Claude Code, Cursor, OpenCode, Gemini CLI, Qoder, CodeBuddy, Copilot, Droid, Pi Agent. Codex relies on `AGENTS.md` plus the `UserPromptSubmit` hook; Kiro's Agent Hooks are user-configured — Trellis does not install any out of the box.
* **`PreToolUse` / extension sub-agent context injection** ships on Claude Code, Cursor, OpenCode, CodeBuddy, Droid, Pi Agent. The other hook-capable platforms rely on a pull-based prelude inside each sub-agent instead.
* **`UserPromptSubmit` / workflow-state nudge** ships on the same platforms as `SessionStart`, plus Codex when hooks are enabled.
* **Kilo, Antigravity, Devin** have no hook primitive at all; behavior is delivered via workflow files + skills.
### Hook types
| Hook | Trigger | Purpose |
| ------------------ | ------------------------ | -------------------------------------------- |
| `SessionStart` | A new session starts | Load context, initialize environment |
| `UserPromptSubmit` | User submits a prompt | Nudge the AI toward the current task state |
| `PreToolUse` | Before a tool invocation | Intercept, modify parameters, inject context |
| `PostToolUse` | After a tool invocation | Log activity, trigger follow-up actions |
Claude Code, Cursor, CodeBuddy, and Droid share a Python-hook layout compatible with CC's event model (`settings.json` or `hooks.json` referencing Python scripts). OpenCode uses JS plugins (factory functions in `.opencode/plugins/`) with the same event semantics. Pi Agent uses `.pi/extensions/trellis/index.ts` instead of Python hook files. Gemini, Qoder, and Copilot use hook/prompt files without `PreToolUse`. Codex installs the shared `UserPromptSubmit` workflow-state hook; its retained `session-start.py` is compatibility code, not the default model-visible startup path.
### `settings.json` configuration (Claude Code)
Configure hooks in `.claude/settings.json`:
```json theme={null}
{
"hooks": {
"SessionStart": [
{
"matcher": "startup",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.py\"",
"timeout": 10
}
]
}
],
"UserPromptSubmit": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/inject-workflow-state.py\"",
"timeout": 5
}
]
}
],
"PreToolUse": [
{
"matcher": "Task",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/inject-subagent-context.py\"",
"timeout": 30
}
]
}
]
}
}
```
Notes:
* Each event type is an array of `{ matcher, hooks }` blocks.
* `matcher`: pattern to match (`"startup"` matches session start, `"Task"` matches Task tool calls, `"*"` matches everything).
* `hooks`: array of commands that run when matched, in order.
* `$CLAUDE_PROJECT_DIR`: expanded by Claude Code to the project root.
* `timeout`: seconds; if exceeded, the hook is skipped.
Trellis does not install a Claude Code `statusLine` by default. New installs do not create `.claude/hooks/statusline.py` or add `statusLine` to `.claude/settings.json`, and `trellis update` never adds one to an opted-out project. Existing projects that already have a `statusLine` keep it during update.
To opt in, run `trellis init --with-statusline` (interactive non-`-y` init also asks once, default no). This installs `.claude/hooks/statusline.py` and adds the `statusLine` command to `.claude/settings.json`. The status line shows the active task, plus rate-limit reset countdowns and width-adaptive layout. It is Claude-Code-only and stays off unless you pass the flag, so it can never silently override a global `statusLine` config.
### Shipped hooks
#### `session-start.py`: context loading
**Trigger**: `SessionStart`.
**What it does**:
* Reads `.trellis/.developer` for developer identity.
* Reads `.trellis/workflow.md` for the workflow contract.
* Reads `.trellis/workspace/{name}/index.md` for session history.
* Reads `git log` for recent commits.
* Reads active tasks.
**Output**: emits all the context as a system message at the start of the session.
#### `inject-workflow-state.py`: workflow-state nudge
**Trigger**: `UserPromptSubmit`.
**What it does**: parses `[workflow-state:STATUS]` blocks from `.trellis/workflow.md` and emits the body matching the active task's `status` as a `` preamble for the turn. Parser-only — the hook does not embed any fallback body text. When the active task's status has no matching block, the hook emits the generic line `Refer to workflow.md for current step.` so the AI re-reads the workflow contract.
To customize per-turn wording, edit the `[workflow-state:STATUS]` block in `.trellis/workflow.md`. No script change required.
#### `inject-subagent-context.py`: spec injection engine
**Trigger**: `PreToolUse`, matching `Task` tool calls.
**What it does**:
* Intercepts Task tool calls.
* Reads the JSONL matching the `subagent_type` (`implement.jsonl` or `check.jsonl`).
* Reads all files referenced in the JSONL.
* Reads `prd.md`, `design.md` if present, and `implement.md` if present.
* Assembles the sub-agent prompt (specs + task artifacts + original instructions).
Design decisions:
* Each sub-agent receives its full context at launch; there is no resume.
* Only `trellis-*` sub-agents are hooked; custom sub-agents must opt in by editing this file or using their own injection.
#### Pi extension: equivalent hook behavior
Pi Agent does not load `.py` hook scripts. Trellis writes `.pi/extensions/trellis/index.ts`, which implements the same three behaviors in extension form:
* session start context injection
* workflow-state breadcrumb injection
* sub-agent JSONL and task artifact context injection
It also passes `TRELLIS_CONTEXT_ID` into Bash commands so `task.py start/current/finish` can resolve the correct `.trellis/.runtime/sessions/.json` file for the current Pi session.
### Writing a custom hook
Hooks receive JSON input on stdin and emit JSON results on stdout.
**Input format** (PreToolUse example):
```json theme={null}
{
"hook_event_name": "PreToolUse",
"tool_name": "Task",
"tool_input": {
"subagent_type": "trellis-implement",
"prompt": "..."
},
"cwd": "/path/to/project"
}
```
**Output format**:
```json theme={null}
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "allow",
"updatedInput": {
"subagent_type": "trellis-implement",
"prompt": "modified prompt..."
}
}
}
```
### Example: an auto-test hook
`.claude/hooks/auto-test.py`:
```python theme={null}
#!/usr/bin/env python3
"""Run tests automatically after an Edit tool call."""
import json
import subprocess
import sys
def main():
input_data = json.load(sys.stdin)
hook_event = input_data.get("hook_event_name", "")
tool_name = input_data.get("tool_name", "")
if hook_event != "PostToolUse" or tool_name != "Edit":
sys.exit(0)
file_path = input_data.get("tool_input", {}).get("file_path", "")
if not file_path.endswith((".ts", ".tsx")):
sys.exit(0)
result = subprocess.run(
["pnpm", "typecheck"],
capture_output=True,
timeout=30,
)
if result.returncode != 0:
output = {
"hookSpecificOutput": {
"message": f"TypeCheck failed after editing {file_path}:\n{result.stderr.decode()}"
}
}
print(json.dumps(output))
sys.exit(0)
if __name__ == "__main__":
main()
```
Register it in `settings.json`:
```json theme={null}
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit",
"hooks": [
{
"type": "command",
"command": "python3 .claude/hooks/auto-test.py"
}
]
}
]
}
}
```
***
# Custom Skills
Source: https://docs.trytrellis.app/beta/advanced/custom-skills
## Custom Skills
Skills are the primary extension point in Trellis. Most of the shipped workflow (brainstorm, before-dev, check, update-spec, break-loop) is delivered as auto-trigger skills. This chapter explains how to add your own.
### Commands vs. sub-agents vs. skills
| | Command | Sub-agent | Skill |
| ------------------ | ------------------------- | ------------------------------- | ---------------------------------------- |
| **Purpose** | Explicit user entry point | Isolated sub-process for a role | Reusable workflow module |
| **Trigger** | `/trellis:xxx` | Spawned via Task tool | Platform auto-matches on user intent |
| **Granularity** | Session boundary | Role-level | Capability or phase level |
| **Cross-platform** | One file per platform | One file per platform | One folder per platform (same structure) |
Use a skill when the AI should trigger it automatically based on context; use a command when the user should decide; use a sub-agent when the work needs isolation with its own prompt and restrictions.
### Skill file format
A skill is a folder containing `SKILL.md`:
```
.claude/skills/my-skill/
├── SKILL.md
└── references/ # optional supporting files the skill can reference
```
`SKILL.md` uses YAML frontmatter that the platform matches against:
```markdown theme={null}
---
name: my-skill
description: |
One-line description of when this skill should fire. Platforms match on this text to decide whether to auto-trigger.
---
# My Skill
Instructions the AI follows when this skill is triggered.
## Steps
1. Read the relevant files.
2. Apply the logic.
3. Report the result in this format: ...
```
Skills ship on all 22 configured platforms — the location differs per platform:
| Platform | Location |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| Claude Code | `.claude/skills/{name}/SKILL.md` |
| Cursor | `.cursor/skills/{name}/SKILL.md` |
| OpenCode | `.opencode/skills/{name}/SKILL.md` |
| Codex | `.agents/skills/{name}/SKILL.md` (shared layer; `.codex/skills/` is created empty for your own skills) |
| Kiro | `.kiro/skills/{name}/SKILL.md` |
| Gemini CLI | `.agents/skills/{name}/SKILL.md` (Gemini CLI 0.40+ reads the shared layer) |
| Qoder | `.qoder/skills/{name}/SKILL.md` |
| CodeBuddy | `.codebuddy/skills/{name}/SKILL.md` |
| Copilot | `.github/skills/{name}/SKILL.md` |
| Droid | `.factory/skills/{name}/SKILL.md` |
| Pi Agent | `.agents/skills/{name}/SKILL.md` (Pi reads the shared layer) |
| Oh My Pi | `.omp/skills/{name}/SKILL.md` |
| Kilo | `.kilocode/skills/{name}/SKILL.md` |
| Antigravity | `.agent/skills/{name}/SKILL.md` |
| Devin | `.devin/skills/{name}/SKILL.md` |
| Reasonix | `.reasonix/skills/{name}/SKILL.md` |
| ZCode | `.zcode/skills/{name}/SKILL.md` |
| Trae | `.trae/skills/{name}/SKILL.md` |
| Grok Build | `.grok/skills/{name}/SKILL.md` |
| Kimi Code | `.kimi-code/skills/{name}/SKILL.md` |
| Snow CLI | `.snow/skills/{name}/SKILL.md` |
`.agents/skills/{name}/SKILL.md` (the [agentskills.io](https://agentskills.io) cross-platform shared layer) is directly usable by Amp, Cline, Deep Agents, Firebender, Warp, and other agents that read the standard.
### Writing a skill that triggers reliably
The `description` field is what platforms match on. Write it as a description of the **condition that should cause this skill to fire**, not a description of the skill's name.
Examples:
```yaml theme={null}
# Good: describes the trigger
description: |
Use when the user reports a bug that was just fixed and wants to understand the root cause and prevent recurrence. Runs a 5-dimension analysis.
# Bad: describes the skill's identity
description: |
The break-loop skill analyzes bugs.
```
The skill body should:
1. State the trigger condition again, in the skill's own voice, so the AI can double-check that the match was correct.
2. Tell the AI exactly which files to read before acting.
3. Give a fixed output format so the result is consistent across invocations.
### Example: an `api-doc` skill
`.claude/skills/api-doc/SKILL.md`:
````markdown theme={null}
---
name: api-doc
description: |
Use when the user has just added or modified backend API endpoints and wants the OpenAPI doc updated. Parses the diff, extracts endpoint signatures, and writes the doc.
---
# api-doc
You auto-generate API documentation from the current diff.
## Trigger check
Before running, verify that the diff contains changes under `src/api/` or `src/routes/`. If not, ask the user to confirm before proceeding.
## Steps
1. Run `git diff --name-only HEAD` and list changed files.
2. For each changed endpoint file, extract the route, HTTP method, request schema, and response schema.
3. Update `docs/openapi.yaml` with the new or modified endpoints.
4. Report which endpoints were added, modified, or removed.
## Output format
```
Added endpoints:
POST /api/foo
Modified endpoints:
PUT /api/bar (request body changed)
Removed endpoints:
(none)
```
````
### Sharing skills
To distribute a skill across projects:
1. Put the canonical `SKILL.md` under `packages/cli/src/templates/common/skills/{name}/SKILL.md` (if contributing upstream) or publish it as its own npm package.
2. Add a configurator step per platform that copies or adapts the skill into that platform's layout.
3. Version the skill alongside the Trellis release so migrations stay consistent.
External skills: if you want to pull in a community skill, fetch the folder into the right platform directory and commit it. Trellis doesn't currently ship an automated installer for external skills.
***
# Custom Spec Template Marketplace
Source: https://docs.trytrellis.app/beta/advanced/custom-spec-template-marketplace
## Custom Spec Template Marketplace
A spec template marketplace is a Git-backed source that `trellis init --registry`
can read when a team wants the same `.trellis/spec/` starting point across many
repositories.
Use it for reusable engineering conventions: framework layout, API patterns,
testing rules, release rules, review checklists, and the examples that your
agents should see before writing code. Do not use it as a remote task store or
as a place for project-private runtime state.
### Runtime model
`trellis init --registry ` parses `` as a GitHub, GitLab, or
Bitbucket source, then probes for `index.json` inside that source path.
| Mode | Condition | Behavior |
| ---------------- | --------------------------------------------- | ----------------------------------------------------------------------- |
| Marketplace mode | `/index.json` exists and is valid | Trellis lists `type: "spec"` templates and installs the selected `id` |
| Direct mode | `/index.json` returns not found | Trellis downloads the source directory itself into `.trellis/spec/` |
| Error | `index.json` exists but is invalid/unreadable | Trellis stops instead of guessing direct mode from a broken marketplace |
Source format:
```text theme={null}
provider:user/repo[/subdir][#ref]
```
Examples:
```bash theme={null}
# Marketplace mode: source points at the directory that contains index.json
trellis init --registry gh:myorg/my-spec-marketplace/marketplace
# Install one template by id
trellis init --registry gh:myorg/my-spec-marketplace/marketplace --template web-app
# Direct mode: source points directly at one template directory
trellis init --registry gh:myorg/my-spec-marketplace/marketplace/specs/web-app
# Pin a branch or tag
trellis init --registry gh:myorg/my-spec-marketplace/marketplace#v1
```
### Repository shape
A common layout is:
```text theme={null}
my-spec-marketplace/
└── marketplace/
├── index.json
└── specs/
├── web-app/
│ ├── README.md
│ ├── frontend/
│ ├── backend/
│ ├── shared/
│ └── guides/
└── worker-service/
├── README.md
├── backend/
├── shared/
└── guides/
```
The template directory should contain the files that should appear inside
`.trellis/spec/`. Do not wrap them in an extra `spec/` folder unless you really
want `.trellis/spec/spec/...` after install.
The inner folder names are your convention. Trellis does not require
`frontend/`, `backend/`, `shared/`, or `guides/`; those are common because agents
can load focused specs more reliably when large rules are split by area.
### index.json contract
`index.json` lives at the registry source path. In the layout above, users point
`--registry` at `gh:myorg/my-spec-marketplace/marketplace`, so Trellis reads:
```text theme={null}
marketplace/index.json
```
Minimal marketplace index:
```json theme={null}
{
"version": 1,
"templates": [
{
"id": "web-app",
"type": "spec",
"name": "Web App",
"description": "Next.js + oRPC + PostgreSQL conventions",
"path": "marketplace/specs/web-app",
"tags": ["nextjs", "orpc", "postgres"]
}
]
}
```
Field rules:
| Field | Required | Meaning |
| ------------- | -------- | ---------------------------------------------------------------------- |
| `version` | Yes | Marketplace index version. Use `1` today. |
| `templates` | Yes | Array of template entries. |
| `id` | Yes | Stable CLI id used by `--template `. |
| `type` | Yes | Must be `"spec"` for spec templates. Other template types are ignored. |
| `name` | Yes | Human label shown in the interactive picker. |
| `description` | No | Short explanation shown beside the template. |
| `path` | Yes | Directory copied into `.trellis/spec/`, relative to repository root. |
| `tags` | No | Search and browsing hints for humans. |
The important detail is `path`: it is relative to the repository root, not
relative to the `index.json` file.
### Authoring workflow
1. Start from an existing template or create a new directory under
`marketplace/specs//`.
2. Put reusable rules in topical files. Keep package-specific examples real, but
remove project-only assumptions.
3. Add or update local `index.md` files if the folder uses them as navigation for
agents.
4. Add the template entry to `marketplace/index.json`.
5. Test from a throwaway repository before publishing the template.
Test commands:
```bash theme={null}
# Interactive picker
trellis init --registry gh:myorg/my-spec-marketplace/marketplace
# Non-interactive install
trellis init --registry gh:myorg/my-spec-marketplace/marketplace --template web-app
# Existing project: only add missing spec files
trellis init --registry gh:myorg/my-spec-marketplace/marketplace --template web-app --append
```
After install, the target project owns its `.trellis/spec/` files. The template
is a starting point, not a live remote wiki. Teams should edit the installed
specs so they match the actual repository.
### What belongs in a spec template
Good template content:
* Directory and module conventions for the stack.
* API, database, state, testing, and error-handling rules.
* Examples copied from real projects after removing private names and secrets.
* Review checklists that agents should apply before finishing work.
* Short guides that explain cross-layer tradeoffs for the stack.
Do not include:
* Secrets, internal URLs, customer data, or private incident details.
* `.trellis/tasks/`, `.trellis/workspace/`, or active task state.
* Platform prompt files such as `.claude/`, `.codex/`, `.cursor/`, or
`.opencode/`. Those belong in Trellis platform customization, not spec
templates.
* Product PRDs that only make sense for one repository.
### Versioning and rollout
Treat template ids as public API for your team. If you need a breaking rewrite,
publish a new id such as `web-app-v2` or pin the old behavior to a Git ref:
```bash theme={null}
trellis init --registry gh:myorg/my-spec-marketplace/marketplace#v1 --template web-app
```
For smaller edits, keep the same id and document the change in the template
`README.md`. Existing projects do not automatically become correct just because
the source template changed; review and merge spec updates intentionally.
### Troubleshooting
| Symptom | Check |
| -------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Picker does not show your templates | `index.json` must be at the registry source path and entries must use `type: "spec"`. |
| `--template web-app` says not found | `--template` matches `id`, not `name` or folder name. |
| Direct mode runs instead of marketplace mode | Trellis did not find `/index.json`. Point `--registry` at the marketplace folder. |
| Files land under `.trellis/spec/spec/` | The template directory contains an extra outer `spec/` folder. |
| Private registry fails | Use a source your local Git credentials can read, or set `GIGET_AUTH` for token-based use. |
| Agents ignore installed rules | Make specs specific, keep folder `index.md` files current, and reference real repo paths. |
### Relationship to the Resource Marketplace
The Resource Marketplace pages are the public catalog. This Advanced page is the
maintenance guide for creating your own registry. If you publish a generally
useful template, add a docs page under the template catalog after the registry
itself works.
# Custom Workflow Format
Source: https://docs.trytrellis.app/beta/advanced/custom-workflow
Create a workflow variant and preserve the markdown contracts used by session, per-turn, phase, and sub-agent runtime paths.
A workflow file is both documentation and runtime input. Trellis reads its
headings and marker blocks to build session context, per-turn guidance, and
step-level instructions.
## Start from the generated scaffold
Create a local workflow:
```bash theme={null}
trellis workflow create review-first
```
This writes `.trellis/workflows/review-first.md` from the complete bundled
native workflow. Starting from native is safer than writing an empty file
because every parser-sensitive section is already present.
The command then asks whether to make the workflow the project default and
whether to make it your personal default. Use `--skip-defaults` when you only
want the file.
The command never replaces or removes `.trellis/workflow.md`. That file remains the global
zero-configuration fallback.
## Understand the file layout
```text theme={null}
.trellis/
├── workflow.md
├── workflows/
│ └── review-first.md
├── config.yaml
└── .developer
```
The runtime chooses a file in this order:
1. Active task: `task.json` `workflow`
2. Current developer: `.developer` `workflow=`
3. Project: `config.yaml` `default_workflow`
4. Global fallback: `.trellis/workflow.md`
See [Dynamic Workflow Switching](/beta/advanced/dynamic-workflow-switching)
for the selection commands and current platform limits.
## Keep the runtime contract
The generated scaffold is the authoritative example. A smaller workflow can
work, but keep these structures:
```markdown theme={null}
## Phase Index
Phase 1: Plan
Phase 2: Execute
Phase 3: Finish
[workflow-state:no_task]
Explain what the agent should do when no task is active.
[/workflow-state:no_task]
[workflow-state:planning]
Explain the planning requirements.
[/workflow-state:planning]
[workflow-state:planning-inline]
Explain the Codex inline planning requirements.
[/workflow-state:planning-inline]
[workflow-state:in_progress]
Explain the implementation, verification, and finish flow.
[/workflow-state:in_progress]
[workflow-state:in_progress-inline]
Explain the Codex inline implementation flow.
[/workflow-state:in_progress-inline]
[workflow-state:completed]
Explain the completed-task action.
[/workflow-state:completed]
## Phase 1: Plan
#### 1.0 Create task
Detailed instructions for this step.
## Phase 2: Execute
#### 2.1 Implement
Detailed instructions for this step.
## Phase 3: Finish
#### 3.4 Commit changes
Detailed instructions for this step.
```
The parser-sensitive parts are:
| Structure | Consumer | Requirement |
| ------------------------------ | ------------------------------------ | ----------------------------------------------------- |
| `## Phase Index` | SessionStart | Exact heading; its content ends at `## Phase 1: Plan` |
| `## Phase 1: Plan` | SessionStart boundary | Keep this exact heading |
| `#### X.Y` | `get_context.py --mode phase --step` | Use numeric step ids such as `2.1` |
| `[workflow-state:STATUS]` pair | Per-turn hook | Opening and closing status must match |
| Platform marker pair | Phase renderer | Opening and closing platform lists must match |
Standard workflow-state ids are `no_task`, `planning`, `planning-inline`,
`in_progress`, `in_progress-inline`, and `completed`. Custom ids may use
letters, digits, underscores, and hyphens, but they only become active when
some task lifecycle path writes the matching `task.json.status`.
## Route instructions by platform
Platform blocks are optional. Use them when one step needs different
instructions for different harnesses:
```markdown theme={null}
[Claude Code, Cursor, OpenCode, codex-sub-agent]
Dispatch the implementation agent with the active task context.
[/Claude Code, Cursor, OpenCode, codex-sub-agent]
[codex-inline, Kilo, Antigravity, Devin]
Load the project specs and implement in the main session.
[/codex-inline, Kilo, Antigravity, Devin]
```
Platform matching ignores case, spaces, hyphens, and underscores. Marker lines
must contain only the bracketed platform list.
## Know what hooks read
Hooks are installed by `trellis init` and `trellis update`. Do not declare
hook event names or script commands inside a workflow file.
| Runtime path | What it reads from the selected workflow |
| ----------------------------- | ------------------------------------------------------- |
| SessionStart | `## Phase Index` overview |
| Per-turn workflow-state hook | The block matching the current task status |
| `get_context.py --mode phase` | Phase index or one `#### X.Y` step |
| Parent session dispatch | Agent-routing instructions written in the selected step |
The sub-agent hook is separate. It injects `implement.jsonl` or `check.jsonl`,
then `prd.md`, `design.md` when present, and `implement.md` when present. It
does not parse workflow markdown. The selected workflow tells the parent
session when and how to dispatch; the sub-agent hook supplies the task-specific
material.
## Validate after editing
Run the real phase parser:
```bash theme={null}
python3 ./.trellis/scripts/get_context.py --mode phase
python3 ./.trellis/scripts/get_context.py --mode phase --step 2.1
python3 ./.trellis/scripts/get_context.py --mode phase --step 2.1 --platform claude
python3 ./.trellis/scripts/get_context.py --mode phase --step 2.1 --platform codex
```
Use `python` instead of `python3` on Windows.
`trellis workflow --save` warns when a marketplace template is missing the
standard phase, step, or workflow-state markers. The warning does not block
the save, so the parser commands above remain the final check for custom
content.
## Safe editing boundary
You can freely change prose, add phases, change routing instructions, and add
custom statuses. Preserve the parser syntax unless you also update every
runtime consumer.
Changes to workflow-state text appear on the next user turn. SessionStart
overview changes appear in a new session. Step changes appear on the next
`get_context.py --mode phase` lookup.
## Related pages
* [Dynamic Workflow Switching](/beta/advanced/dynamic-workflow-switching)
* [Dynamic Spec Loading](/beta/advanced/dynamic-spec-loading)
* [Everyday Use](/beta/start/everyday-use)
# Dynamic Spec Loading
Source: https://docs.trytrellis.app/beta/advanced/dynamic-spec-loading
Load the project rules that govern a file at the moment an agent reads or changes it.
Trellis can attach specs to code paths and deliver the matching rules when an
agent touches a file. This keeps the prompt small while putting the relevant
rules close to the edit they govern.
## Declare which paths a spec governs
Add a `paths` list to the spec's YAML frontmatter. Paths are relative to the
repository root.
```md theme={null}
---
name: commands-workflow
description: Workflow command and resolver contracts
paths:
- packages/cli/src/commands/workflow.ts
- packages/cli/src/utils/workflow-resolver.ts
- packages/cli/test/commands/workflow*.test.ts
---
# Workflow command rules
...
```
The matcher supports:
* `*` within one path segment
* `**` across path segments
* `?` for one character
* a trailing `/` as shorthand for everything below that directory
Specs without `paths` frontmatter keep their existing behavior. They are not
loaded automatically.
## What the agent receives
For each matching spec, Trellis chooses one of three deliveries:
| Situation | Delivery |
| ---------------------------------------- | --------------------------------------------- |
| First matching touch in a session | Full, budgeted spec body |
| Unchanged spec inside the refresh window | No repeated output |
| Unchanged spec after the refresh window | Short ticket with the spec path and read hint |
| Spec content changed | Full body again |
| Session was cleared or compacted | Full body again on the next matching touch |
The refresh window is fixed. Silent touches do not extend it, so continuous
editing still receives a later reminder.
When several specs match one file, narrower path patterns are considered
before broad patterns. If the event budget cannot hold every full body,
remaining matches become an index of spec paths instead of disappearing.
## Platform behavior
| Platform | Trigger | Behavior |
| --------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Code | `PostToolUse` for `Read`, `Edit`, `Write`, and `MultiEdit` | Delivers matching context after the file operation. Claude Code's read-before-write behavior usually loads the rules before the later edit. |
| Codex | `PreToolUse` for native `apply_patch` | Parses every add, update, delete, and move header before the patch runs. |
| OpenCode | `tool.execute.before` for `write`, `edit`, `apply_patch` | Blocks a newly governed mutation once, returns the specs as a model-visible tool error, then allows the model's retry. |
| Other platforms | Pull mode | Query matching spec paths explicitly with `get_context.py`. |
### Why Codex and OpenCode block the first mutation once
Codex and OpenCode do not require a file read before an edit. When a mutation
first matches a spec, Trellis returns the full rules and blocks that call once:
```text theme={null}
mutation requested
→ Trellis injects governing specs
→ mutation is blocked
→ the model reads the specs and retries
→ retry proceeds
```
Only a newly delivered **full** spec blocks the patch. A short refresh ticket
does not block, and an unchanged spec inside the refresh window produces no
output. Codex receives a native hook denial. OpenCode receives the same context
inside a tool error because its stable plugin API has no direct
`additionalContext` return field. This is a context-delivery handshake, not a
policy rejection.
## Configure the budget and refresh window
The defaults fit the host context limits and require no configuration:
```yaml theme={null}
spec_injection:
enabled: true
max_spec_chars: 9400
max_total_chars: 9500
refresh_window_seconds: 2700
tools: [Read, Edit, Write, MultiEdit]
```
| Key | Meaning |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled` | Set to `false` to disable dynamic spec loading. |
| `max_spec_chars` | Maximum characters from one spec. `0` removes this limit. |
| `max_total_chars` | Maximum characters for one hook event. `0` removes this limit. |
| `refresh_window_seconds` | Seconds before an unchanged spec gets a short ticket. `0` disables time-based refresh. |
| `tools` | Logical tool names that can trigger matching. Codex and OpenCode `apply_patch` use `Edit`; OpenCode `write` and `edit` use `Write` and `Edit`. An empty list disables every trigger. |
Truncated bodies include a notice with the full spec path so the agent can read
the source file directly.
## Inspect matches manually
Use pull mode to check which specs govern a path without loading their bodies:
```bash theme={null}
# macOS and Linux
python3 ./.trellis/scripts/get_context.py --mode spec \
--file packages/cli/src/commands/workflow.ts
# Windows
python ./.trellis/scripts/get_context.py --mode spec \
--file packages/cli/src/commands/workflow.ts
```
Add `--json` for structured output:
```bash theme={null}
python3 ./.trellis/scripts/get_context.py --mode spec \
--file packages/cli/src/commands/workflow.ts \
--json
```
An empty match is valid and returns no governing specs.
## State, reset, and failure behavior
Delivery state is stored outside the repository under
`~/.trellis/spec-inject/`. Parent and sub-agent histories are separate.
Claude Code and Codex use `SessionStart(source=clear|compact)` to record a
shared reset marker. OpenCode maps `session.compacted` to the same compact
reset, so rules removed by compaction are delivered again.
The hook does not parse Claude Code, Codex, or OpenCode transcript contents.
Transcript formats are host internals and are not part of this contract.
Matching and state failures are fail-open: malformed frontmatter, missing
paths, unreadable or unwritable state, or an internal hook error must not break
the host tool call. The only intentional block is the first Codex or OpenCode
mutation that has just received a full governing spec with persisted delivery
state.
## Related pages
* [Dynamic Workflow Switching](/beta/advanced/dynamic-workflow-switching)
* [Custom Hooks](/beta/advanced/custom-hooks)
* [Architecture](/beta/advanced/architecture)
# Dynamic Workflow Switching
Source: https://docs.trytrellis.app/beta/advanced/dynamic-workflow-switching
Select workflow variants per task, developer, or team without replacing the global workflow.
Trellis 0.7 separates the global workflow from a library of workflow variants.
Different tasks can use different variants while the project keeps one safe
fallback.
## Global switching and task selection are different
`trellis workflow --template ` replaces the global
`.trellis/workflow.md`. Use it when the project as a whole should move to a
different workflow.
Dynamic selection keeps variants under `.trellis/workflows/` and resolves one
at runtime for the active task. It does not overwrite the global workflow.
## Create a local workflow
Create a complete, editable workflow from the bundled native workflow:
```bash theme={null}
trellis workflow create review-first
```
Trellis writes `.trellis/workflows/review-first.md`, then asks two questions
in order:
1. Set `default_workflow: review-first` in `.trellis/config.yaml`?
2. Set `workflow=review-first` in `.trellis/.developer`?
Both default to no. The workflow file is created regardless of the answers.
Use `--skip-defaults` to create the file without prompts. Non-interactive
execution also skips the prompts.
The command copies the full native workflow so the new file already contains
the required phase headings, workflow-state blocks, and platform markers. It
never changes or removes the global `.trellis/workflow.md`.
## Save workflow variants to the project library
List bundled, marketplace, and already-saved workflows:
```bash theme={null}
trellis workflow --list
```
Save a variant:
```bash theme={null}
trellis workflow --save tdd
trellis workflow --save channel-driven-subagent-dispatch
```
Use another marketplace source when needed:
```bash theme={null}
trellis workflow \
--marketplace owner/repository \
--save my-workflow
```
The result is a user-managed file:
```text theme={null}
.trellis/workflows/
├── tdd.md
├── channel-driven-subagent-dispatch.md
└── my-workflow.md
```
`trellis update` does not overwrite files in this library. Re-run
`trellis workflow --save --force` when you intentionally want to refresh
a saved template.
## Pin a workflow to a task
Choose the workflow when creating a task:
```bash theme={null}
python3 ./.trellis/scripts/task.py create \
"Add checkout validation" \
--workflow tdd
```
Change the active task's selection:
```bash theme={null}
python3 ./.trellis/scripts/task.py workflow tdd
```
Clear the task pin and return to the default chain:
```bash theme={null}
python3 ./.trellis/scripts/task.py workflow --clear
```
The selected id is stored in `task.json`:
```json theme={null}
{
"workflow": "tdd"
}
```
The task pin only works when `.trellis/workflows/tdd.md` exists. A missing or
invalid variant prints a warning and falls through to the next default.
## Configure personal and team defaults
Runtime resolution uses one precedence chain:
| Priority | Source | Scope | Committed |
| -------: | ---------------------------------------------- | ------------------------------ | :-------: |
| 1 | `task.json` `workflow` | Current task | Yes |
| 2 | `.trellis/.developer` `workflow=` | Current developer and checkout | No |
| 3 | `.trellis/config.yaml` `default_workflow` | Team | Yes |
| 4 | `.trellis/workflow.md` | Project fallback | Yes |
Set a team default:
```yaml theme={null}
# .trellis/config.yaml
default_workflow: tdd
```
Set a personal override:
```ini theme={null}
# .trellis/.developer
name=alice
workflow=native
```
The personal file is gitignored, so one developer can prefer `native` while
the team default remains `tdd`. An explicit task pin still wins over both.
When a layer is unset, invalid, or points to a missing file, resolution
continues downward. If none of the optional layers apply, behavior is
identical to reading `.trellis/workflow.md` directly.
## What changes at runtime
The resolved workflow supplies all runtime workflow content:
* the Phase Index shown at session start
* the per-turn `[workflow-state:*]` breadcrumb
* phase and step details returned by `get_context.py --mode phase`
* Codex inline versus sub-agent dispatch guidance
Consumers share the same resolver, so changing a task pin takes effect on the
next workflow lookup. No new hook is installed for the switch.
## Keep variant files compatible
A workflow variant is executable input, not only prose. Keep these parser
markers:
* a `## Phase Index` section
* `#### X.Y` step headings
* `[workflow-state:STATUS]...[/workflow-state:STATUS]` blocks
* any platform routing markers used by your workflow
`trellis workflow --save` warns when a saved template is missing the standard
markers. The warning does not block custom workflows, but missing markers can
degrade session-start context, breadcrumbs, or phase lookup.
Workflow ids must match `[A-Za-z0-9_-]+`. This keeps every id inside
`.trellis/workflows/` and prevents path traversal.
## Current limits
* Selection is explicit. Trellis does not infer a workflow from task type.
* The Oh My Pi extension still reads the global `.trellis/workflow.md`; task,
personal, and team selection does not apply to it yet.
* OpenCode per-turn breadcrumbs honor dynamic selection, but its SessionStart
summary still reads the global workflow.
* Snow SessionStart and per-message context still read the global workflow.
* A saved marketplace workflow is a local copy. It does not update until you
save it again with `--force`.
## Related pages
* [Custom Workflow](/beta/advanced/custom-workflow)
* [Dynamic Spec Loading](/beta/advanced/dynamic-spec-loading)
* [Everyday Use](/beta/start/everyday-use)
# Multi-Platform and Team Configuration
Source: https://docs.trytrellis.app/beta/advanced/multi-platform
## Multi-Platform and Team Configuration
Trellis ships on 22 platforms (Claude Code, Cursor, OpenCode, Codex, Kiro, Kilo, Gemini CLI, Antigravity, Devin (formerly Windsurf), Qoder, CodeBuddy, GitHub Copilot, Droid, Pi Agent, Oh My Pi, Reasonix, ZCode, Trae, Grok Build, Kimi Code, Snow CLI, DeepSeek Harness) and additionally supports any AI coding agent that reads the `.agents/skills/` standard (Amp, Cline, Deep Agents, Firebender, Warp, and more). The `.trellis/` core is identical everywhere; what differs is **how hooks, extensions, skills, sub-agents, and commands are delivered** on each platform.
### Joining an Already-Initialized Trellis Project
Someone else already ran `trellis init` on the repo and you're joining as a new team member. Just run `trellis init` — the CLI detects the existing setup and offers three choices:
```
? Trellis is already initialized. What would you like to do?
❯ Add AI platform(s)
Set up developer identity on this device
Full re-initialize
```
| Option | When to pick |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Add AI platform(s)** | You want to add a platform others haven't configured (e.g. you use Cursor but the team only set up Claude Code) |
| **Set up developer identity on this device** | You're a new member, you just need to write your **identity** on your machine |
| **Full re-initialize** | Project config is broken and you want a clean slate |
New members pick the second option. The CLI asks for your developer name (defaulting to your Git user), then:
* Writes `.trellis/.developer` with your developer name (gitignored, per-machine)
* Creates `.trellis/workspace//` for your own journal
After that, on platforms with a SessionStart hook or extension, opening a new session auto-injects Trellis context. On platforms without automatic session injection, run `/trellis:start` or the platform's start workflow.
Don't pick **Full re-initialize** — it overwrites existing `.trellis/`, `.claude/`, etc.
configuration and affects the whole team.
### Capability Matrix
| Capability | Claude Code | Cursor | OpenCode | Codex | Kiro | Gemini | Qoder | CodeBuddy | Copilot | Droid | Pi Agent | Oh My Pi |
| ------------------------------ | :---------: | :----: | :------: | :---: | :--: | :----: | :---: | :-------: | :-----: | :---: | :------: | :------: |
| SessionStart / startup context | ✅ | ✅ | ✅ | ⚡ | ⚡ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Sub-agent context injection | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ✅ |
| Dynamic spec loading | ✅ | pull | ✅ | ✅ | pull | pull | pull | pull | pull | pull | pull | pull |
| Sub-agents (`trellis-*`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Auto-trigger skills | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Explicit `/trellis:*` commands | ✅ | ✅ | ✅ | — | — | ✅ | ⚡ | ✅ | ✅ | ✅ | ✅ | ✅ |
Legend: ✅ Trellis wires the config and the platform executes it · ⚡ Partial
(Codex uses `AGENTS.md` plus `UserPromptSubmit`; workflow breadcrumbs require
`features.hooks = true` and a one-time `/hooks` review on 0.129+. Kiro ships a
per-turn `userPromptSubmit` hook on the `trellis` agent, but the user must
activate that agent — `chat.defaultAgent trellis` or `/agent swap`) · ❌ the
platform does not expose this event · — the platform has no command primitive; start / finish-work /
continue are delivered as skills instead. Qoder uses `/trellis-{name}` (hyphen,
not colon) for `finish-work` / `continue`, but only in the Qoder CLI — the IDE's
`/` menu lists instructions configured in the Qoder console and does not read
project files; `start` is covered by its SessionStart hook. Pi Agent uses an extension rather than
Python hook files, but the behavior is the same: session context, Bash
environment propagation, and sub-agent context injection are handled before the
agent acts. `pull` means the platform can resolve governing spec paths through
`get_context.py --mode spec`, but Trellis does not push those specs into tool
execution automatically.
`.kilocode/`, `.agent/` (Antigravity), and `.devin/` are workflow-and-skill only: no sub-agents and no hooks. `.agents/skills/` is written by every platform as a cross-platform shared layer.
### Claude Code
Most complete automation. Hook layout:
| Hook | Trigger | Effect |
| ---------------------------- | ----------------- | ---------------------------------------------- |
| `session-start.py` | SessionStart | Injects identity, git status, active tasks |
| `inject-workflow-state.py` | UserPromptSubmit | Nudges the AI toward the current task's state |
| `inject-subagent-context.py` | PreToolUse (Task) | Loads `implement.jsonl` / `check.jsonl` / etc. |
Sub-agents: `trellis-implement`, `trellis-check`, `trellis-research` under `.claude/agents/`.
Skills: `trellis-brainstorm`, `trellis-before-dev`, `trellis-check`, `trellis-update-spec`, `trellis-break-loop` under `.claude/skills/`.
Commands: `start`, `finish-work`, `continue` under `.claude/commands/trellis/`.
### Cursor
```bash theme={null}
trellis init -u your-name --cursor
```
Cursor is a full class-1 platform: real hooks, real sub-agents, real skills.
Layout:
* `.cursor/commands/trellis-{name}.md`: `start`, `finish-work`, `continue` (flat file naming with `trellis-` prefix, invoked as `/trellis-start` etc.)
* `.cursor/skills/trellis-{name}/SKILL.md`: the trellis skills
* `.cursor/agents/`: `trellis-implement.md`, `trellis-check.md`, `trellis-research.md`
* `.cursor/hooks/`: shared Python hook scripts (Claude-Code-compatible)
* `.cursor/hooks.json`: hook configuration (Cursor uses a separate file, not `settings.json`)
### OpenCode
```bash theme={null}
trellis init -u your-name --opencode
```
OpenCode 1.2.x is a class-1 platform (real hooks + real sub-agents):
* `.opencode/commands/trellis/`: start / finish-work / continue
* `.opencode/agents/`: `trellis-implement.md`, `trellis-check.md`, `trellis-research.md`
* `.opencode/skills/`: the trellis skills
* `.opencode/plugins/`: JS plugins: `session-start.js`, `inject-subagent-context.js`, `inject-workflow-state.js`, `inject-spec-context.js`
* `.opencode/hooks/inject-spec-context.py`: shared path matching, budgets, and delivery state
Plugins are factory functions (OpenCode 1.2+). Dynamic spec loading intercepts
`write`, `edit`, and `apply_patch`; a newly matched full spec blocks the first
mutation as a model-visible tool error, then the retry proceeds.
### Codex
```bash theme={null}
trellis init -u your-name --codex
```
Layout:
* `AGENTS.md` (repo root): entry file; Codex auto-reads it every session (acts as the prelude)
* `.agents/skills/trellis-{name}/SKILL.md`: the trellis skills (shared layer; Codex reads it natively)
* `.codex/skills/`: created empty, for skills you add yourself
* `.codex/agents/`: TOML sub-agents: `trellis-implement.toml`, `trellis-check.toml`, `trellis-research.toml`
* `.codex/hooks/inject-workflow-state.py` + `.codex/hooks.json`: `UserPromptSubmit` workflow-state hook
* `.codex/hooks/session-start.py`: retained compact SessionStart compatibility script, not wired by default
**Codex hooks must be enabled, or typing `/` in the chat won't surface Trellis's three commands (`/start`, `/finish-work`, `/continue`) and you can't launch a session with `/start`.** Add to `~/.codex/config.toml`:
```toml theme={null}
[features]
hooks = true # Codex 0.129+. Older versions: `codex_hooks = true`.
```
Codex 0.129+ also gates each installed hook behind a one-time `/hooks` TUI review — run `/hooks` once in Codex and approve the Trellis `UserPromptSubmit` hook, otherwise the hooks stay inactive, Trellis's commands/skills won't appear in the `/` menu, and the workflow breadcrumb won't auto-inject. Without these two steps Codex runs prelude-only (reads `AGENTS.md` every session): the context is still there, but you can't invoke Trellis commands from `/`.
### Kiro
```bash theme={null}
trellis init -u your-name --kiro
```
Layout:
* `.kiro/agents/trellis.json`: main Trellis agent — per-turn `userPromptSubmit` hook + session-start `agentSpawn` hook + `.trellis/workflow.md` as an always-loaded resource
* `.kiro/agents/trellis-{implement,check,research}.json`: sub-agents (`agentSpawn` injects task context)
* `.kiro/hooks/*.py` + `.kiro/hooks/trellis-workflow-state.kiro.hook`: the per-turn workflow-state injector (CLI agent hook + IDE `.kiro.hook`)
* `.kiro/skills/*/SKILL.md`: auto-trigger skills
**Enable it (required — otherwise the workflow won't activate):**
* **Kiro CLI**: make `trellis` the active agent so its hooks fire — `kiro-cli settings chat.defaultAgent trellis` (persists) or `/agent swap trellis` (per session). Kiro otherwise runs the built-in `kiro_default` agent.
* **Kiro IDE**: the `.kiro/hooks/trellis-workflow-state.kiro.hook` (a `promptSubmit` hook) ships enabled; confirm it's on/trusted in Kiro's Agent Hooks UI.
The per-turn injection prints plain text that Kiro adds to the conversation context, per Kiro's
official hooks docs. The exact stdout-to-context behavior (and whether the IDE `runCommand` action
injects stdout) is pending verification on real Kiro hardware; if it doesn't, the fallback is a
static steering nudge.
### Gemini CLI
```bash theme={null}
trellis init -u your-name --gemini
```
Layout:
* `.gemini/commands/trellis/{name}.toml`: TOML command files — `start.toml`, `finish-work.toml`, `continue.toml`
* `.agents/skills/trellis-{name}/SKILL.md`: the trellis skills (shared layer; Gemini CLI 0.40+ reads it natively)
* `.gemini/agents/{name}.md`: sub-agent definitions with pull-based prelude (sub-agents `Read` their own JSONL because Gemini has no sub-agent `PreToolUse` hook)
* `.gemini/hooks/session-start.py`: SessionStart hook
* `.gemini/settings.json`: hook configuration (SessionStart only)
### Qoder
```bash theme={null}
trellis init -u your-name --qoder
```
Skills work on both the Qoder IDE and the Qoder CLI. Commands work on the CLI only — the IDE's `/` menu lists instructions an administrator configures in the Qoder console and does not read files from your project, so Trellis's commands will not appear there. On the IDE, use the skills: the model triggers them from what you ask for.
Layout:
* `.qoder/skills/trellis-{name}/SKILL.md`: auto-trigger workflow skills — `brainstorm`, `before-dev`, `check`, `update-spec`, `break-loop`. Read by both the IDE and the CLI.
* `.qoder/commands/trellis-{name}.md`: session-boundary commands — `finish-work`, `continue` — invoked as `/trellis-finish-work`, `/trellis-continue` **in the Qoder CLI**. The SessionStart hook already injects the "start" context, so there is no `trellis-start` command.
* `.qoder/agents/{name}.md`: sub-agent definitions with pull-based prelude
* `.qoder/hooks/session-start.py`: SessionStart hook, on startup / clear / compact
* `.qoder/hooks/inject-workflow-state.py`: UserPromptSubmit hook
* `.qoder/hooks/inject-shell-session-context.py`: PreToolUse hook on `Bash|run_in_terminal`, which carries the session identity into `task.py`
* `.qoder/settings.json`: hook configuration. Qoder has no sub-agent `PreToolUse` hook, so sub-agents load their context through the pull-based prelude instead.
### CodeBuddy
```bash theme={null}
trellis init -u your-name --codebuddy
```
CodeBuddy is a full class-1 platform (real hooks + real sub-agents).
Layout:
* `.codebuddy/commands/trellis/{name}.md`: `start`, `finish-work`, `continue`
* `.codebuddy/skills/trellis-{name}/SKILL.md`: the trellis skills
* `.codebuddy/agents/{name}.md`: sub-agent definitions
* `.codebuddy/hooks/*.py`: shared Python hook scripts
* `.codebuddy/settings.json`: hook configuration (SessionStart + `PreToolUse` sub-agent injection)
### GitHub Copilot
```bash theme={null}
trellis init -u your-name --copilot
```
Layout:
* `.github/copilot-instructions.md`: the Trellis prelude, loaded automatically every session
* `.github/prompts/trellis-{name}.prompt.md`: prompt files for `start` / `finish-work` / `continue`
* `.github/skills/trellis-{name}/SKILL.md`: the trellis skills
* `.github/agents/{name}.agent.md`: sub-agent definitions with pull-based prelude (Copilot's sub-agent hook does not fire reliably, so sub-agents `Read` their own JSONL)
* `.github/copilot/hooks/*.py`: Copilot-specific + shared Python hook scripts
* `.github/copilot/hooks.json`: hook configuration (SessionStart only — sub-agent `PreToolUse` is absent)
### Droid
```bash theme={null}
trellis init -u your-name --droid
```
Droid (factory.ai) is a class-1 platform with hooks + sub-agents:
* `.factory/commands/trellis/`: start / finish-work / continue
* `.factory/droids/`: the three `trellis-*` sub-agents
* `.factory/skills/`: the trellis skills
* `.factory/hooks/`: SessionStart + sub-agent injection
### Pi Agent
```bash theme={null}
trellis init -u your-name --pi
```
Pi Agent is extension-backed rather than Python-hook-backed. Trellis writes the same workflow primitives, then the extension resolves the current session id and injects task context before Bash commands and sub-agent runs.
Layout:
* `.pi/prompts/trellis-{name}.md`: session-boundary prompts (`finish-work`, `continue`; `start` only where applicable)
* `.agents/skills/trellis-{name}/SKILL.md`: the five Trellis workflow skills (shared layer; Pi reads it natively)
* `.pi/agents/{name}.md`: `trellis-implement`, `trellis-check`, `trellis-research`
* `.pi/extensions/trellis/index.ts`: session context, Bash `TRELLIS_CONTEXT_ID` propagation, and sub-agent JSONL injection
* `.pi/settings.json`: extension registration
The extension stores active task state under `.trellis/.runtime/sessions/.json`, so each Pi window/session can work on its own task without taking over another window.
### Oh My Pi
```bash theme={null}
trellis init -u your-name --omp
```
Oh My Pi is extension-backed, like Pi Agent. Trellis writes the same workflow primitives, then the extension resolves the current session id and injects task context before Bash commands and sub-agent runs. Unlike Pi Agent, Oh My Pi has no `settings.json` — the native provider auto-discovers all subdirectories under `.omp/`.
Layout:
* `.omp/commands/trellis-{name}.md`: session-boundary prompts (`finish-work`, `continue`; `start` only where applicable)
* `.omp/skills/trellis-{name}/SKILL.md`: the five Trellis workflow skills
* `.omp/agents/{name}.md`: `trellis-implement`, `trellis-check`, `trellis-research`
* `.omp/extensions/trellis/index.ts`: session context, Bash `TRELLIS_CONTEXT_ID` propagation, and sub-agent JSONL injection
The extension stores active task state under `.trellis/.runtime/sessions/.json`, so each Oh My Pi window/session can work on its own task without taking over another window.
### Other supported platforms
Trellis also ships configurators for platforms not covered by the capability matrix:
* **Kilo** (`--kilo`): writes `.kilocode/workflows/` (commands: `start`, `finish-work`) and `.kilocode/skills/trellis-{name}/SKILL.md` (the trellis skills). No hook integration.
* **Antigravity** (`--antigravity`): writes Antigravity-native workflow files for the three commands.
* **Devin** (`--devin`, formerly Windsurf): writes Devin-native workflow and skill files. The old `--windsurf` flag still works as a deprecated alias.
* **Reasonix** (`--reasonix`): writes `.reasonix/` skills and sub-agents; commands are invoked as `/skill trellis-{name}`. No hook integration, so the sub-agent loads its own task context.
* **ZCode** (`--zcode`): writes `.zcode/agents/`, `.zcode/commands/`, `.zcode/skills/`, and `.zcode/hooks/`. Commands use the `/trellis:` prefix.
* **Trae** (`--trae`): writes `.trae/` agents, commands, skills, and Python hooks (SessionStart, workflow-state, sub-agent context injection).
* **Grok Build** (`--grok`): writes `.grok/skills/`, `.grok/commands/`, `.grok/agents/`. Sub-agents are dispatched with `spawn_subagent`. No hook integration.
* **Kimi Code** (`--kimi`): writes skills to `.kimi-code/skills/` plus the shared `.agents/skills/` layer; entry points are invoked as `/skill:trellis-{name}`. No project-level hooks (Kimi only supports a user-level `~/.kimi-code/config.toml`).
* **Snow CLI** (`--snow`): writes `.snow/skills/`, `.snow/commands/`, `.snow/agents/`, and `.snow/hooks/` (Python hooks emit `additionalContext` JSON for session / user / sub-agent events).
* **DeepSeek Harness** (`--dsh`): writes the shared workflow layer to `.agents/skills/`, user-invocable entry skills to `.dsh/skills/trellis-*`, and collision-free, non-user-invocable child roles to `.dsh/skills/trellis-agent-*`. The main session dispatches DSH's native continuable `subagent` and each child loads exactly one role skill plus its pull-based task context. If the optional [`dsh-trellis`](https://github.com/SajoLuo/dsh-trellis) companion exposes `trellis_wait`, dependent phases wait on the native settlement event while independent work may continue; without the plugin, the child is dispatched in the foreground from the start. Neither path uses shell sleep or polling, and `trellis init --dsh` does not install the profile plugin.
DSH also inherits ordinary environment variables from its launcher. When it is started inside an already-active Trellis session, an outer `TRELLIS_CONTEXT_ID` would otherwise override DSH's native session id. DSH rebuilds its complete `DSH_*` namespace for each managed shell, so the beta adapter treats `DSH_SHELL=1` together with `DSH_SESSION_ID` as the current DSH identity and resolves it before an inherited generic override, even without the plugin. The optional companion additionally publishes a trusted, per-execution `DSH_TRELLIS_CONTEXT_ID` when it must forward a child identity that differs from the shell's own session id.
Each `dsh --profile headless` invocation creates a fresh DSH session. Keep a task flow in one session or explicitly resume its returned session id; separate headless invocations do not share an active-task pointer automatically.
Beyond the 22 configured platforms, Trellis can be consumed by any AI coding agent that follows the `.agents/skills/` convention (the [agentskills.io](https://agentskills.io) standard). Codex writes its skills there, and the files are directly usable by other agents in that ecosystem (Amp, Cline, Deep Agents, Firebender, Warp, and more). On those platforms you manage Trellis through the `.trellis/` core plus whatever prelude file the agent reads.
### Operating Systems
| OS | Status | Notes |
| ----------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| **macOS** | ✅ Full | Primary platform |
| **Linux** | ✅ Full | Verified |
| **Windows** | ✅ Full | Scripts are Python; Claude Code sets `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1` so hooks cwd resolves correctly |
Python 3.9+ is required for `.trellis/scripts/` and any Python hooks. OpenCode plugins use Node.js 18+.
### Multi-Developer Collaboration
Per-developer isolation (no conflicts):
* `.trellis/workspace/{name}/`: each developer's own journals and index
* `.trellis/.developer`: gitignored
* `.trellis/.runtime/`: gitignored session runtime; each AI session/window has its own active task file
Shared state (coordinate via PR):
* `.trellis/spec/`: team conventions, PR-reviewed like any code
* `.trellis/tasks/`: task JSONs; explicit `--assignee` avoids collisions
Important spec changes should be discussed in reviews; treat the spec library as team code.
### `trellis update` and Version Management
```bash theme={null}
cat .trellis/.version # current version
trellis update # update to latest
trellis update --dry-run # preview
trellis update --migrate # apply breaking-change migrations (required for major)
trellis update -f # force overwrite locally-modified files
trellis update -s # skip locally-modified files
```
Template hash mechanism (`.trellis/.template-hashes.json`):
1. Compute local file hash.
2. Compare against recorded template hash.
3. Match ⇒ file unchanged by user ⇒ safe to update.
4. Differ ⇒ prompt (overwrite / skip), or silently respect policy with `-f` / `-s`.
Breaking changes (for example, removing the Multi-Agent Pipeline in 0.5.0) ship as migration manifests: running `trellis update` without `--migrate` on a breaking-manifest exits with instructions instead of silently renaming files. `trellis update --migrate` applies the rename / delete entries, asking once per conflict.
***
# Resources & Acknowledgments
Source: https://docs.trytrellis.app/beta/advanced/resources
## Resource Links
* **GitHub**: [https://github.com/mindfold-ai/Trellis](https://github.com/mindfold-ai/Trellis)
* **Documentation**: [https://docs.trytrellis.app/zh](https://docs.trytrellis.app/zh)
* **Discord**: [https://discord.com/invite/tWcCZ3aRHc](https://discord.com/invite/tWcCZ3aRHc)
* **npm**: [https://www.npmjs.com/package/@mindfoldhq/trellis](https://www.npmjs.com/package/@mindfoldhq/trellis)
* **Design Philosophy**: [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
***
## Acknowledgments
Thanks to the following community members for reviewing and contributing to this document:
* **Murphy233666**: Platform detail corrections (OpenCode command prefix, Kiro invocation methods, etc.)
* **jsfaint**: Technical accuracy review
* **Joel (Azu)**: Cursor Hook status clarification, OpenCode hook capability confirmation
# Roadmap
Source: https://docs.trytrellis.app/beta/advanced/roadmap
## Shipped in v0.6
### Cross-session memory feedstock (`trellis mem`)
A local CLI that indexes the Claude Code and Codex conversation logs already on the machine and exposes them as structured retrieval. `trellis mem list`, `search`, `context`, `extract`, and `projects` cover discovery, keyword search, context-window drill-down, cleaned-dialogue dump, and per-project routing. `extract --phase brainstorm|implement|all` slices a session at `task.py create` / `task.py start` boundaries so the AI can recover the planning window of any prior task. Reusable retrieval and phase logic live in `@mindfoldhq/trellis-core/mem`; nothing is uploaded.
### Session insight (delivered as a capability skill)
Shipped as the bundled `trellis-session-insight` skill rather than a hard-coded workflow step. The skill teaches the AI when to reach for `trellis mem` (past-solution recall, decision retrieval, cross-session continuation, familiar-bug debugging, self-pattern spotting, finish-work retrospective) and what *not* to do with the output: there is no fixed write-back file. What to do with what `mem` returns — quote inline, update a `prd.md` / `design.md`, append to task notes, internalize, or hand off to `trellis-update-spec` — is judged in the moment by the AI based on the live conversation.
### Configurable hooks
Hook behavior is driven by `.trellis/config.yaml`. Current knobs: `session_commit_message`, `max_journal_lines`, `session_auto_commit`, the `hooks.after_create` / `after_start` / `after_finish` / `after_archive` task-lifecycle commands, `channel.worker_guard.idle_timeout` and `max_live_workers`, and `codex.dispatch_mode: inline | sub-agent` (the inline / sub-agent dispatch toggle that controls whether the main Codex agent edits code directly or routes through `trellis-implement` / `trellis-check` sub-agents).
### Auto runner — superseded
Dropped from the roadmap. Both Claude Code (`/goal`) and Codex (autonomy mode) now ship platform-native multi-step autonomy. Adding a Trellis-side runner on top would conflict with the platform scheduler rather than complement it.
***
## Deferred
### Spec → Wiki concept migration
Inspired by [Karpathy's LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). Expand the `spec` concept into a more general "project memory / knowledge base" layer with wikilinks, cross-references, and stale markers; spec narrows back to pure coding constraints, wiki takes over the broader project memory role.
**Status: deferred for product reasons.** The 0.6 cycle prioritized memory feedstock (`trellis mem`) and the session-insight skill that consumes it, which already covers the most common retrieval need without forcing every team to migrate `spec/` into a new schema. Wiki remains on the roadmap but no longer blocks 0.6.
***
## v0.7
### Team-level memory
Cross-developer, cross-task memory retrieval beyond the per-developer journal that exists today. Aims to drop the "find context" cost on large legacy repos. Strongest repeat signal across user interviews. Shape depends on whether Wiki ships first (rich linked memory) or stays deferred (looser aggregation on top of `trellis mem`).
### TDD template
Optional test-first workflow template that turns `implement → check` into `test → implement → check`. Current `trellis-check` is post-hoc. The TDD switch ships through `trellis-meta` skill; default lightweight workflow stays unchanged.
### Stronger brainstorm
Have brainstorm do deeper code / history investigation before asking business questions, leaving questions for what truly can't be inferred from the code. Today brainstorm asks shallow questions too easily.
### Chinese localization
Chinese versions of CLI output, built-in skill / sub-agent prompts, and default templates. `.trellis/spec/` and `workflow.md` are already model-agnostic markdown — writing them in Chinese works fine. This work targets Trellis's own bundled English copy.
***
# Trellis
Source: https://docs.trytrellis.app/beta/index
All-in-one AI framework & toolkit for 10+ AI coding platforms
## What is Trellis?
AI's capabilities grow like vines: full of vitality but spreading everywhere. Trellis is scaffolding for AI, guiding it along the path of your conventions.
Supported platforms: Claude Code, Cursor, OpenCode, Codex, Kiro, Kilo, Gemini CLI, Antigravity, Devin, Qoder, CodeBuddy, GitHub Copilot, Droid, Pi Agent, Oh My Pi, Reasonix, ZCode, Trae, Grok Build, Kimi Code, Snow CLI, plus any agent that reads the `.agents/skills/` standard (Amp, Cline, Deep Agents, Firebender, Warp, and more).
### One-Line Summary
**Trellis is training wheels for AI coding assistants.** It automatically injects your project specs into every AI session, so the AI writes code following your standards instead of improvising.
> AI's capabilities grow like vines, full of vitality but spreading everywhere.
> Trellis is scaffolding for AI, guiding it along the path of your conventions.
### Comparison with Traditional Approaches
| Dimension | `.cursorrules` | `CLAUDE.md` | Skills | **Trellis** |
| --------------------- | --------------------------------- | -------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------- |
| Spec injection method | Manually loaded each conversation | Auto-loaded but easily truncated | User-initiated | **Auto-injection (hooks on capable platforms, prelude on others), precisely loaded per task** |
| Spec granularity | One large file | One large file | One per Skill | **Modular files, composed per task** |
| Cross-session memory | None | None | None | **Workspace journal persistence** |
| Workflow enforcement | None | None | None | **Auto-trigger skills + check sub-agent verify loop** |
| Team sharing | Single user | Single user | Shareable but no standard | **Git-versioned Spec library** |
| Platform support | Cursor only | Claude Code only | Per platform | **22 configured platforms + shared skill ecosystem** |
### Core Concepts at a Glance
| Concept | Description | Location |
| ------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| **Spec** | Your coding standards, written in Markdown. AI reads specs before writing code | `.trellis/spec/` |
| **Workspace** | Each developer's session logs, letting AI remember what was done last time | `.trellis/workspace/` |
| **Task** | A work unit containing requirements docs and context configuration | `.trellis/tasks/` |
| **Skill** | Auto-triggered workflow modules: brainstorm, before-dev, check, update-spec, break-loop | platform-specific skills dir |
| **Sub-agent** | Specialized AI sub-process: `trellis-research`, `trellis-implement`, `trellis-check` | platform-specific agents dir |
| **Command** | Explicit session entries: `finish-work`, `continue`, and manual `start` where needed | platform-specific commands dir |
| **Hook** | Auto-triggered scripts that inject context at session start, sub-agent launch, etc. (platforms with hook support) | `.claude/hooks/`, etc. |
| **Journal** | Session log files recording what was done in each development session | `.trellis/workspace/{name}/journal-N.md` |
***
## Why Trellis?
| Feature | Problem Solved |
| ----------------------------- | ------------------------------------------------------------------------------------------- |
| **Auto-Injection** | Required specs and workflows auto-inject into every conversation. Write once, apply forever |
| **Auto-updated Spec Library** | Best practices live in auto-updated spec files. The more you use it, the better it gets |
| **Skill-first Workflow** | Most operations are auto-trigger skills. AI picks the right one without manual commands |
| **Team Sync** | Share specs across your team. One person's best practice benefits everyone |
| **Session Persistence** | Work traces persist in your repo. AI remembers project context across sessions |
Install Trellis and set up your first project in 5 minutes.
Understand specs, tasks, hooks, and workspaces.
Reference for slash commands (`/start`, `/finish-work`) and auto-trigger skills.
Turn blank templates into executable contracts with `trellis-update-spec`.
# Commands, Upgrades, Tasks & Specs
Source: https://docs.trytrellis.app/beta/start/everyday-use
## 1. Commands & Skills Reference
Since 0.5.0, Trellis is **skill-first**: most capabilities are auto-trigger skills that the platform fires based on context — you don't have to remember them. Only session-boundary entries remain. Agent-capable platforms expose `finish-work` and `continue`; platforms without automatic session injection also expose `start`.
### 1.1 Surface at a Glance
| Kind | Name | Trigger | Purpose |
| ------------- | ---------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Command** | `/trellis:start` | Manual where no SessionStart hook / extension is available | Open a session, load context, classify work |
| **Command** | `/trellis:finish-work` | Manual, after Phase 3.4 commits land | Archive task + record session in journal |
| **Command** | `/trellis:continue` | Manual | Advance the current task to its next step — you don't memorize the workflow (see §1.2.6) |
| **CLI** | `trellis upgrade` | Manual, when the global CLI package is stale | Upgrade the installed Trellis CLI package |
| **Skill** | `trellis-brainstorm` | Planning after task-creation consent | Clarify requirements, inspect evidence, draft planning artifacts |
| **Skill** | `trellis-before-dev` | Auto before touching code in a task | Read relevant spec before writing |
| **Skill** | `trellis-check` | Auto after implementation; also via sub-agent | Verify + self-fix loop |
| **Skill** | `trellis-update-spec` | Auto when a learning is worth capturing | Promote knowledge into `.trellis/spec/` |
| **Skill** | `trellis-break-loop` | Auto after a tricky bug | Root-cause + prevention analysis |
| **Sub-agent** | `trellis-research` | Spawned by main session for investigation | Read-only codebase search |
| **Sub-agent** | `trellis-implement` | Spawned by main session for coding | Writes code, no git commit |
| **Sub-agent** | `trellis-check` | Spawned by main session for verification | Runs verify + self-fix, has its own loop |
The user-facing command set is deliberately small: `finish-work` and `continue` everywhere they are useful, plus `start` on platforms that need a manual session entry point. Everything that used to be a phase command (`/before-backend-dev`, `/check-backend`, `/record-session`, `/onboard`, …) has either been folded into a skill/sub-agent or removed.
### 1.2 Commands
#### 1.2.1 Three versions: `upgrade` vs `update`
Trellis tracks three separate versions. Knowing which is which explains why upgrading is two steps:
1. **Published** — the latest version on npm
2. **Local CLI** — your globally installed `trellis` binary
3. **Project** — the `.trellis/` templates inside your repo
* `trellis upgrade` raises **② → ①** (upgrades the global CLI itself)
* `trellis update` raises **③ → ②** (syncs the current project to your local CLI's version)
So a full upgrade is `trellis upgrade` (CLI) then `trellis update` (project). `trellis update` can only raise the project as far as your local CLI — if the CLI is stale, upgrade it first.
#### 1.2.2 `trellis upgrade`: Upgrade the CLI package
Use this when your globally installed Trellis CLI is behind the published package:
```bash theme={null}
trellis upgrade # follows your current channel: latest / beta / rc
trellis upgrade --tag beta # switch from stable to the latest beta
trellis upgrade --tag latest # explicitly install the latest stable release
trellis upgrade --dry-run # print the npm command without running it
```
`trellis upgrade` was added in CLI 0.6.0. If your installed CLI is 0.5.x or older the command does
not exist yet — join this beta directly with `npm install -g @mindfoldhq/trellis@beta`, then
`trellis upgrade` is available for every future bump.
`trellis upgrade` updates the global CLI package. It does not change files in the current project. After upgrading the CLI, run `trellis update` inside each Trellis project that needs its bundled workflow, hooks, skills, or platform files synced to the new CLI version.
#### 1.2.3 `trellis update`: Sync the project to the CLI
Run this inside a Trellis project after upgrading the CLI. It syncs `.trellis/` templates and platform files (hooks, skills, commands) to your local CLI's version:
```bash theme={null}
trellis update # sync the project to the local CLI's templates
trellis update --dry-run # preview changes without applying them
trellis update --migrate # also apply file migrations (renames / relocations / deletes)
```
`trellis update` only touches files you haven't modified — your customizations stay intact, and a timestamped backup is created before any change.
If the update output ends with **`MIGRATION REQUIRED`** (breaking changes between your project's
version and the CLI, e.g. `0.4.0 → 0.6.5`), run `trellis update --migrate`. Without `--migrate`,
files renamed or relocated by breaking releases are **not** moved — your project keeps the stale
old paths alongside the new templates. Use `--dry-run` to preview what `--migrate` will do.
#### 1.2.4 `/trellis:start`: Start a session
Run this at the beginning of a session if your platform does not auto-inject context. On hook-capable or extension-capable platforms (Claude Code, Cursor, OpenCode, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi Agent, plus Codex with `features.hooks = true` — legacy: `codex_hooks = true`), the SessionStart hook or extension does this automatically, so `start` is usually not installed as a user-facing command.
What it does:
1. Read `.trellis/workflow.md` so the AI knows the workflow contract.
2. Run `get_context.py` to surface developer identity, git status, active tasks.
3. Read spec indexes (per relevant package in a monorepo).
4. Report context and ask what you want to work on.
Task classification the AI will apply:
| Type | Criteria | Flow |
| ------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Simple conversation | Question, explanation, lookup, or discussion with no repo change | No task by default. If a task might help, ask only whether this turn should create one. |
| Inline small task | Contained edit that can be understood and verified in one turn | Ask only whether this turn should create a task. If no, skip Trellis and work inline. |
| Full Trellis task | Multi-file or durable planning work | Ask whether Trellis may create a task and enter planning. |
If the user rejects task creation for complex work, the AI should clarify scope
or suggest a smaller split instead of doing broad inline implementation.
#### 1.2.5 `/trellis:finish-work`: Wrap up + archive
Prerequisite: code is already committed. The AI drives a batched commit step in workflow Phase 3.4 (see `.trellis/workflow.md`) where it drafts commits from this session's edits, learns the repo's commit-message style from `git log --oneline -5`, presents the plan once for one-shot user confirmation, and runs `git commit` per batch. `/finish-work` itself focuses on archive + journal and **refuses to run on a dirty working tree** to keep bookkeeping commits ordered after work commits.
Steps:
1. Run `get_context.py --mode record` to print active tasks, git status, and recent commits. Use this to spot completed-but-unarchived tasks beyond the current one and to grab work-commit hashes for Step 4.
2. `git status --porcelain`, excluding paths under `.trellis/workspace/` and `.trellis/tasks/` (managed by the script auto-commits). Bail out if anything else is dirty, redirecting the user back to Phase 3.4.
3. Archive the active task with `task.py archive ` (produces a `chore(task): archive ...` commit). If Step 1 surfaced other completed tasks and the user confirmed cleanup, archive those too in the same round.
4. Append a session entry with `add_session.py --title … --commit …` (produces a `chore: record journal` commit).
Final git log order: `` → `chore(task): archive ...` (one or more) → `chore: record journal`. Spec sync (route a non-trivial learning to `trellis-update-spec`) belongs in workflow Phase 3.3 before commits, not in this skill.
#### 1.2.6 `/trellis:continue`: Advance within the current task
`continue` is a **within-task** continue — not a cross-task one. The AI picks up where the active task left off using its `task.json.status` plus the workflow-state breadcrumb the hook injects each turn, consults `workflow.md` to locate the current phase/step, and advances to the next one.
A typical task conversation:
1. Describe the work in natural language → the AI classifies the request and asks for task-creation consent when Trellis is useful. After you agree, `trellis-brainstorm` creates the task and drafts `prd.md`.
2. Once `prd.md` looks right, type `continue` → it decides whether the task is lightweight or needs `design.md` and `implement.md`.
3. After planning artifacts are reviewed, type `continue` → it starts the task and moves into implement/check. Sub-agent mode also curates `implement.jsonl` / `check.jsonl`; inline mode reads artifacts/specs directly.
4. When the sub-agents finish, type `continue` → it routes to `trellis-update-spec`, and finally `finish-work`.
Previously you had to learn the workflow yourself and remember which slash command belonged to each phase. With `continue`, the whole workflow falls out of an ordinary conversation — type `continue` to move on, and Trellis keeps the phases straight on your behalf.
### 1.3 Auto-trigger Skills
Skills run without an explicit command; the platform matches on the user's intent. You can always trigger them manually (`/skill trellis-brainstorm`, etc.) if the auto-match misses.
#### 1.3.1 `trellis-brainstorm`
Turns an approved planning request into concrete artifacts:
* Inspects code, tests, configs, docs, existing specs, and task history before asking questions.
* Proposes a task name and slug, then creates the task via `task.py create` when needed.
* Drafts and iterates `prd.md` with requirements and acceptance criteria.
* Asks one question at a time, including the recommended answer.
* For complex tasks, adds `design.md` and `implement.md` before implementation starts.
#### 1.3.2 `trellis-before-dev`
Runs before coding starts on a task. Reads the spec index for the affected package(s), then the specific guideline files referenced in the pre-development checklist. Ensures the AI knows the conventions *before* writing code, not after.
#### 1.3.3 `trellis-check`
Runs after implementation:
1. `git diff --name-only HEAD` to find what changed.
2. Discover which spec layers apply.
3. Compare the diff against the quality checklist in each layer's index.
4. Run `pnpm lint` / `pnpm typecheck` / `pnpm test` (or equivalent) for affected packages.
5. Self-fix violations in a bounded loop, then report what was fixed and what's left.
The `trellis-check` **sub-agent** wraps the skill — the main session just hands verification off to it. The sub-agent has its own retry loop, so there's no need for an external `Ralph Loop` anymore.
#### 1.3.4 `trellis-update-spec`
Captures a learning as an executable contract in `.trellis/spec/`. Used after debugging sessions, after hitting a gotcha, or after making a non-obvious design decision. Picks the right spec file, adds a focused update (decision / convention / pattern / anti-pattern / gotcha), updates the index if needed.
#### 1.3.5 `trellis-break-loop`
Invoked after resolving a hard bug. Produces a 5-dimension analysis:
1. Root-cause classification (missing spec / contract violation / change propagation / test gap / implicit assumption).
2. Why earlier fix attempts failed.
3. Prevention mechanisms (spec update, type constraints, lint rule, test, review checklist, doc).
4. Systematic expansion: other places with the same pattern.
5. Knowledge capture: route findings into `trellis-update-spec`.
> The value of debugging is not fixing *this* bug; it's making sure this class of bugs never happens again.
### 1.4 Sub-agents
Sub-agents are isolated AI sub-processes with their own prompt and (platform-specific) their own tool / hook wiring. Implementation and check agents receive stable spec/research context via JSONL files per task; research agents write findings into the task's `research/` directory.
| Sub-agent | Restriction | When main session spawns it |
| ------------------- | ---------------------- | ---------------------------------------------------- |
| `trellis-research` | Read-only | Codebase search / pattern discovery / doc lookup |
| `trellis-implement` | Writes code, no commit | Once requirements + plan exist, for the coding phase |
| `trellis-check` | Writes code (fixes) | Verification phase; runs self-fix loop internally |
On Claude Code, Cursor, OpenCode, CodeBuddy, Droid, and Pi Agent, implementation and check sub-agents get the right JSONL context (`implement.jsonl`, `check.jsonl`) injected automatically before they start. Pi uses its extension rather than a Python hook. On the rest, the main session reads the JSONL files itself and passes the relevant content into sub-agent prompts. Research agents write durable findings under the task's `research/` directory.
***
## 2. Task Management Workflow
### 2.1 Task Lifecycle
```
create → plan artifacts → optional jsonl context → start → implement/check → finish → archive
create: task directory + task.json + default prd.md
plan artifacts: prd.md for every task; design.md + implement.md before complex work starts
optional jsonl context: AI fills implement/check context when stable spec or research files must be injected
start: marks the task in_progress for this AI session/window
implement/check: development and verification loop
finish: clears this AI session/window's current task
archive: moves completed task to archive/
```
`task.py create` starts the task in `planning`, creates a default `prd.md`, and best-effort points the current AI session at the new task. It also auto-seeds `implement.jsonl` + `check.jsonl` when a sub-agent-capable platform is installed (Claude / Cursor / Codex / Kiro / Pi / etc.); agent-less platforms (Kilo / Antigravity / Devin) skip this and load specs via the `trellis-before-dev` skill in Phase 2.
### 2.2 `task.py` Subcommands
#### 2.2.1 Task Creation
```bash theme={null}
# Create a task
TASK_DIR=$(./.trellis/scripts/task.py create "Add user login" \
--slug user-login \ # Directory name suffix (optional, auto-slugifies otherwise)
--assignee alice \ # Assignee (optional)
--priority P1 \ # Priority: P0/P1/P2/P3 (optional, default P2)
--description "Implement JWT login") # Description (optional)
# Created directory: .trellis/tasks/02-27-user-login/
# Created files: task.json, prd.md
# May also create implement.jsonl + check.jsonl on sub-agent-capable platforms
```
#### 2.2.2 Context Configuration
```bash theme={null}
# implement.jsonl + check.jsonl are seeded by `task.py create` on
# sub-agent-capable platforms. Each file starts with one self-describing
# `{"_example": "..."}` line you can leave in place or delete.
# Curate entries — either edit the jsonl in your editor, or use add-context:
./.trellis/scripts/task.py add-context "$TASK_DIR" implement \
".trellis/spec/backend/index.md" "Backend development guide"
./.trellis/scripts/task.py add-context "$TASK_DIR" check \
".trellis/spec/cli/unit-test/conventions.md" "Unit test conventions"
# target arg: implement | check (shorthand, auto-appends .jsonl)
# path arg: a file OR directory path — add-context auto-detects and sets type="directory" for dirs
#
# What to put in the jsonl: spec files (.trellis/spec/**/*.md) and research files
# ($TASK_DIR/research/*.md) relevant to this task. Do NOT add code paths — code
# is read during Phase 2 implementation, not pre-registered here.
# Discover what specs exist
./.trellis/scripts/get_context.py --mode packages
# Validate implement.jsonl + check.jsonl (all referenced files exist)
./.trellis/scripts/task.py validate "$TASK_DIR"
# View all JSONL entries
./.trellis/scripts/task.py list-context "$TASK_DIR"
```
`task.py add-context` only writes to `implement.jsonl` / `check.jsonl`. Research findings belong
in `{TASK_DIR}/research/*.md`; add those files to the implement/check manifests only when a later
sub-agent must read them before working.
#### 2.2.3 Task Control
```bash theme={null}
# Set as the current task for this AI session/window
# Writes .trellis/.runtime/sessions/.json
./.trellis/scripts/task.py start "$TASK_DIR"
# Clear the current task for this AI session/window
./.trellis/scripts/task.py finish
# Set Git branch name
./.trellis/scripts/task.py set-branch "$TASK_DIR" "feature/user-login"
# Set PR target branch
./.trellis/scripts/task.py set-base-branch "$TASK_DIR" "main"
# Set scope (used in commit messages: feat(scope): ...)
./.trellis/scripts/task.py set-scope "$TASK_DIR" "auth"
```
#### 2.2.4 Parent-child (subtasks)
A task can have children. Children are independent task directories on disk — they have their own `prd.md`, JSONL files, and status. The parent just references them for grouping.
```bash theme={null}
# Option A: create a child directly under a parent
./.trellis/scripts/task.py create "JWT middleware" \
--slug jwt-middleware \
--parent 02-27-user-login
# Option B: link two existing tasks
./.trellis/scripts/task.py add-subtask \
02-27-user-login \ # parent directory
02-28-jwt-middleware # child directory
# Unlink (does not delete either task)
./.trellis/scripts/task.py remove-subtask \
02-27-user-login 02-28-jwt-middleware
```
Effects on `task.json`:
* Parent's `children: [, ...]` gets the child appended.
* Child's `parent: ""` gets set.
* `task.py list` renders children indented under their parent and shows `[done/total done]` so you can see progress at a glance.
Parent-child links use the `parent` and `children` fields. The `subtasks` field that also appears
in `task.json` is unrelated — it's a **checklist of to-do items within a single task** (name +
status pairs), populated mainly by the bootstrap task. Don't confuse the two.
#### 2.2.5 Task Management
```bash theme={null}
# List active tasks
./.trellis/scripts/task.py list
./.trellis/scripts/task.py list --mine # Only your own
./.trellis/scripts/task.py list --status review # Filter by status
# Archive completed tasks
./.trellis/scripts/task.py archive user-login
# Moves to archive/2026-02/
# List archived tasks
./.trellis/scripts/task.py list-archive
./.trellis/scripts/task.py list-archive 2026-02 # Filter by month
```
### 2.3 `task.json` Schema
The exact shape `task.py create` writes today (see `.trellis/scripts/common/task_store.py`):
```json theme={null}
{
"id": "02-27-user-login",
"name": "user-login",
"title": "Add user login",
"description": "Implement JWT login flow",
"status": "planning",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P1",
"creator": "alice",
"assignee": "alice",
"createdAt": "2026-02-27",
"completedAt": null,
"branch": null,
"base_branch": "main",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": null,
"relatedFiles": [],
"notes": "",
"meta": {}
}
```
Fields get populated over time:
* `dev_type` / `scope` / `package` → set via `task.py set-scope` or by editing `task.json` directly; no automatic setter exists
* `branch` → set via `task.py set-branch`
* `status` → transitions `planning → in_progress → completed`
* `completedAt` → set by `task.py archive` (archive does NOT write the commit hash back)
* `parent` / `children` → set via `task.py create --parent` / `add-subtask`
`worktree_path` / `commit` / `pr_url` are schema placeholders only; no 0.5 script populates them.
Store commit hashes or PR URLs under `meta: {}`, or write them back from an `after_archive` hook.
Older tasks created before a field existed may be missing some keys (e.g. tasks created pre-`package` support won't have `"package"`); `task.py` treats missing fields as null, so nothing breaks.
**Status transitions**:
```
task.py create → status: "planning"
task.py start → flips planning to in_progress (other statuses preserved)
task.py archive → status: "completed" + move to archive/
```
`planning` / `in_progress` / `completed` align with the three phases in `workflow.md`. `task.py start` rewrites `planning` to `in_progress` automatically; non-planning statuses (`in_progress`, `review`, `completed`) are left untouched, so re-starting a task in `review` doesn't clobber its state. `task.py list --status` also accepts `review` as a filter — add any custom statuses you need by writing a matching `[workflow-state:]` block in `workflow.md`.
### 2.4 JSONL Context Configuration in Practice
#### 2.4.1 Seeded on Create, AI Curates in Phase 1.3
On sub-agent-capable platforms, `task.py create` writes a **single seed line** into each jsonl:
```jsonl theme={null}
# implement.jsonl (right after task.py create)
{"_example": "Fill with {\"file\": \"\", \"reason\": \"\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line when done."}
```
This line is a fill-in hint for the AI. It has no `file` field, so every downstream consumer (hook, prelude, validate, list-context) skips it; the AI reads it, understands the format, then replaces it with real entries in Phase 1.3.
**Example curated `implement.jsonl` after AI review** (`dev_type=backend` monorepo):
```jsonl theme={null}
{"file": ".trellis/spec/guides/index.md", "reason": "Shared cross-package thinking guides"}
{"file": ".trellis/spec/cli/backend/index.md", "reason": "Backend dev guide — task touches Python scripts"}
{"file": ".trellis/spec/cli/backend/script-conventions.md", "reason": "Script conventions for the affected files"}
{"file": ".trellis/tasks/.../research/auth-library-comparison.md", "reason": "Library choice rationale"}
```
**What belongs in the jsonl**:
* **Spec files** (`.trellis/spec///index.md` + specific guideline files) that apply to this task's domain
* **Research files** (`{TASK_DIR}/research/*.md`) the sub-agent needs to consult
**What does NOT belong**:
* Code files (`src/**`, `packages/**/*.ts`, etc.) — those are read by the sub-agent during implementation, not pre-registered here
* Files you're about to modify — same reason
On agent-less platforms (Kilo / Antigravity / Devin), `task.py create` skips seeding. Those platforms load specs via the `trellis-before-dev` skill in Phase 2.1 instead.
#### 2.4.2 Adding Custom Context
```bash theme={null}
# Add implementation spec context
./.trellis/scripts/task.py add-context "$TASK_DIR" implement \
".trellis/spec/cli/backend/script-conventions.md" "Script conventions for this task"
# Add research produced during planning
./.trellis/scripts/task.py add-context "$TASK_DIR" implement \
"$TASK_DIR/research/auth-library-comparison.md" "Library choice rationale"
# Add check context
./.trellis/scripts/task.py add-context "$TASK_DIR" check \
".trellis/spec/guides/cross-layer-thinking-guide.md" "Cross-layer verification"
```
### 2.5 Task Lifecycle Hooks
You can configure shell commands that run automatically when task lifecycle events occur. This enables integrations like syncing tasks to Linear, posting to Slack, or triggering CI pipelines.
#### 2.5.1 Configuration
Add a `hooks` block to `.trellis/config.yaml`:
```yaml theme={null}
hooks:
after_create:
- 'python3 .trellis/scripts/hooks/linear_sync.py create'
after_start:
- 'python3 .trellis/scripts/hooks/linear_sync.py start'
after_finish:
- "echo 'Task finished'"
after_archive:
- 'python3 .trellis/scripts/hooks/linear_sync.py archive'
```
The default `config.yaml` ships with the hooks section **commented out**. Uncomment and edit to
activate.
#### 2.5.2 Supported Events
| Event | Fires When | Use Case |
| --------------- | ------------------------------------------------ | -------------------------------------- |
| `after_create` | `task.py create` completes | Create linked issue in project tracker |
| `after_start` | `task.py start` sets the current session task | Update issue status to "In Progress" |
| `after_finish` | `task.py finish` clears the current session task | Notify team, trigger review |
| `after_archive` | `task.py archive` moves the task | Mark issue as "Done" |
#### 2.5.3 Environment Variables
Each hook receives:
| Variable | Value |
| ---------------- | --------------------------------------- |
| `TASK_JSON_PATH` | Absolute path to the task's `task.json` |
All other environment variables from the parent process are inherited.
#### 2.5.4 Execution Behavior
* **Working directory**: Repository root
* **Shell**: Commands run through the system shell (`shell=True`)
* **Failures don't block**: A failing hook prints a `[WARN]` message to stderr but does not prevent the task operation from completing
* **Sequential**: Multiple hooks per event execute in list order; a failure in one does not skip the rest
* **stdout captured**: Hook stdout is not displayed to the user; use stderr for diagnostic output
The `after_archive` hook receives `TASK_JSON_PATH` pointing to the **archived** location (e.g.,
`.trellis/tasks/archive/2026-03/task-name/task.json`), not the original path.
#### 2.5.5 Example: Linear Sync Hook
Trellis ships with an example hook at `.trellis/scripts/hooks/linear_sync.py` that syncs task lifecycle events to [Linear](https://linear.app).
**What it does**:
| Action | Trigger | Effect |
| --------- | --------------- | ------------------------------------------------------------------------- |
| `create` | `after_create` | Creates a Linear issue from task.json (title, priority, assignee, parent) |
| `start` | `after_start` | Updates the linked issue to "In Progress" |
| `archive` | `after_archive` | Updates the linked issue to "Done" |
| `sync` | Manual | Pushes `prd.md` content to the Linear issue description |
**Prerequisites**:
1. Install the [`linearis`](https://www.npmjs.com/package/linearis) CLI and set `LINEAR_API_KEY`
2. Create `.trellis/hooks.local.json` (gitignored) with your team config:
```json theme={null}
{
"linear": {
"team": "ENG",
"project": "My Project",
"assignees": {
"alice": "linear-user-id-for-alice"
}
}
}
```
The hook writes the Linear issue identifier back to `task.json` under `meta.linear_issue` (e.g., `"ENG-123"`), making subsequent events idempotent.
***
## 3. Writing Specs
### 3.1 Spec Directory Structure and Layering
#### 3.1.1 Default layout from `trellis init`
`trellis init` writes a skeleton with `frontend/` + `backend/` + `guides/`, all filled with **empty placeholder templates** marked "(To be filled by the team)". The templates are not ready to inject into sub-agents as-is.
```
.trellis/spec/
├── frontend/ # Frontend specs (placeholders)
│ ├── index.md # Index: lists all specs and their status
│ ├── component-guidelines.md # Component specs
│ ├── hook-guidelines.md # Hook specs
│ ├── state-management.md # State management
│ ├── type-safety.md # Type safety
│ ├── quality-guidelines.md # Quality guidelines
│ └── directory-structure.md # Directory structure
│
├── backend/ # Backend specs (placeholders)
│ ├── index.md
│ ├── database-guidelines.md
│ ├── error-handling.md
│ ├── logging-guidelines.md
│ ├── quality-guidelines.md
│ └── directory-structure.md
│
└── guides/ # Thinking guides
├── index.md
├── cross-layer-thinking-guide.md
└── code-reuse-thinking-guide.md
```
Running `trellis init` also creates a **bootstrap task** (`00-bootstrap-guidelines`). In the first Trellis session, AI detects it, runs `trellis-research` to read your actual codebase, then fills the placeholders with specs grounded in the real project (tech stack, conventions, directory shape). Skip this task and you'll be handing empty scaffolds to every sub-agent — don't.
#### 3.1.2 The layout is only a convention
`frontend/` and `backend/` are not special. Trellis discovers spec layers by scanning one level under `.trellis/spec/` for any directory that contains an `index.md`. Name them after how *your* project actually splits — by runtime, by package, by responsibility — as long as each layer has its own `index.md`.
Trellis itself uses a different shape (monorepo, per-package):
```
.trellis/spec/ # Trellis's own spec tree
├── cli/ # Package: CLI
│ ├── backend/
│ │ └── index.md # ← layer registered via index.md
│ └── unit-test/
│ └── index.md # ← another layer
│
├── docs-site/ # Package: docs site
│ └── docs/
│ └── index.md # ← single-layer package
│
└── guides/ # Cross-package thinking guides
├── index.md
├── cross-layer-thinking-guide.md
├── cross-platform-thinking-guide.md
└── code-reuse-thinking-guide.md
```
No `frontend/` or `backend/` at the top level, because the repo is structured by package. The only contract Trellis enforces is *"a layer is a directory with `index.md`"*; everything else is up to your project.
### 3.2 From Empty Templates to Complete Specs
`trellis init` generates empty templates marked "(To be filled by the team)". Here's how to fill them:
**Step 1**: Extract patterns from actual code
```bash theme={null}
# See how existing code is organized
ls src/components/ # Component structure
ls src/services/ # Service structure
```
**Step 2**: Write down your conventions
```markdown theme={null}
# Component Guidelines
## File Structure
- One component per file
- Use PascalCase for filenames: `UserProfile.tsx`
- Co-locate styles: `UserProfile.module.css`
- Co-locate tests: `UserProfile.test.tsx`
## Patterns
#### Required
- Functional components + hooks (no class components)
- TypeScript with explicit Props interface
- `export default` for page components, named export for shared
#### Forbidden
- No `any` type in Props
- No inline styles (use CSS Modules)
- No direct DOM manipulation
```
**Step 3**: Add code examples
````markdown theme={null}
#### Good Example
```tsx
interface UserProfileProps {
userId: string;
onUpdate: (user: User) => void;
}
export function UserProfile({ userId, onUpdate }: UserProfileProps) {
// ...
}
```
#### Bad Example
```tsx
// Don't: no Props interface, using any
export default function UserProfile(props: any) {
// ...
}
```
````
**Step 4**: Update index.md status
```markdown theme={null}
| Guideline | File | Status |
| -------------------- | ----------------------- | ---------- |
| Component Guidelines | component-guidelines.md | **Filled** |
| Hook Guidelines | hook-guidelines.md | To fill |
```
### 3.3 What a Spec Should Look Like
The `trellis-update-spec` skill writes specs as **executable contracts**, not principle text. Every entry sub-agents read at `trellis-implement` / `trellis-check` time has to tell them *how to implement safely* — concrete signatures, contracts, cases, tests. If what you're writing is really "what to think about before coding", it belongs in `guides/`.
#### 3.3.1 Code-Spec vs Guide
| Type | Location | Purpose | Content style |
| ------------- | ------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------- |
| **Code-Spec** | `/*.md` (e.g., `backend/`, `cli/backend/`) | "How to implement safely" | Signatures, contracts, validation matrix, good/base/bad cases, required tests |
| **Guide** | `guides/*.md` | "What to think about before writing" | Checklists, questions, pointers into specs |
If you're writing "don't forget to check X", put it in a guide. If you're writing "X accepts `{field: type, ...}` and returns `{...}`; here are the error cases and the required tests", put it in a code-spec.
#### 3.3.2 Pick the right update shape
`trellis-update-spec` ships several templates; pick the one that matches what you learned:
| You learned… | Template | Key fields |
| ------------------------------------------ | ------------------------------- | ------------------------------------------------------------- |
| Why we picked approach X over Y | **Design Decision** | Context, Options Considered, Decision, Example, Extensibility |
| The project does X this way | **Convention** | What, Why, Example, Related |
| A reusable solution to a recurring problem | **Pattern** | Problem, Solution, Example (Good + Bad), Why |
| An approach that causes trouble | **Forbidden Pattern** (`Don't`) | Problem snippet, Why it's bad, Instead snippet |
| An easy-to-make error | **Common Mistake** | Symptom, Cause, Fix, Prevention |
| Non-obvious behavior | **Gotcha** | `> Warning:` blockquote with when/how |
#### 3.3.3 Mandatory 7-section form for infra / cross-layer work
When the change touches a **command / API signature**, a **cross-layer request-response contract**, a **DB schema**, or **infra wiring** (storage, queue, cache, secrets, env), the skill requires all seven sections:
1. **Scope / Trigger** — why this demands code-spec depth
2. **Signatures** — command / API / DB signature(s)
3. **Contracts** — request fields, response fields, env keys (name, type, constraint)
4. **Validation & Error Matrix** — ` → ` table
5. **Good / Base / Bad Cases** — example inputs with expected outcome
6. **Tests Required** — unit / integration / e2e with assertion points
7. **Wrong vs Correct** — at least one explicit pair
Skip any of these and the skill prompts you to fill them; that's the "executable contract" bar.
#### 3.3.4 Concrete contrast
A **good Convention entry** (`backend/database-guidelines.md`):
````markdown theme={null}
#### Convention: Use ORM batch methods, never loop single-row DB calls
**What**: For any collection of N rows, call the ORM's batch method (`createMany`, `updateMany`, `deleteMany`) once. Never wrap a single-row `create` / `update` / `delete` in a `for` / `Promise.all` loop.
**Why**: Each DB call is a round-trip. In production, a 200-item loop inside a request handler is how p99 latency silently grows from 50ms to 8s — we've already caught this twice in code review (PRs #312, #417). Batch methods collapse N round-trips into one statement and let the DB plan the write.
**Example**:
```ts
// ✅ Correct — one round-trip
await prisma.user.createMany({ data: users });
// ❌ Wrong — N round-trips
for (const user of users) {
await prisma.user.create({ data: user });
}
// ❌ Also wrong — still N round-trips, just parallel
await Promise.all(users.map((user) => prisma.user.create({ data: user })));
```
**When batch is not available**: wrap the loop in a single transaction (`prisma.$transaction`) so it's at least one logical unit; add a comment explaining why batch wasn't usable.
**Related**: `quality-guidelines.md#performance`, `error-handling.md#transactions`.
````
A **bad spec entry** — no signature, no example, no why, no test point:
```markdown theme={null}
#### Database
- Use good query patterns
- Be careful with SQL
- Follow best practices
```
An **over-specified spec** — mechanical rules with no reasoning, stifles judgment:
```markdown theme={null}
#### Variable Naming
- All boolean variables must start with `is` or `has`
- All arrays must end with `List`
- All functions must be less than 20 lines
- All files must be less than 200 lines
```
The bar: specific, actionable, with a code example, with a stated *why*, and — for code-specs — with enough signature / contract detail that a sub-agent can act on it without asking follow-up questions.
### 3.4 Bootstrap Guided Initial Fill
`trellis init` also creates a bootstrap task (`00-bootstrap-guidelines`). In the first Trellis session, the AI recognizes it, runs `trellis-research` across your code, and fills the empty templates under `frontend/` / `backend/` / `guides/` with specs grounded in your actual project — tech stack, conventions, directory shape, all pulled from the code.
***
# How It Works
Source: https://docs.trytrellis.app/beta/start/how-it-works
This page walks through the normal Trellis flow from a fresh AI session to an
archived task. It focuses on runtime behavior: which files are read, which files
are written, which hooks run, and where platform behavior differs.
> This is the day-to-day usage flow. For module boundaries, customization
> points, and implementation details, see [Architecture Overview](/advanced/architecture).
## Flow overview
## 1. A session opens
A Trellis project is a repository with `.trellis/` plus one or more platform
directories such as `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`,
or `.pi/`.
On platforms with a SessionStart path, Trellis injects a compact startup
payload. It is an index and state report, not a full dump of every workflow,
spec, or task artifact.
Typical startup context includes:
| Context | Source |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Developer identity | `.trellis/.developer` |
| Git state | current branch, dirty files, recent commits |
| Active task pointer | `.trellis/.runtime/sessions/.json`, with a single-session fallback when exactly one runtime session exists |
| Active task list | `.trellis/tasks/*/task.json` |
| Workflow index | compact Phase Index from `.trellis/workflow.md` |
| Spec index paths | `.trellis/spec/**/index.md` paths |
| Workspace memory | `.trellis/workspace//index.md` and recent journal notes |
The delivery path depends on the platform:
| Platform group | Startup behavior |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Code, Cursor, OpenCode, Gemini CLI, Qoder, CodeBuddy, Droid, Pi | A SessionStart hook, plugin, or extension injects compact startup context automatically. |
| Codex | `AGENTS.md` loads automatically. Trellis installs a `UserPromptSubmit` hook; on no-task turns it can inject a `` reminder to read `trellis-start`. |
| Copilot | SessionStart output is diagnostic-only in current Copilot hosts. Trellis relies on prompt hooks and skill files for model-visible context. |
| Kiro | Trellis content is delivered through `.kiro/` skills and agent files; there is no Trellis SessionStart hook by default. |
| Kilo, Antigravity, Devin | The main session reads a workflow or skill entry explicitly. |
After this step, the AI should know where Trellis context lives. Detailed phase
instructions are loaded on demand through workflow-state breadcrumbs, skills, or
`get_context.py`.
## 2. Each prompt gets the current workflow state
On hook-capable platforms, every user message triggers a lightweight
workflow-state injection. This is the per-turn guardrail that keeps the main
session aligned with the current task status.
The hook resolves the active task for the current session:
```text theme={null}
cwd
-> find .trellis/
-> resolve session key
-> read .trellis/.runtime/sessions/.json
-> read .trellis/tasks//task.json
-> read task.json.status
```
Then it parses `.trellis/workflow.md` for the matching block:
```text theme={null}
[workflow-state:STATUS]
...
[/workflow-state:STATUS]
```
The block body is wrapped in `...` and injected
into the current turn. SessionStart workflow summaries use the
`` tag.
Important details:
* The hook is parser-only. Breadcrumb wording lives in `.trellis/workflow.md`.
* Python and JavaScript hooks do not carry duplicated fallback dictionaries.
* If no active task exists, the pseudo-status is `no_task`.
* If a matching block is missing, the hook emits `Refer to workflow.md for current step.`
* Codex also receives a `` banner when `codex.dispatch_mode` changes implementation routing.
Changing workflow-state behavior starts with `.trellis/workflow.md`, not the
hook script.
## 3. Trellis triages the current turn
When there is no active task, the AI first classifies the current turn and asks
for task-creation consent before creating anything under `.trellis/tasks/`.
| Route | When it applies | What the AI asks |
| ------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Simple conversation | No repo writes; simple Q\&A, explanation, lookup, or discussion | No task by default. If a task might help, ask only whether this turn should create a Trellis task. |
| Inline small task | A small contained edit that can be understood and verified in the current turn | Ask only whether this turn should create a Trellis task. If the user says no, skip Trellis for this turn and continue inline. |
| Full Trellis task | Multi-file work, workflow/spec/platform changes, template generation, durable plan | Explain why a task is useful and ask whether Trellis may create a task and enter planning. If the user says no, clarify scope or suggest a smaller split. |
User consent to create a task is not consent to start implementation. Starting
implementation has a separate planning review gate.
## 4. Task creation writes the planning state
When the user consents, the main session creates a task:
```bash theme={null}
python3 ./.trellis/scripts/task.py create "" --slug <name>
```
This command writes a task directory:
```text theme={null}
.trellis/tasks/<MM-DD-name>/
├── task.json
├── prd.md
├── implement.jsonl
└── check.jsonl
```
`prd.md` is always created from the default template. `implement.jsonl` and
`check.jsonl` may be seeded for sub-agent-capable platforms. `design.md` and
`implement.md` are not created by the script; the AI writes them during planning
when the task is complex enough to need them.
The initial `task.json` status is `planning`. `task.py create` also best-effort
sets the current session's active-task pointer, so the next prompt can receive
the `[workflow-state:planning]` block without waiting for `task.py start`.
## 5. Planning writes the right artifacts
Planning converts the request into files that implementation and review can
trust.
| Artifact | Required when | Purpose |
| ----------------- | --------------------------- | --------------------------------------------------------------------------------------- |
| `prd.md` | every task | Requirements, constraints, acceptance criteria, and out-of-scope items. |
| `design.md` | complex tasks | Technical design: boundaries, contracts, data flow, compatibility, tradeoffs, rollback. |
| `implement.md` | complex tasks | Execution plan: ordered checklist, validation commands, review gates, rollback points. |
| `research/*.md` | when investigation matters | Durable facts discovered during planning. |
| `implement.jsonl` | when context manifests help | Spec/research files for implementation context. |
| `check.jsonl` | when context manifests help | Spec/research files for review and verification context. |
`implement.md` does not replace `implement.jsonl`. The markdown file is the
human-readable plan; the JSONL file is a manifest for stable context files.
Lightweight tasks can be PRD-only. Complex tasks need `prd.md`, `design.md`, and
`implement.md` before they can start.
## 6. Context manifests stay narrow
`implement.jsonl` and `check.jsonl` list stable context files to read before
implementation or review.
```jsonl theme={null}
{"file": ".trellis/spec/docs-site/docs/style-guide.md", "reason": "Docs writing style"}
{"file": ".trellis/tasks/04-30-example/research/platforms.md", "reason": "Platform behavior research"}
```
Rules:
* Include spec files and task research files.
* Do not list source files that are about to be modified.
* Do not leave only the seed `_example` row when a sub-agent needs context.
* Put implementation-writing context in `implement.jsonl`.
* Put verification and quality context in `check.jsonl`.
Inline modes can skip JSONL curation when the main session directly reads the
needed artifacts and specs.
## 7. Activation enters implementation
After artifact review, Trellis activates the task:
```bash theme={null}
python3 ./.trellis/scripts/task.py start <task-dir>
```
This changes `task.json.status` from `planning` to `in_progress`.
On the next prompt, the workflow-state hook injects the matching
`[workflow-state:in_progress]` block. That block covers implementation, check,
spec update, commit planning, and finish-work routing.
## 8. Implementation reads task artifacts and specs
Execution always starts from the active task directory. The platform decides how
context gets into the actor doing the work.
| Execution path | Platforms | How context loads |
| ----------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hook-push sub-agent | Claude Code, Cursor, OpenCode, CodeBuddy, Droid, Pi | A hook injects JSONL entries, then `prd.md`, `design.md` if present, and `implement.md` if present before the sub-agent starts. |
| Pull-prelude sub-agent | Codex, Copilot, Gemini CLI, Qoder, Kiro | The sub-agent definition tells the agent to read the active task, JSONL entries, `prd.md`, `design.md` if present, and `implement.md` if present. |
| Main-session skill flow | Codex inline, Kilo, Antigravity, Devin | The main session loads Trellis skills and reads `prd.md`, optional artifacts, and relevant specs inline. |
The shared context order is:
```text theme={null}
jsonl entries -> prd.md -> design.md if present -> implement.md if present
```
Codex can run in two modes:
| Mode | Meaning |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `inline` | The main session implements and checks directly; it does not dispatch implement/check sub-agents. |
| `sub-agent` | Implement/check work defaults to Trellis sub-agents; the main session still coordinates, clarifies, updates specs, commits, and finishes. |
## 9. Check reviews and self-fixes
After implementation, Trellis runs `trellis-check`.
The check path reads:
* `prd.md`
* `design.md` if present
* `implement.md` if present
* `check.jsonl` entries when present
* relevant specs and research
* the changed files
* local test, lint, type-check, or format commands
The goal is not only to report issues. `trellis-check` is allowed to fix
findings directly, then rerun checks.
## 10. Finish updates durable knowledge
After checks pass, the main session performs final verification and loads
`trellis-update-spec`.
This step asks whether the task taught a reusable rule. If yes, the rule is
written into `.trellis/spec/` so future tasks can load it through JSONL or direct
skill context.
Task-local facts stay in `.trellis/tasks/<task>/`; stable team rules move to
`.trellis/spec/`.
## 11. The main session drives the work commit
The commit boundary is separate from implementation and separate from
`/trellis:finish-work`.
In Phase 3.4, the main session:
1. Reads `git status --porcelain`.
2. Separates files changed in this task from unrelated dirty files.
3. Groups task files into logical commits.
4. Prints the proposed commit plan.
5. Waits for one user confirmation.
6. Runs `git add` and `git commit` for the approved batches.
For docs-site changes, there is often a submodule boundary:
1. Commit inside `docs-site/`.
2. Return to the parent repository.
3. Commit the updated `docs-site` submodule pointer.
## 12. `/trellis:finish-work` archives and journals
Only after the work commit exists should `/trellis:finish-work` run.
`/trellis:finish-work` does bookkeeping:
* classifies dirty paths and stops if current-task work is still uncommitted
* archives the task under `.trellis/tasks/archive/YYYY-MM/`
* appends the session summary to `.trellis/workspace/<developer>/journal-N.md`
* updates workspace indexes
It is not the command that commits feature code.
## What survives the session
After the flow completes, durable state lives in files:
| Stored in | What survives |
| --------------------------------- | ---------------------------------------------------------------------------------------------- |
| `.trellis/tasks/<task>/` | PRD, design, implementation plan, research, context manifests, metadata, and archived history. |
| `.trellis/spec/` | Team conventions and reusable lessons. |
| `.trellis/workspace/<developer>/` | Developer journals and cross-session notes. |
| Git commits | Reviewable units of code, docs, spec, archive, and journal changes. |
The next AI session reads the repository state again. It does not need the
previous chat transcript to know what the task was, what specs apply, or what
workflow step comes next.
# Install & First Task
Source: https://docs.trytrellis.app/beta/start/install-and-first-task
## Quick Start
### Installation
```bash theme={null}
# Global install (beta channel)
npm install -g @mindfoldhq/trellis@beta
# Navigate to your project directory
cd your-project
```
<Note>
**Requirements**: Mac, Linux, and Windows are fully supported. Requires Node.js 18+ and Python
3.9+.
</Note>
`trellis init` auto-detects installed platforms. You can also specify them explicitly via flags. Each platform needs to be init'd at least once. Pick any combination:
```bash theme={null}
# Interactive: detects installed platforms and asks which to configure
trellis init -u your-name
# Explicit: configure one or more platforms
trellis init -u your-name --claude
trellis init -u your-name --claude --cursor --opencode
trellis init -u your-name --codex --gemini
trellis init -u your-name --pi
```
`your-name` becomes your developer identity and creates your personal workspace at `.trellis/workspace/your-name/`.
Supported flags: `--claude`, `--cursor`, `--opencode`, `--codex`, `--kiro`, `--gemini`, `--qoder`, `--codebuddy`, `--copilot`, `--droid`, `--pi`, `--antigravity`, `--devin` (alias: `--windsurf`, deprecated), `--kilo`, `--reasonix`, `--zcode`, `--omp`, `--trae`, `--grok`, `--kimi`, `--snow`, `--dsh`.
Beyond these 22 configured platforms, any AI coding agent that reads the `.agents/skills/` standard (Amp, Cline, Deep Agents, Firebender, Warp, and more) can also consume Trellis: Codex writes its skills there, and the files are directly usable by the rest of that ecosystem.
### Upgrading
Upgrading is **two steps** — the CLI and your project's `.trellis/` templates are versioned separately:
```bash theme={null}
trellis upgrade # 1. upgrade the global CLI package
trellis update # 2. inside each project: sync .trellis/ + platform files to the new CLI
```
<Warning>
If `trellis update` reports **`MIGRATION REQUIRED`** (breaking changes between your project's
version and the CLI), run `trellis update --migrate` — otherwise files renamed or relocated by
breaking releases stay at their stale old paths.
</Warning>
See [Commands §1.2](/start/everyday-use#1-2-commands) for the full `upgrade` / `update` / `--migrate` reference.
### Platform Configuration
`trellis init` writes platform-specific config directories. Core concepts (`.trellis/`) are identical across platforms; the differences sit in how commands, skills, sub-agents, and hooks are delivered.
| Platform | Config Directory |
| --------------- | ---------------------------------------------------------------------------- |
| **Claude Code** | `.claude/commands/trellis/`, `agents/`, `skills/`, `hooks/` |
| **Cursor** | `.cursor/commands/`, `agents/`, `skills/`, `hooks/` |
| **OpenCode** | `.opencode/commands/trellis/`, `agents/`, `skills/`, `plugins/`, `hooks/` |
| **Codex** | `.codex/agents/`, `skills/`, `hooks/` + root `AGENTS.md` |
| **Kiro** | `.kiro/agents/`, `skills/`, `hooks/` |
| **Gemini CLI** | `.gemini/commands/trellis/`, `agents/`, `skills/`, `hooks/` |
| **Qoder** | `.qoder/commands/`, `agents/`, `skills/`, `hooks/` |
| **CodeBuddy** | `.codebuddy/commands/trellis/`, `agents/`, `skills/`, `hooks/` |
| **Copilot** | `.github/copilot/`, `prompts/`, `agents/`, `skills/`, `hooks/` |
| **Droid** | `.factory/commands/trellis/`, `droids/`, `skills/`, `hooks/` |
| **Pi Agent** | `.pi/prompts/`, `skills/`, `agents/`, `extensions/trellis/`, `settings.json` |
| **Oh My Pi** | `.omp/commands/`, `skills/`, `agents/`, `extensions/trellis/` |
| **Kilo** | `.kilocode/workflows/`, `skills/` |
| **Antigravity** | `.agent/workflows/`, `skills/` |
| **Devin** | `.devin/workflows/`, `skills/` |
`.agents/skills/` is a shared cross-platform layer ([agentskills.io](https://agentskills.io) standard). `trellis init` writes all skills into it too, so any agent that reads the `.agents/skills/` standard (Amp, Cline, Deep Agents, Firebender, Warp, etc.) can consume them.
### init Scenarios
`trellis init` dispatches on the presence of `.trellis/` and `.trellis/.developer`. Match your situation to the command:
| Scenario | Command | Result |
| --------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **First-time project init** | `trellis init -u your-name --claude` | Creates `.trellis/` + bootstrap task `00-bootstrap-guidelines` that walks you through filling project spec |
| **Add a new platform to an existing project** | `trellis init --cursor` (or no-arg interactive — it lists unconfigured platforms) | Writes the new platform's config dir on top of the existing `.trellis/`; no task generated |
| **New developer joining an existing project** | `trellis init -u their-name` | Generates the joiner onboarding task `00-join-<slug>` and guides reading workflow + spec; start it in the current AI session when ready |
| **Same developer on a new machine** | Same as above | Also generates a joiner task (because `.developer` isn't committed). Archive it if you don't need the refresher. |
| **Same dev, same machine, re-run init** | `trellis init -u your-name` | No-op — both `.trellis/` and `.developer` already exist |
`--force` / `--skip-existing` only affect **how file conflicts are resolved** (overwrite vs skip); they don't change the dispatch logic itself.
<Note>
**Dispatch signal**: `.trellis/.developer` is a gitignored per-checkout identity file (by design, never committed), so a fresh clone never has one — this is the clean signal for "new developer on this checkout". `.trellis/workspace/<name>/` is committed and cannot serve this role.
</Note>
### Basic Flow
Describe what you want to do. The AI first classifies the turn. Simple
conversation and small inline tasks do not automatically create Trellis tasks;
the AI asks whether this turn should create a task. Complex work gets a separate
consent question before Trellis creates a task and enters planning.
```text theme={null}
# 1. Describe what you want
"Add user login feature"
# 2. AI classifies the turn and asks for task-creation consent when needed
# 3. If this is a Trellis task, AI runs Plan → Execute → Finish per workflow.md
# 4. After the work commit exists
/trellis:finish-work
```
<Note>
Agent-capable platforms load Trellis context through a mix of SessionStart hooks, prompt hooks,
extensions, agent files, and skills. Codex is different from Claude-style platforms: it relies on
`AGENTS.md` plus the `UserPromptSubmit` hook, and the no-task breadcrumb can tell the AI to read
`trellis-start`. Only agent-less platforms (Kilo, Antigravity, Devin) ship `/trellis:start` (or
`/start.md`) as an explicit entry point.
</Note>
### Directory Structure
Below is the layout after `trellis init` with Claude Code. Other platforms write to their own sub-directories but share the same `.trellis/` core.
```
your-project/
├── .trellis/ # Trellis core (platform-independent)
│ ├── .developer # Developer identity (gitignored)
│ ├── .version # Trellis version
│ ├── .template-hashes.json # Template file hashes (for update)
│ ├── workflow.md # Development workflow guide
│ ├── config.yaml # Project config (packages, update.skip, hooks)
│ │
│ ├── .runtime/ # Session-scoped runtime state (gitignored)
│ │ └── sessions/ # Active task per AI session/window
│ │ └── <session-key>.json
│ │
│ ├── spec/ # Project spec library
│ │ ├── frontend/ # Frontend specs (or per-package in monorepo)
│ │ ├── backend/ # Backend specs
│ │ └── guides/ # Thinking guides
│ │
│ ├── workspace/ # Developer workspaces
│ │ ├── index.md
│ │ └── {developer-name}/
│ │ ├── index.md
│ │ └── journal-N.md
│ │
│ ├── tasks/ # Task directory
│ │ ├── {MM-DD-task-name}/ # Active tasks
│ │ │ ├── task.json # Task metadata
│ │ │ ├── prd.md # Requirements document
│ │ │ ├── design.md # Technical design for complex tasks
│ │ │ ├── implement.md # Implementation plan for complex tasks
│ │ │ ├── implement.jsonl # Spec/research manifest for implementation
│ │ │ ├── check.jsonl # Spec/research manifest for review
│ │ │ └── research/ # Durable investigation notes
│ │ └── archive/ # Archived tasks
│ │ └── {YYYY-MM}/
│ │
│ └── scripts/ # Automation scripts (Python)
│ ├── task.py # Task management
│ ├── get_context.py # Session context
│ ├── add_session.py # Record session
│ ├── create_bootstrap.py # First-time spec bootstrap
│ └── common/ # Shared libraries
│
├── .claude/ # Claude Code configuration
│ ├── settings.json # Hook and permission config
│ ├── commands/trellis/ # Explicit commands
│ │ ├── start.md
│ │ ├── finish-work.md
│ │ └── continue.md
│ ├── agents/ # Sub-agent definitions
│ │ ├── trellis-implement.md
│ │ ├── trellis-check.md
│ │ └── trellis-research.md
│ ├── skills/ # Auto-trigger skills
│ │ ├── trellis-brainstorm/
│ │ ├── trellis-before-dev/
│ │ ├── trellis-check/
│ │ ├── trellis-update-spec/
│ │ └── trellis-break-loop/
│ └── hooks/ # Hook scripts
│ ├── session-start.py
│ ├── inject-subagent-context.py
│ └── inject-workflow-state.py
│
├── .cursor/ # Cursor: commands/ + rules/
├── .opencode/ # OpenCode: commands/trellis/, agents/, skills/, plugins/, hooks/
├── .codex/ # Codex: prompts/, skills/ + AGENTS.md at repo root
├── .kiro/ # Kiro: steering/, prompts/, skills/
├── .gemini/ # Gemini CLI: commands/trellis/
├── .qoder/ # Qoder: commands/, skills/, agents/, hooks/
├── .codebuddy/ # CodeBuddy: commands/trellis/
├── .factory/ # Droid: commands/trellis/, skills/, hooks/
├── .pi/ # Pi Agent: prompts/, skills/, agents/, extensions/trellis/
└── .github/ # Copilot: copilot-instructions.md, prompts/
```
***
## Your First Task
### Starting a Session
<Tabs>
<Tab title="General">
Open the terminal. On hook-backed platforms, the compact SessionStart payload gives the AI enough
Trellis context to route the next turn:
* compact Phase Index from `workflow.md`
* Identity, git status, active task list
* Spec index paths
* task artifact context order
**Just describe your task.**
If you suspect auto-injection didn't run or you want to reload context, open a
new session or ask the AI to read the `trellis-start` skill once. These
platforms usually do not expose `/trellis:start` as a slash command because the
startup path already handles orientation.
</Tab>
<Tab title="Codex">
**You must enable hooks in `~/.codex/config.toml`, or typing `/` in the chat won't surface Trellis's three commands (`/start`, `/finish-work`, `/continue`) and you can't launch a session with `/start`.**
```toml theme={null}
[features]
hooks = true # Codex 0.129+. Older versions: `codex_hooks = true`.
```
Codex 0.129+ also gates each installed hook behind a one-time `/hooks` TUI review. Open Codex once, run `/hooks`, and approve the Trellis `UserPromptSubmit` hook. Until you do, the hooks stay inactive, Trellis's commands/skills won't appear in the `/` menu, and the workflow breadcrumb won't auto-inject. Even without them, a fallback (the `AGENTS.md` prelude) lets the AI read the `trellis-start` skill manually so context is still there — but you can't invoke Trellis commands from `/`, which is a noticeably worse experience.
After that, describe your task directly. Codex reads `AGENTS.md` automatically,
and the `UserPromptSubmit` hook injects the current workflow-state breadcrumb.
When there is no active task, that breadcrumb may include a `<trellis-bootstrap>`
reminder telling the AI to read `trellis-start` once.
</Tab>
<Tab title="Kiro">
Kiro delivers Trellis content via its `.kiro/` agent / skill files. Kiro's Agent Hooks are user-configured (triggered on file save, build success, etc.); Trellis does not ship any Agent Hook wiring. Describe your task and Kiro's skill matcher enters the brainstorm flow; run `@trellis:start` when you want a full context report.
</Tab>
<Tab title="Kilo / Antigravity / Devin">
These three platforms have workflows + skills only, no hooks and no sub-agents. Entry:
* Kilo: `/start.md`
* Antigravity: open `.agent/workflows/start.md`
* Devin: `/trellis-start`
The AI follows the workflow: reads `workflow.md`, runs `get_context.py`, reads spec indexes, asks what you want to do. The subsequent implement / check phases run inline in the main session instead of spawning sub-agents.
</Tab>
</Tabs>
### Example: Starting a New Project from Scratch
This is the first Trellis loop for a new product, service, SDK, package, or internal tool.
Real situation: you are starting a B2B dashboard with login, team management, billing, and analytics. AI can help move fast, but each session should not reinvent the directory structure, API style, component pattern, and testing rules.
Starting prompt:
```text theme={null}
I am starting a new B2B dashboard from scratch. Help me set up Trellis for the first week of work.
First, ask for the missing product and tech-stack decisions. Then create a small first task and the minimum specs needed for frontend structure, API shape, error handling, and test strategy.
```
Workflow:
1. After project initialization, run `trellis init`. It writes default spec templates under `.trellis/spec/` (about 17 placeholder files across `backend/`, `frontend/`, and `guides`, covering directory structure, error handling, logging, component guidelines, cross-layer thinking, and similar rules), and creates the `00-bootstrap-guidelines` task.
2. Use the bootstrap task to discuss product requirements and the project tech stack with AI, so the AI has enough context before writing code.
3. Optional: use the bundled `trellis-spec-bootstrap` skill so AI can draft first-pass specs from the real codebase. It is installed with Trellis, so there is no extra marketplace download step.
4. Fill the default specs produced by `trellis init` first, based on what you know now. Do not design the entire project upfront.
5. Review the generated spec quality by hand.
6. Create the smallest task that can run end to end.
7. Continue with `/trellis:continue`; Trellis will move the task through check, update-spec, commit, and finish.
### AI Creates the Task and Develops
You say: "Add user login feature". The AI first decides this is complex enough
for a Trellis task and asks whether it may create a task and enter planning. If
you agree, it walks the three phases from `workflow.md`:
```text theme={null}
Phase 1 — Plan (interactive)
1.0 task.py create creates the task directory and default prd.md
1.1 AI activates the trellis-brainstorm skill and walks through the requirement
one question at a time, iterating prd.md
1.2 For complex tasks, AI writes design.md and implement.md before implementation
1.3 When research is needed, findings land in research/
1.4 Sub-agent mode curates implement.jsonl / check.jsonl with spec + research
paths only, not source paths
1.5 After review, task.py start flips status to in_progress
Phase 2 — Execute
2.1 AI implements against prd.md, design.md if present, implement.md if present,
and relevant specs. Depending on platform/mode, this may be a sub-agent
or inline main-session work.
2.2 AI runs trellis-check → reviews diff vs artifacts + specs and runs
lint / typecheck / test, self-fixing when possible
Phase 3 — Finish
3.1 AI activates the trellis-check skill for final verification
3.2 (on demand) AI activates the trellis-break-loop skill for debug retrospective
3.3 AI activates the trellis-update-spec skill and writes new learnings to
.trellis/spec/
3.4 AI proposes the work commit plan, commits approved batches, then runs
/trellis:finish-work for archive and journal bookkeeping
```
**When AI stalls or is skipping ahead**: run `/trellis:continue`. AI uses the
active task's status, artifact presence, and the per-turn workflow-state
breadcrumb to figure out the next step, then loads the relevant workflow detail
before continuing.
### Finishing the Session
```
/trellis:finish-work
```
`finish-work` calls `add_session.py` to append a journal entry and update your personal index. If the task is actually done (code merged, acceptance criteria met), it also archives the task via `task.py archive`.
### Cross-Session Memory
Next time you open a session, the SessionStart hook (or the platform's prelude) reads your workspace journal and active task list, so AI can recall what you did last:
```
AI: "Hi Alice — last session you finished the user login feature (commit abc1234),
covering the LoginForm component, JWT middleware, and users table.
What next?"
```
Journals live under `.trellis/workspace/{name}/journal-N.md`; every `/trellis:finish-work` appends one. Trellis tracks each AI session's active task internally so you can pick it up next time; `task.py finish` clears that pointer.
***
## Remote Spec Templates
Instead of writing specs from scratch, pull pre-built spec templates during init.
### Official Marketplace
```bash theme={null}
# Interactive: browse and pick from available templates
trellis init -u your-name
# Non-interactive: specify a template by ID
trellis init -u your-name --template electron-fullstack
```
The interactive picker shows all templates from the [official marketplace](https://github.com/mindfold-ai/Trellis/tree/main/marketplace). Choose one or start with blank specs.
### Custom Registry (`--registry`)
Pull specs from your own GitHub, GitLab, or Bitbucket repository:
```bash theme={null}
# Direct download: repo directory becomes .trellis/spec/
trellis init --registry gh:myorg/myrepo/my-team-spec
# Marketplace mode: repo has index.json with multiple templates
trellis init --registry gh:myorg/myrepo/marketplace
# Pick a specific template from a custom marketplace
trellis init --registry gh:myorg/myrepo/marketplace --template my-template
# Specify a branch
trellis init --registry gh:myorg/myrepo/specs#develop
# GitLab or Bitbucket
trellis init --registry gitlab:myorg/myrepo/specs
trellis init --registry bitbucket:myorg/myrepo/specs
```
**Source format**: `provider:user/repo[/subdir][#ref]`
| Provider | Prefix |
| --------- | ------------------ |
| GitHub | `gh:` or `github:` |
| GitLab | `gitlab:` |
| Bitbucket | `bitbucket:` |
The ref (branch/tag) defaults to `main` if omitted.
### Handling Existing Specs
When `.trellis/spec/` already exists, use a strategy flag:
| Flag | Behavior |
| ------------- | --------------------------------------------- |
| `--overwrite` | Delete existing spec directory, then download |
| `--append` | Only copy files that don't already exist |
| *(neither)* | Interactive prompt asks what to do |
### Building a Custom Marketplace
Create an `index.json` in your repository:
```json theme={null}
{
"version": 1,
"templates": [
{
"id": "my-backend-spec",
"type": "spec",
"name": "My Backend Spec",
"description": "Backend conventions for our team",
"path": "marketplace/specs/my-backend-spec",
"tags": ["backend", "node"]
}
]
}
```
The `path` field is relative to the repository root. Only `type: "spec"` is supported currently.
### Private Repositories
For private repos, set the `GIGET_AUTH` environment variable with a personal access token:
```bash theme={null}
GIGET_AUTH=ghp_xxxxx trellis init --registry gh:myorg/private-repo/specs
```
For GitHub fine-grained tokens, you need **Contents** and **Metadata** read permissions.
# Real-World Scenarios
Source: https://docs.trytrellis.app/beta/start/real-world-scenarios
Use Trellis in real engineering work: new products, brownfield repos, refactors, bug fixes, and team rollouts.
Most teams do not need another command list. They need a way to keep project decisions from disappearing between AI sessions: new projects need early rules before patterns spread, brownfield repos hide conventions in old PRs, refactors need invariants, and production bugs need lessons that survive the fix.
Each scenario below gives a starting prompt, the Trellis files to produce, the workflow to follow, and a concrete finish line. Pick the closest situation and adapt it into a task for your repo.
<Note>
Trellis is skill-first. Treat the prompts below as task inputs; Trellis routes the work through
the relevant skills for brainstorming, spec loading, checks, and knowledge capture. Use
`/trellis:start` only when your platform needs a manual session entry point.
</Note>
## Scenario map
| Scenario | Use when | Main Trellis value |
| ------------------------------------------------------------------------ | ---------------------------------------------------- | ----------------------------------------------------- |
| [1. Start a new project](#1-start-a-new-project) | You are creating a repo from zero | Make early decisions explicit before code spreads |
| [2. Adopt an existing project](#2-adopt-an-existing-project) | The repo already exists and conventions are implicit | Extract real patterns without pausing feature work |
| [3. Ship a product feature](#3-ship-a-product-feature) | A task touches product, API, data, and UI | Keep scope, specs, implementation, and checks aligned |
| [4. Refactor a legacy module](#4-refactor-a-legacy-module) | Code works but is hard to change safely | Preserve behavior while making structure reviewable |
| [5. Fix a recurring bug](#5-fix-a-recurring-bug) | The same class of issue keeps returning | Convert the fix into tests, specs, and session memory |
| [6. Reduce repeated review feedback](#6-reduce-repeated-review-feedback) | Reviewers repeat the same comments | Promote review rules into shared repo context |
| [7. Roll out to a team](#7-roll-out-to-a-team) | More people or tools need the same workflow | Make adoption consistent across developers and agents |
<Tip>
Optimize for one useful task before pushing a complete framework rollout. A small working spec and
a clear task PRD teach the team more than a large empty spec library.
</Tip>
## 1. Start a new project
Use this when you are creating a product, service, package, or internal tool from zero.
### 1.1 Example situation
You are starting a B2B dashboard with authentication, team management, billing, and analytics. You want AI to help build quickly, but you do not want every session to invent a new folder layout, API style, or component pattern.
### 1.2 Starting prompt
```text theme={null}
I am starting a new B2B dashboard from scratch. Help me set up Trellis for the first week of work.
First, ask for the missing product and tech-stack decisions. Then create a small first-task PRD and
the minimum specs needed for frontend structure, API shape, error handling, and tests.
```
### 1.3 Workflow
1. Run `trellis init` once the project is initialized — it writes around 17 default spec templates under `.trellis/spec/`, split into `backend/` / `frontend/` / `guides/` (directory structure, error handling, logging, component and hook guidelines, cross-layer thinking, etc.), and auto-creates a `00-bootstrap-guidelines` task.
2. Inside the bootstrap task, walk the AI through the product requirements and tech stack so it has full context before doing anything else.
3. Optional: use the bundled `trellis-spec-bootstrap` skill to draft first-pass specs from the real codebase, plus any other skills that match the stack. Trellis installs this bundled skill automatically.
4. Fill in the default spec templates produced by `trellis init`, focusing on what the current work needs; do not pre-design the whole project.
5. Review the generated specs by hand for quality.
6. Create one task for the smallest useful vertical slice.
7. Type `/trellis:continue` repeatedly to drive the task to completion — Trellis routes through check / update-spec / finish per `workflow.md`.
8. Run `/trellis:finish-work` to archive the task and record the session journal.
### 1.4 Done means
* A new developer can read the first task PRD and understand what is in scope.
* The repo has runnable validation commands.
* The first specs describe decisions already made, not speculative architecture.
* The session journal records why the stack and project shape were chosen.
## 2. Adopt an existing project
Use this when the codebase already has real behavior, but conventions live in old PRs, reviewer habits, scattered docs, or senior engineers' memory.
### 2.1 Example situation
You inherit a three-year-old SaaS repo. There are many patterns for API routes, permissions, and forms. AI can make local changes, but it often misses project-specific details.
### 2.2 Starting prompt
```text theme={null}
This is an existing repo. Do not refactor code yet.
Inspect the codebase and propose a minimal Trellis bootstrap for the next feature task. Identify the
actual patterns used for API routes, auth checks, logging, tests, and frontend forms. Write specs only
for patterns supported by current code examples.
```
### 2.3 Workflow
1. Run `trellis init` — it writes the default spec templates and auto-creates a `00-bootstrap-guidelines` task that drives the rest of this scenario.
2. Inside the bootstrap task, walk the AI through the project context and have it scan the repo to extract actual patterns (API routes, auth checks, logging, tests, frontend forms, etc.), filling those findings into the default spec templates.
3. Optional: use the bundled `trellis-spec-bootstrap` skill to draft first-pass specs from the real codebase, then review the output by hand. Trellis installs this bundled skill automatically.
4. Ask the AI to cite file paths for every convention it writes.
5. Review the specs like code. Delete rules that cannot be traced to real examples.
6. Pick one pilot feature or bug fix.
7. Run the pilot task and check whether the specs reduce repeated prompting.
### 2.4 Guardrails
* Do not document aspirational standards as if the code already follows them.
* Do not fill every template. False rules are more harmful than empty placeholders.
### 2.5 What a good spec looks like
Drawn from the `trellis-update-spec` skill's writing principles:
* **Specific**: cite real file paths and real code from the project — not vacuous slogans like "code should be clean and consistent".
* **Explain why**: state the concrete real-world purpose of the rule.
* **Show types**: API signatures, field types, env vars, and error types spelled out.
* **Low coupling**: each spec file covers a single topic; the spec library itself should be high-cohesion / low-coupling.
Examples:
````markdown theme={null}
## API Input Validation
All API routes must validate request input with Zod before calling service code.
Schemas live next to the route file.
```ts
// Bad
const user = await userService.create(req.body);
// Good
const input = CreateUserSchema.parse(req.body);
const user = await userService.create(input);
```
If validation fails, return the standard validation error shape defined in
`src/lib/errors.ts`.
````
````markdown theme={null}
## Database Bulk Writes
Aggregate writes must use the ORM's batch method. Inserting inside a `for` loop is forbidden.
```ts
// Bad
for (const row of rows) {
await db.insert(usersTable).values(row);
}
// Good
await db.insert(usersTable).values(rows);
```
Reason: a per-row loop produces N database round-trips plus a commit per row; batch is one round-trip and one transaction. For 10k rows the latency difference is typically two orders of magnitude.
````
### 2.6 Done means
* The first specs cite real source files.
* The pilot task needs fewer reminders about local patterns.
* Reviewers can point to `.trellis/spec/` instead of re-explaining conventions.
## 3. Ship a product feature
Use this when a feature crosses multiple layers: product behavior, UI state, API contracts, database changes, permissions, tests, and release notes.
### 3.1 Example situation
You need to add team invitations. The feature touches workspace permissions, invitation emails, API routes, database tables, frontend forms, and edge cases such as expired invites.
### 3.2 Starting prompt
```text theme={null}
Create a Trellis task for team invitations.
The feature should let workspace admins invite users by email, resend pending invites, revoke invites,
and accept an invite. Include product requirements, out-of-scope items, data model changes, API shape,
frontend states, tests, and rollout risks.
```
### 3.3 PRD shape
```markdown theme={null}
# Team Invitations
## Goal
Workspace admins can invite teammates by email and manage pending invites.
## In scope
- Create invite
- Resend invite
- Revoke invite
- Accept invite
- Expiration handling
## Out of scope
- Bulk CSV import
- SSO provisioning
- Role templates
## Acceptance criteria
- Non-admin users cannot create, resend, or revoke invites.
- Expired invites show a recoverable error.
- Invite acceptance is idempotent.
- Tests cover permission checks and expired invite behavior.
```
### 3.4 Task and subtask split
The Trellis task is the feature boundary: one PRD, one implementation context,
one check context, and one final reviewable diff.
```text theme={null}
Task: team-invitations
Goal: workspace admins can invite, resend, revoke, and accept invites safely.
Task files: .trellis/tasks/<date>-team-invitations/prd.md, implement.jsonl, check.jsonl
```
Inside that task, split the work into bounded subtasks so agents can work in
parallel without losing the shared product context:
| Subtask | Scope | Typical owner / files |
| ------------------------ | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Product and contract | Invite lifecycle, role rules, expiration behavior, out-of-scope choices | Main session updates `prd.md` and API contract notes |
| Data model | `invitations` table, token hash, expiry, uniqueness, audit fields | Backend implementer owns migrations, schema files, model tests |
| API and service behavior | Create, resend, revoke, accept invite; admin checks; idempotency | Backend implementer owns routes, service code, API tests |
| Email side effect | Invite email template, resend behavior, test mailer/fake provider | Backend implementer owns mailer code and side-effect tests |
| UI states | Invite form, pending invites list, revoke/resend actions, accept screen | Frontend implementer owns routes, components, form validation, UI tests |
| Cross-layer check | End-to-end path from create invite to accepted membership | `trellis-check` verifies UI input, API validation, database writes, permissions, email |
Keep these subtasks under the same Trellis task when they must ship together.
Split a separate Trellis task only when the work has its own scope and release
boundary, such as bulk CSV import, SSO provisioning, or role templates.
### 3.5 Workflow
1. **User** describes the feature in natural language; answers clarifying questions and confirms scope as planning progresses → **AI** classifies the request and asks for Trellis task creation. After the user agrees, AI loads `trellis-brainstorm`, inspects relevant code/docs before asking repo-answerable questions, creates the task (`task.py create`), and captures clarified Goal / In scope / Out of scope / Acceptance criteria into `prd.md` (Phase 1.1).
2. **AI** configures `implement.jsonl` / `check.jsonl` with the specs the task touches (Phase 1.3).
3. **User** types `/trellis:continue` → **AI** dispatches `trellis-implement` and builds the smallest end-to-end slice against the PRD (Phase 2.1).
4. **User** types `/trellis:continue` → **AI** dispatches `trellis-check`, reviewing cross-layer contracts via `check.jsonl` (UI input, API validation, database writes, email side effects, permission-failure paths) and fixing issues in place (Phase 2.2).
5. **User** types `/trellis:continue` → **AI** advances to Phase 3, checks whether the task produced any new reusable specs, and triggers `trellis-update-spec` to update `.trellis/spec/` if it did.
6. **User** types `/trellis:finish-work` → **AI** archives the task and records the session journal.
## 4. Refactor a legacy module
Use this when code works but is hard to change. A Trellis refactor task should be behavior-preserving by default.
### 4.1 Example situation
`src/billing/invoice-service.ts` has grown to 1,200 lines. It calculates invoices, applies discounts, calls payment APIs, writes audit logs, and formats email content. You need to split it without changing billing behavior.
### 4.2 Starting prompt
```text theme={null}
Create a behavior-preserving refactor task for src/billing/invoice-service.ts.
First map current responsibilities, callers, side effects, and existing tests. Then propose the safest
sequence. Do not change behavior until we have characterization tests or clear existing coverage for
the important billing paths.
```
### 4.3 Workflow
1. **User** describes which module to refactor and which behaviors must not change in natural language; confirms the invariant list and extraction order during planning → **AI** classifies the request and asks for Trellis task creation. After the user agrees, AI loads `trellis-brainstorm`, inspects current responsibilities, callers, side effects, and existing test coverage, creates the task (`task.py create`), and records the discussion outcomes into `prd.md` (Phase 1.1).
2. **User** spells out the "behavior must not change" contracts directly in the PRD (see 4.4 Refactor invariants); AI may draft, user must hand-review.
3. **AI** configures `implement.jsonl` (caller paths, existing tests, relevant specs) and `check.jsonl` (behavior contracts, reviewer concerns) → **User** confirms (Phase 1.3).
4. **User** (or AI-assisted) adds or confirms characterization tests and gets the baseline green before any extraction.
5. **User** types `/trellis:continue` → **AI** `trellis-implement` extracts one responsibility per round; public interfaces stay stable by default (Phase 2.1).
6. **User** types `/trellis:continue` → **AI** `trellis-check` runs the tests; failures trigger Phase 2.3 rollback of the current extraction.
7. Repeat 5-6 once per responsibility; user reviews each round's diff.
8. **User** types `/trellis:continue` → **AI** triggers `trellis-update-spec` to record the new module boundaries → **User** confirms which entries are long-term rules.
9. **User** types `/trellis:finish-work` → **AI** archives the task and records the session journal.
### 4.4 Refactor invariants
Put invariants directly in the PRD.
```markdown theme={null}
## Behavior that must not change
- Invoice totals must match existing calculation for active discounts.
- Failed payment attempts must still write audit logs.
- Email rendering output must remain byte-for-byte compatible for existing templates.
- Public API response shape must not change.
```
## 5. Fix a recurring bug
Use this when a patch fixes the symptom, but the same bug class is likely to return.
### 5.1 Example situation
A user reports that Claude Code's SessionStart hook crashes with `TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'` on PEP 604 syntax (`str | None`). Their terminal `python3 --version` reports 3.11, so the syntax should have worked. The surface fix is to swap PEP 604 for `Optional[str]` or add `from __future__ import annotations`; the root cause is that AI-CLI hook subprocesses run with a minimal PATH that resolves `python3` to system `/usr/bin/python3` (3.9 on macOS), not the user's shell-configured 3.11.
### 5.2 Starting prompt
```text theme={null}
Fix the SessionStart hook crash on `str | None`. The user's terminal Python is 3.11, but the hook
subprocess seems to use something older.
Reproduce on a minimal-PATH shell, identify the smallest safe fix, add a way to detect this class
of issue going forward, and then run a break-loop analysis. If the root cause exposes a missing
convention, propose a spec update.
```
### 5.3 Workflow
1. **User** describes the bug, the known reproduction path, and the expected behavior in natural language; works with AI to narrow down root-cause hypotheses during planning → **AI** classifies the request and asks for Trellis task creation. After the user agrees, AI loads `trellis-brainstorm`, inspects the reproduction context before asking repo-answerable questions, creates the bug-fix task (`task.py create`), and records reproduction steps, root-cause hypothesis, and regression-test requirement into `prd.md` (Phase 1.1).
2. **AI** configures `check.jsonl` to reference the relevant specs and testing conventions → **User** confirms the check context covers the edges that matter (Phase 1.3).
3. **User** types `/trellis:continue` → **AI** `trellis-implement` ships the smallest safe fix and adds the regression test before any broader cleanup (Phase 2.1).
4. **User** types `/trellis:continue` and hand-reviews whether the patch actually addresses the reported behavior → **AI** `trellis-check` runs the tests; the regression test must pass with the patch and fail without it (Phase 2.2).
5. **User** types `/trellis:continue` → **AI** runs `trellis-break-loop` for root-cause analysis (Phase 3.2) → **User** confirms whether the conclusion really prevents recurrence.
6. **User** types `/trellis:continue` → **AI** routes the prevention into a spec, test helper, or checklist via `trellis-update-spec` → **User** confirms whether each item is a long-term rule (Phase 3.3).
7. **User** types `/trellis:finish-work` → **AI** archives the task and records the session journal.
### 5.4 Done means
* The patch fixes the reported behavior.
* A regression test fails without the fix.
* The root cause is documented.
* A prevention mechanism exists outside the chat transcript.
## 6. Reduce repeated review feedback
Use this when reviewers keep writing the same comments: missing loading states, inconsistent errors, no regression tests, unsafe SQL, custom date formatting, or new helpers that duplicate existing utilities.
### 6.1 Starting prompt
```text theme={null}
Review the last few PR comments and help me convert repeated engineering feedback into Trellis specs.
Only propose rules that are concrete, enforceable, and tied to actual review comments. For each rule,
show the target spec file and a good/bad example.
```
### 6.2 Convert feedback into specs
| Repeated review comment | Better spec rule |
| ---------------------------------------- | ------------------------------------------------------------------------------- |
| "This needs a loading state." | "Every async submit button has idle, loading, success, and error states." |
| "Do not use `any` here." | "Public component props cannot use `any`; use explicit interfaces or generics." |
| "This API error format is inconsistent." | "All route handlers return `ApiError` through `toApiError()`." |
| "We already have a helper for this." | "Search `src/lib/formatters/` before adding a date or currency formatter." |
### 6.3 Workflow
1. **User** describes which PR feedback is worth capturing in natural language (pasting PR links or the comment list); groups the feedback with AI by engineering rule during planning → **AI** classifies the request and asks for Trellis task creation. After the user agrees, AI loads `trellis-brainstorm`, inspects the supplied feedback before asking repo-answerable questions, creates the spec-tightening task (`task.py create`), and records the target review patterns, scope, and acceptance criteria into `prd.md` (Phase 1.1).
2. **User** collects repeated feedback from real PRs, groups it by engineering rule (one spec file per group), and pastes the grouping into the PRD.
3. **User** types `/trellis:continue` → **AI** `trellis-update-spec` adds each short rule to the most relevant spec file with a good/bad code example → **User** reviews wording for accuracy.
4. **AI** wires the updated specs into the next development task's `check.jsonl` so `trellis-check` can verify the rules catch issues.
5. **User** runs a real task or two and observes which rules failed to catch issues or created noise → **AI** removes or rewrites those rules via `trellis-update-spec`.
6. **User** types `/trellis:finish-work` → **AI** archives the spec-tightening task and records the session journal.
## 7. Roll out to a team
Use this when Trellis adoption involves multiple developers, repos, or AI tools.
### 7.1 Example situation
A 50-person engineering department has Claude Code power users, Cursor users, and developers experimenting with other AI tools. Leadership wants shared conventions and reviewable AI work without forcing everyone into one IDE.
### 7.2 Starting prompt
```text theme={null}
Create a Trellis rollout plan for one pilot repo and one department.
Include pilot criteria, first specs, task workflow, review policy for spec changes, platform adapter
setup, success metrics, and risks. Keep the first rollout small enough to complete in two weeks.
```
### 7.3 Rollout phases
| Phase | Goal | Exit criteria |
| ----- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | Pilot one repo | One real task completed with specs, checks, and journal. Two options for the spec starting point: pull a stack-matched spec pack from the [spec template marketplace](/start/install-and-first-task#official-marketplace), or use `trellis-spec-bootstrap` so AI drafts first-pass specs from the real codebase |
| 2 | Capture repeated feedback | Three to five review patterns become specs |
| 3 | Standardize task workflow | Developers know when to describe work directly, when `/trellis:continue` advances an active task, and when `/trellis:finish-work` archives after commits |
| 4 | Add platform adapters | Multiple AI tools consume the same `.trellis/` context |
| 5 | Govern updates | Spec and workflow changes are reviewed like code |
### 7.4 Success metrics
* New AI sessions need less repeated explanation.
* PRDs describe scope and out-of-scope work more clearly.
* Repeated review comments decrease.
* Teams can switch AI tools without losing conventions.
* New developers complete a first task without relying on one senior engineer.
* Bugs that trigger root-cause analysis become specs, tests, or checklist updates.
## Pick the smallest next step
If you are unsure which scenario applies, start with one of these:
<CardGroup>
<Card title="New repo" icon="rocket" href="#1-start-a-new-project">
Bootstrap a small spec set and one foundation task.
</Card>
<Card title="Existing repo" icon="folder-open" href="#2-adopt-an-existing-project">
Extract conventions from current code before changing behavior.
</Card>
<Card title="Refactor" icon="split" href="#4-refactor-a-legacy-module">
Define invariants, tests, and module boundaries before editing.
</Card>
<Card title="Team rollout" icon="users" href="#7-roll-out-to-a-team">
Pilot Trellis in one repo before expanding usage.
</Card>
</CardGroup>
# Building an AI Collaborative Development System in Real Projects
Source: https://docs.trytrellis.app/blog/ai-collaborative-dev-system
A few days ago, Anthropic published an article about their internal AI-assisted development approach—giving AI "long-term memory" so it can remember project specifications, past decisions, and coding style. The concept is inspiring, but their explanation was fairly theoretical without much practical implementation detail.
Our team recently tried implementing this approach in the Mosi project, extending it significantly to handle real multi-person collaboration scenarios. This article covers how we did it, what pitfalls we encountered, and what the final system feels like in practice.
## 1. Starting Point: The Gap Between Anthropic's Vision and Reality
Anthropic's core idea is: **don't start every AI conversation from scratch—let the AI see the project's "memory" from the beginning**.
This "memory" includes:
* Project tech stack and architecture specifications
* Code style conventions
* Previously discussed design decisions
* Solutions to common problems
Their approach is to organize this content into documentation within the project, then feed relevant documents to the AI during conversations. This way, the AI can work like "an experienced employee who knows the project background" rather than needing everything explained from scratch each time.
Sounds simple, but implementing this in a real multi-person collaborative project raises many practical issues:
* **What about multiple developers working simultaneously?** If everyone's progress is recorded in a single file, conflicts are inevitable.
* **What if specification documents are too long?** Our frontend spec has over 1600 lines, backend specs have hundreds more. Feeding everything to AI would blow the token limit, and most content isn't relevant to the current task anyway.
* **How do we ensure code quality?** AI-written code can't go directly to the main branch—someone needs to review and test it.
* **How do we track AI's work?** If something goes wrong, how do we trace what the AI actually did?
We designed solutions for these problems in the Mosi project.
## 2. Implementation: Four Core Design Decisions
### 1. Multi-Person Collaboration: Each Developer Gets an Independent Progress Folder
Anthropic's article barely mentions multi-person collaboration, but this is unavoidable in real projects.
Our approach: **create an independent folder for each developer (including AI) under `workflow/agent-progress/`**.
For example:
```plaintext theme={null}
workflow/
├── agent-progress/
│ ├── taosu/ # Developer taosu's progress
│ │ ├── index.md
│ │ └── progress-1.md
│ ├── developer2/ # Developer developer2's progress
│ │ ├── index.md
│ │ └── progress-1.md
```
Each folder has an `index.md` that records what this developer is currently working on, how far they've progressed, and what problems they've encountered. AI reads this file before starting work to understand context; after work, it updates this file to record new progress.
This way multiple developers can work simultaneously without interfering with each other.
### 2. Solving Information Overload: Two-Layer Index System
As mentioned, our spec documents are long (frontend 1600+ lines, backend hundreds of lines). In practice, we found that feeding complete documents to AI causes several problems:
**Why do we need a structured system?**
1. **Information overload**: When AI needs to implement a "keyboard shortcut feature," if it reads all 1600 lines of frontend specs, it gets distracted by irrelevant content—like "API calling conventions," "state management specs," etc. These are important but unhelpful for the current task, reducing AI's focus.
2. **Token economics**: In long conversations, if we read complete documents every time, token consumption accumulates rapidly. With 20 rounds of interaction, repeatedly reading documents wastes significant cost.
3. **Knowledge navigation**: Developers (and AI) need to quickly answer "I'm implementing feature X—which part of the spec should I read?" Without a clear navigation system, they can only rely on full-text search or reading chapter by chapter, which is very inefficient.
### Our Solution: Two-Layer Structure
We designed an `index.md + doc.md` two-layer knowledge system:
```plaintext theme={null}
workflow/
├── frontend-structure/
│ ├── index.md # Index layer: quick navigation (~100 lines)
│ └── doc.md # Detail layer: complete spec (1600+ lines)
```
**What is index.md?**
`index.md` is a **lightweight navigation table** that lists all spec chapters with explicit line number ranges. More importantly, it's organized by **development task type**, not document structure.
For example:
```markdown theme={null}
# Frontend Development Spec Index
> **Complete doc**: See `./doc.md` for detailed specifications
This index helps you quickly locate the spec chapters you need. Find the corresponding chapters and line numbers based on the type of feature you're developing.
## Related Workflow Documents
| Document | Use Case |
| ----------------------------------- | ----------------------------- |
| `../frontend-figma-workflow/doc.md` | Developing from Figma designs |
## Quick Navigation
| Development Task | Chapters to Read | Line Range |
| ---------------------------------------- | ------------------------------------------ | ---------- |
| **New feature module** | Directory structure spec | L5-36 |
| **Writing Command Palette** | Component dev spec > Command Palette | L876-1425 |
| **Writing Query Hook** | Hook dev spec > Query Hook | L179-265 |
| **Writing Mutation Hook** | Hook dev spec > Mutation Hook | L266-351 |
| **Calling backend API** | API calling spec | L382-735 |
| **Real-time communication (WebSocket)** | API calling spec > Real-time | L419-465 |
| **AI streaming response (SSE)** | API calling spec > SSE | L466-497 |
| **AI Tool Calls handling** | API calling spec > Tool Calls | L498-735 |
| **State management** | State management spec | L736-873 |
| **URL state sync** | State management spec > URL/Context | L738-873 |
| **Writing components** | Component dev spec | L874-1645 |
| **Accessibility and image optimization** | Component dev spec > Semantic HTML & Image | L1426-1544 |
| **Performance optimization** | Performance optimization spec | L1676-1762 |
| **Code quality check** | Code quality and formatting spec | L2140-2317 |
| **Code review** | General rules + Checklist | L1763-2344 |
......
```
**Core advantages:**
1. **Instant Knowledge Access**: AI only needs to read \~100 lines of index.md to locate "implementing keyboard shortcuts requires reading lines 876-1425" within seconds. This is much faster than full-text search or browsing chapter by chapter.
2. **On-Demand Loading**: AI reads only relevant sections of `doc.md` based on the current task (e.g., 500 lines instead of 1600). This saves tokens while avoiding information overload.
3. **Standardized Workflow**: This two-layer structure becomes a team standard—everyone (including AI and newly joined human developers) knows "read index first, then doc." This reduces cognitive load and improves collaboration efficiency.
**Workflow:**
1. AI reads `index.md` to understand the overall spec structure
2. Based on the current task (e.g., "implement keyboard shortcut"), AI finds "Writing Command Palette → L876-1425" in the navigation table
3. AI precisely reads lines 876-1425 of `doc.md` for detailed implementation guidance
4. AI writes code following the spec, avoiding "not knowing where to start" or "missing key details"
### Fundamental Difference from Claude Skills
You might ask: Didn't Anthropic release Claude Skills? Why not just use Skills instead of building this structure ourselves?
This is because they solve different problems:
* **Claude Skills** are **ecosystem-driven general capability packages**, designed for cross-project reuse. Things like "git operations," "Python testing," "filesystem operations"—these capabilities apply to any project. Skills pursue **breadth and reusability**.
* **Our structure** is a **project-specific deep customization system** that indexes and stores Mosi project's specific architecture, tech stack, state management patterns, API calling conventions, etc. This knowledge is unique to the project and cannot be reused across projects. Our system pursues **depth and precision**.
A concrete example:
* **Skills can teach AI**: "How to write a React component" (general knowledge)
* **Our doc.md teaches AI**: "In the Mosi project, how to write components following our specific architecture (Monorepo + Turborepo), state management patterns (Zustand + URL state sync), API calling conventions (tRPC + SSE + Tool Calls)" (project-specific knowledge)
Skills are like a "general toolbox"; our structure is like "project blueprints." They're not replacements but complements—Skills provide foundational capabilities, structure provides project-specific implementation details.
We use the same organizational approach for backend specs.
### 3. Encapsulating Best Practices: Short Command System
To standardize the development process, we defined a series of "short commands," each corresponding to a specific operation.
Short commands are stored in the `.cursor/commands/` directory, each command as a `.md` file.
Currently common short commands include:
* `/init-agent`: Initialize AI session, having AI read the current developer's progress and relevant specs
* `/check-frontend`: Have AI check if frontend code follows specifications
* `/check-backend`: Have AI check if backend code follows specifications
* `/record-agent-flow`: Record this AI session's work content to the progress file
**What are short commands?**
Short commands are essentially **predefined prompt templates**. Each `.md` file contains a complete AI instruction.
For example, `check-frontend.md` might contain:
```markdown theme={null}
Check your own work—does the code you just wrote follow frontend development specs? First use git status to see which files were modified, then go to `.cursor/rules/frontend-structure/index.md` to find the corresponding doc details and check against `.cursor/rules/frontend-structure/doc.md`
...
```
**How it works:**
When a developer types `/check-frontend` and hits enter:
1. Cursor automatically reads the content of `.cursor/commands/check-frontend.md`
2. Injects this content as a prompt into the current conversation
3. AI performs the corresponding check operations based on this prompt
**Why use short commands?**
Because every time you ask AI to do code checking or progress recording, you need to input a detailed checklist or operational steps. If these instructions aren't detailed enough, AI output quality becomes inconsistent.
Short commands encapsulate these **best practice prompts**—developers just type `/check-frontend`, which is equivalent to sending a carefully designed complete prompt, ensuring instruction consistency and completeness.
Plus, short commands can be shared across the team, so new members can immediately benefit from accumulated team experience.
> Think of short commands as a kind of prompt SDK—using a short command is like calling a specialized SDK our team built for a specific scenario
### 4. Quality Gate: Human Developer Review Mechanism
Although AI can write code, we don't let AI commit directly. **All code requires human developer review and testing before it can be committed**.
The typical flow is:
1. AI writes code
2. Developer runs locally to check if functionality works
3. Developer reviews code for obvious issues
4. If there are problems, have AI fix them; if not, developer commits manually
This way we get AI's efficiency while ensuring code quality.
## 3. Practice: A Complete Development Flow
The design concepts above might still be abstract. Below is a real example showing the complete development flow.
**Background:**
I need to implement a keyboard shortcut feature on the frontend—pressing `Cmd+K` to open the search box. I've already created a Git branch `feat/keyboard-navigation` locally.
### Initialize AI Session
```plaintext theme={null}
Me: /init-agent
```
When I input this short command, Cursor injects the content of `init-agent.md` into the conversation. This template defines the initialization steps AI needs to perform:
**AI executes according to short command guidance:**
1. Read `workflow/agent-progress/taosu/index.md` to understand my current progress and context
2. Read `workflow/frontend-structure/index.md` to understand the overall frontend spec structure
3. If needed, read further into relevant chapters of `doc.md`
**AI's response:**
```plaintext theme={null}
Okay, I've read your progress record and frontend specs.
Current branch: feat/keyboard-navigation
Task: Implement keyboard shortcut feature (Cmd+K opens search)
I noticed the frontend spec has a "Keyboard System" chapter—I'll implement according to those specifications.
Ready. Tell me what specifically needs to be done.
```
### Describe Requirements
```plaintext theme={null}
Me: Help me implement a global keyboard shortcut—when pressing Cmd+K (Mac) or Ctrl+K (Windows),
open the search box. The search box component already exists at components/SearchModal.tsx.
```
**What AI does:**
1. Based on the "keyboard shortcut" keyword, read the "Keyboard System" chapter in `workflow/frontend-structure/doc.md`
2. Learn that the project already has a `useKeyboardShortcut` hook ready to use
3. Write code: call this hook in the appropriate place to bind Cmd+K shortcut
**AI's response:**
```plaintext theme={null}
Okay, here's my implementation:
1. Use useKeyboardShortcut hook in the SearchModal component
2. Listen for Cmd+K / Ctrl+K, trigger search box open
3. Close search box on ESC
Code is written, file path:
- components/SearchModal.tsx (modified)
You can run locally to see the effect.
```
### Local Testing
I run the project locally, press `Cmd+K`, search box opens successfully. Feature works.
### Code Self-Check
```plaintext theme={null}
Me: /check-frontend
```
When I input this short command, Cursor automatically injects the content of `check-frontend.md` (a detailed code check list) into the conversation.
**AI executes check according to short command template:**
Following check items defined in the template, reviews the code just written:
* Check if component naming follows conventions
* Check if React hooks dependency arrays are complete
* Check if type definitions are strict
* Check for potential performance issues\
...
**AI's response:**
```plaintext theme={null}
Checked and found two minor issues:
1. useKeyboardShortcut dependency array was missing a state
2. Type definitions could be stricter
Already fixed for you—should be fine after running again.
```
I retest and confirm no issues.
### Commit Code
```bash theme={null}
git add .
git commit -m "feat: add Cmd+K keyboard shortcut for search"
git push origin feat/keyboard-navigation
```
### Record Flow
```plaintext theme={null}
Me: /record-agent-flow
```
Cursor injects the content of `record-agent-flow.md` into the conversation—this template guides AI on how to record the workflow.
**AI executes according to template guidance:**
1. Summarize this session's work content (requirements, implementation approach, problems encountered, solutions, etc.)
2. Format and append this information to `workflow/agent-progress/taosu/index.md`
**AI's response:**
```plaintext theme={null}
Recorded this session's workflow to your progress file.
Main content:
- Implemented global keyboard shortcut Cmd+K for search
- Used useKeyboardShortcut hook
- Fixed dependency array and type definition issues
- Committed to branch feat/keyboard-navigation
```
This way, next time I continue working with AI, it can quickly understand what I've been doing recently by reading this progress file.
## 4. Pitfalls and Solutions
### Problem 1: Learning Curve for Short Commands
New team members need to learn which short commands exist and what each does.
We provide an `/onboard-developer` short command to guide newcomers. New members just run this command, and AI follows the preset guidance flow to introduce the entire workflow system, common short commands, and how to start the first task.
### Problem 2: AI "Forgets" Specs in Long Conversations
Even if AI reads all specs via `/init-agent` at session start, as conversation turns increase and context lengthens, AI may gradually "forget" the initially read development spec details. This causes AI to drift from spec requirements when writing code.
Our solution: **use short commands at key points to force AI to re-consult specs**.
For example, the `/check-frontend` short command template explicitly requires AI to:
1. First use `git status` to see which code was just modified
2. Based on the change type (e.g., "added a new Hook"), find the corresponding chapter in `index.md`
3. Re-read the relevant part of `doc.md` (e.g., "Hook dev spec L179-265")
4. Check code against specs item by item
This way, even if context is already very long, AI will **mandatorily** re-learn the specs when checking code, ensuring code quality doesn't decline due to "forgetting."
This is also why we encapsulate these operations as short commands—not just for convenience, but to **enforce quality assurance processes at key workflow points**.
## 5. Summary and Future Plans
Anthropic's "AI long-term memory" concept is valuable, but truly implementing it in real multi-person collaborative projects requires solving many engineering problems.
Our practice in the Mosi project did these core things:
* **Multi-person collaboration support**: Each developer has an independent progress folder
* **Spec index system**: index.md + doc.md structure lets AI efficiently find specs
* **Short command system**: Encapsulates common operations, improves development efficiency
* **Human in the loop**: AI writes code, humans review and commit, ensuring quality
This system is still being continuously improved, but we can already feel noticeable improvements in development efficiency.
Improvements we might make next:
* **Automate more processes**: e.g., let AI automatically create branches, automatically write commit messages
* **Smarter spec indexing**: Currently AI manually judges which chapters to read; in the future, AI could automatically match relevant chapters based on task descriptions
* **Team knowledge base**: Organize design decisions discussed by the team and pitfalls encountered into documentation, so AI can learn from this experience
If you're also trying AI-assisted development, I hope this article gives you some inspiration. Welcome to discuss.
***
## Resources
* Anthropic's original article: [Building effective agents](https://www.anthropic.com/research/building-effective-agents)
# Overview
Source: https://docs.trytrellis.app/blog/index
| Article | Date |
| ----------------------------------------------------------------------------------------------------- | ----------- |
| [Understanding Trellis Through Kubernetes](/blog/use-k8s-to-know-trellis) | Feb 1, 2026 |
| [Building an AI Collaborative Development System in Real Projects](/blog/ai-collaborative-dev-system) | Feb 1, 2026 |
# Understanding Trellis Through Kubernetes
Source: https://docs.trytrellis.app/blog/use-k8s-to-know-trellis
2026-02-01
> If you're familiar with Kubernetes, this document will help you quickly grasp Trellis's design philosophy.
<Note>
This article was written in the Trellis 0.4.x era. Some named concepts have changed since: the
Ralph Loop, `dispatch` / `plan` / `debug` agents, and the Multi-Agent Pipeline were all removed
during the 0.5.0 prerelease. The high-level K8s analogy still applies; read specific agent / hook
names here as historical references.
</Note>
***
## Table of Contents
1. [K8s Core Concepts Overview](#1-k8s-core-concepts-overview)
2. [Trellis and K8s Analogy](#2-trellis-and-k8s-analogy)
3. [Reconciliation Mechanism Deep Dive](#3-reconciliation-mechanism-deep-dive)
4. [Complete Workflow](#4-complete-workflow)
5. [Why This Design](#5-why-this-design)
***
## 1. K8s Core Concepts Overview
### Imperative vs Declarative
**Imperative**: Describe "how to do it"
```bash theme={null}
# Step-by-step instructions for the system
current_pods=$(kubectl get pods -l app=nginx --no-headers | wc -l)
if [ $current_pods -lt 3 ]; then
kubectl run nginx --image=nginx:1.19
fi
```
**Declarative**: Describe "what you want"
```yaml theme={null}
# Just state the desired end state
apiVersion: apps/v1
kind: Deployment
spec:
replicas: 3
template:
spec:
containers:
- name: nginx
image: nginx:1.19
```
| Dimension | Imperative | Declarative |
| -------------- | --------------------------- | ---------------------- |
| Focus | Process (How) | Result (What) |
| Executor | User orchestrates each step | System auto-reconciles |
| Idempotency | Requires extra handling | Naturally idempotent |
| Error Recovery | Requires user intervention | Self-healing |
### Control Loop
The core of K8s is the **Control Loop**:
```
Desired State Actual State
(User declares) (System observes)
| |
+---> Controller <----+
|
Observe → Diff → Act → Repeat
```
**Power in action**:
```
I declare: I want 3 nginx Pods
A Pod gets accidentally deleted → Controller detects 2 ≠ 3 → Auto-creates 1
I modify declaration to 5 → Controller detects 3 ≠ 5 → Auto-creates 2
No manual intervention needed. System auto-detects, auto-recovers, auto-adapts.
```
***
## 2. Trellis and K8s Analogy
### Architecture Mapping
```
┌─────────────────────────────────────────────────────────────┐
│ Kubernetes │
│ │
│ YAML Manifest ──> Controller ──> Actual State │
│ (Desired State) (Reconcile) (Actual State) │
└─────────────────────────────────────────────────────────────┘
↕
┌─────────────────────────────────────────────────────────────┐
│ Trellis │
│ │
│ Task Dir ──> Dispatch + Ralph Loop ──> Compliant Code │
│ (Desired State) (Reconcile) (Actual State) │
└─────────────────────────────────────────────────────────────┘
```
### Core Component Mapping
| Kubernetes | Trellis | Description |
| ------------------- | -------------- | ------------------------------- |
| YAML Manifest | Task Directory | Declares desired state |
| Controller | Dispatch | Orchestrates phase execution |
| Reconciliation Loop | Ralph Loop | Loops until verification passes |
| Pod/Container | Agent | Actual execution unit |
| ConfigMap | jsonl + Hook | Injects config/context |
| Actual State | Final Code | Product after reconciliation |
### Key Insight
K8s solves: **Infrastructure complexity** — Uses declarative to abstract away details, Controller handles reconciliation.
Trellis solves: **AI development uncertainty** — Uses declarative to define expectations (prd.md + guidelines), Ralph Loop handles reconciliation.
Common ground:
* Users only declare "what they want", don't worry about "how to do it"
* System continuously reconciles until actual state matches desired
* Auto-repairs when deviations occur
> Next, Chapter 3 details the reconciliation mechanism (Hook + Ralph Loop), and Chapter 4 expands on the complete workflow (Phase 1-4).
***
## 3. Reconciliation Mechanism Deep Dive
Trellis reconciliation is achieved through two mechanisms working together: **Hook Injection** and **Ralph Loop**.
### Hook Injection
**Timing**: Automatically triggered each time a Subagent is called
**Function**: Injects file contents referenced in jsonl into the Agent's context
```
Plan/Research Agent finds needed files in advance
│
▼
Writes to implement.jsonl / check.jsonl
│
▼
Dispatch calls Subagent
│
▼
Hook intercepts, reads jsonl, injects file contents
│
▼
Subagent receives complete context, starts working
```
**jsonl file example**:
```jsonl theme={null}
{"file": ".trellis/spec/backend/index.md", "reason": "Backend guidelines"}
{"file": "src/api/auth.ts", "reason": "Existing auth pattern"}
```
**Why this design**:
* Prevents context overload (Context Rot) — Only injects what's needed for current phase
* Traceable — jsonl records what context each task used
* Decoupled — Agent doesn't need to search, focuses on execution
### Ralph Loop
**Essence**: A programmatic quality gate that intercepts Agent stop requests and forces continuation if verification fails.
**Trigger timing**: When Check Agent attempts to stop
**Flow**:
```
Check Agent attempts to stop
│
▼
SubagentStop Hook triggers ralph-loop.py
│
▼
Has verify config?
│
┌────┴────┐
Yes No
│ │
▼ ▼
Run verify Check completion
commands markers
(pnpm lint) (parse from output)
│ │
▼ ▼
┌──┴──┐ ┌──┴──┐
│Pass │ │Complete│
│ │ │ │
▼ ▼ ▼ ▼
allow block allow block
(stop) (continue) (stop) (continue)
Max 5 iterations, then force allow
```
**verify config example** (worktree.yaml):
```yaml theme={null}
verify:
- pnpm lint
- pnpm typecheck
```
**Why use programmatic verification instead of letting AI judge**:
* Programmatic verification is reliable — lint pass means pass, doesn't depend on AI's judgment
* Configurable — Different projects can configure different verification commands
* Prevents infinite loops — Max 5 iterations, then force allow
**Limitations**:
* Complex architectural issues or logic bugs may require human intervention
* Depends on guideline quality; unclear guidelines lead to limited check effectiveness
***
## 4. Complete Workflow
### Phase Overview
```
Task Directory
├── prd.md (Task requirements)
├── implement.jsonl (Implementation phase context)
├── check.jsonl (Check phase context)
└── task.json (Metadata)
│
▼
┌───────────────────────────────────────────────┐
│ Phase 1: implement │
│ ───────────────── │
│ Agent: Implement Agent │
│ Injects: prd.md + files from implement.jsonl │
│ Task: Write code based on requirements │
└───────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────┐
│ Phase 2: check │
│ ───────────────── │
│ Agent: Check Agent │
│ Injects: Guideline files from check.jsonl │
│ Task: Check code compliance, fix issues │
│ Reconcile: Ralph Loop verifies, loops if fail│
└───────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────┐
│ Phase 3: finish │
│ ───────────────── │
│ Agent: Check Agent (with [finish] flag) │
│ Injects: finish-work.md (Pre-Commit List) │
│ Task: Pre-commit completeness check │
│ - lint/typecheck/test passing │
│ - Documentation in sync │
│ - API/DB changes complete │
│ Reconcile: Skips Ralph Loop (already verified)│
└───────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────┐
│ Phase 4: create-pr │
│ ───────────────── │
│ Task: Create Pull Request │
└───────────────────────────────────────────────┘
│
▼
Compliant Code + PR
```
### Exception Path
If Check Agent reports unfixable issues, Dispatch can call **Debug Agent** for deep analysis. This is not the default flow, but exception handling.
***
## 5. Why This Design
### One-Click Complete Workflow
`/trellis:start` or `/trellis:parallel` (Claude Code only) launches with one click, AI completes the entire flow:
```
Plan → Implement → Check → Finish → PR
```
Users don't need to guide step-by-step. What to do at each phase, which guidelines to reference — it's all predefined.
### Continuous Accumulation of Development Guidelines
```
Guidelines stored in .trellis/spec/
│
▼
AI executes with guidelines ──> Finds issues ──> Updates guidelines
│ │
└────────────────────────────────────┘
Guidelines improve over time
```
Thinking Guides help discover "didn't think of that" problems.
### Preventing Context Rot
Too much context causes LLM to:
* **Distraction** — Gets sidetracked by irrelevant information
* **Confusion** — Information contradicts itself
* **Clash** — Old and new information conflict
Trellis injects by phase:
* implement phase: Requirements + related code
* check phase: Development guidelines
* finish phase: Pre-commit checklist
Each phase's Agent only receives context relevant to its task.
### Programmatic Quality Control
```
Traditional approach:
"Please check code quality" ──> AI says "I checked" ──> Did it really?
Trellis approach:
Ralph Loop runs pnpm lint ──> Pass to proceed ──> Programmatically guaranteed
```
Doesn't rely on AI's self-judgment, uses programmatic enforcement.
### Traceability
| Record | Content |
| --------- | ---------------------------- |
| jsonl | What context each task used |
| workspace | Work content of each session |
| task.json | Complete task lifecycle |
When issues arise, you can trace back to which file was missing, or which guideline was unclear.
***
## Summary
| Concept | K8s | Trellis |
| ------------------- | ------------- | ------------------------------- |
| Desired State | YAML Manifest | Task Directory (prd.md + jsonl) |
| Execution Unit | Pod/Container | Agent |
| Reconciliation Loop | Controller | Dispatch + Ralph Loop |
| Config Injection | ConfigMap | Hook + jsonl |
| Final Product | Running Pods | Compliant Code |
**Core philosophy aligned**: Declare desired → System reconciles → Eventually consistent.
# v0.5.10
Source: https://docs.trytrellis.app/changelog/v0.5.10
2026-05-09
## Bug Fixes
* **`git add -f .trellis/` runaway prevented.** `add_session.py` and `task.py archive` now stage only specific Trellis-owned paths (journal, `index.md`, active task dir, archive subtree) and auto-retry with `git add -f -- <specific-paths>` only when stderr matches `ignored by`. The fallback warning explicitly states `Do NOT use \`git add -f .trellis/\``, listing`.trellis/.backup-\*`,`.trellis/worktrees/`,`.trellis/.template-hashes.json`,`.trellis/.runtime/`,`.trellis/.cache/`as the paths to keep ignored. Helper centralized in`templates/trellis/scripts/common/safe\_commit.py\`.
* **Pi platform `<workflow-state>` / `<session-overview>` / subagent dispatch protocol injection.** Pi extension now injects the `[workflow-state:STATUS]` breadcrumb on every `input` and `before_agent_start` event, plus a `<session-overview>` block from `.trellis/scripts/get_context.py`. The `subagent` tool registration carries a `promptSnippet` with the `Active task: <path>` dispatch protocol. Closes [#249](https://github.com/mindfold-ai/Trellis/issues/249).
* **Pi `npm:pi-subagents` project-level isolation.** `.pi/settings.json` now contains a project-level `packages` entry overriding `npm:pi-subagents` with empty resource lists, so a globally-installed `npm:pi-subagents` cannot inject `extensions / skills / prompts / themes` into the current Trellis project. `scrubPiSettings` reverses the override on `trellis uninstall`. Closes [#246](https://github.com/mindfold-ai/Trellis/pull/246) (thanks @RenaLio).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.11
Source: https://docs.trytrellis.app/changelog/v0.5.11
2026-05-10
## Bug Fixes
* **`add_session.py` / `task.py archive` no longer force-stage with `git add -f`.** When `.gitignore` excludes `.trellis/`, scripts print a warning and skip auto-commit. Reverts the auto-retry added in 0.5.10.
## Enhancements
* **New config: `session_auto_commit: true | false`** in `.trellis/config.yaml` (default `true`). Set `false` to skip auto stage + commit; journal / archive files still write to disk. Closes [#245](https://github.com/mindfold-ai/Trellis/issues/245).
* **Session-start update hint.** `get_context.py` shows `Trellis update available: <current> -> <latest>` once per session when local install lags. 1-second timeout, failures silent. Closes [#254](https://github.com/mindfold-ai/Trellis/pull/254) (thanks @jdjingdian).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.12
Source: https://docs.trytrellis.app/changelog/v0.5.12
2026-05-10
## Bug Fixes
* **`trellis update` now updates hash-tracked `.trellis/workflow.md` as a whole runtime template.** The updater no longer merges only `[workflow-state:*]` blocks, so phase headings and platform routing markers such as `codex-inline` / `codex-sub-agent` refresh together. This fixes upgraded Codex installs that had new hook scripts but stale `[Codex]` workflow blocks.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.13
Source: https://docs.trytrellis.app/changelog/v0.5.13
2026-05-11
## Bug Fixes
* **OpenCode now injects `TRELLIS_CONTEXT_ID` with the shell dialect that parses the command.** Windows Git Bash / MSYS / Cygwin sessions receive `export ...`; Windows PowerShell sessions keep `$env:...`. Duplicate-prefix detection also recognizes `env ... TRELLIS_CONTEXT_ID=...` forms.
* **Session context now handles non-Git Trellis roots.** Context output says when the root is not a Git repository instead of reporting fake clean state, and falls back to bounded child-repo discovery for unconfigured polyrepo layouts.
* **OpenCode sub-agent context is isolated from main-session context.** `trellis-implement`, `trellis-check`, and `trellis-research` child sessions skip duplicate SessionStart / workflow-state injection. Active task lookup now uses session context, `Active task:` hints, or a single-session fallback.
* **Hook timeout defaults now survive slower Windows Python cold starts.** SessionStart hooks use 30 seconds, and per-prompt workflow injection uses 15 seconds across hook-based platforms.
* **Copilot SessionStart no longer prints stale diagnostics.** The hook removes the `Copilot currently ignores sessionStart hook output` system message and keeps `hookSpecificOutput.additionalContext` as the documented payload.
## Internal
* **Spec templates document shell-dialect-aware `TRELLIS_CONTEXT_ID` prefixes.** Platform and cross-platform guides now name the OpenCode Windows POSIX-shell signals that must keep `export ...`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.14
Source: https://docs.trytrellis.app/changelog/v0.5.14
2026-05-13
## Bug Fixes
* **`task.py archive` auto-commit no longer bundles dirty changes from other task dirs.** The archive commit is now scoped to just the archived task's source + destination paths (plus any child task dirs whose `task.json` was edited as part of the parent → children relationship update). If you were editing task B in a parallel terminal while archiving task A, B's changes stay in your working tree where they belong.
* **`task.py archive` no longer leaves "phantom delete" entries against HEAD.** After `shutil.move`-ing a tracked task directory into `archive/<YYYY-MM>/`, the source-side deletions are now explicitly staged so the working tree matches HEAD immediately after archive. No more follow-up "complete archive move" fixup commits.
## Internal
* **New integration test** under `packages/cli/test/scripts/task-archive.integration.test.ts` runs the real Python script against a temp git repo and asserts both regressions (scope-creep + phantom-delete) stay fixed.
* **`safe_archive_paths_to_add()`** accepts optional `task_name` + `modified_children` parameters. Existing callers passing no arguments keep the legacy wide scope.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.15
Source: https://docs.trytrellis.app/changelog/v0.5.15
2026-05-13
## Bug Fixes
### Template manifest ownership
`trellis init`, `trellis update`, and `trellis uninstall` no longer treat user-owned platform runtime files as Trellis templates.
* `initializeHashes()` tracks platform/root files from `startRecordingWrites()` output instead of walking `.codex/`, `.claude/`, and other platform dirs.
* `pruneOrphanManifestKeys()` removes stale orphan entries from `.trellis/.template-hashes.json` before `update` and `uninstall`.
* `trellis init` and `trellis uninstall` refuse to run in `$HOME` unless `TRELLIS_ALLOW_HOMEDIR=1`.
### Windows hook encoding
Hook templates force UTF-8 on Windows for stdin, stdout, and stderr.
* `hooks.json` runs Codex `inject-workflow-state.py` with `python -X utf8`.
* `shared-hooks/inject-workflow-state.py`, `shared-hooks/session-start.py`, `codex/hooks/session-start.py`, and `copilot/hooks/session-start.py` reconfigure streams to UTF-8 with replacement errors.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.16
Source: https://docs.trytrellis.app/changelog/v0.5.16
2026-05-15
## Bug Fixes
### Cursor sessionStart hook
Cursor `sessionStart` output now matches Cursor's top-level context schema.
* Output field: `additional_context`
* Shared format retained: `hookSpecificOutput.additionalContext`
* Removed unsupported Cursor hook: `beforeSubmitPrompt`
* Removed copied Cursor file: `.cursor/hooks/inject-workflow-state.py`
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No file migration is required.
# v0.5.17
Source: https://docs.trytrellis.app/changelog/v0.5.17
2026-05-17
## Enhancements
### Built-in Trellis spec bootstrap skill
Trellis now bundles `trellis-spec-bootstarp` as a built-in multi-file skill.
* Installed automatically by `trellis init` and refreshed by `trellis update` for supported AI platforms
* Helps AI bootstrap `.trellis/spec/` from the real repository instead of generic placeholder guidance
* Includes source-backed reference files for repository analysis, spec task planning, spec writing, and MCP setup
* Replaces the older marketplace-only `cc-codex-spec-bootstrap` entry in the docs and marketplace index
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No migration command is required.
# v0.5.18
Source: https://docs.trytrellis.app/changelog/v0.5.18
2026-05-19
## Bug Fixes
### Archived task create collisions
`task.py create` now rejects a slug that already exists in `.trellis/tasks/archive/**`.
* Checks archived task directories before creating a new active task directory
* Prints the archived path that caused the collision
* Tells the user to choose a new slug for an intentional new task
### Workflow-state tool routing
`[workflow-state:in_progress]` now distinguishes sub-agent types from skills.
* `trellis-implement` and `trellis-research` are sub-agent types only
* `trellis-update-spec` is a skill
* `trellis-check` exists as both; verification after code changes should prefer the Agent form
* Prevents agents from trying to call missing `trellis-implement` / `trellis-research` skills
### Codex multi\_agent\_v2 timeout bounds
`.codex/config.toml` now emits the `multi_agent_v2` wait timeout values as a valid bounds set for Codex CLI 0.131+.
```toml theme={null}
[features.multi_agent_v2]
enabled = true
max_concurrent_threads_per_session = 6
min_wait_timeout_ms = 480000
default_wait_timeout_ms = 480000
max_wait_timeout_ms = 3600000
```
* Fixes Codex startup failure: `default_wait_timeout_ms must be at least min_wait_timeout_ms`
* Keeps the Trellis default wait at 8 minutes
* Keeps the explicit upper clamp at 1 hour
* Covers fresh `trellis init` and template refresh through `trellis update`
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No migration command is required.
# v0.5.19
Source: https://docs.trytrellis.app/changelog/v0.5.19
2026-05-21
## Bug Fixes
### Codex config.toml multi\_agent\_v2 block removed
`trellis init` / `trellis update` no longer write a `[features.multi_agent_v2]` block to the generated `.codex/config.toml`.
* Template source: `packages/cli/src/templates/codex/config.toml`
* Removed fields: `enabled`, `max_concurrent_threads_per_session`, `min_wait_timeout_ms`, `default_wait_timeout_ms`, `max_wait_timeout_ms`
v0.5.18 emitted the structured `multi_agent_v2` table. Codex CLI changed `features` deserialization between `0.130` and `0.131`: the structured table form is only accepted by `0.131+`. On `0.130` and earlier — including the Codex CLI bundled in the Codex desktop app — it fails with `data did not match any variant of untagged enum FeatureToml in features.multi_agent_v2` and aborts the entire config load, blocking Codex from starting. Codex's own default for `multi_agent_v2` is used instead; tune it in your user-level `~/.codex/config.toml` if needed.
Run `trellis update` to regenerate `.codex/config.toml` without the block.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No migration command is required.
# v0.6.0
Source: https://docs.trytrellis.app/changelog/v0.6.0
2026-06-15
Stable promotion of `0.6.0-rc.0` with no new src/ changes. v0.6.0 is a breaking release from 0.5.x — multi-agent collaboration via `trellis channel`, a published `@mindfoldhq/trellis-core` SDK, and cross-session memory recall via `trellis mem`.
<Tip>
**Multi-agent collaboration is now a first-class primitive.** `trellis channel` ships a
worker-supervisor runtime with Claude `stream-json` and Codex `app-server` adapters, persistent
event logs under `~/.trellis/channels/`, forum/thread channels for issue-style boards, a default
OOM guard, and reusable lifecycle/subscription APIs in `@mindfoldhq/trellis-core/channel`. The
bundled `check` / `implement` agent definitions auto-install with `trellis init` / `trellis
update`, so `channel spawn --agent check` works out of the box. See the "[Multi-agent
collaboration](#multi-agent-collaboration)" section below.
</Tip>
<Note>
**Codex users — upgrade caveat in 0.6.0:**
* **`[features.multi_agent_v2]` block removed (beta.21)** — Codex CLI changed `features` deserialization between 0.130 and 0.131. The structured table form only loads on 0.131+; on 0.130 and earlier (including the Codex desktop app's bundled CLI) it failed with `data did not match any variant of untagged enum FeatureToml in features.multi_agent_v2` and aborted config load. `trellis init` / `trellis update` no longer write this block — Codex's own default is used. Tune it yourself in `~/.codex/config.toml` if needed.
* **`codex.dispatch_mode: inline` is the default (beta.1)** — Codex sub-agents run with `fork_turns="none"`, so they can't inherit the parent session's task context. The main Codex agent now edits code directly. Opt back into sub-agent dispatch via `codex.dispatch_mode: sub-agent` in `.trellis/config.yaml`.
</Note>
<Note>
**New platforms in 0.6.0:**
* **Reasonix (DeepSeek-Reasonix)** — 15th supported AI coding tool, available via `trellis init --reasonix`. Skills live at `.reasonix/skills/<name>/SKILL.md`; slash commands are platform-built-in. Sub-agent skills carry `runAs: subagent` for isolated subagent loops. Closes `#301`.
* **Pi Agent — native `trellis_subagent` extension** — Pi now exposes `trellis_subagent` (avoiding the `subagent` namespace collision with community packages) with `single` / `parallel` / `chain` dispatch modes, native progress cards (`Alt+O` for detail view), throttled live updates, and Trellis-agent validation. Closes `#286`, `#290`.
</Note>
<Note>
**OpenCode users — reader temporarily unavailable:**
* **`trellis mem` returns empty on OpenCode 1.2+** — OpenCode 1.2 moved session storage to SQLite. The beta.3 SQLite reader added a `better-sqlite3` native dependency that failed to install on machines without a C toolchain, so it was reverted in beta.4. `trellis mem list / search / extract` now returns empty with a one-shot stderr warning for OpenCode; Claude and Codex paths are unchanged. A permanent OpenCode reader rework is deferred past v0.6.0.
</Note>
<Warning>
**Known upstream issues at GA cut (not fixable from Trellis):**
* **OpenCode 1.2+ SQLite session reader** — see the `<Note>` above. Tracked for v0.7+.
* **Feature requests deferred past v0.6** — `#193`, `#318`, `#320`, `#325`, `#326` and similar tracker items are explicitly punted to v0.7 or later per the `rc.0` cut.
</Warning>
## Multi-agent collaboration
`trellis channel` is the headline addition of v0.6.0 — a worker-supervisor primitive for coordinating multiple AI processes through a shared event log.
### `trellis channel` runtime
* `channel create | send | wait | spawn | run | list | messages | kill | rm | prune` subcommands.
* Claude `stream-json` and Codex `app-server` JSON-RPC adapters translate provider output into normalized `message` / `progress` / `done` / `error` events.
* Events persist to `~/.trellis/channels/<project>/<channel>/events.jsonl` with locked sequence assignment.
* Every subcommand accepts `--scope project|global` for explicit project-or-global targeting.
### Forum and thread channels
`--type threads` and `--type forum` produce durable issue/thread-style boards. `channel post | threads | thread | forum` subcommands plus `channel context add | delete | list`, `channel title set | clear`, and `channel thread rename` cover the lifecycle. Events can carry stable `--description`, `--context-file`, `--context-raw` (legacy `--linked-context-*` aliases preserved).
### Worker coordination
* `channel wait --kind done,killed` — multi-kind filter.
* `channel spawn --warn-before <duration>` emits a `supervisor_warning` event (5m default lead time; disable via `0ms`).
* Codex workers record completed answers before `done` and serialize non-interrupt turns (`turn_started` / `turn_finished` / `interrupt_requested` / `interrupted`).
* Codex channel `progress` events carry `detail.kind` (`output | commentary | reasoning`), `detail.stream_id`, `detail.phase`, `detail.text_delta`. Consumers should group deltas by `stream_id` and treat `kind:"message"` as the canonical completed answer.
### Channel worker OOM guard
Default safeguards `channel.worker_guard.idle_timeout` (5m) and `channel.worker_guard.max_live_workers` (6), configurable per-spawn (`--idle-timeout`, `--max-live-workers`) or via env vars (`TRELLIS_CHANNEL_WORKER_IDLE_TIMEOUT`, `TRELLIS_CHANNEL_MAX_LIVE_WORKERS`). Idle workers emit `killed` with `reason: "idle-timeout"`; mid-turn workers are never killed.
### Message-routing cleanup + durable idempotency
Tag-based routing is removed from `send.ts` / `wait.ts` / provider adapters — tags are kept only on channel events, worker inbox policy, and explicit `to`. `sendMessage` and `postThread` accept a durable `idempotencyKey` option: repeated writes with the same key return the original JSONL event without producing duplicate `undeliverable` events.
### Channel runtime agent definitions auto-dispatched
`trellis init` and `trellis update` now ship platform-agnostic `.trellis/agents/{check,implement}.md` on every install, so `trellis channel spawn --agent check` works out of the box. `trellis workflow --template <id>` prints a non-blocking stderr warning when the resolved workflow references missing `.trellis/agents/<name>.md` files (detection via `utils/agent-refs.ts`). Closes `#323`.
## Memory (`trellis mem`)
A local CLI that indexes Claude Code and Codex conversation logs already on disk and exposes them through `list`, `search`, `context`, `extract`, and `projects` subcommands. Nothing is uploaded. (84 unit tests, 81.89% coverage on first ship.)
### Phase slicing
`mem extract <id> --phase brainstorm` slices between `task.py create` and `task.py start`; `--phase implement` is the inverse; `--phase all` is the default. Multi-task sessions are separated by `--- task: <slug> ---`. The `--phase` parser handles `$(... --slug NAME)` substitution, multiple `task.py` invocations per Bash command, and `task.py start` inside commit-message heredocs.
### Cross-day session window correctness
`--since` now filters by `inRangeOverlap(start, end, filter)` — sessions match if `[created, updated]` overlaps `[since, until]`. The previous "session created in range" filter dropped 29MB Claude sessions that started on day N–1 and were still being written on day N, even when they contained 19 matching turns written that day.
### Reusable retrieval primitives
`@mindfoldhq/trellis-core/mem` exports `listMemSessions`, `searchMemSessions`, `readMemContext`, `extractMemDialogue`, `listMemProjects`, with per-platform adapters under `packages/core/src/mem/adapters/`. The CLI is a thin wrapper.
## Platform coverage
v0.6.0 supports 15 AI coding tools: Claude Code, Codex, Cursor, OpenCode, Gemini, Kiro, Qoder, CodeBuddy, Droid, Pi, GitHub Copilot, Windsurf, Kilo Code, Factory, and the new Reasonix.
* **Reasonix (DeepSeek-Reasonix), new** — 15th supported platform via `trellis init --reasonix`. Skills under `.reasonix/skills/<name>/SKILL.md`; sub-agent skills carry `runAs: subagent`. Closes `#301`.
* **Pi Agent — native `trellis_subagent` extension matured** — `single` / `parallel` / `chain` dispatch modes, native progress cards (`Alt+O` for detail view), throttled live updates, Trellis-agent validation. Closes `#286`, `#290`.
* **Codex — inline mode default** — `codex.dispatch_mode: inline` lets the main Codex agent edit code directly (sub-agents can't inherit task context under `fork_turns="none"`). Opt back into `sub-agent` via `.trellis/config.yaml`.
* **OpenCode — shell-dialect `TRELLIS_CONTEXT_ID`** — hook command now emits a shell-aware export so `$TRELLIS_CONTEXT_ID` resolves correctly across POSIX shells and OpenCode 1.2+ runners.
* **Cursor — sessionStart `additional_context`** — hook payload now uses the documented `additional_context` field, restoring task-context injection on session resume.
* **GitHub Copilot — hook payload corrected** — Copilot-specific hook envelope schema fixed so context injection lands on the Copilot side without truncation.
## SDK extraction (`@mindfoldhq/trellis-core`)
A second published package, `@mindfoldhq/trellis-core`, exposes `/channel`, `/task`, `/testing` subpath exports. The CLI now depends on it; both packages share one git tag, one npm dist-tag, and one version per release. `.github/workflows/publish.yml` publishes `@mindfoldhq/trellis-core` before `@mindfoldhq/trellis`, and post-publish `verify-npm --package all` confirms both on the public npm registry.
### Exported APIs
| Module | Surface |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@mindfoldhq/trellis-core/channel` | `listWorkers`, `watchWorkers`, `spawnWorker`, `requestInterrupt`, `interruptWorker`, `readChannelEvents`, `watchChannels`, `readWorkerInbox`, `watchWorkerInbox`, `WorkerInboxError`, `matchesInboxPolicy` |
| `@mindfoldhq/trellis-core/mem` | `listMemSessions`, `searchMemSessions`, `readMemContext`, `extractMemDialogue`, `listMemProjects` |
| `@mindfoldhq/trellis-core/task` | task lifecycle primitives |
| `@mindfoldhq/trellis-core/testing` | test helpers shared with the CLI |
## Workflow + planning
### Task triage consent gates
No-task turns now classify the request. Simple/small requests ask only whether to create a Trellis task; if not, Trellis is skipped for the turn. Complex requests ask permission to create a task and enter planning; if declined, scope is clarified or a smaller split suggested.
### Planning artifacts (`prd.md` / `design.md` / `implement.md`)
`task.py create` creates a default `prd.md`. Complex planning uses `prd.md` (requirements, constraints, acceptance criteria, out-of-scope), `design.md` (boundaries, data flow, contracts, tradeoffs), and `implement.md` (checklist, validation commands, review gates) before `task.py start`. Implement/check context loading order is consistent across hook-push, pull-prelude, Pi extension, OpenCode plugin, and inline modes: `jsonl entries → prd.md → design.md → implement.md`.
### Workflow templates (selectable + switchable)
`trellis init --workflow / --workflow-source` and `trellis workflow` switch between built-in flavors `native`, `tdd`, `channel-driven-subagent-dispatch`, plus marketplace templates via `workflow-resolver.ts`. The active file remains `.trellis/workflow.md`.
### Parent / child task trees
`.trellis/workflow.md` and `get_context.py --mode phase --step 1.1` document parent/child task tree usage. Breadcrumbs `[workflow-state:planning]` and `[workflow-state:planning-inline]` updated. The `trellis-brainstorm` and `trellis-meta` skills cover the pattern.
### Check agents read artifacts first
Check agents now require `prd.md` and optionally read `design.md` / `implement.md` before checking code. Applied to Claude Code, Cursor, OpenCode, Gemini, Kiro, Qoder, CodeBuddy, Droid, and Pi.
### Workflow-state tool routing — agents vs skills
`trellis-implement` and `trellis-research` are declared as sub-agent types only; `trellis-update-spec` is a skill; `trellis-check` exists as both (verification after code changes prefers the Agent form).
## Updater
### `trellis upgrade` command
Wraps `npm install -g @mindfoldhq/trellis@<channel>` with channel-aware defaults (`latest`, `beta`, `rc`). Flags: `--tag <tag>` for explicit dist-tag/version, `--dry-run` to preview. Validates input, avoids shell interpolation on POSIX, uses `cmd.exe /d /s /c` on Windows, prints npm/PATH troubleshooting on failure. Session-start hints now point at `trellis upgrade`.
### Registry-backed `.trellis/spec` refresh
`trellis init --template <id>` persists the spec source and template id into `.trellis/config.yaml` under a new `registry.spec` block. `trellis update` reads that block, downloads the configured spec registry into a temp dir, and feeds it through the existing hash / conflict / "modified by you" flow. Supports direct spec registries and marketplace-style registries, including SSH and self-hosted Git. New utility: `utils/registry-config.ts`. Closes `#315`.
### Configurable hooks via `.trellis/config.yaml`
| Knob | Controls |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `session_commit_message` / `max_journal_lines` / `session_auto_commit` | journal auto-commit shape |
| `hooks.after_create` / `after_start` / `after_finish` / `after_archive` | user shell commands run after each task lifecycle event |
| `channel.worker_guard.idle_timeout` / `max_live_workers` | channel worker OOM protection |
| `codex.dispatch_mode: inline \| sub-agent` | whether the main Codex agent edits code directly or routes through `trellis-implement` / `trellis-check` sub-agents |
Existing projects receive commented-out blocks via `configSectionsAdded` on `trellis update`.
### Updater hardening
`initializeHashes()` tracks platform/root files from `startRecordingWrites()` output instead of walking `.codex/` / `.claude/`. `pruneOrphanManifestKeys()` removes stale orphans before `update` and `uninstall`. `trellis init` / `uninstall` refuse to run in `$HOME` unless `TRELLIS_ALLOW_HOMEDIR=1`. `trellis update` refreshes hash-tracked `.trellis/workflow.md` as a whole template (fixes upgraded Codex installs with stale `[Codex]` blocks). Hook templates force UTF-8 on Windows (`python -X utf8` + stdio reconfigure with replacement errors).
## Bundled skills
### `trellis-channel`
New bundled capability skill that teaches the AI when to reach for `trellis channel` — multi-agent collaboration, spawned workers, cross-agent review, progress inspection, forum/thread boards, and channel log debugging. SKILL.md plus five reference files (workflows, forum, workers, progress-debugging, command-reference). Auto-dispatched on every supported platform via `getBundledSkillTemplates()` directory scan.
### `trellis-meta`
Rewritten for v0.6 architecture. SKILL.md preamble now covers the channel runtime, `trellis mem`, and dual-package SDK; description triggers cover bundled-skill auto-dispatch. New `references/local-architecture/multi-agent-channel.md` and `references/local-architecture/bundled-skills.md` explain channel-vs-other primitives, where state lives, `.trellis/config.yaml channel.*` knobs, and bundled vs project-local ownership / override convention. `platform-files/platform-map.md` adds the Reasonix row (15th platform) and Pi native `trellis_subagent` annotation; `customize-local/change-skills-or-commands.md` expands the platform path table from 6 to 13 platforms and documents anti-collision rules for all four bundled skills.
### `trellis-spec-bootstrap`
Platform-neutral bundled skill at `templates/common/bundled-skills/trellis-spec-bootstrap/` provides source-backed references for repository analysis, spec task planning, spec writing, and MCP setup. Auto-installed across all platforms on `trellis init` / `trellis update`, replacing the older `cc-codex-spec-bootstrap` marketplace entry. The beta.23 `rename-dir` migration renames already-installed typoed directories across `.claude/skills/`, `.cursor/skills/`, `.opencode/skills/`, `.agents/skills/`, `.kiro/skills/`, `.qoder/skills/`, `.codebuddy/skills/`, `.github/skills/`, `.factory/skills/`, `.pi/skills/`, `.agent/skills/`, `.windsurf/skills/`, `.kilocode/skills/`. Closes `#296`.
### `trellis-session-insight`
A capability skill that teaches the AI when to reach for `trellis mem` (past-solution recall, decision retrieval, cross-session continuation, familiar-bug debugging, self-pattern spotting, finish-work retrospective) with verbatim English + Chinese triggering phrases. Intentionally does not prescribe a fixed write-back file — what to do with what `mem` returns is judged in the moment based on the live conversation. Auto-dispatched to every supported platform.
## Bug Fixes
### `trellis-implement` / `trellis-check` no longer silent-skip when Exa MCP is absent
The bundled `trellis-implement` and `trellis-check` agent definitions declared `mcp__exa__web_search_exa` and `mcp__exa__get_code_context_exa` as explicit tools. Claude Code's `tools:` parser silently skips agent registration when an explicit MCP tool name fails to resolve, so users without Exa MCP installed had every Trellis sub-agent disappear from the dispatch list — the main agent ended up implementing work itself rather than delegating.
Fix:
* `trellis-implement` and `trellis-check` drop both `mcp__exa__*` entries. These agents do not need external web search; the tools list shrinks to `Read, Write, Edit, Bash, Glob, Grep`.
* `trellis-research` folds the previous `mcp__exa__*` + `mcp__chrome-devtools__*` entries into a single `mcp__*` wildcard. Claude Code resolves wildcards lazily (no silent-skip when nothing matches), so this opts research into any MCP the user has configured without locking the source template to a specific provider.
* The Copilot transformer (`mapLegacyToolToCopilot` in `packages/cli/src/configurators/shared.ts`) gets a matching case for `mcp__*` that emits the full set of supported Copilot MCP equivalents.
OpenCode agent files use a different permission mapping syntax (`mcp__exa__*: allow`) that does not silent-skip, so they are intentionally left unchanged. Closes `#302`.
## Breaking changes & upgrade
The breaking-change gate fires at `0.6.0-beta.0` — that manifest carries the rename + delete migration chain. The `0.6.0` manifest itself has `breaking: false` and no migrations (rc.0 → GA is zero source change), but users coming from any `0.5.x` will traverse `0.6.0-beta.0.json` during the manifest chain walk, which IS breaking. Pass `--migrate` so the chain is honored.
## RC stabilization
v0.6.0 GA = `0.6.0-rc.0` with zero `src/` changes; no rc.1 cut was needed. The breaking work happened at `0.6.0-beta.0` and the migration chain was absorbed throughout the beta line.
## Upgrade
From 0.5.x:
```bash theme={null}
trellis update --migrate
```
The `--migrate` flag is REQUIRED — the breaking-change gate from `0.6.0-beta.0` fires when traversing the migration chain. Local customizations are preserved with a warning. Per-prompt `reason` field explains version-specific nuances inline.
<Warning>
Users running `update --migrate` from a 0.5.x install will also see a `rename-dir` migration that fixes the bundled skill directory name from `trellis-spec-bootstarp/` → `trellis-spec-bootstrap/` across every configured platform skill root. This is automatic and idempotent; missing roots silently skip.
</Warning>
From any 0.6.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
```
# v0.6.0-beta.1
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.1
2026-05-08
Beta patch shipping the same Codex dispatch fix as `0.5.9`.
## Bug Fixes
* **Codex `dispatch_mode` default flipped from `sub-agent` to `inline`.** Codex sub-agents run with `fork_turns="none"` isolation, so they can't inherit the parent session's task context — they either exit silently or recursively dispatch. Inline mode keeps the main Codex agent in charge so context isn't lost. To opt back into the legacy dispatch flow, uncomment `codex.dispatch_mode: sub-agent` in `.trellis/config.yaml`. Invalid values fall back to inline.
* **`--platform codex` now namespaces into `codex-inline` / `codex-sub-agent` virtual platforms.** `workflow.md` `[Platform A, B, ...]` blocks render different guidance per mode (inline mode tells the main agent to edit code; sub-agent mode tells it to dispatch `trellis-implement` / `trellis-check`). `inject-workflow-state.py` emits a `<codex-mode>` banner in the per-turn UserPromptSubmit prompt so Codex knows which mode it is in. `[workflow-state:STATUS-inline]` blocks drive the breadcrumb path for inline mode.
## Other Platforms
Claude Code, Cursor, OpenCode, Kiro, CodeBuddy, Droid, Gemini, Qoder, Copilot — unchanged.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-beta.10
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.10
2026-05-12
Adds `trellis channel`, a CLI runtime for coordinating worker agents through a shared event log.
## Enhancements
### Trellis Channel
`trellis channel` manages collaboration sessions, messages, worker processes, waits, cleanup, and one-shot runs.
| Command | Behavior |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `trellis channel create <name>` | Creates a channel session. |
| `trellis channel send <name>` | Writes a message event. |
| `trellis channel wait <name>` | Blocks until matching events arrive. |
| `trellis channel spawn <name>` | Starts a Claude or Codex worker. |
| `trellis channel run [name]` | Creates an ephemeral channel, runs one worker, prints the final answer, and cleans up. |
| `trellis channel list` / `messages` / `kill` / `rm` / `prune` | Inspect, terminate, remove, and clean channel state. |
### Channel adapters
Claude and Codex worker output is normalized into channel events.
| Adapter | Source protocol | Event output |
| ------------------------------------------------------ | --------------------------- | -------------------------------------- |
| `packages/cli/src/commands/channel/adapters/claude.ts` | Claude `stream-json` | `message`, `progress`, `done`, `error` |
| `packages/cli/src/commands/channel/adapters/codex.ts` | Codex `app-server` JSON-RPC | `message`, `progress`, `done`, `error` |
### Channel store
Channel events are written to project-scoped JSONL logs with locked sequence assignment.
| Path | Purpose |
| ------------------------------------------------------ | ------------------------------------------------------- |
| `~/.trellis/channels/<project>/<channel>/events.jsonl` | Channel event stream. |
| `packages/cli/src/commands/channel/store/events.ts` | Append-only event writes and `seq` assignment. |
| `packages/cli/src/commands/channel/store/paths.ts` | Project bucket selection and legacy channel relocation. |
## Internal
### Channel supervisor modules
Channel runtime internals are split into adapter parsing, event storage, inbox polling, stdout pumping, and shutdown control under `packages/cli/src/commands/channel/`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-beta.11
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.11
2026-05-13
## Bug Fixes
### Task archive auto-commit
`task.py archive` now stages only archive-related task paths.
* `safe_archive_paths_to_add()` scopes staging to the archived task source path, archive destination path, and child task dirs whose `task.json` was edited during parent cleanup.
* `_auto_commit_archive()` stages source-side deletes with `git rm -r --cached --ignore-unmatch` after moving a tracked task dir to `.trellis/tasks/archive/<YYYY-MM>/`.
### Template manifest ownership
`trellis init`, `trellis update`, and `trellis uninstall` no longer treat user-owned platform runtime files as Trellis templates.
* `initializeHashes()` tracks platform/root files from `startRecordingWrites()` output instead of walking `.codex/`, `.claude/`, and other platform dirs.
* `pruneOrphanManifestKeys()` removes stale orphan entries from `.trellis/.template-hashes.json` before `update` and `uninstall`.
* `trellis init` and `trellis uninstall` refuse to run in `$HOME` unless `TRELLIS_ALLOW_HOMEDIR=1`.
### Windows hook encoding
Hook templates force UTF-8 on Windows for stdin, stdout, and stderr.
* `hooks.json` runs Codex `inject-workflow-state.py` with `python -X utf8`.
* `shared-hooks/inject-workflow-state.py`, `shared-hooks/session-start.py`, `codex/hooks/session-start.py`, and `copilot/hooks/session-start.py` reconfigure streams to UTF-8 with replacement errors.
## Internal
### Manifest continuity
The beta branch includes the stable patch manifests needed by `trellis update`.
* `packages/cli/src/migrations/manifests/0.5.14.json`
* `packages/cli/src/migrations/manifests/0.5.15.json`
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-beta.12
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.12
2026-05-13
## Enhancements
### Channel thread boards
`trellis channel` now supports durable thread channels for issue-style feedback boards.
* `trellis channel create --type thread`
* `trellis channel post <name> opened|comment|status|labels|assignees|summary|processed`
* `trellis channel threads <name>`
* `trellis channel thread <name> <thread>`
* `trellis channel messages <name> --thread <key> --action <action>`
### Channel scope
Channel commands can now target project or global storage explicitly.
* `--scope project`
* `--scope global`
* Applies to `create`, `send`, `wait`, `spawn`, `messages`, `list`, `kill`, `rm`, and `prune`.
### Linked context
Channel and thread events can carry stable context for future agents.
* `--description <text>`
* `--linked-context-file <absolute-path>`
* `--linked-context-raw <text>`
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-beta.13
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.13
2026-05-14
## Enhancements
### trellis-core SDK
`@mindfoldhq/trellis-core` now publishes the channel and task primitives used by the CLI.
* Package: `@mindfoldhq/trellis-core`
* Exports: `@mindfoldhq/trellis-core/channel`, `@mindfoldhq/trellis-core/task`, `@mindfoldhq/trellis-core/testing`
* CLI dependency: `@mindfoldhq/trellis-core`
### Channel thread commands
Thread channels now use the `threads` structural type and expose context, title, and rename commands.
* `trellis channel create --type threads`
* `trellis channel context add|delete|list`
* `trellis channel title set|clear`
* `trellis channel thread rename`
### Channel context flags
Context input now uses `context` naming while the beta.12 linked-context aliases remain accepted.
* `--context-file <absolute-path>`
* `--context-raw <text>`
* Legacy aliases: `--linked-context-file`, `--linked-context-raw`
## Internal
### Core package publishing
The publish workflow now publishes `@mindfoldhq/trellis-core` before `@mindfoldhq/trellis` with one shared version and npm dist-tag.
* Workflow: `.github/workflows/publish.yml`
* Preflight: `packages/cli/scripts/release-preflight.js`
* Version bump: `packages/cli/scripts/bump-versions.js`
* Release runner: `packages/cli/scripts/release.js`
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
Replace beta.12 scripts that use `trellis channel create --type thread` with `trellis channel create --type threads`.
# v0.6.0-beta.14
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.14
2026-05-14
## Bug Fixes
### Codex channel streamed deltas
Codex channel progress events now include stream metadata for `item/agentMessage/delta`.
* Parser: `packages/cli/src/commands/channel/adapters/codex.ts`
* Fields: `detail.kind`, `detail.stream_id`, `detail.phase`, `detail.text_delta`
* Kinds: `output`, `commentary`, `reasoning`
Consumers should group streamed deltas by `detail.stream_id` and keep `kind:"message"` as the canonical completed assistant answer.
## Internal
### npm publish verification
The publish workflow now verifies both packages on the public npm registry after CI publish.
* Workflow: `.github/workflows/publish.yml`
* Preflight: `packages/cli/scripts/release-preflight.js verify-npm --package all`
* Packages: `@mindfoldhq/trellis`, `@mindfoldhq/trellis-core`
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No file migration is required.
# v0.6.0-beta.15
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.15
2026-05-14
## Enhancements
### Core mem API
`tl mem` retrieval logic is now available from `@mindfoldhq/trellis-core/mem`.
* Package: `@mindfoldhq/trellis-core/mem`
* APIs: `listMemSessions`, `searchMemSessions`, `readMemContext`, `extractMemDialogue`, `listMemProjects`
* Adapters: `packages/core/src/mem/adapters/claude.ts`, `packages/core/src/mem/adapters/codex.ts`, `packages/core/src/mem/adapters/opencode.ts`
* CLI wrapper: `packages/cli/src/commands/mem.ts`
### Forum channel commands
Forum channels now expose thread-style discussion commands and context entries.
* Create: `trellis channel create <name> --type forum`
* Threads: `trellis channel post`, `trellis channel forum`, `trellis channel thread`
* Context: `trellis channel context add`, `trellis channel context delete`, `trellis channel context list`
* Reducers: `reduceThreads`, `reduceChannelMetadata`
### Channel worker runtime APIs
Channel worker lifecycle and subscription primitives are now exported from `@mindfoldhq/trellis-core/channel`.
* Workers: `listWorkers`, `watchWorkers`, `probeWorkerRuntime`, `reconcileWorkerLiveness`
* Runtime: `spawnWorker`, `requestInterrupt`, `interruptWorker`
* Streams: `readChannelEvents({ afterSeq, beforeSeq, limit })`, `watchChannels`
* CLI flags: `trellis channel spawn --inbox-policy`, `trellis channel send --delivery-mode`
## Bug Fixes
### Codex channel turns
Codex channel workers now record completed answers before `done` and serialize non-interrupt turns.
* Parser: `packages/cli/src/commands/channel/adapters/codex.ts`
* Supervisor: `packages/cli/src/commands/channel/supervisor/inbox.ts`
* Events: `turn_started`, `turn_finished`, `interrupt_requested`, `interrupted`
* Behavior: normal messages wait for the active turn; `--tag interrupt` aborts the active turn and starts the new one.
### Worker registry projection
Worker state now separates turn completion from worker termination.
* Reducer: `packages/core/src/channel/internal/store/worker-state.ts`
* Turn-level events: `done`, `error`
* Terminal events: `killed`, synthesized exit events, supervisor errors
* Watch fallback: `packages/core/src/channel/internal/store/watch.ts`, `packages/cli/src/commands/channel/store/watch.ts`
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No file migration is required.
# v0.6.0-beta.16
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.16
2026-05-15
## Enhancements
### Parent / child task trees
Workflow guidance now documents when to use parent tasks and independently verifiable child tasks.
* Workflow: `.trellis/workflow.md`
* Step detail: `get_context.py --mode phase --step 1.1`
* Breadcrumbs: `[workflow-state:planning]`, `[workflow-state:planning-inline]`
* Skills: `trellis-brainstorm`, `trellis-meta`
## Bug Fixes
### Trellis check agents
Check agents now review task artifacts before checking code against specs.
* Required artifact: `prd.md`
* Optional artifacts: `design.md`, `implement.md`
* Platforms: Claude Code, Cursor, OpenCode, Gemini, Kiro, Qoder, CodeBuddy, Droid, Pi
* Pi agents: `trellis-implement.md`, `trellis-check.md`
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No file migration is required.
# v0.6.0-beta.17
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.17
2026-05-15
## Enhancements
### Workflow templates
Workflow templates can now be selected during `trellis init` or switched later with `trellis workflow`.
* Init flags: `--workflow`, `--workflow-source`
* Command: `trellis workflow`
* Built-in templates: `native`, `tdd`, `channel-driven-subagent-dispatch`
* Marketplace resolver: `workflow-resolver.ts`
* Active file: `.trellis/workflow.md`
### Channel worker coordination
Channel workers now expose timeout warning controls and multi-kind wait filters.
* Wait filter: `trellis channel wait --kind done,killed`
* Warning event: `supervisor_warning`
* Spawn flag: `trellis channel spawn --warn-before <duration>`
* Disable warning: `--warn-before 0ms`
* Default warning lead time: `5m`
### Worker inbox core API
`@mindfoldhq/trellis-core/channel` now exports durable worker inbox read and watch APIs.
* Read API: `readWorkerInbox()`
* Watch API: `watchWorkerInbox()`
* Error class: `WorkerInboxError`
* Routing SOT: `matchesInboxPolicy()`
* Generation boundary: same-id respawns do not replay old worker messages
## Bug Fixes
### Cursor sessionStart hook
Cursor `sessionStart` output now matches Cursor's top-level context schema.
* Output field: `additional_context`
* Shared format retained: `hookSpecificOutput.additionalContext`
* Removed unsupported Cursor hook: `beforeSubmitPrompt`
* Removed copied Cursor file: `.cursor/hooks/inject-workflow-state.py`
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No file migration is required.
# v0.6.0-beta.18
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.18
2026-05-17
## Enhancements
### Channel worker OOM guard
`trellis channel spawn` now has default safeguards for resident worker processes.
* Idle cleanup: `channel.worker_guard.idle_timeout`, default `5m`
* Live-worker budget: `channel.worker_guard.max_live_workers`, default `6`
* Spawn flags: `--idle-timeout <duration>`, `--max-live-workers <n>`
* Env overrides: `TRELLIS_CHANNEL_WORKER_IDLE_TIMEOUT`, `TRELLIS_CHANNEL_MAX_LIVE_WORKERS`
* Idle terminal event: `killed` with `reason: "idle-timeout"`
* Core projection: `WorkerState.idleSince`
Mid-turn workers are not killed by idle cleanup. Explicit `--timeout` remains opt-in.
### Channel message routing
Channel worker routing no longer uses message tags in send, wait, run, and provider adapter internals.
* Removed send tag plumbing from `send.ts`
* Removed wait tag filtering from `wait.ts`
* Kept routing on channel events, worker inbox policy, and explicit `to`
* Added interrupt-specific adapter encoding in `interrupt.ts` and supervisor inbox flow
### Trellis spec bootstrap skill
The Trellis beta bundle now includes `trellis-spec-bootstarp`, a platform-neutral skill for bootstrapping `.trellis/spec/` from the real codebase.
* Replaces the older `cc-codex-spec-bootstrap` marketplace entry
* Works after `trellis init` when the default spec templates still need project-specific content
* Installed automatically with Trellis; no extra marketplace download is needed
* Documented in both beta and release docs so the workflow stays visible when the release bundle is updated
## Bug Fixes
### Task archive auto-commit
`task.py archive` now fails when its auto-commit fails instead of reporting a successful archive with dirty task files.
* Template file: `scripts/common/task_store.py`
* Covered path: archive move followed by failed `git commit`
* User-visible behavior: archive failure exits non-zero and leaves the problem visible
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
`trellis update` appends `channel.worker_guard` defaults to existing `.trellis/config.yaml` files. No migration command is required.
# v0.6.0-beta.19
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.19
2026-05-19
## Enhancements
### Pi trellis\_subagent extension
The Pi extension now exposes Trellis sub-agent dispatch through `trellis_subagent` with native progress cards.
* Tool name: `trellis_subagent`, avoiding collisions with community `subagent` packages
* Dispatch modes: `single`, `parallel`, and `chain`
* Live UI: native progress card updates through `renderResult`, throttled by `THROTTLE_MS`
* Detail view: `Alt+O` expands and collapses the latest sub-agent card
* Safety: `isTrellisAgent()` rejects non-Trellis agent names before spawning child Pi processes
* Resource control: bounded stdout/stderr buffers prevent unbounded child-output growth
## Bug Fixes
### Channel durable idempotency
`@mindfoldhq/trellis-core` channel writes now support durable idempotency keys on `sendMessage` and `postThread`.
* New option: `idempotencyKey`
* Replay behavior: repeated writes with the same key return the original JSONL event
* Strict delivery: replays do not duplicate `undeliverable` events
* Validation: empty keys are rejected, and reusing a key across event kinds raises an error
### Archived task create collisions
`task.py create` now rejects a slug that already exists in `.trellis/tasks/archive/**`.
* Checks archived task directories before creating a new active task directory
* Prints the archived path that caused the collision
* Tells the user to choose a new slug for an intentional new task
### Workflow-state tool routing
`[workflow-state:in_progress]` now distinguishes sub-agent types from skills.
* `trellis-implement` and `trellis-research` are sub-agent types only
* `trellis-update-spec` is a skill
* `trellis-check` exists as both; verification after code changes should prefer the Agent form
* Prevents agents from trying to call missing `trellis-implement` / `trellis-research` skills
### Codex multi\_agent\_v2 timeout bounds
`.codex/config.toml` now emits the `multi_agent_v2` wait timeout values as a valid bounds set for Codex CLI 0.131+.
**Codex requirement:** this full timeout-bounds config requires Codex CLI `0.131.0` or newer. Codex CLI `0.128.0` through `0.130.x` only understands the earlier `enabled`, `max_concurrent_threads_per_session`, and `min_wait_timeout_ms` fields; those versions fail config loading when `default_wait_timeout_ms` or `max_wait_timeout_ms` is present.
```toml theme={null}
[features.multi_agent_v2]
enabled = true
max_concurrent_threads_per_session = 6
min_wait_timeout_ms = 480000
default_wait_timeout_ms = 480000
max_wait_timeout_ms = 3600000
```
* Fixes Codex startup failure: `default_wait_timeout_ms must be at least min_wait_timeout_ms`
* Requires Codex CLI `0.131.0+` for `default_wait_timeout_ms` and `max_wait_timeout_ms`
* Keeps the Trellis default wait at 8 minutes
* Keeps the explicit upper clamp at 1 hour
* Covers fresh `trellis init` and template refresh through `trellis update`
## Internal
### Release manifest continuity
The source tree now includes the already-shipped `0.5.17` migration manifest.
* Restores `packages/cli/src/migrations/manifests/0.5.17.json`
* Keeps `check-manifest-continuity.js` green for the beta release
* Preserves adjacent-version `trellis update` chain validation
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No migration command is required.
# v0.6.0-beta.2
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.2
2026-05-08
## Bug Fixes
* **`tl mem list / search --since X` now respects cross-day session activity.** Previously a session whose first event fell before the window was dropped from results even if it stayed active inside it. A 29 MB Claude session that started 5/7 and was still being written 5/8 returned 0 matches under `--since 2026-05-08` despite containing 19 occurrences of the searched keyword written that day. Root cause: `claudeListSessions` and `codexListSessions` filtered by `created` only (single-point `inRange`). New helper `inRangeOverlap(start, end, f)` keeps a session iff its `[created, updated]` interval overlaps `[f.since, f.until]`. Three list sites switched over; the early `tsFromName` short-circuit in codex was a misoptimization that re-introduced the cross-day bug and is removed. 23 new tests cover all five interval relations × three platforms.
## Internal
* Spec drift cleanup (`.trellis/spec/*`): `script-conventions.md` drops removed `task_context.py init-context`; `workflow-state-contract.md` writer-table line numbers refreshed against current code; `directory-structure.md` configurators / utils / commands trees aligned. `docs-site/advanced/architecture.mdx` corrected the false `.trellis/.current-task` fallback claim (EN + ZH). User-facing artifact unchanged.
## Other Platforms
Claude Code, Cursor, OpenCode, Kiro, CodeBuddy, Droid, Gemini, Qoder, Copilot, Codex — unchanged.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
## Known Trade-Off
Removing the codex filename-ts short-circuit means every codex session now does `readJsonlFirst`. Acceptable; a future patch may add a safe one-sided `--until`-only fast prune that does not reintroduce the cross-day bug.
# v0.6.0-beta.20
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.20
2026-05-19
## Bug Fixes
### Trellis spec bootstrap skill
`trellis-spec-bootstarp` is now included in the CLI package templates.
* Template source: `packages/cli/src/templates/common/bundled-skills/trellis-spec-bootstarp/`
* Packed path: `dist/templates/common/bundled-skills/trellis-spec-bootstarp/`
* Install path: platform skill roots such as `.claude/skills/`, `.agents/skills/`, `.pi/skills/`
* Update tracking: `.trellis/.template-hashes.json` includes the bundled skill reference files
Fresh `trellis init` and `trellis update` now install the built-in spec bootstrap skill without a separate marketplace download.
### Codex multi\_agent\_v2 version note
The v0.6.0-beta.19 changelog now states the Codex CLI version requirement for the full timeout-bounds config.
* Required Codex CLI version: `0.131.0+`
* Affected fields: `default_wait_timeout_ms`, `max_wait_timeout_ms`
* Older Codex CLI versions `0.128.0` through `0.130.x` only support the earlier `enabled`, `max_concurrent_threads_per_session`, and `min_wait_timeout_ms` fields
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No migration command is required.
# v0.6.0-beta.21
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.21
2026-05-21
## Bug Fixes
### Codex config.toml multi\_agent\_v2 block removed
`trellis init` / `trellis update` no longer write a `[features.multi_agent_v2]` block to the generated `.codex/config.toml`.
* Template source: `packages/cli/src/templates/codex/config.toml`
* Removed fields: `enabled`, `max_concurrent_threads_per_session`, `min_wait_timeout_ms`, `default_wait_timeout_ms`, `max_wait_timeout_ms`
Codex CLI changed `features` deserialization between `0.130` and `0.131`. The structured table form is only accepted by `0.131+`. On `0.130` and earlier — including the Codex CLI bundled in the Codex desktop app — it fails with `data did not match any variant of untagged enum FeatureToml in features.multi_agent_v2` and aborts the entire config load, blocking Codex from starting. Codex's own default for `multi_agent_v2` is used instead; tune it in your user-level `~/.codex/config.toml` if needed.
Run `trellis update` to regenerate `.codex/config.toml` without the block.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No migration command is required.
# v0.6.0-beta.22
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.22
2026-06-01
## Bug Fixes
### Codex sub-agent toml: duplicated pull-based prelude removed
The generated `.codex/agents/trellis-check.toml` and `trellis-implement.toml` contained the "Required: Load Trellis Context First" prelude **twice**.
* Template source: `packages/cli/src/templates/codex/agents/trellis-check.toml`, `trellis-implement.toml`
* Generated output: `.codex/agents/trellis-check.toml`, `trellis-implement.toml`
Class-2 platforms (Codex / Copilot / Gemini / Qoder) cannot inject sub-agent task context via hook, so the context-loading prelude is added by the configurator (`injectPullBasedPreludeToml`). The two Codex toml source templates still carried an inline copy of that prelude that predated the injector. The injector then prepended a second copy, so each generated agent shipped the block twice. The markdown class-2 templates (gemini / cursor / etc.) were already prelude-free and unaffected.
The inline copies are removed so the injector is the single source. A regression test now asserts the prelude appears exactly once across all class-2 platforms.
Run `trellis update` to regenerate `.codex/agents/` without the duplication.
### Restore 0.5.19 migration manifest on the beta branch
`src/migrations/manifests/0.5.19.json` was missing on the `0.6.0-beta` branch.
* Restored from `main`, byte-identical to the manifest shipped with the published `0.5.19` release.
The published `0.5.19` npm release had no local manifest on this branch, which broke the manifest-continuity guard and would break `trellis update` for users on `0.5.19`. Restoring it keeps the upgrade chain intact.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No migration command is required.
# v0.6.0-beta.23
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.23
2026-06-08
## Enhancements
### Channel runtime agent definitions auto-dispatched
`trellis init` and `trellis update` now ship `.trellis/agents/{check,implement}.md`, the bundled definitions that `trellis channel spawn --agent <name>` loads at runtime.
* Templates: `packages/cli/src/templates/trellis/agents/{implement,check}.md`
* Dispatched by: `createWorkflowStructure` in `packages/cli/src/configurators/workflow.ts`
* Refreshed by: `getAllAgents()` in `packages/cli/src/templates/trellis/index.ts`, threaded through `collectTemplateFiles` in `packages/cli/src/commands/update.ts`
Previously, switching to a channel-driven workflow (`trellis workflow --template channel-driven-subagent-dispatch`) and then running `trellis channel spawn --agent check` failed at runtime with `Agent 'check' not found` because no command shipped these files. They are platform-agnostic and are dispatched on every init regardless of `--workflow` or `--<platform>` selection. The standard hash/conflict flow in `trellis update` backfills missing entries for projects that installed before the bundled definitions existed (#323).
### Registry-backed `.trellis/spec` refresh through `trellis update`
`trellis init --template <id>` now persists the spec source and template id into `.trellis/config.yaml` under a new `registry.spec` block. `trellis update` reads that block, downloads the configured spec registry into a temp directory, and feeds it through the existing hash / conflict / "modified by you" flow so registry-backed spec templates stay current alongside the standard CLI templates.
* New utility: `packages/cli/src/utils/registry-config.ts`
* `init.ts` and `update.ts` extended to write / read the persisted registry config
* Supports direct spec registries and marketplace-style registries, including SSH and self-hosted Git sources
Closes #315.
### Reasonix (DeepSeek-Reasonix) platform support
Adds Reasonix as the 15th supported AI coding tool, available via `trellis init --reasonix`. Reasonix stores skills as `.reasonix/skills/<name>/SKILL.md` with YAML frontmatter; slash commands are platform-built-in, so no separate `commands/` directory is generated.
* New configurator: `packages/cli/src/configurators/reasonix.ts`
* New template module: `packages/cli/src/templates/reasonix/`
* New CLI flag: `--reasonix`
* `{{CMD_REF:start}}` resolves to `/skill trellis-start` for Reasonix via the new `/skill trellis-` `cmdRefPrefix`
Subagent skills (`trellis-implement`, `trellis-check`) ship with `runAs: subagent` frontmatter so Reasonix spawns them as isolated subagent loops rather than inline slash skills. Closes #301.
### `trellis-session-insight` bundled skill
A new bundled skill at `packages/cli/src/templates/common/bundled-skills/trellis-session-insight/` teaches the AI when to reach for the `trellis mem` CLI (past-solution recall, decision retrieval, cross-session continuation, familiar-bug debugging, self-pattern spotting, finish-work retrospective) and intentionally does **not** prescribe a fixed write-back file.
What to do with what `mem` returns — quote inline in the answer, update a `prd.md` / `design.md`, append to task notes, internalize, or hand off to `trellis-update-spec` — is judged in the moment by the AI. References:
* `references/cli-quick-reference.md` — full `trellis mem` flag reference.
* `references/triggering-patterns.md` — verbatim English and Chinese user phrasings calibrated for each intent.
Auto-dispatched on every supported platform on `trellis init` and `trellis update` via the existing `getBundledSkillTemplates()` directory scan.
### Workflow template missing-agent warning
`trellis workflow --template <id>` (and `trellis init --workflow <id>`) now prints a non-blocking stderr warning when the resolved `workflow.md` references `.trellis/agents/<name>.md` files that are missing on disk. Detection lives in `packages/cli/src/utils/agent-refs.ts` and looks for both `--agent <name>` flag forms and literal `.trellis/agents/<name>.md` path references in the workflow body. The warning points the user at `trellis update` to backfill the bundled set and never aborts the workflow switch.
## Bug Fixes
### Bundled skill rename: `trellis-spec-bootstarp` → `trellis-spec-bootstrap`
The bundled spec-bootstrap skill shipped under a typoed directory name. The fix renames both the source template and the per-platform installed directories.
* Renamed source: `packages/cli/src/templates/common/bundled-skills/trellis-spec-bootstarp/` → `trellis-spec-bootstrap/`
* Inner `name:` frontmatter field corrected.
* Test references updated.
For users who already installed the typoed directory, this release ships a `rename-dir` migration in the 0.6.0-beta.23 manifest that renames the installed directory across 13 platform skill roots:
| Platform | Skill root |
| --------------------------- | -------------------- |
| Claude Code | `.claude/skills/` |
| Cursor | `.cursor/skills/` |
| OpenCode | `.opencode/skills/` |
| Codex + Gemini CLI (shared) | `.agents/skills/` |
| Kiro | `.kiro/skills/` |
| Qoder | `.qoder/skills/` |
| CodeBuddy | `.codebuddy/skills/` |
| GitHub Copilot | `.github/skills/` |
| Droid | `.factory/skills/` |
| Pi Agent | `.pi/skills/` |
| Antigravity | `.agent/skills/` |
| Windsurf | `.windsurf/skills/` |
| Kilo | `.kilocode/skills/` |
Run `trellis update --migrate` to apply. Missing roots are silently skipped.
Historical migration manifests `src/migrations/manifests/0.5.17.json` and `src/migrations/manifests/0.6.0-beta.18.json` keep the typoed text intentionally — they describe what actually shipped to users on those versions and stay grep-able for anyone investigating an old install. Closes #296.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update --migrate
```
`--migrate` is recommended for this release because of the `rename-dir` migrations above. Plain `trellis update` still installs the new `.trellis/agents/*.md` runtime files and the `trellis-session-insight` bundled skill, but leaves the existing `trellis-spec-bootstarp/` directories in place.
# v0.6.0-beta.3
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.3
2026-05-09
## Enhancements
* **`tl mem extract <id> --phase brainstorm`** — slice out the discussion portion of a session (between `task.py create` and `task.py start`). Multi-task sessions are separated with `--- task: <slug> ---`. `--phase implement` is the inverse; `--phase all` is the default full dump.
```bash theme={null}
tl mem extract <id> --phase brainstorm
tl mem extract <id> --phase brainstorm --json
tl mem extract <id> --phase implement
```
Supported on Claude and Codex. OpenCode falls back to full dialogue.
* **`tl mem` is 5-9× faster.**
| command | before | after |
| -------------------------------- | ------ | ----- |
| `mem list` | 3.5s | 0.67s |
| `mem list --platform codex` | 3.2s | 0.33s |
| `mem extract --phase brainstorm` | 5.8s | 0.73s |
## Bug Fixes
* **OpenCode 1.2+ users no longer see 0 sessions from `tl mem`.** OpenCode 1.2 moved session storage to SQLite; the old reader was looking at a now-empty JSON directory, so anyone on a recent OpenCode couldn't use `tl mem` at all. Fixed. OpenCode 1.1.x is no longer supported.
* **`--phase` parser handles `$(... --slug NAME)` substitution, multiple `task.py` invocations per Bash command, and `task.py start` quoted literally inside commit-message heredocs.**
## Other Platforms
Claude Code, Cursor, Kiro, CodeBuddy, Droid, Gemini, Qoder, Copilot — unchanged.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
## New dependency
Adds `better-sqlite3` for OpenCode. Standard `npm install` handles it via prebuilt binaries. If the native binding fails to load, `tl mem` still works on other platforms; OpenCode reads return empty with a one-time stderr hint.
# v0.6.0-beta.4
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.4
2026-05-09
## Bug Fixes
* **`better-sqlite3` dependency removed.** Reverts the OpenCode SQLite reader added in 0.6.0-beta.3. Fixes `npm install -g @mindfoldhq/trellis@beta` failure when the prebuilt binary download fails and no local C toolchain is available.
* **OpenCode platform degraded.** `tl mem list / search / extract` on platform `opencode` returns empty + a one-shot stderr warning. Claude and Codex paths unchanged.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-beta.5
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.5
2026-05-09
Brings the four `v0.5.10` stable fixes / features into the 0.6 beta line.
## Bug Fixes
* **`git add -f .trellis/` runaway prevented.** `add_session.py` and `task.py archive` now stage only specific Trellis-owned paths and auto-retry with `git add -f -- <specific-paths>` only on `ignored by` stderr. Warning text explicitly states `Do NOT use \`git add -f .trellis/\``, listing`.trellis/.backup-\*`,`.trellis/worktrees/`,`.trellis/.template-hashes.json`,`.trellis/.runtime/`,`.trellis/.cache/`as the paths to keep ignored. Helper centralized in`templates/trellis/scripts/common/safe\_commit.py\`.
* **Pi platform `<workflow-state>` / `<session-overview>` / subagent dispatch protocol injection.** Pi extension injects breadcrumb + session-overview every `input` / `before_agent_start`, and the `subagent` tool registration carries `promptSnippet` with `Active task: <path>`. Closes [#249](https://github.com/mindfold-ai/Trellis/issues/249).
* **Pi `npm:pi-subagents` project-level isolation.** `.pi/settings.json` overrides global `npm:pi-subagents` package with empty resource lists. `scrubPiSettings` reverses on uninstall. Closes [#246](https://github.com/mindfold-ai/Trellis/pull/246) (thanks @RenaLio).
## Enhancements
* **Session-start version-update hint.** `get_context.py` default mode performs a once-per-session `trellis --version` check and prepends `Trellis update available: <current> -> <latest>, run npm install -g @mindfoldhq/trellis@latest` when the local install lags. Best-effort with 1-second timeout; failures silently skip. Marker under `.trellis/.runtime/`. Closes [#254](https://github.com/mindfold-ai/Trellis/pull/254) (thanks @jdjingdian).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-beta.6
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.6
2026-05-10
Brings the `v0.5.11` stable fix into the 0.6 beta line.
## Bug Fixes
* **`add_session.py` / `task.py archive` no longer force-stage with `git add -f`.** When `.gitignore` excludes `.trellis/`, scripts print a warning and skip auto-commit. Reverts the auto-retry that shipped in 0.6.0-beta.5.
## Enhancements
* **New config: `session_auto_commit: true | false`** in `.trellis/config.yaml` (default `true`). Set `false` to skip auto stage + commit; journal / archive files still write to disk. Existing projects get a commented-out block appended on `trellis update` (via `configSectionsAdded`). Closes [#245](https://github.com/mindfold-ai/Trellis/issues/245).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-beta.7
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.7
2026-05-10
Brings the `v0.5.12` stable fix into the 0.6 beta line.
## Bug Fixes
* **`trellis update` now updates hash-tracked `.trellis/workflow.md` as a whole runtime template.** The updater no longer merges only `[workflow-state:*]` blocks, so phase headings and platform routing markers such as `codex-inline` / `codex-sub-agent` refresh together. This fixes upgraded Codex installs that had new hook scripts but stale `[Codex]` workflow blocks.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-beta.8
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.8
2026-05-10
Adds task-creation consent gates and planning artifacts to the 0.6 beta workflow.
## Enhancements
### Task Triage Consent
No-task turns now classify the request before creating any Trellis task.
| Request type | Behavior |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Simple conversation / small task | Ask only whether this turn should create a Trellis task; if not, skip Trellis for the turn. |
| Complex task | Ask whether Trellis may create a task and enter planning. If declined, clarify scope or suggest a smaller split. |
### Planning Artifacts
`task.py create` now creates a default `prd.md`; complex planning uses `prd.md`,
`design.md`, and `implement.md` before `task.py start`.
| Artifact | Purpose |
| -------------- | --------------------------------------------------------------------------- |
| `prd.md` | Requirements, constraints, acceptance criteria, out-of-scope. |
| `design.md` | Complex task technical design: boundaries, data flow, contracts, tradeoffs. |
| `implement.md` | Complex task execution plan: checklist, validation commands, review gates. |
### Context Loading
Implement/check context order is now consistent across hook-push, pull-prelude, Pi
extension, OpenCode plugin, and inline modes.
```text theme={null}
jsonl entries -> prd.md -> design.md if present -> implement.md if present
```
`implement.jsonl` and `check.jsonl` remain spec/research manifests; they do not
replace `implement.md`.
### Codex Inline Mode
Codex no-task breadcrumbs include `<trellis-bootstrap>` and `<codex-mode>`
context. Inline mode means the main Codex session implements and checks directly;
it does not dispatch implement/check sub-agents.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-beta.9
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.9
2026-05-12
Adds `trellis upgrade` and carries stable-line context fixes into the 0.6 beta track.
## Enhancements
### Trellis Upgrade
`trellis upgrade` installs the npm channel that matches the current CLI version.
| Command | Behavior |
| ----------------------------- | -------------------------------------------------------------------- |
| `trellis upgrade` | Installs `@mindfoldhq/trellis@latest`, `@beta`, or `@rc` by channel. |
| `trellis upgrade --tag <tag>` | Installs an explicit dist-tag or version. |
| `trellis upgrade --dry-run` | Prints the npm command without installing. |
Update hints now point at `trellis upgrade` instead of raw `npm install -g`
commands.
### Brainstorm Templates
Bundled brainstorm instructions are shorter and match the beta.8 planning
artifact flow.
| Template | Change |
| ----------------------------------------------------------------- | ------------------------------------------ |
| `packages/cli/src/templates/codex/skills/brainstorm/SKILL.md` | Uses the shorter brainstorm routing model. |
| `packages/cli/src/templates/common/skills/brainstorm.md` | Uses the same shared planning contract. |
| `packages/cli/src/templates/copilot/prompts/brainstorm.prompt.md` | Mirrors the shorter prompt text. |
## Bug Fixes
### Upgrade Execution
The upgrade command validates tag/version input, avoids shell interpolation on
POSIX, uses `cmd.exe /d /s /c` on Windows, and prints npm/PATH troubleshooting
when installation fails.
### OpenCode Context Prefix
OpenCode now picks the `TRELLIS_CONTEXT_ID` prefix for the shell dialect that
will parse the command.
| Environment | Prefix format |
| ---------------------------- | ------------------------------- |
| Windows PowerShell | `$env:TRELLIS_CONTEXT_ID = ...` |
| Windows Git Bash/MSYS/Cygwin | `export TRELLIS_CONTEXT_ID=...` |
| Existing `env` prefix | `env TRELLIS_CONTEXT_ID=...` |
### Session Context
Non-Git Trellis roots no longer report fake clean Git state. Session context now
states that the root is not a Git repository and scans bounded child repositories
for unconfigured polyrepo layouts.
### OpenCode Sub-Agent Context
Trellis implement/check/research child sessions skip duplicate workflow-state
injection and resolve the active task from session runtime, an `Active task:`
prompt hint, or a single-session fallback.
```text theme={null}
jsonl entries -> prd.md -> design.md if present -> implement.md if present
```
### Hook Timeouts And Copilot
Hook defaults now allow 30s for SessionStart and 15s for per-prompt workflow
injection across hook-based platforms. Copilot SessionStart output no longer
emits the stale `systemMessage`; it keeps `hookSpecificOutput.additionalContext`.
## Internal
### Manifest Continuity
The beta line restores `0.5.13.json` so future beta manifest checks include the
stable `0.5.13` release.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-rc.0
Source: https://docs.trytrellis.app/changelog/v0.6.0-rc.0
2026-06-08
The first release candidate for v0.6.0. The feature surface is now frozen; the v0.6.0 cycle moves from beta into stabilization. Feature requests open on the tracker (`#193`, `#318`, `#320`, `#325`, `#326`, etc.) are deferred to v0.7 or later. Bug-only patches will land as further `0.6.0-rc.*` cuts.
This changelog summarizes what the v0.6 line delivered across 23 beta releases plus the single fix made between `0.6.0-beta.23` and `0.6.0-rc.0`.
## Enhancements
### `trellis mem` — cross-session memory feedstock
A local CLI that indexes Claude Code and Codex conversation logs already on disk and exposes them through `list`, `search`, `context`, `extract`, and `projects` subcommands. `extract --phase brainstorm|implement|all` slices a session at `task.py create` / `task.py start` boundaries so an AI can recover the planning window of any prior task. Reusable retrieval and phase logic live in `@mindfoldhq/trellis-core/mem`; nothing is uploaded.
Shipped progressively from `v0.6.0-beta.15` (core + CLI), with adapters and phase slicing maturing through `beta.18`.
### `trellis-session-insight` bundled skill
A capability skill that teaches the AI when to reach for `trellis mem` (past-solution recall, decision retrieval, cross-session continuation, familiar-bug debugging, self-pattern spotting, finish-work retrospective) and intentionally does *not* prescribe a fixed write-back file. What to do with what `mem` returns is judged in the moment by the AI based on the live conversation.
* Source: `packages/cli/src/templates/common/bundled-skills/trellis-session-insight/`
* Auto-dispatched to every supported platform on `trellis init` and `trellis update`
Shipped in `v0.6.0-beta.23`.
### Channel runtime — multi-agent collaboration
`trellis channel` ships a worker-supervisor primitive for coordinating multiple AI processes:
* `channel create | send | wait | spawn | run | list | messages | kill | rm | prune` subcommands
* Claude stream-json and Codex app-server adapters that translate provider output into channel `message` / `progress` / `done` / `error` events
* Forum and thread channels with `--type forum|threads` and `channel context|title|thread rename`
* `--scope project|global` resolution across every channel command
* Project-scoped channel logs under `~/.trellis/channels/<project>/<channel>/events.jsonl` with locked sequence assignment
* Default OOM guard: `channel.worker_guard.idle_timeout` (5m) and `channel.worker_guard.max_live_workers` (6); both configurable per-spawn or via `.trellis/config.yaml`
* Reusable worker runtime APIs in `@mindfoldhq/trellis-core/channel`: `readWorkerInbox()`, `watchWorkerInbox()`, `WorkerInboxError`
* Durable `idempotencyKey` on `sendMessage` / `postThread` so retries return the original JSONL event
Shipped progressively across `v0.6.0-beta.10` through `beta.19`.
### Channel runtime agent definitions auto-dispatched
`trellis init` and `trellis update` now ship `.trellis/agents/{check,implement}.md`, the bundled definitions that `trellis channel spawn --agent <name>` loads at runtime. `trellis workflow --template <id>` prints a non-blocking stderr warning when the resolved workflow references missing `.trellis/agents/<name>.md` files. Detection lives in `packages/cli/src/utils/agent-refs.ts`.
Shipped in `v0.6.0-beta.23` (closes `#323`).
### Registry-backed `.trellis/spec` refresh through `trellis update`
`trellis init --template <id>` persists the spec source and template id into `.trellis/config.yaml` under a new `registry.spec` block. `trellis update` reads that block, downloads the configured spec registry into a temp directory, and feeds it through the existing hash / conflict / "modified by you" flow. Supports direct spec registries and marketplace-style registries, including SSH and self-hosted Git sources.
Shipped in `v0.6.0-beta.23` (closes `#315`).
### Reasonix (DeepSeek-Reasonix) platform support
Reasonix is the 15th supported AI coding tool, available via `trellis init --reasonix`. Subagent skills (`trellis-implement`, `trellis-check`) carry `runAs: subagent` frontmatter so Reasonix spawns them as isolated subagent loops.
Shipped in `v0.6.0-beta.23` (closes `#301`).
### Pi Agent — native `trellis_subagent` extension
The Pi extension now exposes `trellis_subagent` with native progress cards, `single` / `parallel` / `chain` dispatch modes, throttled live updates, and Trellis-agent validation.
Shipped in `v0.6.0-beta.19` (closes `#286`, `#290`).
### `@mindfoldhq/trellis-core` SDK package
A second published package, `@mindfoldhq/trellis-core`, exposes the reusable channel, task, and mem domain primitives behind the CLI for Node consumers. Both packages share one git tag, one npm dist-tag, and one version at every release.
Shipped in `v0.6.0-beta.13`.
### `trellis upgrade` command
Wraps `npm install -g @mindfoldhq/trellis@<channel>` with channel-aware defaults (`latest`, `beta`, `rc`), explicit `--tag` and `--dry-run` flags. Replaces the long-form `npm install -g …` snippets that previously appeared in session-start hints.
Shipped in `v0.6.0-beta.9`.
### `trellis-spec-bootstrap` bundled skill
A built-in bundled skill that helps an AI bootstrap `.trellis/spec/` from the real codebase with source-backed references for repository analysis, spec task planning, spec writing, and MCP setup. Auto-installed on every supported platform.
Shipped in `v0.6.0-beta.18` (renamed from the historical typo `trellis-spec-bootstarp` in `v0.6.0-beta.23`; see `#296`).
### Configurable hooks via `.trellis/config.yaml`
Project-level configuration now drives hook behavior:
| Knob | Controls |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `session_commit_message` / `max_journal_lines` / `session_auto_commit` | journal auto-commit shape |
| `hooks.after_create` / `after_start` / `after_finish` / `after_archive` | user shell commands run after each task lifecycle event |
| `channel.worker_guard.idle_timeout` / `max_live_workers` | channel worker OOM protection |
| `codex.dispatch_mode: inline \| sub-agent` | whether the main Codex agent edits code directly or routes through `trellis-implement` / `trellis-check` sub-agents |
## Bug Fixes
### `trellis-implement` / `trellis-check` no longer silent-skip when Exa MCP is absent
The bundled `trellis-implement` and `trellis-check` agent definitions declared `mcp__exa__web_search_exa` and `mcp__exa__get_code_context_exa` as explicit tools. Claude Code's `tools:` parser silently skips agent registration when an explicit MCP tool name fails to resolve, so users without the Exa MCP server installed had every Trellis sub-agent disappear from the dispatch list — the main agent ended up implementing work itself rather than delegating.
Fix:
* `trellis-implement` and `trellis-check` drop both `mcp__exa__*` entries. These agents do not need external web search; the tools list shrinks to `Read, Write, Edit, Bash, Glob, Grep`.
* `trellis-research` folds the previous `mcp__exa__*` + `mcp__chrome-devtools__*` entries into a single `mcp__*` wildcard. Claude Code resolves wildcards lazily (no silent-skip when nothing matches), so this opts research into any MCP the user has configured without locking the source template to a specific provider.
* The Copilot transformer (`mapLegacyToolToCopilot` in `packages/cli/src/configurators/shared.ts`) gets a matching case for `mcp__*` that emits the full set of supported Copilot MCP equivalents.
OpenCode agent files use a different permission mapping syntax (`mcp__exa__*: allow`) that does not silent-skip the agent, so they are intentionally left unchanged.
Closes `#302`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@rc
trellis update
```
If you are coming from `0.6.0-beta.22` or earlier, run `trellis update --migrate` to also pick up the `rename-dir` migration that moves installed `trellis-spec-bootstarp/` skill directories to `trellis-spec-bootstrap/` across the 13 platform skill roots.
The next release on this line will be `0.6.0-rc.1` (bug-only) unless a feature regression forces a return to beta. v0.6.0 GA tracks RC stability.
# v0.6.1
Source: https://docs.trytrellis.app/changelog/v0.6.1
2026-06-17
Docs-only refactor. Run `trellis update` to refresh `.trellis/workflow.md`, the bundled `trellis-meta` skill, the three marketplace workflow variants, and (for Copilot users) the `finish-work` prompt. No `--migrate` required; no breaking change.
## Refactor
### `workflow.md` — Phase 3.1 removed
Phase 3.1 `Quality verification` was structurally identical to the last iteration of Phase 2.2 `Quality check` — both load the `trellis-check` skill and run spec compliance + lint / type-check / tests + cross-layer consistency. Removed as redundant.
Its two unique value points are folded into existing steps:
* **Full-scope final check** → Phase 2.2 gains a "Final pass (before Phase 3.4 commit)" paragraph: the last 2.2 of a task must list all affected packages via `python3 ./.trellis/scripts/get_context.py --mode packages` and walk each package's spec index Quality Check section, not just check the latest implement chunk.
* **Spec-sync trigger** → Phase 3.4 gains a "Spec-sync preamble" at the top: before drafting commits, ask whether non-obvious knowledge surfaced in this task should land in `.trellis/spec/` via Phase 3.3 first.
Step numbering kept stable (3.1 is left as a numbered gap; 3.2 / 3.3 / 3.4 / 3.5 unchanged) so external references in docs, tutorials, and spec do not break.
### `workflow.md` — 1.3 `Configure context` label normalized
Phase Index entry for `1.3 Configure context` previously carried `[conditional · once]`, a single-use label that no other step used. The step body itself said `[required · once]`. Normalized both to `[required · once]` with an explicit `sub-agent-dispatch-platforms-only; inline platforms skip` annotation matching the platform list already in the line.
### Marketplace workflow variants synced
The three marketplace workflow variants (`native`, `tdd`, `channel-driven-subagent-dispatch`) received the same Phase 3.1 removal + 1.3 label fix + 2.2 final-pass paragraph + 3.4 spec-sync preamble. Selectable via `trellis init --workflow <variant>` or `trellis workflow`.
### Bundled `trellis-meta` skill — `change-workflow.md`
Status transition example in the resume-at table updated from `Phase 3.1 (verify quality + spec update)` to `Phase 3.3 (spec update) → 3.4 (commit)`, matching the new numbering.
### Copilot prompt — `finish-work.prompt.md`
The Phase 3 ASCII flow at the top of the `/finish-work` prompt updated to remove `3.1 Quality verification` and add a one-line note that `3.1 was folded into 2.2 + 3.4`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` is required. No source code changed; this is a template refresh.
Users on any `0.6.x` install run `trellis update` to pick up the workflow refresh. Users on `0.5.x` should first follow the [v0.6.0](/changelog/v0.6.0) upgrade path (`trellis update --migrate`), then run `trellis update` again to land on 0.6.1.
# v0.6.10
Source: https://docs.trytrellis.app/changelog/v0.6.10
2026-07-28
Patch release restoring Python 3.9–3.11 task script compatibility, complete Codex sub-agent context recovery for truncated hook output, and correct fallback-session cleanup.
## Bug Fixes
### Python task script compatibility
Generated `.trellis/scripts/common/task_context.py` no longer uses multiline nested f-strings. All `task.py` commands parse on the documented Python 3.9+ floor, with warning text unchanged (#476).
### Codex truncated hook context
The `trellis-implement`, `trellis-check`, and `trellis-research` templates now detect `Full hook output saved to: <path>` and read the saved `SubagentStart` payload before treating `<!-- trellis-hook-injected -->` as complete. If the saved output cannot be read, they fall back to the active task's role JSONL and task docs (#465).
### Fallback session cleanup
`clear_active_task()` now deletes the session file named by the resolved `previous.context_key`, not the current process key. `task.py finish` clears a uniquely resolved `session-fallback` task and leaves ambiguous or unresolved session state untouched (#469).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
# v0.6.11
Source: https://docs.trytrellis.app/changelog/v0.6.11
2026-07-30
Patch release improving Pi and Codex sub-agent reliability, UTF-8 hook input, bounded polyrepo scans, and platform detection.
## Bug Fixes
### Pi sub-agent model and thinking
`trellis_subagent` now uses the invoking Pi session model when neither the call nor agent frontmatter selects a model. Explicit overrides keep their existing precedence, and the `thinking` option now accepts and preserves `max` (#494, #499).
### Codex channel failures and idle timeout
The Codex channel adapter now emits a channel error when a turn fails without a final answer, surfaces non-retryable app-server errors, and deduplicates paired failure notifications. The supervisor idle timer continues after `done` or `error`, so completed workers that remain idle are terminated normally (#495, #496).
### UTF-8 hook input
Standalone Python hooks now decode host-provided JSON from `stdin` as UTF-8 independently of the process locale. This covers sub-agent context injection, shell session context, and the optional Claude statusline on GBK and other non-UTF-8 hosts (#498).
### Bounded polyrepo Git scans
Automatic child-repository discovery stops after eight repositories and directs larger workspaces to explicit `packages` configuration. Best-effort Git status probes now use a two-second timeout without changing normal Git commands (#497).
### Trellis-owned platform detection
`getConfiguredPlatforms()` now detects installations from Trellis-owned template hashes intersected with each platform collector and private config directory. Shared `.agents/skills` files no longer create false positives during `trellis init` (#501).
## Internal
### Python 3.9 CI gate
CI now compiles every tracked `.py` file with Python 3.9, runs `basedpyright`, and triggers when Python files change. This enforces the documented minimum Python version before release (#502).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
# v0.6.12
Source: https://docs.trytrellis.app/changelog/v0.6.12
2026-08-01
Patch release isolating concurrent Pi sessions.
## Bug Fixes
### Pi session identity
The `.pi/extensions/trellis/index.ts` extension now derives each main window's Trellis context from Pi's native session ID. `contextKey()` ignores ambient `TRELLIS_CONTEXT_ID`, and `getKey()` no longer adopts an unrelated singleton runtime pointer. Session IDs changed by normalization include a raw-ID hash so distinct IDs cannot collapse onto the same context key (#512, #513).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
# v0.6.13
Source: https://docs.trytrellis.app/changelog/v0.6.13
2026-08-06
Patch release extending the shell-ticket session bridge to six platforms and deduplicating the `CLAUDE_ENV_FILE` append.
## Bug Fixes
### Shell-ticket session bridge on six platforms
`inject-shell-session-context.py` now ships to Gemini CLI, Qoder, CodeBuddy, Droid, Trae and ZCode. On those platforms `task.py start` resolved no session identity and left `.trellis/.runtime/sessions/` unwritten.
| Platform | Hook event | Registered in |
| ---------- | ------------ | -------------------------- |
| Gemini CLI | `BeforeTool` | `.gemini/settings.json` |
| Qoder | `PreToolUse` | `.qoder/settings.json` |
| CodeBuddy | `PreToolUse` | `.codebuddy/settings.json` |
| Droid | `PreToolUse` | `.factory/settings.json` |
| Trae | `PreToolUse` | `.trae/hooks.json` |
| ZCode | `PreToolUse` | `.zcode/config.json` |
Tickets are written to `.trellis/.runtime/shell-tickets/`; the pre-0.6.13 `.trellis/.runtime/cursor-shell/` is still read, never written. Distribution is declared in `SHARED_HOOKS_BY_PLATFORM`. Kiro is not wired: neither of its hook surfaces publishes a pre-tool trigger.
### CLAUDE\_ENV\_FILE append dedupe
`_persist_context_key_for_bash` in `session-start.py` appends `export TRELLIS_CONTEXT_ID=<key>` to `$CLAUDE_ENV_FILE` only when the last existing export assigns a different value. It previously appended on every SessionStart, growing a user-owned file the shell sources for every command. Lines already accumulated are not removed — delete them by hand.
### Update reminder in SessionStart
SessionStart carries `Trellis update available: <current> -> <latest>, run trellis update` inside its `<first-reply-notice>` block, which the assistant relays in its first visible reply. `get_update_hint()` was reachable only through `get_context.py --mode text`, so hook-driven platforms never showed it. The once-per-session marker `.trellis/.runtime/update-check-<key>.marker` now keys on the context key resolved from hook stdin instead of falling back to `TERM_SESSION_ID`.
### ZCode session identity
`.trellis/scripts/common/active_task.py` resolves ZCode session identity from `CLAUDE_CODE_SESSION_ID`, then `CLAUDE_SESSION_ID`. The lookup is platform-scoped, so it fires only after the resolver detects `zcode`.
### Windows Python command rendering
`.snow/SNOW.md`, `.github/copilot-instructions.md` and `.reasonix/skills/<name>/SKILL.md` now go through the `python3` → resolved-Python-command rewrite (`python` on Windows). Every platform file is written through `writeTemplateMap`, which renders each entry with `replacePythonCommandLiterals`. The rewrite is a no-op when the resolved command is `python3`, so output on macOS and Linux is unchanged.
### trellis-meta bundled-skills reference
`trellis-meta`'s `references/local-architecture/bundled-skills.md` — shipped into every platform skill root, e.g. `.claude/skills/trellis-meta/` — documents the current path: one `collect<Platform>Templates()` per platform, written by `writeTemplateMap`. Its platform table lists all 21 skill roots (was 15) and no longer names `writeSkills()` or `configureCursor()`, neither of which exists.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
# v0.6.14
Source: https://docs.trytrellis.app/changelog/v0.6.14
2026-08-06
Fixes task tracking on CodeBuddy, ZCode and Trae. `trellis mem` now returns conversations that were cut short.
## Bug Fixes
### Tasks did not stick on CodeBuddy, ZCode and Trae
On these three, `task.py start` reported success but every later turn still said there was no active task. Trellis read the session under the wrong name, because all three identify themselves with a Claude-compatible variable that Trellis checked first.
On CodeBuddy the hooks also failed to find the project at all: the IDE reports `/` as the working directory, and Trellis took it at face value.
Both are fixed. Run `trellis update` to get the new hooks, then restart your IDE.
### PreToolUse tool names
The IDE and CLI versions of these products name their tools differently, so the hooks were registered for names the IDE never sends.
| Platform | Now matches |
| --------- | ------------------------------------------------------- |
| CodeBuddy | `execute_command`, `Bash`, `PowerShell`, `task`, `Task` |
| Trae | `RunCommand`, `Bash` |
| Qoder | `Bash`, `run_in_terminal` |
## Enhancements
### `trellis mem` returns compacted conversations
When a session was compacted, `trellis mem` used to return only what survived the compaction — often two or three turns out of hundreds. The rest was still in the session file.
It now returns those turns, and marks where each compaction happened. A twice-compacted Codex session that returned 2 turns returns 18; a Claude session went from 100 to 1536. Tool calls, reasoning and system prompts are still stripped as before.
Some content genuinely cannot be recovered, and now says so rather than appearing complete: Codex encrypts messages between agents, and Grok stores pre-compaction turns as rendered markdown under `<session>/compaction/`.
Search results shift slightly. A session that only matched inside a compaction summary no longer matches; sessions whose actual conversation covers the topic now do.
### `trellis mem` reads Grok sessions
```bash theme={null}
trellis mem search "topic" --platform grok
trellis mem extract <session-id>
```
Reads `~/.grok/sessions/`. Project scoping works as it does for other platforms.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
# v0.6.15
Source: https://docs.trytrellis.app/changelog/v0.6.15
2026-08-14
Adds DeepSeek Harness as the 22nd supported platform.
## New Platform
### DeepSeek Harness
```bash theme={null}
trellis init --dsh
```
Writes the shared workflow and bundled skills to `.agents/skills/`, and the
user-invocable entry skills (`trellis-start`, `trellis-continue`,
`trellis-finish-work`) to `.dsh/skills/`, which is dsh's own highest-rank
project skill root. An operator guide lands at `.dsh/DSH.md`.
dsh discovers both skill roots natively and loads skills by name through its
skill-loader tool, so nothing needs to be registered by hand. The default web
and headless profiles ship no session-start hook, so `trellis-start` stays a
skill you invoke rather than something that fires automatically.
dsh exposes no project-level sub-agent surface, so the research, implement and
check phases run inline in the main session instead of being dispatched to
sub-agents. The platform count for sub-agent dispatch stays at 18.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
# v0.6.16
Source: https://docs.trytrellis.app/changelog/v0.6.16
2026-08-27
Task lifecycle commands, a context-manifest gate for sub-agent dispatch, reversible ablation, the OpenCode mem reader restored, and a batch of hook/channel fixes.
## Enhancements
### Context manifest gate
`task.py validate` now fails a seeded `implement.jsonl` / `check.jsonl` with zero curated entries, and `task.py start` refuses to start such a task unless `--allow-empty-context` is passed. The sub-agent injection hook also states in the prompt when no curated context was injected, instead of a stderr-only warning. Absent manifests (platforms without sub-agents) are not gated. (#573)
### Task lifecycle commands
* `task.py rename <task> <new-slug> [--dry-run]` renames the directory and rewrites `task.json` identity, parent/child references, and jsonl manifests together.
* `task.py start` records branch metadata; `task.py archive` validates it.
* Developer identity resolution works in linked git worktrees.
* `task.py create` seeds `implement.jsonl` / `check.jsonl` empty instead of with placeholder rows. (#578)
### Reversible ablation
`trellis ablate` removes every Trellis-managed file from a project and stores the removed state under an external root; `trellis restore` puts it back. Pre-flight conflict checks, project locking, and rollback on failure. (#538)
### Resumable session recorder
`add_session.py` is now a state machine: each step is idempotent, writes are atomic, and a failed run resumes instead of leaving a half-committed session record. (#577)
### OpenCode session reader restored
`trellis mem` reads OpenCode 1.2+ SQLite session storage again — zero-dependency parser, no native module, WAL-aware. (#574)
### OMP prompt-injection skip keyword
`prompt_injection.skip_keyword` in `.trellis/config.yaml` now works on OMP: a prompt containing the keyword skips workflow-state injection for that turn. (#586)
### ZCode bridge hint
`init` / `update` on ZCode print an install hint for the optional trellis-bridge plugin, for 3.6–3.7 builds that disable project-level hooks.
## Bug Fixes
* `add_session.py` and `task.py archive` auto-commits use explicit pathspecs and no longer sweep pre-staged unrelated files into the chore commit (#579).
* Path containment accepts a `.trellis` that is a symlink into an external store (#567).
* Task script runtime hardening: git `index.lock` retry, JSON read diagnostics, safer subprocess cleanup (#576).
* `trellis update` repairs receipt entries for files already byte-identical to their template (#575).
* The Pi extension resolves the Trellis project root from the session cwd (#581).
* The sub-agent context hook contains jsonl-referenced file reads to the task base path (#584) and surfaces unreadable active-task records (#544).
* Channel: UTF-8 preserved across incremental event reads (#569), `seq` continues after a torn `events.jsonl` tail (#564), stdout drained before supervisor exit (#542), Claude system prompt passed as a file to avoid argv limits (#555).
* OMP: task context injection is byte-budgeted with `[truncated]` / `[omitted]` markers, refreshes after file changes (#541), and deduplicates shared files (#540).
* OpenCode: context injected via `messages.transform` so TUI and history stay clean (#563).
* `workflow.md` routing blocks are no longer dropped for four platforms whose marker labels did not match their platform ids.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
# v0.6.17
Source: https://docs.trytrellis.app/changelog/v0.6.17
2026-09-12
Devin CLI session memory, on-demand SQLite page reads, and task/session binding fixes.
## Enhancements
### Devin CLI session adapter
`trellis mem` reads Cognition Devin CLI sessions from `~/.local/share/devin/cli/sessions.db` (WAL SQLite) through the existing zero-dependency parser. This is not `trellis init --devin` (Desktop/Cascade) and not Factory Droid. (#614)
* `--platform devin` on `list` / `search` / `extract` / `context` / `projects`
* OpenCode, ZCode, and Devin share `packages/core/src/mem/internal/sqlite-adapter.ts` and `packages/core/src/mem/platforms.ts`
* Devin forests require `main_chain_id`; a missing tip is `devin-main-chain-missing` (no `max(node_id)` fallback)
* `CREATE TABLE` `--` line comments are stripped so `parent_node_id` and `chat_message` parse on live `sessions.db` files
## Bug Fixes
### Lazy SQLite main-page reads
The zero-dependency SQLite reader in `packages/core/src/mem/internal/sqlite-readonly.ts` loads main-file pages on demand instead of reading the whole database into memory. (#596)
### Pi headless subagent prompts
Pi `trellis_subagent` forwards ask-policy prompts to the parent session. The serving heartbeat sets `PI_SUBAGENT_PARENT_SESSION` (not a stale `PI_SESSION_ID`), sets `PI_SUBAGENT_CHILD=1`, and drops inherited `PI_SESSION_ID` so the child mints its own. (#611)
### Active-task session fallback
Resolving an active task from a missing session id no longer falls back to the only session in the project. That fallback is explicit opt-in, so one session cannot bind another session's task. (#608)
### Archive child unlink restore
If `task.py archive` fails after unlinking some children, it restores each child's `parent` link from a snapshot taken before the clear. A duplicated `children` entry is snapshotted once so a second visit cannot restore `parent: null`. (#613)
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
# v0.6.2
Source: https://docs.trytrellis.app/changelog/v0.6.2
2026-06-17
Docs-only fix following up on the v0.6.1 workflow simplification. Run `trellis update` to refresh the `/continue` command. No `--migrate` required.
## Bug Fixes
### `/continue` routing pointed at the deleted Phase 3.1
The `/continue` command's resume-routing table still sent `status=in_progress` + check-passed to the Phase **3.1** that [v0.6.1](/changelog/v0.6.1) removed. It now routes to **3.3** (spec update) → **3.4** (commit), matching the simplified workflow.
The v0.6.1 cleanup updated `workflow.md`, the three marketplace workflow variants, the bundled `trellis-meta` skill, and the Copilot `finish-work` prompt — but missed `commands/continue.md` because its routing uses a bare-number syntax (`→ **3.1**`) that the `Phase 3.1` grep did not match.
## Internal
### Sync matrix hardened against this class of miss
`.trellis/spec/docs-site/docs/sync-on-change.md` Trigger 1 (Phase Structure Changes) now enumerates every in-template file carrying step-routing references (`continue.md`, `trellis-meta` change-workflow reference, Copilot prompt, marketplace variants) and adds a bare-number grep pattern. A future step delete/renumber audits all routing sites, not just `workflow.md`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required. No source code changed; this is a template refresh.
# v0.6.3
Source: https://docs.trytrellis.app/changelog/v0.6.3
2026-06-18
This release bundles five enhancements — ZCode platform support, an opt-in `--with-statusline` status bar, a Pi session adapter for `trellis mem`, reasoning frameworks for the brainstorm/break-loop skills, and the Windsurf → Devin platform rename — plus two fixes (#300, #303). Run `trellis update` to refresh templates. Only the Windsurf → Devin rename needs `trellis update --migrate`, and only if you previously initialized with `--windsurf`.
## Enhancements
### ZCode platform support (`--zcode`)
Added ZCode (智谱 / Z.ai) as a pull-based, agent-capable platform (no hooks). `trellis init --zcode` writes three output paths:
| Target | Path | Contents |
| ------------- | -------------------------- | ------------------------------------------------------------ |
| Shared skills | `.agents/skills/` | byte-identical with Codex/Gemini |
| Commands | `.zcode/commands/trellis/` | invoked as `/trellis:<name>` |
| Sub-agents | `.zcode/cli/agents/` | `trellis-implement`, `trellis-check` with pull-based prelude |
Registry entry `AI_TOOLS.zcode`: `configDir: ".zcode"`, `cliFlag: "zcode"`, `extraManagedPaths: [".zcode/cli/agents", ".zcode/commands"]`, `agentCapable: true`, `hasHooks: false`, `executorAI: "Bash scripts or Agent calls"`. Configurator `configureZcode` / `collectZcodeTemplates` in `src/configurators/zcode.ts`; templates under `src/templates/zcode/`.
### trellis init --with-statusline (Claude Code statusLine)
`trellis init --with-statusline` installs an opt-in Trellis status bar for Claude Code (off by default). When the flag is omitted and Claude Code is selected, `init` prompts interactively (`default: false`; skipped under `-y`).
Writes two artifacts, Claude Code only:
| Artifact | Content |
| -------------------------------------- | ------------------------------------------------------------------------------------ |
| `.claude/hooks/statusline.py` | Status hook: model · ctx% · branch · duration · developer · task count · rate limits |
| `.claude/settings.json` → `statusLine` | `{ "type": "command", "command": "{{PYTHON_CMD}} .claude/hooks/statusline.py" }` |
The hook is not part of `collectTemplates` or shared-hooks, so `trellis update` never force-installs it on opted-out projects nor removes it from opted-in ones. The flag-off path leaves `settings.json` byte-identical.
### Pi session mem adapter
`trellis mem` now reads persisted Pi Agent sessions. New adapter `packages/core/src/mem/adapters/pi.ts` exports `piListSessions`, `piExtractDialogue`, `piSearch`, `collectPiTurnsAndEvents`. `MemSourceKind` in `mem/types.ts` adds `"pi"`; `--platform claude|codex|opencode|pi|all` is now accepted.
Session discovery:
* Default store `~/.pi/agent/sessions/--<encoded-cwd>--/<timestamp>_<id>.jsonl`, via `piProjectDirFromCwd` / `piSessionRoots`.
* Custom dirs from `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`, or `settings.json` `sessionDir`.
Extraction follows the active branch (`id`/`parentId` leaf walk) and applies Pi compaction rules via `firstKeptEntryId`. Pi joins Claude/Codex with native phase-boundary detection in `sliceMemPhase`; `bash`/`shell` tool calls feed `task.py` events.
### Devin platform (renamed from Windsurf)
Cognition renamed Windsurf to Devin Desktop (2026-06-02 OTA) and moved its config dir from `.windsurf/` to `.devin/` (identical subpaths: `workflows/`, `skills/`). Trellis follows the rename.
* `trellis init --devin` writes `.devin/workflows/` + `.devin/skills/`; the platform shows as **Devin** and `--platform devin` is passed to scripts (#325).
* `--windsurf` remains a **deprecated alias** for `--devin` for one version. Passing it prints a deprecation notice and behaves like `--devin`.
* `TRELLIS_PLATFORM=windsurf` and a leftover `.windsurf/workflows/` directory are still detected as Devin for back-compat.
### Thinking frameworks in brainstorm + break-loop skills
Two reasoning frameworks are embedded in the shared workflow skills (`packages/cli/src/templates/common/skills/`), so every platform picks them up on `trellis update`:
| Skill | Framework | When it applies |
| ------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `brainstorm` | First Principles Analysis | requirement discovery — decompose to fundamental truths, challenge assumptions, build up the minimum viable solution |
| `break-loop` | Bayesian Reasoning | repeated debugging — set hypothesis priors, update beliefs by evidence strength, seek discriminating evidence before committing a fix |
Hardcoded "5 skills" comments across the configurators, `shared.ts`, and `update.ts` are replaced with count-free wording (#335).
## Bug Fixes
### trellis mem --cwd Claude session filter on Windows
`trellis mem` returned 0 Claude sessions when filtering by `--cwd` on Windows. `claudeProjectDirFromCwd` (`packages/core/src/mem/internal/paths.ts`) only replaced `/` and `_` with `-`, so Windows cwds with backslashes, drive colons, and dots derived a project-dir name that did not exist under `~/.claude/projects/`. The sanitization regex now covers all separators: `/[/\\:_.]/g`. In `claudeListSessions` (`packages/core/src/mem/adapters/claude.ts`), the `--cwd` fast path now falls back to scanning every project dir when the derived dir is missing; the per-session `sameProject(cwd, f.cwd)` check still scopes results, so the filter never silently returns 0. Fixes #300.
### .trellis auto-commit staging scope
Scoped `.trellis/` auto-commit staging so it no longer sweeps unrelated task/workspace files into commits (#303). Previously a wide `tasks_dir.iterdir()` scan staged every active task dir, bundling dirty parallel-window task dirs into the session commit.
* `safe_commit.py`: `safe_trellis_paths_to_add()` gained a `task_name` param. When passed, it stages only `.trellis/tasks/<task_name>/` (and its archive location) — no `iterdir()` over all tasks. Omitting `task_name` keeps the legacy wide scan for backward compat.
* `add_session.py`: `_auto_commit_workspace()` resolves the current task via `get_current_task()` and passes `task_name`. When unresolvable (0 or >=2 parallel sessions), it stages only journal/index and skips every task dir under `tasks/`.
* `release.js`: the pre-release `git add -A` now also excludes `':!.trellis'` (alongside `':!docs-site'`, `':!marketplace'`).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
Only the Windsurf → Devin rename needs `--migrate`:
<Note>
If you initialized Trellis with `--windsurf`, run `trellis update --migrate` to apply the `rename-dir` migrations that move:
* `.windsurf/workflows/` → `.devin/workflows/`
* `.windsurf/skills/` → `.devin/skills/`
The migration is idempotent: projects without a `.windsurf/` directory are silently skipped. `--windsurf` still works as a deprecated alias for `--devin` this release.
</Note>
# v0.6.4
Source: https://docs.trytrellis.app/changelog/v0.6.4
2026-06-22
Patch release with two independent bug fixes: Kiro's main session now activates the workflow deterministically, and four `agentCapable && !hasHooks` platforms (Codex, ZCode, OpenCode, Reasonix) finally emit `trellis-start`. Run `trellis update` to refresh. No `--migrate` required.
## Bug Fixes
### `trellis-start` missing on `agentCapable && !hasHooks` platforms
`filterCommands(ctx)` in `packages/cli/src/configurators/shared.ts` stripped `start` whenever `ctx.agentCapable` was true. The premise — that an agent-capable platform always has a SessionStart-style hook to inject opening context — does not hold for **Codex, ZCode, OpenCode, Reasonix**, which lack such a hook. Result: users had no way to load workflow context (no `/trellis:start` slash command, no `trellis-start` skill).
The fix narrows the condition to `agentCapable && hasHooks`. The standard `resolveAllAsSkillsNeutral` / `resolveCommands` paths now emit `trellis-start` naturally on all four platforms.
Codex's one-off `resolveCodexTrellisStartSkill` helper (introduced in 0.5.5 as a manual patch) is deleted along with its two call sites in `configurators/codex.ts` and `configurators/index.ts`. Codex output is byte-identical with the helper-written version (same template `common/commands/start.md`, same resolver, same wrapper), so `trellis update` will not flag user-modified.
Triggered by external user report: `trellis init --zcode` produced neither `/trellis:start` nor `trellis-start`.
### `workflow.md` platform-matrix missing ZCode and Reasonix
13 edit points in `packages/cli/src/templates/trellis/workflow.md`:
* **B1 / B3 / B5 / B7 / B12** (Active Task Routing, Phase 1.2 Research, Phase 1.3 Configure context, Phase 1.5 Completion criteria, Phase 2.2 Quality check) — `ZCode, Reasonix` added to the sub-agent dispatch platform lists.
* **B9** (Phase 2.1 implement, class-2 pull-based) — `[codex-sub-agent]` → `[codex-sub-agent, ZCode, Reasonix]`. Both platforms need the `Active task:` prefix the codex-sub-agent block already mandates.
* **Line 186** — prose enumeration in the Phase Index section gains `, ZCode, Reasonix`.
* **B8 unchanged** — its body claims "platform hook/plugin auto-handles", which is false for pull-based platforms. ZCode and Reasonix are deliberately excluded.
### Kiro main-session workflow injection
Pre-0.6.4 Kiro projects had no deterministic Trellis activation. The three sub-agent JSONs registered `agentSpawn` hooks, but the main session had no hook of its own, so the workflow never kicked in.
The "Kiro supports only `agentSpawn`" assumption that drove the original wiring was wrong. Kiro CLI exposes `userPromptSubmit` and `agentSpawn`; the IDE has file-based `.kiro.hook` (`promptSubmit`). 0.6.4 wires both:
* **`.kiro/agents/trellis.json`** (new main agent): `userPromptSubmit` → `inject-workflow-state.py`, `agentSpawn` → `session-start.py`, `workflow.md` declared as an always-loaded resource.
* **`.kiro/hooks/trellis-workflow-state.kiro.hook`** (new IDE hook): `promptSubmit` → `runCommand`.
* **`inject-workflow-state.py` + `session-start.py`** add an isolated `platform == "kiro"` branch that prints plain stdout (Kiro adds it to context; no `hookSpecificOutput` envelope). Detected via `KIRO_PROJECT_DIR` env or `.kiro` script path. Other platforms byte-unchanged (isolation test added).
* **`SHARED_HOOKS_BY_PLATFORM.kiro`** gains `session-start.py` + `inject-workflow-state.py`.
The three sub-agents (`trellis-{implement,check,research}.json`) keep their `agentSpawn → inject-subagent-context.py` wiring unchanged.
The plain-stdout-to-context contract and the IDE `runCommand` stdout injection follow Kiro's official docs; real-machine verification is pending. Fallback for users hitting issues: `askAgent` + static steering.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
* **Kiro** users: `update` writes the new main-session agent (`.kiro/agents/trellis.json`), the IDE hook (`.kiro/hooks/trellis-workflow-state.kiro.hook`), and the shared hook scripts.
* **ZCode / OpenCode / Reasonix** users: `update` writes the previously missing `trellis-start` skill / `/trellis:start` slash command.
* **Codex** users: no observable change. The trellis-start skill is now produced via the standard path instead of the helper, but the file bytes are identical.
# v0.6.5
Source: https://docs.trytrellis.app/changelog/v0.6.5
2026-06-25
Patch release with Trae IDE support, reliable Pi Agent startup context, Pi sub-agent tool configuration fixes, and runtime reliability improvements for Windows channel sessions, hooks, and task planning gates. Run `trellis update` to refresh existing projects. No `--migrate` required.
## Highlights
### Trae IDE platform support
Trellis now supports Trae IDE as a first-class platform.
`trellis init --trae` writes:
* `.trae/commands/trellis-*.md` slash commands with frontmatter
* `.trae/skills/` workflow skills and bundled skills
* `.trae/agents/` Trellis implement/check/research agents
* `.trae/hooks/` shared Python hooks
* `.trae/hooks.json` for `SessionStart` and `UserPromptSubmit`
Trae uses shared hooks for main-session startup and per-turn workflow context. Sub-agent context uses the class-2 pull-based prelude because Trae does not expose a Trellis-supported sub-agent prompt mutation surface.
The bundled workflow now keeps class-2 implement dispatch (codex-sub-agent, Gemini, Qoder, Copilot, ZCode, Reasonix, Trae) in the pull-based block, not the hook auto-handles block. This keeps workflow guidance aligned with generated pull-based sub-agent context loading.
### Pi Agent startup context
Pi Agent's `session_start` event is notify-only, so it cannot inject model-visible context by itself. 0.6.5 moves the startup payload to the first `before_agent_start` event for each Trellis context key.
New Pi sessions now receive compact Trellis startup context in `systemPrompt`: workflow state, session overview, active-task status, the compact workflow index, and the first-reply notice. `.pi/prompts/trellis-start.md` remains as a manual fallback.
### Pi sub-agent tools
Generated `.pi/agents/trellis-*.md` files can declare `tools` frontmatter for `trellis_subagent`. Tool names are normalized to lowercase, and the unused `PI_TOOL_ALLOWLIST` path is removed so Pi receives the tool names it expects.
## Reliability Fixes
### Windows channel sessions
Channel session spawning now resolves Windows npm `.cmd` shims to a spawnable executable path before launch. This fixes failures where the supervisor tried to spawn a non-existent `.exe` path.
### Hooks and planning gates
Shared Python hooks no longer block when stdin is empty.
ZCode command fallbacks now stay under `.zcode/commands/trellis/` instead of the shared `.agents/skills/` directory. This prevents Codex + ZCode combined installs from reporting immediate template drift on `trellis update --dry-run`.
Trellis also tightens task readiness:
* `workflow.md` requires curated `implement.jsonl` / `check.jsonl` context before starting implementation.
* `brainstorm` requires lossless PRD convergence before planning continues, so updated requirements are not dropped during iterative task shaping.
## Internal
CI now runs on marketplace submodule pointer changes, and the marketplace workflow mirror has been synced for Trae support.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
* **Trae** users: run `trellis init --trae` in projects that do not yet have `.trae/`; run `trellis update` in existing Trellis projects.
* **Pi** users: run `trellis update` to receive the generated start prompt and extension startup-context updates.
* **Windows channel** users: install the latest CLI before starting new channel sessions.
# v0.6.6
Source: https://docs.trytrellis.app/changelog/v0.6.6
2026-07-09
Patch release with Oh My Pi platform support, cache-stable Pi runtime context, corrected ZCode paths, safer channel sessions, and task CLI cleanup. Run `trellis update` to refresh existing projects. New installs do not need `--migrate`; ZCode users on 0.6.3-0.6.5 should run `trellis update --migrate` once if `.zcode/cli/agents/` exists.
## Enhancements
### Oh My Pi platform support
Trellis now supports Oh My Pi as a first-class platform.
`trellis init --omp` writes:
* `.omp/agents/` for `trellis-implement`, `trellis-check`, and `trellis-research`
* `.omp/commands/` for Trellis workflow commands
* `.omp/skills/` for Trellis workflow and bundled skills
* `.omp/extensions/trellis/` for runtime context injection
OMP is registered in the generated `cli_adapter.py` and `task_store.py`, so OMP projects receive Trellis workflow routing and task JSONL context where sub-agents need it.
## Bug Fixes
### Pi runtime context
Pi extension output now keeps `systemPrompt` byte-stable across turns. Startup and task context are memoized, while mutable workflow, session, and task updates are delivered through persistent hidden messages. This preserves provider prefix-cache eligibility while still keeping Trellis context current.
### Oh My Pi runtime context
The OMP extension now injects session-start, task, and sub-agent context through the platform runtime instead of relying on stale session identity fallbacks. Generated OMP command files also include YAML frontmatter, and implement/research agents use the `pi/task` model hint.
### ZCode layout
ZCode-managed Trellis skills now live under `.zcode/skills/`, and ZCode sub-agents live under `.zcode/agents/`. The generated ZCode agent set now includes `trellis-research`, and `.zcode` is treated as sub-agent-capable when Trellis decides whether to seed `implement.jsonl` / `check.jsonl`.
### Channel sessions
Channel workers on Windows now resolve npm `.cmd` and node-script shims before spawning Codex workers. Channel stdout event writes are serialized so concurrent output cannot corrupt event records.
### Task creation
`task.py create` now rejects or normalizes explicit `--slug` values that already include an `MM-DD-` prefix, warns on blank descriptions, makes automatic session activation visible, and adds `--no-start` for backlog creation without moving the current session pointer.
### Codex inline mode
Codex inline mode no longer receives seed-only `implement.jsonl` / `check.jsonl` files just because `.codex/` exists. Trellis only seeds those files for Codex when `codex.dispatch_mode: sub-agent` is explicitly configured.
### Session and hook templates
Session journals now use explicit fallback text instead of placeholders. Copilot instructions preserve repo-authored content while Trellis manages only its own guidance block, and shared hooks keep fail-open behavior without catching `BaseException`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
* **Oh My Pi** users: run `trellis init --omp` in projects that do not yet have `.omp/`; existing OMP dogfood projects should run `trellis update`.
* **ZCode** users on 0.6.3-0.6.5: run `trellis update --migrate` once if `.zcode/cli/agents/` exists. This moves legacy sub-agents to `.zcode/agents/`.
* **Pi** users: run `trellis update` to receive the cache-stable extension runtime.
* **Codex inline** users: run `trellis update` so new tasks stop receiving seed-only JSONL context files.
# v0.6.7
Source: https://docs.trytrellis.app/changelog/v0.6.7
2026-07-13
Patch release with project-local Pi memory discovery and filesystem-safety fixes for channel, update, uninstall, task archive, state writes, and template downloads. Run `trellis update` to refresh existing projects. No `--migrate` required.
## Enhancements
### Pi memory session discovery
`trellis mem` now reads Pi session storage from both global `~/.pi/agent/settings.json` and project-local `.pi/settings.json`. Relative `sessionDir` values resolve from the directory containing the settings file, matching Pi's settings behavior.
## Bug Fixes
### Channel path validation
`trellis channel` now rejects channel and worker names that are unsafe filesystem path segments. Cross-channel discovery skips legacy directories whose names do not pass the same validation instead of aborting the scan.
### State and template writes
Generated files, `.trellis/.template-hashes.json`, registry config, `task.json`, and session pointers now use atomic replace operations. `downloadWithStrategy(..., "overwrite")` downloads into a temporary directory before replacing existing templates, and temporary-directory cleanup errors no longer mask the download result.
### Destructive command guards
Trellis now protects user-owned data across destructive operations:
* `trellis uninstall` removes only the managed block from `AGENTS.md` and refuses unattended `--yes` removal when `.trellis/spec/`, `.trellis/tasks/`, or `.trellis/workspace/` contains uncommitted files.
* `task.py archive` accepts only real task directories under `.trellis/tasks/`.
* `trellis update` keeps an existing `journal-N.md` during the legacy `traces-N.md` rename and only applies `rename-dir` automatically to directories tracked as Trellis-owned.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required. Pi users with project-local session storage can run `trellis mem` from that project after upgrading.
# v0.6.8
Source: https://docs.trytrellis.app/changelog/v0.6.8
2026-07-22
Patch release adding two platforms (Grok Build, Kimi Code), Codex native subagent dispatch, machine-readable platform/task state, and the Pi shared-skills migration. Pi users should run `trellis update --migrate`; everyone else `trellis update`.
## Enhancements
### Grok Build platform
`trellis init --grok` configures Grok Build (xAI CLI) as a class-2 pull-based platform: `.grok/skills/`, flat `.grok/commands/trellis-*.md`, and `.grok/agents/`. Hook context injection is not enabled — Grok does not consume hook stdout.
### Kimi Code platform
`trellis init --kimi` configures Kimi Code as a class-2 pull-based platform: `.kimi-code/skills/`, shared `.agents/skills/`, prompts under `.kimi-code/prompts/`, and dispatch via the built-in `coder` / `explore` sub-agents.
### Codex native subagent dispatch
Codex now dispatches `trellis-implement` / `trellis-check` / `trellis-research` as native subagents with `SubagentStart` context injection and child-side pull fallback. `agents.max_depth=1` is pinned in the project `config.toml` to prevent recursion.
### ZCode hooks and mem sessions
ZCode gains deterministic hook context injection and `trellis mem` session discovery (#411).
### Machine-readable state
* `trellis platforms --json` lists configured platforms with `id`, `displayName`, `configDir` (#396).
* `task.py list --json` / `task.py current --json` emit structured task state (#395).
### Channel and task options
* `trellis channel spawn --sandbox <read-only|workspace-write|danger-full-access>` overrides the Codex worker sandbox mode (#413).
* `task.py create` stamps `base_branch` from the repo default and accepts `--base-branch` (#399).
## Bug Fixes
### Pi shared skills root
Pi now writes skills to the shared `.agents/skills/` root instead of a private `.pi/skills/` copy, fixing duplicate skill installs alongside Codex/Gemini (#447). The 0.6.8 migration moves existing `.pi/skills/` content; `trellis update` rename-dir merges no longer clobber the canonical target with stale source bytes.
### Update and template fixes
* Reintroduced templates are preserved on update (#425).
* Registry template downloads drop `preferOffline`, avoiding stale cache hits (#383).
* YAML frontmatter descriptions are quoted to survive embedded colons (#437).
### Hook and workflow fixes
* Oh My Pi bridges session context into the bash env (#424).
* SessionStart acknowledgment language adapts to the session (#439).
* Brainstorm requires explicit planning approval before task creation (#416).
* 0.6.7 fleet review batch: task boundary, atomic write, activation diagnostics, OpenCode `start.md` (#438).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update # most projects
trellis update --migrate # Pi projects: moves .pi/skills/ → .agents/skills/
```
# v0.6.9
Source: https://docs.trytrellis.app/changelog/v0.6.9
2026-07-24
Patch release adding the Snow CLI platform, sub-agent context injection caps across all three loaders, a per-turn injection skip keyword, durable Codex sub-agent model config, channel trusted context dirs for symlinked workspaces, and journal merge conflict relief.
## Enhancements
### Snow CLI platform
`trellis init --snow` configures Snow CLI as a class-1 platform: auto context inject via `.snow/hooks/`, project agent discovery under `.snow/agents/`, `beforeSubAgentStart` prompt enrichment, and multi-session isolation via Snow session identity env (#443).
### Sub-agent context injection caps
Sub-agent context injection now caps per-file (32 KiB), per-artifact (64 KiB), and total (128 KiB) payload size across the shared Python hook, the Pi extension, and the OpenCode plugin. Oversized files truncate with a notice; once the total cap is reached, remaining files degrade to index lines instead of being inlined. Configurable via `context_injection` in `.trellis/config.yaml` (`0` disables a limit). Binary referenced files (detected via NUL bytes and strict UTF-8 validation) are never inlined — they emit a reference-only notice regardless of the configured limits (#441, #456, #471).
### `no-trellis` skip keyword
A prompt containing the configurable skip keyword (default `no-trellis`, word-boundary match) mutes the per-turn workflow-state injection for that turn. Configurable via `prompt_injection.skip_keyword` in `.trellis/config.yaml`; empty string disables the escape hatch (#427).
### Durable Codex sub-agent model config
User-set `model` / `model_reasoning_effort` in `.codex/agents/trellis-*.toml` now survive `trellis update` regeneration instead of being overwritten. Templates ship commented hints (`gpt-5.6-terra` / `high`) so the knob is discoverable. `dispatch_mode` stays `auto` by default — sub-agents inherit the main session's model unless pinned in the agent toml (#459).
### Channel trusted context dirs
`channel.trusted_context_dirs` in `.trellis/config.yaml` allowlists external directories for context loading, plus narrow auto-trust when `.trellis/tasks` or `.trellis/workspace` themselves are symlinks — for projects that persist Trellis data outside a periodically-replaced project directory (#414).
### Script and task quality-of-life
* `add_session.py` gains repeatable `--change` / `--test` / `--next-step` flags; sections with no content are omitted instead of rendering placeholder text (#394).
* `task.py list` renders a task with a dangling parent reference flat instead of hiding it (#402).
* `task.py create --meta key=value` (repeatable) and a new `task.py set-meta` subcommand expose the `task.json` `meta` field.
## Bug Fixes
### Kimi research persistence
`trellis-research` on Kimi Code now dispatches through the writable built-in `coder` sub-agent, so research findings persist under the task's `research/` directory instead of being lost (#457).
### Journal merge conflicts
`.gitattributes` ships `journal-*.md merge=union`, so parallel-worktree or concurrent `trellis archive` runs no longer conflict on append-only journal content. `index.md` conflicts are expected when parallel sessions ran — picking either side is safe since task state lives in `task.json`, not `index.md`. `add_session.py` warns once when run inside a linked worktree with `session_auto_commit` enabled (#415).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
# v0.7.0-beta.0
Source: https://docs.trytrellis.app/changelog/v0.7.0-beta.0
2026-07-28
The first 0.7 beta adds path-scoped spec delivery and runtime workflow
selection.
## Enhancements
### Dynamic spec loading
Specs can declare repo-relative `paths` globs in YAML frontmatter. Trellis
matches those globs when an agent touches a file and delivers only the
governing spec content.
* Claude Code receives matching specs through `PostToolUse` on
`Read|Edit|Write|MultiEdit`.
* Codex receives matching specs through `PreToolUse` on native `apply_patch`.
A patch that first receives a full spec is denied once and succeeds after
the model reads the rules and retries.
* Full bodies, silent in-window hits, refresh tickets, truncation, and
`SessionStart(source=clear|compact)` reset use one shared decision engine.
* `get_context.py --mode spec --file <path>` exposes the same matching in pull
mode.
See [Dynamic Spec Loading](/beta/advanced/dynamic-spec-loading).
### Dynamic workflow switching
Workflow variants now coexist under `.trellis/workflows/` and can be selected
without replacing the global `.trellis/workflow.md`.
* `trellis workflow --save <workflow-id>` populates the project workflow library.
* `task.py create --workflow <workflow-id>` and
`task.py workflow <workflow-id>` pin a variant to
one task.
* Runtime precedence is task pin → personal `.trellis/.developer` override →
team `default_workflow` → global workflow.
* Session-start context, per-turn breadcrumbs, and phase lookup share the same
resolver.
See [Dynamic Workflow Switching](/beta/advanced/dynamic-workflow-switching).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No file migration is required. Existing specs without `paths` frontmatter and
projects without workflow selection settings retain their previous behavior.
# v0.7.0-beta.1
Source: https://docs.trytrellis.app/changelog/v0.7.0-beta.1
2026-07-29
This beta adds workflow scaffolding, Pi workflow selection, and OpenCode
dynamic spec loading.
## Enhancements
### Workflow scaffolding
`trellis workflow create <workflow-id>` creates a user-managed
`.trellis/workflows/<workflow-id>.md` from the complete native workflow.
Interactive runs can set the new workflow as the project default in
`.trellis/config.yaml` and the personal default in `.trellis/.developer`.
`--skip-defaults` creates only the file. The global `.trellis/workflow.md`
remains unchanged.
### Pi dynamic workflow selection
The Pi extension now resolves the workflow used for per-turn breadcrumbs with
the same precedence as other Trellis consumers:
```text theme={null}
task workflow → personal .developer → team config.yaml → global workflow.md
```
Invalid or missing variants fall through to the next layer.
### OpenCode dynamic spec loading
OpenCode now matches governing specs before `write`, `edit`, and `apply_patch`.
When a full spec is delivered, the plugin blocks the first mutation with a
model-visible tool error; the model reads the rules and retries, while persisted
delivery state makes the retry silent. `session.compacted` resets exposure.
Ticket-only and failure responses remain fail-open.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No file migration is required.
# v0.7.0-beta.2
Source: https://docs.trytrellis.app/changelog/v0.7.0-beta.2
2026-08-06
Sync release. The 0.7 beta line picks up every stable fix shipped in v0.6.11
through v0.6.13. No beta-only features changed.
## Synced from main
| Release | Fixes |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| v0.6.11 | Pi subagent model inheritance and max thinking; Codex channel failure reporting; idle timeout after completed turns; bounded polyrepo Git scan; UTF-8 hook stdin; platform detection from Trellis-owned files |
| v0.6.12 | Pi context isolation by native session ID |
| v0.6.13 | Shell-ticket session bridge on Gemini CLI, Qoder, CodeBuddy, Droid, Trae and ZCode; `CLAUDE_ENV_FILE` append dedupe; SessionStart update reminder; ZCode session identity; Windows Python command rendering; `trellis-meta` bundled-skills reference |
Per-release detail is in the [v0.6.11](/changelog/v0.6.11),
[v0.6.12](/changelog/v0.6.12) and [v0.6.13](/changelog/v0.6.13) changelogs.
Beta-only behavior is unchanged: workflow scaffolding, per-task workflow
selection, path-scoped spec injection and OpenCode dynamic spec loading all
carry over as-is. `SHARED_HOOKS_BY_PLATFORM` now declares both
`inject-spec-context.py` (beta) and `inject-shell-session-context.py` (main);
the shell hook is not wired to OpenCode, whose spec injection is a JS plugin
rather than a Python hook config.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No `--migrate` required.
# v0.7.0-beta.3
Source: https://docs.trytrellis.app/changelog/v0.7.0-beta.3
2026-08-06
Sync release. The 0.7 beta line picks up v0.6.14. No beta-only behavior changed.
## Synced from main
| Release | Changes |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| v0.6.14 | Task tracking fixed on CodeBuddy, ZCode and Trae; PreToolUse matchers updated for IDE tool names; `trellis mem` returns compacted conversations and reads Grok sessions |
See the [v0.6.14](/changelog/v0.6.14) changelog for detail.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No `--migrate` required.
# v0.7.0-beta.4
Source: https://docs.trytrellis.app/changelog/v0.7.0-beta.4
2026-09-12
Sync release. The 0.7 beta line picks up v0.6.15 through v0.6.17. DeepSeek Harness on beta now dispatches native sub-agents.
## Synced from main
| Release | Changes |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| v0.6.15 | DeepSeek Harness (`trellis init --dsh`) as the 22nd platform; phases run inline on stable |
| v0.6.16 | Context-manifest gate; task lifecycle commands; reversible ablation; OpenCode mem reader restored; hook and channel fixes |
| v0.6.17 | Devin CLI session adapter (`--platform devin`); lazy SQLite pages; Pi headless ask forward; active-task session isolation; archive child unlink restore |
See the [v0.6.15](/changelog/v0.6.15), [v0.6.16](/changelog/v0.6.16) and [v0.6.17](/changelog/v0.6.17) changelogs for detail.
## Enhancements
### DeepSeek Harness native sub-agents
On the 0.7 beta line, `trellis init --dsh` installs native research / implement / check sub-agent skills (`trellis-agent-{research,implement,check}`). Stable 0.6.15 still runs those phases inline. (#548)
* Child-only role skills; the main session does not load them
* Uses the companion `dsh-trellis` `trellis_wait` when present; otherwise foreground dispatch. No polling
* Nested-host session identity prefers `DSH_TRELLIS_CONTEXT_ID`, then `DSH_SHELL=1` plus `DSH_SESSION_ID`
## Bug Fixes
### Spec-injection YAML flow lists
`parse_simple_yaml` in `trellis_config.py` now parses scalar flow sequences such as `spec_injection.tools: []` and `tools: [Edit, Write]`. Nested `[]` / `{}` are still rejected.
### `task.py workflow`
`task.py workflow` imports `read_json` from `common.io`, so pinning a per-task workflow no longer raises `NameError`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No `--migrate` required.
# Contribute to Docs
Source: https://docs.trytrellis.app/contribute/docs
How to contribute to Trellis documentation (mindfold-ai/docs)
## Contribute with AI assistance
The easiest way to contribute is with Claude Code. We have a built-in skill that guides you through the process.
### Fork and clone
```bash theme={null}
# Fork on GitHub first, then:
git clone https://github.com/YOUR_USERNAME/docs.git
cd docs
pnpm install
```
### Tell Claude what you want to contribute
Open Claude Code in the project and describe what you want to add:
* "I want to add a new spec template for Next.js projects"
* "I want to improve the multi-agent documentation"
### Claude uses the contribute skill automatically
Claude will read the `contribute` skill and guide you through:
* Where to put your files
* What related files need updating (docs.json, index pages)
* Bilingual requirements (EN + ZH)
* How to test locally
### Review and submit PR
Review the changes, test with `pnpm dev`, push to your fork, then open a PR to the original repo.
<Tip>
The contribute skill knows the project structure and conventions. It handles the details so you
can focus on content.
</Tip>
***
## Ways to contribute
### Report issues
Found a problem with the docs? Open an issue:
[https://github.com/mindfold-ai/docs/issues](https://github.com/mindfold-ai/docs/issues)
Include:
* Which page has the issue
* What's wrong or confusing
* Suggested fix (if you have one)
### Suggest improvements
Have an idea for better docs? Open a discussion:
[https://github.com/mindfold-ai/docs/discussions](https://github.com/mindfold-ai/docs/discussions)
### Contribute a Skill
Skills extend AI capabilities. To add a new skill:
1. Fork the [Trellis repo](https://github.com/mindfold-ai/Trellis)
2. Create skill directory:
```
marketplace/skills/your-skill/
└── SKILL.md
```
3. Open a PR to the Trellis repo
4. (Optional) Create documentation pages in docs repo (`skills-market/your-skill.mdx` + Chinese version)
See [Claude Code Skills documentation](https://code.claude.com/docs/en/skills) for SKILL.md format.
<Note>Skills are hosted in the [Trellis main repo](https://github.com/mindfold-ai/Trellis), not in docs.</Note>
### Contribute a Spec Template
Spec templates are Trellis project guidelines (not Claude features). To add one:
1. Fork the repo
2. Create `marketplace/specs/your-template/` with guideline files
3. Create documentation pages (`templates/specs-your-template.mdx` + Chinese version)
4. Update `docs.json` navigation
5. Open a PR
Good contributions are:
* Specific and actionable
* Well-documented
* Tested on real projects
### Fix typos and improve clarity
Small fixes: edit directly on GitHub and submit a PR.
Larger changes: clone locally, make changes, test with `pnpm dev`.
***
## Development setup
```bash theme={null}
# Install dependencies
pnpm install
# Start local dev server
pnpm dev
# Check markdown lint
pnpm lint:md
# Verify docs structure
pnpm verify
# Format files
pnpm format
```
***
## Bilingual requirement
All user-facing content must have both English and Chinese versions:
| English | Chinese |
| ----------------------- | -------------------------- |
| `guides/example.mdx` | `zh/guides/example.mdx` |
| `templates/example.mdx` | `zh/templates/example.mdx` |
Update `docs.json` navigation for both languages.
***
## Commit messages
Use conventional commits:
```
docs: add Next.js spec template
fix: correct broken link in quickstart
feat: add new skill to marketplace
```
***
## PR process
1. Create a PR with a clear description
2. Ensure CI checks pass (lint, verify)
3. Wait for review
4. Address feedback
5. Merge after approval
***
## License
Contributions are licensed under MIT. By contributing, you agree to this.
## Questions?
Open a discussion or email [taosu@mindfold.ai](mailto:taosu@mindfold.ai).
# Contribute to Trellis
Source: https://docs.trytrellis.app/contribute/trellis
How to contribute to the Trellis project (mindfold-ai/Trellis)
# Contributing to Trellis
See the contribution guide on GitHub:
<Card title="CONTRIBUTING.md" icon="github" href="https://github.com/mindfold-ai/Trellis/blob/main/CONTRIBUTING.md">
English contribution guidelines
</Card>
# Showcase
Source: https://docs.trytrellis.app/showcase/index
<CardGroup>
<Card title="open-typeless" icon="microphone" href="/use-cases/open-typeless">
macOS voice input app, built in 1 day. Shows the full workflow: spec organization, task breakdown,
parallel development.
</Card>
<Card title="Trellis for Cursor" icon="cursor" href="/showcase/trellis-cursor">
Community fork optimized for Cursor with Chinese subagents and MCP integration.
</Card>
</CardGroup>
***
## Add your project
1. Fork the [docs repo](https://github.com/mindfold-ai/docs)
2. Copy `showcase/template.mdx` and `zh/showcase/template.mdx` to create bilingual pages
3. Add page paths to both EN and ZH showcase pages arrays in `docs.json`
4. Add Card to both `showcase/index.mdx` and `zh/showcase/index.mdx`
5. Open a PR
Use `/contribute` skill in Claude Code for assistance.
# open-typeless
Source: https://docs.trytrellis.app/showcase/open-typeless
# About
A macOS voice input app, built with Trellis in 1 day.
[](https://github.com/mindfold-ai/open-typeless)
## How it was built
Copied specs from an existing Electron project, AI filtered and organized them into 3 task batches. Current Trellis runs this style of work with native Git worktrees plus one session-scoped Trellis task per AI window.
# Workflow Demo
Source: https://docs.trytrellis.app/showcase/terminal-demo
See the full Trellis workflow in action: from brainstorm to ship
<div>
<div>
<div />
<div>
<div>
<div>
<div />
<div />
<div />
</div>
</div>
<div>
<div>
<span>❯ </span>
<span>New AI session</span>
</div>
<div>
<span>● </span>
Loaded: workflow, 3 active tasks, branch <span>feat/v0.5.0-rc</span>
</div>
<div>
<span>● </span>
What would you like to work on?
</div>
<div>
<span>❯ </span>
Add Gemini CLI support, similar to how Cursor is integrated
</div>
<div>
<span>● Bash</span>
<span>(task.py create "Gemini CLI support" --slug gemini-cli)</span>
</div>
<div>
<span>▶ </span>
<span>research</span>
<span>(Find platform integration specs and code patterns)</span>
</div>
<div>
└ Initializing...
</div>
<div>
└ Done <span>(36 tool uses · 86.5k tokens · 2m 25s)</span> <span>✓</span>
</div>
<div>
<span>● Bash</span>
<span>(task.py add-context ... platform-integration.md, cursor.ts, ai-tools.ts)</span>
</div>
<div>
└ 6 spec files added to <span>implement.jsonl</span>
</div>
<div>
<span>● Bash</span>
<span>(task.py start ...)</span>
<span>: hooks will inject context into agents</span>
</div>
<div>
<span>▶ </span>
<span>implement</span>
<span>(Implement Gemini CLI platform)</span>
</div>
<div>
└ Writing src/configurators/gemini.ts...
</div>
<div>
└ Done <span>(99 tool uses · 162.5k tokens · 12m 3s)</span> <span>✓</span>
</div>
<div>
<span>● </span>
TypeCheck <span>✓</span> · Lint <span>✓</span> · Tests: 337/337 <span>✓</span>
</div>
<div>
<span>▶ </span>
<span>check</span>
<span>(Review implementation against code-specs)</span>
</div>
<div>
└ Reading diff... 14 files changed
</div>
<div>
└ Found 1 issue: missing EXCLUDE\_PATTERNS entry
</div>
<div>
└ Fixed automatically <span>✓</span>
</div>
<div>
<span>❯ </span>
<span>Capture Gemini CLI conventions in specs</span>
</div>
<div>
<span>● Read</span>
<span>(.trellis/spec/backend/platform-integration.md)</span>
</div>
<div>
<span>● Update</span>
<span>(platform-integration.md)</span>
<span>: added Gemini CLI conventions</span>
</div>
<div>
<span>❯ </span>
<span>/trellis:finish-work</span>
</div>
<div>
<span>● Bash</span>
<span>(task.py archive gemini-cli)</span>
</div>
<div>
<span>● Bash</span>
<span>(add\_session.py --title "feat: Gemini CLI support" --commit "ec6114a")</span>
</div>
<div>
└ Task archived. Session recorded to <span>journal-4.md</span>.
</div>
<div>
<span>❯ </span>
<span />
</div>
</div>
</div>
<div>
<div />
<div />
<div title="Start" />
<div title="Describe" />
<div title="Research" />
<div title="Implement" />
<div title="Check" />
<div title="Update Spec" />
<div title="Ship" />
</div>
<div>
<div>
<p>Session loaded</p>
<p>AI reads your project context: workflow rules, active tasks, git status, and recent journal entries.</p>
</div>
<div>
<p>Natural language input</p>
<p>Describe your feature in plain language. Trellis creates a tracked task with a structured PRD.</p>
</div>
<div>
<p>Research & configure</p>
<p>trellis-research sub-agent finds relevant specs and code patterns. Context files configured in jsonl: hooks auto-inject them into agents.</p>
</div>
<div>
<p>Implement</p>
<p>Agent writes code across 5 layers following project conventions. 99 tool calls, all 337 tests pass on first try.</p>
</div>
<div>
<p>Quality check</p>
<p>trellis-check sub-agent reviews every changed file against code-specs. Issues found and fixed automatically.</p>
</div>
<div>
<p>Update specs</p>
<p>New patterns captured into the spec library: making future sessions even better.</p>
</div>
<div>
<p>Session archived</p>
<p>5 atomic commits, session recorded to journal. The branch is ready for review.</p>
</div>
</div>
</div>
</div>
***
## What just happened?
This demo replays a real Trellis session where we added **Gemini CLI platform support**: a feature touching types, templates, configurators, CLI flags, Python adapters, and documentation.
### The workflow
<Steps>
<Step title="Start session">
SessionStart hook or extension loads your project context: workflow rules, active tasks, git
status, and recent journal entries. The AI is immediately oriented.
</Step>
<Step title="Describe the feature">
You describe what you want in natural language. Trellis creates a tracked task with a structured
PRD.
</Step>
<Step title="Research & configure">
trellis-research sub-agent reads 36 files to find relevant specs and code patterns. Context
files are configured in jsonl so agents receive the right conventions via hooks.
</Step>
<Step title="Implement">
trellis-implement sub-agent writes code across 5 layers (types → templates → configurator → CLI
→ Python). 99 tool calls. All 337 tests pass on first try.
</Step>
<Step title="Quality check">
trellis-check sub-agent reviews every changed file against code-specs. Finds 1 missing
`EXCLUDE_PATTERNS` entry and fixes it automatically.
</Step>
<Step title="Update specs">
The `trellis-update-spec` skill captures new patterns learned from this session into the spec
library: making future sessions even better.
</Step>
<Step title="Finish & ship">
`/trellis:finish-work` archives the task and records the session to your journal. 5 atomic
commits on the feature branch, ready for review.
</Step>
</Steps>
### Key metrics
| Metric | Value |
| ----------------- | -------------------------------------------------------- |
| **Total time** | \~20 minutes |
| **Tool calls** | 169 (explore + research + implement + check) |
| **Files changed** | 14 TOML templates + 5 source files |
| **Tests** | 337/337 passed |
| **Commits** | 5 atomic commits |
| **Human input** | 3 messages (feature request + update-spec + finish-work) |
<Card title="Try it yourself" icon="rocket" href="/start/install-and-first-task">
Install Trellis, open a new AI session, and describe your feature request.
</Card>
# Trellis for Cursor
Source: https://docs.trytrellis.app/showcase/trellis-cursor
# About
Community fork optimized for Cursor with Chinese subagents and MCP integration. Based on Trellis v0.2.12.
[](https://github.com/jojolionss/Trellis)
## Key Features
* **Cursor Commands**: 13 slash commands in `.cursor/commands/` format
* **Chinese Localization**: All commands translated to Chinese
* **MCP Integration**: `trellis-context.*` tools for task management
* **Multi-model Support**: Specify models like `claude-4.5-opus-high-thinking`
# frontend-fullchain-optimization
Source: https://docs.trytrellis.app/skills-market/frontend-fullchain-optimization
Optimize frontend performance with a Web Vitals-driven diagnosis workflow
An evidence-first skill for diagnosing and improving frontend performance with
Web Vitals. It helps AI prioritize the right bottleneck, choose targeted fixes,
and verify whether a change actually improved user experience.
Use it when you need to optimize or review:
* slow page loads
* poor LCP, FCP, INP, CLS, TTFB, or TBT
* layout shifts and unstable rendering
* slow interactions caused by main-thread work
* image, font, or code-splitting regressions
## Why This Skill?
Most frontend performance work fails because teams optimize without enough
evidence or fix symptoms before upstream bottlenecks. This skill gives AI a
repeatable workflow:
1. Collect the minimum useful evidence
2. Identify the primary bottleneck
3. Pick the matching optimization branch
4. Re-measure when possible before claiming success
It supports both tool-rich and tool-light environments:
* **MCP-assisted mode** when Lighthouse or browser performance tooling is available
* **Manual-evidence mode** when you only have reports, traces, screenshots, or metric snapshots
By default, the workflow assumes Lighthouse and Performance evidence is
collected manually. If you do not have manual measurements yet, the skill should
only provide inferred suggestions and recommend follow-up verification after the
change.
## Install
```bash theme={null}
npx skills add mindfold-ai/marketplace --skill frontend-fullchain-optimization
```
Or install all available skills:
```bash theme={null}
npx skills add mindfold-ai/marketplace
```
Options:
| Flag | Description |
| ---------------- | -------------------------------------- |
| `-g` | Install globally (`~/.claude/skills/`) |
| `-a claude-code` | Target a specific agent |
| `-y` | Non-interactive mode |
## Verify Installation
Check if the skill is available:
```
What skills do you have access to?
```
Claude should list `frontend-fullchain-optimization` in the response.
## Usage
After installation, ask AI to analyze the current performance evidence:
```
Use frontend-fullchain-optimization to diagnose why this route has poor LCP and tell me what to fix first.
```
```
Review this Lighthouse report with frontend-fullchain-optimization and propose the smallest high-impact fix.
```
```
I only have DevTools screenshots and metric snapshots. Use frontend-fullchain-optimization in manual-evidence mode.
```
## What It Covers
| Area | Included guidance |
| ------------ | ------------------------------------------------------------------------------------------ |
| Metrics | LCP, FCP, INP, CLS, TTFB, and TBT thresholds and prioritization |
| Diagnosis | Primary bottleneck decision tree and required evidence checklist |
| Optimization | Rendering, images, fonts, code splitting, layout stability, and interaction responsiveness |
| Verification | Before/after template for documenting improvements and remaining bottlenecks |
## What's Included
| File | Contents |
| ---------- | ---------------------------------------------------------------------------------------------- |
| `SKILL.md` | The full performance workflow, metric playbooks, evidence checklist, and verification template |
# Overview
Source: https://docs.trytrellis.app/skills-market/index
Ready-to-use skills for Trellis
Skills extend Trellis with specialized knowledge and workflows. Current Trellis installs include built-in Trellis skills automatically, and marketplace skills remain available for compatibility and specialized domains.
Install marketplace skills with one command via [skills.sh](https://skills.sh):
```bash theme={null}
npx skills add mindfold-ai/marketplace
```
## Official Skills
| Skill | Description | Install |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| [trellis-meta](/skills-market/trellis-meta) | Customize and modify Trellis | Built in via `trellis init`; marketplace install for compatibility |
| [trellis-spec-bootstrap](/skills-market/trellis-spec-bootstrap) | Bootstrap project-specific Trellis specs from the real codebase | Bundled with Trellis |
| [frontend-fullchain-optimization](/skills-market/frontend-fullchain-optimization) | Diagnose and optimize frontend performance with Web Vitals | `npx skills add mindfold-ai/marketplace -s frontend-fullchain-optimization` |
| [mem-recall](/skills-market/mem-recall) | Recall past AI conversations across Claude / Codex / OpenCode / Pi via `trellis mem` | `npx skills add mindfold-ai/marketplace -s mem-recall` |
## Community Skills
Coming soon.
# mem-recall
Source: https://docs.trytrellis.app/skills-market/mem-recall
Cross-platform AI conversation recall via trellis mem
mem-recall makes the AI invoke `trellis mem` whenever the user references past conversations, retrieve content from local Claude Code, Codex, Devin CLI, Grok, OpenCode, Pi and ZCode session stores, and answer with session-id + verbatim quotation.
Trigger phrases include `last time`, `we discussed`, `what did I tell <Claude/Codex>`, `find ... last week`, `上次`, `之前`, and other references to prior dialogue.
Without the skill, the AI defaults to "I don't have that context" or speculative answers. The skill's frontmatter `description` field instructs the AI to run `trellis mem` in these cases, with a `search` → `context` two-step retrieval flow.
## Prerequisites
| Tool | Purpose | Required |
| ----------------------------------------------------------------------- | ----------------------- | ------------ |
| [Trellis CLI](https://github.com/mindfold-ai/Trellis) **0.6.0-beta.0+** | Provides `trellis mem` | Required |
| Claude Code, Codex CLI, Devin CLI, Grok, OpenCode, Pi, ZCode | Source of past sessions | At least one |
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis --version # ≥ 0.6.0-beta.0
```
## Install
```bash theme={null}
npx skills add mindfold-ai/marketplace --skill mem-recall
```
Or install all marketplace skills:
```bash theme={null}
npx skills add mindfold-ai/marketplace
```
| Flag | Description |
| ---------------- | --------------------------------------- |
| `-g` | Install globally to `~/.claude/skills/` |
| `-a claude-code` | Target a specific agent |
| `-y` | Non-interactive mode |
Ask the AI which skills are available; `mem-recall` should appear in the list.
## Trigger examples
No manual command needed. The following user messages trigger the skill:
* last time how did we solve the wait\_agent deadlock in #240?
* which project did I discuss the plugin design in?
* find what I told Claude about memory architecture last week
* 上次我们怎么处理 #240 的来着？
## Retrieval flow
The skill instructs the AI to execute two steps.
**Step 1 — Candidate search**
```bash theme={null}
trellis mem search "<keyword>" [--cwd <project>] [--since <date>]
```
Multi-token AND search across cleaned dialogue. Returns ranked sessions. Score formula: `(3 × user_hits + assistant_hits) / total_turns`. User-turn hits are weighted ×3 because user wording reflects topic intent more strongly than AI elaboration.
**Step 2 — Content extraction**
```bash theme={null}
trellis mem context <session-id> --grep <keyword> --turns 3 --around 1
```
Returns the top-N hit turns plus surrounding context. Default character budget ≤6000, adjustable via `--max-chars`.
## Cleaning before search
`trellis mem` strips the following before searching, so hits reflect actual dialogue:
* prompt injections: `<system-reminder>`, `<workflow-state>`, `<INSTRUCTIONS>`, `<environment_context>`, etc.
* Codex AGENTS.md preamble (first user message is dropped entirely)
* tool calls and tool results (only `text` blocks retained)
Turns from before a compaction are kept, with a marker showing where the compaction happened. Content the platform does not store in readable form is reported instead of silently dropped: Codex encrypts messages between agents, and Grok keeps pre-compaction turns as rendered markdown.
## Data sources
Reads local files directly. No daemon, no index, no upload.
| Platform | Storage |
| ----------- | ----------------------------------------------------------------------------------------------- |
| Claude Code | `~/.claude/projects/<sanitized-cwd>/*.jsonl` |
| Codex | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` |
| Devin CLI | `~/.local/share/devin/cli/sessions.db` (`--platform devin`; not `trellis init --devin` Desktop) |
| OpenCode | `~/.local/share/opencode/opencode.db` |
| Pi | `~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<id>.jsonl` |
| Grok | `~/.grok/sessions/<url-encoded-cwd>/<session-id>/chat_history.jsonl` |
## Out-of-scope use cases
| Need | Tool |
| --------------------------------- | ---------------- |
| Search code | `Grep` / `Read` |
| Search commit history | `git log` / `gh` |
| Search current-project files/docs | `Read` / `Glob` |
mem-recall is for AI conversation history only, not file or code search.
## Performance
| Scope | Time |
| ---------------------------- | ------- |
| Project-scoped 3-week search | \~0.85s |
| Global, no time filter | \~3s |
Stateless. Each invocation cold-reads from disk; OS page cache absorbs IO so warm and cold runs perform similarly.
# trellis-meta
Source: https://docs.trytrellis.app/skills-market/trellis-meta
The essential skill for customizing Trellis
The official meta-skill for understanding and customizing Trellis. Current Trellis projects get this skill automatically from `trellis init`, so AI can help you:
* Add specialized agents for your workflow
* Change how context gets injected
* Add project-specific commands
* Adapt local `.trellis/` and platform files to your project
## Install
Works with all Trellis platform skill roots: Claude Code, Cursor, OpenCode, Codex, Kilo, Kiro, Gemini CLI, Antigravity, Devin, Qoder, CodeBuddy, GitHub Copilot, Factory Droid, and Pi Agent.
For Trellis-managed projects, initialize or update the platform you use:
```bash theme={null}
trellis init --claude
trellis init --codex
trellis update
```
`trellis init` writes `trellis-meta` into the selected platform's skill directory and `trellis update` keeps it hash-tracked with the rest of the built-in templates.
For non-Trellis projects or older Trellis installs, use the marketplace compatibility path:
```bash theme={null}
npx skills add mindfold-ai/marketplace --skill trellis-meta
```
Or install all available skills:
```bash theme={null}
npx skills add mindfold-ai/marketplace
```
Options:
| Flag | Description |
| ---------------- | -------------------------------------- |
| `-g` | Install globally (`~/.claude/skills/`) |
| `-a claude-code` | Target a specific agent |
| `-y` | Non-interactive mode |
## Verify Installation
Check if the skill is available:
```
What skills do you have access to?
```
Your AI tool should list `trellis-meta` in the response.
## Usage
After installation, tell AI what you want:
```
I want to add a deploy agent to handle deployment workflow
```
```
Help me modify the check hook to add a custom verification command
```
```
I want to add a new workflow phase called review
```
AI will automatically use the skill's documentation and give you the correct modification steps.
## What's Included
| Directory | Contents |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `local-architecture/` | How local `.trellis/` workflow, tasks, specs, workspace, scripts, and context injection fit together |
| `platform-files/` | How platform settings, hooks, agents, skills, commands, prompts, and workflows connect to Trellis |
| `customize-local/` | How to modify generated local files for workflow, task lifecycle, context loading, hooks, agents, skills, commands, and specs |
# trellis-spec-bootstrap
Source: https://docs.trytrellis.app/skills-market/trellis-spec-bootstrap
Bootstrap project-specific Trellis coding specs from the real codebase
`trellis-spec-bootstrap` helps an AI create or refresh `.trellis/spec/` guidelines from the actual repository. It is platform-neutral: one capable agent can analyze the codebase, choose the spec boundaries, write the docs, and verify that no placeholder text remains.
## When to Use It
Use this skill after `trellis init` when the default spec templates exist but still need project-specific content.
Good fits:
* New projects that need first-pass Trellis coding specs
* Existing projects where `.trellis/spec/` is still generic
* Repositories where the spec boundaries should follow real package or layer boundaries
* Teams that want source-backed rules instead of boilerplate advice
## Availability
`trellis-spec-bootstrap` is bundled with Trellis. After installing or updating Trellis, use the skill directly; there is no extra marketplace download step.
The beta bundle includes this skill now. The docs also mention it on the release track so the same workflow is visible there once the release bundle includes the matching skill.
## Usage
After installation, ask the AI to bootstrap or refresh specs:
```text theme={null}
Use trellis-spec-bootstrap to fill the Trellis specs for this project from the real codebase.
```
```text theme={null}
Refresh .trellis/spec so it reflects the current repository structure and coding patterns.
```
## How It Works
1. Inspect the existing `.trellis/spec/` tree.
2. Analyze repository architecture with GitNexus, ABCoder, language tooling, or direct source reads.
3. Choose spec boundaries that match the actual codebase.
4. Fill or reshape spec files with concrete file paths, examples, and anti-patterns.
5. Verify that index files match the final spec set and no template placeholders remain.
## Included References
| File | Contents |
| ----------------------------------- | -------------------------------------- |
| `SKILL.md` | Main workflow and operating rules |
| `references/repository-analysis.md` | How to inspect repository architecture |
| `references/spec-task-planning.md` | How to decompose spec work |
| `references/spec-writing.md` | How to write high-signal Trellis specs |
| `references/mcp-setup.md` | GitNexus and ABCoder setup notes |
# Cloudflare Workers + Hono + Turso
Source: https://docs.trytrellis.app/templates/specs-cf-workers
Full-stack spec template for Cloudflare Workers apps with Hono framework and Turso database
A complete coding convention template for production Cloudflare Workers applications with Hono framework, Drizzle ORM, and Turso edge database.
<Card title="Download Template" icon="download" href="https://download-directory.github.io/?url=https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/cf-workers-fullstack">
Download as ZIP and extract to `.trellis/spec/`
</Card>
## What's Included
| Category | Files | Coverage |
| -------- | ------------------ | ---------------------------------------------------- |
| Backend | 11 files | Hono, Drizzle/Turso, API patterns, security, storage |
| Frontend | 7 files + examples | Components, hooks, auth, design templates |
| Shared | 5 files | TypeScript, code quality, dependencies, timestamps |
| Guides | 3 files | OAuth consent flow, serverless connections |
| Pitfalls | 6 files | Workers compat, cross-layer, env config, CSS |
## Template Structure
```
spec/
├── backend/
│ ├── index.md
│ ├── hono-framework.md
│ ├── database.md
│ ├── api-module.md
│ ├── api-patterns.md
│ ├── security.md
│ ├── storage.md
│ └── ...
│
├── frontend/
│ ├── index.md
│ ├── authentication.md
│ ├── components.md
│ ├── hooks.md
│ ├── directory-structure.md
│ ├── examples/frontend-design/
│ └── ...
│
├── guides/
│ ├── oauth-consent-flow.md
│ ├── serverless-connection-guide.md
│ └── ...
│
├── shared/
│ ├── typescript.md
│ ├── code-quality.md
│ ├── dependency-versions.md
│ └── ...
│
├── big-question/
│ ├── workers-nodejs-compat.md
│ ├── cross-layer-contract.md
│ ├── env-configuration.md
│ └── ...
│
└── README.md
```
## Key Topics
### Backend
* Hono framework patterns (type-safe bindings, middleware, WebSocket)
* Drizzle ORM + Turso/libSQL (batch ops, N+1 prevention, Workers pitfalls)
* Cloudflare storage (R2, KV, Cache API for session caching)
* Security (token generation, timing-safe comparison, OAuth redirect validation)
* Structured JSON logging with request context
### Frontend
* React 19 + React Router v7 with Vite
* Better Auth UI v3.x integration (SSR-safe, Cloudflare Workers considerations)
* shadcn/ui components + Tailwind CSS v4
* Design example templates (minimalist hero, maximalist dashboard, animations)
### Guides
* OAuth 2.1 consent flow with resource selection
* Serverless connection debugging (stale connections, subrequest limits)
### Common Pitfalls
* Workers Node.js compatibility (`nodejs_compat` flag)
* Cross-layer contract violations (data flows but never reaches client)
* Build-time vs runtime environment variables
* CSS debugging in Tailwind v4
## Usage
1. Download the ZIP file
2. Extract to your project's `.trellis/spec/` directory
3. Replace generic env var names with your actual bindings
4. Customize for your specific conventions
5. Remove sections that don't apply
<Card title="View on GitHub" icon="github" href="https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/cf-workers-fullstack">
Browse the template source code
</Card>
# Electron + React + TypeScript
Source: https://docs.trytrellis.app/templates/specs-electron
Full-stack spec template for Electron desktop apps with React frontend
A complete coding convention template for Electron applications with React frontend and TypeScript.
<Card title="Download Template" icon="download" href="https://download-directory.github.io/?url=https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/electron-fullstack">
Download as ZIP and extract to `.trellis/spec/`
</Card>
## What's Included
| Category | Files | Coverage |
| -------- | -------- | -------------------------------------- |
| Frontend | 11 files | Components, hooks, state, IPC, CSS |
| Backend | 14 files | API patterns, database, error handling |
| Guides | 8 files | Cross-layer thinking, debugging |
| Shared | 6 files | TypeScript, git, code quality |
## Template Structure
```
spec/
├── frontend/
│ ├── index.md
│ ├── components.md
│ ├── hooks.md
│ ├── state-management.md
│ ├── ipc-electron.md
│ └── ...
│
├── backend/
│ ├── index.md
│ ├── api-patterns.md
│ ├── database.md
│ ├── error-handling.md
│ └── ...
│
├── guides/
│ ├── cross-layer-thinking-guide.md
│ ├── bug-root-cause-thinking-guide.md
│ └── ...
│
├── shared/
│ ├── typescript.md
│ ├── git-conventions.md
│ └── ...
│
└── README.md
```
## Key Topics
### Frontend
* React component patterns and hooks
* Electron IPC communication
* State management with Zustand
* CSS design system
### Backend
* API module structure
* SQLite database patterns
* Error handling and logging
* macOS permissions
### Guides
* Cross-layer thinking for full-stack changes
* Bug root cause analysis
* Database schema migrations
## Usage
1. Download the ZIP file
2. Extract to your project's `.trellis/spec/` directory
3. Customize for your specific conventions
4. Remove sections that don't apply
5. Update examples to match your codebase
<Card title="View on GitHub" icon="github" href="https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/electron-fullstack">
Browse the template source code
</Card>
# Overview
Source: https://docs.trytrellis.app/templates/specs-index
Coding convention templates for common tech stacks
Spec templates help you quickly set up coding guidelines for your project. Download, customize, use.
<Info>
**Specs are meant to be customized.** Trellis ships with empty spec templates by default — they are placeholders for *your* project's conventions. Every team's stack, patterns, and quality bar are different, so the specs you write should reflect your actual codebase, not generic best practices. Templates from the marketplace give you a head start, but always tailor them to your project.
</Info>
## Available Templates
| Template | Stack | Description |
| ---------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------- |
| [Electron + React + TypeScript](https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/electron-fullstack) | Full-stack | Electron desktop app with React frontend |
| [Next.js + oRPC + PostgreSQL](https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/nextjs-fullstack) | Full-stack | Next.js app with oRPC API and PostgreSQL |
| [CF Workers + Hono + Turso](https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/cf-workers-fullstack) | Full-stack | Cloudflare Workers with Hono and Turso |
<CardGroup>
<Card title="Download Electron Template" icon="download" href="https://download-directory.github.io/?url=https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/electron-fullstack">
Electron + React + TypeScript (50 files)
</Card>
<Card title="Download Next.js Template" icon="download" href="https://download-directory.github.io/?url=https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/nextjs-fullstack">
Next.js + oRPC + PostgreSQL (35 files)
</Card>
<Card title="Download CF Workers Template" icon="download" href="https://download-directory.github.io/?url=https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/cf-workers-fullstack">
CF Workers + Hono + Turso (38 files)
</Card>
</CardGroup>
## Template Marketplace <sup>v0.3.6</sup>
Starting from v0.3.6, you can fetch spec templates directly from any Git repository using the `--registry` flag:
```bash theme={null}
# Fetch from a custom registry
trellis init --registry https://github.com/your-org/your-spec-templates
# Combine with platform flags
trellis init --registry https://github.com/your-org/your-spec-templates --cursor -u your-name
```
### How it works
Trellis auto-detects two modes:
* **Marketplace mode**: If the repository contains a `marketplace/index.json` file, Trellis reads the template index and lets you pick which template to install
* **Direct download mode**: If no `index.json` is found, Trellis treats the entire `marketplace/specs/` directory as a single template and downloads it directly
### Publishing your own templates
To create a spec template registry that others can use with `--registry`:
1. Create a Git repository (GitHub, GitLab, or Bitbucket)
2. Add a `marketplace/` directory with your spec templates
3. Create `marketplace/index.json` to list available templates:
```json theme={null}
{
"version": 1,
"templates": [
{
"id": "my-stack",
"type": "spec",
"name": "My Stack Template",
"description": "Conventions for our tech stack",
"path": "marketplace/specs/my-stack",
"tags": ["react", "node", "typescript"]
}
]
}
```
4. Inside each template path, place your spec files following the standard structure (see below)
5. Share the repository URL — users install with `trellis init --registry <url>`
## Template Structure
Each template follows this structure:
```
spec/
├── frontend/ # Frontend guidelines
│ ├── index.md # Navigation index
│ ├── components.md # Component patterns
│ ├── hooks.md # Hook conventions
│ └── state-management.md
│
├── backend/ # Backend guidelines
│ ├── index.md
│ └── ...
│
├── guides/ # Thinking guides
│ ├── index.md
│ └── ...
│
└── README.md # Template overview
```
## How to Use
1. Download the template ZIP or use `trellis init --registry`
2. Extract to `.trellis/spec/` in your project
3. Customize for your project's specific conventions
4. Remove sections that don't apply
5. Update paths and examples to match your codebase
<Tip>
You don't have to fill every spec file at once. Start with the areas that matter most to your project, then expand over time. The bootstrap task created by `trellis init` will guide you through the initial fill.
</Tip>
## Contributing Templates
Want to share your specs with the community? Create a repository with your templates and open a PR to add it to the [official template registry](https://github.com/mindfold-ai/Trellis/tree/main/marketplace).
# Next.js + oRPC + PostgreSQL
Source: https://docs.trytrellis.app/templates/specs-nextjs
Full-stack spec template for Next.js applications with oRPC API layer and PostgreSQL
A complete coding convention template for production Next.js applications with oRPC API layer, Drizzle ORM, and PostgreSQL.
<Card title="Download Template" icon="download" href="https://download-directory.github.io/?url=https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/nextjs-fullstack">
Download as ZIP and extract to `.trellis/spec/`
</Card>
## What's Included
| Category | Files | Coverage |
| -------- | -------- | ------------------------------------------------- |
| Frontend | 12 files | Components, hooks, state, oRPC, AI SDK, CSS |
| Backend | 10 files | oRPC router, database, auth, performance, logging |
| Guides | 3 files | Cross-layer thinking, pre-implementation |
| Shared | 4 files | TypeScript, code quality, dependencies |
| Pitfalls | 5 files | PostgreSQL, build system, mobile CSS |
## Template Structure
```
spec/
├── frontend/
│ ├── index.md
│ ├── components.md
│ ├── hooks.md
│ ├── state-management.md
│ ├── orpc-usage.md
│ ├── authentication.md
│ ├── ai-sdk-integration.md
│ └── ...
│
├── backend/
│ ├── index.md
│ ├── orpc-usage.md
│ ├── database.md
│ ├── authentication.md
│ ├── performance.md
│ └── ...
│
├── guides/
│ ├── pre-implementation-checklist.md
│ ├── cross-layer-thinking-guide.md
│ └── ...
│
├── shared/
│ ├── typescript.md
│ ├── code-quality.md
│ ├── dependencies.md
│ └── ...
│
├── big-question/
│ ├── postgres-json-jsonb.md
│ ├── sentry-nextintl-conflict.md
│ └── ...
│
└── README.md
```
## Key Topics
### Frontend
* Next.js 15 App Router with React 19
* oRPC client + React Query integration
* Server Components vs Client Components
* Authentication with better-auth
* Vercel AI SDK (useChat, tool calls, streaming)
* TailwindCSS 4 + Radix UI patterns
### Backend
* oRPC router, procedures, and middleware
* Drizzle ORM + PostgreSQL (N+1 prevention, transactions, JSON/JSONB)
* better-auth server configuration
* Performance patterns (concurrency, caching, rate limiting)
* Structured logging with Sentry
### Guides
* Pre-implementation checklist (search before write)
* Cross-layer thinking for Next.js full-stack changes
### Common Pitfalls
* PostgreSQL `json` vs `jsonb` with Drizzle ORM
* Sentry + next-intl plugin conflict
* Turbopack vs Webpack flexbox differences
* WebKit tap highlight on mobile
## Usage
1. Download the ZIP file
2. Extract to your project's `.trellis/spec/` directory
3. Replace `@your-app/*` placeholders with your monorepo package paths
4. Customize for your specific conventions
5. Remove sections that don't apply
<Card title="View on GitHub" icon="github" href="https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/nextjs-fullstack">
Browse the template source code
</Card>
# open-typeless
Source: https://docs.trytrellis.app/use-cases/open-typeless
Step-by-step guide: Building a macOS voice input app with Trellis
# open-typeless
A step-by-step tutorial showing how to use Trellis to build a macOS voice input app from scratch.
<Info>
**Source Code**:
[github.com/mindfold-ai/open-typeless](https://github.com/mindfold-ai/open-typeless)
</Info>
## Project Initialization
### Create Electron Project
```bash theme={null}
npx create-electron-app@latest open-typeless --template=vite-typescript
cd open-typeless
# Remove npm generated files
rm -rf node_modules package-lock.json
# Create .npmrc (required for pnpm + Electron)
cat > .npmrc << 'EOF'
node-linker=hoisted
shamefully-hoist=true
EOF
# Reinstall with pnpm
pnpm install
```
### Initialize Trellis
```bash theme={null}
trellis init
```
<img alt="trellis init" />
### Copy Specs from Existing Project
If you have specs from a similar project, copy them over:
```bash theme={null}
cp -r /path/to/old-project/.trellis/spec ./
```
### Ask AI to Fill in Specs
**Prompt:**
> Help me select useful specs from electron-doc/ and organize them into this project's .trellis/spec/
AI will analyze and organize specs:
<img alt="spec selection" />
## Task Planning
### Ask AI to Plan Tasks
**Prompt:**
> I want to use Volcengine ASR BigModel API to build this. Help me plan how to break down the tasks.
AI creates a batch-based task plan:
<img alt="task planning" />
### Create Tasks
AI creates tasks organized into batches:
| Batch | Tasks | Purpose |
| ------- | -------------------------------------------------------------------- | -------------------------------- |
| Batch 1 | `asr-infrastructure` | Foundation (must complete first) |
| Batch 2 | `asr-audio-recorder`, `asr-volcengine-client`, `asr-floating-window` | Can run in parallel |
| Batch 3 | `asr-integration` | Integration (depends on Batch 2) |
<img alt="tasks created" />
### Complete Batch 1
After Batch 1 completes, verify and update downstream task contexts:
<img alt="batch 1 complete" />
## Parallel Development
### Start Parallel Sessions
For current Trellis, create one Git worktree and one AI session for each Batch 2 task, then start the matching Trellis task inside that session.
```bash theme={null}
git worktree add ../asr-audio-recorder -b feature/asr-audio-recorder
git worktree add ../asr-volcengine-client -b feature/asr-volcengine-client
git worktree add ../asr-floating-window -b feature/asr-floating-window
```
Each session has its own active-task pointer, so starting a task in one session does not affect the others.
<img alt="parallel agents" />
## Monitor Progress
### Check Agent Status
AI monitors agent status and task progress:
<img alt="agent status" />
### Record Session
After parallel sessions complete, review and merge each branch through your normal Git process:
<img alt="parallel PRs" />
After merging and completing a batch, record the session:
**Prompt:** `/trellis:finish-work`
<img alt="record session" />
## Continue Development
### Check Remaining Tasks
AI shows remaining tasks in the current project:
<img alt="task list" />
### Implement Next Feature
Select the next task, AI uses trellis-implement sub-agent then trellis-check sub-agent:
<img alt="implement and check" />
### Configure and Test
AI helps with remaining setup (environment config, permissions):
<img alt="final setup" />
## Summary
Using Trellis to build open-typeless:
| Step | What | Trellis Feature |
| ---- | -------------------- | --------------------------------------------------- |
| 1 | Initialize project | `trellis init`, spec organization |
| 2 | Plan tasks | AI task breakdown, batch planning |
| 3 | Parallel development | Native Git worktrees + session-scoped Trellis tasks |
| 4 | Monitor & record | `/trellis:finish-work` |
| 5 | Continue iterating | Task hooks, implement/trellis-check sub-agents |
**Result:** Complete Electron app in 1 day, with structured specs and documented progress.
# v0.1.9
Source: https://docs.trytrellis.app/changelog/v0.1.9
2026-01-10
Renamed some slash commands.
## Changes
| Old | New |
| ---------------------- | ------------------- |
| `onboard-developer.md` | `onboard.md` |
| `record-agent-flow.md` | `record-session.md` |
# v0.2.0
Source: https://docs.trytrellis.app/changelog/v0.2.0
2026-01-15
Comprehensive naming redesign for clarity.
## Changes
| Old | New | Description |
| ------------------ | --------------- | ---------------------- |
| `agent-traces/` | `workspace/` | Developer work records |
| `structure/` | `spec/` | Development guidelines |
| `backlog/` | `tasks/` | Task tracking |
| `.current-feature` | `.current-task` | Current task pointer |
| `feature.sh` | `task.sh` | Task management script |
# v0.3.0-beta.0
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.0
2026-01-25
**BREAKING**: Shell to Python migration + Command namespace changes.
## Shell Scripts to Python
All `.sh` scripts replaced by `.py` equivalents. Requires Python 3.10+.
| Old | New |
| ------------------------------- | ------------------------------- |
| `.trellis/scripts/*.sh` | `.trellis/scripts/*.py` |
| `.trellis/scripts/multi-agent/` | `.trellis/scripts/multi_agent/` |
| `./script.sh` | `python3 ./script.py` |
## Command Namespace
Commands moved to namespaced paths:
| Platform | Old | New |
| ----------- | --------------------------- | ----------------------------------- |
| Claude Code | `.claude/commands/start.md` | `.claude/commands/trellis/start.md` |
| Cursor | `.cursor/commands/start.md` | `.cursor/commands/trellis-start.md` |
Run `trellis update --migrate` to apply changes.
# v0.3.0-beta.10
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.10
2026-01-23
Windows UTF-8 encoding fix.
## Changes
* Fixed UnicodeEncodeError and SyntaxWarning on Windows
* Added UTF-8 encoding declarations and Windows stdout handling in hooks
# v0.3.0-beta.11
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.11
2026-01-23
Bug fix for Windows UTF-8 encoding in hooks.
## Changes
* Fixed remaining Windows UTF-8 encoding issues in hook scripts
# v0.3.0-beta.12
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.12
2026-01-24
Windows compatibility and multi-model dispatch improvements.
## Changes
* Fixed Windows hook JSON parse error caused by backslash characters in templates
* Fixed cross-platform script paths for Python command
* Fixed multi-agent dispatch prompt for GPT/Codex model compatibility
# v0.3.0-beta.13
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.13
2026-01-25
Cursor platform support and base branch auto-recording.
## Changes
* Added Cursor as supported platform alongside Claude Code and OpenCode
* Auto-record `base_branch` on task creation for correct PR targeting
* Added `set-base-branch` command
# v0.3.0-beta.14
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.14
2026-01-26
Fix update error for 0.2.x users.
## Changes
* Fixed "path argument must be of type string" error when upgrading from 0.2.x
* Added missing manifests for 0.2.12, 0.2.13, and earlier beta versions
# v0.3.0-beta.15
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.15
2026-01-27
Add cli\_adapter.py to update system.
## Changes
* Added missing `cli_adapter.py` to template files in update mechanism
# v0.3.0-beta.16
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.16
2026-01-28
iFlow CLI support and update mechanism fix.
## Changes
* Added iFlow CLI platform support
* Fixed Windows stdout encoding in iFlow hooks
* Update mechanism now only updates configured platforms
# v0.3.0-beta.7
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.7
2026-01-30
Windows compatibility fixes and hook JSON format corrections.
## Changes
* Fixed Claude Code hook JSON output format (Issue #18)
* Added UTF-8 encoding for git commands (Issue #19)
* Cross-platform `tail_follow()` implementation in status.py
* Hook commands now use `python3` directly
> **Windows Users**: If your system uses `python` instead of `python3`, manually update `.claude/settings.json` to change `python3` to `python`.
# v0.3.0-beta.8
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.8
2026-01-31
Task commands now support task name lookup. You can use `python3 task.py start my-task` instead of the full path `python3 task.py start .trellis/tasks/01-31-my-task`.
## Changes
* Simplified task command syntax
* No migration required
# v0.3.0-beta.9
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.9
2026-01-22
OpenCode platform support with agents, commands, and plugins.
## Changes
* Added OpenCode platform with agents, commands, and plugin support
* Session ID extraction and resume capability
# v0.3.0-rc.0
Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.0
2026-02-06
Major internal refactor with centralized platform registry, remote spec templates, and comprehensive test coverage.
## New features
* **Remote spec templates**: `trellis init -t electron-fullstack` downloads and applies spec templates
* **Centralized platform registry**: All platform metadata in one place, derived helpers replace scattered hardcoded lists
* **Test coverage**: 312 tests across 17 files with Vitest coverage reporting
## Changes
* Extracted `resolvePlaceholders()` to shared module, removed templates.ts dispatcher
* Release tooling supports beta/rc/release workflows
* Extracted VERSION constant for consistent version management
# v0.3.0-rc.1
Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.1
2026-02-07
Fix CLI version comparison for prerelease versions.
## Changes
* Fixed rc version comparison (`0.3.0-rc.0` was incorrectly sorted below `0.3.0-beta.16`)
* Deduplicated `compareVersions()` across 3 modules into shared `utils/compare-versions.ts`
# v0.3.0-rc.2
Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.2
2026-02-09
Codex platform integration.
## New features
* **Codex platform**: `trellis init --codex` sets up OpenAI Codex CLI with skill templates
* Extended Python runtime (`cli_adapter.py`) to support Codex platform detection
## Changes
* Full test suite passing with coverage
* Codex uses skills pattern (`SKILL.md`) instead of slash commands
# v0.3.0-rc.3
Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.3
2026-02-15
Code-spec enforcement and robustness fixes.
## Changes
* Fixed table separator matching in `add_session.py` to tolerate formatted markdown
* Fixed Codex skill templates (replaced `/trellis:` with `$` syntax, removed Claude-specific references)
* Enforced code-spec depth requirements across all platform templates
# v0.3.0-rc.4
Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.4
2026-02-19
Active spec sync in finish agent.
## Changes
* Finish agent now actively syncs spec docs during pipeline runs
* Injected `update-spec.md` into finish context across Claude, iFlow, and OpenCode
* Restored code-spec enforcement in Codex skill templates
# v0.3.0-rc.5
Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.5
2026-02-24
Brainstorm command templates for all platforms.
## New features
* **Brainstorm command**: `/trellis:brainstorm` added to all 5 platform templates (Claude, iFlow, OpenCode, Cursor, Codex) for interactive requirements discovery
## Changes
* Added brainstorm workflow references to start commands across iFlow, OpenCode, Cursor, and Codex (matching existing Claude start.md)
## Migration
No migration required. Run `trellis update` to get the latest templates.
# v0.3.0-rc.6
Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.6
2026-02-26
4 new platforms — Trellis now supports 8 AI coding tools.
## New platforms
* **Kilo CLI**: Commands-only platform with subdirectory namespacing (`.kilocode/commands/trellis/`)
* **Kiro Code**: Skills-based platform (`.kiro/skills/`)
* **Gemini CLI**: First TOML-format command platform (`.gemini/commands/trellis/*.toml`)
* **Antigravity**: Workflow-based platform adapted from Codex skills (`.agent/workflows/`)
## Bug fixes
* Fixed non-existent `spec/shared/` references in init-context defaults
* Fixed iFlow start/finish-work template content
* Corrected license badge from FSL to AGPL-3.0
* Fixed start process flow
## Tests
* Added 50+ new tests covering all 4 new platforms (templates, configurators, init integration, regression)
## Migration
No migration required. Run `trellis init --kilo`, `--kiro`, `--gemini`, or `--antigravity` to add new platform support.
# v0.3.1
Source: https://docs.trytrellis.app/changelog/v0.3.1
2026-03-02
SessionStart reinject on clear/compact and spec template project-type awareness.
## Enhancements
* **SessionStart reinject**: Hook now fires on `clear` and `compact` events in addition to `startup` — ensures context is always re-injected after session reset (Claude + iFlow)
* **New slash command**: Added `/trellis:create-manifest` to guide AI through the full manifest creation flow
## Bug fixes
* Fixed iFlow command templates writing to wrong path (`.iflow/commands/` → `.iflow/commands/trellis/`)
* Fixed `trellis update` injecting spec files for non-existent backend/frontend directories
* Fixed `trellis init` creating all spec directories regardless of project type (now respects `projectType`)
* Removed dead `guidesCrossPlatformThinkingGuideContent` export and broken links in guides index
## Migration
No migration required. Run `trellis update` to sync template changes.
# v0.3.10
Source: https://docs.trytrellis.app/changelog/v0.3.10
2026-03-12
Bug fixes for registry URL handling and AI model compatibility.
## Bug Fixes
* **HTTPS registry URLs** — `trellis init --registry` now accepts HTTPS URLs (e.g. `https://github.com/user/repo`) by auto-converting them to giget-style format. Supports GitHub, GitLab, and Bitbucket, including `/tree/branch/path` URLs and `.git` suffix. (#87)
* **Record-session AI compatibility** — Updated the record-session command wording across all 9 platforms. AI models (especially GPT) previously refused to run `add_session.py` because the old "AI must NOT execute git commit" instruction was too absolute. The new wording clarifies that scripts handling `.trellis/` metadata commits are safe to execute. (#88)
# v0.3.2
Source: https://docs.trytrellis.app/changelog/v0.3.2
2026-03-03
Auto-commit workspace changes after record-session and project-level configuration.
## Enhancements
* **Auto-commit workspace changes**: `add_session.py` now automatically commits `.trellis/workspace` changes after recording a session — keeps the working directory clean
* **Project-level config**: New `.trellis/config.yaml` for customizing `session_commit_message` and `max_journal_lines`
* **Config reader module**: New `common/config.py` reads config.yaml with hardcoded fallback defaults
* **Skip auto-commit**: Added `--no-commit` flag to `add_session.py` for cases where you don't want automatic commits
* **Template updates**: All 8 platform record-session templates updated with auto-commit documentation
## Migration
No migration required. Run `trellis update` to sync new files (`config.yaml`, `config.py`) and updated templates.
# v0.3.3
Source: https://docs.trytrellis.app/changelog/v0.3.3
2026-03-04
Init download UX improvements, update spec protection, and Windows encoding fixes.
## Enhancements
* **Proxy detection**: Automatically detects `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` environment variables and configures undici ProxyAgent for all network calls (including giget template downloads)
* **Download timeout with countdown**: Template index fetch has a 5s timeout with live `Loading... 2s/5s` countdown; template downloads have a 30s timeout via `Promise.race`
* **Source URL display**: Shows the GitHub URL being fetched during `trellis init` template selection
* **Retry hint**: On download failure, suggests `trellis init --template <name>` for manual retry
* **Eliminate double-fetch**: Pre-fetched `SpecTemplate` is passed to `downloadTemplateById` to avoid fetching the index twice
* **Update skips spec directory**: `trellis update` no longer touches `.trellis/spec/` — user-customized spec content is fully protected
* **Update proxy support**: `trellis update` sets up proxy before npm version check
## Bug Fixes
* **Windows stdin UTF-8**: Centralized stdio encoding in `common/__init__.py` — adds `sys.stdin` to `_configure_stream()` to fix garbled Chinese text when piping content via stdin on Windows PowerShell
* **Remove inline encoding**: Removed duplicated encoding code from `add_session.py` and `git_context.py` — all streams now handled by `common/__init__.py`
* **Record-session template cleanup**: Removed auto-commit implementation details from all 8 platform record-session templates to prevent AI agents from misusing the `--no-commit` flag
## Dependencies
* Added `undici ^6.21.0` for ProxyAgent support
* Bumped `engines.node` from `>=18.0.0` to `>=18.17.0` (required by undici v6)
## Migration
No migration required. Run `trellis update` to sync updated scripts and templates. Node.js >=18.17.0 is now required.
# v0.3.4
Source: https://docs.trytrellis.app/changelog/v0.3.4
2026-03-05
Qoder platform support, Kilo workflows migration, and record-session task awareness.
## Enhancements
* **Qoder platform**: Added Qoder as a skills-based platform (`--qoder` flag). Templates are placed at `.qoder/skills/{name}/SKILL.md`
* **Record-session prompt optimization**: `/record-session` now enforces task archive check before recording — completed tasks must be archived first. `get_context.py` gains `--mode record` for focused context output with MY ACTIVE TASKS shown first
* **Task archive auto-commit**: `task.py archive` now auto-commits after archiving. Use `--no-commit` to skip
## Bug Fixes
* **Kilo workflows**: Renamed `commands/trellis/` to `workflows/` to match Kilo's official spec at `kilo.ai/docs/customize/workflows`
* **iFlow non-interactive**: Added `IFLOW_NON_INTERACTIVE` environment variable check in session-start hook, fixing cross-layer consistency for non-interactive mode
* **Multi-agent nested session**: Clear inherited `CLAUDECODE` env var before spawning child processes, fixing nested session guard introduced in Claude Code v2.1.39+
* **Update preserves user files**: `trellis update` no longer overwrites `workflow.md` and `workspace/index.md` — these user-customizable files are only created during init
## Migration
Kilo users: `trellis update` will automatically rename `.kilocode/commands/trellis/` to `.kilocode/workflows/`.
# v0.3.5
Source: https://docs.trytrellis.app/changelog/v0.3.5
2026-03-05
Hotfix for Kilo workflows delete migration.
## Bug Fixes
* **Migration manifest field name**: Fixed `delete` migration manifest using incorrect `path` field instead of `from`, causing Kilo commands cleanup to fail during `trellis update`
## Migration
No manual migration required. Run `trellis update` to apply the Kilo workflows migration that was blocked in v0.3.4.
# v0.3.6
Source: https://docs.trytrellis.app/changelog/v0.3.6
2026-03-06
Task lifecycle hooks, custom template registries, parent-child subtasks, and PreToolUse hook fix.
## Enhancements
* **Custom template registries**: `trellis init --registry` supports fetching Spec templates from custom GitHub/GitLab/Bitbucket repositories. Automatically detects marketplace mode (`index.json`) and direct download mode
* **Task lifecycle hooks**: `.trellis/config.yaml` gains a `hooks` configuration block supporting four events: `after_create`, `after_start`, `after_finish`, and `after_archive`. Task information is passed via the `TASK_JSON_PATH` environment variable. Ships with a Linear sync hook example. See: [Task Management](/start/everyday-use)
* **Parent-child subtasks**: `task.py add-subtask` / `remove-subtask` commands for linking tasks. `task.json` gains `children`, `parent`, and `meta` fields. `task.py create --parent` creates a child task directly
* **Record-session prompt improvement**: Archive decision is now based on actual work state rather than the `task.json` status field
* **Brainstorm prompt update**: `/brainstorm` now includes a subtask decomposition step for complex tasks
## Bug Fixes
* **PreToolUse context injection failure**: Claude Code v2.1.63 renamed its internal tool from `Task` to `Agent` ([anthropics/claude-code#29677](https://github.com/anthropics/claude-code/issues/29677)), causing hook scripts with `tool_name != "Task"` checks to exit early. This broke code-spec context injection for all implement/check/debug/research agents. Fix: accept both `Task` and `Agent` tool names, and add an `"Agent"` matcher to `settings.json`
## Migration
No manual migration required. Run `trellis update` to sync the updated hook scripts and settings.
# v0.3.7
Source: https://docs.trytrellis.app/changelog/v0.3.7
2026-03-10
Smart update protection, session-start task awareness, and improved start flow.
## Enhancements
* **Update: user-deletion protection**: If you intentionally deleted a file installed by Trellis, `trellis update` now detects this via stored hashes and will not re-add it. A new "Deleted by you (preserved)" section appears in the update summary
* **Update: `update.skip` config**: Add an `update.skip` list in `.trellis/config.yaml` to permanently exclude specific files or directories from `trellis update`. Useful for monorepo projects that don't need certain platform-specific commands
* **Session-start: task status injection**: Session-start hooks now inject a `<task-status>` tag with structured state (`NO ACTIVE TASK` / `NOT READY` / `READY` / `COMPLETED`), enabling AI to automatically detect and resume in-progress tasks
* **Session-start: dynamic spec discovery**: Session-start hooks now dynamically iterate `spec/` subdirectories instead of hardcoding `frontend/backend/guides`, supporting monorepo package layouts (e.g., `spec/cli/backend/`)
* **Start flow: brainstorm enforcement**: Complex tasks now automatically trigger the brainstorm flow across all 9 supported platforms, preventing premature implementation without requirements clarification
## Migration
No manual migration required. Run `trellis update` to sync the updated hook scripts and command templates.
# v0.3.8
Source: https://docs.trytrellis.app/changelog/v0.3.8
2026-03-12
Fix YAML parser quote stripping.
## Bug Fixes
* **YAML parser: greedy quote strip** — `parse_simple_yaml()` in `worktree.py` used Python's `str.strip('"').strip("'")`, which removes ALL matching characters from both ends instead of just one pair of quotes. Values like `"echo 'hello'"` would be corrupted to `echo 'hello`. Replaced with a safe `_unquote()` helper that removes exactly one layer of matching surrounding quotes
* **Update: skip path quote handling** — `loadUpdateSkipPaths` in `update.ts` now correctly strips surrounding quotes from skip paths in `.trellis/config.yaml`, fixing cases where quoted paths like `".claude/commands/"` were not matched
## Migration
No manual migration required. Run `trellis update` to sync the fixed YAML parser to your project.
# v0.3.9
Source: https://docs.trytrellis.app/changelog/v0.3.9
2026-03-12
Fix iFlow hook matcher naming.
## Bug Fixes
* **iFlow: hook matcher naming** — Corrected iFlow SessionStart hook matcher from `compact` to `compress` to match the actual Claude Code event name
# v0.4.0
Source: https://docs.trytrellis.app/changelog/v0.4.0
2026-04-15
After 11 betas and 2 RCs, Trellis v0.4.0 stable is released!
## Monorepo-native support
`trellis init` now detects monorepos and creates **per-package** spec directories — every package gets its own coding conventions and tasks. To keep the command matrix from exploding alongside package count, the type-specific `before-backend-dev` / `before-frontend-dev` / `check-backend` / `check-frontend` are merged into single `before-dev` / `check` commands across 9 platforms.
## More platforms
* **GitHub Copilot** — `--copilot`
* **Windsurf** — `--windsurf`
* **Qoder** — `--qoder`
* **Factory Droid** — `--droid`
Enable multiple platforms in one go:
```bash theme={null}
trellis init --codex --gemini --copilot -u your-name
```
## Codex now fully supported
* **Codex SessionStart hook is enabled.** Codex users get the same auto-injection as Claude Code users — no need to manually invoke `/start` anymore. Task state, workflow, and guidelines are injected at session start.
* **Sub-agent definitions.** `.codex/agents/` now ships TOML-format `implement` / `research` / `check` agents, semantically aligned with Claude Code's `Agent` tool.
* **Shared skills layer.** Codex writes to `.agents/skills/` (the [agentskills.io](https://agentskills.io) standard directory). The same output is read automatically by Cursor, Gemini CLI, GitHub Copilot, Amp, and Kimi Code — one Codex checkbox covers a wide range of tools.
## Other improvements
* **Custom spec template registry.** `trellis init -r <source>` pulls spec templates from a custom git repository (GitHub / GitLab / Bitbucket, including self-hosted GitLab via HTTPS or SSH) instead of the default marketplace. Teams can host their own coding conventions on internal git servers.
* **Re-init fast path.** `trellis init --codex` adds Codex to an existing project; bare `trellis init` shows an interactive menu.
* **Branch awareness.** Sessions and journals carry git branch context, so parallel branches don't get tangled.
* **Claude Code statusline integration.**
* **Multi-agent pipeline.** Supports worktree submodules and PR state tracking.
## Notable fixes
* **SessionStart payload size fix.** Reduced from \~29 KB to \~7 KB, fixing a major silent bug where Claude Code was truncating task state on most projects.
* **Windows.** Statusline GBK encoding crash (thanks @xiangagou163) and `{{PYTHON_CMD}}` placeholder resolution in Codex `hooks.json`.
**Other fixes (selected)**
* fix(update): allow rename migrations to target protected paths + warn on config parse failure
* fix(update): parse name from `.developer` when creating migration task
* fix(hooks): normalize `.current-task` path refs across platforms (#130)
* fix(hooks): correct `SubagentStop` event field names in ralph-loop (#152)
* fix(opencode): make dispatch wait for child tasks (#147)
* fix(init): strip npm scope prefix from monorepo package directory names
* fix(init): rename "empty templates" to "from scratch" in template picker
* fix(scripts): preserve submodule status prefix in `start.py`
## Install & upgrade
```bash theme={null}
# Fresh install
npm install -g @mindfoldhq/trellis@latest --registry=https://registry.npmjs.org
# Upgrade (existing trellis install)
trellis update
```
Upgrading from 0.3.x automatically handles the 36 merged command-file deletions — with hash verification, **your local edits are preserved**; only files that haven't been modified are removed.
***
* Full changelog: [https://docs.trytrellis.app/changelog/v0.4.0](https://docs.trytrellis.app/changelog/v0.4.0)
* Repo: [https://github.com/mindfold-ai/Trellis](https://github.com/mindfold-ai/Trellis)
* Docs: [https://docs.trytrellis.app](https://docs.trytrellis.app)
# v0.4.0-beta.1
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.1
2026-03-12
Monorepo support, unified commands, and Python scripts refactoring.
<Warning>This is a **breaking change** release. Run `trellis update` to migrate. Customized command files will be preserved — only unmodified files are auto-deleted.</Warning>
## Enhancements
* **Monorepo auto-detection** — `trellis init` detects pnpm/npm/Cargo/Go/uv workspaces and git submodules, generates per-package spec directories and `config.yaml` with packages list
* **Unified commands** — `before-backend-dev` + `before-frontend-dev` merged into `before-dev`; `check-backend` + `check-frontend` merged into `check` (all 9 platforms)
* **Safe file delete** — New migration type that auto-removes deprecated files only when content hash matches (user-modified files are never deleted)
* **Protected paths** — `PROTECTED_PATHS` prevents migrations from touching user data (`.trellis/workspace`, `spec`, `tasks`)
* **Update skip paths** — `config.yaml` `update.skip` to exclude paths from safe-file-delete and template updates
* **Worktree submodule awareness** — Worktree agents auto-initialize git submodules for task packages
* **Monorepo script support** — Session-start hook supports `spec_scope` filtering; `task.py` and `add_session.py` support `--package`
* **Migration task auto-creation** — Breaking change updates automatically create a `.trellis/tasks/` migration task with guide and AI instructions
## Bug Fixes
* **Update: protected path compat** — Allow rename/rename-dir migrations to target protected paths (0.2.0 compat)
* **Update: config parse warning** — Warn when `config.yaml` parse fails instead of silently disabling `update.skip`
* **Scripts: submodule status** — Preserve git submodule status prefix character (`.strip` → `.rstrip`)
## Internal
* **Python scripts refactoring** — Shared `io`/`log`/`git` modules, `TaskInfo` TypedDict type safety, god modules (`task.py`, `git_context.py`, `status.py`) split into focused modules. All entry paths unchanged.
## Migration
Run `trellis update` to sync new unified commands. Old `before-backend-dev`, `before-frontend-dev`, `check-backend`, `check-frontend` files will be auto-deleted if unmodified. If you customized these files, merge your changes into the new `before-dev` / `check` files and delete the old ones manually.
# v0.4.0-beta.10
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.10
2026-04-09
Ralph Loop field name fix (P0), migration task assignee parsing fix, and task lifecycle documentation.
## Bug Fixes
* **Ralph Loop field names fix (#152)**: The SubagentStop hook was reading non-existent fields (`subagent_type`, `agent_output`, `prompt`) instead of the actual Claude Code event schema (`agent_type`, `last_assistant_message`), so Ralph Loop was silently inert for **all users since release**. Check/implement/debug subagents will now actually trigger loop control as documented. Thanks to @suyuan2022 for the catch.
* **Migration task assignee parsing (#153)**: When `trellis update --migrate` created the auto-generated migration task, it read `.trellis/.developer` as a plain string and embedded the entire `name=...\ninitialized_at=...` file contents as the `assignee` field. The timestamp line then leaked into `session-start.py` rendering, breaking the ACTIVE TASKS layout. Now parses the `name=` line correctly. Thanks to @suyuan2022 for the fix.
## Documentation
* **Task lifecycle commands**: `workflow.md` now documents `task.py start <name>` and `task.py finish` — previously both subcommands were wired in argparse but completely unmentioned in the workflow guide, so AI agents never knew to call them and `## CURRENT TASK` was perpetually `(none)`. Task Development Flow expanded from 5 to 7 explicit steps with Start (step 2) and Finish (step 7), plus a new "Current task mechanism" explainer tying `.current-task` to SessionStart hook injection.
## Notes
* Run `trellis update` to sync all changes
* **Behavior change**: Ralph Loop will now actually fire for check/implement/debug subagents. If you were unknowingly relying on the previously-silent behavior, watch for new loop activity after upgrading.
# v0.4.0-beta.2
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.2
2026-03-12
Hotfix for scoped npm package names in monorepo init.
## Bug Fixes
* **Scoped package name fix** — `trellis init` on monorepos with scoped npm packages (e.g. `@zhubao/desktop`) no longer creates nested `@scope/` directories in `.trellis/spec/`. The scope prefix is now stripped, so `@zhubao/desktop` becomes `desktop` in all filesystem paths and `config.yaml` keys. Display-only usages retain the full scoped name.
## Migration
If you previously ran `trellis init` on a monorepo with scoped packages, you may need to:
1. Rename `.trellis/spec/@scope/name/` to `.trellis/spec/name/`
2. Update the package keys in `.trellis/config.yaml` (e.g. `@scope/name:` → `name:`)
# v0.4.0-beta.3
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.3
2026-03-13
Fix `trellis update` skipping unregistered Python scripts, plus v0.3.10 fixes merged.
## Bug Fixes
* **Update script sync** — `trellis update` now uses `getAllScripts()` as the single source of truth for Python script files. Previously, 11 scripts (9 in `common/` and 2 in `multi_agent/`) were silently skipped because they weren't registered in `collectTemplateFiles()`'s hand-maintained list.
## Merged from v0.3.10
* **HTTPS registry URLs** — `trellis init --registry` now accepts HTTPS URLs (e.g. `https://github.com/user/repo`) by auto-converting them to giget-style format. (#87)
* **Record-session AI compatibility** — Updated record-session command wording so AI models (especially GPT) no longer refuse to run metadata scripts. (#88)
# v0.4.0-beta.4
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.4
2026-03-16
Git repo context for monorepo packages + improved init-context hints.
## Enhancements
* **Git repo context**: Packages with `git: true` in config.yaml now show branch, working directory status, and recent commits in session context
* **init-context hints**: After initializing context, the output now lists auto-injected defaults and all available spec files for the AI to choose from
* **publish-skill command**: New `/trellis:publish-skill` slash command
* **cc-codex-spec-bootstrap**: New marketplace skill for Claude Code + Codex parallel spec bootstrapping
## Bug Fixes
* Use `_is_true_config_value` for `isGitRepo` consistency (case-insensitive matching)
## Notes
* Run `trellis update` to sync
* No migration required
# v0.4.0-beta.5
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.5
2026-03-16
UX improvements: renamed template picker label + iFlow CLI agent fix.
## Enhancements
* **Template picker UX**: Renamed "empty templates" to "from scratch" in `trellis init` template selection for clearer messaging
## Bug Fixes
* **iFlow CLI agent**: Corrected CLI agent invocation syntax in `cli_adapter.py` (#95)
## Notes
* Run `trellis update` to sync
* No migration required
# v0.4.0-beta.6
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.6
2026-03-22
CodeBuddy platform support, OpenCode plugin fix, improved skill descriptions.
## Enhancements
* **CodeBuddy platform support**: Added [CodeBuddy](https://copilot.tencent.com/) (Tencent Cloud) as the 11th supported platform. Uses nested slash commands at `.codebuddy/commands/trellis/<name>.md` (e.g., `/trellis:start`). Includes type registry, configurator, 12 command templates, CLI flag (`--codebuddy`), and Python `cli_adapter` integration
* **Improved skill descriptions**: Enhanced YAML frontmatter descriptions across Codex, Kiro, and Qoder skill templates for better AI triggering accuracy. Descriptions now include specific use cases and trigger conditions
## Bug Fixes
* **OpenCode plugin directory**: Fixed plugin directory name from `plugin/` to `plugins/` in the OpenCode configurator (#103)
## Notes
* Run `trellis update` to sync
* No migration required
# v0.4.0-beta.7
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.7
2026-03-22
Fix Pyright/Pylance import warnings in session-start hooks.
## Bug Fixes
* **IDE import warnings**: Suppressed Pyright/Pylance `reportMissingImports` false positives in `session-start.py` hooks. The `common.config` and `common.paths` imports are resolved at runtime via `sys.path` but IDE static analyzers cannot follow dynamic paths. Added `# type: ignore[import-not-found]` annotations
## Notes
* Run `trellis update` to sync
* No migration required
# v0.4.0-beta.8
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.8
2026-03-24
Decouple `.agents/skills/` as shared Agent Skills layer, add full `.codex/` directory support with hooks, platform-specific skills, and custom agents.
## Enhancements
* **Shared Agent Skills layer**: `.agents/skills/` is now a shared directory following the [agentskills.io](https://agentskills.io) open standard. It is no longer bound to the Codex platform — any universal agent CLI (Codex, Kimi CLI, Amp, Cline, etc.) can read these skills
* **Codex `.codex/` directory**: New platform-specific directory structure:
* `.codex/config.toml` — project-scoped Codex config
* `.codex/agents/` — custom Codex agents (implement, research, check)
* `.codex/skills/` — Codex-specific skills (e.g. `parallel` with `--platform codex`)
* `.codex/hooks/session-start.py` + `hooks.json` — SessionStart hook injecting full Trellis context (workflow, guidelines, task status)
* **Codex SessionStart hook**: Automatically injects Trellis workflow, guidelines, and task context into Codex sessions. Requires `codex_hooks = true` under `[features]` in `~/.codex/config.toml` (experimental Codex feature)
* **Branch context in sessions**: Session journal records now include git branch information (#108)
## Bug Fixes
* **iFlow CLI adapter**: Reverted incorrect `--agent` flag change from PR #112. iFlow uses `$agent_name` prefix format, not `--agent`
* **Codex agent TOML format**: Fixed to use correct fields (`name`, `description`, `developer_instructions`, `sandbox_mode`) instead of invalid `[sandbox_read_only]` + `prompt` format
## Migration
* **Automatic**: Old Codex users (`.agents/skills/` without `.codex/`) are auto-detected and upgraded on `trellis update`
* **safe-file-delete**: `.agents/skills/parallel/SKILL.md` (moved to `.codex/skills/`), old `trellis-*.toml` agent files (renamed)
* Run `trellis update` to apply all changes
## Breaking Changes
* **Platform detection**: `.agents/skills/` alone no longer detects as Codex. `.codex/` directory is required
* **configDir**: Codex `configDir` changed from `.agents/skills` to `.codex`
## Notes
* Codex hooks require `codex_hooks = true` under `[features]` in `~/.codex/config.toml`
* Codex hooks `suppressOutput` is not yet functional (Codex experimental limitation — context is still printed in TUI)
* `parallel` skill moved from shared `.agents/skills/` to Codex-specific `.codex/skills/` since it contains `--platform codex`
# v0.4.0-beta.9
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.9
2026-04-07
Copilot & Windsurf platform support, self-hosted registry, OpenCode dispatch fix, and 6-phase task lifecycle.
## Enhancements
* **GitHub Copilot support**: New platform with standalone prompt templates and hook tracking. Run `trellis init --platform copilot` to set up
* **Windsurf support**: Full workflow support for Windsurf IDE — rules, workflows (brainstorm, start, before-dev, finish-work, update-spec, record-session), and AI configuration
* **Self-hosted registry**: Support self-hosted GitLab/GitHub Enterprise URLs in `--registry` flag (#131). Template fetcher now correctly parses GHE/GitLab raw file URLs
* **StatusLine integration**: Claude Code statusLine now shows Trellis task context (#127)
* **CodeBuddy & Codex improvements**: New CodeBuddy platform support, Codex agent and docs fixes (#128, #116)
* **6-phase task lifecycle**: Task `next_action` template updated from 4-phase pipeline to full lifecycle: brainstorm → research → implement → check → update-spec → record-session
* **Marketplace as submodule**: Marketplace migrated to standalone repo, linked as git submodule (#117)
## Bug Fixes
* **OpenCode dispatch sync**: Dispatch now waits for child tasks synchronously instead of background polling, preventing premature phase advancement (#147)
* **Cross-platform path normalization**: `.current-task` path references now normalized across platforms (#130)
* **Codex Windows fix**: `{{PYTHON_CMD}}` placeholder in `hooks.json` now correctly resolved on Windows (#132)
* **Session recording**: `add_session.py` git-add error handling improved, Python 3.10 version check added
* **Template fetcher**: Self-hosted GitLab/GHE URL parsing fixed in `template-fetcher.ts`
## Notes
* Run `trellis update` to sync all changes
* New platforms: `trellis init --platform copilot` or `--platform windsurf`
# v0.4.0-rc.0
Source: https://docs.trytrellis.app/changelog/v0.4.0-rc.0
2026-04-14
**v0.4.0 feature freeze.** First release candidate. No new features before stable — only bug fixes accepted. Please test and report regressions.
## SessionStart size fix (#154)
Vanilla `additionalContext` reduced from **\~29 KB to \~7 KB**, comfortably under Claude Code's \~20 KB truncation threshold. Task state (ACTIVE TASKS, CURRENT TASK) was being silently lost on most non-trivial projects. Thanks to @21nak for the thorough writeup, measurements, and both PRs.
* **#161 workflow\.md ToC**: Replace full `workflow.md` injection (\~12 KB) with a compact section index that lists each `##` heading. Applied to all 5 platforms including copilot. AI reads the full file on demand.
* **#160 remove start.md injection**: The `<instructions>` block pre-injected `start.md` (\~11 KB), but slash commands expand on demand anyway — this was duplicate work. Now removed from 4 platforms; copilot never had it.
* **Follow-up cleanup**: `<ready>` text no longer references nonexistent "Steps 1-3 / Step 4" after `<instructions>` was removed. Orphaned `claude_dir` / `codex_dir` / `iflow_dir` variables removed.
## OpenCode plugin v1 refactor (#159)
Update OpenCode templates to the v1 plugin API (`export default { id, server }`). Fixes non-persistent context injection: `experimental.chat.messages.transform` didn't write back to history, so injected Trellis context was lost on session reopen. Now routes through `chat.message` hook with SDK history-based dedupe via `metadata.trellis.sessionStart` markers. `task` tool prompt mutation now in-place (`args.prompt = ...`) because the runtime holds a local reference to the args object. Thanks to @Adamcf123.
## Windows encoding fix (#163)
`statusline.py` crashed on Windows with `UnicodeEncodeError: 'gbk' codec can't encode` when rendering the `·` separator in the info line. Both the live hook and the claude template now wrap `stdout`/`stderr` in UTF-8 on Windows. Thanks to @xiangagou163.
## Features
* **`feat(init)`: re-init fast path (#157)** — When `.trellis/` already exists, `trellis init` offers a streamlined flow instead of the full interactive setup:
* `trellis init --codex` → configure only Codex, skip everything else
* `trellis init -u name` → set up developer identity (new device sync)
* `trellis init` (bare) → menu: add platform / add developer / full re-init
* `--force` / `--skip-existing` → bypass fast path, run full init
## Bug Fixes
* **`fix(init)`: skip bootstrap task creation on re-init** — re-running `trellis init` no longer creates duplicate bootstrap tasks
## Documentation
* **`docs(spec)`: SessionStart size constraint** — platform-integration spec now documents the \~20 KB `additionalContext` truncation threshold with a size budget table, preventing future hooks from silently exceeding the limit
## Notes
* RC install: `npm install -g @mindfoldhq/trellis@rc`
* Please run `trellis update` on an existing project and report any regressions
* Session-start hooks have been significantly restructured — if you customized them locally, re-check after update
* Windows users with statusline garbling should also update
# v0.4.0-rc.1
Source: https://docs.trytrellis.app/changelog/v0.4.0-rc.1
2026-04-14
**Late-RC additive feature.** Two pure-additive changes — no migrations, no behavior changes for existing platforms. Safe to update mid-RC.
## Factory Droid platform support
[Factory Droid](https://factory.ai) is now a first-class Trellis platform. Cursor-level scope: commands-only, no hooks/agents.
* `trellis init --droid` writes 12 Trellis commands to `.factory/commands/trellis/<name>.md`
* Each file ships with optional YAML frontmatter (`description: ...`) so Droid's `/commands` autocomplete shows a one-line summary
* Layout uses nested `trellis/` subdirectory like Claude Code (Droid's docs claim nesting is unsupported but the actual binary picks them up — verified before release)
* `cli_adapter.py` fully integrates Droid so Trellis Python scripts (status, archive, journals) detect `.factory/` projects correctly
* Multi-agent CLI `run`/`resume` currently raises `ValueError` ("not yet integrated with Trellis multi-agent") — same pattern as Copilot/Windsurf. Can be extended in a future release if there's demand.
## Codex option hints at `.agents/skills/` shared layer
The interactive `trellis init` checkbox for Codex now reads:
```
Codex (also writes .agents/skills/ — read by Cursor, Gemini CLI, GitHub Copilot, Amp, Kimi Code)
```
Trellis only writes `.agents/skills/` when Codex is enabled, but that directory is read by many other clients via the [agentskills.io](https://agentskills.io) open standard. Surfacing this in the prompt makes the spillover benefit visible — users picking Codex understand it isn't Codex-specific.
Verified against each client's official docs:
* [Cursor Skills](https://cursor.com/docs/skills) — explicit `.agents/skills/` entry
* [Gemini CLI Skills](https://geminicli.com/docs/cli/skills) — `.agents/skills/` is the cross-client "alias", takes precedence over `.gemini/skills/`
* [VS Code Copilot Agent Skills](https://code.visualstudio.com/docs/copilot/customization/agent-skills) — `.agents/skills/` listed alongside `.github/skills/` and `.claude/skills/`
* [Amp Owner's Manual](https://ampcode.com/manual) — `.agents/skills/` is the only project-level skill location
* [Kimi Code CLI Skills](https://moonshotai.github.io/kimi-cli/en/customization/skills.html) — discovered from `.agents/skills/` (or `.kimi/skills/`, `.claude/skills/`)
Note: Claude Code is intentionally omitted. Its [official skills docs](https://code.claude.com/docs/en/skills) only list `.claude/skills/` and `~/.claude/skills/` — Claude Code does NOT read `.agents/skills/`, contrary to several third-party blog claims.
## Notes
* Pure-additive update. RC users can `trellis update` safely — no file renames, no behavior changes, no migrations.
* Run `trellis init --droid` to try Factory Droid support.
* RC install: `npm install -g @mindfoldhq/trellis@rc`
# v0.5.0
Source: https://docs.trytrellis.app/changelog/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
```
# v0.5.0-beta.0
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.0
2026-04-20
**Skill-first architecture + hooks for everyone.** The first preview of 0.5 reshapes two things at once: how templates are authored (single source, N outputs) and how AI stays on-workflow (per-turn hook, not once-per-session). Plus the largest cleanup since 0.4.0 — iFlow, multi-agent pipeline, Ralph Loop, dispatch/debug/plan agents, and six retired commands are all gone.
## Skill-first template architecture
Commands and skills now live under `packages/cli/src/templates/common/` as a single source of truth (3 commands + 5 skills). All 13 platforms resolve from `common/` through per-platform adapters. Eliminates the prior N-copies-of-same-content drift that caused stale commands to linger on some platforms but not others.
Two reusable helpers landed alongside:
* **`createTemplateReader()`** (in `template-utils.ts`) — factory used by 6 platform template modules, replacing boilerplate `import { readFileSync } from "fs"` scaffolding. Uses `fileURLToPath` correctly so paths with spaces / on Windows resolve.
* **`writeSharedHooks()` + `writeAgents()` + `writeSkills()`** (in `configurators/shared.ts`) — three-line calls that configurators use to emit their hook / agent / skill set, instead of bespoke file-copy loops.
## Hooks + agents for 7 new platforms
Qoder, CodeBuddy, Factory Droid, Cursor, Gemini CLI, Kiro, and GitHub Copilot go from commands-only to fully agent-capable. Each ships:
* Sub-agent definitions (implement / check / research) in the platform's native format
* Hook configuration wired via `shared-hooks/` Python scripts (session-start, inject-subagent-context, statusline) — single implementation, cross-platform output adapters
Claude Code hooks are also migrated to the shared-hooks set, deleting a 1,435-line platform-specific implementation whose dead fallback code (`AGENT_DEBUG`, `spec.jsonl`/`research.jsonl` reads, hardcoded `check-cross-layer.md` references) had accumulated across releases.
## Sub-agent context injection: class-1 hook vs class-2 pull-based
Codex, Copilot, Gemini, and Qoder (class-2) can't reliably receive hook-modified sub-agent prompts:
* Codex `PreToolUse` only fires for Bash; `CollabAgentSpawn` hook unimplemented (#15486)
* Copilot `preToolUse` silently ignored on sub-agents (#2392 / #2540)
* Gemini's `BeforeTool` can't see the caller's context (#18128)
* Qoder has no Task tool + context isolation
These 4 platforms now use a **pull-based prelude**: sub-agent definitions include an up-front instruction block that makes the sub-agent Read `.current-task` + `prd.md` + `implement.jsonl`/`check.jsonl` itself on first turn. Class-1 platforms (Claude / Cursor / OpenCode / Kiro / CodeBuddy / Droid) continue with hook-based push injection. Both paths live in shared infrastructure (`applyPullBasedPreludeMarkdown` / `applyPullBasedPreludeToml`) so future platforms pick one and it works.
## Workflow enforcement v2: per-turn breadcrumb hook
New `inject-workflow-state.py` shared hook fires on every user prompt (UserPromptSubmit equivalent on 8 platforms; `chat.message` on OpenCode Bun plugin). It injects a \~200-byte `<workflow-state>` block nudging AI toward the next workflow step based on the active task's `status`.
Breadcrumb content is pulled from `workflow.md` `[workflow-state:STATUS]...[/workflow-state:STATUS]` blocks — users who fork the workflow edit **one markdown file**, not the hook Python. Covers four states: `no_task` / `planning` / `in_progress` / `completed`. Custom hyphenated statuses (`in-review`, `blocked-by-team`) are recognized via the STATUS regex `[A-Za-z0-9_-]+`. Unknown statuses emit a generic fallback instead of silent-exiting — the hook never leaves a conversation without guidance.
Three-tier fallback (workflow\.md missing → partial tag → unknown status) so the hook never breaks.
Kiro is the one platform downgraded: its `agentSpawn` hook is per-sub-agent only, and there's no upstream equivalent for main-session per-turn injection. Sub-agent context injection still works; per-turn breadcrumb is awaiting upstream support.
## SessionStart payload restructure
The SessionStart `<workflow>` block grew from 2.7 KB to 9.5 KB by inlining Phase 1/2/3 step bodies — AI now has step-level how-to up front instead of lazy-loading via `get_context.py --mode phase --step X.Y`. Funded by shrinking `<guidelines>` from 10.9 KB to 4.6 KB: the cross-package `guides/index.md` stays inlined, but other `spec/<pkg>/<layer>/index.md` files are listed as paths only. Rationale: sub-agents get their specific specs via jsonl injection, and when the main agent needs details it reads on demand.
Total session-start payload: 16.7 KB — under Claude Code's \~20 KB `additionalContext` truncation threshold.
`workflow.md` itself slimmed 17 KB → 14 KB: English-only (was bilingual), removed `What is Trellis` intro + File Structure tree + redundant Best Practices section, task.py command table expanded from 5 → 16 subcommands per PR #169's grouping (lifecycle / context / metadata / hierarchy / PR) with a `--help` pointer for future-proofing.
## Legacy cleanup (126-entry safe-file-delete migration)
This release removes four categories of primitives whose replacement is now the default:
* **iFlow platform** — CLI unmaintained; entire `.iflow/` tree + template source removed
* **Multi-agent pipeline** (`.trellis/scripts/multi_agent/` + `worktree.yaml`) — all major CLIs now ship their own worktree support; Trellis doesn't need to reimplement
* **Ralph Loop hook** (`ralph-loop.py`) — SubagentStop + exit-code-2 enforcement not portable across platforms; check agent's self-fix loop is sufficient
* **Six commands + three sub-agents** — `parallel` (superseded by native worktrees), `onboard` / `create-command` / `integrate-skill` (low usage), `check-cross-layer` (merged into `check`), `record-session` (subsumed by `/finish-work`); `dispatch` / `debug` / `plan` agents (replaced by skill routing)
All cleanup is **hash-verified**: if you modified any of these files locally they stay put with a warning; only pristine Trellis-written copies get removed. 126 safe-file-delete entries cover the full surface across all 13 platforms (with `allowed_hashes` pulled from historical git versions, so users on any past 0.3.x / 0.4.x version get a clean migration).
## Command → skill migration (80 new manifest entries)
The 5 skills that users no longer invoke by hand (`before-dev` / `brainstorm` / `break-loop` / `check` / `update-spec`) now live under `<platform>/skills/trellis-<name>/SKILL.md` on every platform. Without migration, a user upgrading from 0.4.x would end up with both the old command file and the new skill file side-by-side. The manifest closes this cleanly:
* **65 rename** entries (13 platforms × 5 commands) — preserves user customizations via move + subsequent template-write prompt (not plain delete)
* **3 rename** entries for `finish-work` on skill-only platforms (`.kiro` / `.qoder` / `.agents` shared layer) — gains the `trellis-` prefix too
* **10 safe-file-delete** for the old `start` command across agent-capable and skill-only platforms — session-start hook replaces the command's role
* **2 safe-file-delete** for the legacy `improve-ut` skill (`.agent/workflows/` + `.agents/skills/`)
`MigrationItem` gained a new `reason?` field — version-specific context (e.g. "Trellis 0.4.0 skipped hashing this path, so pristine copies show as modified") is authored inline in the manifest and rendered in the confirm prompt. No more hardcoded version-hints rotting in `update.ts`.
## `--migrate` is now required for breaking releases
Running `trellis update` against a project whose installed version spans a manifest flagged `breaking: true` + `recommendMigrate: true` **exits 1** with a clear error telling the user to add `--migrate`. Previously `update` would silently skip the rename/delete entries and still bump the `.version` stamp, leaving the project half-migrated (stale old paths next to new templates). `--dry-run` bypasses the gate so users can still preview.
## Confirm-prompt redesign
When a migration file trips the modified-hash check, the interactive prompt now shows:
1. **What** the migration does (from the manifest `description`)
2. **Why prompted** — per-entry `reason` from the manifest, or a generic fallback
3. Recommendation on each option (Backup / Rename / Skip) including the consequence of skipping (stale path persists to future updates)
Default choice is now `backup-rename` instead of `skip` — pressing Enter never destroys user edits or leaves orphan files.
## Bug fixes
* **Backup no longer snapshots platform worktrees.** `createFullBackup` excludes any `/worktrees/` or `/worktree/` path, so Claude Code's `.claude/worktrees/`, Cursor's `.cursor/worktrees/`, and Gemini CLI's `.gemini/worktrees/` don't get duplicated on every `trellis update` (one backup could otherwise bloat to 100s of MB once worktrees are in use).
* **`copy-templates` build step leaks stale files.** Added `clean` to the build chain (`clean && tsc && copy-templates`) so templates deleted from `src/` stop lingering in `dist/` and shipping to npm. Without this fix, safe-file-deletes fought re-writes from the stale dist templates in a loop.
## Other notable changes
* `task.py create` stops writing legacy `current_phase` / `next_action` fields. FP-analysis outcome: workflow\.md's Phase N.M is documentation layering, not runtime state — `task.json.status` is the single source of task-level state.
* `inject-subagent-context.py`'s `update_current_phase()` function deleted — it was re-writing the legacy `current_phase` field on every Task spawn, silently undoing the deprecation.
* Codex hooks integration: `configureCodex` now auto-writes shared-hooks (was skipping them); stderr warning on `trellis init --codex` about `features.codex_hooks = true` requirement in user's `~/.codex/config.toml`.
* `get_context.py --mode phase` (no `--step`) returns Phase Index + Phase 1/2/3 bodies (was Phase Index only) — agent-less platforms (Kilo / Antigravity / Windsurf) running `/start` manually get the same content as hook-based platforms.
* Hook-path CWD robustness (partial): `inject-workflow-state.py` walks up from CWD to find `.trellis/`, fixing subdirectory / submodule CWD drift for this hook. Full coverage across all hooks is a post-beta task.
## Spec docs updated
* **platform-integration.md** — new sections: Workflow State Injection (per-turn breadcrumb), Subagent Context Injection: Hook-based vs Pull-based, Guidelines: Paths-only vs Inline, Per-Turn Hook design principle (no silent-exit on "nothing to say")
* **quality-guidelines.md** — new section: Schema Deprecation: Audit ALL Writers, Not Just the Creator (from a Codex cross-review finding where `cmd_create` dropped a field but a hook kept re-writing it)
* **workflow\.md** — full English translation; slim structure; task.py 16-subcommand reference table
* **directory-structure.md** + **script-conventions.md** — multi-agent references removed
## Tests
595 tests passing, lint + typecheck clean. 41 new tests since the first draft of this changelog: workflow-state per-turn breadcrumb (7 cases), Phase Index expansion, paths-only guidelines, `update_current_phase` deletion regression, UserPromptSubmit platform wiring invariants, breaking-change gate (3 cases: block / dry-run bypass / `--migrate` pass), 0.5.0-beta.0 manifest shape (65-entry coverage, per-platform path invariant, breaking+recommendMigrate flags), worktree backup exclusion (12 cases across platform conventions + user data + edge cases).
## Deferred to follow-up beta / rc
* Kiro `agentSpawn` hook output-format validation in real environment
* Cursor / CodeBuddy / Droid sub-agent hook injection real-env testing
* Full hook-path CWD-robustness across all hooks (Windows cmd / PowerShell)
* Parent-child Trellis config for submodule / micro-service repos (issue #172)
## Migration
Run `trellis update --migrate` (the `--migrate` flag is **required** this release — 68 rename entries don't auto-execute without it, and the new gate will exit 1 telling you to add it). Then the 138-entry safe-file-delete runs. User-modified files are preserved with warnings; only pristine Trellis-written files get cleaned up. Use `trellis update --migrate --dry-run` first if you want to preview.
**`/trellis:record-session` users:** this command is removed. Its single job (writing a session journal via `add_session.py`) is now Step 3 of `/trellis:finish-work`, which also covers Quality Gate and Commit reminders. Replace any aliases or scripts that invoke `record-session` with `finish-work`.
**Codex users:** enable `features.codex_hooks = true` in `~/.codex/config.toml` to receive SessionStart + UserPromptSubmit breadcrumb injection. Without this flag `hooks.json` is silently ignored by Codex.
**iFlow users:** the `.iflow/` directory will be removed. Copy it out first if you want to keep it.
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.1
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.1
2026-04-20
**First published 0.5 beta.** Code is identical to the `0.5.0-beta.0` dev cut. The bump from `beta.0` → `beta.1` happens automatically inside `pnpm release:beta` (via `pnpm version prerelease --preid beta`), so `beta.0` was never published to npm — `beta.1` is the first tagged release of the skill-first architecture.
All the heavy lifting (command→skill for 5 skills, 138-entry safe-file-delete for legacy commands + iFlow + multi-agent + Ralph Loop, breaking-change `--migrate` gate, per-entry `reason` field in the confirm prompt, worktree backup exclusion, build `clean` step) is defined in the `0.5.0-beta.0` manifest and applies when upgrading from 0.4.x.
See the [`v0.5.0-beta.0` changelog](/changelog/v0.5.0-beta.0) for the full migration story.
## Migration
If upgrading from 0.4.x: run `trellis update --migrate`. The breaking-change gate requires the flag explicitly — without it, `trellis update` exits 1 with guidance.
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.10
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.10
2026-04-22
Hotfix: three bugs in `trellis update --migrate` / `init-context`. Not breaking; no `--migrate` required.
## Bug Fixes
### 1. `trellis-` prefix missing from codex / kiro skill paths
`get_trellis_command_path` in `cli_adapter.py` returned bare-name paths, ignoring the prefix 0.5.0-beta.0 introduced across 60+ skill dirs. `check.jsonl` generated by `task.py init-context` on codex / kiro projects pointed at non-existent files.
```python theme={null}
elif self.platform == "codex":
return f".agents/skills/trellis-{name}/SKILL.md"
elif self.platform == "kiro":
return f".kiro/skills/trellis-{name}/SKILL.md"
```
### 2. `.agents/skills/` blocked Kiro / Antigravity / Windsurf detection
`.agents/skills/` is a shared cross-platform layer (Codex writes, Amp / Cline / Kimi Code / Warp consume via agentskills.io). It was listed in `_ALL_PLATFORM_CONFIG_DIRS`, blocking every detection branch whose exclude set didn't name it. `detect_platform` fell through to `claude`.
* Removed `".agents"` from `_ALL_PLATFORM_CONFIG_DIRS`.
* Added a guarded codex fallback at the end of `detect_platform`:
```python theme={null}
agents_skills = project_root / ".agents" / "skills"
if agents_skills.is_dir() and not _has_other_platform_dir(project_root, set()):
for entry in agents_skills.iterdir():
if entry.is_dir() and entry.name.startswith("trellis-"):
return "codex"
```
### 3. `init-context` now accepts `--platform`
Skills / commands are rendered per-platform; the invoking platform is known at render time. Threaded it end-to-end instead of re-detecting from the filesystem.
* `{{CLI_FLAG}}` placeholder added to `resolvePlaceholders` — resolves to the platform's `cliFlag` at configure time.
* `TemplateContext` gained `cliFlag: CliFlag`, asserted against `AIToolConfig.cliFlag` by a registry invariant test.
* `task.py init-context` gained `--platform`, threaded through `cmd_init_context` → `get_check_context(repo_root, platform=...)` → `get_cli_adapter(platform)`.
* `codex/skills/start/SKILL.md` and `copilot/prompts/start.prompt.md` now invoke:
```bash theme={null}
python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type> --platform {{CLI_FLAG}}
```
Auto-detect remains as fallback when `--platform` is omitted (CLI-direct invocation, `TRELLIS_PLATFORM` env var).
### 4. `migrationGuide` back-fill for 0.5.0-beta.0 and 0.5.0-beta.5
`update.ts` builds the migrate-to-`<version>` task PRD by concatenating every `migrationGuide` between `fromVersion` and `toVersion`. Both breaking 0.5.x releases shipped without the field; users upgrading from 0.4.x saw a PRD containing only 0.3/0.4 historical guides, with nothing about the actual 0.5 breaking changes.
| Manifest | Back-filled content |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `0.5.0-beta.0.json` | 0.4→0.5 narrative: skill renames, retired commands, Multi-Agent Pipeline removal, iFlow drop, `task.json` schema cleanup |
| `0.5.0-beta.5.json` | Sub-agent rename: `implement` / `check` / `research` → `trellis-*` |
`packages/cli/scripts/create-manifest.js` now rejects manifests where `breaking && recommendMigrate && !migrationGuide`. `.trellis/spec/cli/backend/migrations.md` documents the rule.
End-to-end paths verified:
| From → To | Guides included |
| ------------------------------ | ---------------------------------------------- |
| `0.4.0 → 0.5.0-beta.10` | `0.5.0-beta.0`, `0.5.0-beta.5` |
| `0.3.9 → 0.5.0-beta.10` | `0.4.0-beta.1`, `0.5.0-beta.0`, `0.5.0-beta.5` |
| `0.5.0-beta.4 → 0.5.0-beta.10` | `0.5.0-beta.5` |
### 5. `release:beta` / `release:rc` / `release:promote` check docs-site changelog
`packages/cli/scripts/check-docs-changelog.js` runs before version bump. If `docs-site/changelog/v<target>.mdx`, `docs-site/zh/changelog/v<target>.mdx`, or their `docs.json` page entries are missing, the script exits 1. Added after beta.10 itself shipped without a docs-site changelog for this exact reason.
## Upgrade
```bash theme={null}
trellis update
```
Not breaking.
* **Upgraded from beta.9 and already ran `trellis update --migrate`**: `check.jsonl` in tasks created during that run still points at the old bare-name paths. Re-run `task.py init-context <task-dir> <type> --platform <platform>` on each, or recreate the task.
* **On 0.4.x, never migrated to 0.5 yet**: the migration task PRD now contains the real 0.4→0.5 guide.
* **Codex users with fresh clones missing `.codex/`**: `detect_platform` now returns `codex` instead of `claude` when `.agents/skills/trellis-*` is the only platform signal present.
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.11
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.11
2026-04-22
Hotfix: `SessionStart` hook crashed at module-import time on PEP 604 union annotations when the AI CLI host spawned `python3` as macOS system 3.9 — even though the user's shell `python3` was 3.11. Not breaking; no `--migrate` required. Also relaxes the declared Python floor from 3.10 to 3.9 so the macOS system `python3` is supported out of the box.
## Bug Fixes
### Hook PEP 604 annotation crash
`packages/cli/src/templates/shared-hooks/session-start.py` and `inject-subagent-context.py` did not declare `from __future__ import annotations`, so PEP 604 union annotations (`str | None`, `dict | None`) were evaluated eagerly when Python processed the `def` statement. On any `python3` \< 3.10 the module aborted with:
```
TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'
```
Observed in the wild on macOS: the user's shell `python3 --version` reported 3.11.12 (homebrew), but the AI CLI host spawned the hook subprocess with a minimal PATH that did not include `/opt/homebrew/bin`. `env python3` resolved to `/usr/bin/python3` → macOS system 3.9, which does not implement PEP 604 at expression-eval time.
`packages/cli/src/templates/shared-hooks/statusline.py` plus the `copilot/codex` copies of `session-start.py` already carried the future import; the two canonical `shared-hooks/*.py` files were the outliers.
**Fix** — add one line immediately after the module docstring:
```python theme={null}
"""Session Start Hook - Inject structured context"""
from __future__ import annotations # added
```
| File | Change |
| -------------------------------------------------------------------- | ------------------------------------- |
| `packages/cli/src/templates/shared-hooks/session-start.py` | `+from __future__ import annotations` |
| `packages/cli/src/templates/shared-hooks/inject-subagent-context.py` | `+from __future__ import annotations` |
`from __future__ import annotations` (PEP 563) makes all annotations lazy strings, so PEP 604 syntax in annotations is safe on Python 3.7+. Runtime union expressions — e.g. `isinstance(x, int | str)` — are **not** rescued and still require 3.10+; neither hook uses them.
## Improvements
### Python floor relaxed from 3.10 to 3.9
`packages/cli/src/commands/init.ts` now sets `MIN_MINOR = 9`. Rationale: macOS Ventura / Sonoma / Sequoia all ship `/usr/bin/python3` at 3.9.6, and Trellis's distributed templates (both `shared-hooks/*.py` and `trellis/scripts/**/*.py`) were empirically verified against CPython 3.8–3.13 via a full package-import matrix — 30/30 files load cleanly on every tested version.
| Change | Location |
| --------------------------------------------- | ------------------------------------------------------------------------ |
| `MIN_MINOR = 10` → `9` | `packages/cli/src/commands/init.ts` |
| Warning text `Python ≥ 3.10` → `Python ≥ 3.9` | `packages/cli/src/commands/init.ts` (2 occurrences) |
| `Python ≥ 3.10` → `Python ≥ 3.9` | `README.md` |
| Quickstart Prerequisites table | `docs-site/quickstart.mdx` + `docs-site/zh/quickstart.mdx` (new section) |
No CI matrix change yet; the empirical test harness lives in `/tmp/trellis-py-compat/` during development (not committed). Python 3.8 is not supported — EOL 2024-10, and declaring support would incur backport obligations whenever an unmaintained-Python CVE surfaces.
### Init now follows the same OS-aware Python command policy as templates
The template layer already rendered `{{PYTHON_CMD}}` as `python` on Windows and
`python3` on macOS/Linux, but `packages/cli/src/commands/init.ts` still probed
`python3` first everywhere and only fell back to `python`. That meant the
Windows status message, generated hook commands, and init's own
`init_developer.py` bootstrap path were talking about different interpreters.
`trellis init` now uses the same platform rule in both places:
| Platform | Generated command | Init probe / bootstrap command |
| ------------- | ----------------- | --------------------------------------------------------------------- |
| Windows | `python` | `python --version`, `python .trellis/scripts/init_developer.py ...` |
| macOS / Linux | `python3` | `python3 --version`, `python3 .trellis/scripts/init_developer.py ...` |
If the selected platform command resolves to Python \< 3.9, init prints a
warning but still completes. Missing Python still does not block file
generation; the follow-up failure mode remains the same manual bootstrap hint.
| File | Change |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `packages/cli/src/configurators/shared.ts` | Export shared OS → Python command helper used by template rendering |
| `packages/cli/src/commands/init.ts` | Reuse shared helper for version probe, Windows notice, and `init_developer.py` invocation |
| `packages/cli/test/commands/init.integration.test.ts` | Regression coverage for init bootstrap command + soft warning path |
| `packages/cli/test/commands/init-internals.test.ts` | Unit coverage for Python version floor warning behavior |
## Upgrade
Existing projects:
```bash theme={null}
trellis update
```
Picks up the two patched hook files plus the updated `cross-platform-thinking-guide.md` template. Pristine installs apply silently; locally-modified copies land on the standard confirm prompt.
Fresh install:
```bash theme={null}
npm i -g @mindfoldhq/trellis@0.5.0-beta.11
```
# v0.5.0-beta.12
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.12
2026-04-23
Phase 1.3 is now agent-curated. `task.py init-context` is removed; `task.py create` seeds `implement.jsonl` / `check.jsonl` with a self-describing `_example` line on sub-agent-capable platforms, and the AI fills real spec + research entries per `workflow.md` Phase 1.3. Session-start READY gate across four implementations now requires at least one curated entry. Skill Routing tables split per-platform. Release pipeline hardened. Not breaking; `trellis update` handles existing tasks transparently.
## Feature Changes
### workflow\.md Phase 1.3 is now filled in by the agent, not by a script with pre-generated defaults
The old `task.py init-context` pre-filled `implement.jsonl` / `check.jsonl` from `dev_type` + package config, assuming the template path `spec/<package>/{backend,frontend}/index.md`. Monorepos that split by language (e.g. `package = backend` + `package = frontend`) produced entries pointing at files that don't exist — which then led the agent to pre-fill the jsonl itself, and the many tool-call rounds that followed scattered the model's attention and drifted it off the Trellis workflow.
Seed row format (one line per jsonl, no `file` field so every consumer skips it):
```jsonl theme={null}
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line when done."}
```
### Skill Routing tables split per-platform
`workflow.md` Skill Routing and DO-NOT-skip tables now have two dispatch modes: IDEs/CLIs that support sub-agents invoke `trellis-implement` to do the actual coding, while platforms without sub-agents load `trellis-before-dev` in the main agent and code there directly.
| Sub-agent platforms | Non-sub-agent platforms |
| ---------------------------------------------------------------------------------------- | --------------------------------------------------- |
| Claude / Cursor / OpenCode / Codex / Kiro / Gemini / Qoder / CodeBuddy / Copilot / Droid | Kilo / Antigravity / Windsurf |
| Dispatch `trellis-implement` sub-agent per Phase 2.1 | Load `trellis-before-dev` skill (main-session flow) |
### Session-start READY gate across four implementations
Before this release, all four session-start implementations treated `implement.jsonl` file existence as "ready for Phase 2". After `task.py create` seeded jsonl, the breadcrumb jumped straight to `Status: READY` and the AI skipped Phase 1.3 curation.
Now each implementation scans the jsonl for at least one row with a `file` key. Seed-only jsonl surfaces as `Status: PLANNING (Phase 1.3)` with a Next-Action pointing at the curation step.
```python theme={null}
def _has_curated_jsonl_entry(jsonl_path: Path) -> bool:
"""A freshly seeded jsonl only contains `{"_example": ...}` — that is NOT ready."""
for line in jsonl_path.read_text(encoding="utf-8").splitlines():
line = line.strip()
if not line:
continue
try:
row = json.loads(line)
except json.JSONDecodeError:
continue
if isinstance(row, dict) and row.get("file"):
return True
return False
```
| Implementation | Consumed by |
| ----------------------------------- | ----------------------------------------------------- |
| `shared-hooks/session-start.py` | Claude, Cursor, Kiro, CodeBuddy, Droid, Gemini, Qoder |
| `codex/hooks/session-start.py` | Codex |
| `copilot/hooks/session-start.py` | Copilot |
| `opencode/plugins/session-start.js` | OpenCode (JS plugin runtime) |
### Hook + prelude tolerance for seed-only jsonl
`shared-hooks/inject-subagent-context.py:read_jsonl_entries` filters rows without `file` silently (no error) but emits a single stderr warning when the result is empty.
`configurators/shared.ts:buildPullBasedPrelude` teaches Class-2 sub-agents (Codex / Copilot / Gemini / Qoder) to skip rows without `file` and fall back to `prd.md` + self-discovered specs when the jsonl has only the seed row.
## Internal Improvements
### Pre-release manifest continuity guard
`packages/cli/scripts/check-manifest-continuity.js` queries `npm view @mindfoldhq/trellis versions --json` and diffs against local `src/migrations/manifests/*.json`. Any version on npm without a corresponding local manifest fails the check non-zero.
Background: `trellis update` applies migrations where `v > installed && v <= current`. A version on npm without its local manifest silently skips its migration bucket for users upgrading from adjacent versions — see the beta.10 incident in `.trellis/spec/cli/backend/migrations.md`.
| Release script | Pre-flight order |
| ------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `release` / `release:minor` / `release:major` | `check-manifest-continuity.js` → `pnpm test` → bump → commit → tag → push |
| `release:beta` / `release:rc` / `release:promote` | `check-manifest-continuity.js` → `check-docs-changelog.js` → `pnpm test` → bump → ... |
Historical gaps frozen in `KNOWN_GAPS` (pre-manifest-system versions 0.1.0–0.1.8, 0.2.1–0.2.11; early public prerelease 0.3.10-beta.0). The comment block documents the list must not be extended — any new gap means root-cause fix, not whitelist append.
Emergency bypass: `SKIP_MANIFEST_CONTINUITY=1 pnpm release:beta`. Prints a loud banner when set.
### `trellis update` backup-phase stack-overflow fix
`createFullBackup()` descended into old `.trellis/.backup-*` directories during `.trellis/` scan, and those old backups in turn contained nested `.opencode/node_modules` (tens of thousands of files). The original `collectAllFiles()` used recursion + `files.push(...largeArray)`, which tripped V8's `Maximum call stack size exceeded` on large file counts. `trellis update` crashed at the backup phase after the user confirmed.
| Fix | Location |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `collectAllFiles` rewritten as iterative stack traversal (no recursion, no large-array spread) | `packages/cli/src/commands/update.ts:770` |
| Skip `node_modules`, `.backup-*`, and other excluded dirs at the scan phase, not only at the copy phase | `packages/cli/src/commands/update.ts:683` |
| Normalize backslashes to forward slashes before matching `BACKUP_EXCLUDE_PATTERNS` (aligns with `isManagedPath`'s existing regex). `.claude\worktrees\...` now matches on Windows | `packages/cli/src/commands/update.ts:689` |
| `collectAllFiles` skips symlinks and Windows NTFS junctions (`isSymbolicLink()` returns true for junctions too), preventing infinite scans on cyclic paths | `packages/cli/src/commands/update.ts:787` |
| Print full stack trace when `DEBUG=1` or `TRELLIS_DEBUG=1` is set | `packages/cli/src/cli/index.ts:130` |
Regression coverage added in `test/commands/update-internals.test.ts` and `test/commands/update.integration.test.ts`.
Temporary workaround for users on a pre-fix published CLI: `rm -rf .trellis/.backup-*` drops the old backups; subsequent `trellis update` runs won't hit the overflow source.
### `create-manifest.js` guards against rewriting published manifests
The script now refuses to (re)write a manifest for a version already on npm — even with `force: true`. Interactive mode adds the npm-published check before the existing local-file overwrite prompt.
```
$ node scripts/create-manifest.js --stdin <<< '{"version": "0.5.0-beta.11", ...}'
✗ Version 0.5.0-beta.11 is already published on npm.
Its manifest is part of the update contract and must NOT be rewritten.
If you need to release additional migrations, use the NEXT version number.
```
### `vi.mock("node:child_process")` now returns a valid Python version string
`update.integration.test.ts` and `init-joiner.integration.test.ts` stubbed `execSync` to return empty string for all commands. `init()` invokes `requireSupportedPython()` which calls `execSync("python3 --version")` and treats empty output as "Python not found", throwing before any test assertion ran.
```typescript theme={null}
// Before — blanket empty return:
vi.mock("node:child_process", () => ({
execSync: vi.fn().mockReturnValue(""),
}));
// After — conditional return for python version probe:
vi.mock("node:child_process", () => ({
execSync: vi.fn().mockImplementation((cmd: string) => {
const py = process.platform === "win32" ? "python" : "python3";
return cmd === `${py} --version` ? "Python 3.11.12" : "";
}),
}));
```
Resolves 36 pre-existing failures. Full suite: 664/664 green.
## Upgrade
Existing projects:
```bash theme={null}
trellis update
```
Picks up the updated scripts + hooks. Existing `implement.jsonl` / `check.jsonl` files keep working — seed rows without `file` are ignored by every consumer. If your prior `init-context`-generated jsonl points at paths that don't exist on your monorepo spec layout (typical for `package = backend | frontend` projects), re-curate per `workflow.md` Phase 1.3:
```bash theme={null}
python3 ./.trellis/scripts/get_context.py --mode packages # see what specs exist
python3 ./.trellis/scripts/task.py add-context <task-dir> implement \
".trellis/spec/<pkg>/<layer>/index.md" "why it applies"
```
After first real entry, the session-start breadcrumb flips from `PLANNING (Phase 1.3)` to `READY`.
Fresh install:
```bash theme={null}
npm i -g @mindfoldhq/trellis@0.5.0-beta.12
```
# v0.5.0-beta.13
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.13
2026-04-23
Patch follow-up to beta.12. `task.py start` now actually transitions `task.json` status from `planning` to `in_progress`. Previously only the `.current-task` pointer got updated and the status field stayed untouched, so Claude Code's statusline kept showing `planning`.
## Bug Fixes
### `task.py start` transitions `task.json` status to `in_progress`
`cmd_start` previously wrote `.current-task`, ran the `after_start` hook, and returned without modifying the `status` field in `task.json`. That field was maintained only by `create` (writes `planning`) and `archive` (writes `completed`); no code path wrote `in_progress`. Tasks in active development therefore did not appear under `list --status in_progress` and continued to show `Status: PLANNING` in session-start breadcrumbs.
`cmd_start` now reads `task.json` after setting the pointer and writes `in_progress` only when the current `status == "planning"`. Other statuses are preserved:
| Current status | After `task.py start` |
| -------------- | ---------------------------------------------------------------------------------- |
| `planning` | `in_progress` |
| `in_progress` | `in_progress` (no-op) |
| `review` | `review` (preserved; re-starting to address review feedback must not reset status) |
| `completed` | `completed` (preserved) |
Location: `packages/cli/src/templates/trellis/scripts/task.py:cmd_start`.
### Codex agent templates backport the Phase 1.3 fallback section
During beta.11's init-context-removal, a "Required: Load Trellis Context First" block was added to the top of both Codex agent files. It instructs the sub-agent to skip `{"_example": ...}` seed rows and, when `implement.jsonl` / `check.jsonl` contains no curated entries, fall back to reading `prd.md` and selecting specs via `get_context.py --mode packages`.
That edit landed only in the dogfood copy at the project root and was not propagated to `packages/cli/src/templates/codex/agents/`. Through beta.12, Codex agent prompts distributed by `trellis init` / `trellis update` lacked the block; the sub-agent blocked on seed-only jsonl instead of taking the fallback path.
Backported in this release:
* `packages/cli/src/templates/codex/agents/trellis-check.toml`
* `packages/cli/src/templates/codex/agents/trellis-implement.toml`
The text matches the prelude generated by `configurators/shared.ts:buildPullBasedPrelude` for Copilot / Gemini / Qoder, aligning Codex with the other pull-based platforms.
## Docs
### `.codex/config.toml` documents the `features.codex_hooks` opt-in
Trellis's Codex integration depends on the SessionStart and UserPromptSubmit hooks declared in `.codex/hooks.json`. Codex loads these only when `[features] codex_hooks = true` is set in the **user-level** `~/.codex/config.toml`; project-scoped `.codex/config.toml` cannot enable `features.*`. Without the flag, `hooks.json` is silently ignored and Trellis context injection does not run, presenting as Trellis failing to engage on Codex.
The project-scoped stub now carries a comment identifying the user-level config path and the exact TOML snippet to add. The unrelated `shell_environment_policy` block was removed.
## Upgrade
Existing projects:
```bash theme={null}
trellis update
```
No migration steps. Existing tasks, jsonl files, and `.current-task` are preserved. The first `task.py start` on an existing `planning` task after upgrade writes `in_progress` to `status` automatically. Codex users who hand-edited `.codex/agents/trellis-*.toml` will see the two files flagged during update; `trellis update` prompts per file.
Fresh install:
```bash theme={null}
npm i -g @mindfoldhq/trellis@0.5.0-beta.13
```
# v0.5.0-beta.14
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.14
2026-04-24
Patch follow-up to beta.13. SessionStart hooks now emit a one-shot `<first-reply-notice>` so the first visible assistant reply confirms Trellis context has been injected. READY-state breadcrumbs were rewritten to explicitly require `trellis-implement` dispatch on agent-capable platforms, closing a loophole where the main thread would hand-edit code itself. Claude Code's statusline now survives the Windows UTF-8 encoding setup on Python builds that ship typed stdio.
## Enhancements
### One-shot SessionStart announcement on the first reply
Users had no clear signal that Trellis's SessionStart hook had actually injected. SessionStart hooks now prepend the following block to `additionalContext`:
```text theme={null}
<first-reply-notice>
On the first visible assistant reply in this session, begin with exactly one short Chinese sentence:
Trellis SessionStart 已注入：workflow、当前任务状态、开发者身份、git 状态、active tasks、spec 索引已加载。
Then continue directly with the user's request. This notice is one-shot: do not repeat it after the first assistant reply in the same session.
</first-reply-notice>
```
Applied to:
* `packages/cli/src/templates/shared-hooks/session-start.py`
* `packages/cli/src/templates/codex/hooks/session-start.py`
* `packages/cli/src/templates/opencode/plugins/session-start.js`
`copilot/hooks/session-start.py` keeps the JSON shape for protocol parity but omits the notice because GitHub Copilot currently ignores `sessionStart` output (see Docs below).
### READY-state Next-Action copy rewritten
The old breadcrumb copy was:
```text theme={null}
Status: READY
Task: <title>
Next: Continue with implement or check
```
On agent-capable platforms this prompt could let the main agent process write code itself, bypassing the sub-agent workflow.
New copy:
```text theme={null}
Status: READY
Task: <title>
Next required action: dispatch `trellis-implement` per Phase 2.1.
For agent-capable platforms, do NOT edit code in the main session.
After implementation, dispatch `trellis-check` per Phase 2.2 before reporting completion.
```
The `<ready>` closing directive also changed from *"If there is an active task, ask whether to continue it"* to *"If a task is READY, execute its Next required action without asking whether to continue."*
Uniformly applied across:
| File | Scope |
| ------------------------------------------- | --------------------------------------- |
| `shared-hooks/session-start.py` | Claude Code, Gemini, Qoder, Kiro, iFlow |
| `shared-hooks/inject-workflow-state.py` | UserPromptSubmit fallback breadcrumb |
| `opencode/plugins/session-start.js` | OpenCode SessionStart |
| `opencode/plugins/inject-workflow-state.js` | OpenCode fallback breadcrumb |
| `codex/hooks/session-start.py` | Codex SessionStart |
| `copilot/hooks/session-start.py` | Copilot (hook present, see Docs) |
| `trellis/workflow.md` | `[workflow-state:in_progress]` block |
## Bug Fixes
### Claude Code statusline: Windows UTF-8 encoding setup no longer crashes
Claude Code's statusline (`.claude/hooks/statusline.py`, sourced from `shared-hooks/statusline.py`) needs to flip stdout/stderr to UTF-8 on Windows — otherwise glyphs like the middle dot (`·`) get mangled by GBK. The old setup was:
```python theme={null}
sys.stdout = io.TextIOWrapper(sys.stdout.detach(), encoding="utf-8")
sys.stderr = io.TextIOWrapper(sys.stderr.detach(), encoding="utf-8")
```
On some Windows Python builds, `sys.stdout` / `sys.stderr` are typed wrappers that do not expose `detach()`. Calling it raised, the statusline process died, and Claude Code's top info line went blank. The fix uses the standard `io.TextIOBase.reconfigure()` API (Python 3.7+) when available and no-ops otherwise:
```python theme={null}
if sys.platform == "win32":
for stream in (sys.stdout, sys.stderr):
reconfigure = getattr(stream, "reconfigure", None)
if callable(reconfigure):
reconfigure(encoding="utf-8", errors="replace")
```
`reconfigure` is standard on Python 3.7+ text streams; `errors="replace"` keeps rendering when the host refuses a rare glyph.
### Codex & Copilot SessionStart reuse the project's own encoding setup
Both hooks now run `configure_project_encoding(project_dir)` before emitting JSON: add `.trellis/scripts/` to `sys.path`, call `common.configure_encoding()` if the project ships it, skip otherwise:
```python theme={null}
def configure_project_encoding(project_dir: Path) -> None:
scripts_dir = project_dir / ".trellis" / "scripts"
if str(scripts_dir) not in sys.path:
sys.path.insert(0, str(scripts_dir))
try:
from common import configure_encoding # type: ignore[import-not-found]
configure_encoding()
except Exception:
pass
```
Prevents mojibake in hook stdout on Windows Codex/Copilot runs that have not already wrapped stdout.
## Docs
### Copilot `sessionStart` hook is currently advisory
`copilot/hooks/session-start.py`'s module docstring and `systemMessage` now state explicitly that GitHub Copilot's documented SessionStart behavior ignores hook stdout. The script continues to emit the Trellis payload (for parity with other hosts and eventual Copilot support), but the old success message — `Trellis context injected (<n> chars)` — was misleading on this host. It now reads `Trellis SessionStart diagnostics emitted (<n> chars); Copilot currently ignores sessionStart hook output.`
Copilot users should rely on `UserPromptSubmit` breadcrumbs (which *are* honored) and hook logs to verify Trellis engagement, not SessionStart output.
## Upgrade
Existing projects:
```bash theme={null}
trellis update
```
No migration steps. Existing tasks, jsonl files, and `.current-task` are preserved. On the next session start you'll see a one-line Chinese confirmation that Trellis context was injected, and READY tasks will push you to `trellis-implement` without the old "continue?" prompt. Claude Code's statusline on Windows no longer crashes during UTF-8 encoding setup.
Fresh install:
```bash theme={null}
npm i -g @mindfoldhq/trellis@0.5.0-beta.14
```
# v0.5.0-beta.15
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.15
2026-04-27
Beta.15 updates task runtime state, platform session identity propagation, Pi Agent integration, and beta documentation. It also keeps the shared-hook cleanup manifest entries from the pending beta.15 release.
## Behavior Changes
### Session-scoped active task runtime
Active task state now uses a per-session runtime file:
```text theme={null}
.trellis/.runtime/sessions/<session-key>.json
```
`.trellis/.current-task` is no longer used as the active-task fallback.
| Command | Behavior |
| -------------------------- | ---------------------------------------------------------------------------- |
| `task.py start <task>` | Writes the current task into the resolved session file |
| `task.py current --source` | Reads the current task from the resolved session file |
| `task.py finish` | Deletes the resolved session file |
| `task.py archive <task>` | Deletes session files that still point at the archived task before moving it |
Session file shape:
```json theme={null}
{
"platform": "session",
"last_seen_at": "2026-04-27T01:43:24Z",
"current_task": ".trellis/tasks/04-21-session-scoped-task-state",
"current_run": null
}
```
`task.py start` exits with code `1` when no session identity is available:
```text theme={null}
Error: Cannot set active task without a session identity.
Hint: run inside an AI IDE/session that exposes session identity, or set TRELLIS_CONTEXT_ID before running task.py start.
```
### Bootstrap and joiner tasks
`trellis init` still creates bootstrap and joiner task directories, but it no longer writes `.trellis/.current-task`.
The generated PRDs now tell the AI to start the task from a session that exposes Trellis session identity.
### Workflow task-creation policy
`workflow.md` and hook fallback breadcrumbs now use a softer task-creation policy.
| Area | Previous behavior | beta.15 behavior |
| ---------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `no_task` trigger words | Treat matching words as requiring task creation | Treat matching words as task-creation signals |
| Simple turns | No explicit exemption | Task not required when all three hold: zero file writes, one-reply answer, no research beyond reading 1-2 repo files |
| User opt-out | Not documented in the hook prompt | Current-turn phrases such as `skip trellis`, `no task`, `just do it`, `跳过 trellis`, `别走流程`, `先别建任务` skip task creation for that turn |
| `in_progress` implementation | Main session was told not to edit code | Sub-agent dispatch remains the default; explicit current-turn requests such as `do it inline`, `main session 写就行`, `不用 sub-agent` allow main-session implementation |
## Platform Integration
### Shell session identity handling
Several hosts expose session identity differently. beta.15 adds host-specific handling for `task.py start/current/finish`.
| Platform | Change |
| ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| Claude Code | `session-start.py` writes `TRELLIS_CONTEXT_ID` through `CLAUDE_ENV_FILE` |
| Codex | `task.py` resolves native command env such as `CODEX_SESSION_ID` and Codex Desktop `CODEX_THREAD_ID` |
| Cursor | `beforeShellExecution` writes short-lived `.trellis/.runtime/cursor-shell/*.json` tickets for matching `task.py` commands |
| OpenCode | Bash tool commands are prefixed with `TRELLIS_CONTEXT_ID` |
| Pi | Bash tool calls and nested `pi --mode json` sub-agent runs receive `TRELLIS_CONTEXT_ID` |
Other platforms use the same `.trellis/.runtime/sessions/` storage, but beta.15 does not add new shell-command handling for them.
| Platform group | beta.15 status |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GitHub Copilot | The platform-specific SessionStart hook resolves session identity for context injection. `task.py` can use exported `COPILOT_*` session env vars when the host provides them; otherwise use `TRELLIS_CONTEXT_ID` for manual shell starts. |
| Gemini CLI, Qoder, CodeBuddy, Droid, Kiro | Shared hooks resolve session identity from hook input or platform env vars. No new shell-command bridge was added in beta.15. Manual shell starts still use `TRELLIS_CONTEXT_ID` when the host does not export a session id. |
| Kilo, Antigravity, Windsurf | No hook integration. Use their workflow/command files plus explicit `TRELLIS_CONTEXT_ID` when running `task.py start` manually. |
| `.agents/skills` consumers | No Trellis-managed hook layer. They use the `.trellis/` core and whatever prelude or env injection the host provides. |
### Cursor sub-agent hook matching
Cursor `hooks.json` now matches both tool names:
```json theme={null}
{
"matcher": "Task|Subagent"
}
```
`inject-subagent-context.py` also parses Cursor custom-agent payloads in these shapes:
```json theme={null}
{ "custom": { "name": "trellis-implement" } }
```
```json theme={null}
{ "type": { "case": "custom", "value": { "name": "trellis-implement" } } }
```
### Pi Agent session runtime
Pi Agent now reads active task state from `.trellis/.runtime/sessions/`.
Context key sources, in priority order:
| Source | Example |
| ------------------ | ------------------------------------ |
| Explicit env | `TRELLIS_CONTEXT_ID` |
| Pi session manager | `sessionManager.getSessionId()` |
| Pi env | `PI_SESSION_ID`, `PI_SESSIONID` |
| Transcript path | `transcript_path` / `transcriptPath` |
| Process fallback | `pi_process_<hash>` |
Nested Pi sub-agent runs receive the same `TRELLIS_CONTEXT_ID`.
### Workflow-state override copy
`workflow-state` breadcrumbs now use exact Trellis agent names:
```text theme={null}
trellis-implement
trellis-check
trellis-research
```
The breadcrumbs also document explicit per-turn override phrases for skipping task creation or allowing main-session implementation.
## Bug Fixes
### OpenCode sub-agent name normalization
OpenCode now:
* recognizes `OPENCODE_RUN_ID` as session identity
* strips the `trellis-` prefix before matching sub-agent names
* keeps `implement.jsonl` / `check.jsonl` injection working with renamed agents
### Git-backed private registries
Template registry downloads now support private Git-backed registries. When a registry source requires local Git credentials, Trellis uses Git to read `index.json` and copy template directories instead of relying on anonymous raw HTTP.
This applies to self-hosted GitLab / GitHub Enterprise sources and SSH registry URLs. Registry errors are classified separately for authentication failures, missing refs, missing paths, invalid `index.json`, and network failures, so `trellis init --registry` no longer misclassifies those cases as direct-download mode.
### Shared-hook cleanup
`writeSharedHooks` and `collectSharedHooks` now use the same platform capability table:
```text theme={null}
SHARED_HOOKS_BY_PLATFORM
```
Claude Code statusLine is no longer installed by default for new projects. New installs do not write `.claude/hooks/statusline.py` or configure `statusLine` in `.claude/settings.json`.
Existing projects keep their installed Claude Code statusLine behavior: `trellis update` preserves `.claude/hooks/statusline.py` and carries an existing `.claude/settings.json` `statusLine` entry forward into the updated settings file.
The manifest includes 10 hash-verified `safe-file-delete` entries for hooks that were written to projects but are now orphaned.
| Removed path | Reason |
| -------------------------------------- | --------------------------------------- |
| `.cursor/hooks/statusline.py` | Cursor has no `statusLine` event |
| `.codex/hooks/statusline.py` | Codex has no `statusLine` event |
| `.gemini/hooks/statusline.py` | Gemini has no `statusLine` event |
| `.qoder/hooks/statusline.py` | Qoder has no `statusLine` event |
| `.github/copilot/hooks/statusline.py` | Copilot has no `statusLine` event |
| `.codebuddy/hooks/statusline.py` | CodeBuddy has no `statusLine` event |
| `.factory/hooks/statusline.py` | Factory Droid has no `statusLine` event |
| `.kiro/hooks/statusline.py` | Kiro has no `statusLine` event |
| `.kiro/hooks/session-start.py` | Kiro exposes only `agentSpawn` |
| `.kiro/hooks/inject-workflow-state.py` | Kiro exposes only `agentSpawn` |
Modified local files are preserved with a warning.
## Docs
### Beta task docs
Updated beta docs now describe:
* current task state under `.trellis/.runtime/sessions/<session-key>.json`
* session-scoped task ownership instead of a global project pointer
* `continue` / `finish-work` as the primary user-facing task commands
* `task.py start` as a session-bound operation
* Cursor, Codex, Claude Code, OpenCode, and Pi hook/sub-agent behavior
### Multi-agent docs
The beta multi-agent docs now describe native Git worktrees plus Trellis tasks. Removed references to Trellis-managed `/trellis:parallel` and `worktree.yaml`.
## Upgrade
Existing projects:
```bash theme={null}
trellis update
```
No `--migrate` gate is required for beta.15.
Existing task directories and jsonl files remain valid. Existing `.trellis/.current-task` files are preserved but ignored by the new active-task resolver.
Manual shell usage requires an explicit context id:
```bash theme={null}
TRELLIS_CONTEXT_ID=my-session python3 .trellis/scripts/task.py start .trellis/tasks/<task>
```
Fresh install:
```bash theme={null}
npm i -g @mindfoldhq/trellis@0.5.0-beta.15
```
# v0.5.0-beta.16
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.16
2026-04-28
Beta.16 is a compatibility patch for template hash portability, task archive inputs, and Claude Code statusLine upgrades after beta.15.
## Bug Fixes
### Template hash portability
Template hash storage now uses POSIX path keys and LF-normalized content hashes.
The `.trellis/.template-hashes.json` file now uses a versioned envelope:
```json theme={null}
{
"__version": 2,
"hashes": {
".trellis/scripts/task.py": "<sha256>"
}
}
```
| Area | beta.16 behavior |
| ----------------------- | ------------------------------------------------------------------- |
| Hash keys | Stored with `/` separators on every host |
| Hash input | CRLF content is normalized to LF before SHA256 |
| Legacy flat hash file | Discarded and regenerated from installed templates |
| Directory safety checks | `path.relative()` output is normalized before template/hash lookups |
| OpenCode templates | Collector stores `.opencode/*` keys in POSIX form |
This fixes Windows checkout cases where backslash hash keys or CRLF line endings made unchanged templates look modified.
### `task.py archive` input contract
`task.py archive` now accepts the same task inputs as the other task-directory commands.
| Input form | Example |
| ------------------ | ----------------------------------------------------------------------------- |
| Bare task name | `python3 .trellis/scripts/task.py archive 04-27-example` |
| Relative task path | `python3 .trellis/scripts/task.py archive .trellis/tasks/04-27-example` |
| Absolute task path | `python3 .trellis/scripts/task.py archive /repo/.trellis/tasks/04-27-example` |
Previously, `archive` was the only dir-style task command that used slug-only lookup. Passing `.trellis/tasks/<slug>` failed with `Task not found` even though other task commands accepted that form.
### Existing Claude Code statusLine installs are preserved
Beta.15 stopped installing Claude Code `statusLine` for new projects. That default is unchanged.
The upgrade path is now more conservative:
| Case | beta.16 behavior |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| New project | Trellis does not create `.claude/hooks/statusline.py` and does not add `statusLine` to `.claude/settings.json` |
| Existing project with `.claude/hooks/statusline.py` | `trellis update` preserves the file |
| Existing project with `.claude/settings.json` `statusLine` | `trellis update` carries that entry into the updated settings file |
This means beta.16 no longer treats Claude Code statusLine as a cleanup target. Users who no longer want it can delete the file and settings entry manually.
### Shared-hook cleanup still applies to orphan platform files
The non-Claude `statusline.py` cleanup entries remain hash-verified safe deletes. Those platforms have no `statusLine` event, so the files were never invoked:
* `.cursor/hooks/statusline.py`
* `.codex/hooks/statusline.py`
* `.gemini/hooks/statusline.py`
* `.qoder/hooks/statusline.py`
* `.github/copilot/hooks/statusline.py`
* `.codebuddy/hooks/statusline.py`
* `.factory/hooks/statusline.py`
* `.kiro/hooks/statusline.py`
## Upgrade
Existing projects:
```bash theme={null}
trellis update
```
No `--migrate` flag is required for this patch.
# v0.5.0-beta.17
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.17
2026-04-28
Beta.17 updates generated templates and platform integrations for built-in Trellis metadata, Pi subagents, and task context wiring.
## Enhancements
### Bundled `trellis-meta` skill
`trellis-meta` is now installed through the built-in skill template pipeline instead of requiring a separate marketplace install.
| Area | beta.17 behavior |
| ----------------- | ------------------------------------------------------------------------------------ |
| Template source | `packages/cli/src/templates/common/bundled-skills/trellis-meta/` |
| Template reader | `getBundledSkillTemplates()` reads complete skill directories |
| Template resolver | `resolveBundledSkills()` resolves placeholders across `SKILL.md` and `references/**` |
| Template writer | `writeSkills()` writes workflow skills plus bundled multi-file skills |
| Template tracking | `collectSkillTemplates()` includes every bundled skill file for update hash tracking |
Every platform skill root now receives `trellis-meta/SKILL.md` plus its reference files during `trellis init` and `trellis update`.
### Pi subagent launcher and config
The generated Pi extension now launches nested Pi subagents through a Windows-safe process path and supports per-agent model settings.
| Capability | beta.17 behavior |
| ---------------- | ------------------------------------------------------------------------------------------------------- |
| CLI resolution | Resolves `@mariozechner/pi-coding-agent/dist/cli.js` and runs it with `process.execPath` when available |
| Fallback | Uses `spawn("pi", ...)` when no JS entrypoint is found |
| Prompt transport | Sends delegated prompts through stdin instead of argv |
| Output mode | Runs child Pi with `--mode text -p --no-session` |
| Context | Forwards `TRELLIS_CONTEXT_ID` into child processes |
| Cancellation | Wires `AbortSignal` to child process kill/reject behavior |
| Output bounds | Keeps bounded stdout/stderr buffers with truncation notices |
Subagent run configuration can come from `.pi/agents/*.md` frontmatter or per-call tool input:
```yaml theme={null}
---
model: anthropic/claude-sonnet-4
thinking: high
fallbackModels:
- openai/gpt-5-mini
---
```
The extension maps those fields to Pi CLI args:
| Input | Child Pi args |
| -------------------- | --------------------------------------------------------------------------- |
| `model` + `thinking` | `--model <model>:<thinking>` unless the model already has a thinking suffix |
| `model` only | `--model <model>` |
| `thinking` only | `--thinking <level>` |
Pi still keeps Trellis workflow skills under `.pi/skills`. Shared `.agents/skills` remains deferred until the shared skill text is platform-neutral.
### Workflow task slug wording
The Trellis brainstorm instructions now state that `task.py create --slug <auto>` receives a slug without a date prefix.
`task.py create` adds the `MM-DD-` directory prefix automatically, so command examples no longer imply that callers should include the date in `--slug`.
## Behavior Changes
### Init completion output
`trellis init` no longer prints the promotional completion block.
The init completion path now stays focused on generated files, next actions, and testable onboarding output. Integration coverage asserts that the removed promotional pain-point copy does not return.
## Bug Fixes
### Subagent context wiring
Generated and dogfood platform files now preserve subagent context more consistently across host-specific payload formats.
| Host / file | beta.17 behavior |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `.claude/hooks/inject-subagent-context.py` | Parses Cursor-style custom subagent payloads such as `{ custom: { name } }` and `{ type: { case: "custom", value: { name } } }` |
| `.claude/hooks/inject-workflow-state.py` / `.codex/hooks/inject-workflow-state.py` | Workflow-state breadcrumbs require exact `trellis-implement`, `trellis-check`, or `trellis-research` agent names |
| `.cursor/hooks/session-start.py` | Persists `TRELLIS_CONTEXT_ID` through `CLAUDE_ENV_FILE` for later Bash commands when that bridge is available |
| `AGENTS.md` template | Documents that subagents must complete before yielding and when to spawn them |
These changes keep `implement.jsonl` and `check.jsonl` context loading tied to the Trellis agent names that receive injected task context.
## Upgrade
Existing projects:
```bash theme={null}
trellis update
```
No `--migrate` flag is required for this beta.
# v0.5.0-beta.18
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.18
2026-04-29
Beta.18 redesigns Phase 3 of the workflow: a new `Phase 3.4 Commit changes` step lets the AI batch commits of this session's edits, and `/trellis:finish-work` refocuses on archive + journal, refusing to run on a dirty working tree. Also fixes parent-task progress regression on child archive, hash-tracks `AGENTS.md` during `trellis update`, and supports OpenCode PowerShell context injection on Windows.
## Enhancements
### Phase 3.4 Commit changes
`workflow.md` Phase 3 gains a required `3.4 Commit changes` step that drives the commit cadence for the AI rather than leaving it to the user.
| Step | What the AI does |
| ---- | ------------------------------------------------------------------------------------------------------------ |
| 1 | Runs `git status --porcelain` to snapshot every dirty path |
| 2 | Runs `git log --oneline -5` to learn the repo's commit-message style (prefix, language, length) |
| 3 | Classifies dirty files into `AI-edited this session` and `Unrecognized` groups |
| 4 | Drafts a multi-commit plan, one batch per coherent change unit |
| 5 | Presents the plan once for one-shot user confirmation |
| 6 | On confirmation: runs `git add` + `git commit` per batch, no `--amend`, no `git push` |
| 7 | On rejection ("不行" / "我自己来" / "manual" / any pushback): exits to manual mode, no second plan, no flag needed |
The Wrap-up reminder previously at `3.4` renumbers to `3.5`. The `[workflow-state:completed]` breadcrumb (and the four hook fallbacks in `inject-workflow-state.py` / `inject-workflow-state.js`) now point users at `/trellis:finish-work` instead of the legacy `task.py finish` + `task.py archive` sequence.
### `/trellis:finish-work` refocuses on survey + archive + journal
The skill drops its old "Remind user to commit" step and gains a survey step that surfaces completed-but-unarchived tasks for one-shot cleanup. The new flow is:
| Step | Action |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | `get_context.py --mode record` prints active tasks, git status, and recent commits. If other completed tasks beyond the current one surface, prompt once: "archive these N too? \[y/N]" |
| 2 | `git status --porcelain`, excluding paths under `.trellis/workspace/` and `.trellis/tasks/` (managed by the script auto-commits). Bails out if anything else is dirty. |
| 3 | `task.py archive <task>` for the active task (always) and any extra confirmed in Step 1. Each produces a `chore(task): archive ...` commit |
| 4 | `add_session.py --commit <hashes>` writes the session journal (produces `chore: record journal` commit). Hashes come from Step 1's `Recent commits` list |
Final git log order is `<work commits from 3.4>` → `chore(task): archive ...` (one or more) → `chore: record journal`, never interleaved.
The common skill template uses `{{CMD_REF:finish-work}}` so each platform's `cmdRefPrefix` resolves correctly: `/trellis:finish-work` for Claude Code and OpenCode, `$finish-work` for Codex, `/trellis-finish-work` for Cursor.
## Bug Fixes
### Parent-task progress no longer regresses on child archive
`task.py list` previously dropped completed children from the parent's `[x/y done]` count whenever a child task was archived.
| Scenario | Before beta.18 | beta.18 |
| ------------------------------------ | -------------- | ------------ |
| 6 children, 1 completed and archived | `[0/5 done]` | `[1/6 done]` |
| 6 children, 2 completed and archived | `[0/4 done]` | `[2/6 done]` |
`cmd_archive` no longer removes the archived child name from the parent's `children` list, and `children_progress` treats children missing from active statuses as completed (`cmd_archive` always sets `status=completed` before moving the directory). The invariant is documented in `.trellis/spec/cli/backend/script-conventions.md` → "Parent-child invariant".
### `AGENTS.md` hash-tracked during `trellis update`
Pre-0.5.0-beta.18 projects wrote `AGENTS.md` without recording its template hash, which surfaced as a false "modified by you" conflict on update. Beta.18 introduces:
| Mechanism | Behavior |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `<!-- TRELLIS:START -->` block | Marks the Trellis-managed region inside `AGENTS.md`; `update` only replaces this block, never user content outside it |
| `LEGACY_UNTRACKED_AGENTS_MD_BLOCK_HASHES` allowlist | Pristine pre-beta.18 block hashes (e.g. `c1f511b1...`) are accepted silently so old untouched projects update without prompting |
| Hash tracking | `template-hash.ts` records the new template's hash going forward, so subsequent updates use normal classification |
User customizations outside the Trellis block are preserved.
### OpenCode PowerShell context injection on Windows
`inject-subagent-context.js` now picks the correct shell syntax based on `host.platform`:
| Platform | Injected prefix |
| -------- | ---------------------------------------------- |
| `win32` | `$env:TRELLIS_CONTEXT_ID = '<key>'; <command>` |
| Other | `export TRELLIS_CONTEXT_ID='<key>'; <command>` |
The explicit-assignment dedup detector matches both POSIX (`TRELLIS_CONTEXT_ID=...`, `export TRELLIS_CONTEXT_ID=...`) and PowerShell (`$env:TRELLIS_CONTEXT_ID = ...`) forms, so manually-prefixed commands are not double-wrapped.
## Internal
### Vitest test isolation: strip host-shell session env vars
A new `packages/cli/test/setup.ts` is registered via `setupFiles` in `vitest.config.ts`. It deletes `process.env.TRELLIS_CONTEXT_ID` and `process.env.OPENCODE_RUN_ID` at vitest process start so the OpenCode resolver tests no longer pick up a Claude/OpenCode host-session env var that would hijack the platform-input-derived `contextKey`. The pattern is documented in `.trellis/spec/cli/unit-test/conventions.md` → "Test Isolation".
### Spec updates
| Spec file | Addition |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `.trellis/spec/cli/backend/script-conventions.md` | Parent-child `children` list invariant — historical list, not pruned on archive, `children_progress` semantics |
| `.trellis/spec/cli/unit-test/conventions.md` | Test Isolation pattern — strip host-shell session env vars in vitest setup |
## Upgrade
Existing projects:
```bash theme={null}
trellis update
```
No `--migrate` flag is required for this beta.
# v0.5.0-beta.19
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.19
2026-04-29
Beta.19 hot-fixes a regression in beta.18 that could overwrite a hand-authored `AGENTS.md` during `trellis update`.
## Bug Fixes
### `AGENTS.md` content no longer clobbered when TRELLIS markers are absent
Beta.18 introduced a `<!-- TRELLIS:START -->` / `<!-- TRELLIS:END -->` managed-block replacement for `AGENTS.md`. The fallback path — taken when the existing file does not contain the markers — returned the bare Trellis template, which silently replaced the user's content during `trellis update`.
| Pre-existing `AGENTS.md` state | Beta.18 (regressed) | Beta.19 |
| ---------------------------------------- | ----------------------------------- | --------------------------------------------------------- |
| Has `TRELLIS:START` / `TRELLIS:END` | Replace block, keep outside content | Same (unchanged) |
| No markers, hand-authored or pre-beta.18 | **Whole file overwritten** | User content preserved; managed block appended at the end |
| File does not exist | Write fresh template | Same (unchanged) |
The fix lives in `buildAgentsMdTemplate` (`packages/cli/src/commands/update.ts`); the new fallback extracts the managed block from the canonical template via `getTrellisManagedBlock` and appends it after the existing content with a blank line separator. Recovery for projects that already lost content: `git checkout <pre-update-commit> -- AGENTS.md` and rerun `trellis update` on beta.19.
### Test coverage
Added `#4d preserves user AGENTS.md without TRELLIS markers by appending the managed block` in `packages/cli/test/commands/update.integration.test.ts`. The previous suite covered the legacy-pristine (`#4b`) and user-modified-managed-block (`#4c`) cases but missed the no-markers-at-all case where the regression was hiding.
## Upgrade
Existing projects:
```bash theme={null}
trellis update
```
No `--migrate` flag is required for this beta.
# v0.5.0-beta.2
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.2
2026-04-20
## Bug fixes
* **`[b] Backup-rename` in the confirm prompt now actually writes an inline `.backup` copy.** Previously it and `[r] Rename anyway` executed the exact same code path — both just relied on the full project snapshot at `.trellis/.backup-<timestamp>/`. The prompt's promise of "keeps a .backup copy" was misleading.
Now `backup-rename` writes `<new-path>.backup` (for rename) or `<from>.backup` (for delete) alongside the normal operation, so you can diff/merge your customizations against the new template without digging through the full snapshot. The prompt label now states the concrete artifact path.
Default choice stays `backup-rename` (safest — pressing Enter never destroys edits). Pick `[r]` only when you're sure your local edits are fine to move as-is.
No project file migrations in this release — pure CLI-side fix.
## Migration
Run `trellis update` to pick up the new CLI behavior. If upgrading directly from 0.4.x, add `--migrate` (the 0.5.0-beta.0 breaking-change gate still applies).
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.3
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.3
2026-04-20
## Bug fixes
* **`update.skip` no longer leaves breaking-release upgrades half-migrated.** Previously, projects with paths under `update.skip` in `.trellis/config.yaml` upgraded inconsistently across a breaking release: `rename` migrations already ignored skip, but `safe-file-delete` and template writes honored it. Result: users ended up half-migrated — old deprecated files persisted under skip-protected paths, new commands like `continue.md` never landed, and every future update re-flagged the same mess.
Now when the current upgrade spans a manifest with `breaking: true + recommendMigrate: true` **and** the user passed `--migrate`, `update.skip` is bypassed for all three operations:
1. `safe-file-delete` migrations
2. New file writes (e.g. the 0.5.0 `continue.md` command)
3. Template updates for existing files (e.g. 0.5.0 `finish-work.md`)
User customizations are still guarded — the per-file "Modified by you" confirm prompt still fires at write time. And the hash check in `allowed_hashes` is still the ultimate safety net for safe-file-delete (hash-mismatch files stay put with a `skip-modified` warning regardless of bypass).
Non-breaking updates continue to respect `update.skip` exactly as before — only breaking releases trigger the bypass.
A new yellow `⚠ update.skip BYPASSED` notice appears in the breaking-change warning block so users aren't surprised when skip-protected files get cleaned up during the migration.
No project file migrations in this release — pure CLI-side fix.
## Migration
If your 0.4.x → 0.5 beta.2 upgrade left `update.skip`-protected paths half-migrated (old commands and skills sitting next to new ones), this release will finish the job:
```bash theme={null}
trellis update --migrate
```
You'll see the yellow `⚠ update.skip BYPASSED` notice listing the files that will finally get cleaned up.
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.4
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.4
2026-04-20
## Bug fixes
* **`.trellis/workflow.md` is now actually updated by `trellis update`.** Critical fix for 0.5 upgrades.
workflow\.md was explicitly **excluded** from `collectTemplateFiles` since early Trellis versions, under the assumption that it's "user-customizable documentation, written once at init, never touched by update". That assumption broke in 0.5.0 because workflow\.md started carrying **script-parsed structure**:
* `## Phase Index` — read by `get_context.py --mode phase`
* `## Phase 1/2/3` headings — inlined into the 9.5 KB SessionStart payload
* `[workflow-state:STATUS]` tag blocks — consumed by the per-turn breadcrumb hook
Users upgrading from 0.4.x → 0.5 ended up with `get_context.py` reporting `Phase Index section not found in workflow.md` and the new `/continue` command unable to resolve step routing.
**workflow\.md is now included in the normal update flow.** Unmodified copies auto-update, user-modified copies go through the existing "Modified by you" confirm prompt with diff. `workspace/index.md` stays excluded — it's runtime-appended by `add_session.py` and has no script-parsed structure.
## Upgrade path for users stuck on beta.0..beta.3
If you already upgraded to any earlier 0.5 beta and see `Phase Index section not found`:
```bash theme={null}
trellis update --migrate
```
* If you never edited workflow\.md: it auto-updates (shows in "Template updated (will auto-update)" section)
* If you edited workflow\.md: you'll get a `Modified by you` confirm prompt with diff. Pick `[1] Overwrite` to get the new 0.5 structure, or pick `[3] Skip` and merge your edits into the new template manually (the template is at `packages/cli/dist/templates/trellis/workflow.md` inside the globally installed CLI)
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.5
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.5
2026-04-20
## Breaking Changes
* **Sub-agents renamed: `implement` / `check` / `research` → `trellis-implement` / `trellis-check` / `trellis-research`** across all 10 platforms (claude, cursor, opencode, codex, kiro, gemini, qoder, codebuddy, copilot, droid).
The old generic names were colliding with user-defined agents and, on some platforms, getting matched by the main agent's description heuristics. Prefixing with `trellis-` makes them unambiguously Trellis sub-agents that only fire when you explicitly want them.
`workflow.md`, the copilot start prompt, `shared-hooks/inject-subagent-context.py` constants, and the configurator's pull-based prelude detection are all updated. If you wrote a custom command or script that calls `Task(subagent_type: "implement", ...)`, you need to change it to `trellis-implement` yourself.
## Bug Fixes
* **Dropped `model: opus` from all agent frontmatters.** This was a real money bug for Cursor users.
All 18 markdown agent templates shipped with `model: opus` hardcoded in frontmatter, plus three `Task()` examples in `copilot/prompts/start.prompt.md` that said `model: "opus"`. The effect per platform:
* **Claude Code**: silently overrode the user's selected model for every sub-agent run (all work pinned to Opus regardless of preference).
* **Cursor**: mapped `opus` to Claude Opus billing — \~5× Sonnet pricing. One tester reported "差点给我跑破产" ("almost went bankrupt on me") before noticing.
* **Gemini / Droid / Codebuddy / Qoder**: `opus` isn't a valid model identifier for these platforms — at best ignored, at worst broke.
Agents now inherit whatever model the user's platform session is configured to use. This matches user expectation: if you set Sonnet in Cursor, sub-agents run on Sonnet.
## Upgrade
```bash theme={null}
trellis update --migrate
```
* **Unmodified agent files**: auto-renamed via hash check (30 rename entries across 10 platforms).
* **Customized agent files**: you'll see the standard `Modified by you` confirm prompt with diff. Pick `[1] Overwrite` to adopt the new name, or `[3] Skip` if you want to keep your custom agent — but then you must also update `workflow.md`, skill prompts, and hook constants yourself to point at whatever name you kept.
`update.skip` is bypassed for this release (breaking + recommendMigrate both true when invoked with `--migrate`) to prevent a half-migrated state where `workflow.md` references `trellis-implement` but your `.claude/agents/` still contains the old `implement.md`.
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.6
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.6
2026-04-20
## Bug Fixes
* **Codex `trellis-check` was shipped read-only, contradicting its own contract.**
`packages/cli/src/templates/codex/agents/trellis-check.toml` had `sandbox_mode = "read-only"` and framed itself as "Read-only Trellis reviewer focused on correctness". Every other platform's check agent has `Read, Write, Edit` tools and the description explicitly says "Reviews code changes against specs **and self-fixes issues**". `workflow.md` § Phase 2.2 is unambiguous:
> The check agent's job:
>
> * Review code changes against specs
> * Auto-fix issues it finds
> * Run lint and typecheck to verify
Result for Codex users: `trellis-check` would produce findings but could not touch the filesystem, forcing the main agent to manually apply every fix. This is a silent contract violation, not just a permissions issue — the workflow assumes check closes the loop.
Fixed by:
* `sandbox_mode = "workspace-write"` (same as `trellis-implement` and `trellis-research` on codex)
* Rewrote `developer_instructions` to instruct self-fix directly, re-run lint/type-check until green, and emit a `Findings (fixed)` / `Findings (not fixed)` / `Verification` report — behaviorally identical to the Claude Code / Cursor check agent.
## Upgrade
```bash theme={null}
trellis update
```
Not a breaking release. `update.skip` is respected. If you haven't customized `.codex/agents/trellis-check.toml`, it auto-updates; if you have, you'll see the standard `Modified by you` confirm prompt with diff.
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.7
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.7
2026-04-20
## Bug Fixes
* **OpenCode plugins were incompatible with OpenCode 1.2.x.** Users saw OpenCode crash on startup with:
```
TypeError: fn3 is not a function. (In 'fn3(input)', 'fn3' is an instance of Object)
at <anonymous> (src/plugin/index.ts:90:28)
```
Root cause: we shipped plugins as `export default { id, server: async (...) => hooks }` — an object. OpenCode 1.2.x's plugin loader (`packages/opencode/src/plugin/index.ts`) does this:
```ts theme={null}
for (const [_name, fn] of Object.entries(mod)) {
const init = await fn(input) // ← line 90: expects fn to be a function
hooks.push(init)
}
```
It iterates **every** module export (including `default`) and calls each one as a function. Our object export was never unwrapped — the runtime has no special case for a `server:` property, so `{ id, server }(input)` threw `fn is not a function`.
Fixed across all 3 plugins (`inject-subagent-context.js`, `inject-workflow-state.js`, `session-start.js`) by switching to the current factory-function shape:
```js theme={null}
export default async ({ directory, client }) => {
const ctx = new TrellisContext(directory)
return {
"tool.execute.before": async (input, output) => { /* ... */ },
"chat.message": async (input, output) => { /* ... */ },
}
}
```
This matches the documented `Plugin` type in `@opencode-ai/plugin`: `(input: PluginInput) => Promise<Hooks>`.
**Impact**: any Trellis version (including 0.4.x stable) configured for OpenCode was affected as soon as OpenCode updated to 1.2.x. Upgrade to `@mindfoldhq/trellis@beta` to restore startup.
## Upgrade
```bash theme={null}
trellis update
```
Not breaking. `update.skip` is respected. The 3 plugin files auto-update if you haven't modified them; standard `Modified by you` confirm prompt with diff if you did.
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.8
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.8
2026-04-20
## Bug Fixes
### 1. `trellis update` now actually delivers opencode changes (follow-up to beta.7)
Beta.7 fixed the OpenCode 1.2.x plugin factory-function shape in CLI templates. But users running `trellis update` on existing projects reported their `.opencode/plugins/*.js` was **still broken** — the fix wasn't reaching them.
Root cause: `packages/cli/src/configurators/index.ts` had this for opencode:
```ts theme={null}
opencode: {
configure: configureOpenCode,
// ← no collectTemplates!
},
```
Every other configured platform had a `collectTemplates` function returning the platform's file set for hash-tracked update. OpenCode was the only exception — an old omission, not a design choice. Consequence: `collectPlatformTemplates("opencode")` returned `undefined`, so `trellis update` silently skipped the entire `.opencode/` tree. Any CLI-side change to opencode (plugin logic, agent prompts, lib utilities, `package.json` deps) would ship on `init` but never propagate on `update`.
Fixed by adding `collectOpenCodeTemplates()` that walks the opencode template directory and returns `{ .opencode/agents/*, .opencode/plugins/*, .opencode/lib/*, .opencode/package.json, .opencode/commands/trellis/*, .opencode/skills/*/SKILL.md }`. `configureOpenCode` (init) was refactored to use the same enumeration, so init and update write byte-identical file sets.
### 2. Windows hook-path ENOENT after `cd` in Bash tool
Reported by a user running Claude Code on Windows in a monorepo:
```
UserPromptSubmit operation blocked by hook:
[python .claude/hooks/inject-workflow-state.py]:
can't open file 'E:\IdeaProjects\ai-codeview\frontend\.claude\hooks\inject-workflow-state.py':
[Errno 2] No such file or directory
```
The file lives at `E:\IdeaProjects\ai-codeview\.claude\...` (project root), not under `frontend/`. Claude Code's Bash tool had changed cwd to `frontend/` during an earlier command, and by default that cwd **persists** into subsequent hook invocations. The UserPromptSubmit hook command — `python .claude/hooks/inject-workflow-state.py` — resolved the relative path against the stuck cwd and couldn't find the file.
Fixed by pinning `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1` in `.claude/settings.json`'s `env` block:
```json theme={null}
{
"env": {
"CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1"
},
"statusLine": { ... },
"hooks": { ... }
}
```
Claude Code reads this variable internally — no shell expansion involved — so it works identically on macOS, Linux, and Windows. The Bash tool now returns to project root after every command, and hooks always run with cwd at the project root.
We considered rewriting hook commands to use `$CLAUDE_PROJECT_DIR` but dropped that approach — [CC issue #6023](https://github.com/anthropics/claude-code/issues/6023) confirms `$VAR` syntax doesn't expand on Windows cmd/PowerShell, which would have made the Windows problem worse.
## Upgrade
```bash theme={null}
trellis update
```
Not breaking.
* **opencode**: on any beta \< 0.5.0-beta.7 with opencode configured, this release auto-updates the 3 plugin files + `trellis-*` agents + `lib/trellis-context.js` + `.opencode/package.json` to current templates. Hash-matched auto-update for unmodified copies; standard `Modified by you` confirm prompt with diff if customized.
* **claude settings**: if you haven't modified `.claude/settings.json`, it auto-updates. If you customized it (e.g. added your own hooks), you'll see the `Modified by you` prompt — pick `[1] Overwrite` to adopt the new env block, or `[3] Skip` and manually add `"env": { "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1" }` to your settings to get the Windows fix.
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.9
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.9
2026-04-22
Accumulated since beta.8: new joiner-onboarding task, polyrepo detection, AI-facing bootstrap PRDs, workflow tightening on all platforms, Qoder session-boundary command split, task.json schema unification, and orphan-script cleanup. Not breaking; no `--migrate` required.
## New Features
### 1. Joiner onboarding task
`trellis init` now dispatches on two filesystem flags:
| `.trellis/` | `.trellis/.developer` | Generated task |
| ----------- | --------------------- | ---------------------------------------------- |
| missing | n/a | `00-bootstrap-guidelines` (creator, unchanged) |
| present | missing | `00-join-<slug>` (new: joiner flow) |
| present | present | none (same-dev re-init) |
`.trellis/.developer` is the per-checkout signal because it's listed in `.trellis/.gitignore` and therefore absent on fresh clones. `.trellis/workspace/<name>/` cannot serve this role — it's committed to git.
The joiner task is auto-set as the current task, so the new developer's first `/trellis:continue` lands on an onboarding PRD covering four topics: Trellis workflow, runtime mechanics (SessionStart hook, `<workflow-state>` injection, `trellis-implement` / `trellis-check` sub-agents, per-task jsonl manifests), project spec (`.trellis/spec/`), and assigned-work lookup via `task.py list --assignee <name>`.
### 2. AI-facing bootstrap / joiner PRDs
Both onboarding PRDs are now addressed to the AI, not the developer. Opening line:
```
**You (the AI) are running this task. The developer does not read this file.**
```
Content shifted from user-facing prompts (`Ask AI:`, `Read workflow.md`) to AI-side instructions (`Explain`, `Summarize X for them`, `If archive is empty, skip — don't invent examples`). Each PRD ends with a "Suggested opening line" template used verbatim on first response.
### 3. Polyrepo detection
`detectMonorepo()` gains a 7th parser that scans up to 2 levels deep for sibling `.git` directories or worktree gitlinks. Fires only when all 6 workspace parsers miss and no submodules are declared — workspace configs (pnpm-workspace.yaml, Cargo workspaces, etc.) take precedence.
* `DetectedPackage` gains `isGitRepo: boolean` (mutually exclusive with `isSubmodule`)
* `writeMonorepoConfig` emits `git: true` to bridge to the runtime schema already consumed by `get_git_packages()` in `config.py`
* `--monorepo` failure prints a 7-marker checklist + manual `config.yaml` example instead of a one-line error
* Init confirm prompt labels polyrepo packages with `(git repo)`
* `config.yaml` template documents the `git: true` field
Covers the "meta-repo" layout (multiple independent repos under a parent directory).
## Workflow Tightening (all platforms)
### 4. Task-creation trigger words
`workflow.md [workflow-state:no_task]` + `shared-hooks/inject-workflow-state.py` + OpenCode plugin now list explicit trigger words that require a task:
* **Chinese**: `重构` / `抽成` / `独立` / `分发` / `拆出来` / `搞一个` / `做成` / `接入` / `集成`
* **English**: `refactor` / `rewrite` / `extract` / `productize` / `publish` / `build X` / `design Y`
Exemption requires all three: (a) zero file writes this turn, (b) answer fits one reply, (c) no external research. Otherwise: create a task.
### 5. Research delegation
`common/skills/brainstorm.md` adds a "Delegate to trellis-research sub-agent" section with anti-pattern:
> Inline WebFetch/WebSearch (3+ calls) in the main session is an anti-pattern. Correct pattern: spawn `trellis-research` sub-agent via Task tool. Sub-agent writes findings to `{TASK_DIR}/research/<topic>.md`; returns path + one-line summary.
`workflow.md [workflow-state:in_progress]` renames the flow description from generic verbs (`implement → check → update`) to concrete agent types (`trellis-implement → trellis-check → trellis-update-spec → finish`).
## Qoder UX Fix
### 6. Session-boundary commands split out of the skill matcher
Before beta.9, all Qoder Trellis entry points — including `finish-work` and `continue` — lived as `.qoder/skills/trellis-*/SKILL.md`. Invocation was nondeterministic (depended on the skill matcher scoring user phrasing against each skill's description).
Now session-boundary commands are Qoder Custom Commands:
* `.qoder/commands/trellis-finish-work.md` (YAML frontmatter: `name`, `description`)
* `.qoder/commands/trellis-continue.md`
Users invoke via `/trellis-finish-work` / `/trellis-continue` (exact match).
Auto-trigger workflows (`brainstorm`, `before-dev`, `check`, `update-spec`, `break-loop`) remain as `.qoder/skills/trellis-<name>/SKILL.md`.
Infra change in `configurators/shared.ts`:
* New `wrapWithCommandFrontmatter(filePath, content)` helper
* New `COMMAND_DESCRIPTIONS` registry (short, imperative, distinct from `SKILL_DESCRIPTIONS` prose for the matcher)
* `collectBothTemplates` takes an optional `wrapCmd` callback
## Internal Cleanup
### 7. `task.json` schema unification
New shared factory in `packages/cli/src/utils/task-json.ts`:
```ts theme={null}
export type TaskJson = { /* 24 canonical fields */ };
export function emptyTaskJson(overrides?: Partial<TaskJson>): TaskJson;
```
Mirrors the shape produced by `.trellis/scripts/common/task_store.py cmd_create`. Now used by:
* `init.ts getBootstrapTaskJson` (bootstrap task writer)
* `update.ts` migration-task block
Fixes a gap from beta.0: `cmd_create` was canonicalized, but the two TypeScript writers kept their own divergent shapes.
Side effects:
* Migration tasks no longer emit legacy `current_phase: 0` / `next_action: [...]` (dead since Multi-Agent Pipeline removal)
* Bootstrap task checklist moved from structured `subtasks: [{name, status}]` in task.json to markdown `- [ ]` items in prd.md. `task.json.subtasks` is now `string[]` (child task dir names) across all tasks.
### 8. Orphan file cleanup
Hash-verified `safe-file-delete` entries in the manifest:
| Path | Reason | Hashes |
| -------------------------------------- | ------------------------------------------------------------------------------ | --------------------- |
| `.trellis/scripts/common/phase.py` | Multi-Agent Pipeline era orphan; not imported in 0.5 | 1 |
| `.trellis/scripts/create_bootstrap.py` | Legacy 4th task.json writer, replaced by `init.ts getBootstrapTaskJson` in 0.4 | 3 (covers 0.3+ users) |
Pristine copies auto-delete; locally-modified copies preserved with a warning.
Related dead code removed:
* `TaskData` TypedDict (`common/types.py`): drops `current_phase: int` and `next_action: list[dict]` fields
* `script-conventions.md` spec: removes `phase.py` / `create_bootstrap.py` / `multi_agent/` from directory trees
### 9. Orphan markdown templates removed
`packages/cli/src/templates/markdown/spec/`: removed 5 orphan `.md` files never imported by `markdown/index.ts`:
* `spec/backend/index.md`
* `spec/backend/directory-structure.md`
* `spec/backend/script-conventions.md`
* `spec/guides/code-reuse-thinking-guide.md`
* `spec/guides/cross-platform-thinking-guide.md`
These shipped in `dist/` as dead weight (\~35 KB) but never landed on user disks (paired `.md.txt` stubs are what the configurator writes). No migration entry needed. Resolves a duplication bug present since early 0.1.x.
## Upgrade
```bash theme={null}
trellis update
```
Not breaking.
* **All platforms**: `workflow.md` + shared hooks auto-sync the trigger-words + research-delegation changes. Hash-matched auto-update; `Modified by you` prompt if customized.
* **Qoder**: old `.qoder/skills/trellis-{finish-work,continue}/SKILL.md` hash-verified auto-delete; new `.qoder/commands/trellis-{finish-work,continue}.md` written by the configure step.
* **Python scripts**: `phase.py` + `create_bootstrap.py` hash-verified auto-delete from `.trellis/scripts/`.
* **Existing tasks**: untouched. Python readers (`task.py`, `get_context.py`) treat missing canonical fields as `None`. Newly-created bootstrap / migration tasks from beta.9 onward produce the canonical shape.
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-rc.0
Source: https://docs.trytrellis.app/changelog/v0.5.0-rc.0
2026-04-30
`v0.5.0-rc.0` is the release candidate before the 0.5.0 stable release. This build focuses on release stabilization: non-interactive init recovery, workflow breadcrumbs reading from `workflow.md`, automatic `workflow.md` breadcrumb updates, and bundled `trellis-meta` reference updates.
## Enhancements
### Workflow breadcrumbs
Per-turn workflow breadcrumbs, the short prompts that tell the AI which workflow step it is in, now read from `.trellis/workflow.md` `[workflow-state:STATUS]` blocks.
| Component | Change |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `packages/cli/src/templates/shared-hooks/inject-workflow-state.py` | Removes `_FALLBACK_BREADCRUMBS`; missing tags degrade to a generic `Refer to workflow.md` message |
| `packages/cli/src/templates/opencode/plugins/inject-workflow-state.js` | Removes the OpenCode JS fallback dictionary |
| `.trellis/workflow.md` / template copy | Adds required Phase 1.3 jsonl curation to `planning`; adds Phase 3.4 commit before `/trellis:finish-work` to `in_progress` |
| `packages/cli/src/templates/shared-hooks/session-start.py` | Strips full breadcrumb tag blocks from SessionStart payloads so the same body is not injected twice |
The parser and stripper both require matched tag pairs:
```md theme={null}
[workflow-state:planning]
...
[/workflow-state:planning]
```
### Automatic `workflow.md` breadcrumb updates
`trellis update` now refreshes the `[workflow-state:*]` blocks in `.trellis/workflow.md`. Hooks read those blocks to tell the AI what to do next; normal prose outside the blocks is still left alone.
| Case | Behavior |
| ------------------------------------------ | ----------------------------------------------------------------------------------------- |
| User file has a matching status block | Replace that block body with the CLI template block |
| User file is missing a status block | Append the missing block to the end of `workflow.md` |
| User changed content outside tag blocks | Preserve it verbatim |
| User changed prompt text inside tag blocks | Replace it with the current CLI version and print a warning listing the affected statuses |
The implementation lives in `buildWorkflowMdTemplate` (`packages/cli/src/commands/update.ts`).
### Session active task after `task.py create`
`task.py create` now best-effort sets the session active-task pointer. The planning breadcrumb becomes reachable immediately after creating a task, so the AI sees Phase 1.1 through Phase 1.4 guidance instead of falling back to the no-task path.
`trellis continue` also routes by `task.json.status` plus required artifacts, including the Phase 1.4 activation branch after `prd.md` and jsonl context are ready.
### Bundled `trellis-meta` references
The bundled `trellis-meta` skill now describes how workflow-state reads `workflow.md` consistently across its reference pages:
| Reference | Update |
| ------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `customize-local/change-workflow.md` | Explains that `[workflow-state:STATUS]` blocks are parsed by runtime hooks |
| `customize-local/change-task-lifecycle.md` | Adds session active-task pointer notes for `task.py create` / `task.py start` |
| `local-architecture/context-injection.md` | Points workflow-state injection at `workflow.md` instead of duplicated hook fallback text |
| `platform-files/hooks-and-settings.md` | Aligns hook descriptions with current workflow-state behavior |
## Bug Fixes
### Non-interactive `trellis init --yes`
`trellis init --yes` now stays non-interactive when files already exist.
| Layer | Fix |
| --------------------------------------- | ---------------------------------------------------------------------- |
| `packages/cli/src/commands/init.ts` | `--yes` maps write conflicts to `skip` mode unless `--force` is passed |
| `packages/cli/src/utils/file-writer.ts` | Non-TTY `ask` mode falls back to `skip` instead of prompting |
| Failure avoided | `ERR_USE_AFTER_CLOSE` from prompt code after stdin is unavailable |
`--force` still overwrites existing files. `--yes` preserves them by default.
### Aborted first-init recovery
If an earlier init wrote `.trellis/` but aborted before creating any task, rerunning init now creates the bootstrap task instead of routing to joiner onboarding.
| Disk state | Command | rc.0 behavior |
| ---------------------------------------------- | ---------------------------------------------- | ------------------------------------ |
| `.trellis/` exists, `tasks/` empty | `trellis init -u <name> --codex --yes` | Create `00-bootstrap-guidelines` |
| `.trellis/` exists, `tasks/` empty | `trellis init -u <name> --codex --yes --force` | Create `00-bootstrap-guidelines` |
| Existing project with active or archived tasks | `trellis init -u <name> --yes` | Keep normal re-init / joiner routing |
The empty-`tasks/` early check bypasses `handleReinit`, then the main dispatch's bootstrap fallback runs.
## Testing
### Init recovery coverage
The init suite now covers:
| Test file | Coverage |
| ------------------------------------------------------------ | ------------------------------------------------------------- |
| `packages/cli/test/commands/init-joiner.integration.test.ts` | Empty-`tasks/` recovery with `--yes` alone and with `--force` |
| `packages/cli/test/utils/file-writer.test.ts` | Non-TTY conflict fallback from `ask` to `skip` |
### Workflow-state coverage
Regression coverage now guards:
| Invariant | Coverage |
| ---------------------------------------------------- | ---------------------------- |
| Phase 1.3 appears in `planning` breadcrumb | `workflow.md` template test |
| Phase 3.4 commit appears in `in_progress` breadcrumb | `workflow.md` template test |
| Python / JS fallback dictionaries stay removed | Hook source tests |
| Matched tag-pair parsing | SessionStart strip test |
| Automatic `workflow.md` breadcrumb block updates | `update.integration.test.ts` |
## Upgrade
Install the RC:
```bash theme={null}
npm install -g @mindfoldhq/trellis@rc
```
Existing 0.5 beta projects:
```bash theme={null}
trellis update
```
Projects upgrading from 0.4.x:
```bash theme={null}
trellis update --migrate
```
`0.5.0-rc.0` adds no new migration entries, but 0.4.x projects still need the 0.5 migration chain that starts at `0.5.0-beta.0`.
# v0.5.0-rc.1
Source: https://docs.trytrellis.app/changelog/v0.5.0-rc.1
2026-05-01
`v0.5.0-rc.1` patches rc.0 with two OpenCode fixes ([#211](https://github.com/mindfold-ai/Trellis/issues/211), [#212](https://github.com/mindfold-ai/Trellis/issues/212)). No new migrations.
## Bug Fixes
### `trellis-research` subagent on OpenCode (#211)
`packages/cli/src/templates/opencode/agents/trellis-research.md`:
| Slice | Change |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Frontmatter `permission` | `write: allow`, `edit: allow` (were `deny`) |
| Prompt body | Replaced with the cursor/claude shape: Core Principle (PERSIST), Workflow Step 1–5 with `mkdir -p {TASK_DIR}/research/`, Scope Limits, File Format, DO/DON'T |
| Removed | "Context Self-Loading" section — `inject-subagent-context.js` already pre-loads spec dir context |
Description string updated to mention `PERSISTS every finding to the current task's research/ directory`, matching the other platforms.
The existing regression test group `regression: research agent persists findings to task dir` covered six platforms but not OpenCode. rc.1 adds an OpenCode case asserting:
* YAML `permission:` frontmatter contains `write: allow` and `edit: allow`
* Body contains `{TASK_DIR}/research/` and `PERSIST`
* Body does not contain a top-level `- Modify any files` rule
### OpenCode SessionStart plugin loading (#212)
OpenCode 1.2.x plugin loader iterates `Object.entries(mod)` and invokes every export as a plugin factory. `.opencode/plugins/session-start.js` declared two named exports (`buildSessionContext`, `hasInjectedTrellisContext`) alongside `export default`, which caused the loader to call the named exports with the factory input shape, throw, abort the load, and never reach `export default`.
Fix: extract the helpers to `packages/cli/src/templates/opencode/lib/session-utils.js`. Each plugin file now has only `export default`.
```text theme={null}
.opencode/plugins/session-start.js → export default
.opencode/plugins/inject-workflow-state.js → export default
.opencode/plugins/inject-subagent-context.js → export default
.opencode/lib/session-utils.js → buildSessionContext,
hasInjectedTrellisContext,
hasPersistedInjectedContext,
markContextInjected
```
A new regression test walks `packages/cli/src/templates/opencode/plugins/*.js` and asserts each file has exactly one top-level export, matching `^export\s+default\s/`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@rc
trellis update
```
Projects already on 0.5 (beta or rc.0) run `trellis update`. Projects upgrading from 0.4.x run `trellis update --migrate` because the 0.5 migration chain begins at 0.5.0-beta.0. rc.1 adds no new migration entries.
# v0.5.0-rc.2
Source: https://docs.trytrellis.app/changelog/v0.5.0-rc.2
2026-05-02
`v0.5.0-rc.2` adds the `trellis uninstall` command ([#221](https://github.com/mindfold-ai/Trellis/issues/221)) and patches Windows compatibility ([#218](https://github.com/mindfold-ai/Trellis/issues/218)) and Copilot custom-agent frontmatter (PR [#210](https://github.com/mindfold-ai/Trellis/pull/210)). No new migrations.
## Enhancements
### `trellis uninstall` command (#221)
Removes all files generated by trellis along with the `.trellis/` directory. The deletion list is sourced from `.trellis/.template-hashes.json`; files not listed in the manifest are not touched.
```bash theme={null}
trellis uninstall # default: list + Continue? [Y/n]
trellis uninstall --yes # skip prompt
trellis uninstall --dry-run # list then exit, no changes
```
Pre-checks:
| Condition | Behavior |
| ------------------------------------------------------ | ----------------------------------------------------------------- |
| `.trellis/` directory missing | Friendly exit 0 with `"Trellis is not installed in this project"` |
| `.trellis/` exists but `.template-hashes.json` missing | Exit 1 with hint to delete `.trellis/` manually |
| Both present | Proceed to scan + listing |
Output is split into two columns:
* **Will be deleted** — opaque files (`.py` / `.md` / `.ts`) plus structured-config files that scrub down to nothing, plus the `.trellis/` directory itself.
* **Will be modified** — structured-config files where trellis-owned entries are stripped but user-added fields are preserved.
Four scrubbers cover 11 structured config files:
| Scrubber | Files |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scrubHooksJson` (nested) | `.claude/settings.json`, `.gemini/settings.json`, `.factory/settings.json`, `.codebuddy/settings.json`, `.qoder/settings.json`, `.codex/hooks.json` |
| `scrubHooksJson` (flat) | `.cursor/hooks.json`, `.github/copilot/hooks.json` |
| `scrubOpencodePackageJson` | `.opencode/package.json` — removes `dependencies["@opencode-ai/plugin"]` |
| `scrubPiSettings` | `.pi/settings.json` — strips trellis entries from `extensions` / `skills` / `prompts` arrays; removes `enableSkillCommands` |
| `scrubCodexConfigToml` | `.codex/config.toml` — removes `project_doc_fallback_filenames` and the trellis NOTE comment block |
Command matching rule: only the last whitespace token of a `command` string (the script path) is used for comparison. Substring occurrences elsewhere (e.g. inside an `echo`) do not match.
Execution order: scrubber → `unlink` → `cleanupEmptyDirs` (prunes emptied subdirectories) → managed-root sweep (prunes empty `.claude/` / `.cursor/` / etc. top-level dirs) → `rm -rf .trellis/`. Directories that still contain user files are preserved.
Manifest-listed paths are removed unconditionally; no hash check is performed. User-modified trellis files are deleted as well.
23 new tests (15 scrubber unit + 8 integration); 830 tests pass overall.
## Bug Fixes
### Windows `python3` → `python` at write time (#218, PR [#220](https://github.com/mindfold-ai/Trellis/pull/220))
Windows has no `python3` executable. `replacePythonCommandLiterals()` runs at init/update write time on `process.platform === "win32"`:
```ts theme={null}
content
.split('\n')
.map((line) => (line.startsWith('#!') ? line : line.replaceAll('python3', 'python')))
.join('\n');
```
* **Write-time only** — template source files keep `python3`; replacement happens at file generation time.
* **Shebang preserved** — lines beginning with `#!` are not replaced.
* **Idempotent** — `python` does not contain `python3`; running multiple times produces the same result.
* **Coverage** — `configurators/{claude,codex,copilot,opencode,pi}.ts`, `configurators/shared.ts` (`writeSkills` / `writeAgents` / `writeSharedHooks` / `resolvePlaceholders` / `buildPullBasedPrelude`), `configurators/workflow.ts`, `templates/extract.ts`, `configurators/index.ts` (`collectPlatformTemplates`), `commands/update.ts` (`collectTemplateFiles`). init and update produce byte-for-byte identical output on Windows.
9 new platform-mocked unit tests in `test/configurators/shared.test.ts` cover win32/linux/darwin behavior, shebang preservation, multiline content, idempotency, and the documented `python3x` substring boundary.
### Copilot custom agent tools frontmatter (PR [#210](https://github.com/mindfold-ai/Trellis/pull/210))
`injectPullBasedPreludeMarkdown()` now uses a regex frontmatter splitter (`splitMarkdownFrontmatter`) instead of line-based scanning, handling CRLF endings cleanly. `mapLegacyToolToCopilot()` translates Claude-style tool tokens (`Read`, `Write`, `Edit`, `Glob`, ...) into Copilot's lowercase shape (`read`, `edit`, ...) so custom agents authored against the Claude convention render correctly under Copilot. Regression coverage added in `test/regression.test.ts`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@rc
trellis update
```
Projects on 0.5 (beta or earlier rc) run `trellis update`. Projects upgrading from 0.4.x run `trellis update --migrate` because the 0.5 migration chain begins at 0.5.0-beta.0. rc.2 adds no new migration entries.
# v0.5.0-rc.3
Source: https://docs.trytrellis.app/changelog/v0.5.0-rc.3
2026-05-03
Patches Gemini CLI 0.40.x template compatibility ([#224](https://github.com/mindfold-ai/Trellis/issues/224)). No new migrations.
## Bug Fixes
### Gemini CLI 0.40.x template compat (#224)
Three changes to `trellis init --gemini` output:
| File | Change |
| ------------------------------------------------------ | ---------------------------------------------------- |
| `.gemini/agents/trellis-{check,implement,research}.md` | Drop `tools:` line — sub-agent inherits parent tools |
| `.gemini/settings.json` | Hook event `UserPromptSubmit` → `BeforeAgent` |
| Shared skills destination | `.gemini/skills/` → `.agents/skills/` |
Existing Gemini installs: re-run `trellis init --gemini` or delete `.gemini/skills/` manually.
### `inject-workflow-state.py` per-platform `hookEventName`
Branches via `_detect_platform()`:
```python theme={null}
hook_event_name = (
"BeforeAgent" if _detect_platform(data) == "gemini" else "UserPromptSubmit"
)
```
### `needsCodexUpgrade()` false-positive on Gemini installs
Narrowed from any `.agents/skills/` hash entry to:
```ts theme={null}
keys.some((k) => k === '.agents/skills/trellis-continue/SKILL.md') ||
keys.some((k) => k === '.agents/skills/trellis-finish-work/SKILL.md');
```
Only Codex writes those two files. The previous broad heuristic auto-installed Codex on `trellis update` for Gemini-only projects.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@rc
trellis update
```
Projects on 0.5 (beta or earlier rc) run `trellis update`. From 0.4.x: `trellis update --migrate`.
# v0.5.0-rc.4
Source: https://docs.trytrellis.app/changelog/v0.5.0-rc.4
2026-05-05
Adds `TRELLIS_HOOKS` env var to disable Trellis hooks at runtime. No new migrations.
## Enhancements
### `TRELLIS_HOOKS=0` disables all Trellis hooks
Every shipped Trellis hook now early-returns when `TRELLIS_HOOKS=0` (or `TRELLIS_DISABLE_HOOKS=1`) is set on the host CLI process — no `additionalContext` is emitted, the host session starts clean.
| Hook | File |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Shared per-platform | `shared-hooks/session-start.py`, `inject-workflow-state.py`, `inject-subagent-context.py`, `inject-shell-session-context.py` |
| Platform-specific session-start | `codex/hooks/session-start.py`, `copilot/hooks/session-start.py` |
| OpenCode plugins | `opencode/plugins/session-start.js`, `inject-workflow-state.js`, `inject-subagent-context.js` |
Usage:
```bash theme={null}
# Wrapper for casual chat sessions — no workflow breadcrumb, no spec index
TRELLIS_HOOKS=0 claude
# Subprocess spawn — pass via env so the gate inherits to host CLI's hook subprocesses
spawn("codex", args, { env: { ...process.env, TRELLIS_HOOKS: "0" } })
```
`TRELLIS_HOOKS=0` and `TRELLIS_DISABLE_HOOKS=1` are equivalent. None of Claude Code / Codex / OpenCode / Cursor expose a true mid-session hook toggle, so the env-var gate runs at host startup.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@rc
trellis update
```
Projects on 0.5 (beta or earlier rc) run `trellis update`. From 0.4.x: `trellis update --migrate`.
# v0.5.0-rc.5
Source: https://docs.trytrellis.app/changelog/v0.5.0-rc.5
2026-05-05
Codex template enables `multi_agent_v2` with an 8-minute wait floor. `AGENTS.md` adds explicit `wait` tool rules. No new migrations.
## Enhancements
### Codex `multi_agent_v2` default-on
`.codex/config.toml` now writes the feature block instead of a commented-out hint:
```toml theme={null}
[features.multi_agent_v2]
enabled = true
max_concurrent_threads_per_session = 6
min_wait_timeout_ms = 480000
```
| Field | Value | Note |
| ------------------------------------ | ---------------- | ---------------------------------------------------------------------------------------------- |
| `enabled` | `true` | Required inside the table — the table form alone does NOT enable the feature |
| `max_concurrent_threads_per_session` | `6` | Was `4` |
| `min_wait_timeout_ms` | `480000` (8 min) | `wait()` timeout floor. Was `10000` (10 s). Forces the parent to wait through subagent runtime |
Project-level `[features]` activates only when the project is trusted. Add this to `~/.codex/config.toml`:
```toml theme={null}
[projects."/abs/path/to/your/repo"]
trust_level = "trusted"
```
### Drop legacy `codex_hooks = true`
`CodexHooks` is now `Stage::Stable` with `default_enabled: true` in Codex's feature registry, so `hooks.json` loads automatically once the project is trusted. The previous `[features].codex_hooks = true` line in the template was redundant and has been removed.
### `AGENTS.md` subagent wait rules
The Subagents section names Codex's `wait` tool and bans cancelling a subagent before it finishes:
* Wait for terminal status before yielding, acting on partial results, or spawning followups. On Codex, call `wait` with the thread id.
* Never cancel or re-spawn a subagent that hasn't finished. Raise the timeout (default 30 s, max 1 h) before judging it stuck.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@rc
trellis update
```
# v0.5.0-rc.6
Source: https://docs.trytrellis.app/changelog/v0.5.0-rc.6
2026-05-06
Windows `session-start.py` normalizes MSYS / Cygwin / WSL paths. `finish-work` Step 2 classifies dirty paths instead of aborting on any out-of-scope path. No new migrations.
## Enhancements
### `finish-work` Step 2 classifies dirty paths
For dirty paths outside `.trellis/workspace/` and `.trellis/tasks/`, Step 2 classifies into:
| Class | Action |
| ------------- | ------------------------------------------------ |
| Current task | Abort; list files; return to Phase 3.4 to commit |
| Other window | Report and continue Step 3 |
| Indeterminate | Prompt user, route by answer |
A path is classified as "current task" if it appears in the task's `prd.md` / `implement.jsonl` / `check.jsonl`, matches the task's declared scope, or was edited by the AI in this session.
Synced to 8 copies: `packages/cli/src/templates/common/commands/finish-work.md` + 5 platform copies (`.claude/`, `.cursor/`, `.opencode/`, `.pi/`, `copilot`) + 2 `SKILL.md` (`.agents/`, `codex/skills/`).
## Bug Fixes
### Windows `session-start.py`: MSYS / Cygwin / WSL paths
Fixes [#226](https://github.com/mindfold-ai/Trellis/issues/226). On Windows, `Path(val).resolve()` misparses Unix-style cwd values from Git Bash; the hook raises `ModuleNotFoundError: common` and context injection is skipped.
| Input | Normalized to |
| ------------------- | -------------- |
| `/d/Users/...` | `D:\Users\...` |
| `/cygdrive/d/...` | `D:\...` |
| `/mnt/d/...` | `D:\...` |
| `D:\...` / `D:/...` | unchanged |
Synced to 6 `session-start.py` copies: `.claude/`, `.codex/`, `.cursor/`, `templates/shared-hooks/`, `templates/codex/`, `templates/copilot/`. Non-Windows: early return.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@rc
trellis update
```
# v0.5.0-rc.7
Source: https://docs.trytrellis.app/changelog/v0.5.0-rc.7
2026-05-06
Two field-reported fixes from [#232](https://github.com/mindfold-ai/Trellis/issues/232): `trellis update` no longer downgrades the OpenCode plugin; Codex Linux sandbox `EPERM` during `python3` probe is tolerated. No new migrations.
## Bug Fixes
### `@opencode-ai/plugin` template pin: `1.1.40` → `^1.14.39`
`packages/cli/src/templates/opencode/package.json` previously hardcoded `1.1.40`. Users who manually upgraded `@opencode-ai/plugin` to 1.14.x had their `.opencode/package.json` overwritten on `trellis update`, which silently downgraded the plugin on the next `bun install` / `pnpm install`.
The new caret range pulls the latest 1.x at install time, so update no longer regresses the version.
After updating, run inside `.opencode/`:
```bash theme={null}
bun install # or pnpm/npm equivalent
```
to refresh the lockfile to the latest 1.x.
### Codex Linux sandbox: tolerate `EPERM` / `EACCES` on `python3 --version` probe
`requireSupportedPython` in `packages/cli/src/commands/init.ts` previously caught all `child_process.execSync` failures as "Python not found", aborting `trellis init`. Codex's Linux sandbox returns `EPERM` from `execSync` even when `python3` is on the host PATH — the probe was failing, not the binary.
| Error code | Old behavior | New behavior |
| ------------------------------------- | ------------------------ | --------------------------------------------------------------------------- |
| `ENOENT` (and others) | Throw "Python not found" | Same — genuine missing command still aborts |
| `EPERM` / `EACCES` | Throw "Python not found" | Warn (yellow) + proceed; assume `python3` on PATH; return "version unknown" |
| `TRELLIS_SKIP_PYTHON_CHECK=1` env var | (didn't exist) | Skip the probe entirely; return "version check skipped" |
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@rc
trellis update
```
# v0.5.1
Source: https://docs.trytrellis.app/changelog/v0.5.1
2026-05-06
Fix Codex sub-agent recursion via `SessionStart` injection ([#234](https://github.com/mindfold-ai/Trellis/issues/234)) and Cursor agent `description` field rendering. No new migrations.
## Bug Fixes
### Codex `multi_agent_v2`: fix `SessionStart` hook dispatch wording misleading sub-agents
`packages/cli/src/templates/codex/hooks/session-start.py` injects a "main session should dispatch `trellis-implement`" line when a task is in READY state. Under `multi_agent_v2` Codex runs `SessionStart` for every spawned session, so the same line reached the freshly spawned `trellis-implement` sub-agent. The sub-agent followed it and dispatched another `trellis-implement`. The outer sub-agent stayed `running` while the inner one completed; `wait_agent` in the main session timed out.
Codex `SessionStart` stdin has no agent-identity field ([`openai/codex#16226`](https://github.com/openai/codex/issues/16226)), so the hook cannot filter sub-agent sessions directly. Patched at the prompt layer:
| File | Change |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `codex/agents/trellis-implement.toml`, `trellis-check.toml` | `developer_instructions` opens with "do not dispatch `trellis-implement` / `trellis-check`" |
| `codex/hooks/session-start.py` | "if you are a sub-agent reading this, ignore the dispatch instruction" appended to the READY-state block and the `<guidelines>` block |
### `shared-hooks/session-start.py`: same as above
The same dispatch wording lives in `packages/cli/src/templates/shared-hooks/session-start.py` (Claude Code / Cursor / Gemini CLI / Qoder / CodeBuddy / Factory Droid / Kiro). The recursion has not been reported on these platforms but the trigger condition is identical to Codex. Same fix as Codex.
### Cursor: agent frontmatter `description` switched to single-line literal
`packages/cli/src/templates/cursor/agents/trellis-{research,implement,check}.md` previously used a YAML block scalar:
```yaml theme={null}
description: |
Trellis research agent. Use this exact agent ...
```
Cursor's agent parser only reads single-line `description: ...` and drops block-scalar values, leaving the UI Description field blank. Switched to single-line literals; body text unchanged.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.2
Source: https://docs.trytrellis.app/changelog/v0.5.2
2026-05-06
Fix `SessionStart` hook crash on Python ≤3.11 (`SyntaxError: f-string expression part cannot include a backslash`). No new migrations.
## Bug Fixes
### Hook session-start: PEP 498 f-string backslash in Python ≤3.11
The Windows path normalizer added in 0.5.0-rc.6 (#226) used:
```python theme={null}
return f"{drive}:\\{rest.replace('/', '\\')}"
```
PEP 498 forbids backslashes inside f-string expression parts. On Python ≤3.11 the file fails to parse, and the hook exits with code 1 before running:
```
SessionStart hook (failed)
error: hook exited with code 1
```
PEP 701 in Python 3.12 lifted the restriction, so the bug was invisible to 3.12+ users. Codex CLI 0.128 + Trellis 0.5.0 reproduced it in the field.
Fixed by lifting the `.replace(...)` call out of each f-string expression into a local variable. 9 occurrences across:
* `packages/cli/src/templates/codex/hooks/session-start.py`
* `packages/cli/src/templates/copilot/hooks/session-start.py`
* `packages/cli/src/templates/shared-hooks/session-start.py` (Claude Code / Cursor / Gemini CLI / Qoder / CodeBuddy / Factory Droid / Kiro)
Added regression coverage in `packages/cli/test/regression.test.ts`: regex scan asserts no f-string contains a backslash inside `{...}` expressions, plus a best-effort `python3 -c "ast.parse(...)"` pass.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.3
Source: https://docs.trytrellis.app/changelog/v0.5.3
2026-05-06
Fix sub-agent context injection on class-1 platforms when the PreToolUse hook silent-skips (Windows + Claude Code, `--continue` resume, fork distributions, etc.); make `task.py start` non-blocking when session identity is missing. No new migrations.
## Bug Fixes
### Class-1 sub-agents: marker-based context loading fallback
Class-1 platforms (claude / cursor / opencode / kiro / codebuddy / droid) inject sub-agent context — `prd.md` + `implement.jsonl` / `check.jsonl` content — via `PreToolUse` hook. The hook silent-skips on Windows at v2.1.119 (upstream [`anthropics/claude-code#53254`](https://github.com/anthropics/claude-code/issues/53254)); the existing sub-agent definition files trusted the hook to always fire and had no fallback, so sub-agents ran without specs.
Add marker-based dual-channel context loading:
| Layer | File | Change |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hook (success path only) | `packages/cli/src/templates/shared-hooks/inject-subagent-context.py` | Prepend `<!-- trellis-hook-injected -->` sentinel to `build_implement_prompt` / `build_check_prompt` / `build_finish_prompt` outputs |
| Sub-agent definitions | `claude/agents/`, `cursor/agents/`, `codebuddy/agents/`, `opencode/agents/`, `droid/droids/`, `kiro/agents/` (`trellis-implement` + `trellis-check`) | Open with a `Trellis Context Loading Protocol` section: marker present → hook injected, proceed directly; marker absent → read `Active task: <path>` line from dispatch prompt, then Read `prd.md` + the relevant jsonl file yourself |
| Workflow | `packages/cli/src/templates/trellis/workflow.md` | Dispatch protocol scope changed from class-2-only to all platforms (`trellis-research` excluded) |
Class-2 platforms (codex / copilot / gemini / qoder) untouched — they already use `buildPullBasedPrelude`. `trellis-research` is intentionally not marker'd because research is decoupled from active task.
### `task.py start`: non-blocking degraded mode
`task.py start` previously hard-failed (`return 1`) when `resolve_context_key()` returned `None` — i.e. when no SessionStart hook had injected `TRELLIS_CONTEXT_ID`. The error message blamed the AI session, but the real cause is upstream: Windows + Claude Code didn't source `CLAUDE_ENV_FILE` pre-v2.1.111 and still skips PowerShell tool / `--continue` resume paths.
Replace the hard-fail with a yellow-tagged degraded-mode warning, still flip `task.json.status: planning → in_progress`, and return 0 so the AI continues based on conversation context. Happy path (`resolve_context_key()` truthy) is byte-identical to before.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.4
Source: https://docs.trytrellis.app/changelog/v0.5.4
2026-05-06
Fix Trellis sub-agent recursion when a workflow-state instruction reaches a sub-agent ([`#237`](https://github.com/mindfold-ai/Trellis/issues/237)); fix `compareVersions` dropping the tail of hyphenated prereleases ([`#230`](https://github.com/mindfold-ai/Trellis/pull/230)). No new migrations.
## Bug Fixes
### Sub-agent recursion guard
`.trellis/workflow.md`'s `[workflow-state:in_progress]` block tells the main agent to dispatch `trellis-implement` / `trellis-check` sub-agents. On Codex the same block also reaches the spawned sub-agent's turn, and the sub-agent followed the rule on itself — spawning another `trellis-implement` instead of doing the work.
Two changes:
* `[workflow-state:in_progress]` scopes the dispatch rule to the main session, and adds an explicit "if you are already a `trellis-implement` / `trellis-check` sub-agent, work directly and do not spawn another one" exemption.
* Each platform's `trellis-implement` / `trellis-check` agent definition (claude / cursor / opencode / kiro / codebuddy / droid / codex / pi / gemini / qoder) carries the same exemption, so the guard holds even if the workflow-state injection is missed.
`.trellis/spec/cli/backend/workflow-state-contract.md` updated: previously claimed only the main session could see workflow-state breadcrumbs, but Codex hooks deliver them to sub-agents too.
### `compareVersions`: hyphens inside prereleases
Thanks to [@voidborne-d](https://github.com/voidborne-d) for [`#230`](https://github.com/mindfold-ai/Trellis/pull/230).
`packages/cli/src/utils/compare-versions.ts` used `a.split("-", 2)` to separate the base version from the prerelease tag. JavaScript's `split(sep, limit)` truncates the result instead of joining the tail (unlike Python's `maxsplit`):
```js theme={null}
'1.0.0-alpha-1'.split('-', 2);
// → ["1.0.0", "alpha"] // "-1" silently dropped
```
So `compareVersions("1.0.0-alpha-1", "1.0.0-alpha-2")` returned `0` — the two versions sorted as equal. Fixed. Adds 20 test cases in `packages/cli/test/utils/compare-versions.test.ts` covering base versions, release vs prerelease, hyphenated identifiers, and version-list sorting.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.5
Source: https://docs.trytrellis.app/changelog/v0.5.5
2026-05-07
Structural fix for the Codex sub-agent recursion bug ([`#240`](https://github.com/mindfold-ai/Trellis/issues/240), [`#242`](https://github.com/mindfold-ai/Trellis/issues/242)). Removes the Codex `SessionStart` hook entirely and replaces the bootstrap path with a `trellis-start` skill invoked from `UserPromptSubmit`. No new migrations.
## Bug Fixes
### Codex sub-agent recursion (turtles all the way down)
Codex fires `SessionStart` for every spawned sub-agent session and exposes no `agent_id` / `agent_type` field on the hook input ([`openai/codex#16226`](https://github.com/openai/codex/issues/16226)). So the dispatch directive in `packages/cli/src/templates/codex/hooks/session-start.py` was being injected into every sub-agent's session start payload as well — the sub-agent read "Next required action: dispatch `trellis-implement`", thought it was the main session, and spawned its own `trellis-implement`. Then that sub-agent did the same thing.
The 0.5.4 patch ([`#237`](https://github.com/mindfold-ai/Trellis/issues/237)) added a `Sub-agent self-exemption:` clause to the same prompt block, but it sat inline alongside the dispatch directive. LLMs kept picking the command-style instruction over the conditional exemption.
Structural fix:
* Removed the `SessionStart` entry from `packages/cli/src/templates/codex/hooks.json` — the heavy session-start payload no longer reaches any session, sub-agent or main.
* `packages/cli/src/templates/shared-hooks/inject-workflow-state.py` (`UserPromptSubmit`) now injects a `<trellis-bootstrap>` block on `no_task` turns that tells the AI to invoke `$trellis-start` once. The notice carries an explicit sub-agent exemption (sub-agents read the existing `<sub-agent-notice>` first and skip everything below it).
* `packages/cli/src/configurators/codex.ts` writes `.agents/skills/trellis-start/SKILL.md` for Codex. The skill content is the existing `common/commands/start.md` template wrapped with skill frontmatter.
Sub-agent sessions now only see the `<sub-agent-notice>` from the per-turn breadcrumb. No command-style "must dispatch" text exists anywhere in the new injection, so the recursion vector is gone at source.
Other agent-capable platforms (Claude Code, Cursor, OpenCode, Kiro, etc.) keep their working `SessionStart` hooks unchanged — only Codex is affected by `openai/codex#16226`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
Codex users will get a new `.agents/skills/trellis-start/SKILL.md` file and a `hooks.json` without `SessionStart` wiring. No flag needed.
# v0.5.6
Source: https://docs.trytrellis.app/changelog/v0.5.6
2026-05-07
Two prompt-layer follow-ups for Codex `multi_agent_v2`. `AGENTS.md` documents the `fork_turns="none"` requirement on `spawn_agent` calls ([`#240`](https://github.com/mindfold-ai/Trellis/issues/240) follow-up) and the deterministic close-loop algorithm for handling `wait` completion notifications ([`#241`](https://github.com/mindfold-ai/Trellis/issues/241)). No new migrations.
## Bug Fixes
### `fork_turns="none"` requirement (#240 follow-up)
[v0.5.5](/changelog/v0.5.5) removed the `SessionStart` injection vector that hijacked sub-agent sessions. [Marsor707's local-verification comment on `#240`](https://github.com/mindfold-ai/Trellis/issues/240#issuecomment-4393264022) showed a second vector remained:
> Without `fork_turns="none"`, the child can see the parent's own `spawn_agent(...)` records and then apply the Trellis/AGENTS "wait for spawned subagents" rule to itself, causing a self-wait such as `wait_agent({"timeout_ms":480000})`.
Default Codex behavior is `fork_turns="all"` — the child inherits the parent transcript including prior `spawn_agent` tool calls, and re-applies the wait rule to itself. That's another path to `wait_agent` self-deadlock independent of the SessionStart bug.
`packages/cli/src/templates/markdown/agents.md` adds a `### Codex-only — \`spawn\_agent\` parameters`subsection telling the main session to always pass`fork\_turns="none"`. Prompt-layer only — Trellis doesn't intercept`spawn\_agent\`.
### Multi-subagent close-loop algorithm ([`#241`](https://github.com/mindfold-ai/Trellis/issues/241))
The existing rule in `AGENTS.md`:
> ALWAYS wait for every spawned subagent to reach a terminal status before yielding...
Was ambiguous. Reproduction from the issue: parent dispatched two `trellis-research` sub-agents; both completed and wrote `{task_dir}/research/*.md`; parent received `completed` notifications but kept calling `wait_agent` again instead of reading deliverables and closing. User-side appearance: stuck waiting.
`packages/cli/src/templates/markdown/agents.md` adds a `### Codex-only — multi-subagent close-loop` subsection with the deterministic algorithm proposed in the issue:
1. Maintain `expected_agents` set.
2. After each `wait` update: `list_agents`, verify deliverables for terminal agents, `close_agent`, remove from set.
3. Continue waiting only if `expected_agents` still has running agents.
4. Never `wait` on an agent already reported `completed`.
Both subsections are prompt-layer-only — no script, hook, or configurator behavior changed.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
`AGENTS.md` gets two new subsections under `## Subagents`. Other platforms see the `Codex-only` labels and can skip those subsections.
# v0.5.7
Source: https://docs.trytrellis.app/changelog/v0.5.7
2026-05-08
After upgrading Codex 0.129, run `/hooks` once and approve the Trellis hook (without approval the workflow won't auto-inject; details below). New `codex.dispatch_mode` knob lets Codex projects opt into `inline` dispatch. Fixes: Codex sub-agent `wait_agent` deadlock ([`#240`](https://github.com/mindfold-ai/Trellis/issues/240) follow-up, [`#241`](https://github.com/mindfold-ai/Trellis/issues/241)), Kiro CLI rejecting agent JSON ([`#247`](https://github.com/mindfold-ai/Trellis/issues/247)), Windows `trellis init` not finding `python3` / `py -3` ([`#236`](https://github.com/mindfold-ai/Trellis/issues/236)). No new migrations.
## Codex 0.129 compatibility
### `/hooks` review gate (TUI approval required)
Codex 0.129 gates each installed hook behind a one-time `/hooks` TUI review. Until the user runs `/hooks` in Codex and approves the Trellis `UserPromptSubmit` hook, the workflow breadcrumb won't auto-inject; every fresh Codex session looks like Trellis isn't wired in.
The existing `<trellis-bootstrap>` fallback in `inject-workflow-state.py` covers this gap: when the hook hasn't fired, the fallback directs the AI to read the `trellis-start` skill manually so the workflow still runs (just less smoothly). No Trellis code change needed for the fallback. **Run `/hooks` once after upgrading Codex** to restore full auto-injection.
### `[features].codex_hooks` to `[features].hooks` rename
Codex 0.129 renamed `[features].codex_hooks` to `[features].hooks` (legacy name still works but emits a deprecation warning on startup). Trellis docs (`advanced/multi-platform`, `advanced/architecture`, `advanced/custom-hooks`, `advanced/appendix-f`, `start/install-and-first-task`, `start/everyday-use`, `start/how-it-works`), the `spec/cli/backend/platform-integration.md` rules, and the `trellis init` runtime warning now point at the new name. The uninstall scrubber recognizes both `hooks = true` and the legacy `codex_hooks = true` so older projects still clean up cleanly.
## Enhancements
### Codex configurable dispatch mode
New project-level knob in `.trellis/config.yaml`:
```yaml theme={null}
codex:
dispatch_mode: sub-agent # default; set to "inline" to skip sub-agent dispatch
```
When `inline` is set, the `<workflow-state>` breadcrumb tells the main Codex agent to load `trellis-before-dev`, edit code directly, then load `trellis-check` for lint / typecheck / tests, instead of dispatching `trellis-implement` / `trellis-check` sub-agents.
Mechanism: `inject-workflow-state.py` reads the config and resolves `[workflow-state:in_progress-inline]` / `[workflow-state:planning-inline]` blocks from `workflow.md` when codex+inline is set; `get_context.py --platform codex` swaps to the `[Kilo, Antigravity, Windsurf]` block content. Per-turn override phrases (`do it inline` / `你直接改` / etc.) keep working in both modes.
Codex-only. Class-1 platforms (Claude Code, Cursor, OpenCode, Kiro, CodeBuddy, Droid) and the other class-2 platforms keep the dispatch default. `.codex/agents/*.toml` files are still written; sub-agent infrastructure stays installed.
### `configSectionsAdded` manifest field
New optional manifest field declares which top-level keys this release introduces in `.trellis/config.yaml`:
```jsonc theme={null}
{
"version": "0.5.7",
"configSectionsAdded": [
{
"file": ".trellis/config.yaml",
"sentinel": "codex:",
"sectionHeading": "Codex (sub-agent dispatch behavior)",
},
],
}
```
`trellis update` walks each manifest's `configSectionsAdded`, and for each entry whose `sentinel` is missing from the user's target file, appends the section content extracted from the bundled template. Append-only, idempotent (sentinel check on rerun). User customizations stay untouched. Future config additions declare a new entry in their own manifest, no `update.ts` change needed per addition.
Replaces the prior "modified-file confirm prompt" path, where users who customized `config.yaml` had to either accept template (losing edits) or skip (missing the new section).
## Bug Fixes
### Codex sub-agent collab tools, structural disable ([`#240`](https://github.com/mindfold-ai/Trellis/issues/240) follow-up, [`#241`](https://github.com/mindfold-ai/Trellis/issues/241))
[v0.5.5](/changelog/v0.5.5) removed the `SessionStart` injection vector. [v0.5.6](/changelog/v0.5.6) added prompt-layer `fork_turns="none"` guidance to `AGENTS.md`. Both were prompt-layer mitigations. [Ca11back's reproduction on `#241`](https://github.com/mindfold-ai/Trellis/issues/241) showed the prompt-layer fix didn't reach reality:
* The main agent still spawned `trellis-research` with default `fork_turns="all"` despite the AGENTS.md rule.
* The child inherited the parent's transcript including prior `spawn_agent(...)` tool-call records.
* The child read AGENTS.md's "ALWAYS wait for every spawned subagent..." rule, applied it to *itself*, and called `wait_agent` on the inherited records.
* No agents to wait for. `No agents completed yet`. Stuck.
Structural fix: each `packages/cli/src/templates/codex/agents/trellis-{implement,check,research}.toml` now contains:
```toml theme={null}
[features]
multi_agent = false
[features.multi_agent_v2]
enabled = false
```
With both flags off, Codex doesn't register `spawn_agent` / `wait_agent` / `list_agents` / `close_agent` for the sub-agent.
Adds `[issue-241-followup]` regression test asserting all three template toml files retain the disable block.
### Codex `trellis-start` skill missing on update path
0.5.5's `configureCodex()` writes `.agents/skills/trellis-start/SKILL.md` so the `<trellis-bootstrap>` notice from `inject-workflow-state.py` resolves to a real skill. But `collectPlatformTemplates.codex.collectTemplates()` (used by `trellis update`) was missed.
Result: users upgrading from 0.4.x to 0.5.5/0.5.6 ran the safe-file-delete migration that removed `.agents/skills/start/`, then `trellis update` regenerated all the other `trellis-*` skill dirs from `collectTemplates`, but never wrote `trellis-start`. Their AI then reported "no `.agents/skills/trellis-start/SKILL.md`" on every turn that hit `<trellis-bootstrap>`.
Fix: extracted `resolveCodexTrellisStartSkill()` helper in `configurators/shared.ts`, called from both `configureCodex()` (init) and `collectPlatformTemplates.codex` (update) so the file shows up on both paths. No drift possible. Both call the same helper.
### Kiro CLI agent JSON schema migration ([`#247`](https://github.com/mindfold-ai/Trellis/issues/247))
Kiro CLI rejected Trellis's pre-0.5.7 agent JSON with "invalid agent". Three schema changes per Kiro's [Agent Configuration Reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference):
1. **`instructions` becomes `prompt`**. Kiro CLI no longer accepts `instructions`.
2. **Adds `allowedTools` field** mirroring `tools`. Kiro splits "available tools" from "permitted tools"; without `allowedTools` the agent can't actually invoke anything.
3. **`hooks` array becomes object keyed by event name**:
```json theme={null}
// before
"hooks": [
{ "on": "agentSpawn", "command": "...", "timeout_ms": 30000 }
]
// after
"hooks": {
"agentSpawn": [{ "command": "..." }]
}
```
`on` field removed (event is now the key). `timeout_ms` removed.
Affects all three `trellis-{implement,check,research}.json` files. Adds `[issue-247]` regression test asserting the new schema (prompt present, instructions absent, allowedTools array, hooks object not array).
### Windows Python detection fallback chain ([`#236`](https://github.com/mindfold-ai/Trellis/issues/236))
`trellis init` previously tried only `python --version` on Windows. If the host had Python under `python3` (Microsoft Store) or `py -3` (python.org launcher) but not `python`, init failed outright with `Python command "python" not found`.
`resolveSupportedPython()` in `packages/cli/src/commands/init.ts` now walks a per-platform candidate list:
| Platform | Candidate order |
| -------- | ---------------------------- |
| Windows | `python`, `python3`, `py -3` |
| Other | `python3`, `python` |
First candidate whose `--version` matches Python ≥ 3.9 wins. The resolved command is cached via `setResolvedPythonCommand()` in `configurators/shared.ts` so `replacePythonCommandLiterals()` and all downstream template / configurator writes pick up the same value.
Two env-var escape hatches:
* `TRELLIS_PYTHON_CMD=<cmd>` for explicit override (no probe).
* `TRELLIS_SKIP_PYTHON_CHECK=1` for skipping the probe entirely (pre-existing).
Failure case throws an aggregated error listing every candidate's probe result plus a Windows-specific install hint pointing at python.org with the "Add Python to PATH" reminder.
6 new unit tests in `packages/cli/test/commands/init-internals.test.ts` cover the fallback chain, env-var overrides, sandbox-restricted EPERM, and aggregated failure mode.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` needed. Codex users get hardened sub-agent role files; Windows users no longer need to install 0.4.0 first. Codex 0.129+ users should run `/hooks` once after upgrading Codex to approve the Trellis `UserPromptSubmit` hook.
# v0.5.8
Source: https://docs.trytrellis.app/changelog/v0.5.8
2026-05-08
## Bug Fixes
* **Removing the sub-agent guidance in `AGENTS.md` stops Codex from calling / waiting on research agents.** Deleted the `## Subagents` section (36 lines, including the "ALWAYS wait for every spawned subagent" rule).
* **Sub-agent mode fix: `trellis-research` on Codex no longer exits prematurely / produces no research files due to missing task context** (the main agent now includes the `Active task:` line when dispatching to research agents too).
## Added
* `CoreRule` block prepended to the `trellis-brainstorm` skill (adapted from [https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md](https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md) ).
## Other Platforms
Claude Code, Cursor, OpenCode, Kiro, CodeBuddy, and Droid unchanged.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.9
Source: https://docs.trytrellis.app/changelog/v0.5.9
2026-05-08
## Bug Fixes
* **Codex `dispatch_mode` default flipped from `sub-agent` to `inline`.** Codex sub-agents run with `fork_turns="none"` isolation, so they can't inherit the parent session's task context — they either exit silently or recursively dispatch. Inline mode keeps the main Codex agent in charge so context isn't lost. To opt back into the legacy dispatch flow, uncomment `codex.dispatch_mode: sub-agent` in `.trellis/config.yaml`. Invalid values fall back to inline.
* **`--platform codex` now namespaces into `codex-inline` / `codex-sub-agent` virtual platforms.** `workflow.md` `[Platform A, B, ...]` blocks render different guidance per mode (inline mode tells the main agent to edit code; sub-agent mode tells it to dispatch `trellis-implement` / `trellis-check`). `inject-workflow-state.py` emits a `<codex-mode>` banner in the per-turn UserPromptSubmit prompt so Codex knows which mode it is in. `[workflow-state:STATUS-inline]` blocks drive the breadcrumb path for inline mode.
## Internal
* Restored `0.6.0-beta.0.json` on `main`. The version was published from `feat/v0.6.0-beta` but its manifest never landed on main, breaking adjacent-version update chains for users hopping between stable and beta lines.
## Other Platforms
Claude Code, Cursor, OpenCode, Kiro, CodeBuddy, Droid, Gemini, Qoder, Copilot — unchanged.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.6.0-beta.0
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.0
2026-05-08
First 0.6 beta. Adds `trellis mem`: search past Claude Code, Codex, and OpenCode sessions by keyword, read the turns around each match, and dump full conversations.
## New feature: `trellis mem`
Reads each platform's session files on disk (Claude Code, Codex, OpenCode), strips hook injections, AGENTS.md preambles, and tool-call noise, then lets you search by keyword and read the actual dialogue around each match.
```bash theme={null}
trellis mem list # list sessions across platforms
trellis mem search "user login" # find sessions whose contents match
trellis mem context <session-id> # top-N hit turns + surrounding context
trellis mem extract <session-id> # dump cleaned dialogue (--grep KW to filter)
trellis mem projects # list active project cwds (AI-routing entry)
```
Subcommands accept filters: `--since 2026-04-01`, `--cwd /abs/path`, `--platform claude|codex|opencode`, `--json`. Run `trellis mem help` for the full reference.
Mechanics:
* Reads `~/.claude/projects/<encoded-cwd>/<uuid>.jsonl` (Claude Code), Codex session JSON, and OpenCode `<storage>/messages/<session-id>/*.json`. No live process attach; works on closed sessions.
* Strips workflow-state breadcrumbs, session-context blocks, and hook output so search hits surface real user / assistant turns. Handles compaction (Claude `isCompactSummary` + Codex `compacted` events).
* 84 unit tests (Tier 1 pure helpers + Tier 2 fixture-driven platform parsers + Tier 3 subcommand integration). mem.ts coverage: 81.89% statement / 89.04% function / 87.93% line.
## Install
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
This is a beta. The 0.5 stable line continues to receive patches if needed; install latest stable with `@latest` instead. Switch back from beta to stable with `npm install -g @mindfoldhq/trellis@latest`.
# Building an AI Collaborative Development System in Real Projects
Source: https://docs.trytrellis.app/blog/ai-collaborative-dev-system
A few days ago, Anthropic published an article about their internal AI-assisted development approach—giving AI "long-term memory" so it can remember project specifications, past decisions, and coding style. The concept is inspiring, but their explanation was fairly theoretical without much practical implementation detail.
Our team recently tried implementing this approach in the Mosi project, extending it significantly to handle real multi-person collaboration scenarios. This article covers how we did it, what pitfalls we encountered, and what the final system feels like in practice.
## 1. Starting Point: The Gap Between Anthropic's Vision and Reality
Anthropic's core idea is: **don't start every AI conversation from scratch—let the AI see the project's "memory" from the beginning**.
This "memory" includes:
* Project tech stack and architecture specifications
* Code style conventions
* Previously discussed design decisions
* Solutions to common problems
Their approach is to organize this content into documentation within the project, then feed relevant documents to the AI during conversations. This way, the AI can work like "an experienced employee who knows the project background" rather than needing everything explained from scratch each time.
Sounds simple, but implementing this in a real multi-person collaborative project raises many practical issues:
* **What about multiple developers working simultaneously?** If everyone's progress is recorded in a single file, conflicts are inevitable.
* **What if specification documents are too long?** Our frontend spec has over 1600 lines, backend specs have hundreds more. Feeding everything to AI would blow the token limit, and most content isn't relevant to the current task anyway.
* **How do we ensure code quality?** AI-written code can't go directly to the main branch—someone needs to review and test it.
* **How do we track AI's work?** If something goes wrong, how do we trace what the AI actually did?
We designed solutions for these problems in the Mosi project.
## 2. Implementation: Four Core Design Decisions
### 1. Multi-Person Collaboration: Each Developer Gets an Independent Progress Folder
Anthropic's article barely mentions multi-person collaboration, but this is unavoidable in real projects.
Our approach: **create an independent folder for each developer (including AI) under `workflow/agent-progress/`**.
For example:
```plaintext theme={null}
workflow/
├── agent-progress/
│ ├── taosu/ # Developer taosu's progress
│ │ ├── index.md
│ │ └── progress-1.md
│ ├── developer2/ # Developer developer2's progress
│ │ ├── index.md
│ │ └── progress-1.md
```
Each folder has an `index.md` that records what this developer is currently working on, how far they've progressed, and what problems they've encountered. AI reads this file before starting work to understand context; after work, it updates this file to record new progress.
This way multiple developers can work simultaneously without interfering with each other.
### 2. Solving Information Overload: Two-Layer Index System
As mentioned, our spec documents are long (frontend 1600+ lines, backend hundreds of lines). In practice, we found that feeding complete documents to AI causes several problems:
**Why do we need a structured system?**
1. **Information overload**: When AI needs to implement a "keyboard shortcut feature," if it reads all 1600 lines of frontend specs, it gets distracted by irrelevant content—like "API calling conventions," "state management specs," etc. These are important but unhelpful for the current task, reducing AI's focus.
2. **Token economics**: In long conversations, if we read complete documents every time, token consumption accumulates rapidly. With 20 rounds of interaction, repeatedly reading documents wastes significant cost.
3. **Knowledge navigation**: Developers (and AI) need to quickly answer "I'm implementing feature X—which part of the spec should I read?" Without a clear navigation system, they can only rely on full-text search or reading chapter by chapter, which is very inefficient.
### Our Solution: Two-Layer Structure
We designed an `index.md + doc.md` two-layer knowledge system:
```plaintext theme={null}
workflow/
├── frontend-structure/
│ ├── index.md # Index layer: quick navigation (~100 lines)
│ └── doc.md # Detail layer: complete spec (1600+ lines)
```
**What is index.md?**
`index.md` is a **lightweight navigation table** that lists all spec chapters with explicit line number ranges. More importantly, it's organized by **development task type**, not document structure.
For example:
```markdown theme={null}
# Frontend Development Spec Index
> **Complete doc**: See `./doc.md` for detailed specifications
This index helps you quickly locate the spec chapters you need. Find the corresponding chapters and line numbers based on the type of feature you're developing.
## Related Workflow Documents
| Document | Use Case |
| ----------------------------------- | ----------------------------- |
| `../frontend-figma-workflow/doc.md` | Developing from Figma designs |
## Quick Navigation
| Development Task | Chapters to Read | Line Range |
| ---------------------------------------- | ------------------------------------------ | ---------- |
| **New feature module** | Directory structure spec | L5-36 |
| **Writing Command Palette** | Component dev spec > Command Palette | L876-1425 |
| **Writing Query Hook** | Hook dev spec > Query Hook | L179-265 |
| **Writing Mutation Hook** | Hook dev spec > Mutation Hook | L266-351 |
| **Calling backend API** | API calling spec | L382-735 |
| **Real-time communication (WebSocket)** | API calling spec > Real-time | L419-465 |
| **AI streaming response (SSE)** | API calling spec > SSE | L466-497 |
| **AI Tool Calls handling** | API calling spec > Tool Calls | L498-735 |
| **State management** | State management spec | L736-873 |
| **URL state sync** | State management spec > URL/Context | L738-873 |
| **Writing components** | Component dev spec | L874-1645 |
| **Accessibility and image optimization** | Component dev spec > Semantic HTML & Image | L1426-1544 |
| **Performance optimization** | Performance optimization spec | L1676-1762 |
| **Code quality check** | Code quality and formatting spec | L2140-2317 |
| **Code review** | General rules + Checklist | L1763-2344 |
......
```
**Core advantages:**
1. **Instant Knowledge Access**: AI only needs to read \~100 lines of index.md to locate "implementing keyboard shortcuts requires reading lines 876-1425" within seconds. This is much faster than full-text search or browsing chapter by chapter.
2. **On-Demand Loading**: AI reads only relevant sections of `doc.md` based on the current task (e.g., 500 lines instead of 1600). This saves tokens while avoiding information overload.
3. **Standardized Workflow**: This two-layer structure becomes a team standard—everyone (including AI and newly joined human developers) knows "read index first, then doc." This reduces cognitive load and improves collaboration efficiency.
**Workflow:**
1. AI reads `index.md` to understand the overall spec structure
2. Based on the current task (e.g., "implement keyboard shortcut"), AI finds "Writing Command Palette → L876-1425" in the navigation table
3. AI precisely reads lines 876-1425 of `doc.md` for detailed implementation guidance
4. AI writes code following the spec, avoiding "not knowing where to start" or "missing key details"
### Fundamental Difference from Claude Skills
You might ask: Didn't Anthropic release Claude Skills? Why not just use Skills instead of building this structure ourselves?
This is because they solve different problems:
* **Claude Skills** are **ecosystem-driven general capability packages**, designed for cross-project reuse. Things like "git operations," "Python testing," "filesystem operations"—these capabilities apply to any project. Skills pursue **breadth and reusability**.
* **Our structure** is a **project-specific deep customization system** that indexes and stores Mosi project's specific architecture, tech stack, state management patterns, API calling conventions, etc. This knowledge is unique to the project and cannot be reused across projects. Our system pursues **depth and precision**.
A concrete example:
* **Skills can teach AI**: "How to write a React component" (general knowledge)
* **Our doc.md teaches AI**: "In the Mosi project, how to write components following our specific architecture (Monorepo + Turborepo), state management patterns (Zustand + URL state sync), API calling conventions (tRPC + SSE + Tool Calls)" (project-specific knowledge)
Skills are like a "general toolbox"; our structure is like "project blueprints." They're not replacements but complements—Skills provide foundational capabilities, structure provides project-specific implementation details.
We use the same organizational approach for backend specs.
### 3. Encapsulating Best Practices: Short Command System
To standardize the development process, we defined a series of "short commands," each corresponding to a specific operation.
Short commands are stored in the `.cursor/commands/` directory, each command as a `.md` file.
Currently common short commands include:
* `/init-agent`: Initialize AI session, having AI read the current developer's progress and relevant specs
* `/check-frontend`: Have AI check if frontend code follows specifications
* `/check-backend`: Have AI check if backend code follows specifications
* `/record-agent-flow`: Record this AI session's work content to the progress file
**What are short commands?**
Short commands are essentially **predefined prompt templates**. Each `.md` file contains a complete AI instruction.
For example, `check-frontend.md` might contain:
```markdown theme={null}
Check your own work—does the code you just wrote follow frontend development specs? First use git status to see which files were modified, then go to `.cursor/rules/frontend-structure/index.md` to find the corresponding doc details and check against `.cursor/rules/frontend-structure/doc.md`
...
```
**How it works:**
When a developer types `/check-frontend` and hits enter:
1. Cursor automatically reads the content of `.cursor/commands/check-frontend.md`
2. Injects this content as a prompt into the current conversation
3. AI performs the corresponding check operations based on this prompt
**Why use short commands?**
Because every time you ask AI to do code checking or progress recording, you need to input a detailed checklist or operational steps. If these instructions aren't detailed enough, AI output quality becomes inconsistent.
Short commands encapsulate these **best practice prompts**—developers just type `/check-frontend`, which is equivalent to sending a carefully designed complete prompt, ensuring instruction consistency and completeness.
Plus, short commands can be shared across the team, so new members can immediately benefit from accumulated team experience.
> Think of short commands as a kind of prompt SDK—using a short command is like calling a specialized SDK our team built for a specific scenario
### 4. Quality Gate: Human Developer Review Mechanism
Although AI can write code, we don't let AI commit directly. **All code requires human developer review and testing before it can be committed**.
The typical flow is:
1. AI writes code
2. Developer runs locally to check if functionality works
3. Developer reviews code for obvious issues
4. If there are problems, have AI fix them; if not, developer commits manually
This way we get AI's efficiency while ensuring code quality.
## 3. Practice: A Complete Development Flow
The design concepts above might still be abstract. Below is a real example showing the complete development flow.
**Background:**
I need to implement a keyboard shortcut feature on the frontend—pressing `Cmd+K` to open the search box. I've already created a Git branch `feat/keyboard-navigation` locally.
### Initialize AI Session
```plaintext theme={null}
Me: /init-agent
```
When I input this short command, Cursor injects the content of `init-agent.md` into the conversation. This template defines the initialization steps AI needs to perform:
**AI executes according to short command guidance:**
1. Read `workflow/agent-progress/taosu/index.md` to understand my current progress and context
2. Read `workflow/frontend-structure/index.md` to understand the overall frontend spec structure
3. If needed, read further into relevant chapters of `doc.md`
**AI's response:**
```plaintext theme={null}
Okay, I've read your progress record and frontend specs.
Current branch: feat/keyboard-navigation
Task: Implement keyboard shortcut feature (Cmd+K opens search)
I noticed the frontend spec has a "Keyboard System" chapter—I'll implement according to those specifications.
Ready. Tell me what specifically needs to be done.
```
### Describe Requirements
```plaintext theme={null}
Me: Help me implement a global keyboard shortcut—when pressing Cmd+K (Mac) or Ctrl+K (Windows),
open the search box. The search box component already exists at components/SearchModal.tsx.
```
**What AI does:**
1. Based on the "keyboard shortcut" keyword, read the "Keyboard System" chapter in `workflow/frontend-structure/doc.md`
2. Learn that the project already has a `useKeyboardShortcut` hook ready to use
3. Write code: call this hook in the appropriate place to bind Cmd+K shortcut
**AI's response:**
```plaintext theme={null}
Okay, here's my implementation:
1. Use useKeyboardShortcut hook in the SearchModal component
2. Listen for Cmd+K / Ctrl+K, trigger search box open
3. Close search box on ESC
Code is written, file path:
- components/SearchModal.tsx (modified)
You can run locally to see the effect.
```
### Local Testing
I run the project locally, press `Cmd+K`, search box opens successfully. Feature works.
### Code Self-Check
```plaintext theme={null}
Me: /check-frontend
```
When I input this short command, Cursor automatically injects the content of `check-frontend.md` (a detailed code check list) into the conversation.
**AI executes check according to short command template:**
Following check items defined in the template, reviews the code just written:
* Check if component naming follows conventions
* Check if React hooks dependency arrays are complete
* Check if type definitions are strict
* Check for potential performance issues\
...
**AI's response:**
```plaintext theme={null}
Checked and found two minor issues:
1. useKeyboardShortcut dependency array was missing a state
2. Type definitions could be stricter
Already fixed for you—should be fine after running again.
```
I retest and confirm no issues.
### Commit Code
```bash theme={null}
git add .
git commit -m "feat: add Cmd+K keyboard shortcut for search"
git push origin feat/keyboard-navigation
```
### Record Flow
```plaintext theme={null}
Me: /record-agent-flow
```
Cursor injects the content of `record-agent-flow.md` into the conversation—this template guides AI on how to record the workflow.
**AI executes according to template guidance:**
1. Summarize this session's work content (requirements, implementation approach, problems encountered, solutions, etc.)
2. Format and append this information to `workflow/agent-progress/taosu/index.md`
**AI's response:**
```plaintext theme={null}
Recorded this session's workflow to your progress file.
Main content:
- Implemented global keyboard shortcut Cmd+K for search
- Used useKeyboardShortcut hook
- Fixed dependency array and type definition issues
- Committed to branch feat/keyboard-navigation
```
This way, next time I continue working with AI, it can quickly understand what I've been doing recently by reading this progress file.
## 4. Pitfalls and Solutions
### Problem 1: Learning Curve for Short Commands
New team members need to learn which short commands exist and what each does.
We provide an `/onboard-developer` short command to guide newcomers. New members just run this command, and AI follows the preset guidance flow to introduce the entire workflow system, common short commands, and how to start the first task.
### Problem 2: AI "Forgets" Specs in Long Conversations
Even if AI reads all specs via `/init-agent` at session start, as conversation turns increase and context lengthens, AI may gradually "forget" the initially read development spec details. This causes AI to drift from spec requirements when writing code.
Our solution: **use short commands at key points to force AI to re-consult specs**.
For example, the `/check-frontend` short command template explicitly requires AI to:
1. First use `git status` to see which code was just modified
2. Based on the change type (e.g., "added a new Hook"), find the corresponding chapter in `index.md`
3. Re-read the relevant part of `doc.md` (e.g., "Hook dev spec L179-265")
4. Check code against specs item by item
This way, even if context is already very long, AI will **mandatorily** re-learn the specs when checking code, ensuring code quality doesn't decline due to "forgetting."
This is also why we encapsulate these operations as short commands—not just for convenience, but to **enforce quality assurance processes at key workflow points**.
## 5. Summary and Future Plans
Anthropic's "AI long-term memory" concept is valuable, but truly implementing it in real multi-person collaborative projects requires solving many engineering problems.
Our practice in the Mosi project did these core things:
* **Multi-person collaboration support**: Each developer has an independent progress folder
* **Spec index system**: index.md + doc.md structure lets AI efficiently find specs
* **Short command system**: Encapsulates common operations, improves development efficiency
* **Human in the loop**: AI writes code, humans review and commit, ensuring quality
This system is still being continuously improved, but we can already feel noticeable improvements in development efficiency.
Improvements we might make next:
* **Automate more processes**: e.g., let AI automatically create branches, automatically write commit messages
* **Smarter spec indexing**: Currently AI manually judges which chapters to read; in the future, AI could automatically match relevant chapters based on task descriptions
* **Team knowledge base**: Organize design decisions discussed by the team and pitfalls encountered into documentation, so AI can learn from this experience
If you're also trying AI-assisted development, I hope this article gives you some inspiration. Welcome to discuss.
***
## Resources
* Anthropic's original article: [Building effective agents](https://www.anthropic.com/research/building-effective-agents)
# Overview
Source: https://docs.trytrellis.app/blog/index
| Article | Date |
| ----------------------------------------------------------------------------------------------------- | ----------- |
| [Understanding Trellis Through Kubernetes](/blog/use-k8s-to-know-trellis) | Feb 1, 2026 |
| [Building an AI Collaborative Development System in Real Projects](/blog/ai-collaborative-dev-system) | Feb 1, 2026 |
# Understanding Trellis Through Kubernetes
Source: https://docs.trytrellis.app/blog/use-k8s-to-know-trellis
2026-02-01
> If you're familiar with Kubernetes, this document will help you quickly grasp Trellis's design philosophy.
<Note>
This article was written in the Trellis 0.4.x era. Some named concepts have changed since: the
Ralph Loop, `dispatch` / `plan` / `debug` agents, and the Multi-Agent Pipeline were all removed
during the 0.5.0 prerelease. The high-level K8s analogy still applies; read specific agent / hook
names here as historical references.
</Note>
***
## Table of Contents
1. [K8s Core Concepts Overview](#1-k8s-core-concepts-overview)
2. [Trellis and K8s Analogy](#2-trellis-and-k8s-analogy)
3. [Reconciliation Mechanism Deep Dive](#3-reconciliation-mechanism-deep-dive)
4. [Complete Workflow](#4-complete-workflow)
5. [Why This Design](#5-why-this-design)
***
## 1. K8s Core Concepts Overview
### Imperative vs Declarative
**Imperative**: Describe "how to do it"
```bash theme={null}
# Step-by-step instructions for the system
current_pods=$(kubectl get pods -l app=nginx --no-headers | wc -l)
if [ $current_pods -lt 3 ]; then
kubectl run nginx --image=nginx:1.19
fi
```
**Declarative**: Describe "what you want"
```yaml theme={null}
# Just state the desired end state
apiVersion: apps/v1
kind: Deployment
spec:
replicas: 3
template:
spec:
containers:
- name: nginx
image: nginx:1.19
```
| Dimension | Imperative | Declarative |
| -------------- | --------------------------- | ---------------------- |
| Focus | Process (How) | Result (What) |
| Executor | User orchestrates each step | System auto-reconciles |
| Idempotency | Requires extra handling | Naturally idempotent |
| Error Recovery | Requires user intervention | Self-healing |
### Control Loop
The core of K8s is the **Control Loop**:
```
Desired State Actual State
(User declares) (System observes)
| |
+---> Controller <----+
|
Observe → Diff → Act → Repeat
```
**Power in action**:
```
I declare: I want 3 nginx Pods
A Pod gets accidentally deleted → Controller detects 2 ≠ 3 → Auto-creates 1
I modify declaration to 5 → Controller detects 3 ≠ 5 → Auto-creates 2
No manual intervention needed. System auto-detects, auto-recovers, auto-adapts.
```
***
## 2. Trellis and K8s Analogy
### Architecture Mapping
```
┌─────────────────────────────────────────────────────────────┐
│ Kubernetes │
│ │
│ YAML Manifest ──> Controller ──> Actual State │
│ (Desired State) (Reconcile) (Actual State) │
└─────────────────────────────────────────────────────────────┘
↕
┌─────────────────────────────────────────────────────────────┐
│ Trellis │
│ │
│ Task Dir ──> Dispatch + Ralph Loop ──> Compliant Code │
│ (Desired State) (Reconcile) (Actual State) │
└─────────────────────────────────────────────────────────────┘
```
### Core Component Mapping
| Kubernetes | Trellis | Description |
| ------------------- | -------------- | ------------------------------- |
| YAML Manifest | Task Directory | Declares desired state |
| Controller | Dispatch | Orchestrates phase execution |
| Reconciliation Loop | Ralph Loop | Loops until verification passes |
| Pod/Container | Agent | Actual execution unit |
| ConfigMap | jsonl + Hook | Injects config/context |
| Actual State | Final Code | Product after reconciliation |
### Key Insight
K8s solves: **Infrastructure complexity** — Uses declarative to abstract away details, Controller handles reconciliation.
Trellis solves: **AI development uncertainty** — Uses declarative to define expectations (prd.md + guidelines), Ralph Loop handles reconciliation.
Common ground:
* Users only declare "what they want", don't worry about "how to do it"
* System continuously reconciles until actual state matches desired
* Auto-repairs when deviations occur
> Next, Chapter 3 details the reconciliation mechanism (Hook + Ralph Loop), and Chapter 4 expands on the complete workflow (Phase 1-4).
***
## 3. Reconciliation Mechanism Deep Dive
Trellis reconciliation is achieved through two mechanisms working together: **Hook Injection** and **Ralph Loop**.
### Hook Injection
**Timing**: Automatically triggered each time a Subagent is called
**Function**: Injects file contents referenced in jsonl into the Agent's context
```
Plan/Research Agent finds needed files in advance
│
▼
Writes to implement.jsonl / check.jsonl
│
▼
Dispatch calls Subagent
│
▼
Hook intercepts, reads jsonl, injects file contents
│
▼
Subagent receives complete context, starts working
```
**jsonl file example**:
```jsonl theme={null}
{"file": ".trellis/spec/backend/index.md", "reason": "Backend guidelines"}
{"file": "src/api/auth.ts", "reason": "Existing auth pattern"}
```
**Why this design**:
* Prevents context overload (Context Rot) — Only injects what's needed for current phase
* Traceable — jsonl records what context each task used
* Decoupled — Agent doesn't need to search, focuses on execution
### Ralph Loop
**Essence**: A programmatic quality gate that intercepts Agent stop requests and forces continuation if verification fails.
**Trigger timing**: When Check Agent attempts to stop
**Flow**:
```
Check Agent attempts to stop
│
▼
SubagentStop Hook triggers ralph-loop.py
│
▼
Has verify config?
│
┌────┴────┐
Yes No
│ │
▼ ▼
Run verify Check completion
commands markers
(pnpm lint) (parse from output)
│ │
▼ ▼
┌──┴──┐ ┌──┴──┐
│Pass │ │Complete│
│ │ │ │
▼ ▼ ▼ ▼
allow block allow block
(stop) (continue) (stop) (continue)
Max 5 iterations, then force allow
```
**verify config example** (worktree.yaml):
```yaml theme={null}
verify:
- pnpm lint
- pnpm typecheck
```
**Why use programmatic verification instead of letting AI judge**:
* Programmatic verification is reliable — lint pass means pass, doesn't depend on AI's judgment
* Configurable — Different projects can configure different verification commands
* Prevents infinite loops — Max 5 iterations, then force allow
**Limitations**:
* Complex architectural issues or logic bugs may require human intervention
* Depends on guideline quality; unclear guidelines lead to limited check effectiveness
***
## 4. Complete Workflow
### Phase Overview
```
Task Directory
├── prd.md (Task requirements)
├── implement.jsonl (Implementation phase context)
├── check.jsonl (Check phase context)
└── task.json (Metadata)
│
▼
┌───────────────────────────────────────────────┐
│ Phase 1: implement │
│ ───────────────── │
│ Agent: Implement Agent │
│ Injects: prd.md + files from implement.jsonl │
│ Task: Write code based on requirements │
└───────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────┐
│ Phase 2: check │
│ ───────────────── │
│ Agent: Check Agent │
│ Injects: Guideline files from check.jsonl │
│ Task: Check code compliance, fix issues │
│ Reconcile: Ralph Loop verifies, loops if fail│
└───────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────┐
│ Phase 3: finish │
│ ───────────────── │
│ Agent: Check Agent (with [finish] flag) │
│ Injects: finish-work.md (Pre-Commit List) │
│ Task: Pre-commit completeness check │
│ - lint/typecheck/test passing │
│ - Documentation in sync │
│ - API/DB changes complete │
│ Reconcile: Skips Ralph Loop (already verified)│
└───────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────┐
│ Phase 4: create-pr │
│ ───────────────── │
│ Task: Create Pull Request │
└───────────────────────────────────────────────┘
│
▼
Compliant Code + PR
```
### Exception Path
If Check Agent reports unfixable issues, Dispatch can call **Debug Agent** for deep analysis. This is not the default flow, but exception handling.
***
## 5. Why This Design
### One-Click Complete Workflow
`/trellis:start` or `/trellis:parallel` (Claude Code only) launches with one click, AI completes the entire flow:
```
Plan → Implement → Check → Finish → PR
```
Users don't need to guide step-by-step. What to do at each phase, which guidelines to reference — it's all predefined.
### Continuous Accumulation of Development Guidelines
```
Guidelines stored in .trellis/spec/
│
▼
AI executes with guidelines ──> Finds issues ──> Updates guidelines
│ │
└────────────────────────────────────┘
Guidelines improve over time
```
Thinking Guides help discover "didn't think of that" problems.
### Preventing Context Rot
Too much context causes LLM to:
* **Distraction** — Gets sidetracked by irrelevant information
* **Confusion** — Information contradicts itself
* **Clash** — Old and new information conflict
Trellis injects by phase:
* implement phase: Requirements + related code
* check phase: Development guidelines
* finish phase: Pre-commit checklist
Each phase's Agent only receives context relevant to its task.
### Programmatic Quality Control
```
Traditional approach:
"Please check code quality" ──> AI says "I checked" ──> Did it really?
Trellis approach:
Ralph Loop runs pnpm lint ──> Pass to proceed ──> Programmatically guaranteed
```
Doesn't rely on AI's self-judgment, uses programmatic enforcement.
### Traceability
| Record | Content |
| --------- | ---------------------------- |
| jsonl | What context each task used |
| workspace | Work content of each session |
| task.json | Complete task lifecycle |
When issues arise, you can trace back to which file was missing, or which guideline was unclear.
***
## Summary
| Concept | K8s | Trellis |
| ------------------- | ------------- | ------------------------------- |
| Desired State | YAML Manifest | Task Directory (prd.md + jsonl) |
| Execution Unit | Pod/Container | Agent |
| Reconciliation Loop | Controller | Dispatch + Ralph Loop |
| Config Injection | ConfigMap | Hook + jsonl |
| Final Product | Running Pods | Compliant Code |
**Core philosophy aligned**: Declare desired → System reconciles → Eventually consistent.
# v0.5.0
Source: https://docs.trytrellis.app/changelog/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
```
# v0.5.0-beta.19
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.19
2026-04-29
Beta.19 hot-fixes a regression in beta.18 that could overwrite a hand-authored `AGENTS.md` during `trellis update`.
## Bug Fixes
### `AGENTS.md` content no longer clobbered when TRELLIS markers are absent
Beta.18 introduced a `<!-- TRELLIS:START -->` / `<!-- TRELLIS:END -->` managed-block replacement for `AGENTS.md`. The fallback path — taken when the existing file does not contain the markers — returned the bare Trellis template, which silently replaced the user's content during `trellis update`.
| Pre-existing `AGENTS.md` state | Beta.18 (regressed) | Beta.19 |
| ---------------------------------------- | ----------------------------------- | --------------------------------------------------------- |
| Has `TRELLIS:START` / `TRELLIS:END` | Replace block, keep outside content | Same (unchanged) |
| No markers, hand-authored or pre-beta.18 | **Whole file overwritten** | User content preserved; managed block appended at the end |
| File does not exist | Write fresh template | Same (unchanged) |
The fix lives in `buildAgentsMdTemplate` (`packages/cli/src/commands/update.ts`); the new fallback extracts the managed block from the canonical template via `getTrellisManagedBlock` and appends it after the existing content with a blank line separator. Recovery for projects that already lost content: `git checkout <pre-update-commit> -- AGENTS.md` and rerun `trellis update` on beta.19.
### Test coverage
Added `#4d preserves user AGENTS.md without TRELLIS markers by appending the managed block` in `packages/cli/test/commands/update.integration.test.ts`. The previous suite covered the legacy-pristine (`#4b`) and user-modified-managed-block (`#4c`) cases but missed the no-markers-at-all case where the regression was hiding.
## Upgrade
Existing projects:
```bash theme={null}
trellis update
```
No `--migrate` flag is required for this beta.
# v0.5.0-rc.0
Source: https://docs.trytrellis.app/changelog/v0.5.0-rc.0
2026-04-30
`v0.5.0-rc.0` is the release candidate before the 0.5.0 stable release. This build focuses on release stabilization: non-interactive init recovery, workflow breadcrumbs reading from `workflow.md`, automatic `workflow.md` breadcrumb updates, and bundled `trellis-meta` reference updates.
## Enhancements
### Workflow breadcrumbs
Per-turn workflow breadcrumbs, the short prompts that tell the AI which workflow step it is in, now read from `.trellis/workflow.md` `[workflow-state:STATUS]` blocks.
| Component | Change |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `packages/cli/src/templates/shared-hooks/inject-workflow-state.py` | Removes `_FALLBACK_BREADCRUMBS`; missing tags degrade to a generic `Refer to workflow.md` message |
| `packages/cli/src/templates/opencode/plugins/inject-workflow-state.js` | Removes the OpenCode JS fallback dictionary |
| `.trellis/workflow.md` / template copy | Adds required Phase 1.3 jsonl curation to `planning`; adds Phase 3.4 commit before `/trellis:finish-work` to `in_progress` |
| `packages/cli/src/templates/shared-hooks/session-start.py` | Strips full breadcrumb tag blocks from SessionStart payloads so the same body is not injected twice |
The parser and stripper both require matched tag pairs:
```md theme={null}
[workflow-state:planning]
...
[/workflow-state:planning]
```
### Automatic `workflow.md` breadcrumb updates
`trellis update` now refreshes the `[workflow-state:*]` blocks in `.trellis/workflow.md`. Hooks read those blocks to tell the AI what to do next; normal prose outside the blocks is still left alone.
| Case | Behavior |
| ------------------------------------------ | ----------------------------------------------------------------------------------------- |
| User file has a matching status block | Replace that block body with the CLI template block |
| User file is missing a status block | Append the missing block to the end of `workflow.md` |
| User changed content outside tag blocks | Preserve it verbatim |
| User changed prompt text inside tag blocks | Replace it with the current CLI version and print a warning listing the affected statuses |
The implementation lives in `buildWorkflowMdTemplate` (`packages/cli/src/commands/update.ts`).
### Session active task after `task.py create`
`task.py create` now best-effort sets the session active-task pointer. The planning breadcrumb becomes reachable immediately after creating a task, so the AI sees Phase 1.1 through Phase 1.4 guidance instead of falling back to the no-task path.
`trellis continue` also routes by `task.json.status` plus required artifacts, including the Phase 1.4 activation branch after `prd.md` and jsonl context are ready.
### Bundled `trellis-meta` references
The bundled `trellis-meta` skill now describes how workflow-state reads `workflow.md` consistently across its reference pages:
| Reference | Update |
| ------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `customize-local/change-workflow.md` | Explains that `[workflow-state:STATUS]` blocks are parsed by runtime hooks |
| `customize-local/change-task-lifecycle.md` | Adds session active-task pointer notes for `task.py create` / `task.py start` |
| `local-architecture/context-injection.md` | Points workflow-state injection at `workflow.md` instead of duplicated hook fallback text |
| `platform-files/hooks-and-settings.md` | Aligns hook descriptions with current workflow-state behavior |
## Bug Fixes
### Non-interactive `trellis init --yes`
`trellis init --yes` now stays non-interactive when files already exist.
| Layer | Fix |
| --------------------------------------- | ---------------------------------------------------------------------- |
| `packages/cli/src/commands/init.ts` | `--yes` maps write conflicts to `skip` mode unless `--force` is passed |
| `packages/cli/src/utils/file-writer.ts` | Non-TTY `ask` mode falls back to `skip` instead of prompting |
| Failure avoided | `ERR_USE_AFTER_CLOSE` from prompt code after stdin is unavailable |
`--force` still overwrites existing files. `--yes` preserves them by default.
### Aborted first-init recovery
If an earlier init wrote `.trellis/` but aborted before creating any task, rerunning init now creates the bootstrap task instead of routing to joiner onboarding.
| Disk state | Command | rc.0 behavior |
| ---------------------------------------------- | ---------------------------------------------- | ------------------------------------ |
| `.trellis/` exists, `tasks/` empty | `trellis init -u <name> --codex --yes` | Create `00-bootstrap-guidelines` |
| `.trellis/` exists, `tasks/` empty | `trellis init -u <name> --codex --yes --force` | Create `00-bootstrap-guidelines` |
| Existing project with active or archived tasks | `trellis init -u <name> --yes` | Keep normal re-init / joiner routing |
The empty-`tasks/` early check bypasses `handleReinit`, then the main dispatch's bootstrap fallback runs.
## Testing
### Init recovery coverage
The init suite now covers:
| Test file | Coverage |
| ------------------------------------------------------------ | ------------------------------------------------------------- |
| `packages/cli/test/commands/init-joiner.integration.test.ts` | Empty-`tasks/` recovery with `--yes` alone and with `--force` |
| `packages/cli/test/utils/file-writer.test.ts` | Non-TTY conflict fallback from `ask` to `skip` |
### Workflow-state coverage
Regression coverage now guards:
| Invariant | Coverage |
| ---------------------------------------------------- | ---------------------------- |
| Phase 1.3 appears in `planning` breadcrumb | `workflow.md` template test |
| Phase 3.4 commit appears in `in_progress` breadcrumb | `workflow.md` template test |
| Python / JS fallback dictionaries stay removed | Hook source tests |
| Matched tag-pair parsing | SessionStart strip test |
| Automatic `workflow.md` breadcrumb block updates | `update.integration.test.ts` |
## Upgrade
Install the RC:
```bash theme={null}
npm install -g @mindfoldhq/trellis@rc
```
Existing 0.5 beta projects:
```bash theme={null}
trellis update
```
Projects upgrading from 0.4.x:
```bash theme={null}
trellis update --migrate
```
`0.5.0-rc.0` adds no new migration entries, but 0.4.x projects still need the 0.5 migration chain that starts at `0.5.0-beta.0`.
# v0.5.0-rc.1
Source: https://docs.trytrellis.app/changelog/v0.5.0-rc.1
2026-05-01
`v0.5.0-rc.1` patches rc.0 with two OpenCode fixes ([#211](https://github.com/mindfold-ai/Trellis/issues/211), [#212](https://github.com/mindfold-ai/Trellis/issues/212)). No new migrations.
## Bug Fixes
### `trellis-research` subagent on OpenCode (#211)
`packages/cli/src/templates/opencode/agents/trellis-research.md`:
| Slice | Change |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Frontmatter `permission` | `write: allow`, `edit: allow` (were `deny`) |
| Prompt body | Replaced with the cursor/claude shape: Core Principle (PERSIST), Workflow Step 1–5 with `mkdir -p {TASK_DIR}/research/`, Scope Limits, File Format, DO/DON'T |
| Removed | "Context Self-Loading" section — `inject-subagent-context.js` already pre-loads spec dir context |
Description string updated to mention `PERSISTS every finding to the current task's research/ directory`, matching the other platforms.
The existing regression test group `regression: research agent persists findings to task dir` covered six platforms but not OpenCode. rc.1 adds an OpenCode case asserting:
* YAML `permission:` frontmatter contains `write: allow` and `edit: allow`
* Body contains `{TASK_DIR}/research/` and `PERSIST`
* Body does not contain a top-level `- Modify any files` rule
### OpenCode SessionStart plugin loading (#212)
OpenCode 1.2.x plugin loader iterates `Object.entries(mod)` and invokes every export as a plugin factory. `.opencode/plugins/session-start.js` declared two named exports (`buildSessionContext`, `hasInjectedTrellisContext`) alongside `export default`, which caused the loader to call the named exports with the factory input shape, throw, abort the load, and never reach `export default`.
Fix: extract the helpers to `packages/cli/src/templates/opencode/lib/session-utils.js`. Each plugin file now has only `export default`.
```text theme={null}
.opencode/plugins/session-start.js → export default
.opencode/plugins/inject-workflow-state.js → export default
.opencode/plugins/inject-subagent-context.js → export default
.opencode/lib/session-utils.js → buildSessionContext,
hasInjectedTrellisContext,
hasPersistedInjectedContext,
markContextInjected
```
A new regression test walks `packages/cli/src/templates/opencode/plugins/*.js` and asserts each file has exactly one top-level export, matching `^export\s+default\s/`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@rc
trellis update
```
Projects already on 0.5 (beta or rc.0) run `trellis update`. Projects upgrading from 0.4.x run `trellis update --migrate` because the 0.5 migration chain begins at 0.5.0-beta.0. rc.1 adds no new migration entries.
# v0.5.0-rc.2
Source: https://docs.trytrellis.app/changelog/v0.5.0-rc.2
2026-05-02
`v0.5.0-rc.2` adds the `trellis uninstall` command ([#221](https://github.com/mindfold-ai/Trellis/issues/221)) and patches Windows compatibility ([#218](https://github.com/mindfold-ai/Trellis/issues/218)) and Copilot custom-agent frontmatter (PR [#210](https://github.com/mindfold-ai/Trellis/pull/210)). No new migrations.
## Enhancements
### `trellis uninstall` command (#221)
Removes all files generated by trellis along with the `.trellis/` directory. The deletion list is sourced from `.trellis/.template-hashes.json`; files not listed in the manifest are not touched.
```bash theme={null}
trellis uninstall # default: list + Continue? [Y/n]
trellis uninstall --yes # skip prompt
trellis uninstall --dry-run # list then exit, no changes
```
Pre-checks:
| Condition | Behavior |
| ------------------------------------------------------ | ----------------------------------------------------------------- |
| `.trellis/` directory missing | Friendly exit 0 with `"Trellis is not installed in this project"` |
| `.trellis/` exists but `.template-hashes.json` missing | Exit 1 with hint to delete `.trellis/` manually |
| Both present | Proceed to scan + listing |
Output is split into two columns:
* **Will be deleted** — opaque files (`.py` / `.md` / `.ts`) plus structured-config files that scrub down to nothing, plus the `.trellis/` directory itself.
* **Will be modified** — structured-config files where trellis-owned entries are stripped but user-added fields are preserved.
Four scrubbers cover 11 structured config files:
| Scrubber | Files |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scrubHooksJson` (nested) | `.claude/settings.json`, `.gemini/settings.json`, `.factory/settings.json`, `.codebuddy/settings.json`, `.qoder/settings.json`, `.codex/hooks.json` |
| `scrubHooksJson` (flat) | `.cursor/hooks.json`, `.github/copilot/hooks.json` |
| `scrubOpencodePackageJson` | `.opencode/package.json` — removes `dependencies["@opencode-ai/plugin"]` |
| `scrubPiSettings` | `.pi/settings.json` — strips trellis entries from `extensions` / `skills` / `prompts` arrays; removes `enableSkillCommands` |
| `scrubCodexConfigToml` | `.codex/config.toml` — removes `project_doc_fallback_filenames` and the trellis NOTE comment block |
Command matching rule: only the last whitespace token of a `command` string (the script path) is used for comparison. Substring occurrences elsewhere (e.g. inside an `echo`) do not match.
Execution order: scrubber → `unlink` → `cleanupEmptyDirs` (prunes emptied subdirectories) → managed-root sweep (prunes empty `.claude/` / `.cursor/` / etc. top-level dirs) → `rm -rf .trellis/`. Directories that still contain user files are preserved.
Manifest-listed paths are removed unconditionally; no hash check is performed. User-modified trellis files are deleted as well.
23 new tests (15 scrubber unit + 8 integration); 830 tests pass overall.
## Bug Fixes
### Windows `python3` → `python` at write time (#218, PR [#220](https://github.com/mindfold-ai/Trellis/pull/220))
Windows has no `python3` executable. `replacePythonCommandLiterals()` runs at init/update write time on `process.platform === "win32"`:
```ts theme={null}
content
.split('\n')
.map((line) => (line.startsWith('#!') ? line : line.replaceAll('python3', 'python')))
.join('\n');
```
* **Write-time only** — template source files keep `python3`; replacement happens at file generation time.
* **Shebang preserved** — lines beginning with `#!` are not replaced.
* **Idempotent** — `python` does not contain `python3`; running multiple times produces the same result.
* **Coverage** — `configurators/{claude,codex,copilot,opencode,pi}.ts`, `configurators/shared.ts` (`writeSkills` / `writeAgents` / `writeSharedHooks` / `resolvePlaceholders` / `buildPullBasedPrelude`), `configurators/workflow.ts`, `templates/extract.ts`, `configurators/index.ts` (`collectPlatformTemplates`), `commands/update.ts` (`collectTemplateFiles`). init and update produce byte-for-byte identical output on Windows.
9 new platform-mocked unit tests in `test/configurators/shared.test.ts` cover win32/linux/darwin behavior, shebang preservation, multiline content, idempotency, and the documented `python3x` substring boundary.
### Copilot custom agent tools frontmatter (PR [#210](https://github.com/mindfold-ai/Trellis/pull/210))
`injectPullBasedPreludeMarkdown()` now uses a regex frontmatter splitter (`splitMarkdownFrontmatter`) instead of line-based scanning, handling CRLF endings cleanly. `mapLegacyToolToCopilot()` translates Claude-style tool tokens (`Read`, `Write`, `Edit`, `Glob`, ...) into Copilot's lowercase shape (`read`, `edit`, ...) so custom agents authored against the Claude convention render correctly under Copilot. Regression coverage added in `test/regression.test.ts`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@rc
trellis update
```
Projects on 0.5 (beta or earlier rc) run `trellis update`. Projects upgrading from 0.4.x run `trellis update --migrate` because the 0.5 migration chain begins at 0.5.0-beta.0. rc.2 adds no new migration entries.
# v0.5.0-rc.3
Source: https://docs.trytrellis.app/changelog/v0.5.0-rc.3
2026-05-03
Patches Gemini CLI 0.40.x template compatibility ([#224](https://github.com/mindfold-ai/Trellis/issues/224)). No new migrations.
## Bug Fixes
### Gemini CLI 0.40.x template compat (#224)
Three changes to `trellis init --gemini` output:
| File | Change |
| ------------------------------------------------------ | ---------------------------------------------------- |
| `.gemini/agents/trellis-{check,implement,research}.md` | Drop `tools:` line — sub-agent inherits parent tools |
| `.gemini/settings.json` | Hook event `UserPromptSubmit` → `BeforeAgent` |
| Shared skills destination | `.gemini/skills/` → `.agents/skills/` |
Existing Gemini installs: re-run `trellis init --gemini` or delete `.gemini/skills/` manually.
### `inject-workflow-state.py` per-platform `hookEventName`
Branches via `_detect_platform()`:
```python theme={null}
hook_event_name = (
"BeforeAgent" if _detect_platform(data) == "gemini" else "UserPromptSubmit"
)
```
### `needsCodexUpgrade()` false-positive on Gemini installs
Narrowed from any `.agents/skills/` hash entry to:
```ts theme={null}
keys.some((k) => k === '.agents/skills/trellis-continue/SKILL.md') ||
keys.some((k) => k === '.agents/skills/trellis-finish-work/SKILL.md');
```
Only Codex writes those two files. The previous broad heuristic auto-installed Codex on `trellis update` for Gemini-only projects.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@rc
trellis update
```
Projects on 0.5 (beta or earlier rc) run `trellis update`. From 0.4.x: `trellis update --migrate`.
# v0.5.0-rc.4
Source: https://docs.trytrellis.app/changelog/v0.5.0-rc.4
2026-05-05
Adds `TRELLIS_HOOKS` env var to disable Trellis hooks at runtime. No new migrations.
## Enhancements
### `TRELLIS_HOOKS=0` disables all Trellis hooks
Every shipped Trellis hook now early-returns when `TRELLIS_HOOKS=0` (or `TRELLIS_DISABLE_HOOKS=1`) is set on the host CLI process — no `additionalContext` is emitted, the host session starts clean.
| Hook | File |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Shared per-platform | `shared-hooks/session-start.py`, `inject-workflow-state.py`, `inject-subagent-context.py`, `inject-shell-session-context.py` |
| Platform-specific session-start | `codex/hooks/session-start.py`, `copilot/hooks/session-start.py` |
| OpenCode plugins | `opencode/plugins/session-start.js`, `inject-workflow-state.js`, `inject-subagent-context.js` |
Usage:
```bash theme={null}
# Wrapper for casual chat sessions — no workflow breadcrumb, no spec index
TRELLIS_HOOKS=0 claude
# Subprocess spawn — pass via env so the gate inherits to host CLI's hook subprocesses
spawn("codex", args, { env: { ...process.env, TRELLIS_HOOKS: "0" } })
```
`TRELLIS_HOOKS=0` and `TRELLIS_DISABLE_HOOKS=1` are equivalent. None of Claude Code / Codex / OpenCode / Cursor expose a true mid-session hook toggle, so the env-var gate runs at host startup.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@rc
trellis update
```
Projects on 0.5 (beta or earlier rc) run `trellis update`. From 0.4.x: `trellis update --migrate`.
# v0.5.0-rc.5
Source: https://docs.trytrellis.app/changelog/v0.5.0-rc.5
2026-05-05
Codex template enables `multi_agent_v2` with an 8-minute wait floor. `AGENTS.md` adds explicit `wait` tool rules. No new migrations.
## Enhancements
### Codex `multi_agent_v2` default-on
`.codex/config.toml` now writes the feature block instead of a commented-out hint:
```toml theme={null}
[features.multi_agent_v2]
enabled = true
max_concurrent_threads_per_session = 6
min_wait_timeout_ms = 480000
```
| Field | Value | Note |
| ------------------------------------ | ---------------- | ---------------------------------------------------------------------------------------------- |
| `enabled` | `true` | Required inside the table — the table form alone does NOT enable the feature |
| `max_concurrent_threads_per_session` | `6` | Was `4` |
| `min_wait_timeout_ms` | `480000` (8 min) | `wait()` timeout floor. Was `10000` (10 s). Forces the parent to wait through subagent runtime |
Project-level `[features]` activates only when the project is trusted. Add this to `~/.codex/config.toml`:
```toml theme={null}
[projects."/abs/path/to/your/repo"]
trust_level = "trusted"
```
### Drop legacy `codex_hooks = true`
`CodexHooks` is now `Stage::Stable` with `default_enabled: true` in Codex's feature registry, so `hooks.json` loads automatically once the project is trusted. The previous `[features].codex_hooks = true` line in the template was redundant and has been removed.
### `AGENTS.md` subagent wait rules
The Subagents section names Codex's `wait` tool and bans cancelling a subagent before it finishes:
* Wait for terminal status before yielding, acting on partial results, or spawning followups. On Codex, call `wait` with the thread id.
* Never cancel or re-spawn a subagent that hasn't finished. Raise the timeout (default 30 s, max 1 h) before judging it stuck.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@rc
trellis update
```
# v0.5.0-rc.6
Source: https://docs.trytrellis.app/changelog/v0.5.0-rc.6
2026-05-06
Windows `session-start.py` normalizes MSYS / Cygwin / WSL paths. `finish-work` Step 2 classifies dirty paths instead of aborting on any out-of-scope path. No new migrations.
## Enhancements
### `finish-work` Step 2 classifies dirty paths
For dirty paths outside `.trellis/workspace/` and `.trellis/tasks/`, Step 2 classifies into:
| Class | Action |
| ------------- | ------------------------------------------------ |
| Current task | Abort; list files; return to Phase 3.4 to commit |
| Other window | Report and continue Step 3 |
| Indeterminate | Prompt user, route by answer |
A path is classified as "current task" if it appears in the task's `prd.md` / `implement.jsonl` / `check.jsonl`, matches the task's declared scope, or was edited by the AI in this session.
Synced to 8 copies: `packages/cli/src/templates/common/commands/finish-work.md` + 5 platform copies (`.claude/`, `.cursor/`, `.opencode/`, `.pi/`, `copilot`) + 2 `SKILL.md` (`.agents/`, `codex/skills/`).
## Bug Fixes
### Windows `session-start.py`: MSYS / Cygwin / WSL paths
Fixes [#226](https://github.com/mindfold-ai/Trellis/issues/226). On Windows, `Path(val).resolve()` misparses Unix-style cwd values from Git Bash; the hook raises `ModuleNotFoundError: common` and context injection is skipped.
| Input | Normalized to |
| ------------------- | -------------- |
| `/d/Users/...` | `D:\Users\...` |
| `/cygdrive/d/...` | `D:\...` |
| `/mnt/d/...` | `D:\...` |
| `D:\...` / `D:/...` | unchanged |
Synced to 6 `session-start.py` copies: `.claude/`, `.codex/`, `.cursor/`, `templates/shared-hooks/`, `templates/codex/`, `templates/copilot/`. Non-Windows: early return.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@rc
trellis update
```
# v0.5.0-rc.7
Source: https://docs.trytrellis.app/changelog/v0.5.0-rc.7
2026-05-06
Two field-reported fixes from [#232](https://github.com/mindfold-ai/Trellis/issues/232): `trellis update` no longer downgrades the OpenCode plugin; Codex Linux sandbox `EPERM` during `python3` probe is tolerated. No new migrations.
## Bug Fixes
### `@opencode-ai/plugin` template pin: `1.1.40` → `^1.14.39`
`packages/cli/src/templates/opencode/package.json` previously hardcoded `1.1.40`. Users who manually upgraded `@opencode-ai/plugin` to 1.14.x had their `.opencode/package.json` overwritten on `trellis update`, which silently downgraded the plugin on the next `bun install` / `pnpm install`.
The new caret range pulls the latest 1.x at install time, so update no longer regresses the version.
After updating, run inside `.opencode/`:
```bash theme={null}
bun install # or pnpm/npm equivalent
```
to refresh the lockfile to the latest 1.x.
### Codex Linux sandbox: tolerate `EPERM` / `EACCES` on `python3 --version` probe
`requireSupportedPython` in `packages/cli/src/commands/init.ts` previously caught all `child_process.execSync` failures as "Python not found", aborting `trellis init`. Codex's Linux sandbox returns `EPERM` from `execSync` even when `python3` is on the host PATH — the probe was failing, not the binary.
| Error code | Old behavior | New behavior |
| ------------------------------------- | ------------------------ | --------------------------------------------------------------------------- |
| `ENOENT` (and others) | Throw "Python not found" | Same — genuine missing command still aborts |
| `EPERM` / `EACCES` | Throw "Python not found" | Warn (yellow) + proceed; assume `python3` on PATH; return "version unknown" |
| `TRELLIS_SKIP_PYTHON_CHECK=1` env var | (didn't exist) | Skip the probe entirely; return "version check skipped" |
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@rc
trellis update
```
# v0.5.1
Source: https://docs.trytrellis.app/changelog/v0.5.1
2026-05-06
Fix Codex sub-agent recursion via `SessionStart` injection ([#234](https://github.com/mindfold-ai/Trellis/issues/234)) and Cursor agent `description` field rendering. No new migrations.
## Bug Fixes
### Codex `multi_agent_v2`: fix `SessionStart` hook dispatch wording misleading sub-agents
`packages/cli/src/templates/codex/hooks/session-start.py` injects a "main session should dispatch `trellis-implement`" line when a task is in READY state. Under `multi_agent_v2` Codex runs `SessionStart` for every spawned session, so the same line reached the freshly spawned `trellis-implement` sub-agent. The sub-agent followed it and dispatched another `trellis-implement`. The outer sub-agent stayed `running` while the inner one completed; `wait_agent` in the main session timed out.
Codex `SessionStart` stdin has no agent-identity field ([`openai/codex#16226`](https://github.com/openai/codex/issues/16226)), so the hook cannot filter sub-agent sessions directly. Patched at the prompt layer:
| File | Change |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `codex/agents/trellis-implement.toml`, `trellis-check.toml` | `developer_instructions` opens with "do not dispatch `trellis-implement` / `trellis-check`" |
| `codex/hooks/session-start.py` | "if you are a sub-agent reading this, ignore the dispatch instruction" appended to the READY-state block and the `<guidelines>` block |
### `shared-hooks/session-start.py`: same as above
The same dispatch wording lives in `packages/cli/src/templates/shared-hooks/session-start.py` (Claude Code / Cursor / Gemini CLI / Qoder / CodeBuddy / Factory Droid / Kiro). The recursion has not been reported on these platforms but the trigger condition is identical to Codex. Same fix as Codex.
### Cursor: agent frontmatter `description` switched to single-line literal
`packages/cli/src/templates/cursor/agents/trellis-{research,implement,check}.md` previously used a YAML block scalar:
```yaml theme={null}
description: |
Trellis research agent. Use this exact agent ...
```
Cursor's agent parser only reads single-line `description: ...` and drops block-scalar values, leaving the UI Description field blank. Switched to single-line literals; body text unchanged.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.10
Source: https://docs.trytrellis.app/changelog/v0.5.10
2026-05-09
## Bug Fixes
* **`git add -f .trellis/` runaway prevented.** `add_session.py` and `task.py archive` now stage only specific Trellis-owned paths (journal, `index.md`, active task dir, archive subtree) and auto-retry with `git add -f -- <specific-paths>` only when stderr matches `ignored by`. The fallback warning explicitly states `Do NOT use \`git add -f .trellis/\``, listing`.trellis/.backup-\*`,`.trellis/worktrees/`,`.trellis/.template-hashes.json`,`.trellis/.runtime/`,`.trellis/.cache/`as the paths to keep ignored. Helper centralized in`templates/trellis/scripts/common/safe\_commit.py\`.
* **Pi platform `<workflow-state>` / `<session-overview>` / subagent dispatch protocol injection.** Pi extension now injects the `[workflow-state:STATUS]` breadcrumb on every `input` and `before_agent_start` event, plus a `<session-overview>` block from `.trellis/scripts/get_context.py`. The `subagent` tool registration carries a `promptSnippet` with the `Active task: <path>` dispatch protocol. Closes [#249](https://github.com/mindfold-ai/Trellis/issues/249).
* **Pi `npm:pi-subagents` project-level isolation.** `.pi/settings.json` now contains a project-level `packages` entry overriding `npm:pi-subagents` with empty resource lists, so a globally-installed `npm:pi-subagents` cannot inject `extensions / skills / prompts / themes` into the current Trellis project. `scrubPiSettings` reverses the override on `trellis uninstall`. Closes [#246](https://github.com/mindfold-ai/Trellis/pull/246) (thanks @RenaLio).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.11
Source: https://docs.trytrellis.app/changelog/v0.5.11
2026-05-10
## Bug Fixes
* **`add_session.py` / `task.py archive` no longer force-stage with `git add -f`.** When `.gitignore` excludes `.trellis/`, scripts print a warning and skip auto-commit. Reverts the auto-retry added in 0.5.10.
## Enhancements
* **New config: `session_auto_commit: true | false`** in `.trellis/config.yaml` (default `true`). Set `false` to skip auto stage + commit; journal / archive files still write to disk. Closes [#245](https://github.com/mindfold-ai/Trellis/issues/245).
* **Session-start update hint.** `get_context.py` shows `Trellis update available: <current> -> <latest>` once per session when local install lags. 1-second timeout, failures silent. Closes [#254](https://github.com/mindfold-ai/Trellis/pull/254) (thanks @jdjingdian).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.12
Source: https://docs.trytrellis.app/changelog/v0.5.12
2026-05-10
## Bug Fixes
* **`trellis update` now updates hash-tracked `.trellis/workflow.md` as a whole runtime template.** The updater no longer merges only `[workflow-state:*]` blocks, so phase headings and platform routing markers such as `codex-inline` / `codex-sub-agent` refresh together. This fixes upgraded Codex installs that had new hook scripts but stale `[Codex]` workflow blocks.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.13
Source: https://docs.trytrellis.app/changelog/v0.5.13
2026-05-11
## Bug Fixes
* **OpenCode now injects `TRELLIS_CONTEXT_ID` with the shell dialect that parses the command.** Windows Git Bash / MSYS / Cygwin sessions receive `export ...`; Windows PowerShell sessions keep `$env:...`. Duplicate-prefix detection also recognizes `env ... TRELLIS_CONTEXT_ID=...` forms.
* **Session context now handles non-Git Trellis roots.** Context output says when the root is not a Git repository instead of reporting fake clean state, and falls back to bounded child-repo discovery for unconfigured polyrepo layouts.
* **OpenCode sub-agent context is isolated from main-session context.** `trellis-implement`, `trellis-check`, and `trellis-research` child sessions skip duplicate SessionStart / workflow-state injection. Active task lookup now uses session context, `Active task:` hints, or a single-session fallback.
* **Hook timeout defaults now survive slower Windows Python cold starts.** SessionStart hooks use 30 seconds, and per-prompt workflow injection uses 15 seconds across hook-based platforms.
* **Copilot SessionStart no longer prints stale diagnostics.** The hook removes the `Copilot currently ignores sessionStart hook output` system message and keeps `hookSpecificOutput.additionalContext` as the documented payload.
## Internal
* **Spec templates document shell-dialect-aware `TRELLIS_CONTEXT_ID` prefixes.** Platform and cross-platform guides now name the OpenCode Windows POSIX-shell signals that must keep `export ...`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.14
Source: https://docs.trytrellis.app/changelog/v0.5.14
2026-05-13
## Bug Fixes
* **`task.py archive` auto-commit no longer bundles dirty changes from other task dirs.** The archive commit is now scoped to just the archived task's source + destination paths (plus any child task dirs whose `task.json` was edited as part of the parent → children relationship update). If you were editing task B in a parallel terminal while archiving task A, B's changes stay in your working tree where they belong.
* **`task.py archive` no longer leaves "phantom delete" entries against HEAD.** After `shutil.move`-ing a tracked task directory into `archive/<YYYY-MM>/`, the source-side deletions are now explicitly staged so the working tree matches HEAD immediately after archive. No more follow-up "complete archive move" fixup commits.
## Internal
* **New integration test** under `packages/cli/test/scripts/task-archive.integration.test.ts` runs the real Python script against a temp git repo and asserts both regressions (scope-creep + phantom-delete) stay fixed.
* **`safe_archive_paths_to_add()`** accepts optional `task_name` + `modified_children` parameters. Existing callers passing no arguments keep the legacy wide scope.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.15
Source: https://docs.trytrellis.app/changelog/v0.5.15
2026-05-13
## Bug Fixes
### Template manifest ownership
`trellis init`, `trellis update`, and `trellis uninstall` no longer treat user-owned platform runtime files as Trellis templates.
* `initializeHashes()` tracks platform/root files from `startRecordingWrites()` output instead of walking `.codex/`, `.claude/`, and other platform dirs.
* `pruneOrphanManifestKeys()` removes stale orphan entries from `.trellis/.template-hashes.json` before `update` and `uninstall`.
* `trellis init` and `trellis uninstall` refuse to run in `$HOME` unless `TRELLIS_ALLOW_HOMEDIR=1`.
### Windows hook encoding
Hook templates force UTF-8 on Windows for stdin, stdout, and stderr.
* `hooks.json` runs Codex `inject-workflow-state.py` with `python -X utf8`.
* `shared-hooks/inject-workflow-state.py`, `shared-hooks/session-start.py`, `codex/hooks/session-start.py`, and `copilot/hooks/session-start.py` reconfigure streams to UTF-8 with replacement errors.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.16
Source: https://docs.trytrellis.app/changelog/v0.5.16
2026-05-15
## Bug Fixes
### Cursor sessionStart hook
Cursor `sessionStart` output now matches Cursor's top-level context schema.
* Output field: `additional_context`
* Shared format retained: `hookSpecificOutput.additionalContext`
* Removed unsupported Cursor hook: `beforeSubmitPrompt`
* Removed copied Cursor file: `.cursor/hooks/inject-workflow-state.py`
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No file migration is required.
# v0.5.17
Source: https://docs.trytrellis.app/changelog/v0.5.17
2026-05-17
## Enhancements
### Built-in Trellis spec bootstrap skill
Trellis now bundles `trellis-spec-bootstarp` as a built-in multi-file skill.
* Installed automatically by `trellis init` and refreshed by `trellis update` for supported AI platforms
* Helps AI bootstrap `.trellis/spec/` from the real repository instead of generic placeholder guidance
* Includes source-backed reference files for repository analysis, spec task planning, spec writing, and MCP setup
* Replaces the older marketplace-only `cc-codex-spec-bootstrap` entry in the docs and marketplace index
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No migration command is required.
# v0.5.18
Source: https://docs.trytrellis.app/changelog/v0.5.18
2026-05-19
## Bug Fixes
### Archived task create collisions
`task.py create` now rejects a slug that already exists in `.trellis/tasks/archive/**`.
* Checks archived task directories before creating a new active task directory
* Prints the archived path that caused the collision
* Tells the user to choose a new slug for an intentional new task
### Workflow-state tool routing
`[workflow-state:in_progress]` now distinguishes sub-agent types from skills.
* `trellis-implement` and `trellis-research` are sub-agent types only
* `trellis-update-spec` is a skill
* `trellis-check` exists as both; verification after code changes should prefer the Agent form
* Prevents agents from trying to call missing `trellis-implement` / `trellis-research` skills
### Codex multi\_agent\_v2 timeout bounds
`.codex/config.toml` now emits the `multi_agent_v2` wait timeout values as a valid bounds set for Codex CLI 0.131+.
```toml theme={null}
[features.multi_agent_v2]
enabled = true
max_concurrent_threads_per_session = 6
min_wait_timeout_ms = 480000
default_wait_timeout_ms = 480000
max_wait_timeout_ms = 3600000
```
* Fixes Codex startup failure: `default_wait_timeout_ms must be at least min_wait_timeout_ms`
* Keeps the Trellis default wait at 8 minutes
* Keeps the explicit upper clamp at 1 hour
* Covers fresh `trellis init` and template refresh through `trellis update`
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No migration command is required.
# v0.5.19
Source: https://docs.trytrellis.app/changelog/v0.5.19
2026-05-21
## Bug Fixes
### Codex config.toml multi\_agent\_v2 block removed
`trellis init` / `trellis update` no longer write a `[features.multi_agent_v2]` block to the generated `.codex/config.toml`.
* Template source: `packages/cli/src/templates/codex/config.toml`
* Removed fields: `enabled`, `max_concurrent_threads_per_session`, `min_wait_timeout_ms`, `default_wait_timeout_ms`, `max_wait_timeout_ms`
v0.5.18 emitted the structured `multi_agent_v2` table. Codex CLI changed `features` deserialization between `0.130` and `0.131`: the structured table form is only accepted by `0.131+`. On `0.130` and earlier — including the Codex CLI bundled in the Codex desktop app — it fails with `data did not match any variant of untagged enum FeatureToml in features.multi_agent_v2` and aborts the entire config load, blocking Codex from starting. Codex's own default for `multi_agent_v2` is used instead; tune it in your user-level `~/.codex/config.toml` if needed.
Run `trellis update` to regenerate `.codex/config.toml` without the block.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No migration command is required.
# v0.5.2
Source: https://docs.trytrellis.app/changelog/v0.5.2
2026-05-06
Fix `SessionStart` hook crash on Python ≤3.11 (`SyntaxError: f-string expression part cannot include a backslash`). No new migrations.
## Bug Fixes
### Hook session-start: PEP 498 f-string backslash in Python ≤3.11
The Windows path normalizer added in 0.5.0-rc.6 (#226) used:
```python theme={null}
return f"{drive}:\\{rest.replace('/', '\\')}"
```
PEP 498 forbids backslashes inside f-string expression parts. On Python ≤3.11 the file fails to parse, and the hook exits with code 1 before running:
```
SessionStart hook (failed)
error: hook exited with code 1
```
PEP 701 in Python 3.12 lifted the restriction, so the bug was invisible to 3.12+ users. Codex CLI 0.128 + Trellis 0.5.0 reproduced it in the field.
Fixed by lifting the `.replace(...)` call out of each f-string expression into a local variable. 9 occurrences across:
* `packages/cli/src/templates/codex/hooks/session-start.py`
* `packages/cli/src/templates/copilot/hooks/session-start.py`
* `packages/cli/src/templates/shared-hooks/session-start.py` (Claude Code / Cursor / Gemini CLI / Qoder / CodeBuddy / Factory Droid / Kiro)
Added regression coverage in `packages/cli/test/regression.test.ts`: regex scan asserts no f-string contains a backslash inside `{...}` expressions, plus a best-effort `python3 -c "ast.parse(...)"` pass.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.3
Source: https://docs.trytrellis.app/changelog/v0.5.3
2026-05-06
Fix sub-agent context injection on class-1 platforms when the PreToolUse hook silent-skips (Windows + Claude Code, `--continue` resume, fork distributions, etc.); make `task.py start` non-blocking when session identity is missing. No new migrations.
## Bug Fixes
### Class-1 sub-agents: marker-based context loading fallback
Class-1 platforms (claude / cursor / opencode / kiro / codebuddy / droid) inject sub-agent context — `prd.md` + `implement.jsonl` / `check.jsonl` content — via `PreToolUse` hook. The hook silent-skips on Windows at v2.1.119 (upstream [`anthropics/claude-code#53254`](https://github.com/anthropics/claude-code/issues/53254)); the existing sub-agent definition files trusted the hook to always fire and had no fallback, so sub-agents ran without specs.
Add marker-based dual-channel context loading:
| Layer | File | Change |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hook (success path only) | `packages/cli/src/templates/shared-hooks/inject-subagent-context.py` | Prepend `<!-- trellis-hook-injected -->` sentinel to `build_implement_prompt` / `build_check_prompt` / `build_finish_prompt` outputs |
| Sub-agent definitions | `claude/agents/`, `cursor/agents/`, `codebuddy/agents/`, `opencode/agents/`, `droid/droids/`, `kiro/agents/` (`trellis-implement` + `trellis-check`) | Open with a `Trellis Context Loading Protocol` section: marker present → hook injected, proceed directly; marker absent → read `Active task: <path>` line from dispatch prompt, then Read `prd.md` + the relevant jsonl file yourself |
| Workflow | `packages/cli/src/templates/trellis/workflow.md` | Dispatch protocol scope changed from class-2-only to all platforms (`trellis-research` excluded) |
Class-2 platforms (codex / copilot / gemini / qoder) untouched — they already use `buildPullBasedPrelude`. `trellis-research` is intentionally not marker'd because research is decoupled from active task.
### `task.py start`: non-blocking degraded mode
`task.py start` previously hard-failed (`return 1`) when `resolve_context_key()` returned `None` — i.e. when no SessionStart hook had injected `TRELLIS_CONTEXT_ID`. The error message blamed the AI session, but the real cause is upstream: Windows + Claude Code didn't source `CLAUDE_ENV_FILE` pre-v2.1.111 and still skips PowerShell tool / `--continue` resume paths.
Replace the hard-fail with a yellow-tagged degraded-mode warning, still flip `task.json.status: planning → in_progress`, and return 0 so the AI continues based on conversation context. Happy path (`resolve_context_key()` truthy) is byte-identical to before.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.4
Source: https://docs.trytrellis.app/changelog/v0.5.4
2026-05-06
Fix Trellis sub-agent recursion when a workflow-state instruction reaches a sub-agent ([`#237`](https://github.com/mindfold-ai/Trellis/issues/237)); fix `compareVersions` dropping the tail of hyphenated prereleases ([`#230`](https://github.com/mindfold-ai/Trellis/pull/230)). No new migrations.
## Bug Fixes
### Sub-agent recursion guard
`.trellis/workflow.md`'s `[workflow-state:in_progress]` block tells the main agent to dispatch `trellis-implement` / `trellis-check` sub-agents. On Codex the same block also reaches the spawned sub-agent's turn, and the sub-agent followed the rule on itself — spawning another `trellis-implement` instead of doing the work.
Two changes:
* `[workflow-state:in_progress]` scopes the dispatch rule to the main session, and adds an explicit "if you are already a `trellis-implement` / `trellis-check` sub-agent, work directly and do not spawn another one" exemption.
* Each platform's `trellis-implement` / `trellis-check` agent definition (claude / cursor / opencode / kiro / codebuddy / droid / codex / pi / gemini / qoder) carries the same exemption, so the guard holds even if the workflow-state injection is missed.
`.trellis/spec/cli/backend/workflow-state-contract.md` updated: previously claimed only the main session could see workflow-state breadcrumbs, but Codex hooks deliver them to sub-agents too.
### `compareVersions`: hyphens inside prereleases
Thanks to [@voidborne-d](https://github.com/voidborne-d) for [`#230`](https://github.com/mindfold-ai/Trellis/pull/230).
`packages/cli/src/utils/compare-versions.ts` used `a.split("-", 2)` to separate the base version from the prerelease tag. JavaScript's `split(sep, limit)` truncates the result instead of joining the tail (unlike Python's `maxsplit`):
```js theme={null}
'1.0.0-alpha-1'.split('-', 2);
// → ["1.0.0", "alpha"] // "-1" silently dropped
```
So `compareVersions("1.0.0-alpha-1", "1.0.0-alpha-2")` returned `0` — the two versions sorted as equal. Fixed. Adds 20 test cases in `packages/cli/test/utils/compare-versions.test.ts` covering base versions, release vs prerelease, hyphenated identifiers, and version-list sorting.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.5
Source: https://docs.trytrellis.app/changelog/v0.5.5
2026-05-07
Structural fix for the Codex sub-agent recursion bug ([`#240`](https://github.com/mindfold-ai/Trellis/issues/240), [`#242`](https://github.com/mindfold-ai/Trellis/issues/242)). Removes the Codex `SessionStart` hook entirely and replaces the bootstrap path with a `trellis-start` skill invoked from `UserPromptSubmit`. No new migrations.
## Bug Fixes
### Codex sub-agent recursion (turtles all the way down)
Codex fires `SessionStart` for every spawned sub-agent session and exposes no `agent_id` / `agent_type` field on the hook input ([`openai/codex#16226`](https://github.com/openai/codex/issues/16226)). So the dispatch directive in `packages/cli/src/templates/codex/hooks/session-start.py` was being injected into every sub-agent's session start payload as well — the sub-agent read "Next required action: dispatch `trellis-implement`", thought it was the main session, and spawned its own `trellis-implement`. Then that sub-agent did the same thing.
The 0.5.4 patch ([`#237`](https://github.com/mindfold-ai/Trellis/issues/237)) added a `Sub-agent self-exemption:` clause to the same prompt block, but it sat inline alongside the dispatch directive. LLMs kept picking the command-style instruction over the conditional exemption.
Structural fix:
* Removed the `SessionStart` entry from `packages/cli/src/templates/codex/hooks.json` — the heavy session-start payload no longer reaches any session, sub-agent or main.
* `packages/cli/src/templates/shared-hooks/inject-workflow-state.py` (`UserPromptSubmit`) now injects a `<trellis-bootstrap>` block on `no_task` turns that tells the AI to invoke `$trellis-start` once. The notice carries an explicit sub-agent exemption (sub-agents read the existing `<sub-agent-notice>` first and skip everything below it).
* `packages/cli/src/configurators/codex.ts` writes `.agents/skills/trellis-start/SKILL.md` for Codex. The skill content is the existing `common/commands/start.md` template wrapped with skill frontmatter.
Sub-agent sessions now only see the `<sub-agent-notice>` from the per-turn breadcrumb. No command-style "must dispatch" text exists anywhere in the new injection, so the recursion vector is gone at source.
Other agent-capable platforms (Claude Code, Cursor, OpenCode, Kiro, etc.) keep their working `SessionStart` hooks unchanged — only Codex is affected by `openai/codex#16226`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
Codex users will get a new `.agents/skills/trellis-start/SKILL.md` file and a `hooks.json` without `SessionStart` wiring. No flag needed.
# v0.5.6
Source: https://docs.trytrellis.app/changelog/v0.5.6
2026-05-07
Two prompt-layer follow-ups for Codex `multi_agent_v2`. `AGENTS.md` documents the `fork_turns="none"` requirement on `spawn_agent` calls ([`#240`](https://github.com/mindfold-ai/Trellis/issues/240) follow-up) and the deterministic close-loop algorithm for handling `wait` completion notifications ([`#241`](https://github.com/mindfold-ai/Trellis/issues/241)). No new migrations.
## Bug Fixes
### `fork_turns="none"` requirement (#240 follow-up)
[v0.5.5](/changelog/v0.5.5) removed the `SessionStart` injection vector that hijacked sub-agent sessions. [Marsor707's local-verification comment on `#240`](https://github.com/mindfold-ai/Trellis/issues/240#issuecomment-4393264022) showed a second vector remained:
> Without `fork_turns="none"`, the child can see the parent's own `spawn_agent(...)` records and then apply the Trellis/AGENTS "wait for spawned subagents" rule to itself, causing a self-wait such as `wait_agent({"timeout_ms":480000})`.
Default Codex behavior is `fork_turns="all"` — the child inherits the parent transcript including prior `spawn_agent` tool calls, and re-applies the wait rule to itself. That's another path to `wait_agent` self-deadlock independent of the SessionStart bug.
`packages/cli/src/templates/markdown/agents.md` adds a `### Codex-only — \`spawn\_agent\` parameters`subsection telling the main session to always pass`fork\_turns="none"`. Prompt-layer only — Trellis doesn't intercept`spawn\_agent\`.
### Multi-subagent close-loop algorithm ([`#241`](https://github.com/mindfold-ai/Trellis/issues/241))
The existing rule in `AGENTS.md`:
> ALWAYS wait for every spawned subagent to reach a terminal status before yielding...
Was ambiguous. Reproduction from the issue: parent dispatched two `trellis-research` sub-agents; both completed and wrote `{task_dir}/research/*.md`; parent received `completed` notifications but kept calling `wait_agent` again instead of reading deliverables and closing. User-side appearance: stuck waiting.
`packages/cli/src/templates/markdown/agents.md` adds a `### Codex-only — multi-subagent close-loop` subsection with the deterministic algorithm proposed in the issue:
1. Maintain `expected_agents` set.
2. After each `wait` update: `list_agents`, verify deliverables for terminal agents, `close_agent`, remove from set.
3. Continue waiting only if `expected_agents` still has running agents.
4. Never `wait` on an agent already reported `completed`.
Both subsections are prompt-layer-only — no script, hook, or configurator behavior changed.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
`AGENTS.md` gets two new subsections under `## Subagents`. Other platforms see the `Codex-only` labels and can skip those subsections.
# v0.5.7
Source: https://docs.trytrellis.app/changelog/v0.5.7
2026-05-08
After upgrading Codex 0.129, run `/hooks` once and approve the Trellis hook (without approval the workflow won't auto-inject; details below). New `codex.dispatch_mode` knob lets Codex projects opt into `inline` dispatch. Fixes: Codex sub-agent `wait_agent` deadlock ([`#240`](https://github.com/mindfold-ai/Trellis/issues/240) follow-up, [`#241`](https://github.com/mindfold-ai/Trellis/issues/241)), Kiro CLI rejecting agent JSON ([`#247`](https://github.com/mindfold-ai/Trellis/issues/247)), Windows `trellis init` not finding `python3` / `py -3` ([`#236`](https://github.com/mindfold-ai/Trellis/issues/236)). No new migrations.
## Codex 0.129 compatibility
### `/hooks` review gate (TUI approval required)
Codex 0.129 gates each installed hook behind a one-time `/hooks` TUI review. Until the user runs `/hooks` in Codex and approves the Trellis `UserPromptSubmit` hook, the workflow breadcrumb won't auto-inject; every fresh Codex session looks like Trellis isn't wired in.
The existing `<trellis-bootstrap>` fallback in `inject-workflow-state.py` covers this gap: when the hook hasn't fired, the fallback directs the AI to read the `trellis-start` skill manually so the workflow still runs (just less smoothly). No Trellis code change needed for the fallback. **Run `/hooks` once after upgrading Codex** to restore full auto-injection.
### `[features].codex_hooks` to `[features].hooks` rename
Codex 0.129 renamed `[features].codex_hooks` to `[features].hooks` (legacy name still works but emits a deprecation warning on startup). Trellis docs (`advanced/multi-platform`, `advanced/architecture`, `advanced/custom-hooks`, `advanced/appendix-f`, `start/install-and-first-task`, `start/everyday-use`, `start/how-it-works`), the `spec/cli/backend/platform-integration.md` rules, and the `trellis init` runtime warning now point at the new name. The uninstall scrubber recognizes both `hooks = true` and the legacy `codex_hooks = true` so older projects still clean up cleanly.
## Enhancements
### Codex configurable dispatch mode
New project-level knob in `.trellis/config.yaml`:
```yaml theme={null}
codex:
dispatch_mode: sub-agent # default; set to "inline" to skip sub-agent dispatch
```
When `inline` is set, the `<workflow-state>` breadcrumb tells the main Codex agent to load `trellis-before-dev`, edit code directly, then load `trellis-check` for lint / typecheck / tests, instead of dispatching `trellis-implement` / `trellis-check` sub-agents.
Mechanism: `inject-workflow-state.py` reads the config and resolves `[workflow-state:in_progress-inline]` / `[workflow-state:planning-inline]` blocks from `workflow.md` when codex+inline is set; `get_context.py --platform codex` swaps to the `[Kilo, Antigravity, Windsurf]` block content. Per-turn override phrases (`do it inline` / `你直接改` / etc.) keep working in both modes.
Codex-only. Class-1 platforms (Claude Code, Cursor, OpenCode, Kiro, CodeBuddy, Droid) and the other class-2 platforms keep the dispatch default. `.codex/agents/*.toml` files are still written; sub-agent infrastructure stays installed.
### `configSectionsAdded` manifest field
New optional manifest field declares which top-level keys this release introduces in `.trellis/config.yaml`:
```jsonc theme={null}
{
"version": "0.5.7",
"configSectionsAdded": [
{
"file": ".trellis/config.yaml",
"sentinel": "codex:",
"sectionHeading": "Codex (sub-agent dispatch behavior)",
},
],
}
```
`trellis update` walks each manifest's `configSectionsAdded`, and for each entry whose `sentinel` is missing from the user's target file, appends the section content extracted from the bundled template. Append-only, idempotent (sentinel check on rerun). User customizations stay untouched. Future config additions declare a new entry in their own manifest, no `update.ts` change needed per addition.
Replaces the prior "modified-file confirm prompt" path, where users who customized `config.yaml` had to either accept template (losing edits) or skip (missing the new section).
## Bug Fixes
### Codex sub-agent collab tools, structural disable ([`#240`](https://github.com/mindfold-ai/Trellis/issues/240) follow-up, [`#241`](https://github.com/mindfold-ai/Trellis/issues/241))
[v0.5.5](/changelog/v0.5.5) removed the `SessionStart` injection vector. [v0.5.6](/changelog/v0.5.6) added prompt-layer `fork_turns="none"` guidance to `AGENTS.md`. Both were prompt-layer mitigations. [Ca11back's reproduction on `#241`](https://github.com/mindfold-ai/Trellis/issues/241) showed the prompt-layer fix didn't reach reality:
* The main agent still spawned `trellis-research` with default `fork_turns="all"` despite the AGENTS.md rule.
* The child inherited the parent's transcript including prior `spawn_agent(...)` tool-call records.
* The child read AGENTS.md's "ALWAYS wait for every spawned subagent..." rule, applied it to *itself*, and called `wait_agent` on the inherited records.
* No agents to wait for. `No agents completed yet`. Stuck.
Structural fix: each `packages/cli/src/templates/codex/agents/trellis-{implement,check,research}.toml` now contains:
```toml theme={null}
[features]
multi_agent = false
[features.multi_agent_v2]
enabled = false
```
With both flags off, Codex doesn't register `spawn_agent` / `wait_agent` / `list_agents` / `close_agent` for the sub-agent.
Adds `[issue-241-followup]` regression test asserting all three template toml files retain the disable block.
### Codex `trellis-start` skill missing on update path
0.5.5's `configureCodex()` writes `.agents/skills/trellis-start/SKILL.md` so the `<trellis-bootstrap>` notice from `inject-workflow-state.py` resolves to a real skill. But `collectPlatformTemplates.codex.collectTemplates()` (used by `trellis update`) was missed.
Result: users upgrading from 0.4.x to 0.5.5/0.5.6 ran the safe-file-delete migration that removed `.agents/skills/start/`, then `trellis update` regenerated all the other `trellis-*` skill dirs from `collectTemplates`, but never wrote `trellis-start`. Their AI then reported "no `.agents/skills/trellis-start/SKILL.md`" on every turn that hit `<trellis-bootstrap>`.
Fix: extracted `resolveCodexTrellisStartSkill()` helper in `configurators/shared.ts`, called from both `configureCodex()` (init) and `collectPlatformTemplates.codex` (update) so the file shows up on both paths. No drift possible. Both call the same helper.
### Kiro CLI agent JSON schema migration ([`#247`](https://github.com/mindfold-ai/Trellis/issues/247))
Kiro CLI rejected Trellis's pre-0.5.7 agent JSON with "invalid agent". Three schema changes per Kiro's [Agent Configuration Reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference):
1. **`instructions` becomes `prompt`**. Kiro CLI no longer accepts `instructions`.
2. **Adds `allowedTools` field** mirroring `tools`. Kiro splits "available tools" from "permitted tools"; without `allowedTools` the agent can't actually invoke anything.
3. **`hooks` array becomes object keyed by event name**:
```json theme={null}
// before
"hooks": [
{ "on": "agentSpawn", "command": "...", "timeout_ms": 30000 }
]
// after
"hooks": {
"agentSpawn": [{ "command": "..." }]
}
```
`on` field removed (event is now the key). `timeout_ms` removed.
Affects all three `trellis-{implement,check,research}.json` files. Adds `[issue-247]` regression test asserting the new schema (prompt present, instructions absent, allowedTools array, hooks object not array).
### Windows Python detection fallback chain ([`#236`](https://github.com/mindfold-ai/Trellis/issues/236))
`trellis init` previously tried only `python --version` on Windows. If the host had Python under `python3` (Microsoft Store) or `py -3` (python.org launcher) but not `python`, init failed outright with `Python command "python" not found`.
`resolveSupportedPython()` in `packages/cli/src/commands/init.ts` now walks a per-platform candidate list:
| Platform | Candidate order |
| -------- | ---------------------------- |
| Windows | `python`, `python3`, `py -3` |
| Other | `python3`, `python` |
First candidate whose `--version` matches Python ≥ 3.9 wins. The resolved command is cached via `setResolvedPythonCommand()` in `configurators/shared.ts` so `replacePythonCommandLiterals()` and all downstream template / configurator writes pick up the same value.
Two env-var escape hatches:
* `TRELLIS_PYTHON_CMD=<cmd>` for explicit override (no probe).
* `TRELLIS_SKIP_PYTHON_CHECK=1` for skipping the probe entirely (pre-existing).
Failure case throws an aggregated error listing every candidate's probe result plus a Windows-specific install hint pointing at python.org with the "Add Python to PATH" reminder.
6 new unit tests in `packages/cli/test/commands/init-internals.test.ts` cover the fallback chain, env-var overrides, sandbox-restricted EPERM, and aggregated failure mode.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` needed. Codex users get hardened sub-agent role files; Windows users no longer need to install 0.4.0 first. Codex 0.129+ users should run `/hooks` once after upgrading Codex to approve the Trellis `UserPromptSubmit` hook.
# v0.5.8
Source: https://docs.trytrellis.app/changelog/v0.5.8
2026-05-08
## Bug Fixes
* **Removing the sub-agent guidance in `AGENTS.md` stops Codex from calling / waiting on research agents.** Deleted the `## Subagents` section (36 lines, including the "ALWAYS wait for every spawned subagent" rule).
* **Sub-agent mode fix: `trellis-research` on Codex no longer exits prematurely / produces no research files due to missing task context** (the main agent now includes the `Active task:` line when dispatching to research agents too).
## Added
* `CoreRule` block prepended to the `trellis-brainstorm` skill (adapted from [https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md](https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md) ).
## Other Platforms
Claude Code, Cursor, OpenCode, Kiro, CodeBuddy, and Droid unchanged.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.5.9
Source: https://docs.trytrellis.app/changelog/v0.5.9
2026-05-08
## Bug Fixes
* **Codex `dispatch_mode` default flipped from `sub-agent` to `inline`.** Codex sub-agents run with `fork_turns="none"` isolation, so they can't inherit the parent session's task context — they either exit silently or recursively dispatch. Inline mode keeps the main Codex agent in charge so context isn't lost. To opt back into the legacy dispatch flow, uncomment `codex.dispatch_mode: sub-agent` in `.trellis/config.yaml`. Invalid values fall back to inline.
* **`--platform codex` now namespaces into `codex-inline` / `codex-sub-agent` virtual platforms.** `workflow.md` `[Platform A, B, ...]` blocks render different guidance per mode (inline mode tells the main agent to edit code; sub-agent mode tells it to dispatch `trellis-implement` / `trellis-check`). `inject-workflow-state.py` emits a `<codex-mode>` banner in the per-turn UserPromptSubmit prompt so Codex knows which mode it is in. `[workflow-state:STATUS-inline]` blocks drive the breadcrumb path for inline mode.
## Internal
* Restored `0.6.0-beta.0.json` on `main`. The version was published from `feat/v0.6.0-beta` but its manifest never landed on main, breaking adjacent-version update chains for users hopping between stable and beta lines.
## Other Platforms
Claude Code, Cursor, OpenCode, Kiro, CodeBuddy, Droid, Gemini, Qoder, Copilot — unchanged.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
# v0.6.0
Source: https://docs.trytrellis.app/changelog/v0.6.0
2026-06-15
Stable promotion of `0.6.0-rc.0` with no new src/ changes. v0.6.0 is a breaking release from 0.5.x — multi-agent collaboration via `trellis channel`, a published `@mindfoldhq/trellis-core` SDK, and cross-session memory recall via `trellis mem`.
<Tip>
**Multi-agent collaboration is now a first-class primitive.** `trellis channel` ships a
worker-supervisor runtime with Claude `stream-json` and Codex `app-server` adapters, persistent
event logs under `~/.trellis/channels/`, forum/thread channels for issue-style boards, a default
OOM guard, and reusable lifecycle/subscription APIs in `@mindfoldhq/trellis-core/channel`. The
bundled `check` / `implement` agent definitions auto-install with `trellis init` / `trellis
update`, so `channel spawn --agent check` works out of the box. See the "[Multi-agent
collaboration](#multi-agent-collaboration)" section below.
</Tip>
<Note>
**Codex users — upgrade caveat in 0.6.0:**
* **`[features.multi_agent_v2]` block removed (beta.21)** — Codex CLI changed `features` deserialization between 0.130 and 0.131. The structured table form only loads on 0.131+; on 0.130 and earlier (including the Codex desktop app's bundled CLI) it failed with `data did not match any variant of untagged enum FeatureToml in features.multi_agent_v2` and aborted config load. `trellis init` / `trellis update` no longer write this block — Codex's own default is used. Tune it yourself in `~/.codex/config.toml` if needed.
* **`codex.dispatch_mode: inline` is the default (beta.1)** — Codex sub-agents run with `fork_turns="none"`, so they can't inherit the parent session's task context. The main Codex agent now edits code directly. Opt back into sub-agent dispatch via `codex.dispatch_mode: sub-agent` in `.trellis/config.yaml`.
</Note>
<Note>
**New platforms in 0.6.0:**
* **Reasonix (DeepSeek-Reasonix)** — 15th supported AI coding tool, available via `trellis init --reasonix`. Skills live at `.reasonix/skills/<name>/SKILL.md`; slash commands are platform-built-in. Sub-agent skills carry `runAs: subagent` for isolated subagent loops. Closes `#301`.
* **Pi Agent — native `trellis_subagent` extension** — Pi now exposes `trellis_subagent` (avoiding the `subagent` namespace collision with community packages) with `single` / `parallel` / `chain` dispatch modes, native progress cards (`Alt+O` for detail view), throttled live updates, and Trellis-agent validation. Closes `#286`, `#290`.
</Note>
<Note>
**OpenCode users — reader temporarily unavailable:**
* **`trellis mem` returns empty on OpenCode 1.2+** — OpenCode 1.2 moved session storage to SQLite. The beta.3 SQLite reader added a `better-sqlite3` native dependency that failed to install on machines without a C toolchain, so it was reverted in beta.4. `trellis mem list / search / extract` now returns empty with a one-shot stderr warning for OpenCode; Claude and Codex paths are unchanged. A permanent OpenCode reader rework is deferred past v0.6.0.
</Note>
<Warning>
**Known upstream issues at GA cut (not fixable from Trellis):**
* **OpenCode 1.2+ SQLite session reader** — see the `<Note>` above. Tracked for v0.7+.
* **Feature requests deferred past v0.6** — `#193`, `#318`, `#320`, `#325`, `#326` and similar tracker items are explicitly punted to v0.7 or later per the `rc.0` cut.
</Warning>
## Multi-agent collaboration
`trellis channel` is the headline addition of v0.6.0 — a worker-supervisor primitive for coordinating multiple AI processes through a shared event log.
### `trellis channel` runtime
* `channel create | send | wait | spawn | run | list | messages | kill | rm | prune` subcommands.
* Claude `stream-json` and Codex `app-server` JSON-RPC adapters translate provider output into normalized `message` / `progress` / `done` / `error` events.
* Events persist to `~/.trellis/channels/<project>/<channel>/events.jsonl` with locked sequence assignment.
* Every subcommand accepts `--scope project|global` for explicit project-or-global targeting.
### Forum and thread channels
`--type threads` and `--type forum` produce durable issue/thread-style boards. `channel post | threads | thread | forum` subcommands plus `channel context add | delete | list`, `channel title set | clear`, and `channel thread rename` cover the lifecycle. Events can carry stable `--description`, `--context-file`, `--context-raw` (legacy `--linked-context-*` aliases preserved).
### Worker coordination
* `channel wait --kind done,killed` — multi-kind filter.
* `channel spawn --warn-before <duration>` emits a `supervisor_warning` event (5m default lead time; disable via `0ms`).
* Codex workers record completed answers before `done` and serialize non-interrupt turns (`turn_started` / `turn_finished` / `interrupt_requested` / `interrupted`).
* Codex channel `progress` events carry `detail.kind` (`output | commentary | reasoning`), `detail.stream_id`, `detail.phase`, `detail.text_delta`. Consumers should group deltas by `stream_id` and treat `kind:"message"` as the canonical completed answer.
### Channel worker OOM guard
Default safeguards `channel.worker_guard.idle_timeout` (5m) and `channel.worker_guard.max_live_workers` (6), configurable per-spawn (`--idle-timeout`, `--max-live-workers`) or via env vars (`TRELLIS_CHANNEL_WORKER_IDLE_TIMEOUT`, `TRELLIS_CHANNEL_MAX_LIVE_WORKERS`). Idle workers emit `killed` with `reason: "idle-timeout"`; mid-turn workers are never killed.
### Message-routing cleanup + durable idempotency
Tag-based routing is removed from `send.ts` / `wait.ts` / provider adapters — tags are kept only on channel events, worker inbox policy, and explicit `to`. `sendMessage` and `postThread` accept a durable `idempotencyKey` option: repeated writes with the same key return the original JSONL event without producing duplicate `undeliverable` events.
### Channel runtime agent definitions auto-dispatched
`trellis init` and `trellis update` now ship platform-agnostic `.trellis/agents/{check,implement}.md` on every install, so `trellis channel spawn --agent check` works out of the box. `trellis workflow --template <id>` prints a non-blocking stderr warning when the resolved workflow references missing `.trellis/agents/<name>.md` files (detection via `utils/agent-refs.ts`). Closes `#323`.
## Memory (`trellis mem`)
A local CLI that indexes Claude Code and Codex conversation logs already on disk and exposes them through `list`, `search`, `context`, `extract`, and `projects` subcommands. Nothing is uploaded. (84 unit tests, 81.89% coverage on first ship.)
### Phase slicing
`mem extract <id> --phase brainstorm` slices between `task.py create` and `task.py start`; `--phase implement` is the inverse; `--phase all` is the default. Multi-task sessions are separated by `--- task: <slug> ---`. The `--phase` parser handles `$(... --slug NAME)` substitution, multiple `task.py` invocations per Bash command, and `task.py start` inside commit-message heredocs.
### Cross-day session window correctness
`--since` now filters by `inRangeOverlap(start, end, filter)` — sessions match if `[created, updated]` overlaps `[since, until]`. The previous "session created in range" filter dropped 29MB Claude sessions that started on day N–1 and were still being written on day N, even when they contained 19 matching turns written that day.
### Reusable retrieval primitives
`@mindfoldhq/trellis-core/mem` exports `listMemSessions`, `searchMemSessions`, `readMemContext`, `extractMemDialogue`, `listMemProjects`, with per-platform adapters under `packages/core/src/mem/adapters/`. The CLI is a thin wrapper.
## Platform coverage
v0.6.0 supports 15 AI coding tools: Claude Code, Codex, Cursor, OpenCode, Gemini, Kiro, Qoder, CodeBuddy, Droid, Pi, GitHub Copilot, Windsurf, Kilo Code, Factory, and the new Reasonix.
* **Reasonix (DeepSeek-Reasonix), new** — 15th supported platform via `trellis init --reasonix`. Skills under `.reasonix/skills/<name>/SKILL.md`; sub-agent skills carry `runAs: subagent`. Closes `#301`.
* **Pi Agent — native `trellis_subagent` extension matured** — `single` / `parallel` / `chain` dispatch modes, native progress cards (`Alt+O` for detail view), throttled live updates, Trellis-agent validation. Closes `#286`, `#290`.
* **Codex — inline mode default** — `codex.dispatch_mode: inline` lets the main Codex agent edit code directly (sub-agents can't inherit task context under `fork_turns="none"`). Opt back into `sub-agent` via `.trellis/config.yaml`.
* **OpenCode — shell-dialect `TRELLIS_CONTEXT_ID`** — hook command now emits a shell-aware export so `$TRELLIS_CONTEXT_ID` resolves correctly across POSIX shells and OpenCode 1.2+ runners.
* **Cursor — sessionStart `additional_context`** — hook payload now uses the documented `additional_context` field, restoring task-context injection on session resume.
* **GitHub Copilot — hook payload corrected** — Copilot-specific hook envelope schema fixed so context injection lands on the Copilot side without truncation.
## SDK extraction (`@mindfoldhq/trellis-core`)
A second published package, `@mindfoldhq/trellis-core`, exposes `/channel`, `/task`, `/testing` subpath exports. The CLI now depends on it; both packages share one git tag, one npm dist-tag, and one version per release. `.github/workflows/publish.yml` publishes `@mindfoldhq/trellis-core` before `@mindfoldhq/trellis`, and post-publish `verify-npm --package all` confirms both on the public npm registry.
### Exported APIs
| Module | Surface |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@mindfoldhq/trellis-core/channel` | `listWorkers`, `watchWorkers`, `spawnWorker`, `requestInterrupt`, `interruptWorker`, `readChannelEvents`, `watchChannels`, `readWorkerInbox`, `watchWorkerInbox`, `WorkerInboxError`, `matchesInboxPolicy` |
| `@mindfoldhq/trellis-core/mem` | `listMemSessions`, `searchMemSessions`, `readMemContext`, `extractMemDialogue`, `listMemProjects` |
| `@mindfoldhq/trellis-core/task` | task lifecycle primitives |
| `@mindfoldhq/trellis-core/testing` | test helpers shared with the CLI |
## Workflow + planning
### Task triage consent gates
No-task turns now classify the request. Simple/small requests ask only whether to create a Trellis task; if not, Trellis is skipped for the turn. Complex requests ask permission to create a task and enter planning; if declined, scope is clarified or a smaller split suggested.
### Planning artifacts (`prd.md` / `design.md` / `implement.md`)
`task.py create` creates a default `prd.md`. Complex planning uses `prd.md` (requirements, constraints, acceptance criteria, out-of-scope), `design.md` (boundaries, data flow, contracts, tradeoffs), and `implement.md` (checklist, validation commands, review gates) before `task.py start`. Implement/check context loading order is consistent across hook-push, pull-prelude, Pi extension, OpenCode plugin, and inline modes: `jsonl entries → prd.md → design.md → implement.md`.
### Workflow templates (selectable + switchable)
`trellis init --workflow / --workflow-source` and `trellis workflow` switch between built-in flavors `native`, `tdd`, `channel-driven-subagent-dispatch`, plus marketplace templates via `workflow-resolver.ts`. The active file remains `.trellis/workflow.md`.
### Parent / child task trees
`.trellis/workflow.md` and `get_context.py --mode phase --step 1.1` document parent/child task tree usage. Breadcrumbs `[workflow-state:planning]` and `[workflow-state:planning-inline]` updated. The `trellis-brainstorm` and `trellis-meta` skills cover the pattern.
### Check agents read artifacts first
Check agents now require `prd.md` and optionally read `design.md` / `implement.md` before checking code. Applied to Claude Code, Cursor, OpenCode, Gemini, Kiro, Qoder, CodeBuddy, Droid, and Pi.
### Workflow-state tool routing — agents vs skills
`trellis-implement` and `trellis-research` are declared as sub-agent types only; `trellis-update-spec` is a skill; `trellis-check` exists as both (verification after code changes prefers the Agent form).
## Updater
### `trellis upgrade` command
Wraps `npm install -g @mindfoldhq/trellis@<channel>` with channel-aware defaults (`latest`, `beta`, `rc`). Flags: `--tag <tag>` for explicit dist-tag/version, `--dry-run` to preview. Validates input, avoids shell interpolation on POSIX, uses `cmd.exe /d /s /c` on Windows, prints npm/PATH troubleshooting on failure. Session-start hints now point at `trellis upgrade`.
### Registry-backed `.trellis/spec` refresh
`trellis init --template <id>` persists the spec source and template id into `.trellis/config.yaml` under a new `registry.spec` block. `trellis update` reads that block, downloads the configured spec registry into a temp dir, and feeds it through the existing hash / conflict / "modified by you" flow. Supports direct spec registries and marketplace-style registries, including SSH and self-hosted Git. New utility: `utils/registry-config.ts`. Closes `#315`.
### Configurable hooks via `.trellis/config.yaml`
| Knob | Controls |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `session_commit_message` / `max_journal_lines` / `session_auto_commit` | journal auto-commit shape |
| `hooks.after_create` / `after_start` / `after_finish` / `after_archive` | user shell commands run after each task lifecycle event |
| `channel.worker_guard.idle_timeout` / `max_live_workers` | channel worker OOM protection |
| `codex.dispatch_mode: inline \| sub-agent` | whether the main Codex agent edits code directly or routes through `trellis-implement` / `trellis-check` sub-agents |
Existing projects receive commented-out blocks via `configSectionsAdded` on `trellis update`.
### Updater hardening
`initializeHashes()` tracks platform/root files from `startRecordingWrites()` output instead of walking `.codex/` / `.claude/`. `pruneOrphanManifestKeys()` removes stale orphans before `update` and `uninstall`. `trellis init` / `uninstall` refuse to run in `$HOME` unless `TRELLIS_ALLOW_HOMEDIR=1`. `trellis update` refreshes hash-tracked `.trellis/workflow.md` as a whole template (fixes upgraded Codex installs with stale `[Codex]` blocks). Hook templates force UTF-8 on Windows (`python -X utf8` + stdio reconfigure with replacement errors).
## Bundled skills
### `trellis-channel`
New bundled capability skill that teaches the AI when to reach for `trellis channel` — multi-agent collaboration, spawned workers, cross-agent review, progress inspection, forum/thread boards, and channel log debugging. SKILL.md plus five reference files (workflows, forum, workers, progress-debugging, command-reference). Auto-dispatched on every supported platform via `getBundledSkillTemplates()` directory scan.
### `trellis-meta`
Rewritten for v0.6 architecture. SKILL.md preamble now covers the channel runtime, `trellis mem`, and dual-package SDK; description triggers cover bundled-skill auto-dispatch. New `references/local-architecture/multi-agent-channel.md` and `references/local-architecture/bundled-skills.md` explain channel-vs-other primitives, where state lives, `.trellis/config.yaml channel.*` knobs, and bundled vs project-local ownership / override convention. `platform-files/platform-map.md` adds the Reasonix row (15th platform) and Pi native `trellis_subagent` annotation; `customize-local/change-skills-or-commands.md` expands the platform path table from 6 to 13 platforms and documents anti-collision rules for all four bundled skills.
### `trellis-spec-bootstrap`
Platform-neutral bundled skill at `templates/common/bundled-skills/trellis-spec-bootstrap/` provides source-backed references for repository analysis, spec task planning, spec writing, and MCP setup. Auto-installed across all platforms on `trellis init` / `trellis update`, replacing the older `cc-codex-spec-bootstrap` marketplace entry. The beta.23 `rename-dir` migration renames already-installed typoed directories across `.claude/skills/`, `.cursor/skills/`, `.opencode/skills/`, `.agents/skills/`, `.kiro/skills/`, `.qoder/skills/`, `.codebuddy/skills/`, `.github/skills/`, `.factory/skills/`, `.pi/skills/`, `.agent/skills/`, `.windsurf/skills/`, `.kilocode/skills/`. Closes `#296`.
### `trellis-session-insight`
A capability skill that teaches the AI when to reach for `trellis mem` (past-solution recall, decision retrieval, cross-session continuation, familiar-bug debugging, self-pattern spotting, finish-work retrospective) with verbatim English + Chinese triggering phrases. Intentionally does not prescribe a fixed write-back file — what to do with what `mem` returns is judged in the moment based on the live conversation. Auto-dispatched to every supported platform.
## Bug Fixes
### `trellis-implement` / `trellis-check` no longer silent-skip when Exa MCP is absent
The bundled `trellis-implement` and `trellis-check` agent definitions declared `mcp__exa__web_search_exa` and `mcp__exa__get_code_context_exa` as explicit tools. Claude Code's `tools:` parser silently skips agent registration when an explicit MCP tool name fails to resolve, so users without Exa MCP installed had every Trellis sub-agent disappear from the dispatch list — the main agent ended up implementing work itself rather than delegating.
Fix:
* `trellis-implement` and `trellis-check` drop both `mcp__exa__*` entries. These agents do not need external web search; the tools list shrinks to `Read, Write, Edit, Bash, Glob, Grep`.
* `trellis-research` folds the previous `mcp__exa__*` + `mcp__chrome-devtools__*` entries into a single `mcp__*` wildcard. Claude Code resolves wildcards lazily (no silent-skip when nothing matches), so this opts research into any MCP the user has configured without locking the source template to a specific provider.
* The Copilot transformer (`mapLegacyToolToCopilot` in `packages/cli/src/configurators/shared.ts`) gets a matching case for `mcp__*` that emits the full set of supported Copilot MCP equivalents.
OpenCode agent files use a different permission mapping syntax (`mcp__exa__*: allow`) that does not silent-skip, so they are intentionally left unchanged. Closes `#302`.
## Breaking changes & upgrade
The breaking-change gate fires at `0.6.0-beta.0` — that manifest carries the rename + delete migration chain. The `0.6.0` manifest itself has `breaking: false` and no migrations (rc.0 → GA is zero source change), but users coming from any `0.5.x` will traverse `0.6.0-beta.0.json` during the manifest chain walk, which IS breaking. Pass `--migrate` so the chain is honored.
## RC stabilization
v0.6.0 GA = `0.6.0-rc.0` with zero `src/` changes; no rc.1 cut was needed. The breaking work happened at `0.6.0-beta.0` and the migration chain was absorbed throughout the beta line.
## Upgrade
From 0.5.x:
```bash theme={null}
trellis update --migrate
```
The `--migrate` flag is REQUIRED — the breaking-change gate from `0.6.0-beta.0` fires when traversing the migration chain. Local customizations are preserved with a warning. Per-prompt `reason` field explains version-specific nuances inline.
<Warning>
Users running `update --migrate` from a 0.5.x install will also see a `rename-dir` migration that fixes the bundled skill directory name from `trellis-spec-bootstarp/` → `trellis-spec-bootstrap/` across every configured platform skill root. This is automatic and idempotent; missing roots silently skip.
</Warning>
From any 0.6.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
```
# v0.6.0-beta.0
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.0
2026-05-08
First 0.6 beta. Adds `trellis mem`: search past Claude Code, Codex, and OpenCode sessions by keyword, read the turns around each match, and dump full conversations.
## New feature: `trellis mem`
Reads each platform's session files on disk (Claude Code, Codex, OpenCode), strips hook injections, AGENTS.md preambles, and tool-call noise, then lets you search by keyword and read the actual dialogue around each match.
```bash theme={null}
trellis mem list # list sessions across platforms
trellis mem search "user login" # find sessions whose contents match
trellis mem context <session-id> # top-N hit turns + surrounding context
trellis mem extract <session-id> # dump cleaned dialogue (--grep KW to filter)
trellis mem projects # list active project cwds (AI-routing entry)
```
Subcommands accept filters: `--since 2026-04-01`, `--cwd /abs/path`, `--platform claude|codex|opencode`, `--json`. Run `trellis mem help` for the full reference.
Mechanics:
* Reads `~/.claude/projects/<encoded-cwd>/<uuid>.jsonl` (Claude Code), Codex session JSON, and OpenCode `<storage>/messages/<session-id>/*.json`. No live process attach; works on closed sessions.
* Strips workflow-state breadcrumbs, session-context blocks, and hook output so search hits surface real user / assistant turns. Handles compaction (Claude `isCompactSummary` + Codex `compacted` events).
* 84 unit tests (Tier 1 pure helpers + Tier 2 fixture-driven platform parsers + Tier 3 subcommand integration). mem.ts coverage: 81.89% statement / 89.04% function / 87.93% line.
## Install
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
This is a beta. The 0.5 stable line continues to receive patches if needed; install latest stable with `@latest` instead. Switch back from beta to stable with `npm install -g @mindfoldhq/trellis@latest`.
# v0.6.0-beta.1
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.1
2026-05-08
Beta patch shipping the same Codex dispatch fix as `0.5.9`.
## Bug Fixes
* **Codex `dispatch_mode` default flipped from `sub-agent` to `inline`.** Codex sub-agents run with `fork_turns="none"` isolation, so they can't inherit the parent session's task context — they either exit silently or recursively dispatch. Inline mode keeps the main Codex agent in charge so context isn't lost. To opt back into the legacy dispatch flow, uncomment `codex.dispatch_mode: sub-agent` in `.trellis/config.yaml`. Invalid values fall back to inline.
* **`--platform codex` now namespaces into `codex-inline` / `codex-sub-agent` virtual platforms.** `workflow.md` `[Platform A, B, ...]` blocks render different guidance per mode (inline mode tells the main agent to edit code; sub-agent mode tells it to dispatch `trellis-implement` / `trellis-check`). `inject-workflow-state.py` emits a `<codex-mode>` banner in the per-turn UserPromptSubmit prompt so Codex knows which mode it is in. `[workflow-state:STATUS-inline]` blocks drive the breadcrumb path for inline mode.
## Other Platforms
Claude Code, Cursor, OpenCode, Kiro, CodeBuddy, Droid, Gemini, Qoder, Copilot — unchanged.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-beta.10
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.10
2026-05-12
Adds `trellis channel`, a CLI runtime for coordinating worker agents through a shared event log.
## Enhancements
### Trellis Channel
`trellis channel` manages collaboration sessions, messages, worker processes, waits, cleanup, and one-shot runs.
| Command | Behavior |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `trellis channel create <name>` | Creates a channel session. |
| `trellis channel send <name>` | Writes a message event. |
| `trellis channel wait <name>` | Blocks until matching events arrive. |
| `trellis channel spawn <name>` | Starts a Claude or Codex worker. |
| `trellis channel run [name]` | Creates an ephemeral channel, runs one worker, prints the final answer, and cleans up. |
| `trellis channel list` / `messages` / `kill` / `rm` / `prune` | Inspect, terminate, remove, and clean channel state. |
### Channel adapters
Claude and Codex worker output is normalized into channel events.
| Adapter | Source protocol | Event output |
| ------------------------------------------------------ | --------------------------- | -------------------------------------- |
| `packages/cli/src/commands/channel/adapters/claude.ts` | Claude `stream-json` | `message`, `progress`, `done`, `error` |
| `packages/cli/src/commands/channel/adapters/codex.ts` | Codex `app-server` JSON-RPC | `message`, `progress`, `done`, `error` |
### Channel store
Channel events are written to project-scoped JSONL logs with locked sequence assignment.
| Path | Purpose |
| ------------------------------------------------------ | ------------------------------------------------------- |
| `~/.trellis/channels/<project>/<channel>/events.jsonl` | Channel event stream. |
| `packages/cli/src/commands/channel/store/events.ts` | Append-only event writes and `seq` assignment. |
| `packages/cli/src/commands/channel/store/paths.ts` | Project bucket selection and legacy channel relocation. |
## Internal
### Channel supervisor modules
Channel runtime internals are split into adapter parsing, event storage, inbox polling, stdout pumping, and shutdown control under `packages/cli/src/commands/channel/`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-beta.11
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.11
2026-05-13
## Bug Fixes
### Task archive auto-commit
`task.py archive` now stages only archive-related task paths.
* `safe_archive_paths_to_add()` scopes staging to the archived task source path, archive destination path, and child task dirs whose `task.json` was edited during parent cleanup.
* `_auto_commit_archive()` stages source-side deletes with `git rm -r --cached --ignore-unmatch` after moving a tracked task dir to `.trellis/tasks/archive/<YYYY-MM>/`.
### Template manifest ownership
`trellis init`, `trellis update`, and `trellis uninstall` no longer treat user-owned platform runtime files as Trellis templates.
* `initializeHashes()` tracks platform/root files from `startRecordingWrites()` output instead of walking `.codex/`, `.claude/`, and other platform dirs.
* `pruneOrphanManifestKeys()` removes stale orphan entries from `.trellis/.template-hashes.json` before `update` and `uninstall`.
* `trellis init` and `trellis uninstall` refuse to run in `$HOME` unless `TRELLIS_ALLOW_HOMEDIR=1`.
### Windows hook encoding
Hook templates force UTF-8 on Windows for stdin, stdout, and stderr.
* `hooks.json` runs Codex `inject-workflow-state.py` with `python -X utf8`.
* `shared-hooks/inject-workflow-state.py`, `shared-hooks/session-start.py`, `codex/hooks/session-start.py`, and `copilot/hooks/session-start.py` reconfigure streams to UTF-8 with replacement errors.
## Internal
### Manifest continuity
The beta branch includes the stable patch manifests needed by `trellis update`.
* `packages/cli/src/migrations/manifests/0.5.14.json`
* `packages/cli/src/migrations/manifests/0.5.15.json`
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-beta.12
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.12
2026-05-13
## Enhancements
### Channel thread boards
`trellis channel` now supports durable thread channels for issue-style feedback boards.
* `trellis channel create --type thread`
* `trellis channel post <name> opened|comment|status|labels|assignees|summary|processed`
* `trellis channel threads <name>`
* `trellis channel thread <name> <thread>`
* `trellis channel messages <name> --thread <key> --action <action>`
### Channel scope
Channel commands can now target project or global storage explicitly.
* `--scope project`
* `--scope global`
* Applies to `create`, `send`, `wait`, `spawn`, `messages`, `list`, `kill`, `rm`, and `prune`.
### Linked context
Channel and thread events can carry stable context for future agents.
* `--description <text>`
* `--linked-context-file <absolute-path>`
* `--linked-context-raw <text>`
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-beta.13
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.13
2026-05-14
## Enhancements
### trellis-core SDK
`@mindfoldhq/trellis-core` now publishes the channel and task primitives used by the CLI.
* Package: `@mindfoldhq/trellis-core`
* Exports: `@mindfoldhq/trellis-core/channel`, `@mindfoldhq/trellis-core/task`, `@mindfoldhq/trellis-core/testing`
* CLI dependency: `@mindfoldhq/trellis-core`
### Channel thread commands
Thread channels now use the `threads` structural type and expose context, title, and rename commands.
* `trellis channel create --type threads`
* `trellis channel context add|delete|list`
* `trellis channel title set|clear`
* `trellis channel thread rename`
### Channel context flags
Context input now uses `context` naming while the beta.12 linked-context aliases remain accepted.
* `--context-file <absolute-path>`
* `--context-raw <text>`
* Legacy aliases: `--linked-context-file`, `--linked-context-raw`
## Internal
### Core package publishing
The publish workflow now publishes `@mindfoldhq/trellis-core` before `@mindfoldhq/trellis` with one shared version and npm dist-tag.
* Workflow: `.github/workflows/publish.yml`
* Preflight: `packages/cli/scripts/release-preflight.js`
* Version bump: `packages/cli/scripts/bump-versions.js`
* Release runner: `packages/cli/scripts/release.js`
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
Replace beta.12 scripts that use `trellis channel create --type thread` with `trellis channel create --type threads`.
# v0.6.0-beta.14
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.14
2026-05-14
## Bug Fixes
### Codex channel streamed deltas
Codex channel progress events now include stream metadata for `item/agentMessage/delta`.
* Parser: `packages/cli/src/commands/channel/adapters/codex.ts`
* Fields: `detail.kind`, `detail.stream_id`, `detail.phase`, `detail.text_delta`
* Kinds: `output`, `commentary`, `reasoning`
Consumers should group streamed deltas by `detail.stream_id` and keep `kind:"message"` as the canonical completed assistant answer.
## Internal
### npm publish verification
The publish workflow now verifies both packages on the public npm registry after CI publish.
* Workflow: `.github/workflows/publish.yml`
* Preflight: `packages/cli/scripts/release-preflight.js verify-npm --package all`
* Packages: `@mindfoldhq/trellis`, `@mindfoldhq/trellis-core`
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No file migration is required.
# v0.6.0-beta.15
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.15
2026-05-14
## Enhancements
### Core mem API
`tl mem` retrieval logic is now available from `@mindfoldhq/trellis-core/mem`.
* Package: `@mindfoldhq/trellis-core/mem`
* APIs: `listMemSessions`, `searchMemSessions`, `readMemContext`, `extractMemDialogue`, `listMemProjects`
* Adapters: `packages/core/src/mem/adapters/claude.ts`, `packages/core/src/mem/adapters/codex.ts`, `packages/core/src/mem/adapters/opencode.ts`
* CLI wrapper: `packages/cli/src/commands/mem.ts`
### Forum channel commands
Forum channels now expose thread-style discussion commands and context entries.
* Create: `trellis channel create <name> --type forum`
* Threads: `trellis channel post`, `trellis channel forum`, `trellis channel thread`
* Context: `trellis channel context add`, `trellis channel context delete`, `trellis channel context list`
* Reducers: `reduceThreads`, `reduceChannelMetadata`
### Channel worker runtime APIs
Channel worker lifecycle and subscription primitives are now exported from `@mindfoldhq/trellis-core/channel`.
* Workers: `listWorkers`, `watchWorkers`, `probeWorkerRuntime`, `reconcileWorkerLiveness`
* Runtime: `spawnWorker`, `requestInterrupt`, `interruptWorker`
* Streams: `readChannelEvents({ afterSeq, beforeSeq, limit })`, `watchChannels`
* CLI flags: `trellis channel spawn --inbox-policy`, `trellis channel send --delivery-mode`
## Bug Fixes
### Codex channel turns
Codex channel workers now record completed answers before `done` and serialize non-interrupt turns.
* Parser: `packages/cli/src/commands/channel/adapters/codex.ts`
* Supervisor: `packages/cli/src/commands/channel/supervisor/inbox.ts`
* Events: `turn_started`, `turn_finished`, `interrupt_requested`, `interrupted`
* Behavior: normal messages wait for the active turn; `--tag interrupt` aborts the active turn and starts the new one.
### Worker registry projection
Worker state now separates turn completion from worker termination.
* Reducer: `packages/core/src/channel/internal/store/worker-state.ts`
* Turn-level events: `done`, `error`
* Terminal events: `killed`, synthesized exit events, supervisor errors
* Watch fallback: `packages/core/src/channel/internal/store/watch.ts`, `packages/cli/src/commands/channel/store/watch.ts`
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No file migration is required.
# v0.6.0-beta.16
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.16
2026-05-15
## Enhancements
### Parent / child task trees
Workflow guidance now documents when to use parent tasks and independently verifiable child tasks.
* Workflow: `.trellis/workflow.md`
* Step detail: `get_context.py --mode phase --step 1.1`
* Breadcrumbs: `[workflow-state:planning]`, `[workflow-state:planning-inline]`
* Skills: `trellis-brainstorm`, `trellis-meta`
## Bug Fixes
### Trellis check agents
Check agents now review task artifacts before checking code against specs.
* Required artifact: `prd.md`
* Optional artifacts: `design.md`, `implement.md`
* Platforms: Claude Code, Cursor, OpenCode, Gemini, Kiro, Qoder, CodeBuddy, Droid, Pi
* Pi agents: `trellis-implement.md`, `trellis-check.md`
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No file migration is required.
# v0.6.0-beta.17
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.17
2026-05-15
## Enhancements
### Workflow templates
Workflow templates can now be selected during `trellis init` or switched later with `trellis workflow`.
* Init flags: `--workflow`, `--workflow-source`
* Command: `trellis workflow`
* Built-in templates: `native`, `tdd`, `channel-driven-subagent-dispatch`
* Marketplace resolver: `workflow-resolver.ts`
* Active file: `.trellis/workflow.md`
### Channel worker coordination
Channel workers now expose timeout warning controls and multi-kind wait filters.
* Wait filter: `trellis channel wait --kind done,killed`
* Warning event: `supervisor_warning`
* Spawn flag: `trellis channel spawn --warn-before <duration>`
* Disable warning: `--warn-before 0ms`
* Default warning lead time: `5m`
### Worker inbox core API
`@mindfoldhq/trellis-core/channel` now exports durable worker inbox read and watch APIs.
* Read API: `readWorkerInbox()`
* Watch API: `watchWorkerInbox()`
* Error class: `WorkerInboxError`
* Routing SOT: `matchesInboxPolicy()`
* Generation boundary: same-id respawns do not replay old worker messages
## Bug Fixes
### Cursor sessionStart hook
Cursor `sessionStart` output now matches Cursor's top-level context schema.
* Output field: `additional_context`
* Shared format retained: `hookSpecificOutput.additionalContext`
* Removed unsupported Cursor hook: `beforeSubmitPrompt`
* Removed copied Cursor file: `.cursor/hooks/inject-workflow-state.py`
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No file migration is required.
# v0.6.0-beta.18
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.18
2026-05-17
## Enhancements
### Channel worker OOM guard
`trellis channel spawn` now has default safeguards for resident worker processes.
* Idle cleanup: `channel.worker_guard.idle_timeout`, default `5m`
* Live-worker budget: `channel.worker_guard.max_live_workers`, default `6`
* Spawn flags: `--idle-timeout <duration>`, `--max-live-workers <n>`
* Env overrides: `TRELLIS_CHANNEL_WORKER_IDLE_TIMEOUT`, `TRELLIS_CHANNEL_MAX_LIVE_WORKERS`
* Idle terminal event: `killed` with `reason: "idle-timeout"`
* Core projection: `WorkerState.idleSince`
Mid-turn workers are not killed by idle cleanup. Explicit `--timeout` remains opt-in.
### Channel message routing
Channel worker routing no longer uses message tags in send, wait, run, and provider adapter internals.
* Removed send tag plumbing from `send.ts`
* Removed wait tag filtering from `wait.ts`
* Kept routing on channel events, worker inbox policy, and explicit `to`
* Added interrupt-specific adapter encoding in `interrupt.ts` and supervisor inbox flow
### Trellis spec bootstrap skill
The Trellis beta bundle now includes `trellis-spec-bootstarp`, a platform-neutral skill for bootstrapping `.trellis/spec/` from the real codebase.
* Replaces the older `cc-codex-spec-bootstrap` marketplace entry
* Works after `trellis init` when the default spec templates still need project-specific content
* Installed automatically with Trellis; no extra marketplace download is needed
* Documented in both beta and release docs so the workflow stays visible when the release bundle is updated
## Bug Fixes
### Task archive auto-commit
`task.py archive` now fails when its auto-commit fails instead of reporting a successful archive with dirty task files.
* Template file: `scripts/common/task_store.py`
* Covered path: archive move followed by failed `git commit`
* User-visible behavior: archive failure exits non-zero and leaves the problem visible
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
`trellis update` appends `channel.worker_guard` defaults to existing `.trellis/config.yaml` files. No migration command is required.
# v0.6.0-beta.19
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.19
2026-05-19
## Enhancements
### Pi trellis\_subagent extension
The Pi extension now exposes Trellis sub-agent dispatch through `trellis_subagent` with native progress cards.
* Tool name: `trellis_subagent`, avoiding collisions with community `subagent` packages
* Dispatch modes: `single`, `parallel`, and `chain`
* Live UI: native progress card updates through `renderResult`, throttled by `THROTTLE_MS`
* Detail view: `Alt+O` expands and collapses the latest sub-agent card
* Safety: `isTrellisAgent()` rejects non-Trellis agent names before spawning child Pi processes
* Resource control: bounded stdout/stderr buffers prevent unbounded child-output growth
## Bug Fixes
### Channel durable idempotency
`@mindfoldhq/trellis-core` channel writes now support durable idempotency keys on `sendMessage` and `postThread`.
* New option: `idempotencyKey`
* Replay behavior: repeated writes with the same key return the original JSONL event
* Strict delivery: replays do not duplicate `undeliverable` events
* Validation: empty keys are rejected, and reusing a key across event kinds raises an error
### Archived task create collisions
`task.py create` now rejects a slug that already exists in `.trellis/tasks/archive/**`.
* Checks archived task directories before creating a new active task directory
* Prints the archived path that caused the collision
* Tells the user to choose a new slug for an intentional new task
### Workflow-state tool routing
`[workflow-state:in_progress]` now distinguishes sub-agent types from skills.
* `trellis-implement` and `trellis-research` are sub-agent types only
* `trellis-update-spec` is a skill
* `trellis-check` exists as both; verification after code changes should prefer the Agent form
* Prevents agents from trying to call missing `trellis-implement` / `trellis-research` skills
### Codex multi\_agent\_v2 timeout bounds
`.codex/config.toml` now emits the `multi_agent_v2` wait timeout values as a valid bounds set for Codex CLI 0.131+.
**Codex requirement:** this full timeout-bounds config requires Codex CLI `0.131.0` or newer. Codex CLI `0.128.0` through `0.130.x` only understands the earlier `enabled`, `max_concurrent_threads_per_session`, and `min_wait_timeout_ms` fields; those versions fail config loading when `default_wait_timeout_ms` or `max_wait_timeout_ms` is present.
```toml theme={null}
[features.multi_agent_v2]
enabled = true
max_concurrent_threads_per_session = 6
min_wait_timeout_ms = 480000
default_wait_timeout_ms = 480000
max_wait_timeout_ms = 3600000
```
* Fixes Codex startup failure: `default_wait_timeout_ms must be at least min_wait_timeout_ms`
* Requires Codex CLI `0.131.0+` for `default_wait_timeout_ms` and `max_wait_timeout_ms`
* Keeps the Trellis default wait at 8 minutes
* Keeps the explicit upper clamp at 1 hour
* Covers fresh `trellis init` and template refresh through `trellis update`
## Internal
### Release manifest continuity
The source tree now includes the already-shipped `0.5.17` migration manifest.
* Restores `packages/cli/src/migrations/manifests/0.5.17.json`
* Keeps `check-manifest-continuity.js` green for the beta release
* Preserves adjacent-version `trellis update` chain validation
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No migration command is required.
# v0.6.0-beta.2
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.2
2026-05-08
## Bug Fixes
* **`tl mem list / search --since X` now respects cross-day session activity.** Previously a session whose first event fell before the window was dropped from results even if it stayed active inside it. A 29 MB Claude session that started 5/7 and was still being written 5/8 returned 0 matches under `--since 2026-05-08` despite containing 19 occurrences of the searched keyword written that day. Root cause: `claudeListSessions` and `codexListSessions` filtered by `created` only (single-point `inRange`). New helper `inRangeOverlap(start, end, f)` keeps a session iff its `[created, updated]` interval overlaps `[f.since, f.until]`. Three list sites switched over; the early `tsFromName` short-circuit in codex was a misoptimization that re-introduced the cross-day bug and is removed. 23 new tests cover all five interval relations × three platforms.
## Internal
* Spec drift cleanup (`.trellis/spec/*`): `script-conventions.md` drops removed `task_context.py init-context`; `workflow-state-contract.md` writer-table line numbers refreshed against current code; `directory-structure.md` configurators / utils / commands trees aligned. `docs-site/advanced/architecture.mdx` corrected the false `.trellis/.current-task` fallback claim (EN + ZH). User-facing artifact unchanged.
## Other Platforms
Claude Code, Cursor, OpenCode, Kiro, CodeBuddy, Droid, Gemini, Qoder, Copilot, Codex — unchanged.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
## Known Trade-Off
Removing the codex filename-ts short-circuit means every codex session now does `readJsonlFirst`. Acceptable; a future patch may add a safe one-sided `--until`-only fast prune that does not reintroduce the cross-day bug.
# v0.6.0-beta.20
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.20
2026-05-19
## Bug Fixes
### Trellis spec bootstrap skill
`trellis-spec-bootstarp` is now included in the CLI package templates.
* Template source: `packages/cli/src/templates/common/bundled-skills/trellis-spec-bootstarp/`
* Packed path: `dist/templates/common/bundled-skills/trellis-spec-bootstarp/`
* Install path: platform skill roots such as `.claude/skills/`, `.agents/skills/`, `.pi/skills/`
* Update tracking: `.trellis/.template-hashes.json` includes the bundled skill reference files
Fresh `trellis init` and `trellis update` now install the built-in spec bootstrap skill without a separate marketplace download.
### Codex multi\_agent\_v2 version note
The v0.6.0-beta.19 changelog now states the Codex CLI version requirement for the full timeout-bounds config.
* Required Codex CLI version: `0.131.0+`
* Affected fields: `default_wait_timeout_ms`, `max_wait_timeout_ms`
* Older Codex CLI versions `0.128.0` through `0.130.x` only support the earlier `enabled`, `max_concurrent_threads_per_session`, and `min_wait_timeout_ms` fields
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No migration command is required.
# v0.6.0-beta.21
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.21
2026-05-21
## Bug Fixes
### Codex config.toml multi\_agent\_v2 block removed
`trellis init` / `trellis update` no longer write a `[features.multi_agent_v2]` block to the generated `.codex/config.toml`.
* Template source: `packages/cli/src/templates/codex/config.toml`
* Removed fields: `enabled`, `max_concurrent_threads_per_session`, `min_wait_timeout_ms`, `default_wait_timeout_ms`, `max_wait_timeout_ms`
Codex CLI changed `features` deserialization between `0.130` and `0.131`. The structured table form is only accepted by `0.131+`. On `0.130` and earlier — including the Codex CLI bundled in the Codex desktop app — it fails with `data did not match any variant of untagged enum FeatureToml in features.multi_agent_v2` and aborts the entire config load, blocking Codex from starting. Codex's own default for `multi_agent_v2` is used instead; tune it in your user-level `~/.codex/config.toml` if needed.
Run `trellis update` to regenerate `.codex/config.toml` without the block.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No migration command is required.
# v0.6.0-beta.22
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.22
2026-06-01
## Bug Fixes
### Codex sub-agent toml: duplicated pull-based prelude removed
The generated `.codex/agents/trellis-check.toml` and `trellis-implement.toml` contained the "Required: Load Trellis Context First" prelude **twice**.
* Template source: `packages/cli/src/templates/codex/agents/trellis-check.toml`, `trellis-implement.toml`
* Generated output: `.codex/agents/trellis-check.toml`, `trellis-implement.toml`
Class-2 platforms (Codex / Copilot / Gemini / Qoder) cannot inject sub-agent task context via hook, so the context-loading prelude is added by the configurator (`injectPullBasedPreludeToml`). The two Codex toml source templates still carried an inline copy of that prelude that predated the injector. The injector then prepended a second copy, so each generated agent shipped the block twice. The markdown class-2 templates (gemini / cursor / etc.) were already prelude-free and unaffected.
The inline copies are removed so the injector is the single source. A regression test now asserts the prelude appears exactly once across all class-2 platforms.
Run `trellis update` to regenerate `.codex/agents/` without the duplication.
### Restore 0.5.19 migration manifest on the beta branch
`src/migrations/manifests/0.5.19.json` was missing on the `0.6.0-beta` branch.
* Restored from `main`, byte-identical to the manifest shipped with the published `0.5.19` release.
The published `0.5.19` npm release had no local manifest on this branch, which broke the manifest-continuity guard and would break `trellis update` for users on `0.5.19`. Restoring it keeps the upgrade chain intact.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No migration command is required.
# v0.6.0-beta.23
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.23
2026-06-08
## Enhancements
### Channel runtime agent definitions auto-dispatched
`trellis init` and `trellis update` now ship `.trellis/agents/{check,implement}.md`, the bundled definitions that `trellis channel spawn --agent <name>` loads at runtime.
* Templates: `packages/cli/src/templates/trellis/agents/{implement,check}.md`
* Dispatched by: `createWorkflowStructure` in `packages/cli/src/configurators/workflow.ts`
* Refreshed by: `getAllAgents()` in `packages/cli/src/templates/trellis/index.ts`, threaded through `collectTemplateFiles` in `packages/cli/src/commands/update.ts`
Previously, switching to a channel-driven workflow (`trellis workflow --template channel-driven-subagent-dispatch`) and then running `trellis channel spawn --agent check` failed at runtime with `Agent 'check' not found` because no command shipped these files. They are platform-agnostic and are dispatched on every init regardless of `--workflow` or `--<platform>` selection. The standard hash/conflict flow in `trellis update` backfills missing entries for projects that installed before the bundled definitions existed (#323).
### Registry-backed `.trellis/spec` refresh through `trellis update`
`trellis init --template <id>` now persists the spec source and template id into `.trellis/config.yaml` under a new `registry.spec` block. `trellis update` reads that block, downloads the configured spec registry into a temp directory, and feeds it through the existing hash / conflict / "modified by you" flow so registry-backed spec templates stay current alongside the standard CLI templates.
* New utility: `packages/cli/src/utils/registry-config.ts`
* `init.ts` and `update.ts` extended to write / read the persisted registry config
* Supports direct spec registries and marketplace-style registries, including SSH and self-hosted Git sources
Closes #315.
### Reasonix (DeepSeek-Reasonix) platform support
Adds Reasonix as the 15th supported AI coding tool, available via `trellis init --reasonix`. Reasonix stores skills as `.reasonix/skills/<name>/SKILL.md` with YAML frontmatter; slash commands are platform-built-in, so no separate `commands/` directory is generated.
* New configurator: `packages/cli/src/configurators/reasonix.ts`
* New template module: `packages/cli/src/templates/reasonix/`
* New CLI flag: `--reasonix`
* `{{CMD_REF:start}}` resolves to `/skill trellis-start` for Reasonix via the new `/skill trellis-` `cmdRefPrefix`
Subagent skills (`trellis-implement`, `trellis-check`) ship with `runAs: subagent` frontmatter so Reasonix spawns them as isolated subagent loops rather than inline slash skills. Closes #301.
### `trellis-session-insight` bundled skill
A new bundled skill at `packages/cli/src/templates/common/bundled-skills/trellis-session-insight/` teaches the AI when to reach for the `trellis mem` CLI (past-solution recall, decision retrieval, cross-session continuation, familiar-bug debugging, self-pattern spotting, finish-work retrospective) and intentionally does **not** prescribe a fixed write-back file.
What to do with what `mem` returns — quote inline in the answer, update a `prd.md` / `design.md`, append to task notes, internalize, or hand off to `trellis-update-spec` — is judged in the moment by the AI. References:
* `references/cli-quick-reference.md` — full `trellis mem` flag reference.
* `references/triggering-patterns.md` — verbatim English and Chinese user phrasings calibrated for each intent.
Auto-dispatched on every supported platform on `trellis init` and `trellis update` via the existing `getBundledSkillTemplates()` directory scan.
### Workflow template missing-agent warning
`trellis workflow --template <id>` (and `trellis init --workflow <id>`) now prints a non-blocking stderr warning when the resolved `workflow.md` references `.trellis/agents/<name>.md` files that are missing on disk. Detection lives in `packages/cli/src/utils/agent-refs.ts` and looks for both `--agent <name>` flag forms and literal `.trellis/agents/<name>.md` path references in the workflow body. The warning points the user at `trellis update` to backfill the bundled set and never aborts the workflow switch.
## Bug Fixes
### Bundled skill rename: `trellis-spec-bootstarp` → `trellis-spec-bootstrap`
The bundled spec-bootstrap skill shipped under a typoed directory name. The fix renames both the source template and the per-platform installed directories.
* Renamed source: `packages/cli/src/templates/common/bundled-skills/trellis-spec-bootstarp/` → `trellis-spec-bootstrap/`
* Inner `name:` frontmatter field corrected.
* Test references updated.
For users who already installed the typoed directory, this release ships a `rename-dir` migration in the 0.6.0-beta.23 manifest that renames the installed directory across 13 platform skill roots:
| Platform | Skill root |
| --------------------------- | -------------------- |
| Claude Code | `.claude/skills/` |
| Cursor | `.cursor/skills/` |
| OpenCode | `.opencode/skills/` |
| Codex + Gemini CLI (shared) | `.agents/skills/` |
| Kiro | `.kiro/skills/` |
| Qoder | `.qoder/skills/` |
| CodeBuddy | `.codebuddy/skills/` |
| GitHub Copilot | `.github/skills/` |
| Droid | `.factory/skills/` |
| Pi Agent | `.pi/skills/` |
| Antigravity | `.agent/skills/` |
| Windsurf | `.windsurf/skills/` |
| Kilo | `.kilocode/skills/` |
Run `trellis update --migrate` to apply. Missing roots are silently skipped.
Historical migration manifests `src/migrations/manifests/0.5.17.json` and `src/migrations/manifests/0.6.0-beta.18.json` keep the typoed text intentionally — they describe what actually shipped to users on those versions and stay grep-able for anyone investigating an old install. Closes #296.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update --migrate
```
`--migrate` is recommended for this release because of the `rename-dir` migrations above. Plain `trellis update` still installs the new `.trellis/agents/*.md` runtime files and the `trellis-session-insight` bundled skill, but leaves the existing `trellis-spec-bootstarp/` directories in place.
# v0.6.0-beta.3
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.3
2026-05-09
## Enhancements
* **`tl mem extract <id> --phase brainstorm`** — slice out the discussion portion of a session (between `task.py create` and `task.py start`). Multi-task sessions are separated with `--- task: <slug> ---`. `--phase implement` is the inverse; `--phase all` is the default full dump.
```bash theme={null}
tl mem extract <id> --phase brainstorm
tl mem extract <id> --phase brainstorm --json
tl mem extract <id> --phase implement
```
Supported on Claude and Codex. OpenCode falls back to full dialogue.
* **`tl mem` is 5-9× faster.**
| command | before | after |
| -------------------------------- | ------ | ----- |
| `mem list` | 3.5s | 0.67s |
| `mem list --platform codex` | 3.2s | 0.33s |
| `mem extract --phase brainstorm` | 5.8s | 0.73s |
## Bug Fixes
* **OpenCode 1.2+ users no longer see 0 sessions from `tl mem`.** OpenCode 1.2 moved session storage to SQLite; the old reader was looking at a now-empty JSON directory, so anyone on a recent OpenCode couldn't use `tl mem` at all. Fixed. OpenCode 1.1.x is no longer supported.
* **`--phase` parser handles `$(... --slug NAME)` substitution, multiple `task.py` invocations per Bash command, and `task.py start` quoted literally inside commit-message heredocs.**
## Other Platforms
Claude Code, Cursor, Kiro, CodeBuddy, Droid, Gemini, Qoder, Copilot — unchanged.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
## New dependency
Adds `better-sqlite3` for OpenCode. Standard `npm install` handles it via prebuilt binaries. If the native binding fails to load, `tl mem` still works on other platforms; OpenCode reads return empty with a one-time stderr hint.
# v0.6.0-beta.4
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.4
2026-05-09
## Bug Fixes
* **`better-sqlite3` dependency removed.** Reverts the OpenCode SQLite reader added in 0.6.0-beta.3. Fixes `npm install -g @mindfoldhq/trellis@beta` failure when the prebuilt binary download fails and no local C toolchain is available.
* **OpenCode platform degraded.** `tl mem list / search / extract` on platform `opencode` returns empty + a one-shot stderr warning. Claude and Codex paths unchanged.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-beta.5
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.5
2026-05-09
Brings the four `v0.5.10` stable fixes / features into the 0.6 beta line.
## Bug Fixes
* **`git add -f .trellis/` runaway prevented.** `add_session.py` and `task.py archive` now stage only specific Trellis-owned paths and auto-retry with `git add -f -- <specific-paths>` only on `ignored by` stderr. Warning text explicitly states `Do NOT use \`git add -f .trellis/\``, listing`.trellis/.backup-\*`,`.trellis/worktrees/`,`.trellis/.template-hashes.json`,`.trellis/.runtime/`,`.trellis/.cache/`as the paths to keep ignored. Helper centralized in`templates/trellis/scripts/common/safe\_commit.py\`.
* **Pi platform `<workflow-state>` / `<session-overview>` / subagent dispatch protocol injection.** Pi extension injects breadcrumb + session-overview every `input` / `before_agent_start`, and the `subagent` tool registration carries `promptSnippet` with `Active task: <path>`. Closes [#249](https://github.com/mindfold-ai/Trellis/issues/249).
* **Pi `npm:pi-subagents` project-level isolation.** `.pi/settings.json` overrides global `npm:pi-subagents` package with empty resource lists. `scrubPiSettings` reverses on uninstall. Closes [#246](https://github.com/mindfold-ai/Trellis/pull/246) (thanks @RenaLio).
## Enhancements
* **Session-start version-update hint.** `get_context.py` default mode performs a once-per-session `trellis --version` check and prepends `Trellis update available: <current> -> <latest>, run npm install -g @mindfoldhq/trellis@latest` when the local install lags. Best-effort with 1-second timeout; failures silently skip. Marker under `.trellis/.runtime/`. Closes [#254](https://github.com/mindfold-ai/Trellis/pull/254) (thanks @jdjingdian).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-beta.6
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.6
2026-05-10
Brings the `v0.5.11` stable fix into the 0.6 beta line.
## Bug Fixes
* **`add_session.py` / `task.py archive` no longer force-stage with `git add -f`.** When `.gitignore` excludes `.trellis/`, scripts print a warning and skip auto-commit. Reverts the auto-retry that shipped in 0.6.0-beta.5.
## Enhancements
* **New config: `session_auto_commit: true | false`** in `.trellis/config.yaml` (default `true`). Set `false` to skip auto stage + commit; journal / archive files still write to disk. Existing projects get a commented-out block appended on `trellis update` (via `configSectionsAdded`). Closes [#245](https://github.com/mindfold-ai/Trellis/issues/245).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-beta.7
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.7
2026-05-10
Brings the `v0.5.12` stable fix into the 0.6 beta line.
## Bug Fixes
* **`trellis update` now updates hash-tracked `.trellis/workflow.md` as a whole runtime template.** The updater no longer merges only `[workflow-state:*]` blocks, so phase headings and platform routing markers such as `codex-inline` / `codex-sub-agent` refresh together. This fixes upgraded Codex installs that had new hook scripts but stale `[Codex]` workflow blocks.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-beta.8
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.8
2026-05-10
Adds task-creation consent gates and planning artifacts to the 0.6 beta workflow.
## Enhancements
### Task Triage Consent
No-task turns now classify the request before creating any Trellis task.
| Request type | Behavior |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Simple conversation / small task | Ask only whether this turn should create a Trellis task; if not, skip Trellis for the turn. |
| Complex task | Ask whether Trellis may create a task and enter planning. If declined, clarify scope or suggest a smaller split. |
### Planning Artifacts
`task.py create` now creates a default `prd.md`; complex planning uses `prd.md`,
`design.md`, and `implement.md` before `task.py start`.
| Artifact | Purpose |
| -------------- | --------------------------------------------------------------------------- |
| `prd.md` | Requirements, constraints, acceptance criteria, out-of-scope. |
| `design.md` | Complex task technical design: boundaries, data flow, contracts, tradeoffs. |
| `implement.md` | Complex task execution plan: checklist, validation commands, review gates. |
### Context Loading
Implement/check context order is now consistent across hook-push, pull-prelude, Pi
extension, OpenCode plugin, and inline modes.
```text theme={null}
jsonl entries -> prd.md -> design.md if present -> implement.md if present
```
`implement.jsonl` and `check.jsonl` remain spec/research manifests; they do not
replace `implement.md`.
### Codex Inline Mode
Codex no-task breadcrumbs include `<trellis-bootstrap>` and `<codex-mode>`
context. Inline mode means the main Codex session implements and checks directly;
it does not dispatch implement/check sub-agents.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-beta.9
Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.9
2026-05-12
Adds `trellis upgrade` and carries stable-line context fixes into the 0.6 beta track.
## Enhancements
### Trellis Upgrade
`trellis upgrade` installs the npm channel that matches the current CLI version.
| Command | Behavior |
| ----------------------------- | -------------------------------------------------------------------- |
| `trellis upgrade` | Installs `@mindfoldhq/trellis@latest`, `@beta`, or `@rc` by channel. |
| `trellis upgrade --tag <tag>` | Installs an explicit dist-tag or version. |
| `trellis upgrade --dry-run` | Prints the npm command without installing. |
Update hints now point at `trellis upgrade` instead of raw `npm install -g`
commands.
### Brainstorm Templates
Bundled brainstorm instructions are shorter and match the beta.8 planning
artifact flow.
| Template | Change |
| ----------------------------------------------------------------- | ------------------------------------------ |
| `packages/cli/src/templates/codex/skills/brainstorm/SKILL.md` | Uses the shorter brainstorm routing model. |
| `packages/cli/src/templates/common/skills/brainstorm.md` | Uses the same shared planning contract. |
| `packages/cli/src/templates/copilot/prompts/brainstorm.prompt.md` | Mirrors the shorter prompt text. |
## Bug Fixes
### Upgrade Execution
The upgrade command validates tag/version input, avoids shell interpolation on
POSIX, uses `cmd.exe /d /s /c` on Windows, and prints npm/PATH troubleshooting
when installation fails.
### OpenCode Context Prefix
OpenCode now picks the `TRELLIS_CONTEXT_ID` prefix for the shell dialect that
will parse the command.
| Environment | Prefix format |
| ---------------------------- | ------------------------------- |
| Windows PowerShell | `$env:TRELLIS_CONTEXT_ID = ...` |
| Windows Git Bash/MSYS/Cygwin | `export TRELLIS_CONTEXT_ID=...` |
| Existing `env` prefix | `env TRELLIS_CONTEXT_ID=...` |
### Session Context
Non-Git Trellis roots no longer report fake clean Git state. Session context now
states that the root is not a Git repository and scans bounded child repositories
for unconfigured polyrepo layouts.
### OpenCode Sub-Agent Context
Trellis implement/check/research child sessions skip duplicate workflow-state
injection and resolve the active task from session runtime, an `Active task:`
prompt hint, or a single-session fallback.
```text theme={null}
jsonl entries -> prd.md -> design.md if present -> implement.md if present
```
### Hook Timeouts And Copilot
Hook defaults now allow 30s for SessionStart and 15s for per-prompt workflow
injection across hook-based platforms. Copilot SessionStart output no longer
emits the stale `systemMessage`; it keeps `hookSpecificOutput.additionalContext`.
## Internal
### Manifest Continuity
The beta line restores `0.5.13.json` so future beta manifest checks include the
stable `0.5.13` release.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
# v0.6.0-rc.0
Source: https://docs.trytrellis.app/changelog/v0.6.0-rc.0
2026-06-08
The first release candidate for v0.6.0. The feature surface is now frozen; the v0.6.0 cycle moves from beta into stabilization. Feature requests open on the tracker (`#193`, `#318`, `#320`, `#325`, `#326`, etc.) are deferred to v0.7 or later. Bug-only patches will land as further `0.6.0-rc.*` cuts.
This changelog summarizes what the v0.6 line delivered across 23 beta releases plus the single fix made between `0.6.0-beta.23` and `0.6.0-rc.0`.
## Enhancements
### `trellis mem` — cross-session memory feedstock
A local CLI that indexes Claude Code and Codex conversation logs already on disk and exposes them through `list`, `search`, `context`, `extract`, and `projects` subcommands. `extract --phase brainstorm|implement|all` slices a session at `task.py create` / `task.py start` boundaries so an AI can recover the planning window of any prior task. Reusable retrieval and phase logic live in `@mindfoldhq/trellis-core/mem`; nothing is uploaded.
Shipped progressively from `v0.6.0-beta.15` (core + CLI), with adapters and phase slicing maturing through `beta.18`.
### `trellis-session-insight` bundled skill
A capability skill that teaches the AI when to reach for `trellis mem` (past-solution recall, decision retrieval, cross-session continuation, familiar-bug debugging, self-pattern spotting, finish-work retrospective) and intentionally does *not* prescribe a fixed write-back file. What to do with what `mem` returns is judged in the moment by the AI based on the live conversation.
* Source: `packages/cli/src/templates/common/bundled-skills/trellis-session-insight/`
* Auto-dispatched to every supported platform on `trellis init` and `trellis update`
Shipped in `v0.6.0-beta.23`.
### Channel runtime — multi-agent collaboration
`trellis channel` ships a worker-supervisor primitive for coordinating multiple AI processes:
* `channel create | send | wait | spawn | run | list | messages | kill | rm | prune` subcommands
* Claude stream-json and Codex app-server adapters that translate provider output into channel `message` / `progress` / `done` / `error` events
* Forum and thread channels with `--type forum|threads` and `channel context|title|thread rename`
* `--scope project|global` resolution across every channel command
* Project-scoped channel logs under `~/.trellis/channels/<project>/<channel>/events.jsonl` with locked sequence assignment
* Default OOM guard: `channel.worker_guard.idle_timeout` (5m) and `channel.worker_guard.max_live_workers` (6); both configurable per-spawn or via `.trellis/config.yaml`
* Reusable worker runtime APIs in `@mindfoldhq/trellis-core/channel`: `readWorkerInbox()`, `watchWorkerInbox()`, `WorkerInboxError`
* Durable `idempotencyKey` on `sendMessage` / `postThread` so retries return the original JSONL event
Shipped progressively across `v0.6.0-beta.10` through `beta.19`.
### Channel runtime agent definitions auto-dispatched
`trellis init` and `trellis update` now ship `.trellis/agents/{check,implement}.md`, the bundled definitions that `trellis channel spawn --agent <name>` loads at runtime. `trellis workflow --template <id>` prints a non-blocking stderr warning when the resolved workflow references missing `.trellis/agents/<name>.md` files. Detection lives in `packages/cli/src/utils/agent-refs.ts`.
Shipped in `v0.6.0-beta.23` (closes `#323`).
### Registry-backed `.trellis/spec` refresh through `trellis update`
`trellis init --template <id>` persists the spec source and template id into `.trellis/config.yaml` under a new `registry.spec` block. `trellis update` reads that block, downloads the configured spec registry into a temp directory, and feeds it through the existing hash / conflict / "modified by you" flow. Supports direct spec registries and marketplace-style registries, including SSH and self-hosted Git sources.
Shipped in `v0.6.0-beta.23` (closes `#315`).
### Reasonix (DeepSeek-Reasonix) platform support
Reasonix is the 15th supported AI coding tool, available via `trellis init --reasonix`. Subagent skills (`trellis-implement`, `trellis-check`) carry `runAs: subagent` frontmatter so Reasonix spawns them as isolated subagent loops.
Shipped in `v0.6.0-beta.23` (closes `#301`).
### Pi Agent — native `trellis_subagent` extension
The Pi extension now exposes `trellis_subagent` with native progress cards, `single` / `parallel` / `chain` dispatch modes, throttled live updates, and Trellis-agent validation.
Shipped in `v0.6.0-beta.19` (closes `#286`, `#290`).
### `@mindfoldhq/trellis-core` SDK package
A second published package, `@mindfoldhq/trellis-core`, exposes the reusable channel, task, and mem domain primitives behind the CLI for Node consumers. Both packages share one git tag, one npm dist-tag, and one version at every release.
Shipped in `v0.6.0-beta.13`.
### `trellis upgrade` command
Wraps `npm install -g @mindfoldhq/trellis@<channel>` with channel-aware defaults (`latest`, `beta`, `rc`), explicit `--tag` and `--dry-run` flags. Replaces the long-form `npm install -g …` snippets that previously appeared in session-start hints.
Shipped in `v0.6.0-beta.9`.
### `trellis-spec-bootstrap` bundled skill
A built-in bundled skill that helps an AI bootstrap `.trellis/spec/` from the real codebase with source-backed references for repository analysis, spec task planning, spec writing, and MCP setup. Auto-installed on every supported platform.
Shipped in `v0.6.0-beta.18` (renamed from the historical typo `trellis-spec-bootstarp` in `v0.6.0-beta.23`; see `#296`).
### Configurable hooks via `.trellis/config.yaml`
Project-level configuration now drives hook behavior:
| Knob | Controls |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `session_commit_message` / `max_journal_lines` / `session_auto_commit` | journal auto-commit shape |
| `hooks.after_create` / `after_start` / `after_finish` / `after_archive` | user shell commands run after each task lifecycle event |
| `channel.worker_guard.idle_timeout` / `max_live_workers` | channel worker OOM protection |
| `codex.dispatch_mode: inline \| sub-agent` | whether the main Codex agent edits code directly or routes through `trellis-implement` / `trellis-check` sub-agents |
## Bug Fixes
### `trellis-implement` / `trellis-check` no longer silent-skip when Exa MCP is absent
The bundled `trellis-implement` and `trellis-check` agent definitions declared `mcp__exa__web_search_exa` and `mcp__exa__get_code_context_exa` as explicit tools. Claude Code's `tools:` parser silently skips agent registration when an explicit MCP tool name fails to resolve, so users without the Exa MCP server installed had every Trellis sub-agent disappear from the dispatch list — the main agent ended up implementing work itself rather than delegating.
Fix:
* `trellis-implement` and `trellis-check` drop both `mcp__exa__*` entries. These agents do not need external web search; the tools list shrinks to `Read, Write, Edit, Bash, Glob, Grep`.
* `trellis-research` folds the previous `mcp__exa__*` + `mcp__chrome-devtools__*` entries into a single `mcp__*` wildcard. Claude Code resolves wildcards lazily (no silent-skip when nothing matches), so this opts research into any MCP the user has configured without locking the source template to a specific provider.
* The Copilot transformer (`mapLegacyToolToCopilot` in `packages/cli/src/configurators/shared.ts`) gets a matching case for `mcp__*` that emits the full set of supported Copilot MCP equivalents.
OpenCode agent files use a different permission mapping syntax (`mcp__exa__*: allow`) that does not silent-skip the agent, so they are intentionally left unchanged.
Closes `#302`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@rc
trellis update
```
If you are coming from `0.6.0-beta.22` or earlier, run `trellis update --migrate` to also pick up the `rename-dir` migration that moves installed `trellis-spec-bootstarp/` skill directories to `trellis-spec-bootstrap/` across the 13 platform skill roots.
The next release on this line will be `0.6.0-rc.1` (bug-only) unless a feature regression forces a return to beta. v0.6.0 GA tracks RC stability.
# v0.6.1
Source: https://docs.trytrellis.app/changelog/v0.6.1
2026-06-17
Docs-only refactor. Run `trellis update` to refresh `.trellis/workflow.md`, the bundled `trellis-meta` skill, the three marketplace workflow variants, and (for Copilot users) the `finish-work` prompt. No `--migrate` required; no breaking change.
## Refactor
### `workflow.md` — Phase 3.1 removed
Phase 3.1 `Quality verification` was structurally identical to the last iteration of Phase 2.2 `Quality check` — both load the `trellis-check` skill and run spec compliance + lint / type-check / tests + cross-layer consistency. Removed as redundant.
Its two unique value points are folded into existing steps:
* **Full-scope final check** → Phase 2.2 gains a "Final pass (before Phase 3.4 commit)" paragraph: the last 2.2 of a task must list all affected packages via `python3 ./.trellis/scripts/get_context.py --mode packages` and walk each package's spec index Quality Check section, not just check the latest implement chunk.
* **Spec-sync trigger** → Phase 3.4 gains a "Spec-sync preamble" at the top: before drafting commits, ask whether non-obvious knowledge surfaced in this task should land in `.trellis/spec/` via Phase 3.3 first.
Step numbering kept stable (3.1 is left as a numbered gap; 3.2 / 3.3 / 3.4 / 3.5 unchanged) so external references in docs, tutorials, and spec do not break.
### `workflow.md` — 1.3 `Configure context` label normalized
Phase Index entry for `1.3 Configure context` previously carried `[conditional · once]`, a single-use label that no other step used. The step body itself said `[required · once]`. Normalized both to `[required · once]` with an explicit `sub-agent-dispatch-platforms-only; inline platforms skip` annotation matching the platform list already in the line.
### Marketplace workflow variants synced
The three marketplace workflow variants (`native`, `tdd`, `channel-driven-subagent-dispatch`) received the same Phase 3.1 removal + 1.3 label fix + 2.2 final-pass paragraph + 3.4 spec-sync preamble. Selectable via `trellis init --workflow <variant>` or `trellis workflow`.
### Bundled `trellis-meta` skill — `change-workflow.md`
Status transition example in the resume-at table updated from `Phase 3.1 (verify quality + spec update)` to `Phase 3.3 (spec update) → 3.4 (commit)`, matching the new numbering.
### Copilot prompt — `finish-work.prompt.md`
The Phase 3 ASCII flow at the top of the `/finish-work` prompt updated to remove `3.1 Quality verification` and add a one-line note that `3.1 was folded into 2.2 + 3.4`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` is required. No source code changed; this is a template refresh.
Users on any `0.6.x` install run `trellis update` to pick up the workflow refresh. Users on `0.5.x` should first follow the [v0.6.0](/changelog/v0.6.0) upgrade path (`trellis update --migrate`), then run `trellis update` again to land on 0.6.1.
# v0.6.10
Source: https://docs.trytrellis.app/changelog/v0.6.10
2026-07-28
Patch release restoring Python 3.9–3.11 task script compatibility, complete Codex sub-agent context recovery for truncated hook output, and correct fallback-session cleanup.
## Bug Fixes
### Python task script compatibility
Generated `.trellis/scripts/common/task_context.py` no longer uses multiline nested f-strings. All `task.py` commands parse on the documented Python 3.9+ floor, with warning text unchanged (#476).
### Codex truncated hook context
The `trellis-implement`, `trellis-check`, and `trellis-research` templates now detect `Full hook output saved to: <path>` and read the saved `SubagentStart` payload before treating `<!-- trellis-hook-injected -->` as complete. If the saved output cannot be read, they fall back to the active task's role JSONL and task docs (#465).
### Fallback session cleanup
`clear_active_task()` now deletes the session file named by the resolved `previous.context_key`, not the current process key. `task.py finish` clears a uniquely resolved `session-fallback` task and leaves ambiguous or unresolved session state untouched (#469).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
# v0.6.11
Source: https://docs.trytrellis.app/changelog/v0.6.11
2026-07-30
Patch release improving Pi and Codex sub-agent reliability, UTF-8 hook input, bounded polyrepo scans, and platform detection.
## Bug Fixes
### Pi sub-agent model and thinking
`trellis_subagent` now uses the invoking Pi session model when neither the call nor agent frontmatter selects a model. Explicit overrides keep their existing precedence, and the `thinking` option now accepts and preserves `max` (#494, #499).
### Codex channel failures and idle timeout
The Codex channel adapter now emits a channel error when a turn fails without a final answer, surfaces non-retryable app-server errors, and deduplicates paired failure notifications. The supervisor idle timer continues after `done` or `error`, so completed workers that remain idle are terminated normally (#495, #496).
### UTF-8 hook input
Standalone Python hooks now decode host-provided JSON from `stdin` as UTF-8 independently of the process locale. This covers sub-agent context injection, shell session context, and the optional Claude statusline on GBK and other non-UTF-8 hosts (#498).
### Bounded polyrepo Git scans
Automatic child-repository discovery stops after eight repositories and directs larger workspaces to explicit `packages` configuration. Best-effort Git status probes now use a two-second timeout without changing normal Git commands (#497).
### Trellis-owned platform detection
`getConfiguredPlatforms()` now detects installations from Trellis-owned template hashes intersected with each platform collector and private config directory. Shared `.agents/skills` files no longer create false positives during `trellis init` (#501).
## Internal
### Python 3.9 CI gate
CI now compiles every tracked `.py` file with Python 3.9, runs `basedpyright`, and triggers when Python files change. This enforces the documented minimum Python version before release (#502).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
# v0.6.12
Source: https://docs.trytrellis.app/changelog/v0.6.12
2026-08-01
Patch release isolating concurrent Pi sessions.
## Bug Fixes
### Pi session identity
The `.pi/extensions/trellis/index.ts` extension now derives each main window's Trellis context from Pi's native session ID. `contextKey()` ignores ambient `TRELLIS_CONTEXT_ID`, and `getKey()` no longer adopts an unrelated singleton runtime pointer. Session IDs changed by normalization include a raw-ID hash so distinct IDs cannot collapse onto the same context key (#512, #513).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
# v0.6.13
Source: https://docs.trytrellis.app/changelog/v0.6.13
2026-08-06
Patch release extending the shell-ticket session bridge to six platforms and deduplicating the `CLAUDE_ENV_FILE` append.
## Bug Fixes
### Shell-ticket session bridge on six platforms
`inject-shell-session-context.py` now ships to Gemini CLI, Qoder, CodeBuddy, Droid, Trae and ZCode. On those platforms `task.py start` resolved no session identity and left `.trellis/.runtime/sessions/` unwritten.
| Platform | Hook event | Registered in |
| ---------- | ------------ | -------------------------- |
| Gemini CLI | `BeforeTool` | `.gemini/settings.json` |
| Qoder | `PreToolUse` | `.qoder/settings.json` |
| CodeBuddy | `PreToolUse` | `.codebuddy/settings.json` |
| Droid | `PreToolUse` | `.factory/settings.json` |
| Trae | `PreToolUse` | `.trae/hooks.json` |
| ZCode | `PreToolUse` | `.zcode/config.json` |
Tickets are written to `.trellis/.runtime/shell-tickets/`; the pre-0.6.13 `.trellis/.runtime/cursor-shell/` is still read, never written. Distribution is declared in `SHARED_HOOKS_BY_PLATFORM`. Kiro is not wired: neither of its hook surfaces publishes a pre-tool trigger.
### CLAUDE\_ENV\_FILE append dedupe
`_persist_context_key_for_bash` in `session-start.py` appends `export TRELLIS_CONTEXT_ID=<key>` to `$CLAUDE_ENV_FILE` only when the last existing export assigns a different value. It previously appended on every SessionStart, growing a user-owned file the shell sources for every command. Lines already accumulated are not removed — delete them by hand.
### Update reminder in SessionStart
SessionStart carries `Trellis update available: <current> -> <latest>, run trellis update` inside its `<first-reply-notice>` block, which the assistant relays in its first visible reply. `get_update_hint()` was reachable only through `get_context.py --mode text`, so hook-driven platforms never showed it. The once-per-session marker `.trellis/.runtime/update-check-<key>.marker` now keys on the context key resolved from hook stdin instead of falling back to `TERM_SESSION_ID`.
### ZCode session identity
`.trellis/scripts/common/active_task.py` resolves ZCode session identity from `CLAUDE_CODE_SESSION_ID`, then `CLAUDE_SESSION_ID`. The lookup is platform-scoped, so it fires only after the resolver detects `zcode`.
### Windows Python command rendering
`.snow/SNOW.md`, `.github/copilot-instructions.md` and `.reasonix/skills/<name>/SKILL.md` now go through the `python3` → resolved-Python-command rewrite (`python` on Windows). Every platform file is written through `writeTemplateMap`, which renders each entry with `replacePythonCommandLiterals`. The rewrite is a no-op when the resolved command is `python3`, so output on macOS and Linux is unchanged.
### trellis-meta bundled-skills reference
`trellis-meta`'s `references/local-architecture/bundled-skills.md` — shipped into every platform skill root, e.g. `.claude/skills/trellis-meta/` — documents the current path: one `collect<Platform>Templates()` per platform, written by `writeTemplateMap`. Its platform table lists all 21 skill roots (was 15) and no longer names `writeSkills()` or `configureCursor()`, neither of which exists.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
# v0.6.14
Source: https://docs.trytrellis.app/changelog/v0.6.14
2026-08-06
Fixes task tracking on CodeBuddy, ZCode and Trae. `trellis mem` now returns conversations that were cut short.
## Bug Fixes
### Tasks did not stick on CodeBuddy, ZCode and Trae
On these three, `task.py start` reported success but every later turn still said there was no active task. Trellis read the session under the wrong name, because all three identify themselves with a Claude-compatible variable that Trellis checked first.
On CodeBuddy the hooks also failed to find the project at all: the IDE reports `/` as the working directory, and Trellis took it at face value.
Both are fixed. Run `trellis update` to get the new hooks, then restart your IDE.
### PreToolUse tool names
The IDE and CLI versions of these products name their tools differently, so the hooks were registered for names the IDE never sends.
| Platform | Now matches |
| --------- | ------------------------------------------------------- |
| CodeBuddy | `execute_command`, `Bash`, `PowerShell`, `task`, `Task` |
| Trae | `RunCommand`, `Bash` |
| Qoder | `Bash`, `run_in_terminal` |
## Enhancements
### `trellis mem` returns compacted conversations
When a session was compacted, `trellis mem` used to return only what survived the compaction — often two or three turns out of hundreds. The rest was still in the session file.
It now returns those turns, and marks where each compaction happened. A twice-compacted Codex session that returned 2 turns returns 18; a Claude session went from 100 to 1536. Tool calls, reasoning and system prompts are still stripped as before.
Some content genuinely cannot be recovered, and now says so rather than appearing complete: Codex encrypts messages between agents, and Grok stores pre-compaction turns as rendered markdown under `<session>/compaction/`.
Search results shift slightly. A session that only matched inside a compaction summary no longer matches; sessions whose actual conversation covers the topic now do.
### `trellis mem` reads Grok sessions
```bash theme={null}
trellis mem search "topic" --platform grok
trellis mem extract <session-id>
```
Reads `~/.grok/sessions/`. Project scoping works as it does for other platforms.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
# v0.6.15
Source: https://docs.trytrellis.app/changelog/v0.6.15
2026-08-14
Adds DeepSeek Harness as the 22nd supported platform.
## New Platform
### DeepSeek Harness
```bash theme={null}
trellis init --dsh
```
Writes the shared workflow and bundled skills to `.agents/skills/`, and the
user-invocable entry skills (`trellis-start`, `trellis-continue`,
`trellis-finish-work`) to `.dsh/skills/`, which is dsh's own highest-rank
project skill root. An operator guide lands at `.dsh/DSH.md`.
dsh discovers both skill roots natively and loads skills by name through its
skill-loader tool, so nothing needs to be registered by hand. The default web
and headless profiles ship no session-start hook, so `trellis-start` stays a
skill you invoke rather than something that fires automatically.
dsh exposes no project-level sub-agent surface, so the research, implement and
check phases run inline in the main session instead of being dispatched to
sub-agents. The platform count for sub-agent dispatch stays at 18.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
# v0.6.16
Source: https://docs.trytrellis.app/changelog/v0.6.16
2026-08-27
Task lifecycle commands, a context-manifest gate for sub-agent dispatch, reversible ablation, the OpenCode mem reader restored, and a batch of hook/channel fixes.
## Enhancements
### Context manifest gate
`task.py validate` now fails a seeded `implement.jsonl` / `check.jsonl` with zero curated entries, and `task.py start` refuses to start such a task unless `--allow-empty-context` is passed. The sub-agent injection hook also states in the prompt when no curated context was injected, instead of a stderr-only warning. Absent manifests (platforms without sub-agents) are not gated. (#573)
### Task lifecycle commands
* `task.py rename <task> <new-slug> [--dry-run]` renames the directory and rewrites `task.json` identity, parent/child references, and jsonl manifests together.
* `task.py start` records branch metadata; `task.py archive` validates it.
* Developer identity resolution works in linked git worktrees.
* `task.py create` seeds `implement.jsonl` / `check.jsonl` empty instead of with placeholder rows. (#578)
### Reversible ablation
`trellis ablate` removes every Trellis-managed file from a project and stores the removed state under an external root; `trellis restore` puts it back. Pre-flight conflict checks, project locking, and rollback on failure. (#538)
### Resumable session recorder
`add_session.py` is now a state machine: each step is idempotent, writes are atomic, and a failed run resumes instead of leaving a half-committed session record. (#577)
### OpenCode session reader restored
`trellis mem` reads OpenCode 1.2+ SQLite session storage again — zero-dependency parser, no native module, WAL-aware. (#574)
### OMP prompt-injection skip keyword
`prompt_injection.skip_keyword` in `.trellis/config.yaml` now works on OMP: a prompt containing the keyword skips workflow-state injection for that turn. (#586)
### ZCode bridge hint
`init` / `update` on ZCode print an install hint for the optional trellis-bridge plugin, for 3.6–3.7 builds that disable project-level hooks.
## Bug Fixes
* `add_session.py` and `task.py archive` auto-commits use explicit pathspecs and no longer sweep pre-staged unrelated files into the chore commit (#579).
* Path containment accepts a `.trellis` that is a symlink into an external store (#567).
* Task script runtime hardening: git `index.lock` retry, JSON read diagnostics, safer subprocess cleanup (#576).
* `trellis update` repairs receipt entries for files already byte-identical to their template (#575).
* The Pi extension resolves the Trellis project root from the session cwd (#581).
* The sub-agent context hook contains jsonl-referenced file reads to the task base path (#584) and surfaces unreadable active-task records (#544).
* Channel: UTF-8 preserved across incremental event reads (#569), `seq` continues after a torn `events.jsonl` tail (#564), stdout drained before supervisor exit (#542), Claude system prompt passed as a file to avoid argv limits (#555).
* OMP: task context injection is byte-budgeted with `[truncated]` / `[omitted]` markers, refreshes after file changes (#541), and deduplicates shared files (#540).
* OpenCode: context injected via `messages.transform` so TUI and history stay clean (#563).
* `workflow.md` routing blocks are no longer dropped for four platforms whose marker labels did not match their platform ids.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
# v0.6.17
Source: https://docs.trytrellis.app/changelog/v0.6.17
2026-09-12
Devin CLI session memory, on-demand SQLite page reads, and task/session binding fixes.
## Enhancements
### Devin CLI session adapter
`trellis mem` reads Cognition Devin CLI sessions from `~/.local/share/devin/cli/sessions.db` (WAL SQLite) through the existing zero-dependency parser. This is not `trellis init --devin` (Desktop/Cascade) and not Factory Droid. (#614)
* `--platform devin` on `list` / `search` / `extract` / `context` / `projects`
* OpenCode, ZCode, and Devin share `packages/core/src/mem/internal/sqlite-adapter.ts` and `packages/core/src/mem/platforms.ts`
* Devin forests require `main_chain_id`; a missing tip is `devin-main-chain-missing` (no `max(node_id)` fallback)
* `CREATE TABLE` `--` line comments are stripped so `parent_node_id` and `chat_message` parse on live `sessions.db` files
## Bug Fixes
### Lazy SQLite main-page reads
The zero-dependency SQLite reader in `packages/core/src/mem/internal/sqlite-readonly.ts` loads main-file pages on demand instead of reading the whole database into memory. (#596)
### Pi headless subagent prompts
Pi `trellis_subagent` forwards ask-policy prompts to the parent session. The serving heartbeat sets `PI_SUBAGENT_PARENT_SESSION` (not a stale `PI_SESSION_ID`), sets `PI_SUBAGENT_CHILD=1`, and drops inherited `PI_SESSION_ID` so the child mints its own. (#611)
### Active-task session fallback
Resolving an active task from a missing session id no longer falls back to the only session in the project. That fallback is explicit opt-in, so one session cannot bind another session's task. (#608)
### Archive child unlink restore
If `task.py archive` fails after unlinking some children, it restores each child's `parent` link from a snapshot taken before the clear. A duplicated `children` entry is snapshotted once so a second visit cannot restore `parent: null`. (#613)
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
# v0.6.2
Source: https://docs.trytrellis.app/changelog/v0.6.2
2026-06-17
Docs-only fix following up on the v0.6.1 workflow simplification. Run `trellis update` to refresh the `/continue` command. No `--migrate` required.
## Bug Fixes
### `/continue` routing pointed at the deleted Phase 3.1
The `/continue` command's resume-routing table still sent `status=in_progress` + check-passed to the Phase **3.1** that [v0.6.1](/changelog/v0.6.1) removed. It now routes to **3.3** (spec update) → **3.4** (commit), matching the simplified workflow.
The v0.6.1 cleanup updated `workflow.md`, the three marketplace workflow variants, the bundled `trellis-meta` skill, and the Copilot `finish-work` prompt — but missed `commands/continue.md` because its routing uses a bare-number syntax (`→ **3.1**`) that the `Phase 3.1` grep did not match.
## Internal
### Sync matrix hardened against this class of miss
`.trellis/spec/docs-site/docs/sync-on-change.md` Trigger 1 (Phase Structure Changes) now enumerates every in-template file carrying step-routing references (`continue.md`, `trellis-meta` change-workflow reference, Copilot prompt, marketplace variants) and adds a bare-number grep pattern. A future step delete/renumber audits all routing sites, not just `workflow.md`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required. No source code changed; this is a template refresh.
# v0.6.3
Source: https://docs.trytrellis.app/changelog/v0.6.3
2026-06-18
This release bundles five enhancements — ZCode platform support, an opt-in `--with-statusline` status bar, a Pi session adapter for `trellis mem`, reasoning frameworks for the brainstorm/break-loop skills, and the Windsurf → Devin platform rename — plus two fixes (#300, #303). Run `trellis update` to refresh templates. Only the Windsurf → Devin rename needs `trellis update --migrate`, and only if you previously initialized with `--windsurf`.
## Enhancements
### ZCode platform support (`--zcode`)
Added ZCode (智谱 / Z.ai) as a pull-based, agent-capable platform (no hooks). `trellis init --zcode` writes three output paths:
| Target | Path | Contents |
| ------------- | -------------------------- | ------------------------------------------------------------ |
| Shared skills | `.agents/skills/` | byte-identical with Codex/Gemini |
| Commands | `.zcode/commands/trellis/` | invoked as `/trellis:<name>` |
| Sub-agents | `.zcode/cli/agents/` | `trellis-implement`, `trellis-check` with pull-based prelude |
Registry entry `AI_TOOLS.zcode`: `configDir: ".zcode"`, `cliFlag: "zcode"`, `extraManagedPaths: [".zcode/cli/agents", ".zcode/commands"]`, `agentCapable: true`, `hasHooks: false`, `executorAI: "Bash scripts or Agent calls"`. Configurator `configureZcode` / `collectZcodeTemplates` in `src/configurators/zcode.ts`; templates under `src/templates/zcode/`.
### trellis init --with-statusline (Claude Code statusLine)
`trellis init --with-statusline` installs an opt-in Trellis status bar for Claude Code (off by default). When the flag is omitted and Claude Code is selected, `init` prompts interactively (`default: false`; skipped under `-y`).
Writes two artifacts, Claude Code only:
| Artifact | Content |
| -------------------------------------- | ------------------------------------------------------------------------------------ |
| `.claude/hooks/statusline.py` | Status hook: model · ctx% · branch · duration · developer · task count · rate limits |
| `.claude/settings.json` → `statusLine` | `{ "type": "command", "command": "{{PYTHON_CMD}} .claude/hooks/statusline.py" }` |
The hook is not part of `collectTemplates` or shared-hooks, so `trellis update` never force-installs it on opted-out projects nor removes it from opted-in ones. The flag-off path leaves `settings.json` byte-identical.
### Pi session mem adapter
`trellis mem` now reads persisted Pi Agent sessions. New adapter `packages/core/src/mem/adapters/pi.ts` exports `piListSessions`, `piExtractDialogue`, `piSearch`, `collectPiTurnsAndEvents`. `MemSourceKind` in `mem/types.ts` adds `"pi"`; `--platform claude|codex|opencode|pi|all` is now accepted.
Session discovery:
* Default store `~/.pi/agent/sessions/--<encoded-cwd>--/<timestamp>_<id>.jsonl`, via `piProjectDirFromCwd` / `piSessionRoots`.
* Custom dirs from `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`, or `settings.json` `sessionDir`.
Extraction follows the active branch (`id`/`parentId` leaf walk) and applies Pi compaction rules via `firstKeptEntryId`. Pi joins Claude/Codex with native phase-boundary detection in `sliceMemPhase`; `bash`/`shell` tool calls feed `task.py` events.
### Devin platform (renamed from Windsurf)
Cognition renamed Windsurf to Devin Desktop (2026-06-02 OTA) and moved its config dir from `.windsurf/` to `.devin/` (identical subpaths: `workflows/`, `skills/`). Trellis follows the rename.
* `trellis init --devin` writes `.devin/workflows/` + `.devin/skills/`; the platform shows as **Devin** and `--platform devin` is passed to scripts (#325).
* `--windsurf` remains a **deprecated alias** for `--devin` for one version. Passing it prints a deprecation notice and behaves like `--devin`.
* `TRELLIS_PLATFORM=windsurf` and a leftover `.windsurf/workflows/` directory are still detected as Devin for back-compat.
### Thinking frameworks in brainstorm + break-loop skills
Two reasoning frameworks are embedded in the shared workflow skills (`packages/cli/src/templates/common/skills/`), so every platform picks them up on `trellis update`:
| Skill | Framework | When it applies |
| ------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `brainstorm` | First Principles Analysis | requirement discovery — decompose to fundamental truths, challenge assumptions, build up the minimum viable solution |
| `break-loop` | Bayesian Reasoning | repeated debugging — set hypothesis priors, update beliefs by evidence strength, seek discriminating evidence before committing a fix |
Hardcoded "5 skills" comments across the configurators, `shared.ts`, and `update.ts` are replaced with count-free wording (#335).
## Bug Fixes
### trellis mem --cwd Claude session filter on Windows
`trellis mem` returned 0 Claude sessions when filtering by `--cwd` on Windows. `claudeProjectDirFromCwd` (`packages/core/src/mem/internal/paths.ts`) only replaced `/` and `_` with `-`, so Windows cwds with backslashes, drive colons, and dots derived a project-dir name that did not exist under `~/.claude/projects/`. The sanitization regex now covers all separators: `/[/\\:_.]/g`. In `claudeListSessions` (`packages/core/src/mem/adapters/claude.ts`), the `--cwd` fast path now falls back to scanning every project dir when the derived dir is missing; the per-session `sameProject(cwd, f.cwd)` check still scopes results, so the filter never silently returns 0. Fixes #300.
### .trellis auto-commit staging scope
Scoped `.trellis/` auto-commit staging so it no longer sweeps unrelated task/workspace files into commits (#303). Previously a wide `tasks_dir.iterdir()` scan staged every active task dir, bundling dirty parallel-window task dirs into the session commit.
* `safe_commit.py`: `safe_trellis_paths_to_add()` gained a `task_name` param. When passed, it stages only `.trellis/tasks/<task_name>/` (and its archive location) — no `iterdir()` over all tasks. Omitting `task_name` keeps the legacy wide scan for backward compat.
* `add_session.py`: `_auto_commit_workspace()` resolves the current task via `get_current_task()` and passes `task_name`. When unresolvable (0 or >=2 parallel sessions), it stages only journal/index and skips every task dir under `tasks/`.
* `release.js`: the pre-release `git add -A` now also excludes `':!.trellis'` (alongside `':!docs-site'`, `':!marketplace'`).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
Only the Windsurf → Devin rename needs `--migrate`:
<Note>
If you initialized Trellis with `--windsurf`, run `trellis update --migrate` to apply the `rename-dir` migrations that move:
* `.windsurf/workflows/` → `.devin/workflows/`
* `.windsurf/skills/` → `.devin/skills/`
The migration is idempotent: projects without a `.windsurf/` directory are silently skipped. `--windsurf` still works as a deprecated alias for `--devin` this release.
</Note>
# v0.6.4
Source: https://docs.trytrellis.app/changelog/v0.6.4
2026-06-22
Patch release with two independent bug fixes: Kiro's main session now activates the workflow deterministically, and four `agentCapable && !hasHooks` platforms (Codex, ZCode, OpenCode, Reasonix) finally emit `trellis-start`. Run `trellis update` to refresh. No `--migrate` required.
## Bug Fixes
### `trellis-start` missing on `agentCapable && !hasHooks` platforms
`filterCommands(ctx)` in `packages/cli/src/configurators/shared.ts` stripped `start` whenever `ctx.agentCapable` was true. The premise — that an agent-capable platform always has a SessionStart-style hook to inject opening context — does not hold for **Codex, ZCode, OpenCode, Reasonix**, which lack such a hook. Result: users had no way to load workflow context (no `/trellis:start` slash command, no `trellis-start` skill).
The fix narrows the condition to `agentCapable && hasHooks`. The standard `resolveAllAsSkillsNeutral` / `resolveCommands` paths now emit `trellis-start` naturally on all four platforms.
Codex's one-off `resolveCodexTrellisStartSkill` helper (introduced in 0.5.5 as a manual patch) is deleted along with its two call sites in `configurators/codex.ts` and `configurators/index.ts`. Codex output is byte-identical with the helper-written version (same template `common/commands/start.md`, same resolver, same wrapper), so `trellis update` will not flag user-modified.
Triggered by external user report: `trellis init --zcode` produced neither `/trellis:start` nor `trellis-start`.
### `workflow.md` platform-matrix missing ZCode and Reasonix
13 edit points in `packages/cli/src/templates/trellis/workflow.md`:
* **B1 / B3 / B5 / B7 / B12** (Active Task Routing, Phase 1.2 Research, Phase 1.3 Configure context, Phase 1.5 Completion criteria, Phase 2.2 Quality check) — `ZCode, Reasonix` added to the sub-agent dispatch platform lists.
* **B9** (Phase 2.1 implement, class-2 pull-based) — `[codex-sub-agent]` → `[codex-sub-agent, ZCode, Reasonix]`. Both platforms need the `Active task:` prefix the codex-sub-agent block already mandates.
* **Line 186** — prose enumeration in the Phase Index section gains `, ZCode, Reasonix`.
* **B8 unchanged** — its body claims "platform hook/plugin auto-handles", which is false for pull-based platforms. ZCode and Reasonix are deliberately excluded.
### Kiro main-session workflow injection
Pre-0.6.4 Kiro projects had no deterministic Trellis activation. The three sub-agent JSONs registered `agentSpawn` hooks, but the main session had no hook of its own, so the workflow never kicked in.
The "Kiro supports only `agentSpawn`" assumption that drove the original wiring was wrong. Kiro CLI exposes `userPromptSubmit` and `agentSpawn`; the IDE has file-based `.kiro.hook` (`promptSubmit`). 0.6.4 wires both:
* **`.kiro/agents/trellis.json`** (new main agent): `userPromptSubmit` → `inject-workflow-state.py`, `agentSpawn` → `session-start.py`, `workflow.md` declared as an always-loaded resource.
* **`.kiro/hooks/trellis-workflow-state.kiro.hook`** (new IDE hook): `promptSubmit` → `runCommand`.
* **`inject-workflow-state.py` + `session-start.py`** add an isolated `platform == "kiro"` branch that prints plain stdout (Kiro adds it to context; no `hookSpecificOutput` envelope). Detected via `KIRO_PROJECT_DIR` env or `.kiro` script path. Other platforms byte-unchanged (isolation test added).
* **`SHARED_HOOKS_BY_PLATFORM.kiro`** gains `session-start.py` + `inject-workflow-state.py`.
The three sub-agents (`trellis-{implement,check,research}.json`) keep their `agentSpawn → inject-subagent-context.py` wiring unchanged.
The plain-stdout-to-context contract and the IDE `runCommand` stdout injection follow Kiro's official docs; real-machine verification is pending. Fallback for users hitting issues: `askAgent` + static steering.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
* **Kiro** users: `update` writes the new main-session agent (`.kiro/agents/trellis.json`), the IDE hook (`.kiro/hooks/trellis-workflow-state.kiro.hook`), and the shared hook scripts.
* **ZCode / OpenCode / Reasonix** users: `update` writes the previously missing `trellis-start` skill / `/trellis:start` slash command.
* **Codex** users: no observable change. The trellis-start skill is now produced via the standard path instead of the helper, but the file bytes are identical.
# v0.6.5
Source: https://docs.trytrellis.app/changelog/v0.6.5
2026-06-25
Patch release with Trae IDE support, reliable Pi Agent startup context, Pi sub-agent tool configuration fixes, and runtime reliability improvements for Windows channel sessions, hooks, and task planning gates. Run `trellis update` to refresh existing projects. No `--migrate` required.
## Highlights
### Trae IDE platform support
Trellis now supports Trae IDE as a first-class platform.
`trellis init --trae` writes:
* `.trae/commands/trellis-*.md` slash commands with frontmatter
* `.trae/skills/` workflow skills and bundled skills
* `.trae/agents/` Trellis implement/check/research agents
* `.trae/hooks/` shared Python hooks
* `.trae/hooks.json` for `SessionStart` and `UserPromptSubmit`
Trae uses shared hooks for main-session startup and per-turn workflow context. Sub-agent context uses the class-2 pull-based prelude because Trae does not expose a Trellis-supported sub-agent prompt mutation surface.
The bundled workflow now keeps class-2 implement dispatch (codex-sub-agent, Gemini, Qoder, Copilot, ZCode, Reasonix, Trae) in the pull-based block, not the hook auto-handles block. This keeps workflow guidance aligned with generated pull-based sub-agent context loading.
### Pi Agent startup context
Pi Agent's `session_start` event is notify-only, so it cannot inject model-visible context by itself. 0.6.5 moves the startup payload to the first `before_agent_start` event for each Trellis context key.
New Pi sessions now receive compact Trellis startup context in `systemPrompt`: workflow state, session overview, active-task status, the compact workflow index, and the first-reply notice. `.pi/prompts/trellis-start.md` remains as a manual fallback.
### Pi sub-agent tools
Generated `.pi/agents/trellis-*.md` files can declare `tools` frontmatter for `trellis_subagent`. Tool names are normalized to lowercase, and the unused `PI_TOOL_ALLOWLIST` path is removed so Pi receives the tool names it expects.
## Reliability Fixes
### Windows channel sessions
Channel session spawning now resolves Windows npm `.cmd` shims to a spawnable executable path before launch. This fixes failures where the supervisor tried to spawn a non-existent `.exe` path.
### Hooks and planning gates
Shared Python hooks no longer block when stdin is empty.
ZCode command fallbacks now stay under `.zcode/commands/trellis/` instead of the shared `.agents/skills/` directory. This prevents Codex + ZCode combined installs from reporting immediate template drift on `trellis update --dry-run`.
Trellis also tightens task readiness:
* `workflow.md` requires curated `implement.jsonl` / `check.jsonl` context before starting implementation.
* `brainstorm` requires lossless PRD convergence before planning continues, so updated requirements are not dropped during iterative task shaping.
## Internal
CI now runs on marketplace submodule pointer changes, and the marketplace workflow mirror has been synced for Trae support.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
* **Trae** users: run `trellis init --trae` in projects that do not yet have `.trae/`; run `trellis update` in existing Trellis projects.
* **Pi** users: run `trellis update` to receive the generated start prompt and extension startup-context updates.
* **Windows channel** users: install the latest CLI before starting new channel sessions.
# v0.6.6
Source: https://docs.trytrellis.app/changelog/v0.6.6
2026-07-09
Patch release with Oh My Pi platform support, cache-stable Pi runtime context, corrected ZCode paths, safer channel sessions, and task CLI cleanup. Run `trellis update` to refresh existing projects. New installs do not need `--migrate`; ZCode users on 0.6.3-0.6.5 should run `trellis update --migrate` once if `.zcode/cli/agents/` exists.
## Enhancements
### Oh My Pi platform support
Trellis now supports Oh My Pi as a first-class platform.
`trellis init --omp` writes:
* `.omp/agents/` for `trellis-implement`, `trellis-check`, and `trellis-research`
* `.omp/commands/` for Trellis workflow commands
* `.omp/skills/` for Trellis workflow and bundled skills
* `.omp/extensions/trellis/` for runtime context injection
OMP is registered in the generated `cli_adapter.py` and `task_store.py`, so OMP projects receive Trellis workflow routing and task JSONL context where sub-agents need it.
## Bug Fixes
### Pi runtime context
Pi extension output now keeps `systemPrompt` byte-stable across turns. Startup and task context are memoized, while mutable workflow, session, and task updates are delivered through persistent hidden messages. This preserves provider prefix-cache eligibility while still keeping Trellis context current.
### Oh My Pi runtime context
The OMP extension now injects session-start, task, and sub-agent context through the platform runtime instead of relying on stale session identity fallbacks. Generated OMP command files also include YAML frontmatter, and implement/research agents use the `pi/task` model hint.
### ZCode layout
ZCode-managed Trellis skills now live under `.zcode/skills/`, and ZCode sub-agents live under `.zcode/agents/`. The generated ZCode agent set now includes `trellis-research`, and `.zcode` is treated as sub-agent-capable when Trellis decides whether to seed `implement.jsonl` / `check.jsonl`.
### Channel sessions
Channel workers on Windows now resolve npm `.cmd` and node-script shims before spawning Codex workers. Channel stdout event writes are serialized so concurrent output cannot corrupt event records.
### Task creation
`task.py create` now rejects or normalizes explicit `--slug` values that already include an `MM-DD-` prefix, warns on blank descriptions, makes automatic session activation visible, and adds `--no-start` for backlog creation without moving the current session pointer.
### Codex inline mode
Codex inline mode no longer receives seed-only `implement.jsonl` / `check.jsonl` files just because `.codex/` exists. Trellis only seeds those files for Codex when `codex.dispatch_mode: sub-agent` is explicitly configured.
### Session and hook templates
Session journals now use explicit fallback text instead of placeholders. Copilot instructions preserve repo-authored content while Trellis manages only its own guidance block, and shared hooks keep fail-open behavior without catching `BaseException`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
* **Oh My Pi** users: run `trellis init --omp` in projects that do not yet have `.omp/`; existing OMP dogfood projects should run `trellis update`.
* **ZCode** users on 0.6.3-0.6.5: run `trellis update --migrate` once if `.zcode/cli/agents/` exists. This moves legacy sub-agents to `.zcode/agents/`.
* **Pi** users: run `trellis update` to receive the cache-stable extension runtime.
* **Codex inline** users: run `trellis update` so new tasks stop receiving seed-only JSONL context files.
# v0.6.7
Source: https://docs.trytrellis.app/changelog/v0.6.7
2026-07-13
Patch release with project-local Pi memory discovery and filesystem-safety fixes for channel, update, uninstall, task archive, state writes, and template downloads. Run `trellis update` to refresh existing projects. No `--migrate` required.
## Enhancements
### Pi memory session discovery
`trellis mem` now reads Pi session storage from both global `~/.pi/agent/settings.json` and project-local `.pi/settings.json`. Relative `sessionDir` values resolve from the directory containing the settings file, matching Pi's settings behavior.
## Bug Fixes
### Channel path validation
`trellis channel` now rejects channel and worker names that are unsafe filesystem path segments. Cross-channel discovery skips legacy directories whose names do not pass the same validation instead of aborting the scan.
### State and template writes
Generated files, `.trellis/.template-hashes.json`, registry config, `task.json`, and session pointers now use atomic replace operations. `downloadWithStrategy(..., "overwrite")` downloads into a temporary directory before replacing existing templates, and temporary-directory cleanup errors no longer mask the download result.
### Destructive command guards
Trellis now protects user-owned data across destructive operations:
* `trellis uninstall` removes only the managed block from `AGENTS.md` and refuses unattended `--yes` removal when `.trellis/spec/`, `.trellis/tasks/`, or `.trellis/workspace/` contains uncommitted files.
* `task.py archive` accepts only real task directories under `.trellis/tasks/`.
* `trellis update` keeps an existing `journal-N.md` during the legacy `traces-N.md` rename and only applies `rename-dir` automatically to directories tracked as Trellis-owned.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required. Pi users with project-local session storage can run `trellis mem` from that project after upgrading.
# v0.6.8
Source: https://docs.trytrellis.app/changelog/v0.6.8
2026-07-22
Patch release adding two platforms (Grok Build, Kimi Code), Codex native subagent dispatch, machine-readable platform/task state, and the Pi shared-skills migration. Pi users should run `trellis update --migrate`; everyone else `trellis update`.
## Enhancements
### Grok Build platform
`trellis init --grok` configures Grok Build (xAI CLI) as a class-2 pull-based platform: `.grok/skills/`, flat `.grok/commands/trellis-*.md`, and `.grok/agents/`. Hook context injection is not enabled — Grok does not consume hook stdout.
### Kimi Code platform
`trellis init --kimi` configures Kimi Code as a class-2 pull-based platform: `.kimi-code/skills/`, shared `.agents/skills/`, prompts under `.kimi-code/prompts/`, and dispatch via the built-in `coder` / `explore` sub-agents.
### Codex native subagent dispatch
Codex now dispatches `trellis-implement` / `trellis-check` / `trellis-research` as native subagents with `SubagentStart` context injection and child-side pull fallback. `agents.max_depth=1` is pinned in the project `config.toml` to prevent recursion.
### ZCode hooks and mem sessions
ZCode gains deterministic hook context injection and `trellis mem` session discovery (#411).
### Machine-readable state
* `trellis platforms --json` lists configured platforms with `id`, `displayName`, `configDir` (#396).
* `task.py list --json` / `task.py current --json` emit structured task state (#395).
### Channel and task options
* `trellis channel spawn --sandbox <read-only|workspace-write|danger-full-access>` overrides the Codex worker sandbox mode (#413).
* `task.py create` stamps `base_branch` from the repo default and accepts `--base-branch` (#399).
## Bug Fixes
### Pi shared skills root
Pi now writes skills to the shared `.agents/skills/` root instead of a private `.pi/skills/` copy, fixing duplicate skill installs alongside Codex/Gemini (#447). The 0.6.8 migration moves existing `.pi/skills/` content; `trellis update` rename-dir merges no longer clobber the canonical target with stale source bytes.
### Update and template fixes
* Reintroduced templates are preserved on update (#425).
* Registry template downloads drop `preferOffline`, avoiding stale cache hits (#383).
* YAML frontmatter descriptions are quoted to survive embedded colons (#437).
### Hook and workflow fixes
* Oh My Pi bridges session context into the bash env (#424).
* SessionStart acknowledgment language adapts to the session (#439).
* Brainstorm requires explicit planning approval before task creation (#416).
* 0.6.7 fleet review batch: task boundary, atomic write, activation diagnostics, OpenCode `start.md` (#438).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update # most projects
trellis update --migrate # Pi projects: moves .pi/skills/ → .agents/skills/
```
# v0.6.9
Source: https://docs.trytrellis.app/changelog/v0.6.9
2026-07-24
Patch release adding the Snow CLI platform, sub-agent context injection caps across all three loaders, a per-turn injection skip keyword, durable Codex sub-agent model config, channel trusted context dirs for symlinked workspaces, and journal merge conflict relief.
## Enhancements
### Snow CLI platform
`trellis init --snow` configures Snow CLI as a class-1 platform: auto context inject via `.snow/hooks/`, project agent discovery under `.snow/agents/`, `beforeSubAgentStart` prompt enrichment, and multi-session isolation via Snow session identity env (#443).
### Sub-agent context injection caps
Sub-agent context injection now caps per-file (32 KiB), per-artifact (64 KiB), and total (128 KiB) payload size across the shared Python hook, the Pi extension, and the OpenCode plugin. Oversized files truncate with a notice; once the total cap is reached, remaining files degrade to index lines instead of being inlined. Configurable via `context_injection` in `.trellis/config.yaml` (`0` disables a limit). Binary referenced files (detected via NUL bytes and strict UTF-8 validation) are never inlined — they emit a reference-only notice regardless of the configured limits (#441, #456, #471).
### `no-trellis` skip keyword
A prompt containing the configurable skip keyword (default `no-trellis`, word-boundary match) mutes the per-turn workflow-state injection for that turn. Configurable via `prompt_injection.skip_keyword` in `.trellis/config.yaml`; empty string disables the escape hatch (#427).
### Durable Codex sub-agent model config
User-set `model` / `model_reasoning_effort` in `.codex/agents/trellis-*.toml` now survive `trellis update` regeneration instead of being overwritten. Templates ship commented hints (`gpt-5.6-terra` / `high`) so the knob is discoverable. `dispatch_mode` stays `auto` by default — sub-agents inherit the main session's model unless pinned in the agent toml (#459).
### Channel trusted context dirs
`channel.trusted_context_dirs` in `.trellis/config.yaml` allowlists external directories for context loading, plus narrow auto-trust when `.trellis/tasks` or `.trellis/workspace` themselves are symlinks — for projects that persist Trellis data outside a periodically-replaced project directory (#414).
### Script and task quality-of-life
* `add_session.py` gains repeatable `--change` / `--test` / `--next-step` flags; sections with no content are omitted instead of rendering placeholder text (#394).
* `task.py list` renders a task with a dangling parent reference flat instead of hiding it (#402).
* `task.py create --meta key=value` (repeatable) and a new `task.py set-meta` subcommand expose the `task.json` `meta` field.
## Bug Fixes
### Kimi research persistence
`trellis-research` on Kimi Code now dispatches through the writable built-in `coder` sub-agent, so research findings persist under the task's `research/` directory instead of being lost (#457).
### Journal merge conflicts
`.gitattributes` ships `journal-*.md merge=union`, so parallel-worktree or concurrent `trellis archive` runs no longer conflict on append-only journal content. `index.md` conflicts are expected when parallel sessions ran — picking either side is safe since task state lives in `task.json`, not `index.md`. `add_session.py` warns once when run inside a linked worktree with `session_auto_commit` enabled (#415).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```
No `--migrate` required.
# v0.7.0-beta.0
Source: https://docs.trytrellis.app/changelog/v0.7.0-beta.0
2026-07-28
The first 0.7 beta adds path-scoped spec delivery and runtime workflow
selection.
## Enhancements
### Dynamic spec loading
Specs can declare repo-relative `paths` globs in YAML frontmatter. Trellis
matches those globs when an agent touches a file and delivers only the
governing spec content.
* Claude Code receives matching specs through `PostToolUse` on
`Read|Edit|Write|MultiEdit`.
* Codex receives matching specs through `PreToolUse` on native `apply_patch`.
A patch that first receives a full spec is denied once and succeeds after
the model reads the rules and retries.
* Full bodies, silent in-window hits, refresh tickets, truncation, and
`SessionStart(source=clear|compact)` reset use one shared decision engine.
* `get_context.py --mode spec --file <path>` exposes the same matching in pull
mode.
See [Dynamic Spec Loading](/beta/advanced/dynamic-spec-loading).
### Dynamic workflow switching
Workflow variants now coexist under `.trellis/workflows/` and can be selected
without replacing the global `.trellis/workflow.md`.
* `trellis workflow --save <workflow-id>` populates the project workflow library.
* `task.py create --workflow <workflow-id>` and
`task.py workflow <workflow-id>` pin a variant to
one task.
* Runtime precedence is task pin → personal `.trellis/.developer` override →
team `default_workflow` → global workflow.
* Session-start context, per-turn breadcrumbs, and phase lookup share the same
resolver.
See [Dynamic Workflow Switching](/beta/advanced/dynamic-workflow-switching).
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No file migration is required. Existing specs without `paths` frontmatter and
projects without workflow selection settings retain their previous behavior.
# v0.7.0-beta.1
Source: https://docs.trytrellis.app/changelog/v0.7.0-beta.1
2026-07-29
This beta adds workflow scaffolding, Pi workflow selection, and OpenCode
dynamic spec loading.
## Enhancements
### Workflow scaffolding
`trellis workflow create <workflow-id>` creates a user-managed
`.trellis/workflows/<workflow-id>.md` from the complete native workflow.
Interactive runs can set the new workflow as the project default in
`.trellis/config.yaml` and the personal default in `.trellis/.developer`.
`--skip-defaults` creates only the file. The global `.trellis/workflow.md`
remains unchanged.
### Pi dynamic workflow selection
The Pi extension now resolves the workflow used for per-turn breadcrumbs with
the same precedence as other Trellis consumers:
```text theme={null}
task workflow → personal .developer → team config.yaml → global workflow.md
```
Invalid or missing variants fall through to the next layer.
### OpenCode dynamic spec loading
OpenCode now matches governing specs before `write`, `edit`, and `apply_patch`.
When a full spec is delivered, the plugin blocks the first mutation with a
model-visible tool error; the model reads the rules and retries, while persisted
delivery state makes the retry silent. `session.compacted` resets exposure.
Ticket-only and failure responses remain fail-open.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No file migration is required.
# v0.7.0-beta.2
Source: https://docs.trytrellis.app/changelog/v0.7.0-beta.2
2026-08-06
Sync release. The 0.7 beta line picks up every stable fix shipped in v0.6.11
through v0.6.13. No beta-only features changed.
## Synced from main
| Release | Fixes |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| v0.6.11 | Pi subagent model inheritance and max thinking; Codex channel failure reporting; idle timeout after completed turns; bounded polyrepo Git scan; UTF-8 hook stdin; platform detection from Trellis-owned files |
| v0.6.12 | Pi context isolation by native session ID |
| v0.6.13 | Shell-ticket session bridge on Gemini CLI, Qoder, CodeBuddy, Droid, Trae and ZCode; `CLAUDE_ENV_FILE` append dedupe; SessionStart update reminder; ZCode session identity; Windows Python command rendering; `trellis-meta` bundled-skills reference |
Per-release detail is in the [v0.6.11](/changelog/v0.6.11),
[v0.6.12](/changelog/v0.6.12) and [v0.6.13](/changelog/v0.6.13) changelogs.
Beta-only behavior is unchanged: workflow scaffolding, per-task workflow
selection, path-scoped spec injection and OpenCode dynamic spec loading all
carry over as-is. `SHARED_HOOKS_BY_PLATFORM` now declares both
`inject-spec-context.py` (beta) and `inject-shell-session-context.py` (main);
the shell hook is not wired to OpenCode, whose spec injection is a JS plugin
rather than a Python hook config.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No `--migrate` required.
# v0.7.0-beta.3
Source: https://docs.trytrellis.app/changelog/v0.7.0-beta.3
2026-08-06
Sync release. The 0.7 beta line picks up v0.6.14. No beta-only behavior changed.
## Synced from main
| Release | Changes |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| v0.6.14 | Task tracking fixed on CodeBuddy, ZCode and Trae; PreToolUse matchers updated for IDE tool names; `trellis mem` returns compacted conversations and reads Grok sessions |
See the [v0.6.14](/changelog/v0.6.14) changelog for detail.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No `--migrate` required.
# v0.7.0-beta.4
Source: https://docs.trytrellis.app/changelog/v0.7.0-beta.4
2026-09-12
Sync release. The 0.7 beta line picks up v0.6.15 through v0.6.17. DeepSeek Harness on beta now dispatches native sub-agents.
## Synced from main
| Release | Changes |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| v0.6.15 | DeepSeek Harness (`trellis init --dsh`) as the 22nd platform; phases run inline on stable |
| v0.6.16 | Context-manifest gate; task lifecycle commands; reversible ablation; OpenCode mem reader restored; hook and channel fixes |
| v0.6.17 | Devin CLI session adapter (`--platform devin`); lazy SQLite pages; Pi headless ask forward; active-task session isolation; archive child unlink restore |
See the [v0.6.15](/changelog/v0.6.15), [v0.6.16](/changelog/v0.6.16) and [v0.6.17](/changelog/v0.6.17) changelogs for detail.
## Enhancements
### DeepSeek Harness native sub-agents
On the 0.7 beta line, `trellis init --dsh` installs native research / implement / check sub-agent skills (`trellis-agent-{research,implement,check}`). Stable 0.6.15 still runs those phases inline. (#548)
* Child-only role skills; the main session does not load them
* Uses the companion `dsh-trellis` `trellis_wait` when present; otherwise foreground dispatch. No polling
* Nested-host session identity prefers `DSH_TRELLIS_CONTEXT_ID`, then `DSH_SHELL=1` plus `DSH_SESSION_ID`
## Bug Fixes
### Spec-injection YAML flow lists
`parse_simple_yaml` in `trellis_config.py` now parses scalar flow sequences such as `spec_injection.tools: []` and `tools: [Edit, Write]`. Nested `[]` / `{}` are still rejected.
### `task.py workflow`
`task.py workflow` imports `read_json` from `common.io`, so pinning a per-task workflow no longer raises `NameError`.
## Upgrade
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update
```
No `--migrate` required.
# Contribute to Docs
Source: https://docs.trytrellis.app/contribute/docs
How to contribute to Trellis documentation (mindfold-ai/docs)
## Contribute with AI assistance
The easiest way to contribute is with Claude Code. We have a built-in skill that guides you through the process.
### Fork and clone
```bash theme={null}
# Fork on GitHub first, then:
git clone https://github.com/YOUR_USERNAME/docs.git
cd docs
pnpm install
```
### Tell Claude what you want to contribute
Open Claude Code in the project and describe what you want to add:
* "I want to add a new spec template for Next.js projects"
* "I want to improve the multi-agent documentation"
### Claude uses the contribute skill automatically
Claude will read the `contribute` skill and guide you through:
* Where to put your files
* What related files need updating (docs.json, index pages)
* Bilingual requirements (EN + ZH)
* How to test locally
### Review and submit PR
Review the changes, test with `pnpm dev`, push to your fork, then open a PR to the original repo.
<Tip>
The contribute skill knows the project structure and conventions. It handles the details so you
can focus on content.
</Tip>
***
## Ways to contribute
### Report issues
Found a problem with the docs? Open an issue:
[https://github.com/mindfold-ai/docs/issues](https://github.com/mindfold-ai/docs/issues)
Include:
* Which page has the issue
* What's wrong or confusing
* Suggested fix (if you have one)
### Suggest improvements
Have an idea for better docs? Open a discussion:
[https://github.com/mindfold-ai/docs/discussions](https://github.com/mindfold-ai/docs/discussions)
### Contribute a Skill
Skills extend AI capabilities. To add a new skill:
1. Fork the [Trellis repo](https://github.com/mindfold-ai/Trellis)
2. Create skill directory:
```
marketplace/skills/your-skill/
└── SKILL.md
```
3. Open a PR to the Trellis repo
4. (Optional) Create documentation pages in docs repo (`skills-market/your-skill.mdx` + Chinese version)
See [Claude Code Skills documentation](https://code.claude.com/docs/en/skills) for SKILL.md format.
<Note>Skills are hosted in the [Trellis main repo](https://github.com/mindfold-ai/Trellis), not in docs.</Note>
### Contribute a Spec Template
Spec templates are Trellis project guidelines (not Claude features). To add one:
1. Fork the repo
2. Create `marketplace/specs/your-template/` with guideline files
3. Create documentation pages (`templates/specs-your-template.mdx` + Chinese version)
4. Update `docs.json` navigation
5. Open a PR
Good contributions are:
* Specific and actionable
* Well-documented
* Tested on real projects
### Fix typos and improve clarity
Small fixes: edit directly on GitHub and submit a PR.
Larger changes: clone locally, make changes, test with `pnpm dev`.
***
## Development setup
```bash theme={null}
# Install dependencies
pnpm install
# Start local dev server
pnpm dev
# Check markdown lint
pnpm lint:md
# Verify docs structure
pnpm verify
# Format files
pnpm format
```
***
## Bilingual requirement
All user-facing content must have both English and Chinese versions:
| English | Chinese |
| ----------------------- | -------------------------- |
| `guides/example.mdx` | `zh/guides/example.mdx` |
| `templates/example.mdx` | `zh/templates/example.mdx` |
Update `docs.json` navigation for both languages.
***
## Commit messages
Use conventional commits:
```
docs: add Next.js spec template
fix: correct broken link in quickstart
feat: add new skill to marketplace
```
***
## PR process
1. Create a PR with a clear description
2. Ensure CI checks pass (lint, verify)
3. Wait for review
4. Address feedback
5. Merge after approval
***
## License
Contributions are licensed under MIT. By contributing, you agree to this.
## Questions?
Open a discussion or email [taosu@mindfold.ai](mailto:taosu@mindfold.ai).
# Contribute to Trellis
Source: https://docs.trytrellis.app/contribute/trellis
How to contribute to the Trellis project (mindfold-ai/Trellis)
# Contributing to Trellis
See the contribution guide on GitHub:
<Card title="CONTRIBUTING.md" icon="github" href="https://github.com/mindfold-ai/Trellis/blob/main/CONTRIBUTING.md">
English contribution guidelines
</Card>
# Showcase
Source: https://docs.trytrellis.app/showcase/index
<CardGroup>
<Card title="open-typeless" icon="microphone" href="/use-cases/open-typeless">
macOS voice input app, built in 1 day. Shows the full workflow: spec organization, task breakdown,
parallel development.
</Card>
<Card title="Trellis for Cursor" icon="cursor" href="/showcase/trellis-cursor">
Community fork optimized for Cursor with Chinese subagents and MCP integration.
</Card>
</CardGroup>
***
## Add your project
1. Fork the [docs repo](https://github.com/mindfold-ai/docs)
2. Copy `showcase/template.mdx` and `zh/showcase/template.mdx` to create bilingual pages
3. Add page paths to both EN and ZH showcase pages arrays in `docs.json`
4. Add Card to both `showcase/index.mdx` and `zh/showcase/index.mdx`
5. Open a PR
Use `/contribute` skill in Claude Code for assistance.
# open-typeless
Source: https://docs.trytrellis.app/showcase/open-typeless
# About
A macOS voice input app, built with Trellis in 1 day.
[](https://github.com/mindfold-ai/open-typeless)
## How it was built
Copied specs from an existing Electron project, AI filtered and organized them into 3 task batches. Current Trellis runs this style of work with native Git worktrees plus one session-scoped Trellis task per AI window.
# Workflow Demo
Source: https://docs.trytrellis.app/showcase/terminal-demo
See the full Trellis workflow in action: from brainstorm to ship
<div>
<div>
<div />
<div>
<div>
<div>
<div />
<div />
<div />
</div>
</div>
<div>
<div>
<span>❯ </span>
<span>New AI session</span>
</div>
<div>
<span>● </span>
Loaded: workflow, 3 active tasks, branch <span>feat/v0.5.0-rc</span>
</div>
<div>
<span>● </span>
What would you like to work on?
</div>
<div>
<span>❯ </span>
Add Gemini CLI support, similar to how Cursor is integrated
</div>
<div>
<span>● Bash</span>
<span>(task.py create "Gemini CLI support" --slug gemini-cli)</span>
</div>
<div>
<span>▶ </span>
<span>research</span>
<span>(Find platform integration specs and code patterns)</span>
</div>
<div>
└ Initializing...
</div>
<div>
└ Done <span>(36 tool uses · 86.5k tokens · 2m 25s)</span> <span>✓</span>
</div>
<div>
<span>● Bash</span>
<span>(task.py add-context ... platform-integration.md, cursor.ts, ai-tools.ts)</span>
</div>
<div>
└ 6 spec files added to <span>implement.jsonl</span>
</div>
<div>
<span>● Bash</span>
<span>(task.py start ...)</span>
<span>: hooks will inject context into agents</span>
</div>
<div>
<span>▶ </span>
<span>implement</span>
<span>(Implement Gemini CLI platform)</span>
</div>
<div>
└ Writing src/configurators/gemini.ts...
</div>
<div>
└ Done <span>(99 tool uses · 162.5k tokens · 12m 3s)</span> <span>✓</span>
</div>
<div>
<span>● </span>
TypeCheck <span>✓</span> · Lint <span>✓</span> · Tests: 337/337 <span>✓</span>
</div>
<div>
<span>▶ </span>
<span>check</span>
<span>(Review implementation against code-specs)</span>
</div>
<div>
└ Reading diff... 14 files changed
</div>
<div>
└ Found 1 issue: missing EXCLUDE\_PATTERNS entry
</div>
<div>
└ Fixed automatically <span>✓</span>
</div>
<div>
<span>❯ </span>
<span>Capture Gemini CLI conventions in specs</span>
</div>
<div>
<span>● Read</span>
<span>(.trellis/spec/backend/platform-integration.md)</span>
</div>
<div>
<span>● Update</span>
<span>(platform-integration.md)</span>
<span>: added Gemini CLI conventions</span>
</div>
<div>
<span>❯ </span>
<span>/trellis:finish-work</span>
</div>
<div>
<span>● Bash</span>
<span>(task.py archive gemini-cli)</span>
</div>
<div>
<span>● Bash</span>
<span>(add\_session.py --title "feat: Gemini CLI support" --commit "ec6114a")</span>
</div>
<div>
└ Task archived. Session recorded to <span>journal-4.md</span>.
</div>
<div>
<span>❯ </span>
<span />
</div>
</div>
</div>
<div>
<div />
<div />
<div title="Start" />
<div title="Describe" />
<div title="Research" />
<div title="Implement" />
<div title="Check" />
<div title="Update Spec" />
<div title="Ship" />
</div>
<div>
<div>
<p>Session loaded</p>
<p>AI reads your project context: workflow rules, active tasks, git status, and recent journal entries.</p>
</div>
<div>
<p>Natural language input</p>
<p>Describe your feature in plain language. Trellis creates a tracked task with a structured PRD.</p>
</div>
<div>
<p>Research & configure</p>
<p>trellis-research sub-agent finds relevant specs and code patterns. Context files configured in jsonl: hooks auto-inject them into agents.</p>
</div>
<div>
<p>Implement</p>
<p>Agent writes code across 5 layers following project conventions. 99 tool calls, all 337 tests pass on first try.</p>
</div>
<div>
<p>Quality check</p>
<p>trellis-check sub-agent reviews every changed file against code-specs. Issues found and fixed automatically.</p>
</div>
<div>
<p>Update specs</p>
<p>New patterns captured into the spec library: making future sessions even better.</p>
</div>
<div>
<p>Session archived</p>
<p>5 atomic commits, session recorded to journal. The branch is ready for review.</p>
</div>
</div>
</div>
</div>
***
## What just happened?
This demo replays a real Trellis session where we added **Gemini CLI platform support**: a feature touching types, templates, configurators, CLI flags, Python adapters, and documentation.
### The workflow
<Steps>
<Step title="Start session">
SessionStart hook or extension loads your project context: workflow rules, active tasks, git
status, and recent journal entries. The AI is immediately oriented.
</Step>
<Step title="Describe the feature">
You describe what you want in natural language. Trellis creates a tracked task with a structured
PRD.
</Step>
<Step title="Research & configure">
trellis-research sub-agent reads 36 files to find relevant specs and code patterns. Context
files are configured in jsonl so agents receive the right conventions via hooks.
</Step>
<Step title="Implement">
trellis-implement sub-agent writes code across 5 layers (types → templates → configurator → CLI
→ Python). 99 tool calls. All 337 tests pass on first try.
</Step>
<Step title="Quality check">
trellis-check sub-agent reviews every changed file against code-specs. Finds 1 missing
`EXCLUDE_PATTERNS` entry and fixes it automatically.
</Step>
<Step title="Update specs">
The `trellis-update-spec` skill captures new patterns learned from this session into the spec
library: making future sessions even better.
</Step>
<Step title="Finish & ship">
`/trellis:finish-work` archives the task and records the session to your journal. 5 atomic
commits on the feature branch, ready for review.
</Step>
</Steps>
### Key metrics
| Metric | Value |
| ----------------- | -------------------------------------------------------- |
| **Total time** | \~20 minutes |
| **Tool calls** | 169 (explore + research + implement + check) |
| **Files changed** | 14 TOML templates + 5 source files |
| **Tests** | 337/337 passed |
| **Commits** | 5 atomic commits |
| **Human input** | 3 messages (feature request + update-spec + finish-work) |
<Card title="Try it yourself" icon="rocket" href="/start/install-and-first-task">
Install Trellis, open a new AI session, and describe your feature request.
</Card>
# Trellis for Cursor
Source: https://docs.trytrellis.app/showcase/trellis-cursor
# About
Community fork optimized for Cursor with Chinese subagents and MCP integration. Based on Trellis v0.2.12.
[](https://github.com/jojolionss/Trellis)
## Key Features
* **Cursor Commands**: 13 slash commands in `.cursor/commands/` format
* **Chinese Localization**: All commands translated to Chinese
* **MCP Integration**: `trellis-context.*` tools for task management
* **Multi-model Support**: Specify models like `claude-4.5-opus-high-thinking`
# frontend-fullchain-optimization
Source: https://docs.trytrellis.app/skills-market/frontend-fullchain-optimization
Optimize frontend performance with a Web Vitals-driven diagnosis workflow
An evidence-first skill for diagnosing and improving frontend performance with
Web Vitals. It helps AI prioritize the right bottleneck, choose targeted fixes,
and verify whether a change actually improved user experience.
Use it when you need to optimize or review:
* slow page loads
* poor LCP, FCP, INP, CLS, TTFB, or TBT
* layout shifts and unstable rendering
* slow interactions caused by main-thread work
* image, font, or code-splitting regressions
## Why This Skill?
Most frontend performance work fails because teams optimize without enough
evidence or fix symptoms before upstream bottlenecks. This skill gives AI a
repeatable workflow:
1. Collect the minimum useful evidence
2. Identify the primary bottleneck
3. Pick the matching optimization branch
4. Re-measure when possible before claiming success
It supports both tool-rich and tool-light environments:
* **MCP-assisted mode** when Lighthouse or browser performance tooling is available
* **Manual-evidence mode** when you only have reports, traces, screenshots, or metric snapshots
By default, the workflow assumes Lighthouse and Performance evidence is
collected manually. If you do not have manual measurements yet, the skill should
only provide inferred suggestions and recommend follow-up verification after the
change.
## Install
```bash theme={null}
npx skills add mindfold-ai/marketplace --skill frontend-fullchain-optimization
```
Or install all available skills:
```bash theme={null}
npx skills add mindfold-ai/marketplace
```
Options:
| Flag | Description |
| ---------------- | -------------------------------------- |
| `-g` | Install globally (`~/.claude/skills/`) |
| `-a claude-code` | Target a specific agent |
| `-y` | Non-interactive mode |
## Verify Installation
Check if the skill is available:
```
What skills do you have access to?
```
Claude should list `frontend-fullchain-optimization` in the response.
## Usage
After installation, ask AI to analyze the current performance evidence:
```
Use frontend-fullchain-optimization to diagnose why this route has poor LCP and tell me what to fix first.
```
```
Review this Lighthouse report with frontend-fullchain-optimization and propose the smallest high-impact fix.
```
```
I only have DevTools screenshots and metric snapshots. Use frontend-fullchain-optimization in manual-evidence mode.
```
## What It Covers
| Area | Included guidance |
| ------------ | ------------------------------------------------------------------------------------------ |
| Metrics | LCP, FCP, INP, CLS, TTFB, and TBT thresholds and prioritization |
| Diagnosis | Primary bottleneck decision tree and required evidence checklist |
| Optimization | Rendering, images, fonts, code splitting, layout stability, and interaction responsiveness |
| Verification | Before/after template for documenting improvements and remaining bottlenecks |
## What's Included
| File | Contents |
| ---------- | ---------------------------------------------------------------------------------------------- |
| `SKILL.md` | The full performance workflow, metric playbooks, evidence checklist, and verification template |
# Overview
Source: https://docs.trytrellis.app/skills-market/index
Ready-to-use skills for Trellis
Skills extend Trellis with specialized knowledge and workflows. Current Trellis installs include built-in Trellis skills automatically, and marketplace skills remain available for compatibility and specialized domains.
Install marketplace skills with one command via [skills.sh](https://skills.sh):
```bash theme={null}
npx skills add mindfold-ai/marketplace
```
## Official Skills
| Skill | Description | Install |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| [trellis-meta](/skills-market/trellis-meta) | Customize and modify Trellis | Built in via `trellis init`; marketplace install for compatibility |
| [trellis-spec-bootstrap](/skills-market/trellis-spec-bootstrap) | Bootstrap project-specific Trellis specs from the real codebase | Bundled with Trellis |
| [frontend-fullchain-optimization](/skills-market/frontend-fullchain-optimization) | Diagnose and optimize frontend performance with Web Vitals | `npx skills add mindfold-ai/marketplace -s frontend-fullchain-optimization` |
| [mem-recall](/skills-market/mem-recall) | Recall past AI conversations across Claude / Codex / OpenCode / Pi via `trellis mem` | `npx skills add mindfold-ai/marketplace -s mem-recall` |
## Community Skills
Coming soon.
# mem-recall
Source: https://docs.trytrellis.app/skills-market/mem-recall
Cross-platform AI conversation recall via trellis mem
mem-recall makes the AI invoke `trellis mem` whenever the user references past conversations, retrieve content from local Claude Code, Codex, Devin CLI, Grok, OpenCode, Pi and ZCode session stores, and answer with session-id + verbatim quotation.
Trigger phrases include `last time`, `we discussed`, `what did I tell <Claude/Codex>`, `find ... last week`, `上次`, `之前`, and other references to prior dialogue.
Without the skill, the AI defaults to "I don't have that context" or speculative answers. The skill's frontmatter `description` field instructs the AI to run `trellis mem` in these cases, with a `search` → `context` two-step retrieval flow.
## Prerequisites
| Tool | Purpose | Required |
| ----------------------------------------------------------------------- | ----------------------- | ------------ |
| [Trellis CLI](https://github.com/mindfold-ai/Trellis) **0.6.0-beta.0+** | Provides `trellis mem` | Required |
| Claude Code, Codex CLI, Devin CLI, Grok, OpenCode, Pi, ZCode | Source of past sessions | At least one |
```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis --version # ≥ 0.6.0-beta.0
```
## Install
```bash theme={null}
npx skills add mindfold-ai/marketplace --skill mem-recall
```
Or install all marketplace skills:
```bash theme={null}
npx skills add mindfold-ai/marketplace
```
| Flag | Description |
| ---------------- | --------------------------------------- |
| `-g` | Install globally to `~/.claude/skills/` |
| `-a claude-code` | Target a specific agent |
| `-y` | Non-interactive mode |
Ask the AI which skills are available; `mem-recall` should appear in the list.
## Trigger examples
No manual command needed. The following user messages trigger the skill:
* last time how did we solve the wait\_agent deadlock in #240?
* which project did I discuss the plugin design in?
* find what I told Claude about memory architecture last week
* 上次我们怎么处理 #240 的来着？
## Retrieval flow
The skill instructs the AI to execute two steps.
**Step 1 — Candidate search**
```bash theme={null}
trellis mem search "<keyword>" [--cwd <project>] [--since <date>]
```
Multi-token AND search across cleaned dialogue. Returns ranked sessions. Score formula: `(3 × user_hits + assistant_hits) / total_turns`. User-turn hits are weighted ×3 because user wording reflects topic intent more strongly than AI elaboration.
**Step 2 — Content extraction**
```bash theme={null}
trellis mem context <session-id> --grep <keyword> --turns 3 --around 1
```
Returns the top-N hit turns plus surrounding context. Default character budget ≤6000, adjustable via `--max-chars`.
## Cleaning before search
`trellis mem` strips the following before searching, so hits reflect actual dialogue:
* prompt injections: `<system-reminder>`, `<workflow-state>`, `<INSTRUCTIONS>`, `<environment_context>`, etc.
* Codex AGENTS.md preamble (first user message is dropped entirely)
* tool calls and tool results (only `text` blocks retained)
Turns from before a compaction are kept, with a marker showing where the compaction happened. Content the platform does not store in readable form is reported instead of silently dropped: Codex encrypts messages between agents, and Grok keeps pre-compaction turns as rendered markdown.
## Data sources
Reads local files directly. No daemon, no index, no upload.
| Platform | Storage |
| ----------- | ----------------------------------------------------------------------------------------------- |
| Claude Code | `~/.claude/projects/<sanitized-cwd>/*.jsonl` |
| Codex | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` |
| Devin CLI | `~/.local/share/devin/cli/sessions.db` (`--platform devin`; not `trellis init --devin` Desktop) |
| OpenCode | `~/.local/share/opencode/opencode.db` |
| Pi | `~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<id>.jsonl` |
| Grok | `~/.grok/sessions/<url-encoded-cwd>/<session-id>/chat_history.jsonl` |
## Out-of-scope use cases
| Need | Tool |
| --------------------------------- | ---------------- |
| Search code | `Grep` / `Read` |
| Search commit history | `git log` / `gh` |
| Search current-project files/docs | `Read` / `Glob` |
mem-recall is for AI conversation history only, not file or code search.
## Performance
| Scope | Time |
| ---------------------------- | ------- |
| Project-scoped 3-week search | \~0.85s |
| Global, no time filter | \~3s |
Stateless. Each invocation cold-reads from disk; OS page cache absorbs IO so warm and cold runs perform similarly.
# trellis-meta
Source: https://docs.trytrellis.app/skills-market/trellis-meta
The essential skill for customizing Trellis
The official meta-skill for understanding and customizing Trellis. Current Trellis projects get this skill automatically from `trellis init`, so AI can help you:
* Add specialized agents for your workflow
* Change how context gets injected
* Add project-specific commands
* Adapt local `.trellis/` and platform files to your project
## Install
Works with all Trellis platform skill roots: Claude Code, Cursor, OpenCode, Codex, Kilo, Kiro, Gemini CLI, Antigravity, Devin, Qoder, CodeBuddy, GitHub Copilot, Factory Droid, and Pi Agent.
For Trellis-managed projects, initialize or update the platform you use:
```bash theme={null}
trellis init --claude
trellis init --codex
trellis update
```
`trellis init` writes `trellis-meta` into the selected platform's skill directory and `trellis update` keeps it hash-tracked with the rest of the built-in templates.
For non-Trellis projects or older Trellis installs, use the marketplace compatibility path:
```bash theme={null}
npx skills add mindfold-ai/marketplace --skill trellis-meta
```
Or install all available skills:
```bash theme={null}
npx skills add mindfold-ai/marketplace
```
Options:
| Flag | Description |
| ---------------- | -------------------------------------- |
| `-g` | Install globally (`~/.claude/skills/`) |
| `-a claude-code` | Target a specific agent |
| `-y` | Non-interactive mode |
## Verify Installation
Check if the skill is available:
```
What skills do you have access to?
```
Your AI tool should list `trellis-meta` in the response.
## Usage
After installation, tell AI what you want:
```
I want to add a deploy agent to handle deployment workflow
```
```
Help me modify the check hook to add a custom verification command
```
```
I want to add a new workflow phase called review
```
AI will automatically use the skill's documentation and give you the correct modification steps.
## What's Included
| Directory | Contents |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `local-architecture/` | How local `.trellis/` workflow, tasks, specs, workspace, scripts, and context injection fit together |
| `platform-files/` | How platform settings, hooks, agents, skills, commands, prompts, and workflows connect to Trellis |
| `customize-local/` | How to modify generated local files for workflow, task lifecycle, context loading, hooks, agents, skills, commands, and specs |
# trellis-spec-bootstrap
Source: https://docs.trytrellis.app/skills-market/trellis-spec-bootstrap
Bootstrap project-specific Trellis coding specs from the real codebase
`trellis-spec-bootstrap` helps an AI create or refresh `.trellis/spec/` guidelines from the actual repository. It is platform-neutral: one capable agent can analyze the codebase, choose the spec boundaries, write the docs, and verify that no placeholder text remains.
## When to Use It
Use this skill after `trellis init` when the default spec templates exist but still need project-specific content.
Good fits:
* New projects that need first-pass Trellis coding specs
* Existing projects where `.trellis/spec/` is still generic
* Repositories where the spec boundaries should follow real package or layer boundaries
* Teams that want source-backed rules instead of boilerplate advice
## Availability
`trellis-spec-bootstrap` is bundled with Trellis. After installing or updating Trellis, use the skill directly; there is no extra marketplace download step.
The beta bundle includes this skill now. The docs also mention it on the release track so the same workflow is visible there once the release bundle includes the matching skill.
## Usage
After installation, ask the AI to bootstrap or refresh specs:
```text theme={null}
Use trellis-spec-bootstrap to fill the Trellis specs for this project from the real codebase.
```
```text theme={null}
Refresh .trellis/spec so it reflects the current repository structure and coding patterns.
```
## How It Works
1. Inspect the existing `.trellis/spec/` tree.
2. Analyze repository architecture with GitNexus, ABCoder, language tooling, or direct source reads.
3. Choose spec boundaries that match the actual codebase.
4. Fill or reshape spec files with concrete file paths, examples, and anti-patterns.
5. Verify that index files match the final spec set and no template placeholders remain.
## Included References
| File | Contents |
| ----------------------------------- | -------------------------------------- |
| `SKILL.md` | Main workflow and operating rules |
| `references/repository-analysis.md` | How to inspect repository architecture |
| `references/spec-task-planning.md` | How to decompose spec work |
| `references/spec-writing.md` | How to write high-signal Trellis specs |
| `references/mcp-setup.md` | GitNexus and ABCoder setup notes |
# Cloudflare Workers + Hono + Turso
Source: https://docs.trytrellis.app/templates/specs-cf-workers
Full-stack spec template for Cloudflare Workers apps with Hono framework and Turso database
A complete coding convention template for production Cloudflare Workers applications with Hono framework, Drizzle ORM, and Turso edge database.
<Card title="Download Template" icon="download" href="https://download-directory.github.io/?url=https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/cf-workers-fullstack">
Download as ZIP and extract to `.trellis/spec/`
</Card>
## What's Included
| Category | Files | Coverage |
| -------- | ------------------ | ---------------------------------------------------- |
| Backend | 11 files | Hono, Drizzle/Turso, API patterns, security, storage |
| Frontend | 7 files + examples | Components, hooks, auth, design templates |
| Shared | 5 files | TypeScript, code quality, dependencies, timestamps |
| Guides | 3 files | OAuth consent flow, serverless connections |
| Pitfalls | 6 files | Workers compat, cross-layer, env config, CSS |
## Template Structure
```
spec/
├── backend/
│ ├── index.md
│ ├── hono-framework.md
│ ├── database.md
│ ├── api-module.md
│ ├── api-patterns.md
│ ├── security.md
│ ├── storage.md
│ └── ...
│
├── frontend/
│ ├── index.md
│ ├── authentication.md
│ ├── components.md
│ ├── hooks.md
│ ├── directory-structure.md
│ ├── examples/frontend-design/
│ └── ...
│
├── guides/
│ ├── oauth-consent-flow.md
│ ├── serverless-connection-guide.md
│ └── ...
│
├── shared/
│ ├── typescript.md
│ ├── code-quality.md
│ ├── dependency-versions.md
│ └── ...
│
├── big-question/
│ ├── workers-nodejs-compat.md
│ ├── cross-layer-contract.md
│ ├── env-configuration.md
│ └── ...
│
└── README.md
```
## Key Topics
### Backend
* Hono framework patterns (type-safe bindings, middleware, WebSocket)
* Drizzle ORM + Turso/libSQL (batch ops, N+1 prevention, Workers pitfalls)
* Cloudflare storage (R2, KV, Cache API for session caching)
* Security (token generation, timing-safe comparison, OAuth redirect validation)
* Structured JSON logging with request context
### Frontend
* React 19 + React Router v7 with Vite
* Better Auth UI v3.x integration (SSR-safe, Cloudflare Workers considerations)
* shadcn/ui components + Tailwind CSS v4
* Design example templates (minimalist hero, maximalist dashboard, animations)
### Guides
* OAuth 2.1 consent flow with resource selection
* Serverless connection debugging (stale connections, subrequest limits)
### Common Pitfalls
* Workers Node.js compatibility (`nodejs_compat` flag)
* Cross-layer contract violations (data flows but never reaches client)
* Build-time vs runtime environment variables
* CSS debugging in Tailwind v4
## Usage
1. Download the ZIP file
2. Extract to your project's `.trellis/spec/` directory
3. Replace generic env var names with your actual bindings
4. Customize for your specific conventions
5. Remove sections that don't apply
<Card title="View on GitHub" icon="github" href="https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/cf-workers-fullstack">
Browse the template source code
</Card>
# Electron + React + TypeScript
Source: https://docs.trytrellis.app/templates/specs-electron
Full-stack spec template for Electron desktop apps with React frontend
A complete coding convention template for Electron applications with React frontend and TypeScript.
<Card title="Download Template" icon="download" href="https://download-directory.github.io/?url=https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/electron-fullstack">
Download as ZIP and extract to `.trellis/spec/`
</Card>
## What's Included
| Category | Files | Coverage |
| -------- | -------- | -------------------------------------- |
| Frontend | 11 files | Components, hooks, state, IPC, CSS |
| Backend | 14 files | API patterns, database, error handling |
| Guides | 8 files | Cross-layer thinking, debugging |
| Shared | 6 files | TypeScript, git, code quality |
## Template Structure
```
spec/
├── frontend/
│ ├── index.md
│ ├── components.md
│ ├── hooks.md
│ ├── state-management.md
│ ├── ipc-electron.md
│ └── ...
│
├── backend/
│ ├── index.md
│ ├── api-patterns.md
│ ├── database.md
│ ├── error-handling.md
│ └── ...
│
├── guides/
│ ├── cross-layer-thinking-guide.md
│ ├── bug-root-cause-thinking-guide.md
│ └── ...
│
├── shared/
│ ├── typescript.md
│ ├── git-conventions.md
│ └── ...
│
└── README.md
```
## Key Topics
### Frontend
* React component patterns and hooks
* Electron IPC communication
* State management with Zustand
* CSS design system
### Backend
* API module structure
* SQLite database patterns
* Error handling and logging
* macOS permissions
### Guides
* Cross-layer thinking for full-stack changes
* Bug root cause analysis
* Database schema migrations
## Usage
1. Download the ZIP file
2. Extract to your project's `.trellis/spec/` directory
3. Customize for your specific conventions
4. Remove sections that don't apply
5. Update examples to match your codebase
<Card title="View on GitHub" icon="github" href="https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/electron-fullstack">
Browse the template source code
</Card>
# Overview
Source: https://docs.trytrellis.app/templates/specs-index
Coding convention templates for common tech stacks
Spec templates help you quickly set up coding guidelines for your project. Download, customize, use.
<Info>
**Specs are meant to be customized.** Trellis ships with empty spec templates by default — they are placeholders for *your* project's conventions. Every team's stack, patterns, and quality bar are different, so the specs you write should reflect your actual codebase, not generic best practices. Templates from the marketplace give you a head start, but always tailor them to your project.
</Info>
## Available Templates
| Template | Stack | Description |
| ---------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------- |
| [Electron + React + TypeScript](https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/electron-fullstack) | Full-stack | Electron desktop app with React frontend |
| [Next.js + oRPC + PostgreSQL](https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/nextjs-fullstack) | Full-stack | Next.js app with oRPC API and PostgreSQL |
| [CF Workers + Hono + Turso](https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/cf-workers-fullstack) | Full-stack | Cloudflare Workers with Hono and Turso |
<CardGroup>
<Card title="Download Electron Template" icon="download" href="https://download-directory.github.io/?url=https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/electron-fullstack">
Electron + React + TypeScript (50 files)
</Card>
<Card title="Download Next.js Template" icon="download" href="https://download-directory.github.io/?url=https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/nextjs-fullstack">
Next.js + oRPC + PostgreSQL (35 files)
</Card>
<Card title="Download CF Workers Template" icon="download" href="https://download-directory.github.io/?url=https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/cf-workers-fullstack">
CF Workers + Hono + Turso (38 files)
</Card>
</CardGroup>
## Template Marketplace <sup>v0.3.6</sup>
Starting from v0.3.6, you can fetch spec templates directly from any Git repository using the `--registry` flag:
```bash theme={null}
# Fetch from a custom registry
trellis init --registry https://github.com/your-org/your-spec-templates
# Combine with platform flags
trellis init --registry https://github.com/your-org/your-spec-templates --cursor -u your-name
```
### How it works
Trellis auto-detects two modes:
* **Marketplace mode**: If the repository contains a `marketplace/index.json` file, Trellis reads the template index and lets you pick which template to install
* **Direct download mode**: If no `index.json` is found, Trellis treats the entire `marketplace/specs/` directory as a single template and downloads it directly
### Publishing your own templates
To create a spec template registry that others can use with `--registry`:
1. Create a Git repository (GitHub, GitLab, or Bitbucket)
2. Add a `marketplace/` directory with your spec templates
3. Create `marketplace/index.json` to list available templates:
```json theme={null}
{
"version": 1,
"templates": [
{
"id": "my-stack",
"type": "spec",
"name": "My Stack Template",
"description": "Conventions for our tech stack",
"path": "marketplace/specs/my-stack",
"tags": ["react", "node", "typescript"]
}
]
}
```
4. Inside each template path, place your spec files following the standard structure (see below)
5. Share the repository URL — users install with `trellis init --registry <url>`
## Template Structure
Each template follows this structure:
```
spec/
├── frontend/ # Frontend guidelines
│ ├── index.md # Navigation index
│ ├── components.md # Component patterns
│ ├── hooks.md # Hook conventions
│ └── state-management.md
│
├── backend/ # Backend guidelines
│ ├── index.md
│ └── ...
│
├── guides/ # Thinking guides
│ ├── index.md
│ └── ...
│
└── README.md # Template overview
```
## How to Use
1. Download the template ZIP or use `trellis init --registry`
2. Extract to `.trellis/spec/` in your project
3. Customize for your project's specific conventions
4. Remove sections that don't apply
5. Update paths and examples to match your codebase
<Tip>
You don't have to fill every spec file at once. Start with the areas that matter most to your project, then expand over time. The bootstrap task created by `trellis init` will guide you through the initial fill.
</Tip>
## Contributing Templates
Want to share your specs with the community? Create a repository with your templates and open a PR to add it to the [official template registry](https://github.com/mindfold-ai/Trellis/tree/main/marketplace).
# Next.js + oRPC + PostgreSQL
Source: https://docs.trytrellis.app/templates/specs-nextjs
Full-stack spec template for Next.js applications with oRPC API layer and PostgreSQL
A complete coding convention template for production Next.js applications with oRPC API layer, Drizzle ORM, and PostgreSQL.
<Card title="Download Template" icon="download" href="https://download-directory.github.io/?url=https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/nextjs-fullstack">
Download as ZIP and extract to `.trellis/spec/`
</Card>
## What's Included
| Category | Files | Coverage |
| -------- | -------- | ------------------------------------------------- |
| Frontend | 12 files | Components, hooks, state, oRPC, AI SDK, CSS |
| Backend | 10 files | oRPC router, database, auth, performance, logging |
| Guides | 3 files | Cross-layer thinking, pre-implementation |
| Shared | 4 files | TypeScript, code quality, dependencies |
| Pitfalls | 5 files | PostgreSQL, build system, mobile CSS |
## Template Structure
```
spec/
├── frontend/
│ ├── index.md
│ ├── components.md
│ ├── hooks.md
│ ├── state-management.md
│ ├── orpc-usage.md
│ ├── authentication.md
│ ├── ai-sdk-integration.md
│ └── ...
│
├── backend/
│ ├── index.md
│ ├── orpc-usage.md
│ ├── database.md
│ ├── authentication.md
│ ├── performance.md
│ └── ...
│
├── guides/
│ ├── pre-implementation-checklist.md
│ ├── cross-layer-thinking-guide.md
│ └── ...
│
├── shared/
│ ├── typescript.md
│ ├── code-quality.md
│ ├── dependencies.md
│ └── ...
│
├── big-question/
│ ├── postgres-json-jsonb.md
│ ├── sentry-nextintl-conflict.md
│ └── ...
│
└── README.md
```
## Key Topics
### Frontend
* Next.js 15 App Router with React 19
* oRPC client + React Query integration
* Server Components vs Client Components
* Authentication with better-auth
* Vercel AI SDK (useChat, tool calls, streaming)
* TailwindCSS 4 + Radix UI patterns
### Backend
* oRPC router, procedures, and middleware
* Drizzle ORM + PostgreSQL (N+1 prevention, transactions, JSON/JSONB)
* better-auth server configuration
* Performance patterns (concurrency, caching, rate limiting)
* Structured logging with Sentry
### Guides
* Pre-implementation checklist (search before write)
* Cross-layer thinking for Next.js full-stack changes
### Common Pitfalls
* PostgreSQL `json` vs `jsonb` with Drizzle ORM
* Sentry + next-intl plugin conflict
* Turbopack vs Webpack flexbox differences
* WebKit tap highlight on mobile
## Usage
1. Download the ZIP file
2. Extract to your project's `.trellis/spec/` directory
3. Replace `@your-app/*` placeholders with your monorepo package paths
4. Customize for your specific conventions
5. Remove sections that don't apply
<Card title="View on GitHub" icon="github" href="https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/nextjs-fullstack">
Browse the template source code
</Card>
# open-typeless
Source: https://docs.trytrellis.app/use-cases/open-typeless
Step-by-step guide: Building a macOS voice input app with Trellis
# open-typeless
A step-by-step tutorial showing how to use Trellis to build a macOS voice input app from scratch.
<Info>
**Source Code**:
[github.com/mindfold-ai/open-typeless](https://github.com/mindfold-ai/open-typeless)
</Info>
## Project Initialization
### Create Electron Project
```bash theme={null}
npx create-electron-app@latest open-typeless --template=vite-typescript
cd open-typeless
# Remove npm generated files
rm -rf node_modules package-lock.json
# Create .npmrc (required for pnpm + Electron)
cat > .npmrc << 'EOF'
node-linker=hoisted
shamefully-hoist=true
EOF
# Reinstall with pnpm
pnpm install
```
### Initialize Trellis
```bash theme={null}
trellis init
```
<img alt="trellis init" />
### Copy Specs from Existing Project
If you have specs from a similar project, copy them over:
```bash theme={null}
cp -r /path/to/old-project/.trellis/spec ./
```
### Ask AI to Fill in Specs
**Prompt:**
> Help me select useful specs from electron-doc/ and organize them into this project's .trellis/spec/
AI will analyze and organize specs:
<img alt="spec selection" />
## Task Planning
### Ask AI to Plan Tasks
**Prompt:**
> I want to use Volcengine ASR BigModel API to build this. Help me plan how to break down the tasks.
AI creates a batch-based task plan:
<img alt="task planning" />
### Create Tasks
AI creates tasks organized into batches:
| Batch | Tasks | Purpose |
| ------- | -------------------------------------------------------------------- | -------------------------------- |
| Batch 1 | `asr-infrastructure` | Foundation (must complete first) |
| Batch 2 | `asr-audio-recorder`, `asr-volcengine-client`, `asr-floating-window` | Can run in parallel |
| Batch 3 | `asr-integration` | Integration (depends on Batch 2) |
<img alt="tasks created" />
### Complete Batch 1
After Batch 1 completes, verify and update downstream task contexts:
<img alt="batch 1 complete" />
## Parallel Development
### Start Parallel Sessions
For current Trellis, create one Git worktree and one AI session for each Batch 2 task, then start the matching Trellis task inside that session.
```bash theme={null}
git worktree add ../asr-audio-recorder -b feature/asr-audio-recorder
git worktree add ../asr-volcengine-client -b feature/asr-volcengine-client
git worktree add ../asr-floating-window -b feature/asr-floating-window
```
Each session has its own active-task pointer, so starting a task in one session does not affect the others.
<img alt="parallel agents" />
## Monitor Progress
### Check Agent Status
AI monitors agent status and task progress:
<img alt="agent status" />
### Record Session
After parallel sessions complete, review and merge each branch through your normal Git process:
<img alt="parallel PRs" />
After merging and completing a batch, record the session:
**Prompt:** `/trellis:finish-work`
<img alt="record session" />
## Continue Development
### Check Remaining Tasks
AI shows remaining tasks in the current project:
<img alt="task list" />
### Implement Next Feature
Select the next task, AI uses trellis-implement sub-agent then trellis-check sub-agent:
<img alt="implement and check" />
### Configure and Test
AI helps with remaining setup (environment config, permissions):
<img alt="final setup" />
## Summary
Using Trellis to build open-typeless:
| Step | What | Trellis Feature |
| ---- | -------------------- | --------------------------------------------------- |
| 1 | Initialize project | `trellis init`, spec organization |
| 2 | Plan tasks | AI task breakdown, batch planning |
| 3 | Parallel development | Native Git worktrees + session-scoped Trellis tasks |
| 4 | Monitor & record | `/trellis:finish-work` |
| 5 | Continue iterating | Task hooks, implement/trellis-check sub-agents |
**Result:** Complete Electron app in 1 day, with structured specs and documented progress.
# v0.1.9
Source: https://docs.trytrellis.app/changelog/v0.1.9
2026-01-10
Renamed some slash commands.
## Changes
| Old | New |
| ---------------------- | ------------------- |
| `onboard-developer.md` | `onboard.md` |
| `record-agent-flow.md` | `record-session.md` |
# v0.2.0
Source: https://docs.trytrellis.app/changelog/v0.2.0
2026-01-15
Comprehensive naming redesign for clarity.
## Changes
| Old | New | Description |
| ------------------ | --------------- | ---------------------- |
| `agent-traces/` | `workspace/` | Developer work records |
| `structure/` | `spec/` | Development guidelines |
| `backlog/` | `tasks/` | Task tracking |
| `.current-feature` | `.current-task` | Current task pointer |
| `feature.sh` | `task.sh` | Task management script |
# v0.3.0-beta.0
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.0
2026-01-25
**BREAKING**: Shell to Python migration + Command namespace changes.
## Shell Scripts to Python
All `.sh` scripts replaced by `.py` equivalents. Requires Python 3.10+.
| Old | New |
| ------------------------------- | ------------------------------- |
| `.trellis/scripts/*.sh` | `.trellis/scripts/*.py` |
| `.trellis/scripts/multi-agent/` | `.trellis/scripts/multi_agent/` |
| `./script.sh` | `python3 ./script.py` |
## Command Namespace
Commands moved to namespaced paths:
| Platform | Old | New |
| ----------- | --------------------------- | ----------------------------------- |
| Claude Code | `.claude/commands/start.md` | `.claude/commands/trellis/start.md` |
| Cursor | `.cursor/commands/start.md` | `.cursor/commands/trellis-start.md` |
Run `trellis update --migrate` to apply changes.
# v0.3.0-beta.10
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.10
2026-01-23
Windows UTF-8 encoding fix.
## Changes
* Fixed UnicodeEncodeError and SyntaxWarning on Windows
* Added UTF-8 encoding declarations and Windows stdout handling in hooks
# v0.3.0-beta.11
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.11
2026-01-23
Bug fix for Windows UTF-8 encoding in hooks.
## Changes
* Fixed remaining Windows UTF-8 encoding issues in hook scripts
# v0.3.0-beta.12
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.12
2026-01-24
Windows compatibility and multi-model dispatch improvements.
## Changes
* Fixed Windows hook JSON parse error caused by backslash characters in templates
* Fixed cross-platform script paths for Python command
* Fixed multi-agent dispatch prompt for GPT/Codex model compatibility
# v0.3.0-beta.13
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.13
2026-01-25
Cursor platform support and base branch auto-recording.
## Changes
* Added Cursor as supported platform alongside Claude Code and OpenCode
* Auto-record `base_branch` on task creation for correct PR targeting
* Added `set-base-branch` command
# v0.3.0-beta.14
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.14
2026-01-26
Fix update error for 0.2.x users.
## Changes
* Fixed "path argument must be of type string" error when upgrading from 0.2.x
* Added missing manifests for 0.2.12, 0.2.13, and earlier beta versions
# v0.3.0-beta.15
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.15
2026-01-27
Add cli\_adapter.py to update system.
## Changes
* Added missing `cli_adapter.py` to template files in update mechanism
# v0.3.0-beta.16
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.16
2026-01-28
iFlow CLI support and update mechanism fix.
## Changes
* Added iFlow CLI platform support
* Fixed Windows stdout encoding in iFlow hooks
* Update mechanism now only updates configured platforms
# v0.3.0-beta.7
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.7
2026-01-30
Windows compatibility fixes and hook JSON format corrections.
## Changes
* Fixed Claude Code hook JSON output format (Issue #18)
* Added UTF-8 encoding for git commands (Issue #19)
* Cross-platform `tail_follow()` implementation in status.py
* Hook commands now use `python3` directly
> **Windows Users**: If your system uses `python` instead of `python3`, manually update `.claude/settings.json` to change `python3` to `python`.
# v0.3.0-beta.8
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.8
2026-01-31
Task commands now support task name lookup. You can use `python3 task.py start my-task` instead of the full path `python3 task.py start .trellis/tasks/01-31-my-task`.
## Changes
* Simplified task command syntax
* No migration required
# v0.3.0-beta.9
Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.9
2026-01-22
OpenCode platform support with agents, commands, and plugins.
## Changes
* Added OpenCode platform with agents, commands, and plugin support
* Session ID extraction and resume capability
# v0.3.0-rc.0
Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.0
2026-02-06
Major internal refactor with centralized platform registry, remote spec templates, and comprehensive test coverage.
## New features
* **Remote spec templates**: `trellis init -t electron-fullstack` downloads and applies spec templates
* **Centralized platform registry**: All platform metadata in one place, derived helpers replace scattered hardcoded lists
* **Test coverage**: 312 tests across 17 files with Vitest coverage reporting
## Changes
* Extracted `resolvePlaceholders()` to shared module, removed templates.ts dispatcher
* Release tooling supports beta/rc/release workflows
* Extracted VERSION constant for consistent version management
# v0.3.0-rc.1
Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.1
2026-02-07
Fix CLI version comparison for prerelease versions.
## Changes
* Fixed rc version comparison (`0.3.0-rc.0` was incorrectly sorted below `0.3.0-beta.16`)
* Deduplicated `compareVersions()` across 3 modules into shared `utils/compare-versions.ts`
# v0.3.0-rc.2
Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.2
2026-02-09
Codex platform integration.
## New features
* **Codex platform**: `trellis init --codex` sets up OpenAI Codex CLI with skill templates
* Extended Python runtime (`cli_adapter.py`) to support Codex platform detection
## Changes
* Full test suite passing with coverage
* Codex uses skills pattern (`SKILL.md`) instead of slash commands
# v0.3.0-rc.3
Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.3
2026-02-15
Code-spec enforcement and robustness fixes.
## Changes
* Fixed table separator matching in `add_session.py` to tolerate formatted markdown
* Fixed Codex skill templates (replaced `/trellis:` with `$` syntax, removed Claude-specific references)
* Enforced code-spec depth requirements across all platform templates
# v0.3.0-rc.4
Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.4
2026-02-19
Active spec sync in finish agent.
## Changes
* Finish agent now actively syncs spec docs during pipeline runs
* Injected `update-spec.md` into finish context across Claude, iFlow, and OpenCode
* Restored code-spec enforcement in Codex skill templates
# v0.3.0-rc.5
Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.5
2026-02-24
Brainstorm command templates for all platforms.
## New features
* **Brainstorm command**: `/trellis:brainstorm` added to all 5 platform templates (Claude, iFlow, OpenCode, Cursor, Codex) for interactive requirements discovery
## Changes
* Added brainstorm workflow references to start commands across iFlow, OpenCode, Cursor, and Codex (matching existing Claude start.md)
## Migration
No migration required. Run `trellis update` to get the latest templates.
# v0.3.0-rc.6
Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.6
2026-02-26
4 new platforms — Trellis now supports 8 AI coding tools.
## New platforms
* **Kilo CLI**: Commands-only platform with subdirectory namespacing (`.kilocode/commands/trellis/`)
* **Kiro Code**: Skills-based platform (`.kiro/skills/`)
* **Gemini CLI**: First TOML-format command platform (`.gemini/commands/trellis/*.toml`)
* **Antigravity**: Workflow-based platform adapted from Codex skills (`.agent/workflows/`)
## Bug fixes
* Fixed non-existent `spec/shared/` references in init-context defaults
* Fixed iFlow start/finish-work template content
* Corrected license badge from FSL to AGPL-3.0
* Fixed start process flow
## Tests
* Added 50+ new tests covering all 4 new platforms (templates, configurators, init integration, regression)
## Migration
No migration required. Run `trellis init --kilo`, `--kiro`, `--gemini`, or `--antigravity` to add new platform support.
# v0.3.1
Source: https://docs.trytrellis.app/changelog/v0.3.1
2026-03-02
SessionStart reinject on clear/compact and spec template project-type awareness.
## Enhancements
* **SessionStart reinject**: Hook now fires on `clear` and `compact` events in addition to `startup` — ensures context is always re-injected after session reset (Claude + iFlow)
* **New slash command**: Added `/trellis:create-manifest` to guide AI through the full manifest creation flow
## Bug fixes
* Fixed iFlow command templates writing to wrong path (`.iflow/commands/` → `.iflow/commands/trellis/`)
* Fixed `trellis update` injecting spec files for non-existent backend/frontend directories
* Fixed `trellis init` creating all spec directories regardless of project type (now respects `projectType`)
* Removed dead `guidesCrossPlatformThinkingGuideContent` export and broken links in guides index
## Migration
No migration required. Run `trellis update` to sync template changes.
# v0.3.10
Source: https://docs.trytrellis.app/changelog/v0.3.10
2026-03-12
Bug fixes for registry URL handling and AI model compatibility.
## Bug Fixes
* **HTTPS registry URLs** — `trellis init --registry` now accepts HTTPS URLs (e.g. `https://github.com/user/repo`) by auto-converting them to giget-style format. Supports GitHub, GitLab, and Bitbucket, including `/tree/branch/path` URLs and `.git` suffix. (#87)
* **Record-session AI compatibility** — Updated the record-session command wording across all 9 platforms. AI models (especially GPT) previously refused to run `add_session.py` because the old "AI must NOT execute git commit" instruction was too absolute. The new wording clarifies that scripts handling `.trellis/` metadata commits are safe to execute. (#88)
# v0.3.2
Source: https://docs.trytrellis.app/changelog/v0.3.2
2026-03-03
Auto-commit workspace changes after record-session and project-level configuration.
## Enhancements
* **Auto-commit workspace changes**: `add_session.py` now automatically commits `.trellis/workspace` changes after recording a session — keeps the working directory clean
* **Project-level config**: New `.trellis/config.yaml` for customizing `session_commit_message` and `max_journal_lines`
* **Config reader module**: New `common/config.py` reads config.yaml with hardcoded fallback defaults
* **Skip auto-commit**: Added `--no-commit` flag to `add_session.py` for cases where you don't want automatic commits
* **Template updates**: All 8 platform record-session templates updated with auto-commit documentation
## Migration
No migration required. Run `trellis update` to sync new files (`config.yaml`, `config.py`) and updated templates.
# v0.3.3
Source: https://docs.trytrellis.app/changelog/v0.3.3
2026-03-04
Init download UX improvements, update spec protection, and Windows encoding fixes.
## Enhancements
* **Proxy detection**: Automatically detects `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` environment variables and configures undici ProxyAgent for all network calls (including giget template downloads)
* **Download timeout with countdown**: Template index fetch has a 5s timeout with live `Loading... 2s/5s` countdown; template downloads have a 30s timeout via `Promise.race`
* **Source URL display**: Shows the GitHub URL being fetched during `trellis init` template selection
* **Retry hint**: On download failure, suggests `trellis init --template <name>` for manual retry
* **Eliminate double-fetch**: Pre-fetched `SpecTemplate` is passed to `downloadTemplateById` to avoid fetching the index twice
* **Update skips spec directory**: `trellis update` no longer touches `.trellis/spec/` — user-customized spec content is fully protected
* **Update proxy support**: `trellis update` sets up proxy before npm version check
## Bug Fixes
* **Windows stdin UTF-8**: Centralized stdio encoding in `common/__init__.py` — adds `sys.stdin` to `_configure_stream()` to fix garbled Chinese text when piping content via stdin on Windows PowerShell
* **Remove inline encoding**: Removed duplicated encoding code from `add_session.py` and `git_context.py` — all streams now handled by `common/__init__.py`
* **Record-session template cleanup**: Removed auto-commit implementation details from all 8 platform record-session templates to prevent AI agents from misusing the `--no-commit` flag
## Dependencies
* Added `undici ^6.21.0` for ProxyAgent support
* Bumped `engines.node` from `>=18.0.0` to `>=18.17.0` (required by undici v6)
## Migration
No migration required. Run `trellis update` to sync updated scripts and templates. Node.js >=18.17.0 is now required.
# v0.3.4
Source: https://docs.trytrellis.app/changelog/v0.3.4
2026-03-05
Qoder platform support, Kilo workflows migration, and record-session task awareness.
## Enhancements
* **Qoder platform**: Added Qoder as a skills-based platform (`--qoder` flag). Templates are placed at `.qoder/skills/{name}/SKILL.md`
* **Record-session prompt optimization**: `/record-session` now enforces task archive check before recording — completed tasks must be archived first. `get_context.py` gains `--mode record` for focused context output with MY ACTIVE TASKS shown first
* **Task archive auto-commit**: `task.py archive` now auto-commits after archiving. Use `--no-commit` to skip
## Bug Fixes
* **Kilo workflows**: Renamed `commands/trellis/` to `workflows/` to match Kilo's official spec at `kilo.ai/docs/customize/workflows`
* **iFlow non-interactive**: Added `IFLOW_NON_INTERACTIVE` environment variable check in session-start hook, fixing cross-layer consistency for non-interactive mode
* **Multi-agent nested session**: Clear inherited `CLAUDECODE` env var before spawning child processes, fixing nested session guard introduced in Claude Code v2.1.39+
* **Update preserves user files**: `trellis update` no longer overwrites `workflow.md` and `workspace/index.md` — these user-customizable files are only created during init
## Migration
Kilo users: `trellis update` will automatically rename `.kilocode/commands/trellis/` to `.kilocode/workflows/`.
# v0.3.5
Source: https://docs.trytrellis.app/changelog/v0.3.5
2026-03-05
Hotfix for Kilo workflows delete migration.
## Bug Fixes
* **Migration manifest field name**: Fixed `delete` migration manifest using incorrect `path` field instead of `from`, causing Kilo commands cleanup to fail during `trellis update`
## Migration
No manual migration required. Run `trellis update` to apply the Kilo workflows migration that was blocked in v0.3.4.
# v0.3.6
Source: https://docs.trytrellis.app/changelog/v0.3.6
2026-03-06
Task lifecycle hooks, custom template registries, parent-child subtasks, and PreToolUse hook fix.
## Enhancements
* **Custom template registries**: `trellis init --registry` supports fetching Spec templates from custom GitHub/GitLab/Bitbucket repositories. Automatically detects marketplace mode (`index.json`) and direct download mode
* **Task lifecycle hooks**: `.trellis/config.yaml` gains a `hooks` configuration block supporting four events: `after_create`, `after_start`, `after_finish`, and `after_archive`. Task information is passed via the `TASK_JSON_PATH` environment variable. Ships with a Linear sync hook example. See: [Task Management](/start/everyday-use)
* **Parent-child subtasks**: `task.py add-subtask` / `remove-subtask` commands for linking tasks. `task.json` gains `children`, `parent`, and `meta` fields. `task.py create --parent` creates a child task directly
* **Record-session prompt improvement**: Archive decision is now based on actual work state rather than the `task.json` status field
* **Brainstorm prompt update**: `/brainstorm` now includes a subtask decomposition step for complex tasks
## Bug Fixes
* **PreToolUse context injection failure**: Claude Code v2.1.63 renamed its internal tool from `Task` to `Agent` ([anthropics/claude-code#29677](https://github.com/anthropics/claude-code/issues/29677)), causing hook scripts with `tool_name != "Task"` checks to exit early. This broke code-spec context injection for all implement/check/debug/research agents. Fix: accept both `Task` and `Agent` tool names, and add an `"Agent"` matcher to `settings.json`
## Migration
No manual migration required. Run `trellis update` to sync the updated hook scripts and settings.
# v0.3.7
Source: https://docs.trytrellis.app/changelog/v0.3.7
2026-03-10
Smart update protection, session-start task awareness, and improved start flow.
## Enhancements
* **Update: user-deletion protection**: If you intentionally deleted a file installed by Trellis, `trellis update` now detects this via stored hashes and will not re-add it. A new "Deleted by you (preserved)" section appears in the update summary
* **Update: `update.skip` config**: Add an `update.skip` list in `.trellis/config.yaml` to permanently exclude specific files or directories from `trellis update`. Useful for monorepo projects that don't need certain platform-specific commands
* **Session-start: task status injection**: Session-start hooks now inject a `<task-status>` tag with structured state (`NO ACTIVE TASK` / `NOT READY` / `READY` / `COMPLETED`), enabling AI to automatically detect and resume in-progress tasks
* **Session-start: dynamic spec discovery**: Session-start hooks now dynamically iterate `spec/` subdirectories instead of hardcoding `frontend/backend/guides`, supporting monorepo package layouts (e.g., `spec/cli/backend/`)
* **Start flow: brainstorm enforcement**: Complex tasks now automatically trigger the brainstorm flow across all 9 supported platforms, preventing premature implementation without requirements clarification
## Migration
No manual migration required. Run `trellis update` to sync the updated hook scripts and command templates.
# v0.3.8
Source: https://docs.trytrellis.app/changelog/v0.3.8
2026-03-12
Fix YAML parser quote stripping.
## Bug Fixes
* **YAML parser: greedy quote strip** — `parse_simple_yaml()` in `worktree.py` used Python's `str.strip('"').strip("'")`, which removes ALL matching characters from both ends instead of just one pair of quotes. Values like `"echo 'hello'"` would be corrupted to `echo 'hello`. Replaced with a safe `_unquote()` helper that removes exactly one layer of matching surrounding quotes
* **Update: skip path quote handling** — `loadUpdateSkipPaths` in `update.ts` now correctly strips surrounding quotes from skip paths in `.trellis/config.yaml`, fixing cases where quoted paths like `".claude/commands/"` were not matched
## Migration
No manual migration required. Run `trellis update` to sync the fixed YAML parser to your project.
# v0.3.9
Source: https://docs.trytrellis.app/changelog/v0.3.9
2026-03-12
Fix iFlow hook matcher naming.
## Bug Fixes
* **iFlow: hook matcher naming** — Corrected iFlow SessionStart hook matcher from `compact` to `compress` to match the actual Claude Code event name
# v0.4.0
Source: https://docs.trytrellis.app/changelog/v0.4.0
2026-04-15
After 11 betas and 2 RCs, Trellis v0.4.0 stable is released!
## Monorepo-native support
`trellis init` now detects monorepos and creates **per-package** spec directories — every package gets its own coding conventions and tasks. To keep the command matrix from exploding alongside package count, the type-specific `before-backend-dev` / `before-frontend-dev` / `check-backend` / `check-frontend` are merged into single `before-dev` / `check` commands across 9 platforms.
## More platforms
* **GitHub Copilot** — `--copilot`
* **Windsurf** — `--windsurf`
* **Qoder** — `--qoder`
* **Factory Droid** — `--droid`
Enable multiple platforms in one go:
```bash theme={null}
trellis init --codex --gemini --copilot -u your-name
```
## Codex now fully supported
* **Codex SessionStart hook is enabled.** Codex users get the same auto-injection as Claude Code users — no need to manually invoke `/start` anymore. Task state, workflow, and guidelines are injected at session start.
* **Sub-agent definitions.** `.codex/agents/` now ships TOML-format `implement` / `research` / `check` agents, semantically aligned with Claude Code's `Agent` tool.
* **Shared skills layer.** Codex writes to `.agents/skills/` (the [agentskills.io](https://agentskills.io) standard directory). The same output is read automatically by Cursor, Gemini CLI, GitHub Copilot, Amp, and Kimi Code — one Codex checkbox covers a wide range of tools.
## Other improvements
* **Custom spec template registry.** `trellis init -r <source>` pulls spec templates from a custom git repository (GitHub / GitLab / Bitbucket, including self-hosted GitLab via HTTPS or SSH) instead of the default marketplace. Teams can host their own coding conventions on internal git servers.
* **Re-init fast path.** `trellis init --codex` adds Codex to an existing project; bare `trellis init` shows an interactive menu.
* **Branch awareness.** Sessions and journals carry git branch context, so parallel branches don't get tangled.
* **Claude Code statusline integration.**
* **Multi-agent pipeline.** Supports worktree submodules and PR state tracking.
## Notable fixes
* **SessionStart payload size fix.** Reduced from \~29 KB to \~7 KB, fixing a major silent bug where Claude Code was truncating task state on most projects.
* **Windows.** Statusline GBK encoding crash (thanks @xiangagou163) and `{{PYTHON_CMD}}` placeholder resolution in Codex `hooks.json`.
**Other fixes (selected)**
* fix(update): allow rename migrations to target protected paths + warn on config parse failure
* fix(update): parse name from `.developer` when creating migration task
* fix(hooks): normalize `.current-task` path refs across platforms (#130)
* fix(hooks): correct `SubagentStop` event field names in ralph-loop (#152)
* fix(opencode): make dispatch wait for child tasks (#147)
* fix(init): strip npm scope prefix from monorepo package directory names
* fix(init): rename "empty templates" to "from scratch" in template picker
* fix(scripts): preserve submodule status prefix in `start.py`
## Install & upgrade
```bash theme={null}
# Fresh install
npm install -g @mindfoldhq/trellis@latest --registry=https://registry.npmjs.org
# Upgrade (existing trellis install)
trellis update
```
Upgrading from 0.3.x automatically handles the 36 merged command-file deletions — with hash verification, **your local edits are preserved**; only files that haven't been modified are removed.
***
* Full changelog: [https://docs.trytrellis.app/changelog/v0.4.0](https://docs.trytrellis.app/changelog/v0.4.0)
* Repo: [https://github.com/mindfold-ai/Trellis](https://github.com/mindfold-ai/Trellis)
* Docs: [https://docs.trytrellis.app](https://docs.trytrellis.app)
# v0.4.0-beta.1
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.1
2026-03-12
Monorepo support, unified commands, and Python scripts refactoring.
<Warning>This is a **breaking change** release. Run `trellis update` to migrate. Customized command files will be preserved — only unmodified files are auto-deleted.</Warning>
## Enhancements
* **Monorepo auto-detection** — `trellis init` detects pnpm/npm/Cargo/Go/uv workspaces and git submodules, generates per-package spec directories and `config.yaml` with packages list
* **Unified commands** — `before-backend-dev` + `before-frontend-dev` merged into `before-dev`; `check-backend` + `check-frontend` merged into `check` (all 9 platforms)
* **Safe file delete** — New migration type that auto-removes deprecated files only when content hash matches (user-modified files are never deleted)
* **Protected paths** — `PROTECTED_PATHS` prevents migrations from touching user data (`.trellis/workspace`, `spec`, `tasks`)
* **Update skip paths** — `config.yaml` `update.skip` to exclude paths from safe-file-delete and template updates
* **Worktree submodule awareness** — Worktree agents auto-initialize git submodules for task packages
* **Monorepo script support** — Session-start hook supports `spec_scope` filtering; `task.py` and `add_session.py` support `--package`
* **Migration task auto-creation** — Breaking change updates automatically create a `.trellis/tasks/` migration task with guide and AI instructions
## Bug Fixes
* **Update: protected path compat** — Allow rename/rename-dir migrations to target protected paths (0.2.0 compat)
* **Update: config parse warning** — Warn when `config.yaml` parse fails instead of silently disabling `update.skip`
* **Scripts: submodule status** — Preserve git submodule status prefix character (`.strip` → `.rstrip`)
## Internal
* **Python scripts refactoring** — Shared `io`/`log`/`git` modules, `TaskInfo` TypedDict type safety, god modules (`task.py`, `git_context.py`, `status.py`) split into focused modules. All entry paths unchanged.
## Migration
Run `trellis update` to sync new unified commands. Old `before-backend-dev`, `before-frontend-dev`, `check-backend`, `check-frontend` files will be auto-deleted if unmodified. If you customized these files, merge your changes into the new `before-dev` / `check` files and delete the old ones manually.
# v0.4.0-beta.10
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.10
2026-04-09
Ralph Loop field name fix (P0), migration task assignee parsing fix, and task lifecycle documentation.
## Bug Fixes
* **Ralph Loop field names fix (#152)**: The SubagentStop hook was reading non-existent fields (`subagent_type`, `agent_output`, `prompt`) instead of the actual Claude Code event schema (`agent_type`, `last_assistant_message`), so Ralph Loop was silently inert for **all users since release**. Check/implement/debug subagents will now actually trigger loop control as documented. Thanks to @suyuan2022 for the catch.
* **Migration task assignee parsing (#153)**: When `trellis update --migrate` created the auto-generated migration task, it read `.trellis/.developer` as a plain string and embedded the entire `name=...\ninitialized_at=...` file contents as the `assignee` field. The timestamp line then leaked into `session-start.py` rendering, breaking the ACTIVE TASKS layout. Now parses the `name=` line correctly. Thanks to @suyuan2022 for the fix.
## Documentation
* **Task lifecycle commands**: `workflow.md` now documents `task.py start <name>` and `task.py finish` — previously both subcommands were wired in argparse but completely unmentioned in the workflow guide, so AI agents never knew to call them and `## CURRENT TASK` was perpetually `(none)`. Task Development Flow expanded from 5 to 7 explicit steps with Start (step 2) and Finish (step 7), plus a new "Current task mechanism" explainer tying `.current-task` to SessionStart hook injection.
## Notes
* Run `trellis update` to sync all changes
* **Behavior change**: Ralph Loop will now actually fire for check/implement/debug subagents. If you were unknowingly relying on the previously-silent behavior, watch for new loop activity after upgrading.
# v0.4.0-beta.2
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.2
2026-03-12
Hotfix for scoped npm package names in monorepo init.
## Bug Fixes
* **Scoped package name fix** — `trellis init` on monorepos with scoped npm packages (e.g. `@zhubao/desktop`) no longer creates nested `@scope/` directories in `.trellis/spec/`. The scope prefix is now stripped, so `@zhubao/desktop` becomes `desktop` in all filesystem paths and `config.yaml` keys. Display-only usages retain the full scoped name.
## Migration
If you previously ran `trellis init` on a monorepo with scoped packages, you may need to:
1. Rename `.trellis/spec/@scope/name/` to `.trellis/spec/name/`
2. Update the package keys in `.trellis/config.yaml` (e.g. `@scope/name:` → `name:`)
# v0.4.0-beta.3
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.3
2026-03-13
Fix `trellis update` skipping unregistered Python scripts, plus v0.3.10 fixes merged.
## Bug Fixes
* **Update script sync** — `trellis update` now uses `getAllScripts()` as the single source of truth for Python script files. Previously, 11 scripts (9 in `common/` and 2 in `multi_agent/`) were silently skipped because they weren't registered in `collectTemplateFiles()`'s hand-maintained list.
## Merged from v0.3.10
* **HTTPS registry URLs** — `trellis init --registry` now accepts HTTPS URLs (e.g. `https://github.com/user/repo`) by auto-converting them to giget-style format. (#87)
* **Record-session AI compatibility** — Updated record-session command wording so AI models (especially GPT) no longer refuse to run metadata scripts. (#88)
# v0.4.0-beta.4
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.4
2026-03-16
Git repo context for monorepo packages + improved init-context hints.
## Enhancements
* **Git repo context**: Packages with `git: true` in config.yaml now show branch, working directory status, and recent commits in session context
* **init-context hints**: After initializing context, the output now lists auto-injected defaults and all available spec files for the AI to choose from
* **publish-skill command**: New `/trellis:publish-skill` slash command
* **cc-codex-spec-bootstrap**: New marketplace skill for Claude Code + Codex parallel spec bootstrapping
## Bug Fixes
* Use `_is_true_config_value` for `isGitRepo` consistency (case-insensitive matching)
## Notes
* Run `trellis update` to sync
* No migration required
# v0.4.0-beta.5
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.5
2026-03-16
UX improvements: renamed template picker label + iFlow CLI agent fix.
## Enhancements
* **Template picker UX**: Renamed "empty templates" to "from scratch" in `trellis init` template selection for clearer messaging
## Bug Fixes
* **iFlow CLI agent**: Corrected CLI agent invocation syntax in `cli_adapter.py` (#95)
## Notes
* Run `trellis update` to sync
* No migration required
# v0.4.0-beta.6
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.6
2026-03-22
CodeBuddy platform support, OpenCode plugin fix, improved skill descriptions.
## Enhancements
* **CodeBuddy platform support**: Added [CodeBuddy](https://copilot.tencent.com/) (Tencent Cloud) as the 11th supported platform. Uses nested slash commands at `.codebuddy/commands/trellis/<name>.md` (e.g., `/trellis:start`). Includes type registry, configurator, 12 command templates, CLI flag (`--codebuddy`), and Python `cli_adapter` integration
* **Improved skill descriptions**: Enhanced YAML frontmatter descriptions across Codex, Kiro, and Qoder skill templates for better AI triggering accuracy. Descriptions now include specific use cases and trigger conditions
## Bug Fixes
* **OpenCode plugin directory**: Fixed plugin directory name from `plugin/` to `plugins/` in the OpenCode configurator (#103)
## Notes
* Run `trellis update` to sync
* No migration required
# v0.4.0-beta.7
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.7
2026-03-22
Fix Pyright/Pylance import warnings in session-start hooks.
## Bug Fixes
* **IDE import warnings**: Suppressed Pyright/Pylance `reportMissingImports` false positives in `session-start.py` hooks. The `common.config` and `common.paths` imports are resolved at runtime via `sys.path` but IDE static analyzers cannot follow dynamic paths. Added `# type: ignore[import-not-found]` annotations
## Notes
* Run `trellis update` to sync
* No migration required
# v0.4.0-beta.8
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.8
2026-03-24
Decouple `.agents/skills/` as shared Agent Skills layer, add full `.codex/` directory support with hooks, platform-specific skills, and custom agents.
## Enhancements
* **Shared Agent Skills layer**: `.agents/skills/` is now a shared directory following the [agentskills.io](https://agentskills.io) open standard. It is no longer bound to the Codex platform — any universal agent CLI (Codex, Kimi CLI, Amp, Cline, etc.) can read these skills
* **Codex `.codex/` directory**: New platform-specific directory structure:
* `.codex/config.toml` — project-scoped Codex config
* `.codex/agents/` — custom Codex agents (implement, research, check)
* `.codex/skills/` — Codex-specific skills (e.g. `parallel` with `--platform codex`)
* `.codex/hooks/session-start.py` + `hooks.json` — SessionStart hook injecting full Trellis context (workflow, guidelines, task status)
* **Codex SessionStart hook**: Automatically injects Trellis workflow, guidelines, and task context into Codex sessions. Requires `codex_hooks = true` under `[features]` in `~/.codex/config.toml` (experimental Codex feature)
* **Branch context in sessions**: Session journal records now include git branch information (#108)
## Bug Fixes
* **iFlow CLI adapter**: Reverted incorrect `--agent` flag change from PR #112. iFlow uses `$agent_name` prefix format, not `--agent`
* **Codex agent TOML format**: Fixed to use correct fields (`name`, `description`, `developer_instructions`, `sandbox_mode`) instead of invalid `[sandbox_read_only]` + `prompt` format
## Migration
* **Automatic**: Old Codex users (`.agents/skills/` without `.codex/`) are auto-detected and upgraded on `trellis update`
* **safe-file-delete**: `.agents/skills/parallel/SKILL.md` (moved to `.codex/skills/`), old `trellis-*.toml` agent files (renamed)
* Run `trellis update` to apply all changes
## Breaking Changes
* **Platform detection**: `.agents/skills/` alone no longer detects as Codex. `.codex/` directory is required
* **configDir**: Codex `configDir` changed from `.agents/skills` to `.codex`
## Notes
* Codex hooks require `codex_hooks = true` under `[features]` in `~/.codex/config.toml`
* Codex hooks `suppressOutput` is not yet functional (Codex experimental limitation — context is still printed in TUI)
* `parallel` skill moved from shared `.agents/skills/` to Codex-specific `.codex/skills/` since it contains `--platform codex`
# v0.4.0-beta.9
Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.9
2026-04-07
Copilot & Windsurf platform support, self-hosted registry, OpenCode dispatch fix, and 6-phase task lifecycle.
## Enhancements
* **GitHub Copilot support**: New platform with standalone prompt templates and hook tracking. Run `trellis init --platform copilot` to set up
* **Windsurf support**: Full workflow support for Windsurf IDE — rules, workflows (brainstorm, start, before-dev, finish-work, update-spec, record-session), and AI configuration
* **Self-hosted registry**: Support self-hosted GitLab/GitHub Enterprise URLs in `--registry` flag (#131). Template fetcher now correctly parses GHE/GitLab raw file URLs
* **StatusLine integration**: Claude Code statusLine now shows Trellis task context (#127)
* **CodeBuddy & Codex improvements**: New CodeBuddy platform support, Codex agent and docs fixes (#128, #116)
* **6-phase task lifecycle**: Task `next_action` template updated from 4-phase pipeline to full lifecycle: brainstorm → research → implement → check → update-spec → record-session
* **Marketplace as submodule**: Marketplace migrated to standalone repo, linked as git submodule (#117)
## Bug Fixes
* **OpenCode dispatch sync**: Dispatch now waits for child tasks synchronously instead of background polling, preventing premature phase advancement (#147)
* **Cross-platform path normalization**: `.current-task` path references now normalized across platforms (#130)
* **Codex Windows fix**: `{{PYTHON_CMD}}` placeholder in `hooks.json` now correctly resolved on Windows (#132)
* **Session recording**: `add_session.py` git-add error handling improved, Python 3.10 version check added
* **Template fetcher**: Self-hosted GitLab/GHE URL parsing fixed in `template-fetcher.ts`
## Notes
* Run `trellis update` to sync all changes
* New platforms: `trellis init --platform copilot` or `--platform windsurf`
# v0.4.0-rc.0
Source: https://docs.trytrellis.app/changelog/v0.4.0-rc.0
2026-04-14
**v0.4.0 feature freeze.** First release candidate. No new features before stable — only bug fixes accepted. Please test and report regressions.
## SessionStart size fix (#154)
Vanilla `additionalContext` reduced from **\~29 KB to \~7 KB**, comfortably under Claude Code's \~20 KB truncation threshold. Task state (ACTIVE TASKS, CURRENT TASK) was being silently lost on most non-trivial projects. Thanks to @21nak for the thorough writeup, measurements, and both PRs.
* **#161 workflow\.md ToC**: Replace full `workflow.md` injection (\~12 KB) with a compact section index that lists each `##` heading. Applied to all 5 platforms including copilot. AI reads the full file on demand.
* **#160 remove start.md injection**: The `<instructions>` block pre-injected `start.md` (\~11 KB), but slash commands expand on demand anyway — this was duplicate work. Now removed from 4 platforms; copilot never had it.
* **Follow-up cleanup**: `<ready>` text no longer references nonexistent "Steps 1-3 / Step 4" after `<instructions>` was removed. Orphaned `claude_dir` / `codex_dir` / `iflow_dir` variables removed.
## OpenCode plugin v1 refactor (#159)
Update OpenCode templates to the v1 plugin API (`export default { id, server }`). Fixes non-persistent context injection: `experimental.chat.messages.transform` didn't write back to history, so injected Trellis context was lost on session reopen. Now routes through `chat.message` hook with SDK history-based dedupe via `metadata.trellis.sessionStart` markers. `task` tool prompt mutation now in-place (`args.prompt = ...`) because the runtime holds a local reference to the args object. Thanks to @Adamcf123.
## Windows encoding fix (#163)
`statusline.py` crashed on Windows with `UnicodeEncodeError: 'gbk' codec can't encode` when rendering the `·` separator in the info line. Both the live hook and the claude template now wrap `stdout`/`stderr` in UTF-8 on Windows. Thanks to @xiangagou163.
## Features
* **`feat(init)`: re-init fast path (#157)** — When `.trellis/` already exists, `trellis init` offers a streamlined flow instead of the full interactive setup:
* `trellis init --codex` → configure only Codex, skip everything else
* `trellis init -u name` → set up developer identity (new device sync)
* `trellis init` (bare) → menu: add platform / add developer / full re-init
* `--force` / `--skip-existing` → bypass fast path, run full init
## Bug Fixes
* **`fix(init)`: skip bootstrap task creation on re-init** — re-running `trellis init` no longer creates duplicate bootstrap tasks
## Documentation
* **`docs(spec)`: SessionStart size constraint** — platform-integration spec now documents the \~20 KB `additionalContext` truncation threshold with a size budget table, preventing future hooks from silently exceeding the limit
## Notes
* RC install: `npm install -g @mindfoldhq/trellis@rc`
* Please run `trellis update` on an existing project and report any regressions
* Session-start hooks have been significantly restructured — if you customized them locally, re-check after update
* Windows users with statusline garbling should also update
# v0.4.0-rc.1
Source: https://docs.trytrellis.app/changelog/v0.4.0-rc.1
2026-04-14
**Late-RC additive feature.** Two pure-additive changes — no migrations, no behavior changes for existing platforms. Safe to update mid-RC.
## Factory Droid platform support
[Factory Droid](https://factory.ai) is now a first-class Trellis platform. Cursor-level scope: commands-only, no hooks/agents.
* `trellis init --droid` writes 12 Trellis commands to `.factory/commands/trellis/<name>.md`
* Each file ships with optional YAML frontmatter (`description: ...`) so Droid's `/commands` autocomplete shows a one-line summary
* Layout uses nested `trellis/` subdirectory like Claude Code (Droid's docs claim nesting is unsupported but the actual binary picks them up — verified before release)
* `cli_adapter.py` fully integrates Droid so Trellis Python scripts (status, archive, journals) detect `.factory/` projects correctly
* Multi-agent CLI `run`/`resume` currently raises `ValueError` ("not yet integrated with Trellis multi-agent") — same pattern as Copilot/Windsurf. Can be extended in a future release if there's demand.
## Codex option hints at `.agents/skills/` shared layer
The interactive `trellis init` checkbox for Codex now reads:
```
Codex (also writes .agents/skills/ — read by Cursor, Gemini CLI, GitHub Copilot, Amp, Kimi Code)
```
Trellis only writes `.agents/skills/` when Codex is enabled, but that directory is read by many other clients via the [agentskills.io](https://agentskills.io) open standard. Surfacing this in the prompt makes the spillover benefit visible — users picking Codex understand it isn't Codex-specific.
Verified against each client's official docs:
* [Cursor Skills](https://cursor.com/docs/skills) — explicit `.agents/skills/` entry
* [Gemini CLI Skills](https://geminicli.com/docs/cli/skills) — `.agents/skills/` is the cross-client "alias", takes precedence over `.gemini/skills/`
* [VS Code Copilot Agent Skills](https://code.visualstudio.com/docs/copilot/customization/agent-skills) — `.agents/skills/` listed alongside `.github/skills/` and `.claude/skills/`
* [Amp Owner's Manual](https://ampcode.com/manual) — `.agents/skills/` is the only project-level skill location
* [Kimi Code CLI Skills](https://moonshotai.github.io/kimi-cli/en/customization/skills.html) — discovered from `.agents/skills/` (or `.kimi/skills/`, `.claude/skills/`)
Note: Claude Code is intentionally omitted. Its [official skills docs](https://code.claude.com/docs/en/skills) only list `.claude/skills/` and `~/.claude/skills/` — Claude Code does NOT read `.agents/skills/`, contrary to several third-party blog claims.
## Notes
* Pure-additive update. RC users can `trellis update` safely — no file renames, no behavior changes, no migrations.
* Run `trellis init --droid` to try Factory Droid support.
* RC install: `npm install -g @mindfoldhq/trellis@rc`
# v0.5.0-beta.0
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.0
2026-04-20
**Skill-first architecture + hooks for everyone.** The first preview of 0.5 reshapes two things at once: how templates are authored (single source, N outputs) and how AI stays on-workflow (per-turn hook, not once-per-session). Plus the largest cleanup since 0.4.0 — iFlow, multi-agent pipeline, Ralph Loop, dispatch/debug/plan agents, and six retired commands are all gone.
## Skill-first template architecture
Commands and skills now live under `packages/cli/src/templates/common/` as a single source of truth (3 commands + 5 skills). All 13 platforms resolve from `common/` through per-platform adapters. Eliminates the prior N-copies-of-same-content drift that caused stale commands to linger on some platforms but not others.
Two reusable helpers landed alongside:
* **`createTemplateReader()`** (in `template-utils.ts`) — factory used by 6 platform template modules, replacing boilerplate `import { readFileSync } from "fs"` scaffolding. Uses `fileURLToPath` correctly so paths with spaces / on Windows resolve.
* **`writeSharedHooks()` + `writeAgents()` + `writeSkills()`** (in `configurators/shared.ts`) — three-line calls that configurators use to emit their hook / agent / skill set, instead of bespoke file-copy loops.
## Hooks + agents for 7 new platforms
Qoder, CodeBuddy, Factory Droid, Cursor, Gemini CLI, Kiro, and GitHub Copilot go from commands-only to fully agent-capable. Each ships:
* Sub-agent definitions (implement / check / research) in the platform's native format
* Hook configuration wired via `shared-hooks/` Python scripts (session-start, inject-subagent-context, statusline) — single implementation, cross-platform output adapters
Claude Code hooks are also migrated to the shared-hooks set, deleting a 1,435-line platform-specific implementation whose dead fallback code (`AGENT_DEBUG`, `spec.jsonl`/`research.jsonl` reads, hardcoded `check-cross-layer.md` references) had accumulated across releases.
## Sub-agent context injection: class-1 hook vs class-2 pull-based
Codex, Copilot, Gemini, and Qoder (class-2) can't reliably receive hook-modified sub-agent prompts:
* Codex `PreToolUse` only fires for Bash; `CollabAgentSpawn` hook unimplemented (#15486)
* Copilot `preToolUse` silently ignored on sub-agents (#2392 / #2540)
* Gemini's `BeforeTool` can't see the caller's context (#18128)
* Qoder has no Task tool + context isolation
These 4 platforms now use a **pull-based prelude**: sub-agent definitions include an up-front instruction block that makes the sub-agent Read `.current-task` + `prd.md` + `implement.jsonl`/`check.jsonl` itself on first turn. Class-1 platforms (Claude / Cursor / OpenCode / Kiro / CodeBuddy / Droid) continue with hook-based push injection. Both paths live in shared infrastructure (`applyPullBasedPreludeMarkdown` / `applyPullBasedPreludeToml`) so future platforms pick one and it works.
## Workflow enforcement v2: per-turn breadcrumb hook
New `inject-workflow-state.py` shared hook fires on every user prompt (UserPromptSubmit equivalent on 8 platforms; `chat.message` on OpenCode Bun plugin). It injects a \~200-byte `<workflow-state>` block nudging AI toward the next workflow step based on the active task's `status`.
Breadcrumb content is pulled from `workflow.md` `[workflow-state:STATUS]...[/workflow-state:STATUS]` blocks — users who fork the workflow edit **one markdown file**, not the hook Python. Covers four states: `no_task` / `planning` / `in_progress` / `completed`. Custom hyphenated statuses (`in-review`, `blocked-by-team`) are recognized via the STATUS regex `[A-Za-z0-9_-]+`. Unknown statuses emit a generic fallback instead of silent-exiting — the hook never leaves a conversation without guidance.
Three-tier fallback (workflow\.md missing → partial tag → unknown status) so the hook never breaks.
Kiro is the one platform downgraded: its `agentSpawn` hook is per-sub-agent only, and there's no upstream equivalent for main-session per-turn injection. Sub-agent context injection still works; per-turn breadcrumb is awaiting upstream support.
## SessionStart payload restructure
The SessionStart `<workflow>` block grew from 2.7 KB to 9.5 KB by inlining Phase 1/2/3 step bodies — AI now has step-level how-to up front instead of lazy-loading via `get_context.py --mode phase --step X.Y`. Funded by shrinking `<guidelines>` from 10.9 KB to 4.6 KB: the cross-package `guides/index.md` stays inlined, but other `spec/<pkg>/<layer>/index.md` files are listed as paths only. Rationale: sub-agents get their specific specs via jsonl injection, and when the main agent needs details it reads on demand.
Total session-start payload: 16.7 KB — under Claude Code's \~20 KB `additionalContext` truncation threshold.
`workflow.md` itself slimmed 17 KB → 14 KB: English-only (was bilingual), removed `What is Trellis` intro + File Structure tree + redundant Best Practices section, task.py command table expanded from 5 → 16 subcommands per PR #169's grouping (lifecycle / context / metadata / hierarchy / PR) with a `--help` pointer for future-proofing.
## Legacy cleanup (126-entry safe-file-delete migration)
This release removes four categories of primitives whose replacement is now the default:
* **iFlow platform** — CLI unmaintained; entire `.iflow/` tree + template source removed
* **Multi-agent pipeline** (`.trellis/scripts/multi_agent/` + `worktree.yaml`) — all major CLIs now ship their own worktree support; Trellis doesn't need to reimplement
* **Ralph Loop hook** (`ralph-loop.py`) — SubagentStop + exit-code-2 enforcement not portable across platforms; check agent's self-fix loop is sufficient
* **Six commands + three sub-agents** — `parallel` (superseded by native worktrees), `onboard` / `create-command` / `integrate-skill` (low usage), `check-cross-layer` (merged into `check`), `record-session` (subsumed by `/finish-work`); `dispatch` / `debug` / `plan` agents (replaced by skill routing)
All cleanup is **hash-verified**: if you modified any of these files locally they stay put with a warning; only pristine Trellis-written copies get removed. 126 safe-file-delete entries cover the full surface across all 13 platforms (with `allowed_hashes` pulled from historical git versions, so users on any past 0.3.x / 0.4.x version get a clean migration).
## Command → skill migration (80 new manifest entries)
The 5 skills that users no longer invoke by hand (`before-dev` / `brainstorm` / `break-loop` / `check` / `update-spec`) now live under `<platform>/skills/trellis-<name>/SKILL.md` on every platform. Without migration, a user upgrading from 0.4.x would end up with both the old command file and the new skill file side-by-side. The manifest closes this cleanly:
* **65 rename** entries (13 platforms × 5 commands) — preserves user customizations via move + subsequent template-write prompt (not plain delete)
* **3 rename** entries for `finish-work` on skill-only platforms (`.kiro` / `.qoder` / `.agents` shared layer) — gains the `trellis-` prefix too
* **10 safe-file-delete** for the old `start` command across agent-capable and skill-only platforms — session-start hook replaces the command's role
* **2 safe-file-delete** for the legacy `improve-ut` skill (`.agent/workflows/` + `.agents/skills/`)
`MigrationItem` gained a new `reason?` field — version-specific context (e.g. "Trellis 0.4.0 skipped hashing this path, so pristine copies show as modified") is authored inline in the manifest and rendered in the confirm prompt. No more hardcoded version-hints rotting in `update.ts`.
## `--migrate` is now required for breaking releases
Running `trellis update` against a project whose installed version spans a manifest flagged `breaking: true` + `recommendMigrate: true` **exits 1** with a clear error telling the user to add `--migrate`. Previously `update` would silently skip the rename/delete entries and still bump the `.version` stamp, leaving the project half-migrated (stale old paths next to new templates). `--dry-run` bypasses the gate so users can still preview.
## Confirm-prompt redesign
When a migration file trips the modified-hash check, the interactive prompt now shows:
1. **What** the migration does (from the manifest `description`)
2. **Why prompted** — per-entry `reason` from the manifest, or a generic fallback
3. Recommendation on each option (Backup / Rename / Skip) including the consequence of skipping (stale path persists to future updates)
Default choice is now `backup-rename` instead of `skip` — pressing Enter never destroys user edits or leaves orphan files.
## Bug fixes
* **Backup no longer snapshots platform worktrees.** `createFullBackup` excludes any `/worktrees/` or `/worktree/` path, so Claude Code's `.claude/worktrees/`, Cursor's `.cursor/worktrees/`, and Gemini CLI's `.gemini/worktrees/` don't get duplicated on every `trellis update` (one backup could otherwise bloat to 100s of MB once worktrees are in use).
* **`copy-templates` build step leaks stale files.** Added `clean` to the build chain (`clean && tsc && copy-templates`) so templates deleted from `src/` stop lingering in `dist/` and shipping to npm. Without this fix, safe-file-deletes fought re-writes from the stale dist templates in a loop.
## Other notable changes
* `task.py create` stops writing legacy `current_phase` / `next_action` fields. FP-analysis outcome: workflow\.md's Phase N.M is documentation layering, not runtime state — `task.json.status` is the single source of task-level state.
* `inject-subagent-context.py`'s `update_current_phase()` function deleted — it was re-writing the legacy `current_phase` field on every Task spawn, silently undoing the deprecation.
* Codex hooks integration: `configureCodex` now auto-writes shared-hooks (was skipping them); stderr warning on `trellis init --codex` about `features.codex_hooks = true` requirement in user's `~/.codex/config.toml`.
* `get_context.py --mode phase` (no `--step`) returns Phase Index + Phase 1/2/3 bodies (was Phase Index only) — agent-less platforms (Kilo / Antigravity / Windsurf) running `/start` manually get the same content as hook-based platforms.
* Hook-path CWD robustness (partial): `inject-workflow-state.py` walks up from CWD to find `.trellis/`, fixing subdirectory / submodule CWD drift for this hook. Full coverage across all hooks is a post-beta task.
## Spec docs updated
* **platform-integration.md** — new sections: Workflow State Injection (per-turn breadcrumb), Subagent Context Injection: Hook-based vs Pull-based, Guidelines: Paths-only vs Inline, Per-Turn Hook design principle (no silent-exit on "nothing to say")
* **quality-guidelines.md** — new section: Schema Deprecation: Audit ALL Writers, Not Just the Creator (from a Codex cross-review finding where `cmd_create` dropped a field but a hook kept re-writing it)
* **workflow\.md** — full English translation; slim structure; task.py 16-subcommand reference table
* **directory-structure.md** + **script-conventions.md** — multi-agent references removed
## Tests
595 tests passing, lint + typecheck clean. 41 new tests since the first draft of this changelog: workflow-state per-turn breadcrumb (7 cases), Phase Index expansion, paths-only guidelines, `update_current_phase` deletion regression, UserPromptSubmit platform wiring invariants, breaking-change gate (3 cases: block / dry-run bypass / `--migrate` pass), 0.5.0-beta.0 manifest shape (65-entry coverage, per-platform path invariant, breaking+recommendMigrate flags), worktree backup exclusion (12 cases across platform conventions + user data + edge cases).
## Deferred to follow-up beta / rc
* Kiro `agentSpawn` hook output-format validation in real environment
* Cursor / CodeBuddy / Droid sub-agent hook injection real-env testing
* Full hook-path CWD-robustness across all hooks (Windows cmd / PowerShell)
* Parent-child Trellis config for submodule / micro-service repos (issue #172)
## Migration
Run `trellis update --migrate` (the `--migrate` flag is **required** this release — 68 rename entries don't auto-execute without it, and the new gate will exit 1 telling you to add it). Then the 138-entry safe-file-delete runs. User-modified files are preserved with warnings; only pristine Trellis-written files get cleaned up. Use `trellis update --migrate --dry-run` first if you want to preview.
**`/trellis:record-session` users:** this command is removed. Its single job (writing a session journal via `add_session.py`) is now Step 3 of `/trellis:finish-work`, which also covers Quality Gate and Commit reminders. Replace any aliases or scripts that invoke `record-session` with `finish-work`.
**Codex users:** enable `features.codex_hooks = true` in `~/.codex/config.toml` to receive SessionStart + UserPromptSubmit breadcrumb injection. Without this flag `hooks.json` is silently ignored by Codex.
**iFlow users:** the `.iflow/` directory will be removed. Copy it out first if you want to keep it.
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.1
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.1
2026-04-20
**First published 0.5 beta.** Code is identical to the `0.5.0-beta.0` dev cut. The bump from `beta.0` → `beta.1` happens automatically inside `pnpm release:beta` (via `pnpm version prerelease --preid beta`), so `beta.0` was never published to npm — `beta.1` is the first tagged release of the skill-first architecture.
All the heavy lifting (command→skill for 5 skills, 138-entry safe-file-delete for legacy commands + iFlow + multi-agent + Ralph Loop, breaking-change `--migrate` gate, per-entry `reason` field in the confirm prompt, worktree backup exclusion, build `clean` step) is defined in the `0.5.0-beta.0` manifest and applies when upgrading from 0.4.x.
See the [`v0.5.0-beta.0` changelog](/changelog/v0.5.0-beta.0) for the full migration story.
## Migration
If upgrading from 0.4.x: run `trellis update --migrate`. The breaking-change gate requires the flag explicitly — without it, `trellis update` exits 1 with guidance.
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.10
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.10
2026-04-22
Hotfix: three bugs in `trellis update --migrate` / `init-context`. Not breaking; no `--migrate` required.
## Bug Fixes
### 1. `trellis-` prefix missing from codex / kiro skill paths
`get_trellis_command_path` in `cli_adapter.py` returned bare-name paths, ignoring the prefix 0.5.0-beta.0 introduced across 60+ skill dirs. `check.jsonl` generated by `task.py init-context` on codex / kiro projects pointed at non-existent files.
```python theme={null}
elif self.platform == "codex":
return f".agents/skills/trellis-{name}/SKILL.md"
elif self.platform == "kiro":
return f".kiro/skills/trellis-{name}/SKILL.md"
```
### 2. `.agents/skills/` blocked Kiro / Antigravity / Windsurf detection
`.agents/skills/` is a shared cross-platform layer (Codex writes, Amp / Cline / Kimi Code / Warp consume via agentskills.io). It was listed in `_ALL_PLATFORM_CONFIG_DIRS`, blocking every detection branch whose exclude set didn't name it. `detect_platform` fell through to `claude`.
* Removed `".agents"` from `_ALL_PLATFORM_CONFIG_DIRS`.
* Added a guarded codex fallback at the end of `detect_platform`:
```python theme={null}
agents_skills = project_root / ".agents" / "skills"
if agents_skills.is_dir() and not _has_other_platform_dir(project_root, set()):
for entry in agents_skills.iterdir():
if entry.is_dir() and entry.name.startswith("trellis-"):
return "codex"
```
### 3. `init-context` now accepts `--platform`
Skills / commands are rendered per-platform; the invoking platform is known at render time. Threaded it end-to-end instead of re-detecting from the filesystem.
* `{{CLI_FLAG}}` placeholder added to `resolvePlaceholders` — resolves to the platform's `cliFlag` at configure time.
* `TemplateContext` gained `cliFlag: CliFlag`, asserted against `AIToolConfig.cliFlag` by a registry invariant test.
* `task.py init-context` gained `--platform`, threaded through `cmd_init_context` → `get_check_context(repo_root, platform=...)` → `get_cli_adapter(platform)`.
* `codex/skills/start/SKILL.md` and `copilot/prompts/start.prompt.md` now invoke:
```bash theme={null}
python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type> --platform {{CLI_FLAG}}
```
Auto-detect remains as fallback when `--platform` is omitted (CLI-direct invocation, `TRELLIS_PLATFORM` env var).
### 4. `migrationGuide` back-fill for 0.5.0-beta.0 and 0.5.0-beta.5
`update.ts` builds the migrate-to-`<version>` task PRD by concatenating every `migrationGuide` between `fromVersion` and `toVersion`. Both breaking 0.5.x releases shipped without the field; users upgrading from 0.4.x saw a PRD containing only 0.3/0.4 historical guides, with nothing about the actual 0.5 breaking changes.
| Manifest | Back-filled content |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `0.5.0-beta.0.json` | 0.4→0.5 narrative: skill renames, retired commands, Multi-Agent Pipeline removal, iFlow drop, `task.json` schema cleanup |
| `0.5.0-beta.5.json` | Sub-agent rename: `implement` / `check` / `research` → `trellis-*` |
`packages/cli/scripts/create-manifest.js` now rejects manifests where `breaking && recommendMigrate && !migrationGuide`. `.trellis/spec/cli/backend/migrations.md` documents the rule.
End-to-end paths verified:
| From → To | Guides included |
| ------------------------------ | ---------------------------------------------- |
| `0.4.0 → 0.5.0-beta.10` | `0.5.0-beta.0`, `0.5.0-beta.5` |
| `0.3.9 → 0.5.0-beta.10` | `0.4.0-beta.1`, `0.5.0-beta.0`, `0.5.0-beta.5` |
| `0.5.0-beta.4 → 0.5.0-beta.10` | `0.5.0-beta.5` |
### 5. `release:beta` / `release:rc` / `release:promote` check docs-site changelog
`packages/cli/scripts/check-docs-changelog.js` runs before version bump. If `docs-site/changelog/v<target>.mdx`, `docs-site/zh/changelog/v<target>.mdx`, or their `docs.json` page entries are missing, the script exits 1. Added after beta.10 itself shipped without a docs-site changelog for this exact reason.
## Upgrade
```bash theme={null}
trellis update
```
Not breaking.
* **Upgraded from beta.9 and already ran `trellis update --migrate`**: `check.jsonl` in tasks created during that run still points at the old bare-name paths. Re-run `task.py init-context <task-dir> <type> --platform <platform>` on each, or recreate the task.
* **On 0.4.x, never migrated to 0.5 yet**: the migration task PRD now contains the real 0.4→0.5 guide.
* **Codex users with fresh clones missing `.codex/`**: `detect_platform` now returns `codex` instead of `claude` when `.agents/skills/trellis-*` is the only platform signal present.
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.11
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.11
2026-04-22
Hotfix: `SessionStart` hook crashed at module-import time on PEP 604 union annotations when the AI CLI host spawned `python3` as macOS system 3.9 — even though the user's shell `python3` was 3.11. Not breaking; no `--migrate` required. Also relaxes the declared Python floor from 3.10 to 3.9 so the macOS system `python3` is supported out of the box.
## Bug Fixes
### Hook PEP 604 annotation crash
`packages/cli/src/templates/shared-hooks/session-start.py` and `inject-subagent-context.py` did not declare `from __future__ import annotations`, so PEP 604 union annotations (`str | None`, `dict | None`) were evaluated eagerly when Python processed the `def` statement. On any `python3` \< 3.10 the module aborted with:
```
TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'
```
Observed in the wild on macOS: the user's shell `python3 --version` reported 3.11.12 (homebrew), but the AI CLI host spawned the hook subprocess with a minimal PATH that did not include `/opt/homebrew/bin`. `env python3` resolved to `/usr/bin/python3` → macOS system 3.9, which does not implement PEP 604 at expression-eval time.
`packages/cli/src/templates/shared-hooks/statusline.py` plus the `copilot/codex` copies of `session-start.py` already carried the future import; the two canonical `shared-hooks/*.py` files were the outliers.
**Fix** — add one line immediately after the module docstring:
```python theme={null}
"""Session Start Hook - Inject structured context"""
from __future__ import annotations # added
```
| File | Change |
| -------------------------------------------------------------------- | ------------------------------------- |
| `packages/cli/src/templates/shared-hooks/session-start.py` | `+from __future__ import annotations` |
| `packages/cli/src/templates/shared-hooks/inject-subagent-context.py` | `+from __future__ import annotations` |
`from __future__ import annotations` (PEP 563) makes all annotations lazy strings, so PEP 604 syntax in annotations is safe on Python 3.7+. Runtime union expressions — e.g. `isinstance(x, int | str)` — are **not** rescued and still require 3.10+; neither hook uses them.
## Improvements
### Python floor relaxed from 3.10 to 3.9
`packages/cli/src/commands/init.ts` now sets `MIN_MINOR = 9`. Rationale: macOS Ventura / Sonoma / Sequoia all ship `/usr/bin/python3` at 3.9.6, and Trellis's distributed templates (both `shared-hooks/*.py` and `trellis/scripts/**/*.py`) were empirically verified against CPython 3.8–3.13 via a full package-import matrix — 30/30 files load cleanly on every tested version.
| Change | Location |
| --------------------------------------------- | ------------------------------------------------------------------------ |
| `MIN_MINOR = 10` → `9` | `packages/cli/src/commands/init.ts` |
| Warning text `Python ≥ 3.10` → `Python ≥ 3.9` | `packages/cli/src/commands/init.ts` (2 occurrences) |
| `Python ≥ 3.10` → `Python ≥ 3.9` | `README.md` |
| Quickstart Prerequisites table | `docs-site/quickstart.mdx` + `docs-site/zh/quickstart.mdx` (new section) |
No CI matrix change yet; the empirical test harness lives in `/tmp/trellis-py-compat/` during development (not committed). Python 3.8 is not supported — EOL 2024-10, and declaring support would incur backport obligations whenever an unmaintained-Python CVE surfaces.
### Init now follows the same OS-aware Python command policy as templates
The template layer already rendered `{{PYTHON_CMD}}` as `python` on Windows and
`python3` on macOS/Linux, but `packages/cli/src/commands/init.ts` still probed
`python3` first everywhere and only fell back to `python`. That meant the
Windows status message, generated hook commands, and init's own
`init_developer.py` bootstrap path were talking about different interpreters.
`trellis init` now uses the same platform rule in both places:
| Platform | Generated command | Init probe / bootstrap command |
| ------------- | ----------------- | --------------------------------------------------------------------- |
| Windows | `python` | `python --version`, `python .trellis/scripts/init_developer.py ...` |
| macOS / Linux | `python3` | `python3 --version`, `python3 .trellis/scripts/init_developer.py ...` |
If the selected platform command resolves to Python \< 3.9, init prints a
warning but still completes. Missing Python still does not block file
generation; the follow-up failure mode remains the same manual bootstrap hint.
| File | Change |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `packages/cli/src/configurators/shared.ts` | Export shared OS → Python command helper used by template rendering |
| `packages/cli/src/commands/init.ts` | Reuse shared helper for version probe, Windows notice, and `init_developer.py` invocation |
| `packages/cli/test/commands/init.integration.test.ts` | Regression coverage for init bootstrap command + soft warning path |
| `packages/cli/test/commands/init-internals.test.ts` | Unit coverage for Python version floor warning behavior |
## Upgrade
Existing projects:
```bash theme={null}
trellis update
```
Picks up the two patched hook files plus the updated `cross-platform-thinking-guide.md` template. Pristine installs apply silently; locally-modified copies land on the standard confirm prompt.
Fresh install:
```bash theme={null}
npm i -g @mindfoldhq/trellis@0.5.0-beta.11
```
# v0.5.0-beta.12
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.12
2026-04-23
Phase 1.3 is now agent-curated. `task.py init-context` is removed; `task.py create` seeds `implement.jsonl` / `check.jsonl` with a self-describing `_example` line on sub-agent-capable platforms, and the AI fills real spec + research entries per `workflow.md` Phase 1.3. Session-start READY gate across four implementations now requires at least one curated entry. Skill Routing tables split per-platform. Release pipeline hardened. Not breaking; `trellis update` handles existing tasks transparently.
## Feature Changes
### workflow\.md Phase 1.3 is now filled in by the agent, not by a script with pre-generated defaults
The old `task.py init-context` pre-filled `implement.jsonl` / `check.jsonl` from `dev_type` + package config, assuming the template path `spec/<package>/{backend,frontend}/index.md`. Monorepos that split by language (e.g. `package = backend` + `package = frontend`) produced entries pointing at files that don't exist — which then led the agent to pre-fill the jsonl itself, and the many tool-call rounds that followed scattered the model's attention and drifted it off the Trellis workflow.
Seed row format (one line per jsonl, no `file` field so every consumer skips it):
```jsonl theme={null}
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line when done."}
```
### Skill Routing tables split per-platform
`workflow.md` Skill Routing and DO-NOT-skip tables now have two dispatch modes: IDEs/CLIs that support sub-agents invoke `trellis-implement` to do the actual coding, while platforms without sub-agents load `trellis-before-dev` in the main agent and code there directly.
| Sub-agent platforms | Non-sub-agent platforms |
| ---------------------------------------------------------------------------------------- | --------------------------------------------------- |
| Claude / Cursor / OpenCode / Codex / Kiro / Gemini / Qoder / CodeBuddy / Copilot / Droid | Kilo / Antigravity / Windsurf |
| Dispatch `trellis-implement` sub-agent per Phase 2.1 | Load `trellis-before-dev` skill (main-session flow) |
### Session-start READY gate across four implementations
Before this release, all four session-start implementations treated `implement.jsonl` file existence as "ready for Phase 2". After `task.py create` seeded jsonl, the breadcrumb jumped straight to `Status: READY` and the AI skipped Phase 1.3 curation.
Now each implementation scans the jsonl for at least one row with a `file` key. Seed-only jsonl surfaces as `Status: PLANNING (Phase 1.3)` with a Next-Action pointing at the curation step.
```python theme={null}
def _has_curated_jsonl_entry(jsonl_path: Path) -> bool:
"""A freshly seeded jsonl only contains `{"_example": ...}` — that is NOT ready."""
for line in jsonl_path.read_text(encoding="utf-8").splitlines():
line = line.strip()
if not line:
continue
try:
row = json.loads(line)
except json.JSONDecodeError:
continue
if isinstance(row, dict) and row.get("file"):
return True
return False
```
| Implementation | Consumed by |
| ----------------------------------- | ----------------------------------------------------- |
| `shared-hooks/session-start.py` | Claude, Cursor, Kiro, CodeBuddy, Droid, Gemini, Qoder |
| `codex/hooks/session-start.py` | Codex |
| `copilot/hooks/session-start.py` | Copilot |
| `opencode/plugins/session-start.js` | OpenCode (JS plugin runtime) |
### Hook + prelude tolerance for seed-only jsonl
`shared-hooks/inject-subagent-context.py:read_jsonl_entries` filters rows without `file` silently (no error) but emits a single stderr warning when the result is empty.
`configurators/shared.ts:buildPullBasedPrelude` teaches Class-2 sub-agents (Codex / Copilot / Gemini / Qoder) to skip rows without `file` and fall back to `prd.md` + self-discovered specs when the jsonl has only the seed row.
## Internal Improvements
### Pre-release manifest continuity guard
`packages/cli/scripts/check-manifest-continuity.js` queries `npm view @mindfoldhq/trellis versions --json` and diffs against local `src/migrations/manifests/*.json`. Any version on npm without a corresponding local manifest fails the check non-zero.
Background: `trellis update` applies migrations where `v > installed && v <= current`. A version on npm without its local manifest silently skips its migration bucket for users upgrading from adjacent versions — see the beta.10 incident in `.trellis/spec/cli/backend/migrations.md`.
| Release script | Pre-flight order |
| ------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `release` / `release:minor` / `release:major` | `check-manifest-continuity.js` → `pnpm test` → bump → commit → tag → push |
| `release:beta` / `release:rc` / `release:promote` | `check-manifest-continuity.js` → `check-docs-changelog.js` → `pnpm test` → bump → ... |
Historical gaps frozen in `KNOWN_GAPS` (pre-manifest-system versions 0.1.0–0.1.8, 0.2.1–0.2.11; early public prerelease 0.3.10-beta.0). The comment block documents the list must not be extended — any new gap means root-cause fix, not whitelist append.
Emergency bypass: `SKIP_MANIFEST_CONTINUITY=1 pnpm release:beta`. Prints a loud banner when set.
### `trellis update` backup-phase stack-overflow fix
`createFullBackup()` descended into old `.trellis/.backup-*` directories during `.trellis/` scan, and those old backups in turn contained nested `.opencode/node_modules` (tens of thousands of files). The original `collectAllFiles()` used recursion + `files.push(...largeArray)`, which tripped V8's `Maximum call stack size exceeded` on large file counts. `trellis update` crashed at the backup phase after the user confirmed.
| Fix | Location |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `collectAllFiles` rewritten as iterative stack traversal (no recursion, no large-array spread) | `packages/cli/src/commands/update.ts:770` |
| Skip `node_modules`, `.backup-*`, and other excluded dirs at the scan phase, not only at the copy phase | `packages/cli/src/commands/update.ts:683` |
| Normalize backslashes to forward slashes before matching `BACKUP_EXCLUDE_PATTERNS` (aligns with `isManagedPath`'s existing regex). `.claude\worktrees\...` now matches on Windows | `packages/cli/src/commands/update.ts:689` |
| `collectAllFiles` skips symlinks and Windows NTFS junctions (`isSymbolicLink()` returns true for junctions too), preventing infinite scans on cyclic paths | `packages/cli/src/commands/update.ts:787` |
| Print full stack trace when `DEBUG=1` or `TRELLIS_DEBUG=1` is set | `packages/cli/src/cli/index.ts:130` |
Regression coverage added in `test/commands/update-internals.test.ts` and `test/commands/update.integration.test.ts`.
Temporary workaround for users on a pre-fix published CLI: `rm -rf .trellis/.backup-*` drops the old backups; subsequent `trellis update` runs won't hit the overflow source.
### `create-manifest.js` guards against rewriting published manifests
The script now refuses to (re)write a manifest for a version already on npm — even with `force: true`. Interactive mode adds the npm-published check before the existing local-file overwrite prompt.
```
$ node scripts/create-manifest.js --stdin <<< '{"version": "0.5.0-beta.11", ...}'
✗ Version 0.5.0-beta.11 is already published on npm.
Its manifest is part of the update contract and must NOT be rewritten.
If you need to release additional migrations, use the NEXT version number.
```
### `vi.mock("node:child_process")` now returns a valid Python version string
`update.integration.test.ts` and `init-joiner.integration.test.ts` stubbed `execSync` to return empty string for all commands. `init()` invokes `requireSupportedPython()` which calls `execSync("python3 --version")` and treats empty output as "Python not found", throwing before any test assertion ran.
```typescript theme={null}
// Before — blanket empty return:
vi.mock("node:child_process", () => ({
execSync: vi.fn().mockReturnValue(""),
}));
// After — conditional return for python version probe:
vi.mock("node:child_process", () => ({
execSync: vi.fn().mockImplementation((cmd: string) => {
const py = process.platform === "win32" ? "python" : "python3";
return cmd === `${py} --version` ? "Python 3.11.12" : "";
}),
}));
```
Resolves 36 pre-existing failures. Full suite: 664/664 green.
## Upgrade
Existing projects:
```bash theme={null}
trellis update
```
Picks up the updated scripts + hooks. Existing `implement.jsonl` / `check.jsonl` files keep working — seed rows without `file` are ignored by every consumer. If your prior `init-context`-generated jsonl points at paths that don't exist on your monorepo spec layout (typical for `package = backend | frontend` projects), re-curate per `workflow.md` Phase 1.3:
```bash theme={null}
python3 ./.trellis/scripts/get_context.py --mode packages # see what specs exist
python3 ./.trellis/scripts/task.py add-context <task-dir> implement \
".trellis/spec/<pkg>/<layer>/index.md" "why it applies"
```
After first real entry, the session-start breadcrumb flips from `PLANNING (Phase 1.3)` to `READY`.
Fresh install:
```bash theme={null}
npm i -g @mindfoldhq/trellis@0.5.0-beta.12
```
# v0.5.0-beta.13
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.13
2026-04-23
Patch follow-up to beta.12. `task.py start` now actually transitions `task.json` status from `planning` to `in_progress`. Previously only the `.current-task` pointer got updated and the status field stayed untouched, so Claude Code's statusline kept showing `planning`.
## Bug Fixes
### `task.py start` transitions `task.json` status to `in_progress`
`cmd_start` previously wrote `.current-task`, ran the `after_start` hook, and returned without modifying the `status` field in `task.json`. That field was maintained only by `create` (writes `planning`) and `archive` (writes `completed`); no code path wrote `in_progress`. Tasks in active development therefore did not appear under `list --status in_progress` and continued to show `Status: PLANNING` in session-start breadcrumbs.
`cmd_start` now reads `task.json` after setting the pointer and writes `in_progress` only when the current `status == "planning"`. Other statuses are preserved:
| Current status | After `task.py start` |
| -------------- | ---------------------------------------------------------------------------------- |
| `planning` | `in_progress` |
| `in_progress` | `in_progress` (no-op) |
| `review` | `review` (preserved; re-starting to address review feedback must not reset status) |
| `completed` | `completed` (preserved) |
Location: `packages/cli/src/templates/trellis/scripts/task.py:cmd_start`.
### Codex agent templates backport the Phase 1.3 fallback section
During beta.11's init-context-removal, a "Required: Load Trellis Context First" block was added to the top of both Codex agent files. It instructs the sub-agent to skip `{"_example": ...}` seed rows and, when `implement.jsonl` / `check.jsonl` contains no curated entries, fall back to reading `prd.md` and selecting specs via `get_context.py --mode packages`.
That edit landed only in the dogfood copy at the project root and was not propagated to `packages/cli/src/templates/codex/agents/`. Through beta.12, Codex agent prompts distributed by `trellis init` / `trellis update` lacked the block; the sub-agent blocked on seed-only jsonl instead of taking the fallback path.
Backported in this release:
* `packages/cli/src/templates/codex/agents/trellis-check.toml`
* `packages/cli/src/templates/codex/agents/trellis-implement.toml`
The text matches the prelude generated by `configurators/shared.ts:buildPullBasedPrelude` for Copilot / Gemini / Qoder, aligning Codex with the other pull-based platforms.
## Docs
### `.codex/config.toml` documents the `features.codex_hooks` opt-in
Trellis's Codex integration depends on the SessionStart and UserPromptSubmit hooks declared in `.codex/hooks.json`. Codex loads these only when `[features] codex_hooks = true` is set in the **user-level** `~/.codex/config.toml`; project-scoped `.codex/config.toml` cannot enable `features.*`. Without the flag, `hooks.json` is silently ignored and Trellis context injection does not run, presenting as Trellis failing to engage on Codex.
The project-scoped stub now carries a comment identifying the user-level config path and the exact TOML snippet to add. The unrelated `shell_environment_policy` block was removed.
## Upgrade
Existing projects:
```bash theme={null}
trellis update
```
No migration steps. Existing tasks, jsonl files, and `.current-task` are preserved. The first `task.py start` on an existing `planning` task after upgrade writes `in_progress` to `status` automatically. Codex users who hand-edited `.codex/agents/trellis-*.toml` will see the two files flagged during update; `trellis update` prompts per file.
Fresh install:
```bash theme={null}
npm i -g @mindfoldhq/trellis@0.5.0-beta.13
```
# v0.5.0-beta.14
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.14
2026-04-24
Patch follow-up to beta.13. SessionStart hooks now emit a one-shot `<first-reply-notice>` so the first visible assistant reply confirms Trellis context has been injected. READY-state breadcrumbs were rewritten to explicitly require `trellis-implement` dispatch on agent-capable platforms, closing a loophole where the main thread would hand-edit code itself. Claude Code's statusline now survives the Windows UTF-8 encoding setup on Python builds that ship typed stdio.
## Enhancements
### One-shot SessionStart announcement on the first reply
Users had no clear signal that Trellis's SessionStart hook had actually injected. SessionStart hooks now prepend the following block to `additionalContext`:
```text theme={null}
<first-reply-notice>
On the first visible assistant reply in this session, begin with exactly one short Chinese sentence:
Trellis SessionStart 已注入：workflow、当前任务状态、开发者身份、git 状态、active tasks、spec 索引已加载。
Then continue directly with the user's request. This notice is one-shot: do not repeat it after the first assistant reply in the same session.
</first-reply-notice>
```
Applied to:
* `packages/cli/src/templates/shared-hooks/session-start.py`
* `packages/cli/src/templates/codex/hooks/session-start.py`
* `packages/cli/src/templates/opencode/plugins/session-start.js`
`copilot/hooks/session-start.py` keeps the JSON shape for protocol parity but omits the notice because GitHub Copilot currently ignores `sessionStart` output (see Docs below).
### READY-state Next-Action copy rewritten
The old breadcrumb copy was:
```text theme={null}
Status: READY
Task: <title>
Next: Continue with implement or check
```
On agent-capable platforms this prompt could let the main agent process write code itself, bypassing the sub-agent workflow.
New copy:
```text theme={null}
Status: READY
Task: <title>
Next required action: dispatch `trellis-implement` per Phase 2.1.
For agent-capable platforms, do NOT edit code in the main session.
After implementation, dispatch `trellis-check` per Phase 2.2 before reporting completion.
```
The `<ready>` closing directive also changed from *"If there is an active task, ask whether to continue it"* to *"If a task is READY, execute its Next required action without asking whether to continue."*
Uniformly applied across:
| File | Scope |
| ------------------------------------------- | --------------------------------------- |
| `shared-hooks/session-start.py` | Claude Code, Gemini, Qoder, Kiro, iFlow |
| `shared-hooks/inject-workflow-state.py` | UserPromptSubmit fallback breadcrumb |
| `opencode/plugins/session-start.js` | OpenCode SessionStart |
| `opencode/plugins/inject-workflow-state.js` | OpenCode fallback breadcrumb |
| `codex/hooks/session-start.py` | Codex SessionStart |
| `copilot/hooks/session-start.py` | Copilot (hook present, see Docs) |
| `trellis/workflow.md` | `[workflow-state:in_progress]` block |
## Bug Fixes
### Claude Code statusline: Windows UTF-8 encoding setup no longer crashes
Claude Code's statusline (`.claude/hooks/statusline.py`, sourced from `shared-hooks/statusline.py`) needs to flip stdout/stderr to UTF-8 on Windows — otherwise glyphs like the middle dot (`·`) get mangled by GBK. The old setup was:
```python theme={null}
sys.stdout = io.TextIOWrapper(sys.stdout.detach(), encoding="utf-8")
sys.stderr = io.TextIOWrapper(sys.stderr.detach(), encoding="utf-8")
```
On some Windows Python builds, `sys.stdout` / `sys.stderr` are typed wrappers that do not expose `detach()`. Calling it raised, the statusline process died, and Claude Code's top info line went blank. The fix uses the standard `io.TextIOBase.reconfigure()` API (Python 3.7+) when available and no-ops otherwise:
```python theme={null}
if sys.platform == "win32":
for stream in (sys.stdout, sys.stderr):
reconfigure = getattr(stream, "reconfigure", None)
if callable(reconfigure):
reconfigure(encoding="utf-8", errors="replace")
```
`reconfigure` is standard on Python 3.7+ text streams; `errors="replace"` keeps rendering when the host refuses a rare glyph.
### Codex & Copilot SessionStart reuse the project's own encoding setup
Both hooks now run `configure_project_encoding(project_dir)` before emitting JSON: add `.trellis/scripts/` to `sys.path`, call `common.configure_encoding()` if the project ships it, skip otherwise:
```python theme={null}
def configure_project_encoding(project_dir: Path) -> None:
scripts_dir = project_dir / ".trellis" / "scripts"
if str(scripts_dir) not in sys.path:
sys.path.insert(0, str(scripts_dir))
try:
from common import configure_encoding # type: ignore[import-not-found]
configure_encoding()
except Exception:
pass
```
Prevents mojibake in hook stdout on Windows Codex/Copilot runs that have not already wrapped stdout.
## Docs
### Copilot `sessionStart` hook is currently advisory
`copilot/hooks/session-start.py`'s module docstring and `systemMessage` now state explicitly that GitHub Copilot's documented SessionStart behavior ignores hook stdout. The script continues to emit the Trellis payload (for parity with other hosts and eventual Copilot support), but the old success message — `Trellis context injected (<n> chars)` — was misleading on this host. It now reads `Trellis SessionStart diagnostics emitted (<n> chars); Copilot currently ignores sessionStart hook output.`
Copilot users should rely on `UserPromptSubmit` breadcrumbs (which *are* honored) and hook logs to verify Trellis engagement, not SessionStart output.
## Upgrade
Existing projects:
```bash theme={null}
trellis update
```
No migration steps. Existing tasks, jsonl files, and `.current-task` are preserved. On the next session start you'll see a one-line Chinese confirmation that Trellis context was injected, and READY tasks will push you to `trellis-implement` without the old "continue?" prompt. Claude Code's statusline on Windows no longer crashes during UTF-8 encoding setup.
Fresh install:
```bash theme={null}
npm i -g @mindfoldhq/trellis@0.5.0-beta.14
```
# v0.5.0-beta.15
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.15
2026-04-27
Beta.15 updates task runtime state, platform session identity propagation, Pi Agent integration, and beta documentation. It also keeps the shared-hook cleanup manifest entries from the pending beta.15 release.
## Behavior Changes
### Session-scoped active task runtime
Active task state now uses a per-session runtime file:
```text theme={null}
.trellis/.runtime/sessions/<session-key>.json
```
`.trellis/.current-task` is no longer used as the active-task fallback.
| Command | Behavior |
| -------------------------- | ---------------------------------------------------------------------------- |
| `task.py start <task>` | Writes the current task into the resolved session file |
| `task.py current --source` | Reads the current task from the resolved session file |
| `task.py finish` | Deletes the resolved session file |
| `task.py archive <task>` | Deletes session files that still point at the archived task before moving it |
Session file shape:
```json theme={null}
{
"platform": "session",
"last_seen_at": "2026-04-27T01:43:24Z",
"current_task": ".trellis/tasks/04-21-session-scoped-task-state",
"current_run": null
}
```
`task.py start` exits with code `1` when no session identity is available:
```text theme={null}
Error: Cannot set active task without a session identity.
Hint: run inside an AI IDE/session that exposes session identity, or set TRELLIS_CONTEXT_ID before running task.py start.
```
### Bootstrap and joiner tasks
`trellis init` still creates bootstrap and joiner task directories, but it no longer writes `.trellis/.current-task`.
The generated PRDs now tell the AI to start the task from a session that exposes Trellis session identity.
### Workflow task-creation policy
`workflow.md` and hook fallback breadcrumbs now use a softer task-creation policy.
| Area | Previous behavior | beta.15 behavior |
| ---------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `no_task` trigger words | Treat matching words as requiring task creation | Treat matching words as task-creation signals |
| Simple turns | No explicit exemption | Task not required when all three hold: zero file writes, one-reply answer, no research beyond reading 1-2 repo files |
| User opt-out | Not documented in the hook prompt | Current-turn phrases such as `skip trellis`, `no task`, `just do it`, `跳过 trellis`, `别走流程`, `先别建任务` skip task creation for that turn |
| `in_progress` implementation | Main session was told not to edit code | Sub-agent dispatch remains the default; explicit current-turn requests such as `do it inline`, `main session 写就行`, `不用 sub-agent` allow main-session implementation |
## Platform Integration
### Shell session identity handling
Several hosts expose session identity differently. beta.15 adds host-specific handling for `task.py start/current/finish`.
| Platform | Change |
| ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| Claude Code | `session-start.py` writes `TRELLIS_CONTEXT_ID` through `CLAUDE_ENV_FILE` |
| Codex | `task.py` resolves native command env such as `CODEX_SESSION_ID` and Codex Desktop `CODEX_THREAD_ID` |
| Cursor | `beforeShellExecution` writes short-lived `.trellis/.runtime/cursor-shell/*.json` tickets for matching `task.py` commands |
| OpenCode | Bash tool commands are prefixed with `TRELLIS_CONTEXT_ID` |
| Pi | Bash tool calls and nested `pi --mode json` sub-agent runs receive `TRELLIS_CONTEXT_ID` |
Other platforms use the same `.trellis/.runtime/sessions/` storage, but beta.15 does not add new shell-command handling for them.
| Platform group | beta.15 status |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GitHub Copilot | The platform-specific SessionStart hook resolves session identity for context injection. `task.py` can use exported `COPILOT_*` session env vars when the host provides them; otherwise use `TRELLIS_CONTEXT_ID` for manual shell starts. |
| Gemini CLI, Qoder, CodeBuddy, Droid, Kiro | Shared hooks resolve session identity from hook input or platform env vars. No new shell-command bridge was added in beta.15. Manual shell starts still use `TRELLIS_CONTEXT_ID` when the host does not export a session id. |
| Kilo, Antigravity, Windsurf | No hook integration. Use their workflow/command files plus explicit `TRELLIS_CONTEXT_ID` when running `task.py start` manually. |
| `.agents/skills` consumers | No Trellis-managed hook layer. They use the `.trellis/` core and whatever prelude or env injection the host provides. |
### Cursor sub-agent hook matching
Cursor `hooks.json` now matches both tool names:
```json theme={null}
{
"matcher": "Task|Subagent"
}
```
`inject-subagent-context.py` also parses Cursor custom-agent payloads in these shapes:
```json theme={null}
{ "custom": { "name": "trellis-implement" } }
```
```json theme={null}
{ "type": { "case": "custom", "value": { "name": "trellis-implement" } } }
```
### Pi Agent session runtime
Pi Agent now reads active task state from `.trellis/.runtime/sessions/`.
Context key sources, in priority order:
| Source | Example |
| ------------------ | ------------------------------------ |
| Explicit env | `TRELLIS_CONTEXT_ID` |
| Pi session manager | `sessionManager.getSessionId()` |
| Pi env | `PI_SESSION_ID`, `PI_SESSIONID` |
| Transcript path | `transcript_path` / `transcriptPath` |
| Process fallback | `pi_process_<hash>` |
Nested Pi sub-agent runs receive the same `TRELLIS_CONTEXT_ID`.
### Workflow-state override copy
`workflow-state` breadcrumbs now use exact Trellis agent names:
```text theme={null}
trellis-implement
trellis-check
trellis-research
```
The breadcrumbs also document explicit per-turn override phrases for skipping task creation or allowing main-session implementation.
## Bug Fixes
### OpenCode sub-agent name normalization
OpenCode now:
* recognizes `OPENCODE_RUN_ID` as session identity
* strips the `trellis-` prefix before matching sub-agent names
* keeps `implement.jsonl` / `check.jsonl` injection working with renamed agents
### Git-backed private registries
Template registry downloads now support private Git-backed registries. When a registry source requires local Git credentials, Trellis uses Git to read `index.json` and copy template directories instead of relying on anonymous raw HTTP.
This applies to self-hosted GitLab / GitHub Enterprise sources and SSH registry URLs. Registry errors are classified separately for authentication failures, missing refs, missing paths, invalid `index.json`, and network failures, so `trellis init --registry` no longer misclassifies those cases as direct-download mode.
### Shared-hook cleanup
`writeSharedHooks` and `collectSharedHooks` now use the same platform capability table:
```text theme={null}
SHARED_HOOKS_BY_PLATFORM
```
Claude Code statusLine is no longer installed by default for new projects. New installs do not write `.claude/hooks/statusline.py` or configure `statusLine` in `.claude/settings.json`.
Existing projects keep their installed Claude Code statusLine behavior: `trellis update` preserves `.claude/hooks/statusline.py` and carries an existing `.claude/settings.json` `statusLine` entry forward into the updated settings file.
The manifest includes 10 hash-verified `safe-file-delete` entries for hooks that were written to projects but are now orphaned.
| Removed path | Reason |
| -------------------------------------- | --------------------------------------- |
| `.cursor/hooks/statusline.py` | Cursor has no `statusLine` event |
| `.codex/hooks/statusline.py` | Codex has no `statusLine` event |
| `.gemini/hooks/statusline.py` | Gemini has no `statusLine` event |
| `.qoder/hooks/statusline.py` | Qoder has no `statusLine` event |
| `.github/copilot/hooks/statusline.py` | Copilot has no `statusLine` event |
| `.codebuddy/hooks/statusline.py` | CodeBuddy has no `statusLine` event |
| `.factory/hooks/statusline.py` | Factory Droid has no `statusLine` event |
| `.kiro/hooks/statusline.py` | Kiro has no `statusLine` event |
| `.kiro/hooks/session-start.py` | Kiro exposes only `agentSpawn` |
| `.kiro/hooks/inject-workflow-state.py` | Kiro exposes only `agentSpawn` |
Modified local files are preserved with a warning.
## Docs
### Beta task docs
Updated beta docs now describe:
* current task state under `.trellis/.runtime/sessions/<session-key>.json`
* session-scoped task ownership instead of a global project pointer
* `continue` / `finish-work` as the primary user-facing task commands
* `task.py start` as a session-bound operation
* Cursor, Codex, Claude Code, OpenCode, and Pi hook/sub-agent behavior
### Multi-agent docs
The beta multi-agent docs now describe native Git worktrees plus Trellis tasks. Removed references to Trellis-managed `/trellis:parallel` and `worktree.yaml`.
## Upgrade
Existing projects:
```bash theme={null}
trellis update
```
No `--migrate` gate is required for beta.15.
Existing task directories and jsonl files remain valid. Existing `.trellis/.current-task` files are preserved but ignored by the new active-task resolver.
Manual shell usage requires an explicit context id:
```bash theme={null}
TRELLIS_CONTEXT_ID=my-session python3 .trellis/scripts/task.py start .trellis/tasks/<task>
```
Fresh install:
```bash theme={null}
npm i -g @mindfoldhq/trellis@0.5.0-beta.15
```
# v0.5.0-beta.16
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.16
2026-04-28
Beta.16 is a compatibility patch for template hash portability, task archive inputs, and Claude Code statusLine upgrades after beta.15.
## Bug Fixes
### Template hash portability
Template hash storage now uses POSIX path keys and LF-normalized content hashes.
The `.trellis/.template-hashes.json` file now uses a versioned envelope:
```json theme={null}
{
"__version": 2,
"hashes": {
".trellis/scripts/task.py": "<sha256>"
}
}
```
| Area | beta.16 behavior |
| ----------------------- | ------------------------------------------------------------------- |
| Hash keys | Stored with `/` separators on every host |
| Hash input | CRLF content is normalized to LF before SHA256 |
| Legacy flat hash file | Discarded and regenerated from installed templates |
| Directory safety checks | `path.relative()` output is normalized before template/hash lookups |
| OpenCode templates | Collector stores `.opencode/*` keys in POSIX form |
This fixes Windows checkout cases where backslash hash keys or CRLF line endings made unchanged templates look modified.
### `task.py archive` input contract
`task.py archive` now accepts the same task inputs as the other task-directory commands.
| Input form | Example |
| ------------------ | ----------------------------------------------------------------------------- |
| Bare task name | `python3 .trellis/scripts/task.py archive 04-27-example` |
| Relative task path | `python3 .trellis/scripts/task.py archive .trellis/tasks/04-27-example` |
| Absolute task path | `python3 .trellis/scripts/task.py archive /repo/.trellis/tasks/04-27-example` |
Previously, `archive` was the only dir-style task command that used slug-only lookup. Passing `.trellis/tasks/<slug>` failed with `Task not found` even though other task commands accepted that form.
### Existing Claude Code statusLine installs are preserved
Beta.15 stopped installing Claude Code `statusLine` for new projects. That default is unchanged.
The upgrade path is now more conservative:
| Case | beta.16 behavior |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| New project | Trellis does not create `.claude/hooks/statusline.py` and does not add `statusLine` to `.claude/settings.json` |
| Existing project with `.claude/hooks/statusline.py` | `trellis update` preserves the file |
| Existing project with `.claude/settings.json` `statusLine` | `trellis update` carries that entry into the updated settings file |
This means beta.16 no longer treats Claude Code statusLine as a cleanup target. Users who no longer want it can delete the file and settings entry manually.
### Shared-hook cleanup still applies to orphan platform files
The non-Claude `statusline.py` cleanup entries remain hash-verified safe deletes. Those platforms have no `statusLine` event, so the files were never invoked:
* `.cursor/hooks/statusline.py`
* `.codex/hooks/statusline.py`
* `.gemini/hooks/statusline.py`
* `.qoder/hooks/statusline.py`
* `.github/copilot/hooks/statusline.py`
* `.codebuddy/hooks/statusline.py`
* `.factory/hooks/statusline.py`
* `.kiro/hooks/statusline.py`
## Upgrade
Existing projects:
```bash theme={null}
trellis update
```
No `--migrate` flag is required for this patch.
# v0.5.0-beta.17
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.17
2026-04-28
Beta.17 updates generated templates and platform integrations for built-in Trellis metadata, Pi subagents, and task context wiring.
## Enhancements
### Bundled `trellis-meta` skill
`trellis-meta` is now installed through the built-in skill template pipeline instead of requiring a separate marketplace install.
| Area | beta.17 behavior |
| ----------------- | ------------------------------------------------------------------------------------ |
| Template source | `packages/cli/src/templates/common/bundled-skills/trellis-meta/` |
| Template reader | `getBundledSkillTemplates()` reads complete skill directories |
| Template resolver | `resolveBundledSkills()` resolves placeholders across `SKILL.md` and `references/**` |
| Template writer | `writeSkills()` writes workflow skills plus bundled multi-file skills |
| Template tracking | `collectSkillTemplates()` includes every bundled skill file for update hash tracking |
Every platform skill root now receives `trellis-meta/SKILL.md` plus its reference files during `trellis init` and `trellis update`.
### Pi subagent launcher and config
The generated Pi extension now launches nested Pi subagents through a Windows-safe process path and supports per-agent model settings.
| Capability | beta.17 behavior |
| ---------------- | ------------------------------------------------------------------------------------------------------- |
| CLI resolution | Resolves `@mariozechner/pi-coding-agent/dist/cli.js` and runs it with `process.execPath` when available |
| Fallback | Uses `spawn("pi", ...)` when no JS entrypoint is found |
| Prompt transport | Sends delegated prompts through stdin instead of argv |
| Output mode | Runs child Pi with `--mode text -p --no-session` |
| Context | Forwards `TRELLIS_CONTEXT_ID` into child processes |
| Cancellation | Wires `AbortSignal` to child process kill/reject behavior |
| Output bounds | Keeps bounded stdout/stderr buffers with truncation notices |
Subagent run configuration can come from `.pi/agents/*.md` frontmatter or per-call tool input:
```yaml theme={null}
---
model: anthropic/claude-sonnet-4
thinking: high
fallbackModels:
- openai/gpt-5-mini
---
```
The extension maps those fields to Pi CLI args:
| Input | Child Pi args |
| -------------------- | --------------------------------------------------------------------------- |
| `model` + `thinking` | `--model <model>:<thinking>` unless the model already has a thinking suffix |
| `model` only | `--model <model>` |
| `thinking` only | `--thinking <level>` |
Pi still keeps Trellis workflow skills under `.pi/skills`. Shared `.agents/skills` remains deferred until the shared skill text is platform-neutral.
### Workflow task slug wording
The Trellis brainstorm instructions now state that `task.py create --slug <auto>` receives a slug without a date prefix.
`task.py create` adds the `MM-DD-` directory prefix automatically, so command examples no longer imply that callers should include the date in `--slug`.
## Behavior Changes
### Init completion output
`trellis init` no longer prints the promotional completion block.
The init completion path now stays focused on generated files, next actions, and testable onboarding output. Integration coverage asserts that the removed promotional pain-point copy does not return.
## Bug Fixes
### Subagent context wiring
Generated and dogfood platform files now preserve subagent context more consistently across host-specific payload formats.
| Host / file | beta.17 behavior |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `.claude/hooks/inject-subagent-context.py` | Parses Cursor-style custom subagent payloads such as `{ custom: { name } }` and `{ type: { case: "custom", value: { name } } }` |
| `.claude/hooks/inject-workflow-state.py` / `.codex/hooks/inject-workflow-state.py` | Workflow-state breadcrumbs require exact `trellis-implement`, `trellis-check`, or `trellis-research` agent names |
| `.cursor/hooks/session-start.py` | Persists `TRELLIS_CONTEXT_ID` through `CLAUDE_ENV_FILE` for later Bash commands when that bridge is available |
| `AGENTS.md` template | Documents that subagents must complete before yielding and when to spawn them |
These changes keep `implement.jsonl` and `check.jsonl` context loading tied to the Trellis agent names that receive injected task context.
## Upgrade
Existing projects:
```bash theme={null}
trellis update
```
No `--migrate` flag is required for this beta.
# v0.5.0-beta.18
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.18
2026-04-29
Beta.18 redesigns Phase 3 of the workflow: a new `Phase 3.4 Commit changes` step lets the AI batch commits of this session's edits, and `/trellis:finish-work` refocuses on archive + journal, refusing to run on a dirty working tree. Also fixes parent-task progress regression on child archive, hash-tracks `AGENTS.md` during `trellis update`, and supports OpenCode PowerShell context injection on Windows.
## Enhancements
### Phase 3.4 Commit changes
`workflow.md` Phase 3 gains a required `3.4 Commit changes` step that drives the commit cadence for the AI rather than leaving it to the user.
| Step | What the AI does |
| ---- | ------------------------------------------------------------------------------------------------------------ |
| 1 | Runs `git status --porcelain` to snapshot every dirty path |
| 2 | Runs `git log --oneline -5` to learn the repo's commit-message style (prefix, language, length) |
| 3 | Classifies dirty files into `AI-edited this session` and `Unrecognized` groups |
| 4 | Drafts a multi-commit plan, one batch per coherent change unit |
| 5 | Presents the plan once for one-shot user confirmation |
| 6 | On confirmation: runs `git add` + `git commit` per batch, no `--amend`, no `git push` |
| 7 | On rejection ("不行" / "我自己来" / "manual" / any pushback): exits to manual mode, no second plan, no flag needed |
The Wrap-up reminder previously at `3.4` renumbers to `3.5`. The `[workflow-state:completed]` breadcrumb (and the four hook fallbacks in `inject-workflow-state.py` / `inject-workflow-state.js`) now point users at `/trellis:finish-work` instead of the legacy `task.py finish` + `task.py archive` sequence.
### `/trellis:finish-work` refocuses on survey + archive + journal
The skill drops its old "Remind user to commit" step and gains a survey step that surfaces completed-but-unarchived tasks for one-shot cleanup. The new flow is:
| Step | Action |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | `get_context.py --mode record` prints active tasks, git status, and recent commits. If other completed tasks beyond the current one surface, prompt once: "archive these N too? \[y/N]" |
| 2 | `git status --porcelain`, excluding paths under `.trellis/workspace/` and `.trellis/tasks/` (managed by the script auto-commits). Bails out if anything else is dirty. |
| 3 | `task.py archive <task>` for the active task (always) and any extra confirmed in Step 1. Each produces a `chore(task): archive ...` commit |
| 4 | `add_session.py --commit <hashes>` writes the session journal (produces `chore: record journal` commit). Hashes come from Step 1's `Recent commits` list |
Final git log order is `<work commits from 3.4>` → `chore(task): archive ...` (one or more) → `chore: record journal`, never interleaved.
The common skill template uses `{{CMD_REF:finish-work}}` so each platform's `cmdRefPrefix` resolves correctly: `/trellis:finish-work` for Claude Code and OpenCode, `$finish-work` for Codex, `/trellis-finish-work` for Cursor.
## Bug Fixes
### Parent-task progress no longer regresses on child archive
`task.py list` previously dropped completed children from the parent's `[x/y done]` count whenever a child task was archived.
| Scenario | Before beta.18 | beta.18 |
| ------------------------------------ | -------------- | ------------ |
| 6 children, 1 completed and archived | `[0/5 done]` | `[1/6 done]` |
| 6 children, 2 completed and archived | `[0/4 done]` | `[2/6 done]` |
`cmd_archive` no longer removes the archived child name from the parent's `children` list, and `children_progress` treats children missing from active statuses as completed (`cmd_archive` always sets `status=completed` before moving the directory). The invariant is documented in `.trellis/spec/cli/backend/script-conventions.md` → "Parent-child invariant".
### `AGENTS.md` hash-tracked during `trellis update`
Pre-0.5.0-beta.18 projects wrote `AGENTS.md` without recording its template hash, which surfaced as a false "modified by you" conflict on update. Beta.18 introduces:
| Mechanism | Behavior |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `<!-- TRELLIS:START -->` block | Marks the Trellis-managed region inside `AGENTS.md`; `update` only replaces this block, never user content outside it |
| `LEGACY_UNTRACKED_AGENTS_MD_BLOCK_HASHES` allowlist | Pristine pre-beta.18 block hashes (e.g. `c1f511b1...`) are accepted silently so old untouched projects update without prompting |
| Hash tracking | `template-hash.ts` records the new template's hash going forward, so subsequent updates use normal classification |
User customizations outside the Trellis block are preserved.
### OpenCode PowerShell context injection on Windows
`inject-subagent-context.js` now picks the correct shell syntax based on `host.platform`:
| Platform | Injected prefix |
| -------- | ---------------------------------------------- |
| `win32` | `$env:TRELLIS_CONTEXT_ID = '<key>'; <command>` |
| Other | `export TRELLIS_CONTEXT_ID='<key>'; <command>` |
The explicit-assignment dedup detector matches both POSIX (`TRELLIS_CONTEXT_ID=...`, `export TRELLIS_CONTEXT_ID=...`) and PowerShell (`$env:TRELLIS_CONTEXT_ID = ...`) forms, so manually-prefixed commands are not double-wrapped.
## Internal
### Vitest test isolation: strip host-shell session env vars
A new `packages/cli/test/setup.ts` is registered via `setupFiles` in `vitest.config.ts`. It deletes `process.env.TRELLIS_CONTEXT_ID` and `process.env.OPENCODE_RUN_ID` at vitest process start so the OpenCode resolver tests no longer pick up a Claude/OpenCode host-session env var that would hijack the platform-input-derived `contextKey`. The pattern is documented in `.trellis/spec/cli/unit-test/conventions.md` → "Test Isolation".
### Spec updates
| Spec file | Addition |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `.trellis/spec/cli/backend/script-conventions.md` | Parent-child `children` list invariant — historical list, not pruned on archive, `children_progress` semantics |
| `.trellis/spec/cli/unit-test/conventions.md` | Test Isolation pattern — strip host-shell session env vars in vitest setup |
## Upgrade
Existing projects:
```bash theme={null}
trellis update
```
No `--migrate` flag is required for this beta.
# v0.5.0-beta.2
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.2
2026-04-20
## Bug fixes
* **`[b] Backup-rename` in the confirm prompt now actually writes an inline `.backup` copy.** Previously it and `[r] Rename anyway` executed the exact same code path — both just relied on the full project snapshot at `.trellis/.backup-<timestamp>/`. The prompt's promise of "keeps a .backup copy" was misleading.
Now `backup-rename` writes `<new-path>.backup` (for rename) or `<from>.backup` (for delete) alongside the normal operation, so you can diff/merge your customizations against the new template without digging through the full snapshot. The prompt label now states the concrete artifact path.
Default choice stays `backup-rename` (safest — pressing Enter never destroys edits). Pick `[r]` only when you're sure your local edits are fine to move as-is.
No project file migrations in this release — pure CLI-side fix.
## Migration
Run `trellis update` to pick up the new CLI behavior. If upgrading directly from 0.4.x, add `--migrate` (the 0.5.0-beta.0 breaking-change gate still applies).
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.3
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.3
2026-04-20
## Bug fixes
* **`update.skip` no longer leaves breaking-release upgrades half-migrated.** Previously, projects with paths under `update.skip` in `.trellis/config.yaml` upgraded inconsistently across a breaking release: `rename` migrations already ignored skip, but `safe-file-delete` and template writes honored it. Result: users ended up half-migrated — old deprecated files persisted under skip-protected paths, new commands like `continue.md` never landed, and every future update re-flagged the same mess.
Now when the current upgrade spans a manifest with `breaking: true + recommendMigrate: true` **and** the user passed `--migrate`, `update.skip` is bypassed for all three operations:
1. `safe-file-delete` migrations
2. New file writes (e.g. the 0.5.0 `continue.md` command)
3. Template updates for existing files (e.g. 0.5.0 `finish-work.md`)
User customizations are still guarded — the per-file "Modified by you" confirm prompt still fires at write time. And the hash check in `allowed_hashes` is still the ultimate safety net for safe-file-delete (hash-mismatch files stay put with a `skip-modified` warning regardless of bypass).
Non-breaking updates continue to respect `update.skip` exactly as before — only breaking releases trigger the bypass.
A new yellow `⚠ update.skip BYPASSED` notice appears in the breaking-change warning block so users aren't surprised when skip-protected files get cleaned up during the migration.
No project file migrations in this release — pure CLI-side fix.
## Migration
If your 0.4.x → 0.5 beta.2 upgrade left `update.skip`-protected paths half-migrated (old commands and skills sitting next to new ones), this release will finish the job:
```bash theme={null}
trellis update --migrate
```
You'll see the yellow `⚠ update.skip BYPASSED` notice listing the files that will finally get cleaned up.
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.4
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.4
2026-04-20
## Bug fixes
* **`.trellis/workflow.md` is now actually updated by `trellis update`.** Critical fix for 0.5 upgrades.
workflow\.md was explicitly **excluded** from `collectTemplateFiles` since early Trellis versions, under the assumption that it's "user-customizable documentation, written once at init, never touched by update". That assumption broke in 0.5.0 because workflow\.md started carrying **script-parsed structure**:
* `## Phase Index` — read by `get_context.py --mode phase`
* `## Phase 1/2/3` headings — inlined into the 9.5 KB SessionStart payload
* `[workflow-state:STATUS]` tag blocks — consumed by the per-turn breadcrumb hook
Users upgrading from 0.4.x → 0.5 ended up with `get_context.py` reporting `Phase Index section not found in workflow.md` and the new `/continue` command unable to resolve step routing.
**workflow\.md is now included in the normal update flow.** Unmodified copies auto-update, user-modified copies go through the existing "Modified by you" confirm prompt with diff. `workspace/index.md` stays excluded — it's runtime-appended by `add_session.py` and has no script-parsed structure.
## Upgrade path for users stuck on beta.0..beta.3
If you already upgraded to any earlier 0.5 beta and see `Phase Index section not found`:
```bash theme={null}
trellis update --migrate
```
* If you never edited workflow\.md: it auto-updates (shows in "Template updated (will auto-update)" section)
* If you edited workflow\.md: you'll get a `Modified by you` confirm prompt with diff. Pick `[1] Overwrite` to get the new 0.5 structure, or pick `[3] Skip` and merge your edits into the new template manually (the template is at `packages/cli/dist/templates/trellis/workflow.md` inside the globally installed CLI)
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.5
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.5
2026-04-20
## Breaking Changes
* **Sub-agents renamed: `implement` / `check` / `research` → `trellis-implement` / `trellis-check` / `trellis-research`** across all 10 platforms (claude, cursor, opencode, codex, kiro, gemini, qoder, codebuddy, copilot, droid).
The old generic names were colliding with user-defined agents and, on some platforms, getting matched by the main agent's description heuristics. Prefixing with `trellis-` makes them unambiguously Trellis sub-agents that only fire when you explicitly want them.
`workflow.md`, the copilot start prompt, `shared-hooks/inject-subagent-context.py` constants, and the configurator's pull-based prelude detection are all updated. If you wrote a custom command or script that calls `Task(subagent_type: "implement", ...)`, you need to change it to `trellis-implement` yourself.
## Bug Fixes
* **Dropped `model: opus` from all agent frontmatters.** This was a real money bug for Cursor users.
All 18 markdown agent templates shipped with `model: opus` hardcoded in frontmatter, plus three `Task()` examples in `copilot/prompts/start.prompt.md` that said `model: "opus"`. The effect per platform:
* **Claude Code**: silently overrode the user's selected model for every sub-agent run (all work pinned to Opus regardless of preference).
* **Cursor**: mapped `opus` to Claude Opus billing — \~5× Sonnet pricing. One tester reported "差点给我跑破产" ("almost went bankrupt on me") before noticing.
* **Gemini / Droid / Codebuddy / Qoder**: `opus` isn't a valid model identifier for these platforms — at best ignored, at worst broke.
Agents now inherit whatever model the user's platform session is configured to use. This matches user expectation: if you set Sonnet in Cursor, sub-agents run on Sonnet.
## Upgrade
```bash theme={null}
trellis update --migrate
```
* **Unmodified agent files**: auto-renamed via hash check (30 rename entries across 10 platforms).
* **Customized agent files**: you'll see the standard `Modified by you` confirm prompt with diff. Pick `[1] Overwrite` to adopt the new name, or `[3] Skip` if you want to keep your custom agent — but then you must also update `workflow.md`, skill prompts, and hook constants yourself to point at whatever name you kept.
`update.skip` is bypassed for this release (breaking + recommendMigrate both true when invoked with `--migrate`) to prevent a half-migrated state where `workflow.md` references `trellis-implement` but your `.claude/agents/` still contains the old `implement.md`.
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.6
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.6
2026-04-20
## Bug Fixes
* **Codex `trellis-check` was shipped read-only, contradicting its own contract.**
`packages/cli/src/templates/codex/agents/trellis-check.toml` had `sandbox_mode = "read-only"` and framed itself as "Read-only Trellis reviewer focused on correctness". Every other platform's check agent has `Read, Write, Edit` tools and the description explicitly says "Reviews code changes against specs **and self-fixes issues**". `workflow.md` § Phase 2.2 is unambiguous:
> The check agent's job:
>
> * Review code changes against specs
> * Auto-fix issues it finds
> * Run lint and typecheck to verify
Result for Codex users: `trellis-check` would produce findings but could not touch the filesystem, forcing the main agent to manually apply every fix. This is a silent contract violation, not just a permissions issue — the workflow assumes check closes the loop.
Fixed by:
* `sandbox_mode = "workspace-write"` (same as `trellis-implement` and `trellis-research` on codex)
* Rewrote `developer_instructions` to instruct self-fix directly, re-run lint/type-check until green, and emit a `Findings (fixed)` / `Findings (not fixed)` / `Verification` report — behaviorally identical to the Claude Code / Cursor check agent.
## Upgrade
```bash theme={null}
trellis update
```
Not a breaking release. `update.skip` is respected. If you haven't customized `.codex/agents/trellis-check.toml`, it auto-updates; if you have, you'll see the standard `Modified by you` confirm prompt with diff.
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.7
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.7
2026-04-20
## Bug Fixes
* **OpenCode plugins were incompatible with OpenCode 1.2.x.** Users saw OpenCode crash on startup with:
```
TypeError: fn3 is not a function. (In 'fn3(input)', 'fn3' is an instance of Object)
at <anonymous> (src/plugin/index.ts:90:28)
```
Root cause: we shipped plugins as `export default { id, server: async (...) => hooks }` — an object. OpenCode 1.2.x's plugin loader (`packages/opencode/src/plugin/index.ts`) does this:
```ts theme={null}
for (const [_name, fn] of Object.entries(mod)) {
const init = await fn(input) // ← line 90: expects fn to be a function
hooks.push(init)
}
```
It iterates **every** module export (including `default`) and calls each one as a function. Our object export was never unwrapped — the runtime has no special case for a `server:` property, so `{ id, server }(input)` threw `fn is not a function`.
Fixed across all 3 plugins (`inject-subagent-context.js`, `inject-workflow-state.js`, `session-start.js`) by switching to the current factory-function shape:
```js theme={null}
export default async ({ directory, client }) => {
const ctx = new TrellisContext(directory)
return {
"tool.execute.before": async (input, output) => { /* ... */ },
"chat.message": async (input, output) => { /* ... */ },
}
}
```
This matches the documented `Plugin` type in `@opencode-ai/plugin`: `(input: PluginInput) => Promise<Hooks>`.
**Impact**: any Trellis version (including 0.4.x stable) configured for OpenCode was affected as soon as OpenCode updated to 1.2.x. Upgrade to `@mindfoldhq/trellis@beta` to restore startup.
## Upgrade
```bash theme={null}
trellis update
```
Not breaking. `update.skip` is respected. The 3 plugin files auto-update if you haven't modified them; standard `Modified by you` confirm prompt with diff if you did.
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.8
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.8
2026-04-20
## Bug Fixes
### 1. `trellis update` now actually delivers opencode changes (follow-up to beta.7)
Beta.7 fixed the OpenCode 1.2.x plugin factory-function shape in CLI templates. But users running `trellis update` on existing projects reported their `.opencode/plugins/*.js` was **still broken** — the fix wasn't reaching them.
Root cause: `packages/cli/src/configurators/index.ts` had this for opencode:
```ts theme={null}
opencode: {
configure: configureOpenCode,
// ← no collectTemplates!
},
```
Every other configured platform had a `collectTemplates` function returning the platform's file set for hash-tracked update. OpenCode was the only exception — an old omission, not a design choice. Consequence: `collectPlatformTemplates("opencode")` returned `undefined`, so `trellis update` silently skipped the entire `.opencode/` tree. Any CLI-side change to opencode (plugin logic, agent prompts, lib utilities, `package.json` deps) would ship on `init` but never propagate on `update`.
Fixed by adding `collectOpenCodeTemplates()` that walks the opencode template directory and returns `{ .opencode/agents/*, .opencode/plugins/*, .opencode/lib/*, .opencode/package.json, .opencode/commands/trellis/*, .opencode/skills/*/SKILL.md }`. `configureOpenCode` (init) was refactored to use the same enumeration, so init and update write byte-identical file sets.
### 2. Windows hook-path ENOENT after `cd` in Bash tool
Reported by a user running Claude Code on Windows in a monorepo:
```
UserPromptSubmit operation blocked by hook:
[python .claude/hooks/inject-workflow-state.py]:
can't open file 'E:\IdeaProjects\ai-codeview\frontend\.claude\hooks\inject-workflow-state.py':
[Errno 2] No such file or directory
```
The file lives at `E:\IdeaProjects\ai-codeview\.claude\...` (project root), not under `frontend/`. Claude Code's Bash tool had changed cwd to `frontend/` during an earlier command, and by default that cwd **persists** into subsequent hook invocations. The UserPromptSubmit hook command — `python .claude/hooks/inject-workflow-state.py` — resolved the relative path against the stuck cwd and couldn't find the file.
Fixed by pinning `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1` in `.claude/settings.json`'s `env` block:
```json theme={null}
{
"env": {
"CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1"
},
"statusLine": { ... },
"hooks": { ... }
}
```
Claude Code reads this variable internally — no shell expansion involved — so it works identically on macOS, Linux, and Windows. The Bash tool now returns to project root after every command, and hooks always run with cwd at the project root.
We considered rewriting hook commands to use `$CLAUDE_PROJECT_DIR` but dropped that approach — [CC issue #6023](https://github.com/anthropics/claude-code/issues/6023) confirms `$VAR` syntax doesn't expand on Windows cmd/PowerShell, which would have made the Windows problem worse.
## Upgrade
```bash theme={null}
trellis update
```
Not breaking.
* **opencode**: on any beta \< 0.5.0-beta.7 with opencode configured, this release auto-updates the 3 plugin files + `trellis-*` agents + `lib/trellis-context.js` + `.opencode/package.json` to current templates. Hash-matched auto-update for unmodified copies; standard `Modified by you` confirm prompt with diff if customized.
* **claude settings**: if you haven't modified `.claude/settings.json`, it auto-updates. If you customized it (e.g. added your own hooks), you'll see the `Modified by you` prompt — pick `[1] Overwrite` to adopt the new env block, or `[3] Skip` and manually add `"env": { "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1" }` to your settings to get the Windows fix.
Install: `npm install -g @mindfoldhq/trellis@beta`
# v0.5.0-beta.9
Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.9
2026-04-22
Accumulated since beta.8: new joiner-onboarding task, polyrepo detection, AI-facing bootstrap PRDs, workflow tightening on all platforms, Qoder session-boundary command split, task.json schema unification, and orphan-script cleanup. Not breaking; no `--migrate` required.
## New Features
### 1. Joiner onboarding task
`trellis init` now dispatches on two filesystem flags:
| `.trellis/` | `.trellis/.developer` | Generated task |
| ----------- | --------------------- | ---------------------------------------------- |
| missing | n/a | `00-bootstrap-guidelines` (creator, unchanged) |
| present | missing | `00-join-<slug>` (new: joiner flow) |
| present | present | none (same-dev re-init) |
`.trellis/.developer` is the per-checkout signal because it's listed in `.trellis/.gitignore` and therefore absent on fresh clones. `.trellis/workspace/<name>/` cannot serve this role — it's committed to git.
The joiner task is auto-set as the current task, so the new developer's first `/trellis:continue` lands on an onboarding PRD covering four topics: Trellis workflow, runtime mechanics (SessionStart hook, `<workflow-state>` injection, `trellis-implement` / `trellis-check` sub-agents, per-task jsonl manifests), project spec (`.trellis/spec/`), and assigned-work lookup via `task.py list --assignee <name>`.
### 2. AI-facing bootstrap / joiner PRDs
Both onboarding PRDs are now addressed to the AI, not the developer. Opening line:
```
**You (the AI) are running this task. The developer does not read this file.**
```
Content shifted from user-facing prompts (`Ask AI:`, `Read workflow.md`) to AI-side instructions (`Explain`, `Summarize X for them`, `If archive is empty, skip — don't invent examples`). Each PRD ends with a "Suggested opening line" template used verbatim on first response.
### 3. Polyrepo detection
`detectMonorepo()` gains a 7th parser that scans up to 2 levels deep for sibling `.git` directories or worktree gitlinks. Fires only when all 6 workspace parsers miss and no submodules are declared — workspace configs (pnpm-workspace.yaml, Cargo workspaces, etc.) take precedence.
* `DetectedPackage` gains `isGitRepo: boolean` (mutually exclusive with `isSubmodule`)
* `writeMonorepoConfig` emits `git: true` to bridge to the runtime schema already consumed by `get_git_packages()` in `config.py`
* `--monorepo` failure prints a 7-marker checklist + manual `config.yaml` example instead of a one-line error
* Init confirm prompt labels polyrepo packages with `(git repo)`
* `config.yaml` template documents the `git: true` field
Covers the "meta-repo" layout (multiple independent repos under a parent directory).
## Workflow Tightening (all platforms)
### 4. Task-creation trigger words
`workflow.md [workflow-state:no_task]` + `shared-hooks/inject-workflow-state.py` + OpenCode plugin now list explicit trigger words that require a task:
* **Chinese**: `重构` / `抽成` / `独立` / `分发` / `拆出来` / `搞一个` / `做成` / `接入` / `集成`
* **English**: `refactor` / `rewrite` / `extract` / `productize` / `publish` / `build X` / `design Y`
Exemption requires all three: (a) zero file writes this turn, (b) answer fits one reply, (c) no external research. Otherwise: create a task.
### 5. Research delegation
`common/skills/brainstorm.md` adds a "Delegate to trellis-research sub-agent" section with anti-pattern:
> Inline WebFetch/WebSearch (3+ calls) in the main session is an anti-pattern. Correct pattern: spawn `trellis-research` sub-agent via Task tool. Sub-agent writes findings to `{TASK_DIR}/research/<topic>.md`; returns path + one-line summary.
`workflow.md [workflow-state:in_progress]` renames the flow description from generic verbs (`implement → check → update`) to concrete agent types (`trellis-implement → trellis-check → trellis-update-spec → finish`).
## Qoder UX Fix
### 6. Session-boundary commands split out of the skill matcher
Before beta.9, all Qoder Trellis entry points — including `finish-work` and `continue` — lived as `.qoder/skills/trellis-*/SKILL.md`. Invocation was nondeterministic (depended on the skill matcher scoring user phrasing against each skill's description).
Now session-boundary commands are Qoder Custom Commands:
* `.qoder/commands/trellis-finish-work.md` (YAML frontmatter: `name`, `description`)
* `.qoder/commands/trellis-continue.md`
Users invoke via `/trellis-finish-work` / `/trellis-continue` (exact match).
Auto-trigger workflows (`brainstorm`, `before-dev`, `check`, `update-spec`, `break-loop`) remain as `.qoder/skills/trellis-<name>/SKILL.md`.
Infra change in `configurators/shared.ts`:
* New `wrapWithCommandFrontmatter(filePath, content)` helper
* New `COMMAND_DESCRIPTIONS` registry (short, imperative, distinct from `SKILL_DESCRIPTIONS` prose for the matcher)
* `collectBothTemplates` takes an optional `wrapCmd` callback
## Internal Cleanup
### 7. `task.json` schema unification
New shared factory in `packages/cli/src/utils/task-json.ts`:
```ts theme={null}
export type TaskJson = { /* 24 canonical fields */ };
export function emptyTaskJson(overrides?: Partial<TaskJson>): TaskJson;
```
Mirrors the shape produced by `.trellis/scripts/common/task_store.py cmd_create`. Now used by:
* `init.ts getBootstrapTaskJson` (bootstrap task writer)
* `update.ts` migration-task block
Fixes a gap from beta.0: `cmd_create` was canonicalized, but the two TypeScript writers kept their own divergent shapes.
Side effects:
* Migration tasks no longer emit legacy `current_phase: 0` / `next_action: [...]` (dead since Multi-Agent Pipeline removal)
* Bootstrap task checklist moved from structured `subtasks: [{name, status}]` in task.json to markdown `- [ ]` items in prd.md. `task.json.subtasks` is now `string[]` (child task dir names) across all tasks.
### 8. Orphan file cleanup
Hash-verified `safe-file-delete` entries in the manifest:
| Path | Reason | Hashes |
| -------------------------------------- | ------------------------------------------------------------------------------ | --------------------- |
| `.trellis/scripts/common/phase.py` | Multi-Agent Pipeline era orphan; not imported in 0.5 | 1 |
| `.trellis/scripts/create_bootstrap.py` | Legacy 4th task.json writer, replaced by `init.ts getBootstrapTaskJson` in 0.4 | 3 (covers 0.3+ users) |
Pristine copies auto-delete; locally-modified copies preserved with a warning.
Related dead code removed:
* `TaskData` TypedDict (`common/types.py`): drops `current_phase: int` and `next_action: list[dict]` fields
* `script-conventions.md` spec: removes `phase.py` / `create_bootstrap.py` / `multi_agent/` from directory trees
### 9. Orphan markdown templates removed
`packages/cli/src/templates/markdown/spec/`: removed 5 orphan `.md` files never imported by `markdown/index.ts`:
* `spec/backend/index.md`
* `spec/backend/directory-structure.md`
* `spec/backend/script-conventions.md`
* `spec/guides/code-reuse-thinking-guide.md`
* `spec/guides/cross-platform-thinking-guide.md`
These shipped in `dist/` as dead weight (\~35 KB) but never landed on user disks (paired `.md.txt` stubs are what the configurator writes). No migration entry needed. Resolves a duplication bug present since early 0.1.x.
## Upgrade
```bash theme={null}
trellis update
```
Not breaking.
* **All platforms**: `workflow.md` + shared hooks auto-sync the trigger-words + research-delegation changes. Hash-matched auto-update; `Modified by you` prompt if customized.
* **Qoder**: old `.qoder/skills/trellis-{finish-work,continue}/SKILL.md` hash-verified auto-delete; new `.qoder/commands/trellis-{finish-work,continue}.md` written by the configure step.
* **Python scripts**: `phase.py` + `create_bootstrap.py` hash-verified auto-delete from `.trellis/scripts/`.
* **Existing tasks**: untouched. Python readers (`task.py`, `get_context.py`) treat missing canonical fields as `None`. Newly-created bootstrap / migration tasks from beta.9 onward produce the canonical shape.
Install: `npm install -g @mindfoldhq/trellis@beta`