Skip to main content
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 <workflow-id> 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:
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:
Save a variant:
Use another marketplace source when needed:
The result is a user-managed file:
trellis update does not overwrite files in this library. Re-run trellis workflow --save <workflow-id> --force when you intentionally want to refresh a saved template.

​
Pin a workflow to a task

Choose the workflow when creating a task:
Change the active task’s selection:
Clear the task pin and return to the default chain:
The selected id is stored in task.json:
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: Set a team default:
Set a personal override:
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.