1 1 #
ultra workflow spec — canonical reference 3 -A workflow is a single JSON object. `parseWorkflow` (the same validator the
4 -runtime uses) checks it structurally and rejects anything malformed. This file
5 -is the authoritative format reference; the extension `README.md` links here
6 -rather than restating it.
3 +- a workflow is a single JSON object.
4 +- `parseWorkflow` uses the runtime validator to check it structurally and reject malformed specs.
5 +- this file is the authoritative format reference; the extension `README.md` links here rather than restating it.
7 +##
machine-readable contract 10 -| Field | Required | Type | Meaning |
11 -| ------------- | -------- | --------------------------- | -------------------------------------------------------------- |
12 -| `name` | yes | string (non-empty) | Workflow id. The file is invoked as `/ultra run <name>`. |
13 -| `description` | no | string | One line shown in the picker. |
14 -| `args` | no | object (`{ hint?, ... }`) | Declares run inputs; `hint` is the usage shown after the name. |
15 -| `schemas` | no | record<
string, JSON Schema> | Named, reusable output schemas referenced by steps. |
16 -| `phases` | yes | array (≥1) of phases | The ordered stages. Each is `single` or `fanout`. |
17 -| `return` | no | string (one selector token) | Selects the workflow's final value from phase results. |
9 +- the active `run_workflow` tool exposes the complete `WorkflowSpecSchema` for inline `spec` values.
10 +- that schema is the source for field names, requiredness, types, unions, and field descriptions.
11 +- `parseWorkflow()` remains the source for semantic checks and applies to saved and inline specs alike.
12 +- this reference avoids repeating the structural schema; it documents execution semantics, authoring rules, and valid examples.
19 -`args` may also declare `params`: an ordered list of input names. A bare
20 -`/ultra run <name> tokA tokB` maps tokens onto them positionally; the last declared parameter absorbs all remaining tokens so it can carry free text. Values are exposed as `{args.NAME}`. Without `params`, pass inputs as a trailing JSON object: `/ultra run <name> {"k": "v"}`. A missing `{args.NAME}` renders to the empty string.
14 +- `args` may declare `params`, an ordered list of input names.
15 +- `/ultra run <name> tokA tokB` maps tokens positionally; the last declared parameter absorbs remaining tokens as free text.
16 +- values are exposed as `{args.NAME}`.
17 +- without `params`, pass inputs as a trailing JSON object: `/ultra run <name> {"k": "v"}`.
18 +- a missing `{args.NAME}` renders to the empty string.
22 -##
Orchestrator output 20 +##
orchestrator output 24 -`return` selects the final value; without it, the last phase's results are used.
25 -For both tool and command results, the full aggregate is always stored once and every bounded model-facing envelope includes `fullOutputPath`.
26 -The selected value appears once when it fits, with phase counts, bounded failure diagnostics, and usage, not duplicated `phaseResults`.
27 -`executionStatus` is `finished`, `incomplete` for dropped steps, or `aborted`; `finished` describes execution only, not artifact quality or semantic success.
28 -Oversized values use a retrieval notice within the 50KB or 2000 lines limit.
29 -Complete contents, including intermediate results and failure inputs/transcript tails, remain in UI details.
30 -Read that file selectively when needed, rather than loading all intermediate work into context.
22 +- `return` selects the final value; without it, the last phase's results are used.
23 +- `report` optionally selects the human-facing value; without it, human rendering uses the existing `return`-based formatting.
24 +- tool and command results store the full aggregate once; every bounded model-facing envelope includes `fullOutputPath`.
25 +- the selected `return` value appears once in the bounded model-facing envelope when it fits, with phase counts, bounded failure diagnostics, and usage; `phaseResults` is not duplicated.
26 +- the selected `report` value is persisted in the full aggregate and rendered only on human-facing surfaces; it is omitted from the bounded model-facing envelope.
27 +- `executionStatus` is `finished`, `incomplete` for dropped steps, or `aborted`.
28 +- `finished` describes execution only, not artifact quality or semantic success.
29 +- oversized values use a retrieval notice within the 50KB or 2000 lines limit.
30 +- complete contents, including intermediate results and failure inputs/transcript tails, remain in UI details.
31 +- read that file selectively when needed instead of loading all intermediate work into context.
34 -A phase has an `id` (referenced by interpolation and `return`), a `kind`, a
35 -`step`, an optional `concurrency` cap, an optional `when` selector, and optional fan-out `writeIsolation`.
36 -Phase IDs must be unique identifiers matching `[A-Za-z_][A-Za-z0-9_]*`; the reserved phase ID `args` is forbidden because it belongs to the workflow-input namespace.
35 +- a phase has an `id`, `kind`, `step`, optional `concurrency`, optional `when`, and optional fan-out `writeIsolation`.
36 +- `id` is referenced by interpolation, `return`, and `report`.
37 +- phase IDs must match `[A-Za-z_][A-Za-z0-9_]*` and be unique.
38 +- the reserved phase ID `args` is forbidden because it belongs to the workflow-input namespace.
38 -- **`single`** — runs the step exactly once, for one synthesis / judge /
39 - aggregation pass over prior results. (`over` is accepted by the schema but
40 - **ignored** in v1; for per-item parallelism use `fanout`.)
41 -- **`fanout`** — runs the step once per element of `over`, concurrently (capped
42 - by `concurrency` and the engine's global pool). `over` is **required**.
40 +- **`single`** — runs the step once for synthesis, judging, or aggregation over prior results; `over` is accepted but ignored in v1.
41 +- **`fanout`** — runs the step once per `over` element, concurrently within `concurrency` and the engine's global pool; `over` is required.
44 -`when` uses the existing single-selector grammar.
45 -If it resolves to `false`, `null`, `undefined`, an empty string, or an empty array, the phase is skipped and records `{ ran: 0, ok: 0, dropped: 0 }` with empty results.
46 -Any other value runs the phase.
47 -A skipped phase may still be referenced later through empty `{PHASE.results}` and `{PHASE.failures}` arrays.
48 -There are no loops or arbitrary expressions.
43 +- `when` uses the existing single-selector grammar.
44 +- `false`, `null`, `undefined`, an empty string, or an empty array skips the phase and records `{ ran: 0, ok: 0, dropped: 0 }` with empty results.
45 +- any other value runs the phase.
46 +- a skipped phase remains addressable through empty `{PHASE.results}` and `{PHASE.failures}` arrays.
47 +- there are no loops or arbitrary expressions.
50 -`over` is either a literal array or a single interpolation token string (e.g.
51 -`"{review.results[].findings[]}"`).
49 +- `over` is a literal array or one interpolation token string, such as `"{review.results[].findings[]}"`.
50 +- `return` and `report` use the same single-selector grammar and resolve after all phases.
53 -###
Fan-out mutation ownership 52 +###
fan-out mutation ownership 55 -Without `writeIsolation`, a `fanout` step's initial tools must stay within Pi's core set:
56 -`read`, `grep`, `find`, `ls`, `bash`.
57 -The prompt must instruct the agent not to mutate anything.
58 -With `writeIsolation`, mutating tools are allowed and the non-empty rationale plus prompt must assign disjoint ownership to every item.
59 -Ultra trusts that declaration; it does not constrain paths or arbitrary custom mutators.
60 -Loaded extensions remain trusted to activate additional tools.
61 -Every listed tool must be available to sub-agents or Ultra refuses to start the workflow.
54 +- without `writeIsolation`, a `fanout` step's initial tools must stay within Pi's core set: `read`, `grep`, `find`, `ls`, and `bash`.
55 +- the prompt must instruct the agent not to mutate anything.
56 +- with `writeIsolation`, mutating tools are allowed; the non-empty rationale and prompt must assign disjoint ownership to every item.
57 +- Ultra trusts that declaration and does not constrain paths or arbitrary custom mutators.
58 +- loaded extensions remain trusted to activate additional tools.
59 +- every listed tool must be available to sub-agents or Ultra refuses to start the workflow.
65 -| Field | Required | Type | Meaning |
66 -| --------------- | -------- | --------------------- | ------------------------------------------------------------------------------------------------- |
67 -| `summary` | yes | string | One short progress-UI sentence describing the task; interpolates `{...}` tokens. |
68 -| `prompt` | yes | string | The exact agent instruction; interpolates `{...}` tokens (see below). |
69 -| `tools` | no | string[] | Initial tool set. Omit when the agent needs only the injected result-submission tool. |
70 -| `model` | no | string | Configured tier name or concrete `provider/model`; omitted uses the session model. |
71 -| `thinkingLevel` | no | off…max | Optional explicit reasoning override; normally omit it for the tier default. |
72 -| `dynamicExtensions` | no | string[]
\| selector | Stable catalog names, or one selector resolving to names, loaded in declared order. |
73 -| `schema` | no | string
\| JSON Schema | A `schemas` name, or an inline schema that validates structured output. |
63 +- schema-declared step fields and types are available through the active tool contract.
64 +- `summary` is rendered on tool and overlay agent rows.
65 +- `prompt` is the exact resolved child instruction.
66 +- model, tools, thinking-level, dynamic-extension, and output-schema behavior below describes runtime semantics not captured by field shape alone.
67 +- use the same interpolation grammar as `prompt` so fan-out rows can identify their item.
68 +- summary interpolation renders objects as short labels and arrays as counts; prompts retain compact JSON.
69 +- the overlay shows the exact resolved `prompt` as the first user message in that agent's transcript.
70 +- normal child context-file loading is enabled; children do not inherit the parent conversation.
71 +- prompts must supply the task context, constraints, instruction paths, evidence, and authority boundaries each child needs.
72 +- see [child context mechanics](../ultra-authoring/SKILL.md#give-children-context).
75 -`summary` is rendered on tool and overlay agent rows.
76 -Keep it concise and concrete; use the same interpolation grammar as `prompt` so fan-out rows can identify their item.
77 -Summary interpolation renders objects as short labels and arrays as counts; prompts retain compact JSON.
78 -The overlay separately shows the exact resolved `prompt` as the first user message in that agent's transcript.
79 -Normal child context-file loading is enabled; children do not inherit the parent conversation.
80 -Authored prompts must still supply task-specific parent constraints, applicable nested instruction paths, required evidence, and authority/blocker boundaries as required by the [delegation contract](../ultra-authoring/SKILL.md#delegation-contract).
81 -Provide tools to read those instructions and evidence; skill and reference contents remain on demand.
74 +- every step returns one JSON object through the terminating `structured_output` tool.
75 +- Ultra requests provider-side strict schema sampling when supported and always validates the submitted object locally.
76 +- when an agent stops without submitting, Ultra sends up to `ultra.maxRetries` focused reminders in the same session.
77 +- without `schema`, any JSON object is accepted.
78 +- `schema` validates that object and is required when downstream phases depend on a stable shape.
79 +- a string `schema` is a name reference and must resolve in the spec's `schemas` map.
83 -Every step returns a JSON object through the terminating `structured_output` tool.
84 -Ultra requests provider-side strict schema sampling when supported and always validates the submitted object locally.
85 -When an agent stops without submitting, Ultra sends up to `ultra.maxRetries` focused reminders in the same session.
86 -Without `schema`, any JSON object is accepted.
87 -A `schema` validates that object and is required when downstream phases depend on a stable shape.
88 -A string `schema` is a **name reference** and must resolve in the spec's `schemas` map, or validation fails.
81 +- configured model tiers live in Pi settings under `ultra.modelTiers`.
82 +- tier names are resolved dynamically, so a step may select any configured tier name.
83 +- an unknown bare tier name is invalid; a concrete `provider/model` reference is always valid.
84 +- omitting `model`, or selecting a tier whose `model` is `null`, uses the session model.
85 +- an explicit `thinkingLevel` overrides the tier default.
90 -Configured model tiers live in Pi settings under `ultra.modelTiers`.
91 -Their names are resolved dynamically, so a step may select any configured tier name.
92 -An unknown bare tier name is invalid; a concrete `provider/model` reference is always valid.
93 -Omitting `model`, or selecting a tier whose `model` is `null`, uses the session model.
94 -An explicit `thinkingLevel` overrides the tier default, but workflow authors normally omit it.
87 +###
dynamic extensions and builders 96 -###
Dynamic extensions and builders 89 +- `dynamicExtensions` names stable catalog identities, never hashes.
90 +- Ultra resolves each name to one validated hash and a run-local source snapshot before child creation.
91 +- normal configured extensions load first, then dynamic extensions in declared order.
92 +- a builder step selects all four tools or none: `search_dynamic_extensions`, `create_dynamic_extension`, `checkout_dynamic_extension`, and `validate_dynamic_extension`.
93 +- builders receive every available child tool except `run_workflow` plus the [builder contract](../dynamic-extension-builder.md).
94 +- known canonical names may load directly; discovery, creation, improvement, stale validation, and repair require a builder.
95 +- a builder failure blocks every later phase with typed `dynamic_extension_builder_failure` outcomes.
98 -`dynamicExtensions` names stable catalog identities, never hashes.
99 -Immediately before child creation, Ultra resolves each name to one validated hash and a run-local source snapshot; name and hash participate in the checkpoint key.
100 -Normal configured extensions load first, then dynamic extensions in declared order.
101 -`subagentExtensions: "none"` suppresses normal extensions only.
102 -Generated tools activate during `session_start`.
103 -Dynamic extensions may declare exact qualified normal-registration overrides, but Ultra's workflow and builder tool names remain reserved.
105 -A builder step selects all four tools or none: `search_dynamic_extensions`, `create_dynamic_extension`, `checkout_dynamic_extension`, and `validate_dynamic_extension`.
106 -Builders receive every available child tool except `run_workflow` plus a versioned authoring contract.
107 -Available host capability is not authorized scope; the brief must preserve applicable constraints, instruction paths, required evidence, and authority/blocker boundaries.
108 -These authoring obligations do not change validator contract version 2 or its validation gates.
109 -A builder failure blocks every later phase with typed `u008_builder_failure_blocker` outcomes; no normal-tool fallback exists.
110 -Known canonical names may load directly, but discovery, creation, improvement, stale validation, and repair require a builder.
99 +- when `run_workflow` is active, Ultra injects the effective tier rubric generated from merged `ultra.modelTiers` settings into the orchestrator system prompt.
100 +- a step's `model` names a configured tier or a concrete `provider/model` reference.
101 +- an unknown bare tier name is invalid; omitting `model` uses the session model.
102 +- a tier supplies a default `thinkingLevel`; an explicit step value overrides it.
103 +- tier instructions guide the orchestrator and are not passed to child agents.
112 -###
Model tier and thinking policy 105 +##
interpolation grammar 114 -When `run_workflow` is active, Ultra injects one effective tier rubric generated from merged `ultra.modelTiers` settings into the orchestrator system prompt.
115 -Use that rubric to choose each step's explicit tier selection; do not encode a hardcoded tier-to-role list here or in child prompts.
116 -Choose the least-compute tier likely to satisfy each step's acceptance criteria.
117 -Escalate only for a concrete remaining reasoning bottleneck that a lower tier cannot adequately handle.
118 -Broad scope, long prompts, routine review or debugging, and general importance do not justify more compute.
119 -Supply missing context or report blocked instead of compensating with a larger tier.
120 -Saved workflows retain their selected tier names.
122 -Normally omit `thinkingLevel` so settings decide the tier default.
123 -Set it only when that step has a distinct, explicitly justified reasoning need, because the explicit value wins over the tier default.
124 -Tier instructions guide the orchestrator's selection and are never model-specific child instructions.
125 -If every phase selects the same tier, re-evaluate whether their work actually warrants it.
127 -##
Interpolation grammar 129 -A closed mini-syntax — not an expression evaluator, no `eval`. Tokens
130 -(braces are literal here, shown without JSON quoting):
107 +- interpolation is a closed mini-syntax, not an expression evaluator, and has no `eval`.
108 +- braces below are literal and shown without JSON quoting:
133 111 {args.NAME} workflow input value
134 112 {item} current fanout item (string verbatim; else compact JSON)
135 113 {PHASE.results} a prior phase's results array (nulls retained positionally)
136 114 {PHASE.failures} a prior phase's typed failure array
137 -{PHASE.results[].FIELD[]} flatten: concat each result's FIELD array (nulls/missing skipped)
138 -{EXPR | where FIELD} keep elements whose boolean FIELD is truthy
115 +{PHASE.results[].FIELD[]} flatten: concat each result's FIELD array (nulls/missing skipped)
116 +{EXPR | where FIELD} keep elements whose boolean FIELD is truthy
117 +{EXPR | where FIELD == "VALUE"} keep elements whose string FIELD exactly equals VALUE
118 +{EXPR | groupBy FIELD} group records by exact string FIELD value
141 -Anything outside this grammar raises a validation error at run time. In a
142 -step `prompt`, the only literal braces allowed are these tokens — do not put
143 -raw `{`/`}` (e.g. an inline JSON example) in a prompt; describe the shape in
144 -words and use a `schema` instead.
121 +- `where FIELD` keeps records whose field is truthy.
122 +- `where FIELD == "VALUE"` keeps records whose field is a string exactly equal to VALUE; missing, null, and non-string fields do not match.
123 +- `groupBy FIELD` returns first-seen groups shaped as `{ "key": "...", "items": [...] }`; records with missing, null, or non-string fields are skipped.
124 +- group item order and group order follow the source array.
125 +- the left side of `where` and `groupBy` must resolve to an array.
126 +- anything outside this grammar raises a validation error at run time.
127 +- in a step `prompt`, literal braces are allowed only as these tokens.
128 +- describe inline JSON shapes in words and use a `schema` instead.
146 -###
Explicit linear recovery 130 +###
explicit linear recovery 148 -A dropped step appears in `{PHASE.failures}` with `agentId`, `index`, optional original `item`, `code`, `message`, `retryable`, `attempts`, optional `model`, optional `thinkingLevel`, optional accumulated `usage`, and an optional 2,000-character `transcriptTail`.
149 -Failure codes are `auth`, `transport`, `schema`, `missing-output`, `aborted`, or `session`.
151 -Use the non-empty failure array to condition and fan out one later recovery phase.
152 -Recovery must restate the original goal, scope, constraints, instruction paths, required evidence, tools, and output schema; failure diagnostics supplement the assignment, never replace it.
153 -This complete example reads only the root `package.json` to extract its declared package name and license, with one explicit recovery and a final selection that preserves blocked work.
154 -Supply `instructions` as a run input containing applicable parent constraints and instruction paths, or explicitly state that no additional task-specific instructions apply.
155 -No child may infer a license from repository conventions or change files to make the task succeed.
132 +- a dropped step appears in `{PHASE.failures}` with `agentId`, `index`, optional original `item`, `code`, `message`, `retryable`, `attempts`, optional `model`, optional `thinkingLevel`, optional accumulated `usage`, and an optional 2,000-character `transcriptTail`.
133 +- failure codes are `auth`, `transport`, `schema`, `missing-output`, `aborted`, `session`, or `dynamic_extension_builder_failure`.
134 +- use a non-empty failure array to condition and fan out one later recovery phase.
135 +- recovery must restate the original goal, scope, constraints, instruction paths, required evidence, tools, and output schema; failure diagnostics supplement the assignment, never replace it.
136 +- the example below reads only the root `package.json`, then recovers and selects an outcome that preserves blocked work.
137 +- supply `instructions` as a run input containing applicable parent constraints and instruction paths, or explicitly state that no additional task-specific instructions apply.
138 +- no child may infer a license from repository conventions or change files to make the task succeed.
216 -Ultra has no timeout, automatic rerun, loop, or back-edge.
217 -`ultra.maxRetries` sends result-submission reminders only after an agent turn ends without output; it never reruns the work in a fresh session.
218 -Workflow authors explicitly place any recovery phase after the failed phase.
199 +- Ultra has no timeout, automatic rerun, loop, or back-edge.
200 +- `ultra.maxRetries` sends result-submission reminders only after an agent turn ends without output; it never reruns the work in a fresh session.
201 +- workflow authors explicitly place any recovery phase after the failed phase.
220 -### Schema join-keys
203 +### schema join-keys
222 -When one phase fans out over another's findings, require a stable unique `id` in both schemas and instruct the consumer to echo it verbatim.
223 -Use the same ID-based join as the bundled review workflow: a review dimension, a colon, and a locally unique identifier containing only letters, digits, underscores, or hyphens, for example `correctness:1`.
224 -Keep IDs stable through verification and distinguish multiple findings in one file.
225 -`file` is a locator, not a unique join key; never merge or overwrite candidates merely because they share a file or title.
226 -Missing or duplicate verdict IDs remain unresolved work, not implicit refutations.
205 +- when one phase fans out over another's findings, require a stable unique `id` in both schemas and instruct the consumer to echo it verbatim.
206 +- use the same ID-based join as the bundled review workflow: a review dimension, a colon, and a locally unique identifier containing only letters, digits, underscores, or hyphens, such as `correctness:1`.
207 +- keep IDs stable through verification and distinguish multiple findings in one file.
208 +- `file` is a locator, not a unique join key; never merge or overwrite candidates merely because they share a file or title.
209 +- missing or duplicate verdict IDs remain unresolved work, not implicit refutations.
228 -## Worked example — minimal single fan-out
230 -Every `fanout` agent reads one path and returns a structured summary. Tools are
231 -read-only; the prompt forbids mutation.
213 +The gallery intentionally exercises the structural variants and selector forms accepted by the runtime.
214 +Each block is independently parsed and validated by the workflow reference tests.
220 + "name": "tiny-single",
225 + "step": { "summary": "Answer the request", "prompt": "Answer the request." }
231 +###
single with positional input 235 + "name":
"single-input",
236 + "args": {
"hint":
"<question>",
"params": [
"question"] },
241 + "step": {
"summary":
"Answer the question",
"prompt":
"Answer: {args.question}" }
244 + "return":
"{answer.results}" 252 + "name":
"literal-fanout",
257 + "over": [
"README.md",
"CHANGELOG.md",
"package.json"],
258 + "step": {
"summary":
"Inspect {item}",
"prompt":
"Read {item} and summarize it." }
261 + "return":
"{inspect.results}" 265 +###
input-driven fanout 269 + "name":
"input-fanout",
270 + "args": {
"hint":
"<paths>",
"params": [
"paths"] },
275 + "over":
"{args.paths}",
276 + "step": {
"summary":
"Inspect {item}",
"prompt":
"Read {item}; return its key facts." }
282 +###
ignored single over 286 + "name":
"single-over",
291 + "over": [
"ignored",
"also-ignored"],
292 + "step": {
"summary":
"Run once",
"prompt":
"Run this synthesis once." }
298 +###
conditional single 302 + "name":
"conditional-single",
303 + "args": {
"hint":
"optional input",
"params": [
"input"] },
308 + "step": {
"summary":
"Collect evidence",
"prompt":
"Collect evidence for {args.input}." }
313 + "when":
"{collect.results}",
314 + "step": {
"summary":
"Judge evidence",
"prompt":
"Judge {collect.results}." }
317 + "return":
"{judge.results}" 321 +###
conditional fanout 325 + "name":
"conditional-fanout",
330 + "step": {
"summary":
"Discover targets",
"prompt":
"Discover targets." }
335 + "when":
"{discover.results}",
336 + "over":
"{discover.results}",
337 + "step": {
"summary":
"Verify {item}",
"prompt":
"Verify target {item}." }
340 + "return":
"{verify.results}" 344 +###
flatten selector 348 + "name":
"flatten-findings",
353 + "over": [
"correctness",
"security"],
354 + "step": {
"summary":
"Review {item}",
"prompt":
"Review the {item} dimension." }
359 + "over":
"{review.results[].findings[]}",
360 + "step": {
"summary":
"Verify {item}",
"prompt":
"Verify finding {item}." }
363 + "return":
"{verify.results}" 371 + "name":
"truthy-filter",
374 + "id":
"candidates",
376 + "over": [
"a",
"b",
"c"],
377 + "step": {
"summary":
"Inspect {item}",
"prompt":
"Inspect candidate {item}." }
382 + "step": {
"summary":
"Select candidates",
"prompt":
"Select from {candidates.results | where valid}." }
385 + "return":
"{selected.results}" 389 +###
exact string filter 393 + "name":
"source-filter",
398 + "over": [
"sessions",
"repository",
"web"],
399 + "step": {
"summary":
"Collect {item} evidence",
"prompt":
"Collect evidence from {item}." }
404 + "when":
"{evidence.results | where source_type == \"sessions\"}",
405 + "over":
"{evidence.results | where source_type == \"sessions\"}",
406 + "step": {
"summary":
"Inspect session evidence {item}",
"prompt":
"Inspect session evidence {item}." }
409 + "return":
"{sessions.results}" 413 +###
dynamic grouping 417 + "name":
"source-groups",
422 + "over": [
"one",
"two",
"three"],
423 + "step": {
"summary":
"Collect evidence for {item}",
"prompt":
"Collect evidence for {item}." }
428 + "over":
"{evidence.results | groupBy source_type}",
429 + "step": {
"summary":
"Process source group {item}",
"prompt":
"Process this source group: {item}." }
432 + "return":
"{groups.results}" 436 +###
named output schema 440 + "name":
"named-schema",
444 + "properties": {
"title": {
"type":
"string" } },
445 + "required": [
"title"]
452 + "over": [
"src/a.ts",
"src/b.ts"],
453 + "step": {
"summary":
"Find issues in {item}",
"prompt":
"Inspect {item}.",
"schema":
"Finding" }
459 +###
inline output schema 463 + "name":
"inline-schema",
469 + "summary":
"Measure the target",
470 + "prompt":
"Measure the target and return its size.",
473 + "properties": {
"size": {
"type":
"number",
"minimum":
0 } },
474 + "required": [
"size"]
482 +###
explicit concurrency 486 + "name":
"bounded-fanout",
491 + "over": [
1,
2,
3,
4,
5,
6],
493 + "step": {
"summary":
"Inspect item {item}",
"prompt":
"Inspect item {item}." }
496 + "return":
"{inspect.results}" 500 +###
explicit model and reasoning 504 + "name":
"routed-review",
510 + "summary":
"Review the change",
511 + "prompt":
"Review the supplied change carefully.",
513 + "thinkingLevel":
"high" 520 +###
concrete provider model 524 + "name":
"concrete-model",
530 + "summary":
"Extract the value",
531 + "prompt":
"Extract the requested value.",
532 + "model":
"provider/model-id",
533 + "thinkingLevel":
"low" 537 + "return":
"{extract.results}" 541 +###
read-only fanout tools 545 + "name":
"read-only-review",
550 + "over": [
"correctness",
"security"],
551 + "tools": [
"read",
"grep",
"find",
"ls",
"bash"],
552 + "step": {
"summary":
"Review {item}",
"prompt":
"Review {item}; do not mutate anything." }
558 +###
isolated mutation fanout 562 + "name":
"isolated-edits",
567 + "over": [
"src/a.ts",
"src/b.ts"],
568 + "writeIsolation":
"Each item owns exactly one disjoint source file.",
569 + "tools": [
"read",
"edit"],
570 + "step": {
"summary":
"Update {item}",
"prompt":
"Update only {item}; it is exclusively yours." }
576 +###
dynamic extension consumer 580 + "name":
"dynamic-consumer",
581 + "args": {
"hint":
"<extension names>",
"params": [
"extensions"] },
587 + "summary":
"Inspect with extensions",
588 + "prompt":
"Inspect the task with the requested capabilities.",
589 + "dynamicExtensions":
"{args.extensions}" 596 +###
dynamic extension builder 600 + "name":
"dynamic-builder",
606 + "summary":
"Build the requested capability",
607 + "prompt":
"Discover or build the requested capability using the builder contract.",
608 + "tools": [
"search_dynamic_extensions",
"create_dynamic_extension",
"checkout_dynamic_extension",
"validate_dynamic_extension"]
614 + "step": {
"summary":
"Use the capability",
"prompt":
"Use the validated capability." }
617 + "return":
"{use.results}" 621 +###
independent human report 625 + "name":
"separate-report",
630 + "step": {
"summary":
"Do the full work",
"prompt":
"Produce complete machine-readable evidence." }
635 + "step": {
"summary":
"Prepare the report",
"prompt":
"Prepare a concise human report from {work.results}." }
638 + "return":
"{work.results}",
639 + "report":
"{human.results}" 643 +###
explicit report selector 647 + "name":
"report-projection",
652 + "step": {
"summary":
"Produce report data",
"prompt":
"Produce report data." }
655 + "return":
"{work.results}",
656 + "report":
"{work.results}" 664 + "name":
"empty-fanout",
670 + "step": {
"summary":
"Process {item}",
"prompt":
"Process {item}." }
673 + "return":
"{nothing.results}" 681 + "name":
"recover-failure",
686 + "over": [
"one",
"two"],
687 + "step": {
"summary":
"Try {item}",
"prompt":
"Try the task for {item}." }
692 + "when":
"{first.failures}",
693 + "over":
"{first.failures}",
694 + "step": {
"summary":
"Recover {item}",
"prompt":
"Recover the failed task described by {item}." }
697 + "return":
"{recover.results}",
698 + "report":
"{first.failures}" 702 +###
arbitrary input metadata 706 + "name":
"metadata-input",
707 + "args": {
"hint":
"<task>",
"params": [
"task"],
"owner":
"workflow-team",
"labels": [
"safe",
"read-only"] },
712 + "step": {
"summary":
"Complete the task",
"prompt":
"Complete {args.task}." }
718 +###
three-stage pipeline 722 + "name":
"three-stage",
723 + "args": {
"hint":
"<target>",
"params": [
"target"] },
728 + "step": {
"summary":
"Research {args.target}",
"prompt":
"Research {args.target}." }
733 + "step": {
"summary":
"Plan the work",
"prompt":
"Create a plan from {research.results}." }
738 + "step": {
"summary":
"Check the plan",
"prompt":
"Check the plan in {plan.results}." }
741 + "return":
"{check.results}",
742 + "report":
"{plan.results}" 746 +###
multi-fanout pipeline 750 + "name":
"multi-fanout",
755 + "over": [
"a.ts",
"b.ts",
"c.ts"],
756 + "step": {
"summary":
"Inspect {item}",
"prompt":
"Inspect {item}." }
761 + "over":
"{files.results}",
762 + "step": {
"summary":
"Test {item}",
"prompt":
"Test the evidence for {item}." }
767 + "step": {
"summary":
"Summarize the pipeline",
"prompt":
"Summarize {files.results} and {tests.results}." }
770 + "return":
"{summary.results}" 774 +###
complex mixed workflow 778 + "name":
"complex-mixed",
779 + "description":
"Research, filter, verify, recover, and report a multi-dimensional review.",
780 + "args": {
"hint":
"<target>",
"params": [
"target",
"instructions"] },
784 + "properties": {
"id": {
"type":
"string" },
"valid": {
"type":
"boolean" } },
785 + "required": [
"id",
"valid"]
789 + "properties": {
"id": {
"type":
"string" },
"status": {
"type":
"string" } },
790 + "required": [
"id",
"status"]
797 + "over": [
"correctness",
"security",
"performance"],
799 + "tools": [
"read",
"grep",
"find",
"ls",
"bash"],
800 + "step": {
"summary":
"Research {item}",
"prompt":
"Research {item} for {args.target}; {args.instructions}.",
"schema":
"Candidate",
"model":
"large" }
805 + "when":
"{research.results}",
806 + "over":
"{research.results | where valid}",
807 + "step": {
"summary":
"Verify {item}",
"prompt":
"Verify candidate {item}.",
"schema":
"Verdict",
"model":
"large",
"thinkingLevel":
"high" }
812 + "when":
"{verify.failures}",
813 + "over":
"{verify.failures}",
814 + "step": {
"summary":
"Recover {item}",
"prompt":
"Recover failed verification {item}.",
"schema":
"Verdict",
"model":
"medium" }
819 + "step": {
"summary":
"Write the final report",
"prompt":
"Write a report from {research.results}, {verify.results}, and {recover.results}." }
822 + "return":
"{verify.results}",
823 + "report":
"{report.results}" 827 +##
worked example — minimal single fan-out 829 +- every `fanout` agent reads one path and returns a structured summary.
830 +- tools are read-only and the prompt forbids mutation.
263 -## Worked example: two phases with a unique finding join key
862 +## worked example: two phases with a unique finding join key
265 -Fan out a review across dimensions, then fan out verification over the flattened findings.
266 -`Findings.findings[].id` → `Verdict.id` is the join key, even for several findings in one file.
267 -The single `params` entry maps `/ultra run review main` to `{args.base}`; an empty base selects `git diff`, the unstaged working-tree diff.
268 -A base ref selects the current tracked working tree against that ref, not an unrelated comparison chosen by the verifier.
269 -Supply applicable task-specific parent constraints and instruction paths through the `instructions` input when constructing or invoking this example with JSON arguments.
270 -Verification receives that same original base, constraints, candidate detail, and evidence, plus explicit inspection tools.
271 -`bash` is authorized only for read-only Git inspection, not arbitrary commands or tests that write caches.
272 -The selected output preserves every verdict, including unresolved ones; the closed selector grammar cannot compare status strings and must not filter uncertainty away.
273 -Typed phase failures accompany the selected output, so missing verifier results remain visible as incomplete work.
864 +- fan out a review across dimensions, then fan out verification over the flattened findings.
865 +- `Findings.findings[].id` → `Verdict.id` is the join key, including several findings in one file.
866 +- the single `params` entry maps `/ultra run review main` to `{args.base}`; an empty base selects the unstaged working-tree diff.
867 +- a base ref selects the current tracked working tree against that ref, not an unrelated comparison chosen by the verifier.
868 +- supply task-specific parent constraints and instruction paths through `instructions` when constructing or invoking this example with JSON arguments.
869 +- verification receives the original base, constraints, candidate detail, and evidence, plus explicit inspection tools.
870 +- `bash` is authorized only for read-only Git inspection, not arbitrary commands or tests that write caches.
871 +- the selected output preserves every verdict, including unresolved ones; the closed selector grammar cannot compare status strings or filter uncertainty away.
872 +- typed phase failures accompany the selected output, so missing verifier results remain visible as incomplete work.
349 -## Where workflows live
948 +## where workflows live
351 -Discovery merges three locations, lowest-to-highest precedence — a later source
352 -overrides a bundled name:
354 -1. **bundled** — `<extension>/workflows/*.json` (ships with ultra)
355 -2. **global** — `~/.pi/agent/workflows/*.json`
356 -3. **project** — `<cwd>/.pi/workflows/*.json`
358 -Save an authored workflow as `<name>.json` (filename should match the spec's
359 -`name`) in the project dir for repo-scoped workflows, or the global dir for
950 +- discovery merges three locations, lowest-to-highest precedence; a later source overrides a bundled name.
951 +- **bundled** — `<extension>/workflows/*.json` (ships with Ultra)
952 +- **global** — `~/.pi/agent/workflows/*.json`
953 +- **project** — `<cwd>/.pi/workflows/*.json`
954 +- save an authored workflow as `<name>.json`, with a filename matching the spec's `name`, in the project directory for repo-scoped workflows or the global directory for personal workflows.