Templates
Templates are reusable workflow skeletons with fill-in-the-blank variables. ctrlyoke ships these built-in templates: Blank, Template Starter, Simple Feature, Parallel Research, Fix Tests, Full Feature Pipeline, Spec-Driven Loop, Feature-Driven Loop, Bug Hunt Loop, and Bug Drain Loop. You can add your own templates under .ctrlyoke/templates/ in the workspace or under ~/.ctrlyoke/templates/ for your user account. When you run New Workflow from Template, ctrlyoke prompts for each variable, substitutes the values, and creates a ready-to-run workflow.
Choose Spec-Driven Loop when you already have a spec or design document. Feature-Driven Loop starts from a description, writes an implementation plan to .ctrlyoke/plans/plan.md, then uses the same self-extending orchestration pattern.
Spec-Driven Loop asks for a testCommand (default npm test), which every queued step is told to pass and the review uses as its main gate, and a harness and model for each of two roles. The orchestrator runs the plan step and the review final step, which resumes the plan step's session, so both always use the same harness. Both run in interactive mode so you can watch and steer them. The implementer runs every step the orchestrator queues, each in a fresh headless session. The defaults are opus and sonnet, both on Claude Code, so the template works with only Claude Code installed. To use a different pairing, such as gpt-6-luna on Codex CLI for the implementer, pick it in the dialog and save it as the variable default.
Feature-Driven Loop asks for the same testCommand and the same two harness and model pairs, with the same defaults. Its orchestrator also runs the step that writes the plan, interactively like the plan and review steps.
Full Feature Pipeline asks for a harness and model for its two review steps, which give a second opinion on the plan and on the implementation. The default is gpt-6.1-sol on Codex CLI. Pick a different harness from the one that runs the rest of the workflow, so the reviewer is not the model that wrote the work.
Loops commit every step
Spec-Driven Loop, Feature-Driven Loop, Bug Hunt Loop, and Bug Drain Loop need a git repository, because each step commits its own work. The commits are how a review sees what each step did, and how you roll back a step that went wrong.
- Before it starts, the loop checks that the working tree is clean and stops if it isn't, or if the folder isn't a git repository. Commit or stash your own changes first, or run
git initto start a repository. The bug loops repeat this check at the start of every pass. - After each planning, review, or bug-hunting step, an end condition checks
git status --porcelain. If anything is uncommitted, ctrlyoke resumes that step's session and asks it to finish and commit. After two failed retries, the workflow stops. - After each step the loop queues for itself, the same check runs when the orchestrator attaches it. Each loop declares it as the
committedcondition preset, and the orchestrator attaches it to every queued step that runs on its own. It leaves the check off steps it queues to run in parallel, because those steps share one working tree: one would fail the check on the other's unfinished edits. Steps in a parallel group still commit their own files, and the step after the group or the next review catches anything they left behind.
The test command is not part of the end condition. Agents usually run it themselves, so gating on it as well would run the suite twice per step. To run a loop without git, create a custom template from it with New template... and remove its endCondition, preCondition, and conditions.
Create a workflow from a template
Open the Create Workflow from Template dialog in any of these ways:
- the arrow beside New in the dashboard header, then New From Template...;
- Create from Template in the steps panel of an empty workflow;
- the ctrlyoke: New Workflow from Template command (
Ctrl+Shift+N, orCmd+Shift+Non macOS) in the dashboard.

Pick a template under Template. The list groups Built-in Templates, Custom Templates (Workspace) and Custom Templates (User). It starts on your default template.
Read the description under the picker, then fill in the Variables. Each field's helper text comes from the template, and fields with a
defaultstart filled in. Required fields have a*; Create stays disabled until each has a non-blank value. The control depends on the variable's type:Type Control text A single-line box, or a resizable multi-line box with multiline: true.file, directory A box with a Browse… button. In VS Code it opens your system's file or folder picker. In the browser dashboard it opens a file browser for the workspace. select A dropdown of the template's options.harness The harness picker, showing which harnesses are installed. model (with a harness) A model picker beside its harness, listing that harness's models. Enter a Workflow Name. It is required, and some characters aren't allowed in it.
Click Create to open the new workflow without running it, or Create & Run to start it right away.
Enterin a single-line field creates the workflow, andCtrl+Enterin any text field creates and runs it.
Set as Default, at the right of the Template label, makes the selected template the one the dialog starts on next time. It saves general.defaultTemplate at the scope chosen by the dialog's User/Workspace toggle. When the selected template is already the default, it reads Default template instead, with the scope it comes from when it is a saved setting. See Defaults and blank fields.
New template... under the picker creates a custom template from the selected one. See Custom templates.
Saved variable values
Open Settings → Templates to choose the default template and save variable values for any built-in or custom template. The drawer's User scope stores values for your own use across workspaces; Workspace stores values with the project. When both scopes save the same variable, the Workspace value wins in that workspace. Linked harness and model values are saved together.
Each saved value is used to pre-fill the matching field in New Workflow. Choose Add template and Add value to add a value from Settings, or pin a value while creating a workflow. Blank text clears a saved value. Clear all removes every saved value for that template at the selected scope, returning fields to the other scope or the variable default authored by the template. Missing templates and variables that have since been removed remain visible until cleared, so stale settings can be cleaned up.
Bug Hunt Loop and Bug Drain Loop
Both templates are dynamic workflow loops that keep bug reports as Markdown files in your repo, one file per bug, rather than in an issue tracker. They have no steps up front. Their final step reviews the fixes that landed since its previous pass, then appends new fix steps; the loop ends on the first pass that appends nothing.
| Template | Each pass | Ends when |
|---|---|---|
| Bug Hunt Loop | Finds and files at least two new bugs, then queues fixes for the ones it is confident about | A pass finds nothing, you stop it, or the step limit |
| Bug Drain Loop | Queues fixes for every report already in the backlog directory. Never files new bugs | The backlog is empty |
Both ask for the same directories, so the hunt can fill a backlog that the drain later clears:
bugBacklogDir(defaultbugs/backlog): where open bug reports are filed.bugImplementedDir(defaultbugs/implemented): where a fix step moves its report once the bug is fixed.
Put a README or template in the backlog directory, or the directory above it, that describes your bug report format. The hunter follows it, so every report has the same sections. Without one, it writes a title, severity, reproduction steps, expected and actual behavior, evidence, and a suggested fix.
Both templates also ask for testCommand, which every queued fix must pass, and a harness and model for each of two roles: the final step that reviews and queues, and the fix steps. Give the final step your most capable model; a cheaper model is usually enough for the fix steps, because each one gets a self-contained description of its fix. The defaults are opus on Claude Code for the final step and gpt-6-luna on Codex CLI for the fixes. Each model picker sits beside its harness and lists that harness's models; changing the harness switches the model to that harness's default model. Bug Hunt Loop has no natural end, so set maxSteps on the workflow or the queue.maxSteps setting if you want to cap how much it runs.
Variables in the body
A variable is a {placeholder} token in a prompt (or any string field). The token form sets its default input type:
| Token in the body | Input type | UI |
|---|---|---|
{name} | text | single-line input |
{text:name} | text | single-line input (explicit) |
{file:name} | file | input with a Browse… button |
Variable names must start with a lowercase letter and contain only letters and digits. Condition output references ($preCondition:<field> and $endCondition:<field>) are runtime values and never treated as template variables. $preCondition:* works in step and retry prompts; $endCondition:* is only available in retry prompts.
The {file:…} / {text:…} inline prefixes only cover those two types. For a directory, select, harness, or model variable, write a plain {name} token in the body and declare its type in _templateMeta (below).
Put a file variable in prompt text as @{file:name}. Keep the @ outside the braces so the substituted value becomes a normal file reference.
Placeholders are allowed in fields that normally accept only fixed values, such as harness: "{harness}", but only in a file that has a _templateMeta block. Quote such values in YAML.
Enriching variables with _templateMeta
A top-level _templateMeta block names the template, describes it, and adds UI metadata to the variables extracted from the body. It is stripped from the generated workflow — it exists only for authoring.
_templateMeta:
name: Full Feature
description: "Plan → Implement → Review → Docs → Commit"
variables:
featureDescription:
type: text
multiline: true
description: What to build — describe the feature or change.
planDocument:
type: text
default: docs/plan.md
description: Path where the plan is written and referenced by later steps.
steps:
- name: plan
prompt: |
{featureDescription}
Write the implementation plan to {planDocument}.
- name: implement
prompt: Implement the feature per @{planDocument}.Variable metadata fields
| Field | Applies to | Effect |
|---|---|---|
type | any | text (default), file, directory, select, harness, or model. |
harness | model | Name of the harness variable whose models this variable offers. Required for model. |
options | select | The dropdown choices (e.g. [debug, info, warn]). The first option is used as the default unless default is set. |
default | any | Pre-fills the input; substituted when the field is left blank. |
description | any | Helper text shown under the input. |
multiline | text | Renders a resizable textarea instead of a single-line input. |
required | any | Requires a non-blank value before a workflow can be created. A default pre-fills the required field. |
fileFilter | file | Glob patterns for the file picker (e.g. ["**/*.md"]). |
autoFillFilename | file, directory | Seeds the new workflow's filename from the picked file/folder basename. Only the first variable that declares it wins. |
Input controls by type: text → single-line input (or textarea with multiline); file → input + Browse (file picker); directory → input + Browse (folder picker); select → dropdown of options; harness → the harness picker (no options needed; defaults to claude-cli when no default is set); model → a model picker on the same row as its harness, listing that harness's models. Changing the harness switches the model to that harness's default model, and a model with no default starts on it too.
Pair a model with its harness so a template can run each role on its own harness and model:
_templateMeta:
variables:
reviewHarness:
type: harness
default: codex-cli
reviewModel:
type: model
harness: reviewHarnessUse both in the body, for example harness: "{reviewHarness}" and model: "{reviewModel}" on the step they configure.
_templateMeta:
variables:
logLevel:
type: select
options: [debug, info, warn, error]
default: info
outputDir:
type: directory
description: Where generated artifacts should be written.A key under _templateMeta.variables only takes effect if a matching {token} exists in the body — the meta block enriches extracted variables, it does not create them.
Fields appear in the dialog in the order their tokens first appear in the body, not the order of _templateMeta.variables. This custom template uses a required multi-line text variable, a directory, a select, and a harness with its model:
_templateMeta:
name: Bug Fix
description: "Fix → Review on a second harness"
variables:
bugReport:
type: text
multiline: true
required: true
description: What is broken, and how to reproduce it.
area:
type: directory
description: Where the bug probably lives.
severity:
type: select
options: [low, medium, high]
reviewHarness:
type: harness
default: codex-cli
reviewModel:
type: model
harness: reviewHarness
steps:
- name: fix
prompt: |
Fix this {severity}-severity bug in @{area}:
{bugReport}
- name: review
harness: "{reviewHarness}"
model: "{reviewModel}"
prompt: Review the fix in $previous and run the tests.
Defaults and blank fields
If a variable declares a default, that value is pre-filled in the UI and used when the field is left empty. A select variable without a default starts on its first option. Blank optional fields become empty text in the generated workflow. Required fields must be filled before creation: the dialog blocks creation, and the API rejects a missing or blank value. A required field with a default is pre-filled.
For optional file variables, avoid writing the placeholder with an @ prefix. When the field is blank, the placeholder becomes empty text and leaves a bare @ in the prompt.
You can save a field's current value as a variable default from the template picker. Once you change a field, Save as default appears at the right of its label. The User/Workspace toggle in the title bar selects where Save as default writes; it also selects where Set as Default writes the default template setting. The toggle starts on Workspace until a save succeeds, then remembers the scope of the last successful save. With no workspace open, it stays on User.
Saved values override the value declared in the template. Workspace values take precedence over User values, which take precedence over the template's authored value. This is resolved per variable, so a template can use some values saved in Workspace and others saved in User. A Saved (User) or Saved (Workspace) marker shows the source, and Clear saved value removes the value from that scope so the next value in the precedence order applies. Saving the value already inherited at the selected scope clears that scope's override instead of keeping a redundant saved value.
A harness and its linked model fields are one unit: they are saved, marked, and cleared together, and resolve from the same scope. The picker draws a box around them, with their shared save or clear action in the box's top edge. Multiline text fields cannot be saved as variable defaults.
Custom templates
Custom templates are *.ctrlyoke.yaml, *.ctrlyoke.yml, or *.ctrlyoke.json files in .ctrlyoke/templates/ (workspace) or ~/.ctrlyoke/templates/ (user). They use the same _templateMeta schema as the built-ins. A file name must be unique within its location, regardless of format.
There are two ways to create one:
- In the template picker, click New template..., or run the Create New Custom Template command, which opens the same form. Choose a name, a location (workspace or user), and a format (YAML or JSON). ctrlyoke copies the currently selected template as the starting point, carrying any saved variable values into the copy as its authored defaults. Select Template Starter first to get an example of every variable type.
- In the Save Workflow dialog, turn on Save as Template. This saves the workflow's current values as-is; edit the file afterward to replace fixed values with
{placeholder}variables.