Skip to main content
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:
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

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 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:
The parser-sensitive parts are: 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:
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. 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:
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.