Workflows

A workflow is a saved chain of subagent steps. It runs on a deterministic executor, so code rather than a model decides what runs next. Steps pass work to each other through a shared run directory (the blackboard). A review gate can loop back to an earlier step. An interrupted run can be resumed. A run whose process died (SIGKILL, closed terminal) is marked interrupted at the next session start. A run records its process in owner.json; it is taken as dead only when that process is gone, however quiet it has been, and a run from before owner.json existed falls back to 5 minutes of quiet (tests/workflow-recovery-smoke.ts); a failed gate's error carries the first 400 characters of what it read.

Use a workflow when the same multi-step delegation keeps coming up: plan → implement → review, reproduce → fix → verify, or fan out → synthesise. For a one-off delegation, the subagent tool (single or parallel) is enough.

Running

Surface Use
/workflows list Available workflows and their inputs (* = required)
/workflows run feature goal="add rate limiting to /api/orders" Start a run in the background. The footer shows progress, and the summary is posted into the session when it finishes. /workflows run with no name opens a picker.
/workflows status [run-id] Recent runs, or one run's steps
/workflows Every run the workspace and the autonomy state home know about — workflow YAML and script runs, background subagents and autonomous container runs — live or finished
/workflows panel [run-id] The workflow panel: this session's runs with their phases, agents and narration (see The /workflows panel)
/workflows pause <run-id> Pause a live run: it starts no new agents (see Pausing, stopping and skipping)
/workflows skip <run-id> Stop the agents running now and record their steps as skipped
/workflows stop <run-id> Stop an active run (it can be resumed)
/workflows resume <run-id> Unpause a live paused run; otherwise continue an interrupted or failed run from its current step
workflow_run tool The agent runs a workflow itself: {name, inputs}, {name: "list"}, {resume: "<run-id>"}, or an inline plan as {steps: [...]}
workflow_status tool The agent inspects runs of every format, including autonomous container runs; a live run shows (active) or (active, paused)
workflow_control tool The agent controls a live run: {runId, action} with pause, resume, stop or skip

workflow_status and workflow_control are registered inactive and become callable once a run starts (a workflow_run or workflow call, a background subagent, a run started with a command, or a live or blocked autonomous run found when a prompt is sent), so a session that never runs a workflow does not carry their text; see Efficiency and loops. /workflows works throughout.

Esc cancels a workflow_run started by the agent. The current step's subagent is stopped, the run is marked interrupted, and it can be resumed.

The table's commands and tools are checked by tests/workflow-panel-smoke.ts (registration), tests/workflow-control-smoke.ts (pause, skip, stop and resume) and tests/workflow-smoke.ts (an interrupted run resumes); Esc cancellation is the tool call's signal, checked by tests/workflow-plan-smoke.ts.

Inline plans

workflow_run {steps: [...]} takes the step fields as JSON and runs them in the same executor as a saved workflow, without a file. A plan cannot set what would widen a step (model, thinking, extensions, max_runtime, skill), tools only narrow the role, and a refused plan returns the path, the problem and the fix with nothing started. (tests/workflow-plan-smoke.ts)

Plan examples

Each shape below is a valid plan. A task with one step, one file and one check is done directly rather than planned; plan when there are several steps, a fan-out or a check that can send work back.

(a) One step, defaulting to the implementer role:

{"steps":[{"task":"Fix the typo in README.md."}]}

(b) Parallel investigation, then a synthesis over {previous}:

{"steps":[{"id":"look","parallel":[{"id":"web","agent":"scout","task":"Read the web sources on rate limiting."},{"id":"db","agent":"scout","task":"Read the database code for rate limiting."}]},{"id":"sum","agent":"planner","task":"Combine: {previous}"}]}

(c) Review plus revise: the gate sends work back to build until the reviewer passes, at most twice:

{"steps":[{"id":"build","task":"Build the endpoint and run its tests."},{"id":"check","agent":"reviewer","task":"Review: {previous}. End with one line: VERDICT: PASS or VERDICT: FAIL.","gate":{"pass":"/(?:^|\\n)VERDICT: PASS\\s*$/","retry":"build","max_loops":2}}]}

(d) Bounded recovery: the first attempt may fail without failing the run, and a when step names its status before recovering:

{"steps":[{"id":"try","agent":"scout","task":"Try the first route.","continue_on_error":true},{"id":"recover","agent":"scout","task":"Recover: {{steps.try.status}}","when":{"step":"try","status":"failed"}}]}

tests/workflow-plan-smoke.ts pins all four: it parses these blocks, compiles each through compilePlan, and checks that together they cover the single-step, parallel, gate and when shapes.

Expanding a plan

A step with expand: true asks the host for more steps. Its final answer is one JSON object: {"steps": [...]}, a plan the host runs next, or {"done": "the result"}, which adds nothing and becomes the step's output. The child never gains a way to start agents: process depth stays 1, and the steps run as ordinary steps of the same run, so stop, failure, gates, status and the summary treat them like any other.

  • Ids. The steps run right after the expanding step, each id prefixed with the parent's: a under split is split.a, and its answer is steps/split.a.md. References inside the expansion follow the prefix. A step outside it cannot name an expanded step, and sees a spliced plan as the expanding step's output, so a later step reads expanded results from the run directory.
  • Inherited restrictions. The steps compile under every plan rule, and no step may have a tool the expanding step lacks, whether through tools or through its role, and like any plan step it cannot be a role that starts agents unless tools narrows that away. A planner cannot ask for an implementer unless the step narrows it to the planner's tools, so a step that should expand into writers has to be able to write. A role's model, thinking, extensions, run time limit and effort must also match the parent role's, so an expansion cannot reach a dearer model by naming a role that sets one, or the session's model by naming one that does not.
  • Budget. An expand step counts as 2 agents, for its one resample. The host charges each expansion's worst case to the same run scope and allowance before anything in it launches, and never past 60 step executions in the run.
  • Refused and invalid. An answer that is not valid JSON, or a plan that does not compile, is asked for once more with {path, problem, fix} added to the task; a second miss fails the step, and so does a miss when the run has no execution left for the second ask. An expansion past the depth limit, the allowance or the execution limit launches nothing, is recorded as an omission, and the run goes on to end partial, so the agent can replan within what is left of the allowance, or once it renews on the next user message. The step stays passed, but when and {{steps.<id>.status}} read it as skipped, and its output is the reason, so a later step does not act on work that never happened. A typed /workflows resume has no run scope to charge, so it refuses a new expansion the same way; it still replays one the run already charged.
  • Depth. strategy.expandDepth in the effort policy (3 by default) limits the generations one plan may reach.
  • Resume. Each expansion is saved in plan.json before it runs, so a resume replays it and does not ask the step again. A plan.json this process did not write is gated like a project workflow.

expand goes on a top-level step only. It is refused on a parallel member, with a gate on the same step, inside a segment a gate can go back over (the step would run twice), and in a saved workflow file, where it fails to parse: expansion is for inline plans only. (tests/workflow-plan-smoke.ts)

Pausing, stopping and skipping

Every live run in the session has one control (control.ts). The workflow_control tool and the /workflows pause|resume|skip|stop commands both call the same function (controlRun), so they behave the same. Only runs started in this pi process can be controlled; any other run id is refused with the list of live ones.

Action Effect
pause The executor waits at its scheduler gate before it launches any agent, so a paused run starts no new agents. Agents already running keep running and finish. state.json gets "paused": true while it lasts, and the run model shows paused.
resume Opens the gate; the next step launches. For a run that is not live, use workflow_run {resume} or /workflows resume instead.
stop Aborts the run's AbortController, which stops its running agents. The run ends interrupted and can be resumed. A step that was waiting at a paused gate never launches and keeps its old status.
skip Stops only the agents running now (each agent has its own AbortController under the run's). Their steps are recorded as skipped with the error "skipped by operator" (or "skipped by the agent" through the workflow_control tool), and the run goes on: a later when sees skipped, and a parallel group whose members were skipped passes. A skipped step's outputs: check does not run. Skip never passes a review gate: a skipped gate step, or a skipped member of a group that has a gate, fails that gate, so the run loops back to retry (while max_loops lasts) or ends failed, and the step after the gate does not run. The governed agent's skip of a required step is an omission, so the run reads partial; an operator's is not (tests/workflow-hooks-smoke.ts, r01). With nothing running, skip is refused.

workflow_control is allowed by the shipped firewall policy as process_control.

Resuming an interrupted writer step

A run stopped while a step was running leaves that step aborted (or running, after a crash). If that step can write, re-running it on resume would run on top of whatever it already changed. A step is a writer unless every tool it can use (its tools:, or else its role's) is read, grep, find or ls; a role with bash or with no tool list is a writer. So resuming a run whose current step, or any unfinished member of its current parallel group, is an interrupted writer asks first, with a select whose default is No:

  • "No, leave the run interrupted" (also Esc): the run is not resumed.
  • "Re-run the interrupted step(s)": resume as before.
  • "Skip the interrupted step(s)": mark them skipped, then continue with the next step (or the group's other unfinished members). A skipped step that has a gate (or a skipped member of a gated group) fails that gate, as a live skip does: the run loops back to retry or ends failed.

A headless resume of such a run is refused. Steps that never launched, and read-only steps, ask nothing.

Checked by tests/workflow-control-smoke.ts (npm run smoke:workflow-control), which also checks that both firewall policy copies hold the same workflow_control rule.

Where workflows live

Location Source Trust
packages/kit/workflows/*.md, *.js shipped with Luna (YAML: feature, bugfix, research; scripts: the built-ins) trusted
~/.pi/agent/workflows/*.md, *.js yours, available in every project trusted
.pi/workflows/*.md, *.js the project's needs a digest grant or interactive approval (see below)

*.md files are YAML workflows (this page). *.js files are script workflows. Both kinds share one set of names, and a later location overrides an earlier one with the same name, whatever its kind. Luna reads only these directories; Claude Code's .claude/workflows/ is not read.

The locations, the shared namespace and the override rule are checked in tests/workflow-registry-smoke.ts; the trust prompt and the headless refusal in tests/workflow-smoke.ts.

Trusting a project workflow

A project workflow can start any delegated work, so before it runs (a new run or a resume, from workflow_run or /workflows) Luna checks for a grant for the file's exact SHA-256:

  • a digest listed in PI_KIT_TRUSTED_WORKFLOWS (;-separated), or
  • a digest you trusted earlier, stored in <agent dir>/pi-kit/trusted-workflows.json (mode 0600). protected-paths blocks agent writes to that file, so the agent cannot plant a grant.

Without a grant, an interactive session asks with a select whose first, default option is No:

Choice Effect
No, don't run it (or Esc) The run is cancelled.
Run once This run goes ahead. Nothing is stored, so the next run asks again.
Trust this digest This run goes ahead and the digest is stored, so later runs of the same file, headless ones included, are not asked.

A headless session (no UI, for example pi -p) is refused unless a grant exists, and the error names the digest to grant. Editing the file changes its digest, so the old grant stops applying. A malformed store grants nothing. To revoke a grant, delete its entry from the store. These rules are checked in tests/workflow-smoke.ts, and the protected store in tests/protected-paths-smoke.ts.

Script workflows

A script workflow is a JavaScript file that starts with a literal meta object:

export const meta = {
  name: 'find-flaky-tests',                       // required, same pattern as a YAML name
  description: 'Find flaky tests and propose fixes', // required, shown in the trust prompt
  whenToUse: 'CI shows retries',                  // optional, shown in the list
  phases: [{ title: 'Scan', detail: 'grep logs' }, { title: 'Fix', model: 'provider/model' }],
}

The registry reads meta without running the script. Only whitespace and comments may come before it. It must be a pure literal: strings (template strings without ${}), numbers, true, false, null, arrays and objects with plain or quoted keys, plus comments and trailing commas. Variables, calls, spreads, computed or shorthand keys, methods, regexes, duplicate keys and __proto__ are parse errors, and so is an expression that continues after the literal (end it with ; or a new line). phases[] entries need a title and may have detail and model strings. Other keys are ignored. A script larger than 1 MiB is not listed, and an entry named *.js that is not a regular file (a directory or a FIFO) is skipped silently (tests/workflow-registry-smoke.ts). Errors show up under "Invalid workflow files" in /workflows list. A YAML and a script workflow with the same name in one directory is an error, and the script is skipped.

workflow_run list and /workflows list show script workflows as (<source>, script). The workflow tool runs them; workflow_run with a script's name returns an error that points to it.

Opening a script for a run (openScriptWorkflow in workflow-tools.ts) applies the same trust rules as a project YAML workflow: kit and user scripts open without a prompt, and a project script needs a digest grant or the No-first select described above. A script's workflow(name) call goes through the same function, with the calling workflow named in the prompt, so a nested project script is gated as well. That includes a project script that shadows a kit or user name. The script text it returns is the exact bytes whose SHA-256 was checked. These rules are checked in tests/workflow-meta-smoke.ts (npm run smoke:workflow-meta) and tests/workflow-registry-smoke.ts (npm run smoke:workflow-registry).

Format

A workflow is a Markdown file. The YAML frontmatter is the definition; the body is documentation for people.

---
name: feature                       # lowercase id; what /workflows run uses
description: One line shown in /workflows list
inputs:
  goal: { description: What to build, required: true }
  area: { description: Where to look, default: the whole repository }
vault: false                        # true: copy the finished run into the memory vault
steps:
  - id: scout                       # unique across the workflow
    agent: scout                    # a role: scout, planner, implementer, reviewer, or yours
    task: |
      Map the code relevant to: {{inputs.goal}} (look in {{inputs.area}})
  - id: plan
    agent: planner
    skills: [task-decomposition]    # SKILL.md bodies preloaded into this step's subagent
    task: |
      Plan {{inputs.goal}} using these findings:
      {{steps.scout.output}}
  - id: implement
    agent: implementer
    task: |
      Implement: {{steps.plan.output}}
      Previous review, if any: {{steps.review.output?}}
  - id: review
    agent: reviewer
    task: "Review against the plan: {{steps.plan.output}}"
    gate:
      pass: "/(?:^|\\n)VERDICT: PASS\\s*$/"     # text must be on the verdict line; or /regex/ (case-insensitive)
      retry: implement                            # an earlier top-level step to go back to
      max_loops: 2
---

Step fields

Field Meaning
id Required. a-z0-9_-, starting with a letter.
agent The role to run. Required unless skill is given (which defaults the role to implementer).
skill Shorthand for a step that exists to apply one skill: the skill is preloaded and the role defaults to implementer.
task Required. The subagent's task, a template (see below). The subagent can't see anything else, so make it self-contained.
skills Extra skills preloaded into the subagent's system prompt.
tools Restrict the subagent's tools, e.g. [read, grep, find, ls].
extensions Extra kit extensions for the isolated child, e.g. [memory-vault] so it can call memory_save.
model, thinking Per-step model (provider/id) and thinking level. The default is the role's model:, else the session model.
max_runtime Wall-clock limit for this step: 90s, 20m, 2h.
outputs Files (relative to the run directory) the step must write. It fails if they are missing.
when { step: <earlier id>, status: passed \| failed \| skipped } (or a list). Otherwise the step is skipped. A parallel group cannot take when, which is refused at parse time: put it on each member (tests/workflow-hooks-smoke.ts).
gate After the step passes, its output must match pass. If it doesn't, go back to retry (up to max_loops, a whole number from 0 to 10, default 2; anything else is refused at parse time). When the loops run out, the run fails. Plain text is matched case-insensitively against the verdict line (the last non-empty line); a /regex/ is tested on the last 64 KiB of the output, off the host's event loop, and a test that takes over a second is a miss; if that test cannot run at all, the run fails and says so. A step skipped by skip or on resume fails its gate; a step skipped by its own when does not check it. A gate goes on a top-level step or a parallel group; on a parallel member it is refused at parse time.
continue_on_error A failure of this step doesn't fail the run, which then reports partial.
parallel A list of steps run concurrently (up to 4 at once in a run you start with /workflows run; in a model-started run, the tier's maxConcurrent) instead of agent/task. The group passes when every member passes. Groups can't nest.

The format and its step fields are parsed and checked in tests/workflow-smoke.ts for a saved workflow and in tests/workflow-plan-smoke.ts for an inline plan, which refuses the fields that would widen a step.

Templates

Expression Value
{{inputs.<name>}} A run input (after defaults)
{{steps.<id>.output}} That step's final answer (for a parallel group: every member's answer under ## <id>)
{{steps.<id>.status}} passed, failed, skipped, …
{{file:<path>}} A file in the run directory (up to 64 KiB). Paths can't leave the run directory, and anything but a regular file with one link, such as a symbolic link or a FIFO, fails the step, even with ?.
{{run.dir}}, {{run.id}}, {{loop}} Run directory, run id, current gate loop

Add ? to make a missing value empty instead of an error, for example {{steps.review.output?}} on the first pass through a gate loop. Values are inserted verbatim; nothing inside them is re-expanded.

Templates, ? and the {{file:}} limits are checked by tests/workflow-smoke.ts and tests/workflow-plan-smoke.ts.

The blackboard (run directory)

Each run gets .pi/workflows/runs/<run-id>/:

state.json          status, current step, gate loops, per-step status/attempts/cost/run ids
steps/<id>.md       every step's final answer (what {{steps.<id>.output}} reads)
<anything else>     artefacts steps were asked to write, e.g. plan.md, report.md

Every step's subagent is told the run directory and the files already in it, so tasks can say "write your findings to findings.md" and later steps can use {{file:findings.md}}. Read-only roles (scout, planner) can't write files. Use their {{steps.<id>.output}} instead. With vault: true, a run that reaches its last step, passed or partial, is copied to ~/.pi/vault/Projects/<project>/Workflows/<run-id>/, so it can be picked up from another session or opened in Obsidian. (tests/workflow-hooks-smoke.ts)

Redaction and file modes

The executor redacts secrets before it writes state.json or steps/<id>.md (an expand answer waiting to be acted on is the one exception, below): the run's inputs, each step's answer and the step and run errors. Known secret shapes become [REDACTED]. These are the rules the trace ledger applies to its targets (authorization headers, password/secret/token/api_key assignments, user:password@ in URLs, sk- and gh*_ tokens) plus secret-guard's content patterns (private key blocks, which are removed whole, AWS key ids and secret keys, Slack tokens, GitHub tokens, sk- keys, credential assignments). Every state.json written this way carries "redacted": true and a redactionPolicy name. This is best-effort hygiene, not a security boundary. A secret in a shape the rules don't know is written as is, and files a step writes itself are not touched.

Because a later step's {{steps.<id>.output}} reads steps/<id>.md, it gets the redacted answer. A step's own prompt is built from the in-memory inputs, so it still gets the real input values. A resumed run reads its inputs back from state.json, though, so it gets the redacted ones.

A plan is the definition a resume runs, so plan.json is never redacted. A plan or expansion with text the kit's secret table matches is refused instead, by field name and never quoting it, and an expansion is resampled once, asked to name the credential instead. The table is not the wider redaction above, so a task may say "token" or "password" (tests/workflow-plan-smoke.ts). An expand step's answer is read as the child gave it, not from the redacted steps/<id>.md. Until the host acts on it, state.json holds that answer unredacted, if the table leaves it unchanged and it fits in 64 KiB. Otherwise a kill in that window loses the answer and a resume asks about the step like an interrupted writer.

The executor creates the run directory and steps/ with mode 0700 and writes state.json and steps/<id>.md with mode 0600, and it sets those modes again on each write. The redaction rules are copies, because extensions are self-contained. npm run verify and tests/workflow-redaction-smoke.ts fail if a copy stops being byte-identical to src/trace-ledger/index.ts or src/secret-guard/index.ts. The same test checks that redaction runs in linear time on adversarial input, and that a run's files are redacted and have the right modes.

Each step is an ordinary subagent run, so it also has a log under .pi/subagent/ (/workflows, workflow_status {id: <run>}). Such a step is not listed as a run of its own, but its id still shows its log and workflow_control can stop it. The step's run ids are recorded in state.json. A corrupt or wrong-shape state.json is ignored and not listed by /workflows status, rather than crashing the status listing. The persisted state must also carry a non-negative integer cursor and a finite executions count, or it is treated as corrupt and skipped the same way. Each entry in steps must be a mapping whose status is one of the known step statuses and whose attempts and cost are numbers and runIds is an array of strings, and every value in loops must be a number; otherwise the whole state is treated as corrupt.

Execution rules

  • Steps run top to bottom. A failing step fails the run, unless it has continue_on_error; such a run reports partial, and the rule is in Run status. A gate that misses and then passes stays passed. (tests/workflow-hooks-smoke.ts)
  • Gates loop back to retry, and every step from there to the gate runs again.
  • A run is capped at 60 step executions, counting loops. Each member of a parallel group is an execution, and a group that would pass the cap fails the run before any member starts (tests/workflow-hooks-smoke.ts, r06).
  • Resuming re-runs the interrupted step (in a parallel group, only the members that hadn't passed) and continues from there. inputs and finished outputs are kept.
  • Subagents in a workflow get the same governed launch as any subagent: --no-extensions plus the parent's protections, the companions and the step's extensions, with the child's own protection check (see Agent orchestration). A subagent can't start another workflow.
  • Effort budgets apply. /workflows run and /workflows resume are user-directed launches, limited only by the platform ceilings. The workflow_run tool, which the model calls, runs in its own run scope and is hidden at E1. The run's worst case (each step, plus every gated segment at its full max_loops) is charged to the tier's plan allowance before the first launch, so a run that does not fit is refused with nothing started, and the reason names /effort. The kit's bugfix and feature cost 8 and research costs 5, so each fits at E3 and above, one to a request at E3. A model-started resume opens a new scope and is charged only what has not passed. A parallel group runs at most the tier's maxConcurrent at once, and at 0 it starts nothing and fails the run. In a plan, a group with a member that can edit files runs its members one at a time, because nobody reviewed it; a saved workflow's author decides. (tests/workflow-builtin-smoke.ts, tests/workflow-plan-smoke.ts)
  • Steps do not delegate. An agent of a model-started run has E1 as its tier and cap, and gets neither the subagent tool nor its extension, whatever its role or step asks for (tests/workflow-builtin-smoke.ts). A plan also refuses a role that loads an extension which starts agents (tests/workflow-plan-smoke.ts).

Live telemetry

While a workflow runs, the subagent extension keeps an in-process record of it, the run model (run-model.ts). The run model is what a status view reads; it is not written to disk.

  • Phases. Every top-level step is a phase, listed in definition order when the run starts. A phase is pending, running, passed, failed, skipped or aborted. On resume, phases start with the status saved in state.json; a step left running by a crash shows as pending.
  • Agents. Every step execution is one agent, with id <step id>#<n>, so a step re-run by a gate loop appears as implement#1, implement#2. Members of a parallel group belong to the group's phase. Each agent records its label (the step id), phase, role, model, token usage (input, output, cache read and write, cost, turns), elapsed time and status (running, passed, failed, skipped or aborted), plus the subagent run id and the error text when there is one. Usage and the last progress line update after every child message, while the agent still runs. A step skipped by when is recorded as a skipped agent; a step whose template fails is a failed agent that never launched. In a script run an agent can also be marked cached (answered from a resumed run's journal) and carry the group (the nested workflow() it ran in), and a phase can name its parent group phase.
  • Runs. A run records its kind (yaml or script), name, the workflow's description, definition file and source (kit, user or project), status (running, passed, partial, failed, interrupted), whether it is paused, elapsed time, the usage summed over its agents and a count of approvals (noteApproval). A script run also records its sandbox mode, budget.total and the sha256 of the script it executed. A resumed run keeps its id, and its record starts again with this execution's agents. When a run ends, any agent still marked running is marked aborted. The registry keeps every active run and the 20 most recently finished ones.
  • Events. Listeners receive run_start, phase, agent and run_end events, each with a copy of the record, a control event when a live run is paused or resumed, and an approvals event when an approval is counted. A listener that throws is ignored, so telemetry cannot fail a run.
  • The pi-kit.subagents status snapshot ({ live, finished, failures }) also reports workflows, the number of workflow runs active in this process.

Records hold labels, ids, model names, counters and error text, never prompts or step outputs. Checked by tests/workflow-telemetry-smoke.ts (npm run smoke:workflow-telemetry); the script-run fields (cached, group, parent, approvals, sandbox, budget, digest) by tests/workflow-panel-smoke.ts.

The /workflows panel

Bare /workflows lists the runs of every format as text (tests/run-query-smoke.ts): workflow YAML and script runs, background subagents, and autonomous container runs under PI_AUTONOMY_HOME (else $XDG_STATE_HOME/pi-autonomy, else ~/.local/state/pi-autonomy). /workflows panel [run-id] opens the panel, which shows the workflow runs of this pi session, read from the run model above (wf-panel.ts). Runs started in another pi process are not shown there; use /workflows or workflow_status for those, and workflow_status {id} and workflow_control for a step's log and to stop it. The panel is modelled on Claude Code's workflow panel and shows YAML runs and script workflow runs (started by the workflow tool) alike; both can be saved with s.

In the TUI it opens as an overlay on pi 1.3.0 or newer (on older pi, as a plain custom component, the control-center hub's rule; tests/workflow-panel-smoke.ts checks the rule and the options passed on the installed pi). It has two views:

  • Run list (/workflows panel): one row per run, newest first, with a status dot, name, status, done/total agents, elapsed time and run id. ↑↓ select, Enter opens a run, Esc closes the panel. The selection stays on the highlighted run when a new run arrives while the list is open, and falls back to the row at the same position if that run is pruned from the session. If a run pruned from the session was open in the run view, the panel falls back to the list body and keys. An open stop or save choice still owns the keys while it is shown, so the fallback takes effect once that choice is answered.
  • Run view (Enter on a run, or /workflows panel <run-id>):
  • a header with the workflow's name and description, then the run's status (and paused), done/total agents, how many were cached (when any), elapsed time and id. A third line holds the badges that apply: sandbox: reduced when the script ran in the reduced sandbox, approvals: k when the run model has counted k tool-firewall approvals for the run, and budget: N% (used/total output tok) when the run has a budget.total (warning colour from 80%, error colour from 100%). The workflow engine does not count child approvals yet, and the workflow tool sets a budget only while ultracode standing mode has one (/effort ultracode --budget N), so otherwise only the sandbox badge appears for tool-started runs;
  • Phases with done/total: each phase's status dot, status and its done/total agents. A nested workflow() call shows as a ▸ <name> group whose phases are indented under it; the group counts its own agents and those of its phases;
  • Agents with done/total: each agent's id (<step id>#<n>), model, tokens (input plus output; cache reads and writes are not counted), elapsed time and status with a coloured dot. Every column is measured and cut in terminal display columns, not code points, so a long title, id, model or run name is truncated with an ellipsis to its cap and a wide glyph (a CJK character, an emoji) keeps the columns after it aligned, instead of pushing them over. An agent() call answered from a resumed run's journal (nothing launched) has a ◆ dot instead of ●. Agents of a nested workflow() are indented under a ▸ <name> line. ↑↓ select an agent; the selected agent's error, or else its last progress line, shows below the list. Up to ten agents show at a time (fewer on a short terminal) and the list scrolls with the selection;
  • Narrator: the last six lines of the run's narration, such as +14s scan#1 passed, 12.3k tok. Narration starts when the extension loads and records run start and end, phase status changes, agent starts and ends (with tokens and the error; a journal answer is narrated as reused from the journal, and a nested workflow's lines start with ▸ <name>:), pause and resume, and counted approvals. The last 40 lines of each run are kept in memory; nothing is written to disk.
  • the footer keys ↑↓ select · k skip · x stop · p pause · s save · esc back. Elapsed times tick once a second while the panel is open.

In the list view, on a terminal too short for the panel, the run list trims to a window around the selected run, keeping the header, footer and both rules, and shows … n above / … n more indicators for the runs it omits. In the run view, narration and extra phase/agent rows are dropped; the header, confirm block and footer are kept, and the selected agent is the last middle row dropped. Once even that does not fit, the middle collapses to one … n more line. Below the run-view minimum the confirm hint ↑↓ choose · enter confirm · esc cancel and the blank spacer before the confirm block give way first, so the question, choices and bottom rule stay. On a terminal shorter than that fixed block (roughly seven rows or fewer) the panel makes one last clamp: the body is cut to the row budget from the bottom up, so the bottom rule is always kept and, where the budget allows, the lines next to it (a confirm's choices or question, the list's footer); the framed panel then never grows past the host overlay's height cap. At those heights some of the middle content is not shown, and a one-line budget leaves only the bottom rule.

Key Effect
x Stop the run. Asks first, inside the panel, with "No, keep it running" highlighted; Enter on it or Esc keeps the run, and only "Stop the run" stops it, through the same controlRun as workflow_control. A run that is not live has nothing to stop.
k Skip the selected agent when it is running: it is cut off and recorded as skipped (its agent() call returns null in a script run, and a required one fails that run); other running agents are not touched. A finished agent, or a run that is not live, has nothing to skip.
p Pause a live run, or resume it when it is paused (controlRun). The footer shows p resume while paused, for YAML and script runs.
s Save the run's workflow into the project's .pi/workflows/. Asks first with "No, don't save" highlighted; when the file already exists the second choice is "Overwrite …", so an overwrite is No-first too. A YAML run's definition is copied under the same file name; the copy is a project workflow, so it overrides the Luna or user workflow of the same name in this project and goes through the trust prompt when it runs. A script run's script is saved as .pi/workflows/<name>.js only while the file still hashes to the sha256 of the script the run executed (checked when s is pressed and again at the write), and that digest is then trusted ("Trust this digest", in every project); for a script run the question names the sha256 and the second choice is "Save and trust …" or "Overwrite … and trust it", so the saved script runs without the trust prompt until the file changes. A run of a project workflow has nothing to save. The save is refused when .pi, .pi/workflows or the target file is a symlink (or not a directory / regular file), so a planted link cannot redirect the write outside the project.
Esc Back from a run to the list, then close the panel. In a stop or save choice, Esc means No.

Outside the TUI (RPC, pi -p, JSON mode) /workflows panel [run-id] prints the same content as text (as a notification when the mode has a UI, otherwise on stderr): the list followed by every run, or the one run asked for. The text lists each failed agent's error under it. A subagent child does not register /workflows.

While a run is active the footer status (setStatus, key workflows) summarises it: wf <name>: done/total agents, plus paused, budget N% and approvals: k when they apply, or wf: <n> running · done/total agents (and how many are paused) for several runs. It clears when no run is active. The subagent extension's session_start handler points it at the session's footer (sessions with a UI only), and session_shutdown clears it.

Checked by tests/workflow-panel-smoke.ts (npm run smoke:workflow-panel): a render snapshot of the run view and list, the keys, the No-first stop and save choices, the list cursor staying on the selected run when a newer run arrives (including Esc back from the run view) and the row it falls back to when that run is pruned, a YAML run feeding the panel, the text fallback and the overlay; for script runs, the ▸ groups, the ◆ dot and the badges, k skip, the No-first script save (digest trusted, overwrite, an edited script refused), the status line, and real engine runs (fake children) feeding the groups, ◆ on resume, the sandbox badge, p pause, k and s. tests/workflow-hooks-smoke.ts (npm run smoke:workflow-hooks) checks that a script run shows in the panel with its phases and agents.

Shipped workflows

  • feature: scout → plan → implement ↔ review (gate).
  • bugfix: reproduce → diagnose → fix ↔ verify (gate). The reviewer re-runs the reproduction itself.
  • research: three parallel scouts (code, tests, history) → synthesis → durable facts saved to memory; the run is copied to the vault.

tests/workflow-smoke.ts checks that all three parse, their names and both gates; tests/workflow-builtin-smoke.ts runs each with fake children and pins their worst-case agent counts (8, 8 and 5).

Writing your own: checklist

  1. Put it in ~/.pi/agent/workflows/<name>.md (all projects) or .pi/workflows/.
  2. Give every task everything the subagent needs. It sees only its task, preloaded skills, and the run-directory note.
  3. Pass results between steps with {{steps.<id>.output}}. Use files only when a writing role produces an artefact.
  4. Gate on something the role reliably prints, and anchor it so an echoed template or a quoted report can't match. The shipped feature and bugfix gates pass only when the reviewer's last non-blank line is VERDICT: PASS; VERDICT: PASS or FAIL, Passing..., or a PASS quoted before the reviewer's own FAIL all fail (checked in tests/workflow-smoke.ts).
  5. /workflows list shows validation errors for files that don't parse.

Worktree isolation for workflow agents

packages/extensions/third_party/subagent/worktree.ts gives a writing workflow agent its own git worktree. The script-workflow engine uses it for agent(..., {isolation: "worktree"}) and its writer lock; the YAML workflows above do not.

  • createWorkflowWorktree({cwd, runId, index}) runs git in the cwd it is given (the tool's ctx.cwd). It creates <repo>/.pi/worktrees/<runId>/<index> on branch luna/wf/<runId>/<index> from the checkout's HEAD. .pi/ is git-ignored, so the main checkout stays clean. A run id is letters, digits, _ and - (up to 64), and the index is a non-negative integer.
  • With the child's cwd set to the worktree, the worktree is its workspace: the worktree has its own .git file, which is where tool-firewall's workspace lookup stops.
  • finishWorkflowWorktree(tree, {journalFile}) removes the worktree and its branch when nothing changed (a clean status and HEAD still at the base commit). A changed worktree is kept with its branch and never merged. Its outcome (branch, head, commit count, whether it has uncommitted changes, and the reason) is appended to journalFile (mode 0600) when one is given. If git refuses the removal, the worktree is kept and journaled too. If the worktree was removed but its branch could not be deleted, the outcome is removed with a reason naming the branch.
  • Before it runs git in the worktree, finishWorkflowWorktree checks that the worktree's .git file still names the git dir recorded at creation, and that git dir's commondir still names the common dir. If either changed, the worktree is kept and journaled without being inspected. Its git commands name that git dir explicitly and run with core.fsmonitor=false, core.hooksPath=/dev/null and submodule.recurse=false, and its status check uses --ignore-submodules=dirty, so it never enters a nested repo (whose config, such as a clean filter, the agent controls); a staged or moved gitlink still counts as a change. A planted fsmonitor command, hook or nested-repo clean filter does not run in the parent (smoke:workflow-worktree).
  • At most 16 worktrees per checkout are live at once. A request beyond that waits for a slot rather than failing, and an abort signal cancels the wait.
  • withCheckoutLock(cwd, fn) runs writers that work in the main checkout one at a time, in arrival order. The lock lives in this process, so it orders one pi session's writers, not other processes.
  • protected-paths blocks writes to git's hooks/, config, info/ and worktrees/ in the repository's git common directory, and a linked worktree's own .git file, under both firewall policies. From inside a worktree it also blocks the main checkout's protected entries. What it finds for a cwd the first time (the session's cwd when it loads) is kept, so rewriting the .git file later drops none of it. A .git file that does not name a real git dir blocks every write (tests/workflow-worktree-smoke.ts).

Checked in tests/workflow-worktree-smoke.ts (npm run smoke:workflow-worktree).