End conditions and pre-conditions
Script gates make workflows react to project state instead of trusting the model to declare success. You can write them in the workflow file or set them from the Validation tab of the Workflow properties panel.
End condition
An end condition runs after a prompt step completes.
endCondition:
script: npm test
timeoutSec: 60
maxRetries: 2
retryPrompt: |
Validation failed.
stdout:
$endCondition:stdout
stderr:
$endCondition:stderrA failed validation is re-prompted while retry budget remains. A retryPrompt alone does not enable retries: set maxRetries above 0 on the condition or in defaults.endCondition.maxRetries, or use onFail: retry. With onFail: retry, no template is required: ctrlyoke sends a fallback prompt containing the expected and actual values and script output. The implicit retry limit is one when onFail: retry is set and maxRetries is omitted. When the budget runs out the step fails and the workflow stops. onFail: continue skips retries and advances immediately.
onPass: retry works in the other direction: it re-prompts when a passing validation means the step should keep working. Pass retries use passRetryPrompt, then the default pass-retry prompt from settings, and finally the step's own prompt when no template is configured. They reuse the same maxRetries budget as failure retries and the same session by default.
maxSteps is a separate run-wide cap on entries in the workflow's steps array. It counts queued steps regardless of whether the workflow author, an agent, or the dashboard added them, but it does not count finalStep iterations or end-condition retries. A workflow can set maxSteps: -1 to override a numeric global queue.maxSteps cap. See Dynamic workflows for the cap and append behavior.
When a pass-retry budget is exhausted while validation still passes, the step succeeds and the workflow advances. If a re-evaluation inside the pass-retry loop fails, the normal onFail action handles that result.
For example, this keeps asking for a regression test until the test actually fails, then advances to the next step:
steps:
- prompt: Write a regression test for issue #123. Do not fix the bug.
endCondition:
script: npm test
onPass: retry
onFail: continue
maxRetries: 3
passRetryPrompt: |
npm test still passes, so the new test does not reproduce the bug.
Strengthen the test until it fails for the right reason.This onPass: retry plus onFail: continue combination is the regression-test recipe: keep working while the condition passes, and advance once it fails.
Important fields
| Field | Meaning |
|---|---|
script | Command or script path to execute (required) |
env | Extra environment variables for the script. Secrets only as ${secret:NAME} values |
timeoutSec | Timeout in seconds. Defaults to the execution.scriptTimeoutSec setting |
shell | Shell for inline command text, e.g. pwsh, bash, cmd. Ignored for script files |
compareSource | Which output to compare: exitCode (default), stdout, stderr |
operator | How to compare: eq (default), ne, contains, notContains, gte, gt, lte, lt, matches, isEmpty, isNotEmpty |
expected | Value to compare against. Omit it to pass on exit code 0 |
ignoreCase | Case-insensitive text compare (string operators only) |
maxRetries | Shared retry limit across pass and failure retries. 0 = none, -1 = unlimited, max 100. Unset: 1 when onPass/onFail is retry; otherwise the configured default applies only when this condition has its own retryPrompt, and the limit is 0 without one |
retryPrompt | Optional template sent after validation failure; onFail: retry uses a fallback prompt when no template is configured |
passRetryPrompt | Template sent after validation passes with onPass: retry |
resumeSessionOnRetry | Whether retries stay in the same conversation (default true) |
onPass | continue (default), retry, or stopWorkflow |
onFail | continue, retry, or stopWorkflow (default) |
Every matches comparison runs in an isolated worker. Its deadline is set by execution.regexTimeoutSec (default 10 seconds). A timeout or worker failure is an evaluation error routed through the step's errorBehavior; it does not count as a failed comparison and does not trigger onFail: retry.
endCondition and preCondition can also be set once at the workflow level (or in the defaults settings) and are inherited by every prompt step. Set either to null on a step to switch an inherited condition off.
Workflows can also define named condition presets for MCP agents to attach to queued steps. Presets keep condition scripts under the workflow author's control while letting an agent choose a gate per step.
Condition presets
Declare presets in the workflow's root conditions map. The scripts and their execution settings come from the workflow author; an MCP agent names a preset when appending or editing a step and cannot supply or change its script.
conditions:
committed:
script: git status --porcelain
compareSource: stdout
operator: isEmpty
maxRetries: 2
retryPrompt: |
Finish the work, run its gate, and commit your own files.
$endCondition:stdoutAn agent attaches the preset by name:
{
"prompt": "Implement the next planned change",
"endCondition": { "use": "committed" }
}The MCP tools materialize the preset onto the step when it is queued, so later changes to the workflow preset do not affect that step. Attaching a preset replaces a workflow-level condition the step would otherwise inherit. The agent may supply declared params and override retry text or maxRetries, but the retry count cannot exceed the preset's effective retry budget. Parameter values become environment variables and are not inserted into the script; preset scripts must quote them, for example "$BUG_FILE". A parameter name cannot collide with a key set by the preset's own env.
See MCP tools for the append_step and edit_step fields.
Comparing output
A condition with no compareSource/operator/expected passes when the script exits 0. To compare stdout, stderr or the exit code against an expected value instead, state all three parts:
endCondition:
script: npm test
compareSource: stdout
operator: contains
expected: "0 failing"Every operator and comparison rule is described in Script steps and condition scripts: Comparing output.
Pre-condition
A pre-condition runs before a prompt step and decides whether to run the prompt, skip it, or stop the workflow. It uses the same script and comparison fields as an end condition (no retry fields).
preCondition:
script: npm run lint
onFail: stopWorkflow| Field | Values |
|---|---|
onPass | continue (default, run the prompt), skipPrompt, stopWorkflow |
onFail | continue, skipPrompt (default), stopWorkflow |
onFail: continue makes the pre-condition advisory: the prompt runs anyway, and its output is still available through $preCondition:* references.
How scripts run
Condition scripts are resolved and run exactly like script steps: a file path is looked up in the execution directory, the workspace root, .ctrlyoke/ and ~/.ctrlyoke/scripts/, and anything else runs as a shell command. Condition scripts always run headless. A script that cannot be run at all is an internal error handled by errorBehavior, not a failed validation. See Script steps and condition scripts: How scripts run.
Condition output references
Retry templates can use $endCondition:* references:
$endCondition:stdout$endCondition:stderr$endCondition:exitCode$endCondition:actual$endCondition:expected$endCondition:compareSource
$preCondition:* references use the same six fields and work in both the step prompt and its retry prompt. $endCondition:* references are only available in retry prompts because the end condition runs after the prompt.