---
name: ultra-authoring
description: "Use when authoring or editing Ultra workflow specs or before calling run_workflow."
---

# authoring Ultra workflows

read the [workflow reference](../references/spec-format.md) before constructing
or editing a workflow spec.
read the [dynamic-extension builder contract](../dynamic-extension-builder.md)
when a workflow discovers, creates, improves, validates, or repairs an extension.

## choose the command

- `/ultra exec <instructions>` sends an inline request and does not save a workflow.
- `/ultra run <name> [args]` runs a saved workflow.
- `run_workflow` accepts a saved `name` or an inline `spec` object.
- use an inline spec unless the user explicitly requests a reusable saved workflow.
- save project workflows as `<cwd>/.pi/workflows/<name>.json`.
- save personal workflows as `~/.pi/agent/workflows/<name>.json`.
- ask for scope only when project versus personal ownership is unclear.

## build the spec

- a spec is one JSON object with a `name` and at least one phase.
- phases run in order and use `single` for one child or `fanout` for one child per `over` item.
- `fanout` requires `over`; `single` ignores `over`.
- phase IDs are unique identifiers; `args` is reserved.
- `when` skips a phase when its selector resolves to a false, null, undefined, empty string, or empty array value.
- `return` selects the final value; without it, the last phase's results are returned.
- `report` optionally selects a human-facing value independently from `return`; it is also returned to the agent.
- use `args` for declared run inputs and `schemas` for output shapes reused by later phases.

## give children context

children run in separate sessions and do not inherit the parent conversation.
supply each prompt with the task context, constraints, instruction paths, evidence,
and authority boundaries it needs.
normal child context-file loading remains enabled, but it does not replace that
prompt-specific context.
Ultra automatically wraps fresh assignments with workflow, phase, and agent identity.
prior-agent outputs inserted through interpolation are automatically quoted with
immediate producer identity and task summary.
do not add manual agent identity or provenance wrappers to workflow prompts.

## connect phases

use only the closed interpolation grammar in `summary`, `prompt`, `over`, `when`,
`return`, and `report`.
use `{item}` for the current fanout item and phase selectors for prior results or
failures.
keep literal braces out of child prompts unless they are interpolation tokens.
`where FIELD` filters truthy fields; `where FIELD == "VALUE"` filters exact strings.
`groupBy FIELD` returns first-seen `{key, items}` groups for generic fanout.
use a `schema` when a later phase consumes a stable output shape.
when joining findings to later results, carry a stable ID through both schemas.

## control tools

all listed tools must be available to children or Ultra refuses to start.
loaded extensions may activate additional tools.
without `writeIsolation`, a fanout step may select only the initial tools listed in the current `ultra fanout tool policy` system section, and its prompt forbids mutation.
other initial tools require `writeIsolation` with genuine disjoint ownership assigned to every fanout item; do not invent ownership to bypass validation.
every child returns one JSON object through `structured_output`.
some extension tools stay off until a flag enables them; set `flags` on the step as the `ultra sub-agent flags` system section describes, or the step fails.

## use dynamic extensions

`dynamicExtensions` names published catalog extensions by stable identity.
publication attests artifact identity, not quality; repair reported Pi load or test failures before consumption.
known names load into the child in declared order.
discovery, creation, improvement, validation, and repair use one builder step with
all four tools: `search_dynamic_extensions`, `create_dynamic_extension`,
`copy_dynamic_extension`, and `validate_dynamic_extension`.
the builder receives the linked contract; a builder failure blocks later phases with code `dynamic_extension_builder_failure`.

## select models

`model` resolves a configured tier or a concrete `provider/model` reference.
omitting `model` uses the session model.
`thinkingLevel` overrides the selected tier's default.
an unknown bare tier name fails validation.

## inspect results

`return` selects the value shown to the orchestrator.
`report` selects the value rendered to the human and included alongside `return` in the tool result.
Unselected data remains available through the full aggregate path.
the result includes failures, usage, and `fullOutputPath` for complete evidence.
read that path selectively when the bounded result is insufficient.
a dropped step appears in its phase's failures and can feed one later recovery phase;
there are no automatic loops.
execution status describes execution, not artifact quality or semantic success.

## save and run

for a persisted workflow, write `<name>.json` in the selected workflow directory.
the filename must match the spec's `name`.
runtime validation checks the complete spec when it loads or runs.
after saving, offer `/ultra run <name>` with any declared arguments.