Workflows

A workflow is a reusable sequence of steps that runs inside a session. Use workflows to standardize recurring development and review procedures, and to drive automated ticket implementation.

Step types

Steps define what happens and when the workflow pauses for user or agent input.

Step	Purpose
Message	Send instructions to the agent. A Message step cannot be empty.
Task	Run a Bash, PowerShell, Command Prompt, Node.js, or Python script in the session working copy. Options: Max Retries, Notify session on failure with a Failure Message, and Send output to session on success.
Clear Context	Clear conversation context before the next step.
Complete Session	Finish the session: create a pull request when no ticket is linked, or advance the linked ticket to its approval stage. Complete only if no file changes leaves the session open when uncommitted changes exist.
Generate Instruction File	Write the linked ticket's content (its approved plan when present, otherwise its description) to a repository-relative file path and copy the ticket's attachments. Requires a linked ticket.
Send System Message	Add an informational message to the session without starting agent work.
Ralph Loop	Repeat an instruction until a configured stop condition is met. See Ralph Loop.

Any step can be switched off with Skip this step without deleting it.

Progression

Progression controls whether operators must start each step manually.

• Advance automatically on the workflow advances every step as soon as it completes.
• A step's Continue automatically on completion/success option advances that step even when the workflow setting is off. It cannot hold a step back while the workflow setting is on.
• Steps that do not wait for the agent — Clear Context, Complete Session, Generate Instruction File, and Send System Message — always continue immediately.
• A failed step stops the run and displays the failure in the session.

Parameters

Parameters let one workflow accept run-specific values without duplicating the workflow.

Parameter	Usage
Initial	Collected when the workflow starts. Reference as $alias or ${alias}.
Step	Collected when a step reaches a ${name} value that was not supplied initially.
Automatic	Resolved by Polygent from the run context. Automatic aliases are reserved and cannot be used as initial parameter names.

If an initial parameter has the same alias as a step placeholder, its value is used without another prompt. A ${name} placeholder that appears in only one enabled step and does not match an initial alias is rejected on save.

Automatic parameters

Parameter	Value
$date, $datetime, $timestamp, $time	Current date and time (UTC).
$year, $month, $day	Current date parts (UTC).
$guid	A new unique identifier.
$session-id, $session-name, $session-url	The running session.
$session-owner-mail, $session-owner-name	The session owner.
$session-branch, $starter-branch	The session branch and the branch it started from.
$workspace-id, $workspace-name	The session workspace.
$ticket-id, $ticket-title, $ticket-description	The linked ticket; the run is rejected before it starts if no ticket is linked.
$env:VAR_NAME	A workspace environment variable; resolves to empty when the variable is missing.
$spec-content	Text of the specification attachment supplied at start; empty when none is supplied.

Treat parameter values as text. Validate required values when testing the workflow, especially values used in branch names, commands, or generated content.

Auto-Implementation

Auto-Implementation marks a workflow as suitable for unattended ticket implementation: it runs without prompting and always advances automatically.

A workflow can be marked Auto-Implementation only when:

1. Every initial parameter has a default value (no required parameters).
2. The ticket content reaches the agent through a $ticket-* parameter or a Generate Instruction File step.
3. Every $ticket-*, $session-*, and $workspace-* reference can be resolved for a ticket session.
4. Any Generate Instruction File path is relative and does not contain ...

The same checks run when a ticket using the workflow is queued and when it starts; a failing check blocks the start with the reason. Custom System Prompt is available only on Auto-Implementation workflows and is added to every run of the workflow.

Managing workflows

Workflow management provides reusable definitions and ordered steps.

• Create, edit, Duplicate, and delete workflows from Workflows. Requires Manage Workflows; viewing requires View Workflows.
• Reorder steps with the up and down buttons (or Alt+↑ / Alt+↓).
• Restrict a workflow to specific workspaces when it uses workspace-specific prompts or variables.
• Workflows marked System are synchronized from the managed resource repository and are read-only; they cannot be edited, exported, or deleted.
• Verify that no ticket, template, or automation still references a workflow before deleting it.

Import and export

Import and export move workflow definitions between installations.

• Export saves the workflow name, settings, and steps as JSON.
• Initial parameters and workspace restrictions are not included. An imported workflow is available to all workspaces; restrict it after import.
• Because parameters are not carried, a workflow whose steps reference initial $alias values fails import validation until those references are removed or the parameters are recreated.
• Imported definitions do not validate external scripts or credentials used by Task steps or workspace hooks.

Operating procedure

Use this procedure before assigning a workflow to tickets or automations.

1. Run it manually in the target workspace.
2. Supply every initial parameter and verify substitutions in messages.
3. Confirm pause and auto-advance behavior at each step.
4. Verify failure output is actionable.
5. Confirm completion behavior with both clean and changed working copies.
6. Enable it for tickets or automations only after the manual run succeeds.

Troubleshooting

These checks address common workflow failures.

Symptom	Check
Run does not advance	Check Advance automatically and the current step's continue option, and whether the agent is still working.
Parameter prompt appears unexpectedly	Confirm the initial parameter alias exactly matches the step placeholder.
Placeholder remains in output	Use the syntax shown by the editor and confirm the value exists in the current run context.
Workflow cannot be marked Auto-Implementation	Give every initial parameter a default and add a $ticket-* reference or a Generate Instruction File step.
Ticket start is blocked by the workflow	Read the reported reason; a $ticket-*, $session-*, or $workspace-* reference or instruction-file path failed validation.
Import is rejected	Remove $alias references to initial parameters that the export did not carry, or recreate the parameters after import.
Session remains open after completion	Complete only if no file changes found uncommitted changes.
Task step fails	Review the step output in the session, then test the script directly on the session host with the same working directory and runtime.