Create reusable workflows

A workflow is a saved set of instructions that Orek can reuse for different tasks. You choose the steps, what each step needs from earlier work, and where to ask for approval. For example, review a different folder each time without rewriting your review process.

When a workflow runs, Orek starts its steps in the order the template sets and passes results between them. Models carry out each step but do not choose the steps or their order. Their answers and tool calls can still vary, so a workflow does not guarantee the same or a successful result. For a checklist the agent updates as it works, see Track multi-step work.

Quickstart: run a built-in workflow

List your saved templates and the built-in workflows (code_audit, deep_research, and adversarial_verify) inside Orek:

/workflow list

The interface also calls these templates recipes. Run a built-in workflow such as code_audit from the composer with %:

%code_audit Focus on src/auth and report any session-handling bugs.

1. Open your project

Start Orek in the project you want to work on, with a model configured. See Quickstart if you need to set that up. Select the model you want with /model before starting a workflow.

A workflow works directly in your project’s files, like any subagent, so it runs in any project folder, with or without Git and with or without uncommitted changes. Its steps change your files as they go.

2. Save a template

Create .orek/workflows/review_change.toml in your project and paste this template. It inspects a target, runs two independent reviews, and combines their findings. The first step asks you to confirm the target and focus.

name = "review_change"
description = "Review a target for correctness and security, then combine findings."

[budget]
max_tokens = 200000
max_children = 6
max_concurrency = 2
timeout_secs = 900

[[steps]]
id = "inspect"
agent = "explore"
task = "Inspect {{args.target}} with focus on {{args.focus}}. Identify relevant files and summarize how they connect. Do not edit files."
gate = "Review {{args.target}} with focus on {{args.focus}}?"

[[steps]]
id = "correctness"
agent = "reviewer"
task = "Review {{args.target}} for correctness issues related to {{args.focus}}. Use the inspection notes, check the source, and cite file locations."
needs = ["inspect"]
input_from = ["inspect"]

[[steps]]
id = "security"
agent = "reviewer"
task = "Review {{args.target}} for security issues related to {{args.focus}}. Use the inspection notes, check the source, and cite file locations."
needs = ["inspect"]
input_from = ["inspect"]

[[steps]]
id = "report"
agent = "reviewer"
task = "Combine both reviews. Remove duplicate findings, rank the remaining issues, and explain what was checked. Do not claim tests ran unless a result demonstrates it."
needs = ["correctness", "security"]
input_from = ["correctness", "security"]

The limits in this example are starting values you can change, not a price estimate; Limits and retries explains what they count.

Run /workflow list to check that review_change appears with four steps. Orek reloads template files whenever you list or start a workflow; a run that has already started keeps the version it started with.

Where to save workflows

A template replaces a lower-priority or built-in workflow with the same name. Files can be TOML, JSON, or YAML (.toml, .json, .yaml, or .yml), must be at most 256 KiB, and must sit directly in the folder (subfolders are not searched). name sets the name you run it by; without it, Orek uses the file name without the extension.

3. Supply inputs and run it

The example has two inputs: target and focus. Replace src/auth below with a folder or file in your project:

/workflow run review_change Use target "src/auth" and focus "session expiry".

You can also start a message with % and the workflow name:

%review_change Use target "src/auth" and focus "session expiry".

Press Tab to complete a name. /workflows run works the same as /workflow run. The request goes to the selected conversation and waits if that conversation is busy.

The text after the name is an instruction to the agent, which then calls run_workflow; it is not parsed as command-line flags. To spell out several inputs exactly, you can write:

Run the saved review_change workflow with run_workflow. Use these arguments:
{"name":"review_change","args":{"target":"src/auth","focus":"session expiry"}}
Keep the saved steps and limits.

Check the run_workflow tool card and the step’s approval prompt to confirm the target and focus values before approving.

How inputs work

Orek replaces {{args.<key>}} (or {{<key>}}) in each step’s task and gate text with the matching value from args.

Supply every input the template uses. Orek does not check for required inputs or their types, and a missing value can leave the placeholder in the text.

Use flat input names such as target and focus; there are no loops, conditions, or nested fields. Steps the agent passes directly to run_workflow, instead of from a saved file, are used as written, without input substitution.

Choose order and pass results

Each step needs a unique id and a non-empty task. Use needs to list the steps that must finish successfully first. The order of steps in the file does not make one wait for another.

Use input_from to include an earlier step’s answer in the next step’s instruction. It also makes the step wait for that answer, even without a matching needs entry. needs alone waits without passing the answer.

Orek runs steps in rounds: every step whose dependencies are done starts together, up to max_concurrency, and the next round starts when the round finishes. Circular and self-dependencies are rejected. If a step fails, steps that depend on it do not run, and results from independent steps remain available. Keep step answers focused so the text passed through input_from fits in the next request.

Choose roles and a model

The agent field sets the step’s profile. Use a built-in profile (explore, reviewer, tester, or edit) or one configured under agent.subagent_profiles; any other name is an error. See Choose a profile and Configure named profiles. Enabled provider web tools are available to steps of every profile. A profile’s tool list is not a security boundary; the session’s approval settings and permission rules still apply.

A workflow file has no per-step model or reasoning_effort key. Each step uses the model and reasoning_effort set on its profile ([agent.subagent_profiles.<name>]), or else the conversation’s model and reasoning settings when the run starts. A resumed run keeps those settings even if you have since switched models.

The approval mode, Plan mode, the execution policy, and compaction settings are not saved with a run. Steps always follow the session’s current settings, so changing a mode during a run, for example with /permissions or /plan, affects steps already running, and a resumed run follows the settings of the session that resumes it. While Plan mode is on, blocked tool calls fail as denied approvals, and Orek does not retry them.

Add an editing step

You can append this step to the example. It waits for the report, asks for approval, and then edits your project:

[[steps]]
id = "fix"
agent = "edit"
task = "Fix the confirmed issues from the report in {{args.target}}. Keep changes focused and run the relevant tests. Report changes and test results."
needs = ["report"]
input_from = ["report"]
gate = "Apply the confirmed fixes to {{args.target}}?"

Give parallel editing steps separate files so their edits do not collide. Stopping, pausing, or failing a run does not undo files a step already changed, so review the diff and test results before committing.

Workflows do not skip the usual tool approvals: a step asks for approval the same way any agent does, and the prompt names the step’s agent. Only gate approvals are recorded with the run. Other agents can message, stop, or resume a workflow’s agents like any other subagent.

Limits and retries

Set limits for the whole run in [budget]:

• Timeouts (timeout_secs): include time spent queued, waiting for subagents, between retries, and at tool approval prompts. The clock stops while the run is paused or waiting only on a step gate.
• Token budget (max_tokens): checked between model requests, so a request already in progress can go over. If a provider does not report usage, Orek flags it instead of counting it as zero. Pausing and resuming keeps the running total.

A step can also set its own time limit and number of attempts. Add these lines inside its [[steps]] block:

timeout_secs = 300
retry = { max_attempts = 2 }

max_attempts is the total number of attempts for the step (default 3: the first run plus two retries). Orek retries only temporary failures and never automatically repeats an interrupted command or external action.

When a step’s answer must have a particular shape, give it a result_schema written as JSON Schema. For example, require a text summary:

result_schema = { type = "object", required = ["summary"], properties = { summary = { type = "string" } } }

Orek checks the answer and can ask the model to fix its format; that request allows no tool calls. This checks the answer’s structure, not whether its claims are true. It is separate from the template’s inputs, which have no schema.

A schema without $schema is read as JSON Schema Draft 7. Declare $schema to use another draft, such as Draft 2020-12. format values such as date are checked, and $ref must point inside the same schema.

Inspect, approve, pause, and resume

Open /workflows to browse runs and their steps, or manage runs with /workflow:

Open a step’s tool card with /detail, or use /detail list to find an earlier result. If a run was paused while a gate was pending, approve the request first and then resume the run.

While a pause, resume, cancel, or approval you started is still finishing, /clear, resuming another session from /sessions, and /setup are refused with a notice naming the run. Try again once it finishes.

Quitting Orek, clearing or switching the conversation, ending orek run, or closing an editor session pauses active workflows. Reopen the conversation with /sessions and run /workflow resume <run-id>. Resuming a workflow also resumes any workflow it started.

Completed, failed, and cancelled runs cannot be resumed. Start a new run to try again or to use different inputs.

When something goes wrong

When an interrupted step resumes:

• File reads, MCP resource reads, and interrupted file edits continue automatically; the step re-reads any file whose edit was interrupted.
• Shell commands, Python runs, and MCP tool calls interrupted mid-call stop the run, because Orek cannot tell whether they already had an effect, even when the MCP server marks the tool as read-only. Check your project before starting a new run.
• Tool calls with unreadable arguments keep their recorded error instead of running again.

Workflow files describe a fixed set of steps. They do not support conditional branches, loops, or adding steps based on an earlier answer. There is no orek workflow shell command; use the commands above, or ask the agent to use run_workflow in a headless request.

Next steps

• Track multi-step work for an evolving checklist.
• Delegate to subagents for individual delegated tasks.
• Manage sessions to find and reopen prior work.