> ## Documentation Index
> Fetch the complete documentation index at: https://www.plungeai.com/guide/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> A workflow is a file of tasks that oceancode runs in a fixed order: which agent does what, which tasks run at once, where a check or your approval stops the run. No model picks the next step. Five ship with oceancode — Spec, Build, Review, Secure and Research — beside Goal and Race, and you can …


A workflow is a file of tasks that oceancode runs in a fixed order: which agent does what, which tasks run at once,
where a check or your approval stops the run. No model picks the next step. Five ship with oceancode — **Spec**,
**Build**, **Review**, **Secure** and **Research** — beside Goal and Race, and you can write your own or have the
agent write or change one.

## A workflow and a mode

A work mode decides how agents work together on your prompt ([23](/oceancode/work-modes)). A session has two settings, and
they combine:

- Its **mode**, a way of working (`kind: mode`: Model, Auto, Solo, Delegate, Pair, Orchestrate), shapes the lead's
  ordinary turn: which sub-agents it may call, whether it edits, which limits apply. You talk to the lead as usual.
  `F4` sets it.
- Its **workflow setting** is off, Auto, or one workflow (`kind: workflow`). One workflow takes the turn's place.
  **Every prompt you send is one run**: the prompt becomes the run's input (`{input}`), the turn answers at once
  (`spec ×3 — started run <id>`), the tasks run in the background, and the result comes back into the session when
  the run ends (`crates/ocean-session/src/run/workflow/goal.rs:57`). With Auto, Jev picks a workflow for a prompt
  that fits one, and the others run in the mode ([Auto and workflows](#auto-and-workflows)). `/workflows` sets it.

You can run Pair with workflow Auto. What each pair of settings does is in
[23](/oceancode/work-modes#mode-and-workflow-together).

Under one workflow a follow-up question, `/workflow new` or `/workflow edit` starts a run too. To talk to the agent again, turn the
workflow off: `Enter` on **Off** in `/workflows`, or `/mode default`.

## The workflow picker

`/workflows` opens the workflow picker in the prompt's place, the same kind of picker as `F4`
([23](/oceancode/work-modes#picking-a-mode)). Its title reads `Which workflow?`, and the right of the title row names your
way of working: `Mode: <label> · F4 to change`. The rows, in order:

- **Off**: no workflow; your prompts run in your way of working.
- **Auto**: Jev picks a workflow per task, else your way of working ([Auto and workflows](#auto-and-workflows)).
- The built-in workflows Spec, Build, Review, Secure, Research, Goal and Race.
- After a `── yours ──` divider, your own files A–Z ([Writing your own](#writing-your-own)).
- **Build your own…**, last.

The hidden built-ins Pipeline and Implement are not listed, and neither are the engine's `.rhai` scripts
(`deep-research`, `goal`, `pipeline`, a project's `.rhai` files): those still run by name through the `workflow` tool
and `oceancode workflow run <name>` ([21](/oceancode/cli-reference#oceancode-workflow)).

`●` marks the session's setting and `○` the other rows; the cursor opens on the session's setting. `default` tags the
default for new sessions: your `workflow` default when you set one, otherwise Auto when your default way of working is
Auto, otherwise Off. The list sits on the left and the highlighted row's picture on the right; under both, across the
whole width, its description, when to use it and its cost. The footer names the keys that apply to the highlighted
row.

| Key | What it does |
|---|---|
| `↑` / `↓` (`k` / `j`) | Move. The picture and the text follow at once. |
| `Enter` | Turn the row on for this session and close: Auto, or this workflow. `Enter` on Off turns the workflow off. On **Build your own…** it closes and puts `/workflow new ` in the prompt: type what it should do and press Enter ([Three ways to start](#three-ways-to-start)). |
| `d` | Make it the default for new sessions (`workflow` in your user `oceancode.json`). `d` on the current default clears it. |
| `e` | On one of yours, close and put `/workflow edit <name> ` in the prompt ([Changing one](#changing-one)). On a built-in it first writes your copy, `.oceancode/workflows/<name>-copy.yaml`, named `<name>-copy` and labelled `<Label> (copy)`, and puts `/workflow edit <name>-copy ` in the prompt instead; when that copy is already listed as yours, it takes that copy without writing it again. |
| `o` | Close and open the workflow in the editor ([The editor](#editing-by-hand)): one of yours to change by hand, a built-in read-only. On **Build your own…** it opens a starter to write one yourself. |
| `Esc` | Close. |

Typed forms: `/mode spec` (any workflow id) turns that workflow on for this session and leaves your way of working as
it is; `/mode default` clears both settings back to their defaults. `"workflow": "spec"` (or `"auto"`, `"off"`) in
`oceancode.json` makes the default for new sessions; `"mode": "spec"` and `agents.<id>.mode` still work
([02](/oceancode/configuration)). Which one wins: [23](/oceancode/work-modes#mode-and-workflow-together).

## The five

### Spec — research, then a spec you approve

```
        you: task
 ┌────────▼────────┐
 │ Brief · general │
 └────────┬────────┘
   ┌──────┼──────┐
 ┌─▼──┐ ┌─▼──┐ ┌─▼───┐
 │code│ │docs│ │prior│  explore ×3
 └─┬──┘ └─┬──┘ └─┬───┘
   └──────◇──────┘ validate · review ↺ ≤ 2
 ┌────────▼────────┐
 │ Spec ✎ · general│ → .oceancode/plans/
 └────────┬────────┘ ◇ you approve
```

1. **brief** (`general`) restates the task: the goal in one sentence, what is in and out of scope, the questions a
   spec must answer. No code.
2. **research**: three `explore` agents at once, evidence as `path:line` only — **code** (where it is handled, what
   it calls, which tests cover it), **docs** (the rules that apply: `CLAUDE.md`, `AGENTS.md`, `docs/`), **prior**
   (a feature shaped like this one, its tests, its guide page).
3. **validate** (`review`, a verdict) opens every `path:line` and passes only when each says what the scout claims.
   On a failure the three scouts correct their evidence against the findings and validate checks again; two passes at
   most.
4. **spec** (`general`) writes the spec in the plan-file shape — Goal · Research findings · Approach · one fenced
   `todo` block, one buildable step per row · Verification per to-do · Open questions — and saves it as
   `.oceancode/plans/<date>-spec-<run>.md`.
5. **approve**: a question card shows the spec. **Approve** goes on; **Stop** ends the run `blocked · not approved`,
   and the file stays.
6. **report** (`general`): three lines — where the spec is, how many to-dos, and that Build with that path builds it.

Cost ≈ 3–5×. Needs an interactive session. Limits: 4 at once, 20 per turn, depth 1.

### Build — to-dos from the spec, build, tests, review

```
        you: spec path
 ┌─────────▼─────────┐
 │ To-dos · general  │ → the builder's list
 └─────────┬─────────┘
 ┌─────────▼─────────┐
 │ Build ✎ · builder │◀──┐◀──┐
 └─────────┬─────────┘   │   │
           ◇ tests ──fail┘   │ ↺ ≤ 3
 ┌─────────▼─────────┐       │
 │ Review · review   │──fix──┘ ↺ ≤ 2
 └─────────┬─────────┘
           ▼ report · general ──▶ you
```

1. **plan** (`general`) reads the spec your prompt names, else the newest file in `.oceancode/plans/`, and replies
   with its path and its `todo` block (adding a verification line to any row without one). It edits nothing.
2. **build** (`builder`) gets those rows as its to-do list and carries them out in order, running every check the
   spec names. While rows are open it is resumed, three times at most; a row still open fails the run.
3. **tests**, three passes at most: your `test_command` runs, and on a failure `builder` fixes the cause, never the
   test. After the third pass the run goes on with the last result, which review and the report read.
4. **review**, two passes at most: `review` tries to refute the change against the spec — did every row land, is
   anything outside the spec, can every new test fail? — and `builder` fixes those findings, nothing else.
5. **report** (`general`): the files changed, the commands with their pass lines, what is open.

Cost ≈ 2–5×. Needs `test_command` in `oceancode.json`; runs headless. Limits: 4 at once, 30 per turn, depth 2 (the
builder may call a helper such as `explore`).

### Review — three lenses, a judge, a verdict

```
          you: the change
      ┌──────────┼──────────┐
┌─────▼─────┐┌───▼────┐┌────▼────┐
│correctness││ scope  ││  tests  │ review ×3
└─────┬─────┘└───┬────┘└────┬────┘
      └──────────┼──────────┘
             ┌───▼───┐
             │ judge │ merges, evidence only
             └───┬───┘
                 ▼ verdict ──▶ you
```

1. **lenses**: three `review` agents at once, each answering a verdict — **correctness** (it reads the diff, staged
   and unstaged, and the code it touches: the wrong assumption, the missing case, the error path), **scope** (does
   the change do what was asked and only that?), **tests** (can each test fail, does one cover each new branch, is
   any check only claimed?).
2. **verdict** (`judge`): approve, request changes or block in one line, then the findings as `path:line`, worst
   first, without duplicates or anything uncited.

Your prompt names the change and what was asked. Nothing edits. Cost ≈ 3–4×. Runs headless. Limits: 3 at once, 10
per turn, depth 1.

### Secure — threat model, four lenses, a verdict

```
        you: change
 ┌────────▼────────┐
 │ Surface·explore │ inputs, secrets, sinks
 └────────┬────────┘ review ×4 with
   ┌──────┼───────┬──────┐ security-audit
┌──▼───┐┌─▼────┐┌─▼───┐┌─▼────┐
│secret││inject││authz││supply│
└──┬───┘└─┬────┘└─┬───┘└─┬────┘
   └──────┼───────┴──────┘
      ┌───▼───┐
      │ judge │──▶ approve · changes · block
      └───────┘
```

1. **surface** (`explore`) maps the change's attack surface without judging it: every input from outside, secret or
   credential, auth or tenant check, shell, SQL or HTML sink and external call, as `path:line`.
2. **lenses**: four `review` agents at once, each given the `security-audit` skill and answering a verdict —
   **secrets** (keys in code, logs or responses, weak crypto, bad randomness), **injection** (shell, SQL, path
   traversal, templates, unsafe deserialization, XSS: each input traced to its sink), **authz** (authentication,
   authorization and tenant boundaries), **supply** (a new dependency, a changed lockfile, a download or install
   step, an external call the change does not explain).
3. **verdict** (`judge`): approve, request changes or block, then each finding as `path:line` with its exploit path,
   keeping only findings a lens cited with more than 80 % confidence.

Nothing edits. Cost ≈ 4–6×. Runs headless; the lenses want the `security-audit` skill ([Requirements](#requirements)).
Limits: 4 at once, 10 per turn, depth 1.

### Research — a sweep, verified claims, a cited report

```
       you: question
 ┌────────▼────────┐
 │ Plan ≤ 4 asks   │
 └────────┬────────┘
   ┌──────┼──────┐
 ┌─▼──┐ ┌─▼──┐ ┌─▼──┐ researchers, read-only
 │ q1 │ │ q2 │ │ q3 │ claims with sources
 └─┬──┘ └─┬──┘ └─┬──┘
   └──────◇──────┘ verifiers re-check
 ┌────────▼────────┐ every claim
 │ Report · cited  │──▶ you
 └─────────────────┘
```

Research has no tasks of its own: it runs the built-in script `deep-research` (`workflow: deep-research`), which
splits your question into independent ones (four by default), sends one read-only researcher per question for claims
with their sources, has every claim re-checked against its source, and writes a report that cites only what
survived. Its runs are listed as `deep-research`.

Cost ≈ 4–8×. Runs headless. It sets no limits: the workflow bounds apply (`workflows.max_concurrent_agents`,
`workflows.agent_budget`, [02](/oceancode/configuration)).

### Goal, Race and Pipeline

Goal (loop until proven done) and Race (attempts, a judge ranks, you pick) are the two older workflows; they are
described in [23](/oceancode/work-modes#the-modes). Pipeline (spec, your approval, build, review) left the picker: Spec and
Build do its two halves with more checks. It is still built in, and `"mode": "pipeline"` in `oceancode.json` still
runs it; `/mode pipeline` is refused, as `/mode` takes only the picker's ids.

## While it runs

- **The badge.** The prompt's top border, at the left after the agent, names the workflow and how many agents its first parallel task runs —
  `spec ×3`, `build`, `review ×3`, `secure ×4`, `research` — and, while a run is active, the task it is on:
  `spec ×3 · validate` (`crates/ocean-protocol/src/diagram.rs:841`).
- **The transcript row.** `Workflow spec: <your prompt>  [brief ✓ · research ● …]` follows the tasks as they start
  (`✓` done, `●` running) and ends as `Workflow spec done in 2m: …`, `failed`, `cancelled` or `paused`.
- **The dock.** Its Workflows section (`Workflows 1`) lists each running run with its agents beneath it; open an
  agent's row to watch it ([19](/oceancode/tui#watching-a-sub-agent)).
- **Workflow Runs.** `/workflow runs` opens the runs pane (a text overview in minimal mode); `/workflow pause`,
  `resume` and `stop` control a run, and a paused or stopped run keeps its journal, so it can be resumed
  (see [After a crash or an exit](#after-a-crash-or-an-exit)).
- **Question cards.** An `approve` task puts a card in the prompt's place: *Approve?*, the result it shows (Spec's
  spec), and the options Approve and Stop. A `pick` task (Race) lists the attempts in the judge's order with its
  reasons, and None. `1`–`9` choose ([19](/oceancode/tui#question-cards)).
- **The hand-back.** When the run ends, its status and its last task's output land in the session as a `<workflow>`
  message, and the agent is woken to read it, so the session's next answer is the run's result. A headless
  `oceancode run` whose turn started a workflow waits for it and prints that answer before it exits. A workflow that
  cannot run here answers your prompt at once with the reason and starts nothing.

## After a crash or an exit

A run keeps its state in its own folder, `<data dir>/workflows/<run id>/`, as it goes:

- `journal.jsonl`: one line per finished agent (and per command, copy and question), written to disk before the
  script moves on. An agent of a `parallel` task is written as soon as it and the agents before it have returned,
  not when the whole task ends (`crates/ocean-workflow/src/engine.rs:599`).
- `run.json`: what a resume needs, written at the start: the script, its args, the project and the model
  (`crates/ocean-session/src/run/workflow/launcher.rs:101`).
- `snapshot.json`: the status and the agents the runs pane shows.

So a run survives Ocean Code ending, whether you quit, close the terminal or the process is killed. Resume it from
the same project in any later Ocean Code: in a session, ask the agent to resume the run (its `workflow` tool takes
the run id); headless, run `oceancode workflow resume <run id>`. Every agent in the journal returns its saved
result without a model call; the work that was cut off runs again, from the first agent with no line in the
journal. A run resumed from a session reports into that session from then on: its progress and its result land
where you asked, not in the session that started it. `oceancode workflow resume` has no session, so its run keeps
reporting to the session it last reported to. A run left `active` by a crash shows as `interrupted` in `oceancode workflow runs` and resumes the same
way as a paused one.

Ocean Code refuses a resume, and says why, when:

- the run is complete;
- the run belongs to another project;
- it is still running: a live run holds `run.lock` in its folder, so one run never runs twice at once
  (`crates/ocean-session/src/run/workflow/launcher.rs:152`);
- its project copies are gone: a run that used `isolate: copy` or `copy_project()` needs them, and copies are
  removed when a run ends and a day after a run was left. Start the workflow again
  (`crates/ocean-session/src/run/workflow/launcher.rs:1062`).

A run does not resume by itself: a crashed run waits until you resume it, so nothing spends money unasked. A command
or an agent that was cut off may have done part of its work before the crash; it runs again from the start.

## Requirements

| Workflow | Needs | Headless |
|---|---|---|
| Spec | an interactive session, for the approve card | no |
| Build | `test_command` in `oceancode.json`, for the tests | yes |
| Review | nothing more | yes |
| Secure | nothing more; the `security-audit` skill, see below | yes |
| Research | nothing more | yes |
| Goal | nothing more | yes |
| Race | a git project, `test_command`, an interactive session for the pick | no |

Every workflow needs workflows on (`workflows.enabled`, the default). An interactive session is one that can show you
a question card (the TUI, an editor); a headless one (`oceancode run`, a client without cards) cannot. A workflow
whose need is unmet answers the prompt with the reason — `spec needs an interactive session`, `build needs a
test_command in oceancode.json` — and Auto never picks it (`crates/ocean-session/src/run/mode.rs:123`).

**Secure's skill.** Each of Secure's four lenses names the skill `security-audit`. oceancode ships no skill bodies:
it finds this one where it finds every skill ([09](/oceancode/capabilities)) — the project's `.oceancode/skills/` or
`.claude/skills/` (this repository ships `security-audit` in its root `.claude/skills/`), or your
`~/.oceancode/skills/` or `~/.claude/skills/` (`crates/ocean-capabilities/src/discover.rs:74`). Its `SKILL.md` body
goes in front of each lens's prompt. Without it each lens gets one line instead —
`(Skill "security-audit" was not found; go on without it.)` — and runs on its prompt alone
(`crates/ocean-session/src/run/workflow/host.rs:626`).

## Auto and workflows

With the workflow setting on Auto, Jev picks for each prompt among the workflows that can run here. Under a fixed
mode it may also answer "stay in <mode>", which runs the prompt as a plain turn in that mode; under mode Auto it picks
among the ways of working and the workflows together ([23](/oceancode/work-modes#mode-and-workflow-together)). Each option
shows its summary and its `when_to_use` (Spec: "a task needs a spec before anything is built"). When Jev cannot
answer, the rules pick, and five rules on the prompt's first word come before the four of [Auto](/oceancode/work-modes#auto)
(`crates/ocean-protocol/src/auto_route.rs:31`):

1. `spec`, `specify`, `design` → Spec;
2. `build`, `implement`, when the prompt also names `.oceancode/plans/` or the word `spec` → Build;
3. `review` → Review;
4. `secure`, `security`, `audit` → Secure;
5. `research`, `compare`, `investigate` → Research.

The first word counts whole and in any case. A rule whose workflow cannot run here is passed over, so a headless
`design the cache` falls through to the other rules. The badge says who decided: `auto → review · rules: asks for a
review`. When the rules' answer is not among the options (their default, Model, under a fixed mode), the prompt
stays in the session's mode. Auto decides per prompt, so only the prompts it gives a workflow start a run. Until it
picks, a fixed mode's border reads `workflow auto` after the mode's badge.

## Writing your own

A workflow is one YAML file, `.yaml` or `.yml`, in the project: `.oceancode/workflows/<name>.yaml`. Every session and
everyone who works in the repository gets it. Workflows are read only from the project; to use one in another project,
copy the file by hand into that project's `.oceancode/workflows/`. A file left in the old user folder,
`~/.config/oceancode/workflows/`, is not read; the engine log names that folder once
(`crates/ocean-app/src/modes.rs:41`).

A way of working (`kind: mode`) goes in a `modes/` folder beside it instead, which also still reads JSONC (`*.jsonc`,
`*.json`, with `flow` written out and no `kind`). The workflows folder is
read when Ocean Code starts and again after each save, by the editor or by the agent's `workflow` tool; nothing watches it.
A saved workflow is listed in `/workflows` under `── yours ──` at once; a file copied in by hand while Ocean Code runs is
listed after the next start. The `modes/` folders are watched as before: a mode is listed in `F4`, under `── custom ──`. A file is skipped, with the reason in the engine log, when
its name is taken (a built-in; a workflow script's name: a `.rhai` beside it with the same stem, any `.rhai` whose
`meta.name` it is, or the built-in
scripts `deep-research`, `goal`, `pipeline` and `diagram`), when it is the other kind for its folder, or when an
earlier file holds its name (the project's wins). A
file that does not parse or validate is left out, and the `workflow` tool's unknown-diagram error names it with the
reason (`crates/ocean-app/src/modes.rs:41`).

### Three ways to start

- **Copy one.** `e` on a built-in in `/workflows` writes `.oceancode/workflows/<id>-copy.yaml` and puts
  `/workflow edit <id>-copy ` in the prompt ([Changing one](#changing-one)).
- **Ask for one.** `/workflow new <what it should do>` (or **Build your own…** in `/workflows`) asks the agent to write it. It follows
  the `workflow-author` skill, which this repository ships in its root `.oceancode/skills/workflow-author/`; in
  another project, copy the skill into that project's `.oceancode/skills/` or your `~/.oceancode/skills/`. The agent
  writes the YAML, checks it with the `workflow` tool (`source: {type: "yaml", yaml}` with `validate_only: true`),
  fixes what the check names (three rounds at most), then saves it with `save: {}` into the project.
  Without the skill the agent takes the format from `oceancode workflow schema` and the tool's errors.
- **Write it.** `o` on **Build your own…** in `/workflows` opens a starter in the editor, two steps that pass the
  check as written ([The editor](#editing-by-hand)). `oceancode workflow schema` prints the JSON Schema of a workflow or
  mode file.

The check reads the file as the catalog does, validates it against the agents this session knows, checks what the
session can run, then runs it once on a stand-in host: every question takes its first option, every command exits 0,
every verdict passes (`crates/ocean-session/src/run/workflow/launcher_yaml.rs:76`). A save does the same, asks you
once for the file, and writes it. It is refused when the file exists and `replace: true` is not set, when the name is
taken (a built-in, a workflow script, a TUI `/workflow` op — `new`, `edit`, `runs`, `pause`, `resume`, `stop`,
`save` — or a file listed from elsewhere), outside `.oceancode/workflows/`, and when a line looks like it holds a key (`sk-`,
`AKIA` or `Bearer ` followed by 16 or more key characters, or `-----BEGIN`;
`crates/ocean-session/src/run/workflow/launcher_yaml.rs:107`). A file that exists is saved over only as `write`
overwrites one: after this session read it, not when it changed on disk since, and not while another session, or you
in the editor, holds it (`crates/ocean-agent/src/tool/workflow.rs:334`). A workflow is shared text: it never holds a key, and a
command takes its secrets from the environment it runs in.

To run a saved workflow: `Enter` on it in `/workflows` (or `/mode <name>`) and a prompt, or the `workflow` tool with
`source: {type: "name", name: "diagram"}, args: {diagram: "<name>", task: "<the input>"}`. A saved workflow named
`new` or `edit` cannot be launched from the TUI's `/workflow`, as those are its ops.

### Changing one

`/workflow edit <name> <what to change>` asks the agent to change a workflow of yours. It reads `<name>.yaml` in
`.oceancode/workflows/`, changes only what you asked, checks it with the `workflow` tool
(`validate_only: true`) and fixes what the check names, then saves it in place (`replace: true`). It follows the `workflow-author` skill, as `/workflow new` does, with the same fallback without it.

A built-in is never changed: `/workflow edit review …` is refused with the hint to press `e` on it in `/workflows`,
which writes your copy and puts `/workflow edit review-copy ` in the prompt. Without a name or a change it answers
`Usage: /workflow edit <name> <what to change>`.

To change it by hand instead, press `o` on it in `/workflows` ([The editor](#editing-by-hand)). The two mix: let the agent
write it, then open it and correct a line; or write it yourself and ask the agent for the rest.

### Editing by hand

`o` in `/workflows` opens the highlighted workflow in an editor inside Ocean Code, over the conversation: the YAML
with line numbers and colours, the workflow's diagram on the right when the window is 100 columns or wider, a status
row and the keys. `o` on **Build your own…** opens a starter instead.

| Key | What it does |
|---|---|
| `Ctrl+S` | Check and save. `Alt+S` does the same where the terminal keeps `Ctrl+S` for itself. A text the check refuses is not written: the errors show under the text with their line, the gutter marks the line, and the cursor goes to the first one. A click on an error goes to its line. |
| `Ctrl+T` | Check only. Nothing is written. |
| `Tab` / `Shift+Tab` | Indent or outdent the line, or every selected line, by two spaces. YAML takes no tabs. |
| `Enter` | A new line at the same indent; two spaces more after a line ending in `:`, `: \|` or `: >`, or after a list item that starts a mapping. |
| `PageUp` / `PageDown` | Move a screen. `Ctrl+Home` and `Ctrl+End` go to the start and the end. |
| `Esc` | Close. With unsaved changes, or while a save or check is still running, the first `Esc` warns and a second one closes. |

Arrows, word moves, `Shift` selection, mouse selection, undo (`Ctrl+Z`), redo and copy and paste work as in the
prompt (`ocean-tui/crates/ocean-tui-ui/src/views/workflow_editor.rs`).

The check is the `workflow` tool's ([Three ways to start](#three-ways-to-start)): the reader, the rules over the agents
this session knows, what the session can run, and the dry run on the stand-in host. A save writes the file in place.
A changed `name:` saves a new file, `<name>.yaml`, and leaves the old one as it was; a starter saves as `<name>.yaml`
in the project's `.oceancode/workflows/`. Neither ever writes over a file that exists. When the file changed on disk
since you opened it, the save writes nothing and says so; a second `Ctrl+S` saves your text over it.

While the editor is open, a workflow of yours is held for you, as a session holds a file it writes. The session line names
the holder "the user, in the workflow editor" for 60 minutes from opening; each check and save renews it, and closing
gives it back (`crates/ocean-acp/src/extensions/workflow_file.rs:38`). Meanwhile no agent writes the file, this
window's own included: the `workflow` tool's save, `write` and `edit` are refused, naming you. After you save, the
window's agent is told before its next request that you changed a file it read, and which lines.

A built-in opens read-only, and `Ctrl+S` on it saves your copy as `e` does and opens that. A file another session is
writing also opens read-only, with the reason on the status row.

### The file

```yaml
kind: workflow                 # workflow (tasks, or a script) or mode (the lead's turn)
name: lint-review              # the id: the file's stem, /mode lint-review, the badge
label: Lint review             # the picker's title
description: lint, three lenses, a verdict
when_to_use: a change exists and the linter must pass first
agents: { review: {}, judge: { model: openai/gpt-5 } }
tasks: []                      # the tasks, in order (next section)
limits: { at_once: 3, per_turn: 10, depth: 1 }
picture: []                    # lines drawn in the picker
cost: "≈ 3–4×"
```

| Key | What it holds |
|---|---|
| `kind` | Required in YAML: `workflow` or `mode`. It must agree with `flow`. |
| `name` | Required: `^[a-z][a-z0-9-]*$`, the key for `/mode`, the config's `mode` and `workflow`, the badge and the file's stem. |
| `label` | Required: the picker's title. |
| `description` | The picker's line and the text under the list. `summary`, when set, is a shorter line beside the label; one of the two is required. |
| `when_to_use` | One sentence; Jev reads it under Auto. |
| `flow` | Leave it out: `script` for a workflow, `lead` for a mode (`auto` is Auto's alone). |
| `agents` | Every agent a task names, each with options: `model` and `effort` (pins, see [Models](#models)), `isolate: copy` (the agent works in its own copy of the project: needs git, never inside a loop; every writing agent in a `parallel` needs it), `max` (at most this many at once), `keep` (a mode's lead resumes the same child). |
| `tasks` | The tasks, in order. |
| `workflow` | Instead of `tasks`: a workflow script's name (Research: `deep-research`). Never both. |
| `limits` | `at_once` 0–64, `per_turn` 1–1000, `depth` 1–4 (1: task agents start no sub-agents), `race_n` 1–8 (copies of a `parallel` that names neither `n` nor `models`). Your `subagent.max_*` settings win. |
| `picture` | Lines drawn on the right of either picker (`F4` or `/workflows`); keep to 12 lines of 44 cells, as the built-ins do. Left out, one line per task is drawn. |
| `cost` | Shown under the list in either picker, against working alone. |
| `picker` | `false` hides it from the picker and from `/workflows`. |
| `lead_writes`, `lead_prompt` | A mode's only: `false` takes the lead's edit tools; text added to the lead's prompt. |

An agent is any agent oceancode knows; an unknown one's error lists them. `general` and `builder` write; `explore`,
`review` and `judge` are read-only; your own markdown agents count too. The shipped workflows use only these five.

### The four task types

```yaml
- type: task                   # one agent, one prompt
  id: build                    # its result's name; default: the agent's id
  agent: builder
  prompt: |
    Carry out the to-dos:
    {plan}
  schema: verdict              # verdict, ranking or deliverables: the reply is that JSON
  model: openai/gpt-5          # this task only
  condition: '!tests.pass'     # runs only when it holds; quote a leading !
  skills: [security-audit]     # SKILL.md bodies put before the prompt
  todo: { from: plan }         # the todo block of an earlier reply, or a list of rows
  save: spec                   # writes the reply to .oceancode/plans/<date>-spec-<run>.md
- type: parallel               # different tasks at once
  id: scouts                   # required
  schema: verdict              # for subtasks that name none
  subtasks:
    - { type: task, id: code, agent: explore, prompt: "Read the code. {input}" }
    - { type: task, id: docs, agent: explore, prompt: "Read the docs. {input}" }
- type: parallel               # copies: one agent, one prompt, n times
  id: checks
  agent: review
  prompt: "Refute the change. {input}"
  n: 3                         # 1–8; else one copy per model; else limits.race_n; else 3
  models: [openai/gpt-5, openai/gpt-5-mini]
- type: loop                   # repeats its tasks
  max: 3                       # passes, at least 1
  until: tests.pass            # ends it when this holds
  tasks:
    - { type: gate, gate: tests }
    - { type: task, id: fix, agent: builder, condition: '!tests.pass', prompt: "Fix the cause: {tests.output}" }
- type: gate                   # approve, pick, tests or check
  gate: check
  id: lint
  command: cargo clippy --all-targets -- -D warnings
  expect: Finished             # passes on exit 0 with this text in the output's last 4 KiB
```

- **task**: `agent` and `prompt` are required. `todo` needs an agent that writes; the agent is resumed while rows
  are open, three times at most, and a row still open fails the task. `save` runs once, so never on a subtask or
  inside a loop, and never replaces a file. `effort` is read on a task too, but only the agent's `effort` is applied.
- **parallel**: `id` is required. With `subtasks`, each a `type: task`, every result is saved under its own id and
  the set under the parallel's; it takes no `agent`, `prompt`, `n` or `models`, and every subtask id is unique in the
  file. Without, it runs copies of one `agent` with one `prompt`.
- **loop**: `max` and `tasks` are required; `until` is optional.
- **gate**: see [Gates](#gates). A gate and a parallel take `condition` too.

A failed task or subtask ends the run as failed; copies end it only when none succeeds. A failing gate does not stop
the run: follow it with a fix under `condition: '!<id>.pass'` inside a loop `until: <id>.pass`.

### Templating, conditions and schemas

- `{input}` is the prompt the run started with. `{id}` is a saved result as text: a plain reply as itself, a schema
  reply as JSON, a parallel as a JSON list. `{id.field}` is one field (`{review.findings}`, `{tests.output}`; on a
  parallel, each member's), and `{id.file}` the plan file a `save` wrote. A name nothing has saved stays as typed,
  braces and all.
- A condition reads `name.field` or `!name.field`, both words lowercase letters and `_` only — so a result a condition
  reads needs such an id (`fix_two`, not `fix2`). It holds when the field is `true`; on a parallel, when it is true for
  every member that answered in a schema; for a name nothing has saved, never, so `!review.pass` runs before any
  review. There is no `&&`, `==` or number. Quote it: a bare `!` starts a YAML tag, and a tag is refused.
- `schema: verdict` asks for `{pass, findings}`, `ranking` for `{order, reasons}` (attempt numbers, best first: what
  a `pick` gate shows), `deliverables` for `{deliverables}`. The reply is held to its schema, asked again a bounded
  number of times.

### Gates

Gates are local: the cloud engine never waits for a person.

| `gate` | Keys | Result | Needs |
|---|---|---|---|
| `approve` | `show`: a saved result shown with the question (else the input) | Stop ends the run `blocked · not approved` | an interactive session |
| `pick` | `from`: an earlier parallel's id; `show`: a `ranking` result | applies the chosen copy and ends the run | an interactive session; copies (`isolate: copy`) |
| `tests` | `command` (else the config's `test_command`); `each`: run in every copy of a parallel | `{pass, exit, output}` under its `id`, else `tests` | `test_command` when it names no `command` |
| `check` | `command` (required), `expect` | `{pass, exit, output}` under its `id`, else `check` | nothing |

With `each` the result stays on each copy, so that gate takes no `expect` and no `id`.

### Aliases

The work-mode files before 2026-11-02 used other words. They are still read, so every older file parses; write the
first column. A word and its alias together are refused.

| Write | Also read |
|---|---|
| `name` | `id` (top level) |
| `tasks` | `steps` |
| a task's `id` | `as` |
| `prompt` | `do` |
| `condition: x` (runs the task when x holds) | `unless: '!x'` (skips it when x holds) |
| `{input}` | `{task}` |
| `type: task`, `type: gate` | a task keyed by `agent`, a gate keyed by `gate` |
| `type: parallel` | `parallel: { … }` with `as` beside it |
| `type: loop` | `loop: { max, until, steps }` |

An error names where it is and what was meant, counting the top-level list as `tasks` even when the file wrote
`steps` (`crates/ocean-protocol/src/diagram_read.rs:21`):

```
mode draft: tasks[2].unles: unknown field, expected one of `type`, `id`, …; did you mean `unless`?
```

### From the cloud engine's words

A local file has the shape of a bare CNL document (`orchestration/cnl-engine/`). What the local engine lacks is the
registry, SharedMemory and CEL; what it adds is `loop` and `gate`.

| Cloud (CNL) | This file |
|---|---|
| the `workflow:` envelope with `name`, `description`, `tasks` | top-level `kind: workflow`, `name`, `label`, `description`, `tasks` |
| `type: agent`, `type: harness` (`goal`, `mission`) | `type: task` with `agent` and `prompt` |
| a task's `id` | `id` |
| `parallel` with `subtasks` | `type: parallel` with `subtasks` |
| `validate` | a verdict task or parallel in a `loop` with `until: <id>.pass` |
| `condition` (CEL) | `condition: "name.field"` or `"!name.field"` |
| `retry` | `type: loop` with `max` |
| `{input}`, `{task_id}` | `{input}`, `{id}`, `{id.field}` |
| a harness's `skills` | `skills` |
| `allowed_tools`, `posture: read_only` | the agent: `explore`, `review` and `judge` are read-only |
| `sequential` | the top-level `tasks`, which run in order |
| `batch`, `dynamic`, `debate`, `output`, `version`, `inputs`, `followup`, `timeout`, `budget` | none (budgets: the config's `workflows.*`) |

### Models

A cheap model for the scouts and a strong one for the builder or the judge:

- `agents.<id>.model` and `effort` pin an agent in every task;
- a task's `model` pins that task;
- `models: [a, b, c]` on a copies `parallel` runs one copy per model;
- the `workflow` tool's `args.models: {<agent id>: <model>}`, when it launches `diagram`, wins over an agent's pin.

A model is `provider/model`, as `/model` lists it. The session's `/subagent` model wins over every pin; with no pin,
a task runs the config's `agents.<id>.model`, else `subagent.model`, else the session's model. The picker tags each
agent with its pin.

## What is and is not enforced

The file is data the engine runs (`crates/ocean-session/src/run/workflow/builtins/diagram.rhai`), so these hold
whatever an agent says:

- **The order.** The tasks run as written; no model picks the next one, and a replayed run never decides again. A
  failed task ends the run.
- **The gates.** An approve gate waits for you, and Stop ends the run. A tests or check gate passes only on exit 0
  (and `expect` in the output). A pick applies only the copy you chose.
- **The answers.** A reply in a schema is checked against it, and a condition or `until` reads its fields; a loop
  ends at `max`.
- **The to-dos.** Rows are in the agent's list before it starts, it is resumed while they are open, and a row still
  open fails the task.
- **The saves.** One new file under `.oceancode/plans/`, never elsewhere, never over another.
- **The limits.** At once, per turn and depth bound the run's agents ([23](/oceancode/work-modes#limits)); `explore`,
  `review` and `judge` have no edit tools.
- **The rules of the file.** An unknown key or agent, a malformed condition, `todo` on a read-only agent, `save` in a
  loop or a subtask, a writer in a parallel without `isolate: copy`: each is refused before anything runs, and a
  workflow whose needs are unmet never starts.

These are judgement, which no file can hold:

- the quality of a spec, a review or a report;
- a builder's "done" beyond the tests and its to-do rows, which it closes itself;
- the honesty of `verdict.pass`: a model can pass what it should not, so a second lens or a `check` gate is the guard;
- what a skill's text does: `skills` adds text to the prompt, not rules;
- a `{name}` that names nothing: it stays in the prompt as typed, and validation does not catch it;
- which sub-agents a task's agent calls: a mode's allow-list shapes only the lead's own calls
  (`crates/ocean-session/src/run/orchestration.rs:679`), which is why Spec, Review and Secure set `limits.depth: 1`
  (Build: 2).

## See also

- [23 · Work modes](/oceancode/work-modes) — the ways of working, Goal and Race, limits, Auto.
- [02 · Configuration](/oceancode/configuration) — `mode`, `test_command`, `agents.<id>.mode`, `workflows.*`.
- [09 · Capabilities and plugins](/oceancode/capabilities) — where skills are found.
- [19 · Ocean TUI](/oceancode/tui) and [22 · Ocean TUI reference](/oceancode/tui-reference) — the picker, the badge,
  the dock and question cards.
- [21 · CLI reference](/oceancode/cli-reference) — `oceancode workflow`.
