Workflows

A workflow is a reusable sequence of actions that runs inside a session. Use workflows to standardize recurring development and review procedures.

Step types

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

Step	Purpose
Message	Send instructions to the agent.
Clear Context	Clear conversation context before the next action.
Asset	Add a configured asset to the working copy.
Complete Session	Mark the session done; optionally leave it open when file changes require review.
Generate Instruction File	Generate instructions from linked ticket content.
Send System Message	Add an informational message without starting agent work.
Ralph Loop	Repeat an instruction until a configured stop condition is met. See Ralph Loop.
Task	Reserved; direct task execution from workflow steps is not available. Use session hooks for scripts.

Progression

Progression controls whether operators must start each step manually.

• Workflow auto-advance sets the default for the run.
• Step auto-advance overrides progression for an individual step.
• Steps that do not wait for agent input complete immediately and continue when auto-advance is enabled.
• 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.
Step	Collected when a step needs a value that was not supplied initially.
Automatic	Supplied from the current date, session, workspace, ticket, or user context.

Initial values can be referenced as $alias or ${alias}. Step values use ${name}. If an initial parameter has the same alias, its value is used without another prompt. Automatic values use the $alias shown in the workflow editor.

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 automated ticket implementation.

Before enabling it:

1. Ensure the workflow is restricted to a workspace.
2. Add an initial parameter with alias prompt.
3. Ensure the workflow can progress without unanswered step parameters.
4. Test it in a Develop session.

The ticket description is supplied through the prompt parameter. If the requirements are not met, automated ticket start is blocked and the configuration must be corrected.

Managing workflows

Workflow management provides reusable definitions and ordered steps.

• Create, edit, clone, enable, disable, and delete workflows from Workflows.
• Drag steps to reorder them.
• Restrict a workflow to a workspace when it uses workspace-specific prompts, assets, or hooks.
• Add a custom system prompt only when every run needs the same behavior constraint.
• Disabling a workflow prevents new runs; verify active sessions before deleting a workflow.

Import and export

Import and export move workflow definitions between installations or workspaces.

• Export before making large changes or moving configuration.
• Review imported workspace restrictions, model-independent prompts, parameters, and assets before enabling the workflow.
• Imported definitions do not validate external scripts or credentials used by 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 workflow and current-step auto-advance settings, 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.
Auto-Implementation cannot start	Add the required prompt initial parameter and restrict the workflow to the ticket workspace.
Session remains open after completion	Check whether Complete only if no file changes detected changes requiring review.
Hook-backed script fails	Review the hook result in the session and test the workspace task independently. See Session Hooks.