{% phase %}

Attributes

Parameter	Type	Required	Description
id	string	✓	Unique identifier within the flow. Used for Mermaid subgraph ID and cross-references.
label	string	✓	Human-readable phase name. Rendered as the subgraph title and table section header.
actor	string	—	Default actor for all steps in this phase. Steps inherit this unless they declare their own actor=.
style	enum	—	Visual preset: default, primary, success, warning, danger, muted. Controls subgraph fill and table header color.

Valid Children

Tag	Multiplicity
{% step %}	[+]
{% branch %}	[*]

Valid Parent Contexts

This tag is valid inside: {% flow %}

Rules

Rule	Force	Realm	Reference	Description
phase-no-mixed-steps	must	global	—	When any tag exists in a flow, all top-level steps must be inside a phase. Mixing free steps and phases is not allowed. validationstructure
phase-unique-ids	must	global	—	All phase values within a flow must be unique. validationstructure
phase-non-empty	must	global	—	Every phase must contain at least one step. Empty phases are not allowed. validationstructure
phase-no-nesting	must	global	—	Phases cannot be nested. A inside another is an error. validationstructure

Phases divide a flow into named stages. Each phase becomes a Mermaid subgraph in the diagram and a section header row in the steps table. Step numbering is continuous across phases (phase 1 steps 1–3, phase 2 steps 4–6).

When actor is set on a phase, all steps within that phase (including those nested inside \{% branch %\} / \{% path %\} subtrees) inherit the actor unless they declare their own actor= attribute.

Agentic workflow with init, plan, and exec phases

tagphaseflow phase-tag-agentic-flow

{% flow id="agent-loop" %}
  {% phase id="init" label="Initialization" %}
    {% step actor="role/orchestrator" action="load-context" %}
      Load user context and conversation history.
    {% /step %}
  {% /phase %}

  {% phase id="plan" label="Planning" actor="role/planner" style="primary" %}
    {% step action="decompose-task" %}
      Break the goal into sub-tasks.
    {% /step %}
    {% step action="select-tools" %}
      Choose tools for each sub-task.
    {% /step %}
  {% /phase %}

  {% phase id="exec" label="Execution" actor="role/executor" %}
    {% step action="run-tool" %}
      Execute the selected tool.
    {% /step %}
    {% branch condition="tool result" %}
      {% path outcome="success" emit="tool-completed" %}
        Tool returned successfully.
      {% /path %}
      {% path outcome="failure" %}
        Tool failed.
        {% join target="plan" label="re-plan" /%}
      {% /path %}
    {% /branch %}
  {% /phase %}
{% /flow %}