git:20260822.b43704d to git:20260826.1ed54bd

---

name: wise-workflow-run

description: >-

Start a new run of a registered workflow. The main Claude Code

conversation becomes the conductor — runs pre-flight (control mode +

worktree), resolves the target project, and executes the workflow's

DAG wave by wave via the Skill / Task / Bash tools, tracking per-step

state under a ULID run directory. Invoked as `/wise-workflow-run`

(bare alias) or `/wise:wise-workflow-run` (canonical). Use when the

user says "run the workflow", "start a workflow", "kick off

<workflow-name>", "run the ticket-plan workflow", or types

`/wise-workflow-run`.

argument-hint: "[<workflow-name> [<input1> <free-form remainder…>]]"

allowed-tools: Read, Write, Skill, AskUserQuestion, TodoWrite, Task, Agent, TeamCreate, TeamDelete, SendMessage, Monitor, TaskCreate, TaskList, TaskGet, TaskUpdate, TaskOutput, TaskStop, Bash(${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap-deps.sh:*), Bash(${CLAUDE_PLUGIN_ROOT}/scripts/init-registry.py:*), Bash(${CLAUDE_PLUGIN_ROOT}/scripts/workflows.py:*), Bash(bash:*), Bash(python3:*), Bash(mkdir:*), Bash(git:*), Bash(test:*)

---

# /wise-workflow-run — the conductor

## Why this skill exists

Running a workflow is an orchestration task: parsing a DAG, tracking

per-step state, driving parallel executions, asking for approvals,

and surfacing progress. This skill owns that loop. Together with

`wise-workflow-resume`, it is one of only two skills in the plugin

allowed to invoke other wise action skills (as part of `type: skill`

steps from a validated workflow definition) — see the invariant

documented in `CLAUDE.md`.

## Arguments

Read `$ARGUMENTS`. The first whitespace-separated token is the

`workflow-name`; everything after it is **positional input values**

for the workflow's declared `inputs:` (see [§2](#2-resolve-the-workflow-name)

and [§6c](#6c-collect-workflow-inputs)). When `$ARGUMENTS` is empty,

the skill prompts interactively in [§2](#2-resolve-the-workflow-name).

- `workflow-name` — matches the filename without `.yaml`. Resolution

order: user dir first, bundled second. When absent, [§2](#2-resolve-the-workflow-name)

prompts the user to pick from the available definitions.

- positional inputs — optional. Tokens after the workflow name are

assigned to the declared inputs **in order**, and the **last

declared input absorbs the entire remainder of the line** (verbatim,

spaces preserved) so a trailing free-form prompt works. An input

satisfied positionally is **not** prompted for in §6c. Example:

`/wise-workflow-run ticket-auto PROJ-1 prefer the wise-estimation

skill; never touch infra/*` → `workflow-name=ticket-auto`, first

input `ticket_ids=PROJ-1`, last input `config_prompt=prefer the

wise-estimation skill; never touch infra/*`, no questions asked.

Only the **last** input may contain spaces; every earlier positional

is a single whitespace-delimited token, so a value that would

otherwise contain spaces (e.g. a multi-ticket list) must avoid them

when passed positionally — use `PROJ-1,PROJ-2`, or supply it via the

interactive prompt, which still accepts spaces.

## Procedure

### 1. Init-check + list + picker — in ONE message

Run the init-check per `${CLAUDE_PLUGIN_ROOT}/references/init-check.md`,

firing in the SAME message: `init-registry.py check`, the data call

`workflows.py list-defs`, and a `select:AskUserQuestion` ToolSearch (so

the §2 picker is ready). On `INIT:ok`, use the `list-defs` output and

proceed to §2. Otherwise follow the reference's fallback — this skill

mutates state, so it **drives the need-python install loop** and

proceeds to §2 only once Python is `READY`.

### 2. Resolve the workflow name

If `$ARGUMENTS` is non-empty, use its first whitespace-separated token

as the workflow-name and skip the rest of this step (the `list-defs`

output from §1 is unused in this case — a cheap fork, not worth

re-ordering for). **Keep the text after that first token** — it is the

positional-input remainder consumed in [§6c](#6c-collect-workflow-inputs).

Call it `ARG_REST` (everything in `$ARGUMENTS` after the first token,

with the single separating run of whitespace stripped; preserve all

inner spacing). When the user typed a bare workflow name, `ARG_REST`

is empty.

Otherwise (user typed bare `/wise-workflow-run`), use the `list-defs`

JSON already captured in §1. If the array is empty, stop with:

```

No workflows are registered yet. Create one with

/wise-workflow-create <name>

or install a marketplace plugin that ships one.

```

Otherwise `AskUserQuestion`:

- Question: `Which workflow do you want to run?`

- Header: `Workflow`

- One option per entry. Label: `[bundled] <name>` for entries with

`source: bundled`, `[user] <name>` for `source: user` — the

bracketed tag is part of the label so the source is visible at a

glance in the picker, not buried in the description. Description:

`<description first sentence, truncated to ~80 chars>`. Mark

shadowed bundled entries with a trailing ` (shadowed by user

definition)` on the description so the user knows which one will

actually run. Add a final `Abort` option.

On pick, strip the `[bundled] ` / `[user] ` prefix from the chosen

label to recover the bare workflow name (or, simpler, look up the

chosen label's entry in the `list-defs` JSON array by label match

and read its `name` field). Set `workflow-name` to that bare name

and continue. On `Abort`, stop cleanly (no state written, no

"error" framing — the user chose to back out).

### 3. Locate the workflow definition

```bash

DEF=$(python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workflows.py" locate-def "<workflow-name>")

```

Non-zero exit → relay stderr and stop.

### 4. Probe requires (with install-retry loop)

```bash

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workflows.py" probe-requires "$DEF"

```

Exit 0 (stdout `OK`) → proceed.

Exit 2 → stdout has one or more `MISSING:` lines. Relay them to the

user with the exact install commands:

```

This workflow requires the following that are not installed:

- <missing item 1>

- <missing item 2>

Install them (out of band):

/plugin install <plugin>@<marketplace>

/plugin install <plugin>@<marketplace>

```

Then `AskUserQuestion`:

- Options: `I've installed them, re-check`, `Abort`.

On `re-check`, re-run the probe. Loop until OK or user aborts. No

auto-install.

### 5. Generate the run ID, tag the session, write stub state

The very first persistent act of a run is to allocate its ULID and

write a stub `state.yaml` that records the Claude Code session the

run was started in. Doing this before pre-flight (rather than after)

is deliberate: if the user later interrupts the conductor and

invokes `/wise-workflow-resume <run-ulid>` from a different session,

resume can compare the stored session UUID against the current one

and offer to send them back to the original session (where the

conductor's TodoWrite list and partial step logs are meaningful).

**5a. Allocate the run ID and run directory:**

```bash

RUN_ID=$(python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workflows.py" new-ulid)

RUNS_ROOT="$(python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workflows.py" runs-root)"

RUN_DIR="$RUNS_ROOT/$RUN_ID"

mkdir -p "$RUN_DIR/logs"

```

**5e. Write the stub state:**

Build `CTX` as a JSON object with two keys — `claude_session_id`

(JSON-encode `SESSION_ID`, or `null` when it's empty) and

`session_label` (JSON-encode `SESSION_LABEL`), e.g.

`{"claude_session_id":"<uuid>","session_label":"<label>"}`. Then:

```bash

STATE=$(python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workflows.py" \

init-state "$DEF" "$RUN_DIR" "$RUN_ID" "$CTX")

```

This writes `state.yaml` with the session fields, the steps list

(all `pending`), and `status: initializing`. Pre-flight answers get

folded in by `start-run` once they're collected.

**5g. Read pre-flight pins from the workflow definition:**

Before any of the three pre-flight prompts (rename_session /

control-mode / worktree), read the workflow's `preflight:` block

— it may pin any or all of those answers, in which case the

corresponding prompt is skipped entirely:

```bash

eval "$(python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workflows.py" \

get-preflight "$DEF")"

```

This sets five shell variables:

- `CONTROL_MODE` — `prompt` (default; ask §6a) | `wave-sync` | `synchronous` | `auto-advance`

- `WORKTREE` — `prompt` (default; ask §6b) | `current` | `new`

- `RENAME_SESSION` — `prompt` (default; ask §5h) | `skip`

- `TUNING` — `skip` (default) | `prompt` (ask §6b2)

- `STEP_SELECT` — `skip` (default) | `prompt` (ask §6b3)

Missing keys (or a missing `preflight:` block entirely) resolve to

each key's default — `prompt` for the three original questions

(matching pre-0.42 behaviour), `skip` for the two opt-in

questionaries, so a workflow only gets a tuning / step-selection

prompt by declaring it. Invalid values emit a `WARN:` line on

stderr and fall back to the key's default so the workflow still

runs.

**5h. Prompt the user to rename the session (skip if pinned):**

### 6. Pre-flight prompts

The two base-control questions below (plus, when the workflow opts

in, the §6b2 tuning and §6b3 step-selection flows — those are

multi-question flows, not single prompts). For the base controls: up

to two `AskUserQuestion`s in sequence (or batched — your call;

batching is fine since answers are independent). Each is skipped

when the workflow's `preflight:` block pinned the answer in §5g.

Pinned answers are logged (`Pre-flight pin: control-mode=wave-sync

(declared by workflow).`) so the user knows why the prompt didn't

appear.

**6a. Control mode (skip if pinned):**

- **`CONTROL_MODE=prompt`** → run the prompt below.

- **`CONTROL_MODE=wave-sync`** → skip; set the answer to `wave-sync`.

- **`CONTROL_MODE=synchronous`** → skip; set the answer to `synchronous`.

- **`CONTROL_MODE=auto-advance`** → skip; set the answer to `auto-advance`.

Prompt:

- Question: `How should the workflow run control progress?`

- Options:

- `Wave-sync (recommended)` — `Run one wave of steps, pause for me between waves. I can ask questions, steer, or abort mid-flight. Approval gates use AskUserQuestion.`

- `Synchronous` — `Run end-to-end without stopping. Approval gates are auto-approved (picking this IS the approval). Step output goes to per-step log files under the run dir, not the chat — tail state.yaml if you want to watch progress.`

- `Auto-advance` — `Run waves back-to-back without a between-wave menu, but still prompt at steps that need input (asks, approvals, AskUserQuestion inside interactive steps). Best when the workflow's only stops should be its own questions.`

### 7. Resolve the project

`wise` keeps no persisted project registry — the project a run

operates on is derived from the current context. Read the workflow

definition's `project-selection`:

- `any` → `project = null`.

- `current` (default) → **auto-detect from the current directory**:

- `path` = `git rev-parse --show-toplevel` (fall back to `$(pwd)`

when not inside a git repo);

- `name` = the basename of `path` (or the `owner/repo` slug from

`git remote get-url origin` when one is set);

- `kind` = inferred from the repo's contents — `go.mod` → `backend`,

a `package.json` with a React/React-Native dependency → `frontend`,

both backend and frontend markers → `fullstack`, otherwise `other`.

- `prompt` → **ask the user** with `AskUserQuestion`: confirm the

auto-detected `path`/`name`/`kind` above, or let them override each

field (the "Other" free-text option accepts a path/name/kind the

detection missed).

Let `project_json` be the resolved `{path, name, kind}` or the string

`null`.

### 8. Finalise the run (worktree + start-run)

If the user picked a worktree at [§6](#6-pre-flight-prompts)b, create it now:

```bash

WT_DIR="<project.path>.wise-$RUN_ID"

git -C "<project.path>" worktree add "$WT_DIR" -b "wise/<workflow-name>-$RUN_ID"

```

(`<project.path>` is the resolved project path from §7, not a shell

variable — substitute the literal path. `${project.path}` is not valid

shell expansion.)

On git failure, fall back to the original `project.path` and pass

`worktree: null` below; tell the user the worktree couldn't be

created and why. If the worktree WAS created, override

`project.path` to `WT_DIR` in the payload below.

If the worktree was created, carry over any `.worktreeinclude` files

from the original base repo into it — `git worktree add` checks out

only tracked files, so untracked artifacts a tree needs to run

(`.env`, local config) would otherwise be missing:

```bash

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workflows.py" \

apply-worktree-include "<project.path>" "$WT_DIR" || true

```

(`<project.path>` is the ORIGINAL base path from §7 — the source of the

`.worktreeinclude` file and the files it lists — not `$WT_DIR`. Run

this BEFORE overriding `project.path` below. The helper is best-effort:

no `.worktreeinclude`, a non-git base, or a missing listed path are all

silent no-ops and never abort the run, so the `|| true` is belt-and-braces.)

Fold the pre-flight answers into `state.yaml` (flipping

`status: initializing` → `status: running`) via `start-run`:

```bash

CTX='{"control_mode":"<mode>","worktree":<wt-json-or-null>,"project":<project-json-or-null>,"inputs":<inputs-json-or-empty-object>}'

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workflows.py" start-run "$STATE" "$CTX"

```

(`jq` isn't in `allowed-tools`; construct the JSON yourself as a

literal string from the values you already have. Omit `inputs` or

pass `{}` when the workflow declared none — the engine tolerates

either. Example:

`'{"control_mode":"wave-sync","worktree":null,"project":{"path":"/path/to/project","name":"project","kind":"frontend"},"inputs":{"ticket_id":"TICKET-123"}}'`.)

### 9. Initial TodoWrite

Read the definition's `steps` list. `TodoWrite` one todo per step:

```

{ subject: "<step.id>: <short summary>", activeForm: "Running <step.id>", status: "pending" }

```

Summary hint per type: skill → the skill name; prompt → first 40

chars of the prompt; bash → first 40 chars of the command; approval

→ "awaiting approval"; ask → `ask: <def.output>`. A step §6b3

pre-marked `skipped` gets its todo created as `cancelled` (suffix

the subject with `— deselected at pre-flight`).

Tell the user: `Run <RUN_ID> started. state.yaml: <path>.`

### 10. Main loop

Repeat until a terminal state is reached in [§11](#11-finalise).

**IMPORTANT — turn continuity.** The main loop runs inside a single

Claude Code conversational turn. A turn ends as soon as you emit a

message that does **not** contain a tool call. That will **stall the

run** — the user will see the last output and nothing else, with no

prompt to continue.

The rule is simple and applies equally in wave-sync and synchronous

mode: **every message in the main loop must end with a tool call**.

Prose is fine — encouraged, even, because it's how the user sees

progress — as long as the message it lives in also contains the tool

call that moves the run forward.

Concretely:

message** as the tool calls that follow them. Never emit a bare

text-only message mid-loop.

- After every `update-step` bookkeeping batch, your very next tool

call is either (a) the next-wave Bash probe, or (b) the finalise

sequence in [§11](#11-finalise) if the wave just completed pushed

the run terminal. The bookkeeping + the following tool call can

live in one message; they don't have to be split.

- If you find yourself about to write "Step X complete. Running step

Y…" as prose and realise no tool call is following in the same

message, either bundle the next `next-wave` call into the same

message or drop the prose. The run's progress is reported *at* the

```bash

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workflows.py" next-wave "$DEF" "$STATE"

```

Parse the JSON:

- `runnable: []` — list of step descriptors (each has `id`, `type`,

`definition` — the def merged with templates expanded).

- `to_skip: []` — step ids that should be marked `skipped` per their

`trigger-rule` (e.g. a dep failed and the rule is `all-success`).

- Optional `terminal: "completed" | "failed"` — when runnable and

to_skip are both empty AND no steps are `running` in state.

When `to_skip` is non-empty, emit a prose preamble naming each

skipped step and why, then perform the bookkeeping in the SAME

message:

```

Skipping:

- ⊘ <step.id> (<type>) — <trigger-rule> not met: dep <dep-id>

is <dep-status>

- …

```

In the same message, for each id in `to_skip`:

```bash

python3 .../workflows.py update-step "$STATE" <id> status=skipped

```

And `TodoWrite` to mark the matching todos `cancelled`. Do **not**

emit the skip prose as a standalone message — it must share a

message with the tool calls that follow.

If `terminal` is set, jump to [§11](#11-finalise).

Build ONE message with:

1. A prose announcement naming each step about to run.

2. The per-step `update-step` bookkeeping that transitions each to

`status: running`.

3. The per-step execution tool calls (dispatched concurrently).

The announcement format:

```

Wave <N> — <count> step(s):

- ▶ <step.id> (<type>): <one-line description>

- ▶ <step.id> (<type>): <one-line description>

```

`<N>` is a simple counter the conductor increments per wave (1 for

the first wave, 2 for the second, …). Don't persist it in state; it's

display-only and doesn't survive resume.

The one-line description is generated from the step definition:

| Type | Description |

|---|---|

| `skill` | `invoke <def.skill>` + first non-empty payload key if any |

| `prompt` | first 60 chars of rendered `def.prompt` (one line, ellipsise); append ` [→ wise:<role>]` when an agent resolves |

| `supervised-prompt` | as `prompt`, plus ` [supervised]` (runs as a watched background worker) |

| `bash` | `$ ` + first 60 chars of rendered `def.command` + `(cwd: …)` if `def.cwd` is set |

| `approval` | `approval: ` + first 60 chars of rendered `def.message` |

Then, in the same message, for each runnable step allocate a

step-run-ulid and transition its state:

```bash

SID_RUN=$(python3 .../workflows.py new-ulid)

python3 .../workflows.py update-step "$STATE" <step.id> \

status=running run_id=$SID_RUN started_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \

log="logs/<step.id>.$SID_RUN.log"

```

And dispatch each step's executor — **all in the same message**

(multiple tool calls in one message execute concurrently per Claude

Code's tool-use docs). Per step type:

**Resolving agent / model / effort (prompt steps only).** Before

dispatching a `type: prompt` step, resolve its roster binding in one call:

```

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workflows.py" resolve-team "$DEF" "<step.id>"

```

Branch on `mode`:

- **`errors` non-empty** → do NOT dispatch. Fail the step loudly with the

(`auto`/`off`) used as a team member, or two leads is an authoring bug —

silently dispatching the wrong agent is worse than failing.

- **`mode: unset`** → the step pinned no `agent:`; apply the workflow's

top-level `agents:` policy (read once from `$DEF`; default `off`). `off` →

one `general-purpose` subagent; `auto` → roster-match (next).

- **`mode: off`** → one `general-purpose` subagent.

- **`mode: auto`** → pick the best-fit roster role. Cache the roster **once

per run**: on the first `auto`/policy-auto step, shell

`python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workflows.py" list-agents` once,

hold the JSON (`{name, description, tools, model, effort}`) in working

memory, reuse it for every later wave/step — never re-shell per wave.

Match the step's rendered prompt intent against the `description`s AND

check `tools` cover what the step does: **writes/edits files** needs

`Write`/`Edit`; **runs shell or git** needs `Bash`; a step needing a tool

**no role has** (e.g. `TeamCreate`, a tracker MCP) fits none. **When no

role both matches the intent and covers the required tools, fall back to

`general-purpose`.** Resolve its model with `resolve-model

"<step.model or 'inherit'>" "<step.effort or ''>"`.

- **`mode: single`** → dispatch `members[0]` as one `wise:<role>` Task.

- **`mode: team`** → dispatch every member and synthesize (team flow below).

- `type: skill`:

```

Skill({

skill: "<def.skill>",

args: <def.payload as key: value per line, rendered>

})

```

- `type: prompt` — **single agent** (`mode` off / auto / single → one member):

```

Task({

subagent_type: <"wise:<role>" | "general-purpose">,

description: "Workflow step <step.id>",

model: <member.model — include ONLY if not "inherit">,

prompt: "<rendered def.prompt>"

+ [if member.effort] "\n\nReason at <EFFORT> effort — <gloss>."

+ [if def.until] "\n\nEnd your last line with a value that matches the regex /<until>/ so the conductor can capture it."

})

```

If `def.outputs` is set, remember the list so you can extract on

reports them.

- `type: bash`:

```

Bash({

command: "<def.command>",

description: "Workflow step <step.id>",

run_in_background: <true if timeout > 30>,

timeout: <def.timeout * 1000>,

...with explicit working-directory handled by prefixing `cd <def.cwd> && <command>`

(the Bash tool has no cwd field; the engine.sh pattern is to use

`cd <path> && ...` which is already in the allowed-tools grant).

})

```

After the wave's tool results come back, build ONE message that

reports every step's outcome (prose) AND performs all the

bookkeeping (tool calls). Structure:

announced them:

```

Wave <N> results:

- ✓ <step.id>: <one-line outcome>

- ✗ <step.id>: <one-line failure reason>

- ⊘ <step.id>: <skip reason>

```

Outcome wording per type:

| Type | On success | On failure |

|---|---|---|

| `skill` | `<last message first sentence, truncated to ~80 chars>` | `error: <error text, truncated>` |

| `prompt` | `captured <name>=<value>` for each `def.outputs`; else `ok (<duration>s)` | `no match for until:/<regex>/ after <iterations>` or subagent error |

| `bash` | `exit 0 in <duration>s` + first matched group of stdout if `stdout_matches` captures | `exit <code>: <first line of stderr, truncated>` |

| `approval` | `approved` (wave-sync) or `auto-approved` (sync) | `rejected by user` |

For a `prompt` step dispatched to a roster agent or with a `model:` /

`effort:` override, append the resolved knobs to its outcome line —

`[agent=wise:<role> model=<m> effort=<e>]`, omitting any that were not

set — and write the same to the step log so the routing is auditable.

For a **team** step, list each member and mark the lead —

`[team=wise:<lead>*, wise:<role2>, wise:<role3> | synthesized]` (the `*`

flags the lead; `synthesized` notes the conductor merged them) — and write

each member's `model`/`effort` to the step log. When a member's

`resolve-team`/`resolve-model` `reason` is non-null (a retired-id swap or an

effort clamp), append `; <role>: <reason>` so the substitution is visible in

chat, not just the log.

Keep each step's line under ~100 chars — if the "one-line" needs

more room, point at the log file instead (`see logs/<id>.<run-id>.log`).

**Surface the step's output when declared.** If the step def

includes a `surface:` field, render the requested content

inline *immediately after* the step's one-line outcome, so the

user can review it without opening a file. Shapes:

```yaml

surface:

file: <output-name> # read the file at state.outputs[<output-name>]

label: "Drafted PR body" # optional prefix shown above the content

max-lines: 400 # optional cap; default 400

```

Rendering:

```

- ✓ <step.id>: <one-line outcome>

<label> (<N> lines from <path>):

```markdown

<file contents, truncated to max-lines; add "… (<X> more lines)" line if truncated>

```

```

If `state.outputs[<output-name>]` is unset or the file is

missing/unreadable, render `<surface failed: <reason>>` in

place of the block — don't fail the step over a surface miss.

The content goes to the main chat message, not the step log

declare `surface:` when the content is genuinely worth reading

without extra clicks (drafted text the user has to approve,

small generated reports, etc.) — long binary or noisy outputs

should stay in the log file.

2. For each step in the wave, in the same message:

a. Determine success per type:

- `skill`: tool result returned without an error. On error,

capture the error text.

- `prompt`: extract the final assistant message. If

`def.until` is set, run the regex against the final message;

success only if a group matches. If `def.outputs` is

non-empty, capture the group(s) and `record-output` each.

- `bash`: interpret the tool result's exit code and output.

Apply `def.success.exit_code` (must match) and any

`stdout_matches` regex.

- `approval`: the user's pick (`Approve` → completed, `Reject`

→ failed).

```bash

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workflows.py" write-log \

"$RUN_DIR" "<step.id>" "<step-run-ulid>" <<'WISE_LOG_EOF'

WISE_LOG_EOF

```

The `Bash(${CLAUDE_PLUGIN_ROOT}/scripts/workflows.py:*)` grant

already in `allowed-tools` covers this invocation, so every

subsequent log write runs silently. If the output content

might contain the literal token `WISE_LOG_EOF`, pick a

different heredoc delimiter (e.g. `WISE_LOG_<random 6 chars>`).

c. `update-step status=<completed|failed|skipped> completed_at=<utc>` —

plus `error=<short text>` if failed.

d. `TodoWrite` to update the matching todo (`completed` or

`cancelled`).

`update-run last_activity_at=<utc>` is handled by every `update-step`

call — you don't need a separate write.

The between-wave user-control menu fires in **`wave-sync` only**.

the next wave (see the skip branch below).

If `state.control_mode == "wave-sync"`:

here. Optionally tack one line on noting what's likely next (the ids

the next `next-wave` call will surface — cheap to predict from

`depends_on`). Then call `AskUserQuestion` in the SAME message:

- Options: `Continue`, `Pause (you'll resume later)`, `Abort run`, `Modify (freeform instruction)`.

- `Pause` → `update-run status=paused`; print resume command:

```

Resume later with:

/wise-workflow-resume <RUN_ID>

```

Stop.

- `Abort` → `update-run status=cancelled completed_at=<utc>`; jump to [§11](#11-finalise).

- `Modify` → accept free-form instruction ("skip step X", "edit

prompt of Y and re-run", …). Interpret it against the current

state: for a skip, `update-step <id> status=skipped`; for an edit,

you cannot interpret the instruction safely, surface what you'd

do and ask again.

If `state.control_mode == "synchronous"` **or

bundle your next `next-wave` Bash call into the **same message** as

of these modes: it reports what the wave did AND kicks off the next

wave's probe, all while keeping the turn open.

In other words, both these modes have the same per-step reporting as

`AskUserQuestion`). They never have a moment where prose is the

last thing in the message — the next tool call is always there.

The difference between the two: `synchronous` also suppresses every

in-step prompt (approvals auto-approve, asks record empty,

interactive steps don't call `AskUserQuestion`), so it runs fully

unattended. `auto-advance` keeps all those in-step prompts — it only

drops the between-wave menu, so the run still stops wherever a step

genuinely needs the user's input.

### 11. Finalise

Terminal branch:

```bash

python3 .../workflows.py update-run "$STATE" status=<completed|failed|cancelled> completed_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"

```

Print a summary:

```

Run <RUN_ID> — <status>.

Workflow: <name>.

Duration: <mm:ss>.

State: <path to state.yaml>.

Logs: <path to logs dir>.

[if worktree] Worktree at <path> — still there; prune with `git worktree remove` when ready.

```

## Guardrails

- Never invoke the `wise:wise` natural-language helper or another

`wise-workflow-*` skill. The only Skill invocations this skill is

allowed to make are the `type: skill` steps of a validated

workflow.

- Never write outside the run directory and (when requested) the

worktree path.

- Never skip the `next-wave` round-trip — do not compute runnable

steps yourself in-conversation. The script is the source of truth

for readiness.

- Never reorder or re-rank a wave — dispatch all runnable steps

together, in one message.

- Every message in the main loop **must end with a tool call** — the

full turn-continuity rule is §10. A trailing text-only message stalls

the run, especially across a between-wave transition in synchronous

`AskUserQuestion` to prompt the user back in.

- On `Modify`, changes are ephemeral: apply them in state.yaml if

persistent, but never rewrite the definition YAML (the user's

definitions directory is only mutated by `wise-workflow-create` and

`wise-workflow-remove`).