Workflow schema reference
A workflow file is YAML, JSON, or a .prompt.md file. It is checked against schemas/workflow-schema.json. A multi-step workflow looks like this:
harness: claude-cli
model: sonnet
steps:
- name: Review
prompt: Review @src/ for error-handling gaps.
- type: script
script: npm test
finalStep:
prompt: Summarize what changed.A file with a single step can drop steps and put the prompt step or script step fields at the root.
How values are inherited
Most fields are execution properties. You can set them in three places. When a field appears in more than one place, the most specific one wins:
- A step's own value.
- The workflow root.
- The matching
defaults.*setting.
On most fields, null means "turn off what would be inherited". Omitting a field means "inherit it". Where null is allowed, the field's accepted forms say what it does.
| Section | Purpose |
|---|---|
| Workflow file | Root fields of a multi-step workflow file. |
| Execution properties | Shared execution configuration properties used across workflow-level defaults, prompt-level overrides, and runtime metadata |
| Prompt step | A step that sends a prompt to a harness. |
| Script step | A workflow step that runs a shell script/command with no AI interaction. |
| Parallel group | An authored group of prompt or script steps. |
| Pre-condition | Script gate that runs before the prompt. |
| End condition | Validation that runs after the prompt completes. |
| Condition presets | Author-defined named conditions available to MCP steps. |
| Shared script fields | Shared script execution properties used by endCondition, preCondition, and scriptStep. |
| Error behavior | Policy for internal errors in any step phase, including pre-conditions, prompts/harnesses, end-conditions, and script steps. |
| Prompt Markdown frontmatter | The optional YAML frontmatter block at the top of a .prompt.md file. |
| Worktree | Where the workflow runs: the working checkout or a Git worktree. |
| Variables | Workflow-level variable defaults for {{varName}} substitution. |
| Hook entry | One user-defined hook in a hooks array. |
| MCP server entry | User-defined MCP server configuration. |
| Run source | Selects another workflow's completed run for priorContext imports. |
| Harness IDs | The harnesses a workflow or step can select. |
| Template metadata | Authoring metadata for a reusable workflow template. |
| Template variable | One entry in _templateMeta.variables. |
| Template placeholder | A template variable placeholder such as {harness}. |
Workflow file
Properties authored only at the workflow root.
name
- Type:
string
Optional workflow display name shown in the dashboard heading, recent workflows and history. If omitted, the file name without its extension is used. Renaming the workflow in the dashboard does not edit this file; the next Save writes the current name back here. In a single-step file (a root prompt or script), name labels that step instead. Not substituted: This structural field or identity value stays as authored.
steps
- Type: array of (Prompt step or Script step or Parallel group)
- Required: yes
The ordered step queue. Each item is a prompt step, a script step, or a parallel group.
finalStep
- Type: Prompt step or Script step
A step that always runs after all queued prompts complete. Can be an AI prompt or a script step. If mcpServers includes "ctrlyoke" and the finalStep appends prompts, those prompts run before finalStep executes again. Working files store resolved harness/model/session metadata on finalStep._runtime; workflow phase/status remains in the root _runtime.finalStep block.
maxSteps
- Type:
-1orintegerorstring
Maximum number of entries in the run steps array. A whole-value {{name}} placeholder is coerced and validated at run start.
Accepted forms:
-1orinteger— Maximum number of entries in the run'sstepsarray, regardless of who queued them, including parallel members and disabled steps.finalStepiterations and retries are not counted. Omit to inheritqueue.maxSteps.-1means unlimited.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
worktree
- Type: Worktree
- Settings default:
defaults.worktree
Run the workflow in the working checkout or in a Git worktree. When omitted, the defaults.worktree setting applies.
vars
- Type: Variables
Default values for {{varName}} substitutions. Not substituted: Variables are not recursively expanded.
conditions
- Type: map of Condition presets
Named condition presets that MCP agents may attach to steps by name. Authors define every script; MCP agents can choose a preset but can never supply or override its scripts. Preset scripts that use declared params must quote each value (for example, "$BUG_FILE") because values are passed through environment variables. A param name may not collide with a key in that preset's own env. Not substituted: Preset definitions and parameter names are author-only contracts.
trustedExternalRoots
- Type:
string[]ornull
Restricts, extends, or disables this workflow's external-root access relative to the user/workspace defaults. Omit this field entirely to inherit the live union of approved user + workspace permissions.trustedExternalRoots (today's behavior, unchanged). When set, the array REPLACES that inherited union rather than adding to it — it may contain brand-new roots this workflow alone needs (widening, without growing the user/workspace list for every other workflow) and/or a deliberately narrowed subset of already-trusted roots (restricting a risky workflow to less than the everyday default); either way every root in the array still needs its own one-time approval unless already approved at a broader scope. These roots bound where terminal commands can write only while sandbox resolves to true (they become the sandbox's extra writable roots, none under sandboxMode: read-only); with the sandbox off or None they limit the directories given to ctrlyoke and the harness's file tools, not what a shell command can reach. Not substituted: Approval is keyed to the authored value.
Accepted forms:
string[]— Absolute external directory roots this workflow is restricted to. REPLACES (does not add to) the workspace's approved permissions.trustedExternalRoots for this workflow's runs — a root already approved at user or workspace scope needs no separate approval, but this array is the complete set; roots trusted broadly but omitted here are not accessible to this workflow. Declaring a new root here only registers a request — it never grants access by itself. Before this workflow first runs (or is loaded in VS Code) with a newly declared root, a one-time batch approval is required: a VS Code prompt, orctrlyoke trust-workflow-external-roots <file>for the standalone CLI. Execution fails closed until every declared root has a recorded decision for this workflow file's identity.null— Explicitly disables all external-root access for this workflow, regardless of user/workspace-scope trusted roots. Only workspace files are accessible. Use this to run a specific workflow with no external directories at all.
_templateMeta
- Type: Template metadata
Marks the file as a reusable template and describes its placeholders. Removed when the template is instantiated. Not substituted: This structural field or identity value stays as authored.
Execution properties
Shared execution configuration properties used across workflow-level defaults, prompt-level overrides, and runtime metadata
harness
- Type: Harness IDs or Template placeholder or
string - Settings default:
defaults.harness
Harness to use for this prompt. Determines which AI CLI executes the prompt. Optional - defaults to the defaults.harness setting.
Accepted forms:
- Harness IDs
- Template placeholder
stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
model
- Type:
string
AI model to use for this prompt. Model IDs are harness-specific, so a workflow-level model applies only to steps that run on the workflow's harness; a step on another harness that omits model uses that harness's defaults.models setting. Some harnesses replace a model they don't support with their default and log a warning, while others pass it through and the harness CLI may reject it. 'none' (None (harness default) in the dashboard) passes no model flag, so the harness CLI uses its own configured default model; it is also the out-of-the-box defaults.models value for every harness. Use it as well when you pass the model yourself in additionalArgs (e.g. a custom Bedrock model string). Optional - defaults to the harness's defaults.models setting.
executionMode
- Type:
"interactive" | "headless"orstring - Settings default:
defaults.executionMode
Where this step runs. 'interactive' uses a live PTY/TUI; 'headless' runs in the background with output in the Output panel. Pre/end-condition scripts always run headless. Omitting this field inherits the workflow/global default. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"interactive" | "headless"— Where this step runs. 'interactive' uses a live PTY/TUI; 'headless' runs in the background with output in the Output panel. Pre/end-condition scripts always run headless. Omitting this field inherits the workflow/global default.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
agent
- Type:
stringor""ornull - Settings default:
defaults.agent
Portable ctrlyoke prompt attachment. Specify ONLY the agent name without file extensions (e.g., 'ctrlyoke-workflow-composer' for file 'ctrlyoke-workflow-composer.agent.md'). ctrlyoke attaches the agent's content to the prompt wrapped in <agentInstructions> tags, so it works the same on every harness. Native harness agent discovery is managed separately in the Agents & Skills settings page and does not determine workflow agent support. On a step, null (None in the step properties) disables the agent inherited from the workflow. Variable substitution: step text accepts {{name}} and resolves at dispatch; unresolved placeholders fail before execution.
Accepted forms:
stringmatching^[a-zA-Z0-9-_]+$""— Empty string means no agent — the form the dashboard's "None" selection serializes to. Distinct from null, which explicitly disables an inherited agent.null
resumeSession
- Type:
booleanorstring - Settings default:
defaults.resumeSession
Whether this step continues an earlier step's conversation instead of starting a new session. When omitted, a step inherits the workflow's value and a workflow inherits the defaults.resumeSession setting (default: true). Without a sessionId, a resuming step continues the most recent earlier step on the same harness, skipping steps that ran on other harnesses; the first step always starts a new session. Set false where each step must start fresh, such as orchestrated loops whose steps are self-contained. Retries continue in the same session by default; set endCondition.resumeSessionOnRetry=false to start a fresh session for each retry. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
boolean— Whether this step continues an earlier step's conversation instead of starting a new session. When omitted, a step inherits the workflow's value and a workflow inherits thedefaults.resumeSessionsetting (default: true). Without a sessionId, a resuming step continues the most recent earlier step on the same harness, skipping steps that ran on other harnesses; the first step always starts a new session. Set false where each step must start fresh, such as orchestrated loops whose steps are self-contained. Retries continue in the same session by default; set endCondition.resumeSessionOnRetry=false to start a fresh session for each retry.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
mcpServers
- Type: array of (
stringor{ id: "ctrlyoke", deniedTools? }or MCP server entry) ornull - Settings default:
defaults.mcpServers
MCP servers to attach to the harness for this prompt/workflow. Registry IDs resolve against ctrlyoke's managed MCP registry. Include "ctrlyoke" to let the harness append steps through ctrlyoke's MCP server (a dynamic workflow). Use /mcp:<server-id> in the prompt to force-attach a managed server; an inline reference wins over null, which otherwise explicitly disables inherited servers. Not substituted: Entries launch programs and carry authored secret grants.
Accepted forms:
- array of (
stringor{ id: "ctrlyoke", deniedTools? }or MCP server entry) — MCP servers to attach. Registry IDs resolve against ctrlyoke's managed MCP registry; include "ctrlyoke" to let the harness append steps (a dynamic workflow). null— Explicitly disable inherited MCP servers.
Fields:
deniedTools·string[]
hooks
- Type: array of Hook entry or
null - Settings default:
defaults.hooks
User-defined hooks run alongside ctrlyoke's completion-detection hooks. Supported events vary by harness; unsupported events are silently skipped.
Accepted forms:
- array of Hook entry — User-defined hooks. A step's hooks replace the workflow's hooks for each event it defines; other workflow events inherit. A workflow's hooks array replaces defaults.hooks from settings entirely.
null— Explicitly disables all hooks for this prompt/workflow.
sessionId
- Type:
stringorinteger
Session ID for resuming CLI conversations. Can be: a string (exact CLI session ID to resume), a number (prompt reference: 1 = use session from first prompt), or the special value "finalStep" (resume the session established by the most recent final step execution — works on any prompt, not just the final step itself; on first pass when no final step session exists yet, a new session starts). When omitted and resumeSession=true, automatically resumes previous prompt's session. Working file runtime metadata stores the actual session ID used during execution. Variable substitution: step text accepts {{name}} and resolves at dispatch; unresolved placeholders fail before execution.
skills
- Type:
string[]ornull - Settings default:
defaults.skills
Portable ctrlyoke prompt attachments. For skills found inside a trusted root, ctrlyoke adds the skill name, path, and description to the prompt so the harness can read the SKILL.md file when it uses the skill; skill files outside trusted roots are read and embedded. This makes workflow skills available on every harness. The Agents & Skills settings page separately manages optional harness-native discovery directories whose behavior varies by harness; native discovery does not determine workflow skills support. Prompt-level skills replace workflow-level skills (no merging). On a step, null (None in the step properties) disables inherited workflow skills; skills declared by the selected agent still attach. Variable substitution: step text accepts {{name}} and resolves at dispatch; unresolved placeholders fail before execution.
secrets
- Type:
string[]ornull - Settings default:
defaults.secrets
Secret environment-variable names granted to this prompt or workflow. Prompt-level secrets replace workflow-level secrets (no merging). Use null to explicitly disable an inherited grant array; inline !NAME references in prompt text remain authoritative grants. Not substituted: Secret grant approval is keyed to authored grant names.
endCondition
- Type: End condition or
null - Settings default:
defaults.endCondition
End condition validation to run after this prompt completes. On a step, null (None in the step properties) disables the inherited workflow end condition, even if the workflow defines one. Omitting this field inherits the workflow-level end condition (if any).
preCondition
- Type: Pre-condition or
null - Settings default:
defaults.preCondition
Script gate that runs before the prompt. Determines whether to run the prompt, skip it, or stop the workflow. When set at workflow level, all prompts inherit it unless overridden. On a step, null (None in the step properties) disables an inherited pre-condition.
priorContext
- Type:
"all" | "previous" | "none" | "finalStepAll" | "finalStepPrevious"orinteger[]or{ previous }or Run source - Settings default:
defaults.priorContext
Controls injection of prior prompt outputs into this prompt's text before sending to the AI. 'all' injects all prior queue prompt outputs; 'previous' injects the immediately preceding queue prompt output; 'none' disables injection; 'finalStepAll' injects all previous final-step pass outputs; 'finalStepPrevious' injects the immediately preceding final-step pass output; { previous: N } injects the last N queue outputs before this prompt; an array of integers ([1, 3]) injects specific prompts by 1-based index; or { workflow, run? } imports resolved output from a completed run of another workflow in this workspace. 'workflow' accepts the workflow's name, workflow key, or key without its timestamp suffix; 'run' is an optional run number or stable run reference. When 'run' is omitted, the workflow's latest completed run is used. Addresses never contain local paths. When omitted, no context is injected. Note: combining with resumeSession:true may duplicate context (accepted limitation). Variable substitution: step text accepts {{name}} and resolves at dispatch; unresolved placeholders fail before execution.
Accepted forms:
"all" | "previous" | "none" | "finalStepAll" | "finalStepPrevious"— Keyword shorthand: 'all' = all prior queue prompt outputs, 'previous' = immediately preceding queue prompt output, 'none' = no injection, 'finalStepAll' = all previous final-step pass outputs, 'finalStepPrevious' = immediately preceding final-step pass outputinteger[]— Specific prior prompt numbers to include (1-based, e.g. [1, 3] includes prompts 1 and 3){ previous }— The last N queue prompt outputs before this prompt, oldest first (e.g. { previous: 3 }). Counted relative to the prompt, so it stays correct when steps are inserted or reordered. Like 'previous', steps that produced no output are skipped rather than counted; { previous: 1 } is the same as 'previous'. Inline equivalent: $previous:N.- Run source — Import all resolved queue and final-step output from a completed run of another workflow in this same workspace.
priorContext.previous
- Type:
integer - Required: yes
- Constraints: minimum 1
How many of the most recent earlier outputs to include
priorContextDetail
- Type:
"full" | "summary"orstring
How much prior output to include. 'full' includes the complete bounded transcript; 'summary' includes the authored prompt head, changed files, and text tail. Resolves prompt → workflow. Inline :summary references ($previous:summary, $step:summary:1,3) select summary for that reference. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"full" | "summary"— How much prior output to include. 'full' includes the complete bounded transcript; 'summary' includes the authored prompt head, changed files, and text tail. Resolves prompt → workflow. Inline :summary references ($previous:summary, $step:summary:1,3) select summary for that reference.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
additionalArgs
- Type:
stringornull - Settings default:
defaults.additionalArgs
Additional CLI flags appended to ctrlyoke's standard argument set. ctrlyoke continues to manage model, permissions, workspace dirs, and session flags normally. Tokens are injected before the tool permission args. Applies to all harnesses (copilot-cli, claude-cli, codex-cli, opencode-cli, qwen-cli, antigravity-cli). Flags are harness-specific, so workflow-level additionalArgs apply only to steps that run on the workflow's harness; a step on another harness that omits additionalArgs uses that harness's defaults.additionalArgs setting. On a step, null (None in the step properties) disables additional args even if the workflow or settings define some. Example: "--effort high --max-turns 10"
toolPermissions
- Type:
{ mode?, allowedTools?, deniedTools? }ornull - Settings default:
defaults.toolPermissions
Tool permission overrides for this prompt/workflow. Resolves prompt → workflow → the defaults.toolPermissions setting. Set mode to 'none' to pass no permission flags and rely entirely on the harness's own local configuration; null behaves the same as mode 'none'. Not substituted: Permission posture must match the reviewed value.
Accepted forms:
{ mode?, allowedTools?, deniedTools? }— Per-workflow/prompt tool permission overrides. Follows three-tier precedence: prompt > workflow > thedefaults.toolPermissionssetting.null
toolPermissions.mode
- Type:
"dangerouslyAllowAll" | "allowAll" | "auto" | "custom" | "none"
Permission mode. 'dangerouslyAllowAll' bypasses all restrictions. 'allowAll' auto-grants all but respects the deny list. 'auto' lets the harness's own safety judge approve or block each request; the deny list always blocks, while the allow list pre-approves tools without limiting what runs. Unsupported harnesses run with custom tool permissions and report a warning. Codex auto review can approve sandbox escalations. 'custom' uses allowedTools + deniedTools. 'none' passes no permission flags at all — it does not deny tools; the harness applies whatever permissions are configured in its own local settings (e.g. ~/.claude/settings.json, Copilot CLI config). Not substituted: This structural field or identity value stays as authored.
toolPermissions.allowedTools
- Type:
string[]
Tool patterns to allow (used in custom mode). Currently supported by Copilot CLI, Claude CLI, Qwen Code, and OpenCode. Qwen uses inline granular support. OpenCode delivers permissions through OPENCODE_CONFIG_CONTENT and writes no workspace opencode.json. Codex and Antigravity only support an overall permission mode, not individual tool patterns; Allowed Tools are NOT ENFORCED by those harnesses.
toolPermissions.deniedTools
- Type:
string[]
Tool patterns to deny (takes precedence over allow list). Currently supported by Copilot CLI, Claude CLI, Qwen Code, and OpenCode. Qwen uses inline granular support. OpenCode delivers permissions through OPENCODE_CONFIG_CONTENT and writes no workspace opencode.json. Antigravity only supports an overall permission mode and does NOT ENFORCE Denied Tools. Codex enforces only mcp__<server>__<tool> entries for MCP servers the workflow attaches, passed as that server's disabled_tools; it does NOT ENFORCE shell or other tool patterns.
sandbox
- Type:
booleanornull - Settings default:
defaults.sandbox
Terminal-command containment, separate from tool approval. true turns the harness's sandbox on: terminal commands may write only what sandboxMode allows. false (the shipped defaults.sandbox) turns the harness's sandbox off, overriding a sandbox you enabled in the harness's own settings: Codex gets -s danger-full-access, Claude Code sandbox.enabled: false, Copilot CLI --no-sandbox and Qwen Code --sandbox=false with QWEN_SANDBOX=false; Antigravity CLI and OpenCode have nothing to turn off. An organization or managed policy that forces a sandbox still wins. null (None) passes no sandbox flags, so the harness's own settings apply; with toolPermissions mode none it hands both axes to the harness. When absent, inherits the workflow, then defaults.sandbox. Network access, harness file tools and MCP servers follow each harness's own sandbox policy. Only Codex CLI and Claude Code support true: on Copilot CLI, Antigravity CLI, Qwen Code and OpenCode a true written in the workflow or step fails the step at launch, while one inherited from defaults.sandbox is skipped with a warning and the harness's own settings apply. Not substituted: Permission posture must match the reviewed value.
sandboxMode
- Type:
"workspace-write" | "read-only" - Settings default:
defaults.sandboxMode
How strict sandbox: true is. workspace-write (the default) lets terminal commands write the workspace roots, approved external roots, temp directories and the harness's own caches. read-only lets them write none of the workspace: Codex runs -s read-only (which also covers its file edits), and Claude Code denies Bash writes to the workspace roots, while its built-in Write and Edit tools still follow tool permissions. Has no effect unless sandbox resolves to true. Resolves step → workflow → the defaults.sandboxMode setting. Not substituted: Permission posture must match the reviewed value.
errorBehavior
- Type: Error behavior or
null - Settings default:
defaults.errorBehavior
Internal-error policy for every step phase: pre-conditions, prompts/harnesses, end-conditions, and script steps. Resolves prompt → workflow → the defaults.errorBehavior setting. Worktree setup is outside this policy: setup runs before any step is in flight, so a non-succeeded setup blocks the worktree and the next Run is the recovery gesture. Use null to explicitly disable an inherited policy.
Prompt step
A step that sends a prompt to a harness.
Also includes every field from Execution properties.
type
- Type:
"prompt"
Optional step type discriminator. When omitted, the step is treated as an AI prompt (backwards compatible). Not substituted: This structural field or identity value stays as authored.
name
- Type:
string - Constraints: at most 100 characters
Optional human-readable display label shown in the ctrlyoke dashboard. If omitted, the dashboard shows a truncated preview of the prompt text. Not substituted: This structural field or identity value stays as authored.
enabled
- Type:
booleanorstring
Whether this step executes. A whole-value {{name}} placeholder is coerced to boolean and validated at run start.
Accepted forms:
boolean— Whether this step executes. When omitted, the step is enabled. Set to false to keep the step in the workflow but skip execution.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
color
- Type:
string - Constraints: pattern
^#[0-9a-fA-F]{6}$
Optional authored identity colour for this step. Not substituted: This structural field or identity value stays as authored.
prompt
- Type:
string - Required: yes
The prompt text to send to the AI. Can be either: (1) Final-form prompt text with context references expanded inline before sending — use @path/to/file or @path/to/dir/ for files/directories, and #selection:path:line-line or #sym.<kind>:path:symbol:line-line for file excerpts and symbols. ctrlyoke inserts the kinded #sym.<kind>: form; hand-authored #sym:path:symbol:line-line remains valid and generic. OR (2) A file path to a .prompt.md, .md, or .txt file containing the prompt. File paths are resolved relative to the prompt file's directory, then workspace root, then .ctrlyoke directory. Absolute paths are also supported.
_runtime
- Type: Step runtime
Per-prompt runtime execution metadata (optional, added automatically during execution). Not substituted: This structural field or identity value stays as authored.
Script step
A workflow step that runs a shell script/command with no AI interaction.
type
- Type:
"script" - Required: yes
Step type discriminator. Required, and must be "script", for script steps. Not substituted: This structural field or identity value stays as authored.
name
- Type:
string - Constraints: at most 100 characters
Optional display label shown in the ctrlyoke dashboard. If omitted, the dashboard shows the script text. Not substituted: This structural field or identity value stays as authored. Variable substitution: step text accepts {{name}} and resolves at dispatch; unresolved placeholders fail before execution.
enabled
- Type:
booleanorstring
Whether this step executes. A whole-value {{name}} placeholder is coerced to boolean and validated at run start.
Accepted forms:
boolean— Whether this step executes. When omitted, the step is enabled. Set to false to keep the step in the workflow but skip execution.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
color
- Type:
string - Constraints: pattern
^#[0-9a-fA-F]{6}$
Optional authored identity colour for this step. Not substituted: This structural field or identity value stays as authored.
executionMode
- Type:
"interactive" | "headless"orstring
Where this script step runs. 'interactive' uses a live PTY/TUI; 'headless' runs in the background with output in the Output panel. Pre/end-condition scripts always run headless. Omitting this field inherits the workflow's executionMode, then the defaults.executionMode setting. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"interactive" | "headless"— Where this script step runs. 'interactive' uses a live PTY/TUI; 'headless' runs in the background with output in the Output panel. Pre/end-condition scripts always run headless. Omitting this field inherits the workflow's executionMode, then the defaults.executionMode setting.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
script
- Type:
string - Required: yes
Shell command or path to script. Relative paths are checked in this order: execution directory, workspace root, .ctrlyoke/, then ~/.ctrlyoke/scripts/.
env
- Type: map of
string
Environment map consumed by the script process. Secret references are allowed only as ${secret:NAME} values.
compareSource
- Type:
"stdout" | "stderr" | "exitCode"orstringorstring
Which output the comparison reads. Default: 'exitCode'. 'stdout'/'stderr' compare the trimmed text; 'exitCode' compares the numeric exit code. There is no implicit clean-exit requirement layered onto a text comparison. A whole-value {{name}} placeholder is coerced and validated before dispatch. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"stdout" | "stderr" | "exitCode"orstring— Which output the comparison reads. Default: 'exitCode'. 'stdout'/'stderr' compare the trimmed text; 'exitCode' compares the numeric exit code. There is no implicit clean-exit requirement layered onto a text comparison. A whole-value{{name}}placeholder is coerced and validated before dispatch.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
timeoutSec
- Type:
numberorstringorstring
Timeout in seconds. When omitted, the execution.scriptTimeoutSec setting applies. A whole-value {{name}} placeholder is coerced and validated before dispatch. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
numberorstring— Timeout in seconds. When omitted, theexecution.scriptTimeoutSecsetting applies. A whole-value{{name}}placeholder is coerced and validated before dispatch.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
shell
- Type:
string
Pin the shell that runs this script's inline text. Used only when script is inline text rather than a path to a script file with a known extension. Free-form executable name or path, e.g. "pwsh", "bash", "cmd". Overrides the terminal.shellExecutable setting for this one script; falls back to it, then platform auto-detect, when omitted. Variable substitution: step text accepts {{name}} and resolves at dispatch; unresolved placeholders fail before execution.
errorBehavior
- Type: Error behavior or
null
Internal-error policy for this script step when it cannot run or evaluation breaks. Use null to explicitly disable an inherited workflow policy.
secrets
- Type:
string[]ornull
Secret environment-variable names granted to this script step. Use null to explicitly disable an inherited grant array. Not substituted: Secret grant approval is keyed to authored grant names.
onPass
- Type:
"continue" | "stopWorkflow"orstring
What to do when the script passes (exit 0 / returns matches). 'continue': advance the queue (default). 'stopWorkflow': halt execution immediately. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"continue" | "stopWorkflow"— What to do when the script passes (exit 0 / returns matches). 'continue': advance the queue (default). 'stopWorkflow': halt execution immediately.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
onFail
- Type:
"continue" | "stopWorkflow"orstring
What to do when the script fails or returns is not matched. 'continue': log a warning and advance the queue. 'stopWorkflow': halt execution (default). A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"continue" | "stopWorkflow"— What to do when the script fails or returns is not matched. 'continue': log a warning and advance the queue. 'stopWorkflow': halt execution (default).stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
_runtime
- Type: Step runtime
Per-step runtime execution metadata (optional, added automatically during execution). Not substituted: This structural field or identity value stays as authored.
operator
- Type:
"eq" | "ne" | "contains" | "notContains" | "gte" | "gt" | "lte" | "lt" | "matches" | "isEmpty" | "isNotEmpty"orstringorstring
How the compare source is compared against expected. Default: 'eq' (whole-value literal match on trimmed text; numeric when compareSource is exitCode). 'contains'/'notContains' are substring tests. 'gte'/'gt'/'lte'/'lt' are numeric and fail when either side is not a number. 'matches' treats expected as an unanchored regular expression — add ^ and $ to require a full match. Every matches comparison runs in a worker bounded by execution.regexTimeoutSec; a timeout is an evaluation error handled by errorBehavior. 'isEmpty'/'isNotEmpty' take no expected. Use word tokens such as gte and ne; operator: >= and operator: != are YAML parse errors. A whole-value {{name}} placeholder is coerced and validated before dispatch. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"eq" | "ne" | "contains" | "notContains" | "gte" | "gt" | "lte" | "lt" | "matches" | "isEmpty" | "isNotEmpty"orstring— How the compare source is compared againstexpected. Default: 'eq' (whole-value literal match on trimmed text; numeric when compareSource is exitCode). 'contains'/'notContains' are substring tests. 'gte'/'gt'/'lte'/'lt' are numeric and fail when either side is not a number. 'matches' treatsexpectedas an unanchored regular expression — add ^ and $ to require a full match. Everymatchescomparison runs in a worker bounded byexecution.regexTimeoutSec; a timeout is an evaluation error handled byerrorBehavior. 'isEmpty'/'isNotEmpty' take noexpected. Use word tokens such asgteandne;operator: >=andoperator: !=are YAML parse errors. A whole-value{{name}}placeholder is coerced and validated before dispatch.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
expected
- Type:
stringornumber
Value the compare source is compared against. Omit it to pass when the script exits 0 — there is no boolean form, and 'true'/'false' are not accepted as exit-code values. Omitting it while compareSource or operator states a comparison is allowed but ignores that comparison and still falls back to exit code 0; the dashboard flags this as a warning rather than refusing the workflow. Variable substitution: step text accepts {{name}} and resolves at dispatch; unresolved placeholders fail before execution.
ignoreCase
- Type:
booleanorstringorstring
Compare text case-insensitively. Applies only to eq/ne/contains/notContains. Default: false. A whole-value {{name}} placeholder is coerced and validated before dispatch. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
booleanorstring— Compare text case-insensitively. Applies only to eq/ne/contains/notContains. Default: false. A whole-value{{name}}placeholder is coerced and validated before dispatch.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
returns
- Type: removed
Removed — renamed to expected, and 'true'/'false' are no longer mapped onto exit codes. Omit it entirely to pass on exit code 0.
Parallel group
An authored group of prompt or script steps. Groups are flattened into steps plus parallelGroups when loaded. Members share the workflow's workspace and its one managed or named worktree; ctrlyoke does not isolate members or merge their work, so give each member independent work. The queue.maxParallelSteps setting caps how many members run at once. Groups cannot be nested, and finalStep cannot be a group. A numeric priorContext or sessionId in a member cannot point at another member of the same group, and two members cannot resolve to the same harness session. Members may use the built-in ctrlyoke MCP server.
steps:
- parallel:
- name: inspect-api
prompt: Inspect the API surface.
- name: inspect-ui
prompt: Inspect the dashboard surface.
failFast: trueSee Dynamic workflows: parallel groups for what a member can do through the ctrlyoke MCP server.
parallel
- Type: array of (Prompt step or Script step)
- Required: yes
- Constraints: at least 2 item(s)
The prompt or script steps that run concurrently. Groups cannot be nested. Not substituted: This structural field or identity value stays as authored.
failFast
- Type:
boolean - Default:
true
Stop the remaining members as soon as one member fails. Default: true. Not substituted: This structural field or identity value stays as authored.
Pre-condition
Script gate that runs before the prompt. Determines whether to run the prompt, skip it, or stop the workflow.
Also includes every field from Shared script fields.
mcpLiteralEnvKeys
- Type:
string[]
Internal provenance for MCP supplied literal env values.
script
- Type:
string - Required: yes
Shell command or path to script. Relative paths are checked in this order: execution directory, workspace root, .ctrlyoke/, then ~/.ctrlyoke/scripts/.
env
- Type: map of
string
Environment map consumed by the script process. Secret references are allowed only as ${secret:NAME} values.
compareSource
- Type:
"stdout" | "stderr" | "exitCode"orstring
Which output the comparison reads. Default: 'exitCode'. 'stdout'/'stderr' compare the trimmed text; 'exitCode' compares the numeric exit code. There is no implicit clean-exit requirement layered onto a text comparison. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"stdout" | "stderr" | "exitCode"— Which output the comparison reads. Default: 'exitCode'. 'stdout'/'stderr' compare the trimmed text; 'exitCode' compares the numeric exit code. There is no implicit clean-exit requirement layered onto a text comparison.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
returns
- Type: removed
Removed — renamed to expected, and 'true'/'false' are no longer mapped onto exit codes. Omit it entirely to pass on exit code 0.
timeoutSec
- Type:
numberorstring
Timeout in seconds. When omitted, the execution.scriptTimeoutSec setting applies. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
number— Timeout in seconds. When omitted, theexecution.scriptTimeoutSecsetting applies.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
shell
- Type:
string
Pin the shell that runs this script's inline text. Used only when script is inline text rather than a path to a script file with a known extension. Free-form executable name or path, e.g. "pwsh", "bash", "cmd". Overrides the terminal.shellExecutable setting for this one script; falls back to it, then platform auto-detect, when omitted. Variable substitution: step text accepts {{name}} and resolves at dispatch; unresolved placeholders fail before execution.
operator
- Type:
"eq" | "ne" | "contains" | "notContains" | "gte" | "gt" | "lte" | "lt" | "matches" | "isEmpty" | "isNotEmpty"orstring
How the compare source is compared against expected. Default: 'eq' (whole-value literal match on trimmed text; numeric when compareSource is exitCode). 'contains'/'notContains' are substring tests. 'gte'/'gt'/'lte'/'lt' are numeric and fail when either side is not a number. 'matches' treats expected as an unanchored regular expression — add ^ and $ to require a full match. Every matches comparison runs in a worker bounded by execution.regexTimeoutSec; a timeout is an evaluation error handled by errorBehavior. 'isEmpty'/'isNotEmpty' take no expected. Use word tokens such as gte and ne; operator: >= and operator: != are YAML parse errors. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"eq" | "ne" | "contains" | "notContains" | "gte" | "gt" | "lte" | "lt" | "matches" | "isEmpty" | "isNotEmpty"— How the compare source is compared againstexpected. Default: 'eq' (whole-value literal match on trimmed text; numeric when compareSource is exitCode). 'contains'/'notContains' are substring tests. 'gte'/'gt'/'lte'/'lt' are numeric and fail when either side is not a number. 'matches' treatsexpectedas an unanchored regular expression — add ^ and $ to require a full match. Everymatchescomparison runs in a worker bounded byexecution.regexTimeoutSec; a timeout is an evaluation error handled byerrorBehavior. 'isEmpty'/'isNotEmpty' take noexpected. Use word tokens such asgteandne;operator: >=andoperator: !=are YAML parse errors.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
expected
- Type:
stringornumber
Value the compare source is compared against. Omit it to pass when the script exits 0 — there is no boolean form, and 'true'/'false' are not accepted as exit-code values. Omitting it while compareSource or operator states a comparison is allowed but ignores that comparison and still falls back to exit code 0; the dashboard flags this as a warning rather than refusing the workflow. Variable substitution: step text accepts {{name}} and resolves at dispatch; unresolved placeholders fail before execution.
ignoreCase
- Type:
booleanorstring
Compare text case-insensitively. Applies only to eq/ne/contains/notContains. Default: false. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
boolean— Compare text case-insensitively. Applies only to eq/ne/contains/notContains. Default: false.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
onPass
- Type:
"continue" | "skipPrompt" | "stopWorkflow"orstring
What to do when the pre-condition check passes (script exits 0 / returns matches). 'continue': run the prompt (default). 'skipPrompt': skip this prompt and advance the queue. 'stopWorkflow': halt execution. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"continue" | "skipPrompt" | "stopWorkflow"— What to do when the pre-condition check passes (script exits 0 / returns matches). 'continue': run the prompt (default). 'skipPrompt': skip this prompt and advance the queue. 'stopWorkflow': halt execution.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
onFail
- Type:
"continue" | "skipPrompt" | "stopWorkflow"orstring
What to do when the pre-condition check fails. 'continue': run the prompt anyway (pre-condition is advisory). 'skipPrompt': skip this prompt and advance the queue (default). 'stopWorkflow': halt execution. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"continue" | "skipPrompt" | "stopWorkflow"— What to do when the pre-condition check fails. 'continue': run the prompt anyway (pre-condition is advisory). 'skipPrompt': skip this prompt and advance the queue (default). 'stopWorkflow': halt execution.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
End condition
Validation that runs after the prompt completes. Shares script/env/compareSource/operator/expected/timeoutSec with preCondition and scriptStep via scriptProperties.
Also includes every field from Shared script fields.
mcpLiteralEnvKeys
- Type:
string[]
Internal provenance for MCP supplied literal env values.
script
- Type:
string - Required: yes
Shell command or path to script. Relative paths are checked in this order: execution directory, workspace root, .ctrlyoke/, then ~/.ctrlyoke/scripts/.
env
- Type: map of
string
Environment map consumed by the script process. Secret references are allowed only as ${secret:NAME} values.
compareSource
- Type:
"stdout" | "stderr" | "exitCode"orstring
Which output the comparison reads. Default: 'exitCode'. 'stdout'/'stderr' compare the trimmed text; 'exitCode' compares the numeric exit code. There is no implicit clean-exit requirement layered onto a text comparison. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"stdout" | "stderr" | "exitCode"— Which output the comparison reads. Default: 'exitCode'. 'stdout'/'stderr' compare the trimmed text; 'exitCode' compares the numeric exit code. There is no implicit clean-exit requirement layered onto a text comparison.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
returns
- Type: removed
Removed — renamed to expected, and 'true'/'false' are no longer mapped onto exit codes. Omit it entirely to pass on exit code 0.
timeoutSec
- Type:
numberorstring
Timeout in seconds. When omitted, the execution.scriptTimeoutSec setting applies. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
number— Timeout in seconds. When omitted, theexecution.scriptTimeoutSecsetting applies.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
shell
- Type:
string
Pin the shell that runs this script's inline text. Used only when script is inline text rather than a path to a script file with a known extension. Free-form executable name or path, e.g. "pwsh", "bash", "cmd". Overrides the terminal.shellExecutable setting for this one script; falls back to it, then platform auto-detect, when omitted. Variable substitution: step text accepts {{name}} and resolves at dispatch; unresolved placeholders fail before execution.
operator
- Type:
"eq" | "ne" | "contains" | "notContains" | "gte" | "gt" | "lte" | "lt" | "matches" | "isEmpty" | "isNotEmpty"orstring
How the compare source is compared against expected. Default: 'eq' (whole-value literal match on trimmed text; numeric when compareSource is exitCode). 'contains'/'notContains' are substring tests. 'gte'/'gt'/'lte'/'lt' are numeric and fail when either side is not a number. 'matches' treats expected as an unanchored regular expression — add ^ and $ to require a full match. Every matches comparison runs in a worker bounded by execution.regexTimeoutSec; a timeout is an evaluation error handled by errorBehavior. 'isEmpty'/'isNotEmpty' take no expected. Use word tokens such as gte and ne; operator: >= and operator: != are YAML parse errors. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"eq" | "ne" | "contains" | "notContains" | "gte" | "gt" | "lte" | "lt" | "matches" | "isEmpty" | "isNotEmpty"— How the compare source is compared againstexpected. Default: 'eq' (whole-value literal match on trimmed text; numeric when compareSource is exitCode). 'contains'/'notContains' are substring tests. 'gte'/'gt'/'lte'/'lt' are numeric and fail when either side is not a number. 'matches' treatsexpectedas an unanchored regular expression — add ^ and $ to require a full match. Everymatchescomparison runs in a worker bounded byexecution.regexTimeoutSec; a timeout is an evaluation error handled byerrorBehavior. 'isEmpty'/'isNotEmpty' take noexpected. Use word tokens such asgteandne;operator: >=andoperator: !=are YAML parse errors.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
expected
- Type:
stringornumber
Value the compare source is compared against. Omit it to pass when the script exits 0 — there is no boolean form, and 'true'/'false' are not accepted as exit-code values. Omitting it while compareSource or operator states a comparison is allowed but ignores that comparison and still falls back to exit code 0; the dashboard flags this as a warning rather than refusing the workflow. Variable substitution: step text accepts {{name}} and resolves at dispatch; unresolved placeholders fail before execution.
ignoreCase
- Type:
booleanorstring
Compare text case-insensitively. Applies only to eq/ne/contains/notContains. Default: false. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
boolean— Compare text case-insensitively. Applies only to eq/ne/contains/notContains. Default: false.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
maxRetries
- Type:
-1orintegerorstring
Maximum number of retry attempts. -1 means unlimited. 0 means no retries by default, or 1-100 for a specific limit. When onPass or onFail is 'retry' and this field is omitted, one retry is allowed. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
-1orinteger— Maximum number of retry attempts.-1means unlimited. 0 means no retries by default, or 1-100 for a specific limit. When onPass or onFail is 'retry' and this field is omitted, one retry is allowed.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
retryPrompt
- Type:
string
Template for retry prompt. Supports $preCondition:<field> and $endCondition:<field> for condition output fields (stdout, stderr, exitCode, actual, expected, compareSource). $preCondition:* works in the step and retry prompts; $endCondition:* is only available in the retry prompt.
passRetryPrompt
- Type:
string
Template for the prompt sent after the end condition passes and onPass is 'retry'. Supports $preCondition:<field> and $endCondition:<field> for condition output fields (stdout, stderr, exitCode, actual, expected, compareSource); both prefixes are substituted on a pass retry. If omitted, the step's own prompt is re-sent.
resumeSessionOnRetry
- Type:
boolean
Whether retries continue in the same session. Default: true (retries resume the existing session for context continuity). Set to false to start a fresh session for each retry.
onPass
- Type:
"continue" | "retry" | "stopWorkflow"orstring
What to do when the end condition passes. 'continue': advance to the next step (default). 'retry': re-run the step's prompt while the condition keeps passing, up to maxRetries; exhausting the retries advances to the next step. A failure during the loop is handled by onFail. 'stopWorkflow': halt execution immediately. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"continue" | "retry" | "stopWorkflow"— What to do when the end condition passes. 'continue': advance to the next step (default). 'retry': re-run the step's prompt while the condition keeps passing, up to maxRetries; exhausting the retries advances to the next step. A failure during the loop is handled by onFail. 'stopWorkflow': halt execution immediately.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
onFail
- Type:
"continue" | "retry" | "stopWorkflow"orstring
What to do when end condition fails. 'retry': re-run the AI prompt (up to maxRetries times); if retryPrompt is omitted, a fallback prompt includes the expected and actual values and script output. When maxRetries is omitted, one retry is allowed. 'continue': advance to the next step even if validation fails. 'stopWorkflow': halt execution (default). A retryPrompt alone does not enable retries; set maxRetries above 0 on the condition or in defaults.endCondition.maxRetries, or use onFail: retry. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"continue" | "retry" | "stopWorkflow"— What to do when end condition fails. 'retry': re-run the AI prompt (up to maxRetries times); if retryPrompt is omitted, a fallback prompt includes the expected and actual values and script output. When maxRetries is omitted, one retry is allowed. 'continue': advance to the next step even if validation fails. 'stopWorkflow': halt execution (default). A retryPrompt alone does not enable retries; set maxRetries above 0 on the condition or in defaults.endCondition.maxRetries, or use onFail: retry.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
Condition presets
Author-defined condition preset available to MCP steps.
Also includes every field from Shared script fields.
script
- Type:
string - Required: yes
Shell command or path to script. Relative paths are checked in this order: execution directory, workspace root, .ctrlyoke/, then ~/.ctrlyoke/scripts/.
env
- Type: map of
string
Environment map consumed by the script process. Secret references are allowed only as ${secret:NAME} values.
compareSource
- Type:
"stdout" | "stderr" | "exitCode"orstring
Which output the comparison reads. Default: 'exitCode'. 'stdout'/'stderr' compare the trimmed text; 'exitCode' compares the numeric exit code. There is no implicit clean-exit requirement layered onto a text comparison. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"stdout" | "stderr" | "exitCode"— Which output the comparison reads. Default: 'exitCode'. 'stdout'/'stderr' compare the trimmed text; 'exitCode' compares the numeric exit code. There is no implicit clean-exit requirement layered onto a text comparison.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
returns
- Type: removed
Removed — renamed to expected, and 'true'/'false' are no longer mapped onto exit codes. Omit it entirely to pass on exit code 0.
timeoutSec
- Type:
numberorstring
Timeout in seconds. When omitted, the execution.scriptTimeoutSec setting applies. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
number— Timeout in seconds. When omitted, theexecution.scriptTimeoutSecsetting applies.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
shell
- Type:
string
Pin the shell that runs this script's inline text. Used only when script is inline text rather than a path to a script file with a known extension. Free-form executable name or path, e.g. "pwsh", "bash", "cmd". Overrides the terminal.shellExecutable setting for this one script; falls back to it, then platform auto-detect, when omitted. Variable substitution: step text accepts {{name}} and resolves at dispatch; unresolved placeholders fail before execution.
operator
- Type:
"eq" | "ne" | "contains" | "notContains" | "gte" | "gt" | "lte" | "lt" | "matches" | "isEmpty" | "isNotEmpty"orstring
How the compare source is compared against expected. Default: 'eq' (whole-value literal match on trimmed text; numeric when compareSource is exitCode). 'contains'/'notContains' are substring tests. 'gte'/'gt'/'lte'/'lt' are numeric and fail when either side is not a number. 'matches' treats expected as an unanchored regular expression — add ^ and $ to require a full match. Every matches comparison runs in a worker bounded by execution.regexTimeoutSec; a timeout is an evaluation error handled by errorBehavior. 'isEmpty'/'isNotEmpty' take no expected. Use word tokens such as gte and ne; operator: >= and operator: != are YAML parse errors. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"eq" | "ne" | "contains" | "notContains" | "gte" | "gt" | "lte" | "lt" | "matches" | "isEmpty" | "isNotEmpty"— How the compare source is compared againstexpected. Default: 'eq' (whole-value literal match on trimmed text; numeric when compareSource is exitCode). 'contains'/'notContains' are substring tests. 'gte'/'gt'/'lte'/'lt' are numeric and fail when either side is not a number. 'matches' treatsexpectedas an unanchored regular expression — add ^ and $ to require a full match. Everymatchescomparison runs in a worker bounded byexecution.regexTimeoutSec; a timeout is an evaluation error handled byerrorBehavior. 'isEmpty'/'isNotEmpty' take noexpected. Use word tokens such asgteandne;operator: >=andoperator: !=are YAML parse errors.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
expected
- Type:
stringornumber
Value the compare source is compared against. Omit it to pass when the script exits 0 — there is no boolean form, and 'true'/'false' are not accepted as exit-code values. Omitting it while compareSource or operator states a comparison is allowed but ignores that comparison and still falls back to exit code 0; the dashboard flags this as a warning rather than refusing the workflow. Variable substitution: step text accepts {{name}} and resolves at dispatch; unresolved placeholders fail before execution.
ignoreCase
- Type:
booleanorstring
Compare text case-insensitively. Applies only to eq/ne/contains/notContains. Default: false. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
boolean— Compare text case-insensitively. Applies only to eq/ne/contains/notContains. Default: false.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
maxRetries
- Type:
-1orintegerorstring
Maximum number of retry attempts. -1 means unlimited. 0 means no retries by default, or 1-100 for a specific limit. When onPass or onFail is 'retry' and this field is omitted, one retry is allowed. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
-1orinteger— Maximum number of retry attempts.-1means unlimited. 0 means no retries by default, or 1-100 for a specific limit. When onPass or onFail is 'retry' and this field is omitted, one retry is allowed.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
retryPrompt
- Type:
string
Template for retry prompt. Supports $preCondition:<field> and $endCondition:<field> for condition output fields (stdout, stderr, exitCode, actual, expected, compareSource). $preCondition:* works in the step and retry prompts; $endCondition:* is only available in the retry prompt.
passRetryPrompt
- Type:
string
Template for the prompt sent after the end condition passes and onPass is 'retry'. Supports $preCondition:<field> and $endCondition:<field> for condition output fields (stdout, stderr, exitCode, actual, expected, compareSource); both prefixes are substituted on a pass retry. If omitted, the step's own prompt is re-sent.
resumeSessionOnRetry
- Type:
boolean
Whether retries continue in the same session. Default: true (retries resume the existing session for context continuity). Set to false to start a fresh session for each retry.
onPass
- Type:
"continue" | "retry" | "skipPrompt" | "stopWorkflow"
Action when the condition passes. Valid actions depend on whether the preset is used as an end condition or pre-condition.
onFail
- Type:
"continue" | "retry" | "skipPrompt" | "stopWorkflow"
Action when the condition fails. Valid actions depend on whether the preset is used as an end condition or pre-condition.
params
- Type:
string[]
Environment-variable names whose values MCP agents may supply when attaching this preset. Not substituted: Parameter names are an author-only contract with condition presets.
Shared script fields
Shared script execution properties used by endCondition, preCondition, and scriptStep.
script
- Type:
string - Required: yes
Shell command or path to script. Relative paths are checked in this order: execution directory, workspace root, .ctrlyoke/, then ~/.ctrlyoke/scripts/.
env
- Type: map of
string
Environment map consumed by the script process. Secret references are allowed only as ${secret:NAME} values.
compareSource
- Type:
"stdout" | "stderr" | "exitCode"orstring
Which output the comparison reads. Default: 'exitCode'. 'stdout'/'stderr' compare the trimmed text; 'exitCode' compares the numeric exit code. There is no implicit clean-exit requirement layered onto a text comparison. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"stdout" | "stderr" | "exitCode"— Which output the comparison reads. Default: 'exitCode'. 'stdout'/'stderr' compare the trimmed text; 'exitCode' compares the numeric exit code. There is no implicit clean-exit requirement layered onto a text comparison.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
returns
- Type: removed
Removed — renamed to expected, and 'true'/'false' are no longer mapped onto exit codes. Omit it entirely to pass on exit code 0.
timeoutSec
- Type:
numberorstring
Timeout in seconds. When omitted, the execution.scriptTimeoutSec setting applies. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
number— Timeout in seconds. When omitted, theexecution.scriptTimeoutSecsetting applies.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
shell
- Type:
string
Pin the shell that runs this script's inline text. Used only when script is inline text rather than a path to a script file with a known extension. Free-form executable name or path, e.g. "pwsh", "bash", "cmd". Overrides the terminal.shellExecutable setting for this one script; falls back to it, then platform auto-detect, when omitted. Variable substitution: step text accepts {{name}} and resolves at dispatch; unresolved placeholders fail before execution.
operator
- Type:
"eq" | "ne" | "contains" | "notContains" | "gte" | "gt" | "lte" | "lt" | "matches" | "isEmpty" | "isNotEmpty"orstring
How the compare source is compared against expected. Default: 'eq' (whole-value literal match on trimmed text; numeric when compareSource is exitCode). 'contains'/'notContains' are substring tests. 'gte'/'gt'/'lte'/'lt' are numeric and fail when either side is not a number. 'matches' treats expected as an unanchored regular expression — add ^ and $ to require a full match. Every matches comparison runs in a worker bounded by execution.regexTimeoutSec; a timeout is an evaluation error handled by errorBehavior. 'isEmpty'/'isNotEmpty' take no expected. Use word tokens such as gte and ne; operator: >= and operator: != are YAML parse errors. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"eq" | "ne" | "contains" | "notContains" | "gte" | "gt" | "lte" | "lt" | "matches" | "isEmpty" | "isNotEmpty"— How the compare source is compared againstexpected. Default: 'eq' (whole-value literal match on trimmed text; numeric when compareSource is exitCode). 'contains'/'notContains' are substring tests. 'gte'/'gt'/'lte'/'lt' are numeric and fail when either side is not a number. 'matches' treatsexpectedas an unanchored regular expression — add ^ and $ to require a full match. Everymatchescomparison runs in a worker bounded byexecution.regexTimeoutSec; a timeout is an evaluation error handled byerrorBehavior. 'isEmpty'/'isNotEmpty' take noexpected. Use word tokens such asgteandne;operator: >=andoperator: !=are YAML parse errors.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
expected
- Type:
stringornumber
Value the compare source is compared against. Omit it to pass when the script exits 0 — there is no boolean form, and 'true'/'false' are not accepted as exit-code values. Omitting it while compareSource or operator states a comparison is allowed but ignores that comparison and still falls back to exit code 0; the dashboard flags this as a warning rather than refusing the workflow. Variable substitution: step text accepts {{name}} and resolves at dispatch; unresolved placeholders fail before execution.
ignoreCase
- Type:
booleanorstring
Compare text case-insensitively. Applies only to eq/ne/contains/notContains. Default: false. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
boolean— Compare text case-insensitively. Applies only to eq/ne/contains/notContains. Default: false.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
Error behavior
Policy for internal errors in any step phase, including pre-conditions, prompts/harnesses, end-conditions, and script steps. Worktree setup is outside this policy: setup runs before any step is in flight, so a non-succeeded setup blocks the worktree and the next Run is the recovery gesture.
onError
- Type:
"stopWorkflow" | "retry" | "retryPhase" | "continue"orstring - Required: yes
What to do when a step phase cannot run or otherwise encounters an internal error. 'stopWorkflow': fail the step and stop the workflow (default). 'retry': re-run the whole step from its pre-condition, starting a fresh harness session. 'retryPhase': re-run only the phase that errored — an errored end-condition re-runs just its script against the existing response without another AI call, and a failed prompt is re-sent in a fresh harness session without re-running the pre-condition; for pre-conditions and script steps it behaves like 'retry'. 'continue': proceed as if the phase had not errored and record a warning. Each phase keeps its own retry count. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
"stopWorkflow" | "retry" | "retryPhase" | "continue"— What to do when a step phase cannot run or otherwise encounters an internal error. 'stopWorkflow': fail the step and stop the workflow (default). 'retry': re-run the whole step from its pre-condition, starting a fresh harness session. 'retryPhase': re-run only the phase that errored — an errored end-condition re-runs just its script against the existing response without another AI call, and a failed prompt is re-sent in a fresh harness session without re-running the pre-condition; for pre-conditions and script steps it behaves like 'retry'. 'continue': proceed as if the phase had not errored and record a warning. Each phase keeps its own retry count.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
maxRetries
- Type:
integerorstring
Maximum retry attempts when onError is retry or retryPhase. When omitted, one retry is allowed. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
integer— Maximum retry attempts when onError is retry or retryPhase. When omitted, one retry is allowed.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
retryDelaySec
- Type:
numberorstring
Delay before retrying, in seconds. A whole-value {{name}} placeholder is coerced and validated before dispatch.
Accepted forms:
number— Delay before retrying, in seconds.stringmatching^\{\{\w+\}\}$— A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.
Prompt Markdown frontmatter
The optional YAML frontmatter block at the top of a .prompt.md file. ctrlyoke reads only the fields listed here and ignores any other key, so a prompt file written for another tool (for example a GitHub Copilot prompt file with model, tools or agent) still loads. The block is never sent to the harness, whether the file runs on its own or a step's prompt names it.
schemaVersion
- Type:
integer - Constraints: minimum 1
Workflow definition format version. Absent means format 1. An older ctrlyoke refuses to load a file with a newer version. Not substituted: This structural field or identity value stays as authored.
name
- Type:
string
Workflow display name used when the file runs on its own (cut to 100 characters). If omitted, the file name without .prompt.md is used. It is display metadata only and is never sent to the harness. Not substituted: This structural field or identity value stays as authored.
description
- Type:
string
Short summary of the prompt. When the file runs on its own, it becomes the step's name in the dashboard (cut to 100 characters). It is display metadata only and is never sent to the harness.
Worktree
Where the workflow runs: the working checkout or a Git worktree.
- Type:
falseortrueorstringor{ mode: "managed", merge?, keep?, … }or{ mode: "named", branch, directory?, … }
Accepted forms:
false— No worktree: the workflow runs directly in the ordinary workspace checkout, sharing it with your own edits.true— Managed-worktree shorthand.string— Named-worktree branch shorthand. The value must be a valid local Git branch name.{ mode: "managed", merge?, keep?, … }— Managed creates a throw-away worktree and branch per run and removes the directory when the workflow completes, leaving the branch for review; pick it for isolated runs you will not follow up on.{ mode: "named", branch, directory?, … }— Named targets a persistent worktree you own, which ctrlyoke never commits, merges, or removes; pick it for conversational workflows you will append to.
When mode is "managed":
worktree.merge
- Type:
boolean
Merge the managed branch into the captured source checkout after the run. Not substituted: This structural field or identity value stays as authored.
worktree.keep
- Type:
boolean
Keeps the managed worktree directory after the run instead of removing it. Without it, appending a follow-up prompt recreates the directory from the branch; ignored files such as node_modules are gone and the setup command runs again, so a long setup pays that cost on every append. Removing the directory also ends filesystem undo for that run. Not substituted: This structural field or identity value stays as authored.
worktree.base
- Type:
string - Constraints: at least 1 character(s)
Optional Git ref resolved to a commit when the worktree is created.
worktree.setup
- Type:
string
Optional setup command run after a new managed worktree is created. Setup is outside the step-scoped errorBehavior policy: it runs before any step is in flight, so a non-succeeded setup blocks the worktree and the next Run re-runs it; a succeeded outcome is skipped.
When mode is "named":
worktree.branch
- Type:
string - Required: yes
- Constraints: at least 1 character(s)
Local Git branch name for the named worktree.
worktree.directory
- Type:
string - Constraints: at least 1 character(s) · pattern
^(?:~[/\\].*|/.*|[A-Za-z]:[/\\].*|\\\\.*|[^/\\]+)$
Optional long-lived directory for this named worktree, so one directory can hold different branches over time. Use an absolute path, a ~-prefixed path, or a bare name with no slash or backslash; relative paths containing separators are rejected. A bare name reuses the registered linked worktree whose directory has that exact name (or the directory ctrlyoke derived for a branch of that name); otherwise ctrlyoke creates the directory as <worktree root>/<name>, with no hash suffix, or as <worktrees.root>/<repository>-<hash>/<name> when the shared worktrees.root setting is set. When branch differs from the branch the directory holds, ctrlyoke switches it only when it is clean and never switches it back. Omit to derive the directory from the branch.
worktree.base
- Type:
string - Constraints: at least 1 character(s)
Optional Git ref resolved to a commit when the worktree is created.
worktree.setup
- Type:
string
Optional setup command run in the named worktree at the start of every run, such as npm ci to pick up dependency changes since the last run. Resuming or continuing a run whose setup already succeeded does not run it again. Omit it for no setup. Setup is outside the step-scoped errorBehavior policy: it runs before any step is in flight, so a failed setup blocks the worktree and the next Run re-runs it.
Variables
Workflow-level variable defaults for {{varName}} substitution. CLI --var key=value flags override these at runtime. Substituted at run start: defaults.worktree.base, defaults.worktree.branch, defaults.worktree.directory, harness, maxSteps, steps[].enabled, steps[].harness, worktree.base, worktree.branch, worktree.directory. Substituted at dispatch: defaults.worktree.setup, endCondition.compareSource, endCondition.env.*, endCondition.ignoreCase, endCondition.maxRetries, endCondition.onFail, endCondition.onPass, endCondition.operator, endCondition.passRetryPrompt, endCondition.retryPrompt, endCondition.script, endCondition.timeoutSec, errorBehavior.maxRetries, errorBehavior.onError, errorBehavior.retryDelaySec, executionMode, hooks[].command, hooks[].env.*, preCondition.compareSource, preCondition.env.*, preCondition.ignoreCase, preCondition.onFail, preCondition.onPass, preCondition.operator, preCondition.script, preCondition.timeoutSec, priorContextDetail, resumeSession, scriptStep.env.*, scriptStep.script, steps[].additionalArgs, steps[].agent, steps[].compareSource, steps[].errorBehavior.maxRetries, steps[].errorBehavior.onError, steps[].errorBehavior.retryDelaySec, steps[].executionMode, steps[].expected, steps[].ignoreCase, steps[].model, steps[].name, steps[].onFail, steps[].onPass, steps[].operator, steps[].priorContext.run, steps[].priorContext.workflow, steps[].prompt, steps[].sessionId, steps[].shell, steps[].skills[], steps[].timeoutSec, worktree.setup. Fields without a steps[] prefix (executionMode, errorBehavior.*, preCondition.*, endCondition.* and the rest) are substituted in the effective value, so they cover a placeholder authored on a step, the finalStep, the workflow root or a settings default. Values are validated against the field schema after substitution. Excluded fields include approval and permission settings, MCP server definitions, condition preset contracts, vars themselves, and structural or identity fields.
- Type: map of
string
Hook entry
One user-defined hook in a hooks array.
event
- Type:
"stop" | "sessionStart" | "preToolUse" | "postToolUse" | "userPromptSubmit" | "permissionRequest" | "notification" | "error" - Required: yes
Logical hook event. Unsupported events for the active harness are silently skipped. 'stop' maps to Stop (Claude/Qwen/Antigravity), Stop (Codex), agentStop (Copilot). 'notification' maps to Notification (Claude/Qwen), notification (Copilot), and is n/a for Codex/Antigravity/OpenCode.
command
- Type:
string - Required: yes
Command to execute. Resolved relative to workspace root if not absolute.
env
- Type: map of
string
Each hook receives only its own env values, merged over the harness environment when it runs. These values are not added to the harness process environment, but are written to a per-step temp file readable by the local user, so they are not hidden from a model with shell access. Secret references are allowed only as ${secret:NAME} values.
timeoutSec
- Type:
integer - Constraints: minimum 1
Maximum time a user hook may run, in seconds. Applied by Copilot, Claude Code, Codex, Qwen Code, Antigravity, and OpenCode; harnesses that do not support per-hook timeouts use their own limit.
MCP server entry
User-defined MCP server configuration. Exactly one of command (stdio) or url (remote) must be set. The built-in ctrlyoke server is configured by its ID and can use deniedTools to disable selected built-in tools.
id
- Type:
string - Required: yes
Unique server identifier
description
- Type:
string
Human-readable description shown in MCP Manager. ctrlyoke-only metadata — deliberately omitted by every harness export path so it never leaks an unrecognized key into an external tool's native config file.
command
- Type:
string
Command to run the MCP server process (stdio servers, e.g. "npx" or "node")
args
- Type:
string[]
Arguments to pass to the command (stdio servers only)
env
- Type: map of
string
Environment variables for the server process (stdio servers only)
autoApprove
- Type:
booleanorstring[]
Tools to auto-approve from this MCP server: true = all tools, string[] = tool names. For Copilot CLI, server IDs must not match built-in permission kinds or contain whitespace, parentheses, or commas, and tool names must not contain parentheses or commas.
url
- Type:
string
Remote endpoint URL for streamable-http or SSE servers (e.g. "https://mcp.example.com")
transport
- Type:
"streamable-http" | "sse"
Transport protocol for remote servers. Defaults to "streamable-http".
headers
- Type: map of
string
HTTP headers to send with every request (remote servers only, e.g. { "Authorization": "Bearer token" }). Secret references are allowed as ${secret:NAME} values.
deniedTools
- Type:
string[]
Tool names from this server to deny at execution time. Use bare tool names without the mcp__<serverid>__ prefix (e.g. ["append_step"]). Translated to mcp__<id>__<tool> deny patterns and merged into the harness permission args. Supported on harnesses that accept tool deny patterns.
Run source
Selects another workflow's completed run for priorContext imports.
workflow
- Type:
string - Required: yes
- Constraints: at least 1 character(s)
The workflow to import from, in this workspace: its workflow key (Copy Workflow Key in the workflow list's context menu), its name, or its key without the timestamp suffix. Names are matched case-insensitively, and a name shared by several workflows is an error at execution, so use the key to be exact.
run
- Type:
integerorstring
Which run of the workflow to import: its number, or its run reference. Omit it to use the workflow's latest completed run, which moves on as new runs complete. A run named here cannot be deleted while a workflow references it. A string placeholder resolves at dispatch and must become an integer or stable run reference.
Accepted forms:
integer— The run's number, as shown in the run list.stringmatching^(run-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z|\{\{\w+\}\})$— The run's stable run reference. May also be one whole{{name}}placeholder, validated after substitution.
Harness IDs
The harnesses a workflow or step can select.
- Type:
"copilot-cli" | "claude-cli" | "codex-cli" | "opencode-cli" | "qwen-cli" | "antigravity-cli"
Template metadata
Authoring metadata for a reusable workflow template. Removed when the template is instantiated.
name
- Type:
string
Display name shown in the template picker. Not substituted: This structural field or identity value stays as authored.
description
- Type:
string
Short explanation shown in the template picker.
variables
- Type: map of Template variable
Metadata for placeholders used by this template, keyed by variable name.
Template variable
One entry in _templateMeta.variables.
type
- Type:
"text" | "file" | "directory" | "select" | "harness" | "model"
Control used to collect this variable in the template dialog. A model variable shows the models of the harness variable named by harness, beside that harness picker. Not substituted: This structural field or identity value stays as authored.
harness
- Type:
string - Constraints: pattern
^[a-z][a-zA-Z0-9]*$
For a model variable: the name of the harness variable whose models it offers. Changing that harness resets this model to the harness's default model.
fileFilter
- Type:
string[]
File-picker glob patterns used by file variables.
options
- Type:
string[] - Constraints: at least 1 item(s)
Available values for a select variable.
autoFillFilename
- Type:
boolean
Use the selected file or directory basename as the initial workflow name.
description
- Type:
string
Help text shown below the variable control.
default
- Type:
string
Initial value used when the user leaves the variable unchanged.
multiline
- Type:
boolean
Render a text variable as a multiline input.
required
- Type:
boolean
Require a non-blank value for this variable before creating a workflow.
Template placeholder
A template variable placeholder such as {harness}. Only accepted in authoring files that declare _templateMeta.
- Type:
string - Constraints: pattern
^\{[a-z][a-zA-Z0-9]*\}$