Skip to content

Workflow files ​

ctrlyoke supports three file formats:

FormatExtensionBest use
YAML.ctrlyoke.yaml, .ctrlyoke.ymlMulti-step workflows written by hand
JSON.ctrlyoke.jsonGenerated workflows and automation
Markdown.prompt.mdSingle prompt files

Current schema shape ​

The current multi-step schema uses steps, not prompts.

yaml
harness: copilot-cli
steps:
  - prompt: Review @src/
finalStep:
  prompt: Summarize the result and any follow-up work.

Main workflow building blocks ​

  • root-level execution defaults such as harness, model, and toolPermissions
  • a steps array containing prompt steps, script steps, and parallel groups
  • an optional finalStep
  • runtime metadata added automatically during execution

A one-step workflow can also skip steps and put a single prompt step (or a type: script step) directly at the root:

yaml
harness: claude-cli
prompt: Review @src/ and list the riskiest modules.

Read the format-specific pages next:

Sharing a workflow ​

A workflow file is an ordinary file in your repository. Commit it, or copy it to another machine or repository, and it runs there too, as long as the files it refers to come along. A workflow you saved from the dashboard may also have a sibling <workflow>.assets/ folder holding its pasted images and other attachments. Keep the two together. See Durable workflows and generated files.

Sharing the workflow file shares the definition, not its runs. To share what a run did, export it with ctrlyoke export; see Exporting a run.

Paths relative to the workflow file ​

How a path in a workflow resolves depends on where it appears:

PathResolves from
@, #selection: or #sym: path starting ./ or ../The workflow file's folder
Any other relative @, #selection: or #sym: pathThe workspace root
A step prompt that is a file path (./… or ../…)The workflow file's folder, then the workspace root, then .ctrlyoke/
A script, end condition or pre-condition scriptThe run's folder, the workspace root, .ctrlyoke/, then ~/.ctrlyoke/scripts/

So to keep a workflow and the files it attaches together, put the files next to the workflow and refer to them with ./:

yaml
steps:
  - prompt: Implement the screen in @./mockups/login.png following @./spec.md.

A ./ reference needs a workflow file to resolve against. In a workflow you've built in the dashboard and not saved yet, it fails with "This reference is relative to the workflow file, which has no known location." In a worktree run, it resolves from the same folder inside the worktree.

Scripts are looked up from the workspace, not the workflow file. Keep shared scripts in .ctrlyoke/scripts/ and commit them; a script in your own ~/.ctrlyoke/scripts/ stays on your machine. An absolute path only works on machines with the same folders. See How scripts run and Where paths resolve.

What travels with the repository ​

Under .ctrlyoke/, the files you write are meant to be committed: templates/, scripts/, agents/, skills/, mcp/servers.json and settings.json. What ctrlyoke generates for itself is ignored by the generated .ctrlyoke/.gitignore and stays on your machine, including pasted attachments and saved prompts.

These never travel with a workflow, so each person sets them up on their own machine:

  • the harness CLIs, and signing in to them
  • user settings in ~/.ctrlyoke/settings.json, and agents, skills and MCP servers saved in your home folder
  • secret values
  • run history and favorites
  • your approvals, below

Approvals stay on each machine ​

A shared file can only request access. Each person approves it once on their own machine, and the answer is stored in their home folder, never in the workflow or the workspace:

  • A workflow's trustedExternalRoots are approved per folder, for that workflow file in that workspace. Moving or renaming the file, or the workspace folder, asks again. See Trusted external folders.
  • Secret grants are approved per name for the workspace, so another workflow in the same workspace can use an approved name without asking. See Approving grants.
  • Workspace settings that run a program, such as a hook or an MCP server in the workspace's .ctrlyoke/settings.json, are approved per exact value. A changed value asks again. See Settings that run programs.

On a CI runner, approve them up front with the trust-* commands and --yes (see Running in CI).

Apart from secret grants and external folders, what the workflow file itself contains needs no approval. Running a workflow runs its steps, scripts, end conditions, hooks and MCP servers. Read a workflow you got from someone else before you run it.

Source-available under the ctrlyoke Commercial License.