Skip to content

YAML format ​

YAML is the most readable way to author multi-step workflows by hand.

The YAML schema flags unknown keys as editor squiggles when the Red Hat YAML extension is version 1.20 or newer. Older versions still provide ordinary YAML and type checking, but do not recognize the schema's unknown-key closures.

Example ​

yaml
name: Reliability pass
harness: copilot-cli
model: claude-sonnet-5.5

steps:
  - name: inspect
    prompt: |
      Inspect @src/core/ and identify the biggest reliability risk.

  - name: verify-workspace
    type: script
    script: npm test
    compareSource: exitCode
    expected: 0
    onFail: stopWorkflow

  - name: implement
    resumeSession: true
    prompt: |
      Fix the issue you identified and update any directly related docs.

finalStep:
  prompt: |
    Review the completed work for obvious edge cases.

Root-level fields you will use first ​

FieldPurpose
nameWorkflow name shown in the dashboard; defaults to the file name
harnessSelect the harness
modelOverride the harness model
stepsOrdered list of work to run
finalStepPrompt or script that runs after the queue
varsWorkflow-level variables for {{name}} substitution
trustedExternalRootsWorkflow-scoped external directory access

Workflow-scoped external roots ​

trustedExternalRoots lists the folders outside the workspace this workflow may use. Each new root needs a one-time approval on your machine before it takes effect.

yaml
trustedExternalRoots:
  - C:/Users/me/.codex/sessions

See Trusted external folders.

Prompt step fields you will use first ​

FieldPurpose
nameHuman-readable label in the dashboard
promptInline prompt text or a path to .prompt.md, .md, or .txt
resumeSessionContinue the previous compatible session
sessionIdResume a step's session (1), an exact ID, or finalStep
endConditionValidate after the step completes
preConditionGate before the step runs

A prompt value is read as a file path only when the whole value is a path that starts with ./, ../, or an absolute path, or in a multi-root workspace a path that starts with a workspace folder name (for example prompt: ./prompts/review.prompt.md). The file is looked up next to the workflow file first, then in the workspace root, then in .ctrlyoke/. Anything else, including prompts/review.prompt.md without the ./, is sent as inline prompt text.

A leading ! in a prompt step is sent to the AI as prompt text; ctrlyoke does not treat it as a harness shell escape. To run a command, use a script step. A prompt that starts with a secret grant such as !API_TOKEN is not affected: the grant works as usual and the editor doesn't warn about it.

How step properties inherit ​

Most step fields can also be set once at the root of the workflow. These are the execution properties: harness, model, executionMode, agent, skills, secrets, resumeSession, sessionId, mcpServers, hooks, endCondition, preCondition, priorContext, additionalArgs, toolPermissions and errorBehavior. A step takes each one from the first level that sets it:

  1. the step itself
  2. the workflow root
  3. the matching defaults.* setting, such as defaults.executionMode or defaults.models. See Settings.
yaml
harness: claude-cli
model: sonnet
executionMode: headless

steps:
  - name: plan
    model: opus
    prompt: Write a plan for the change to plan.md.
  - name: implement
    prompt: Implement plan.md.
  - name: review
    executionMode: interactive
    prompt: Walk me through the change.

Here plan runs on opus and the other two on sonnet. Only review opens a terminal.

The winning value is used as a whole. Lists and objects such as skills, mcpServers and toolPermissions are not merged with the levels below. The one exception is hooks: a step's hooks replace the workflow's hooks only for the events the step lists.

Leaving a field out vs null ​

Leaving a field out means "inherit". Setting it to null, on a step or at the root, means "none" and stops inheritance from the levels below:

yaml
agent: reviewer
mcpServers: [github]

steps:
  - name: draft
    prompt: Draft the release notes.
  - name: format
    agent: null # no agent for this step
    mcpServers: null # and no MCP servers
    prompt: Reformat CHANGELOG.md.

agent, skills, secrets, mcpServers, hooks, endCondition, preCondition, additionalArgs and errorBehavior accept null. toolPermissions: null is the same as mode: none: ctrlyoke passes no permission flags. Fields that only take a value, such as model, executionMode and resumeSession, have no null; set the value you want instead. In the dashboard, null is the None option in the step's properties.

Where settings defaults come in ​

When you open a workflow file, ctrlyoke makes its own working copy (your file is not changed) and fills in the current defaults.* value for each root field the file leaves out. Those values show in Workflow Properties, and the run uses them. A settings change therefore applies the next time you open the file. It doesn't change a workflow that is already open, or a run you continue.

defaults.errorBehavior works only this way: it is copied into a new workflow, not looked up while the run is going. See Error handling.

A root toolPermissions that sets only some of mode, allowedTools and deniedTools gets the missing ones from defaults.toolPermissions. A step's toolPermissions doesn't. See Permissions.

Steps on another harness ​

Model names and command-line flags differ from one harness to the next, so model and additionalArgs at the root apply only to steps that run on the workflow's own harness. A step on another harness that leaves them out uses that harness's defaults.models and defaults.additionalArgs values instead:

yaml
harness: claude-cli
model: sonnet

steps:
  - prompt: Plan the change. # sonnet
  - harness: codex-cli
    prompt: Implement the plan. # defaults.models for codex-cli
  - harness: codex-cli
    model: gpt-6-sol
    prompt: Review the change. # gpt-6-sol

The step's properties show which one applies. Inherit (…) means the step takes the workflow's value. Default (…) means it takes the settings default for its own harness. Picking a harness for a step clears the step's model and additional arguments, so they follow the rule above until you choose new ones.

model: none ​

model: none (None (harness default) in the model picker) passes no model flag, so the harness uses its own default model: whatever you have configured in that harness's CLI. It is the out-of-the-box value of defaults.models for every harness, so a new workflow shows it until you pick a model. Inside Inherit (…) and on the footer's model button it reads Harness default. Also use it when you pass the model yourself in additionalArgs, for example a custom model string your harness accepts. Each harness page has a Model selection section listing where its models come from.

executionMode ​

interactive runs the step in a terminal on the Terminal tab; headless runs it in the background. It inherits like the fields above, with two exceptions: pre-conditions and end conditions always run headless, and ctrlyoke run without a terminal runs every step headless. See Interactive and headless.

resumeSession ​

resumeSession defaults to true through defaults.resumeSession, so each step continues the previous step's conversation on the same harness. Set resumeSession: false on a step, or at the root for every step, to start fresh. See Session management.

additionalArgs ​

additionalArgs is a string of extra flags for the harness command, such as --effort high. ctrlyoke still manages the model, permission, folder and session flags; your flags go in before the permission flags. Set it to null on a step to drop arguments inherited from the workflow or settings.

Changing additionalArgs from one step to the next means the harness has to start again: the next step can't be typed into the previous step's terminal, so it gets a new one. See What happens when a step ends.

A defaults.additionalArgs value in a workspace settings file needs your approval first. See Workspace settings that run programs.

Step-only fields: enabled and color ​

enabled and color belong to one step and are never inherited:

  • enabled: false keeps the step in the workflow but skips it when the workflow runs. Leaving it out means the step runs.
  • color sets the step's identity colour as a hex value, such as color: "#4f9dff". It overrides the Harness and Unique colour modes, and isn't shown when step colours are off. See Step colours.

Script steps ​

Set type: script to run a shell command or script file as a step, with no AI involved:

yaml
steps:
  - name: lint
    type: script
    script: npm run lint
    onFail: stopWorkflow

See Script steps and condition scripts.

Parallel steps ​

A parallel queue item runs a flat group of prompt or script steps concurrently before the next queue item starts:

yaml
steps:
  - parallel:
      - prompt: Research the authentication flow.
      - prompt: Research the data model.

See Parallel steps.

Source-available under the ctrlyoke Commercial License.