Workflows

A workflow is a reusable multi-step procedure that orchestrates AI sessions, scripts, and conditional logic. Build a workflow once, run it many times — feature implementations, bug fix pipelines, doc updates, code migrations.

Step types

Workflows are sequences of typed steps:

Step type	Purpose
Message	Send a message to the AI agent
Clear Context	Reset the agent's conversation context
Asset	Inject a file/asset into the workspace
Complete Session	Mark the session done (optional "complete only if no file changes" gate leaves the session open for review when the workspace has uncommitted changes)
Generate Instruction File	Produce an instruction file the agent will read
Send System Message	Send a system-level note to the session
Ralph Loop	Run a Ralph Loop iteration block — see Ralph Loop in the Sessions guide
Task	Reserved — running a script directly from a workflow step is not yet available; use a session hook to run scripts.

Auto-advance

Workflows can advance from step to step automatically:

• Workflow-level toggle — turns auto-advance on/off for the whole flow
• Step-level toggle — fine-grained control per step
• Instant steps — Clear Context, Asset, Complete Session, and Generate Instruction File advance immediately when reached

Parameters

Workflows support three kinds of parameters:

Kind	When set
Init parameters	Collected from the user when the workflow starts
Step parameters	Substituted per-step using ${paramName} syntax
Auto parameters	Provided by Polygent automatically

Parameter syntax

• Init parameters accept both $alias and ${alias} in step content.
• Step parameters use ${paramName} and prompt the user when the step runs. If paramName matches an init parameter alias, the init value wins (no prompt).
• Auto parameters use $alias only (e.g., $session-id, $ticket-title).

Auto parameters

Useful values you don't have to define yourself:

• $date, $datetime, $timestamp, $time
• $year, $month, $day
• $session-id, $session-name, $session-url, $session-branch
• $session-owner-mail, $session-owner-name
• $workspace-id, $workspace-name, $starter-branch
• $ticket-id, $ticket-title, $ticket-description, $ticket-comments
• $env:VAR_NAME — workspace environment variable, resolved per-step (missing keys become empty strings)
• $spec-content — text content of the optional spec attachment supplied at workflow start; the file is also copied into the session worktree as spec.<ext> so the agent can read it directly
• $guid — fresh GUID

Auto-Implementation flag

Mark a workflow as Auto-Implementation to run it fire-and-forget:

• No required init parameters
• Must include either GenerateInstructionFile or a ticket auto-parameter (so the agent has source material)
• Forced auto-advance throughout
• Useful when wired to ticket queues or automations

Pre-flight check

Before any workflow actually starts (Auto-Implementation or manual), Polygent runs a server-side pre-flight check against the target ticket / session / workspace and rejects the run if any of the following are true:

• A step references $ticket-title, $ticket-id, or $ticket-description but the linked ticket is missing or that field is empty.
• A Generate Instruction File step is present but the session has no linked ticket — the runtime path needs one.
• A Generate Instruction File step's resolved file path is absolute or tries to escape the workspace directory (file paths must stay inside the workspace).
• A $workspace-* or $session-* reference can't be resolved against the actual target.
• (Auto-Implementation only) A Generate Instruction File step is present but the linked ticket has no plan, no description, and no attachments — there's no source content to generate the file from.

Each rule fires only when the workflow actually references its target — a manual workflow that doesn't use $ticket-* and doesn't have a Generate Instruction File step won't be penalized for either.

When started from the Start Ticket dialog (or a manual start from the session UI), a failed pre-flight check is rejected with a message describing which rule failed. When started from a queued batch run, the offending ticket is moved to the Failed stage with the same message — the rest of the queue keeps moving.

Step management

Edit workflows freely:

• Add new steps
• Update existing step config
• Delete unused steps
• Duplicate a step (handy when steps share most config)
• Reorder to change execution order

Workspace restrictions

Workflows can be global (available in any workspace) or per-workspace (visible only inside one workspace). Restrict a workflow when it's tied to a specific repo's tooling.

Custom system prompt

Each workflow can define a custom system prompt that overrides the workspace default for the duration of the run. Use this when one workflow needs a different agent persona (e.g., a "documentation writer" tone).

Execution status

Status	Meaning
Not Started	Defined but never run
In Progress	Currently executing
Completed	Finished
Canceled	Aborted by user

Import / Export

Move workflows between environments:

• JSON Export — download a workflow definition
• JSON Import — upload a definition into a workspace
• Git-Based System Resource Sync — version-control workflows in Git for full traceability

Common patterns

Feature development pipeline

1. Generate Instruction File (load ticket spec)
2. Message: "implement the spec"
3. Message: "run the test suite and fix any failures"
4. Message: "run the linter and fix any issues"
5. Complete Session

Bug fix loop

1. Message: "reproduce the bug as a failing test"
2. Ralph Loop: "fix until tests pass" (max 5 iterations)
3. Complete Session

Code migration

1. Asset: load migration spec
2. Message: "transform all matching files, then run the build and report results"
3. Send System Message: "migration complete"
4. Complete Session

Tip: to run tests, builds, or linters as part of a workflow, either instruct the agent to run them in a Message step or wire them up as session hooks on the relevant lifecycle events.