Skip to content

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:

yaml
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:

  1. A step's own value.
  2. The workflow root.
  3. 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.

SectionPurpose
Workflow fileRoot fields of a multi-step workflow file.
Execution propertiesShared execution configuration properties used across workflow-level defaults, prompt-level overrides, and runtime metadata
Prompt stepA step that sends a prompt to a harness.
Script stepA workflow step that runs a shell script/command with no AI interaction.
Parallel groupAn authored group of prompt or script steps.
Pre-conditionScript gate that runs before the prompt.
End conditionValidation that runs after the prompt completes.
Condition presetsAuthor-defined named conditions available to MCP steps.
Shared script fieldsShared script execution properties used by endCondition, preCondition, and scriptStep.
Error behaviorPolicy for internal errors in any step phase, including pre-conditions, prompts/harnesses, end-conditions, and script steps.
Prompt Markdown frontmatterThe optional YAML frontmatter block at the top of a .prompt.md file.
WorktreeWhere the workflow runs: the working checkout or a Git worktree.
VariablesWorkflow-level variable defaults for {{varName}} substitution.
Hook entryOne user-defined hook in a hooks array.
MCP server entryUser-defined MCP server configuration.
Run sourceSelects another workflow's completed run for priorContext imports.
Harness IDsThe harnesses a workflow or step can select.
Template metadataAuthoring metadata for a reusable workflow template.
Template variableOne entry in _templateMeta.variables.
Template placeholderA 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 ​

The ordered step queue. Each item is a prompt step, a script step, or a parallel group.

finalStep ​

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: -1 or integer or string

Maximum number of entries in the run steps array. A whole-value {{name}} placeholder is coerced and validated at run start.

Accepted forms:

  • -1 or integer — Maximum number of entries in the run's steps array, regardless of who queued them, including parallel members and disabled steps. finalStep iterations and retries are not counted. Omit to inherit queue.maxSteps. -1 means unlimited.
  • string matching ^\{\{\w+\}\}$ — A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.

worktree ​

Run the workflow in the working checkout or in a Git worktree. When omitted, the defaults.worktree setting applies.

vars ​

Default values for {{varName}} substitutions. Not substituted: Variables are not recursively expanded.

conditions ​

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[] or null

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, or ctrlyoke 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 ​

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 ​

Harness to use for this prompt. Determines which AI CLI executes the prompt. Optional - defaults to the defaults.harness setting.

Accepted forms:

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 ​

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.
  • string matching ^\{\{\w+\}\}$ — A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.

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:

  • string matching ^[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 ​

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 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.
  • string matching ^\{\{\w+\}\}$ — A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.

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 (string or { 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 ​

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: string or integer

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 ​

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 ​

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 ​

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 ​

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 ​

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 output
  • integer[] — 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" or string

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.
  • string matching ^\{\{\w+\}\}$ — A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.

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 ​

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 > the defaults.toolPermissions setting.
  • 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 ​

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 ​

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 ​

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: boolean or string

Whether this step executes. A whole-value {{name}} placeholder is coerced to boolean and validated at run start.

Accepted forms:

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 ​

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: boolean or string

Whether this step executes. A whole-value {{name}} placeholder is coerced to boolean and validated at run start.

Accepted forms:

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" or string

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.
  • string matching ^\{\{\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" or string or string

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" or string — 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.
  • string matching ^\{\{\w+\}\}$ — A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.

timeoutSec ​

  • Type: number or string or string

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:

  • number or string — Timeout in seconds. When omitted, the execution.scriptTimeoutSec setting applies. A whole-value {{name}} placeholder is coerced and validated before dispatch.
  • string matching ^\{\{\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 ​

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[] or null

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" or string

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.
  • string matching ^\{\{\w+\}\}$ — A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.

onFail ​

  • Type: "continue" | "stopWorkflow" or string

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).
  • string matching ^\{\{\w+\}\}$ — A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.

_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" or string or string

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" or string — 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.
  • string matching ^\{\{\w+\}\}$ — A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.

expected ​

  • Type: string or number

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: boolean or string or string

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:

  • boolean or string — Compare text case-insensitively. Applies only to eq/ne/contains/notContains. Default: false. A whole-value {{name}} placeholder is coerced and validated before dispatch.
  • string matching ^\{\{\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.

yaml
steps:
  - parallel:
      - name: inspect-api
        prompt: Inspect the API surface.
      - name: inspect-ui
        prompt: Inspect the dashboard surface.
    failFast: true

See Dynamic workflows: parallel groups for what a member can do through the ctrlyoke MCP server.

parallel ​

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" or string

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.
  • string matching ^\{\{\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: number or string

Timeout in seconds. When omitted, the execution.scriptTimeoutSec setting applies. A whole-value {{name}} placeholder is coerced and validated before dispatch.

Accepted forms:

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" or string

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 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.
  • string matching ^\{\{\w+\}\}$ — A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.

expected ​

  • Type: string or number

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: boolean or string

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:

onPass ​

  • Type: "continue" | "skipPrompt" | "stopWorkflow" or string

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.
  • string matching ^\{\{\w+\}\}$ — A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.

onFail ​

  • Type: "continue" | "skipPrompt" | "stopWorkflow" or string

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.
  • string matching ^\{\{\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" or string

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.
  • string matching ^\{\{\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: number or string

Timeout in seconds. When omitted, the execution.scriptTimeoutSec setting applies. A whole-value {{name}} placeholder is coerced and validated before dispatch.

Accepted forms:

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" or string

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 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.
  • string matching ^\{\{\w+\}\}$ — A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.

expected ​

  • Type: string or number

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: boolean or string

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:

maxRetries ​

  • Type: -1 or integer or string

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:

  • -1 or integer — 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.
  • string matching ^\{\{\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" or string

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.
  • string matching ^\{\{\w+\}\}$ — A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.

onFail ​

  • Type: "continue" | "retry" | "stopWorkflow" or string

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.
  • string matching ^\{\{\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" or string

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.
  • string matching ^\{\{\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: number or string

Timeout in seconds. When omitted, the execution.scriptTimeoutSec setting applies. A whole-value {{name}} placeholder is coerced and validated before dispatch.

Accepted forms:

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" or string

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 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.
  • string matching ^\{\{\w+\}\}$ — A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.

expected ​

  • Type: string or number

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: boolean or string

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:

maxRetries ​

  • Type: -1 or integer or string

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:

  • -1 or integer — 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.
  • string matching ^\{\{\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" or string

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.
  • string matching ^\{\{\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: number or string

Timeout in seconds. When omitted, the execution.scriptTimeoutSec setting applies. A whole-value {{name}} placeholder is coerced and validated before dispatch.

Accepted forms:

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" or string

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 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.
  • string matching ^\{\{\w+\}\}$ — A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.

expected ​

  • Type: string or number

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: boolean or string

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:

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" or string
  • 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.
  • string matching ^\{\{\w+\}\}$ — A whole-value workflow variable placeholder. See https://ctrlyoke.dev/docs/workflows/variables#where-substituted.

maxRetries ​

  • Type: integer or string

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:

retryDelaySec ​

  • Type: number or string

Delay before retrying, in seconds. A whole-value {{name}} placeholder is coerced and validated before dispatch.

Accepted forms:

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: false or true or string or { 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: boolean or string[]

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: integer or string

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.
  • string matching ^(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 ​

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]*\}$

Source-available under the ctrlyoke Commercial License.