Documentation Index
Fetch the complete documentation index at: https://docs.trytrellis.app/llms.txt
Use this file to discover all available pages before exploring further.
v0.5.0-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 |
[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 |
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.
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 |
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:
npm install -g @mindfoldhq/trellis@rc
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.
