1 +#
Ultra Tool Guidance Design 5 +The `workflow` tool now exposes the structural `WorkflowSpecSchema`, but most schema fields have no descriptions.
6 +Calling agents can construct the correct object shape while still guessing two critical semantic contracts: string step schemas must exactly name top-level schemas, and interpolation uses a closed grammar.
7 +Runtime errors are actionable, but they arrive only after a failed tool call.
11 +Put invocation-critical semantics on the shared TypeBox schema fields that Pi exposes directly to tool callers.
14 +- exact named-schema references versus inline JSON Schema objects;
15 +- the complete interpolation grammar and the context matrix below;
16 +- phase identifier restrictions, uniqueness, and prior-phase references;
17 +- `single`, `fanout`, `over`, `when`, and `return` behavior;
18 +- read-only fan-out tools and mutation prohibition;
19 +- workflow inputs, model tiers, thinking levels, and output-schema purpose.
21 +Add a compact reminder to the top-level tool description and descriptions for tool `spec` arguments and run `args`.
22 +Do not duplicate the full reference in the top-level prompt.
23 +Do not auto-repair malformed specs or change runtime error handling because the observed errors already enabled immediate correction.
25 +Use the identifier pattern already enforced for argument names on phase IDs, matching the interpolation parser's accepted phase syntax.
26 +Reject duplicate phase IDs during `parseWorkflow`; `args` and `item` remain valid phase IDs because interpolation namespaces are segregated.
27 +These checks prevent unreferenceable IDs and result-map overwrites.
29 +##
Selector Context Matrix 31 +| Field | Accepted form | Available values | Additional rule |
32 +| --- | --- | --- | --- |
33 +| `step.prompt` | Text containing zero or more grammar tokens | args, current fan-out item, prior phase results/failures, flattened fields, one `where` filter | `{item}` is meaningful only in fan-out; literal braces are forbidden. |
34 +| `phase.when` | Exactly one brace-wrapped selector | args or prior phase results/failures; no current item | False, null, undefined, empty string, or empty array skips. |
35 +| fan-out `over` | Literal array or exactly one brace-wrapped selector | args or prior phase results/failures; no current item | Resolved selector must produce an array. |
36 +| workflow `return` | Exactly one brace-wrapped selector | args or any completed phase results/failures | No required result type. |
38 +The closed tokens are `{args.NAME}`, `{item}`, `{PHASE.results}`, `{PHASE.failures}`, `{PHASE.results[].FIELD[]}`, and `{EXPR | where FIELD}`.
39 +Phase and field identifiers use `[A-Za-z_][A-Za-z0-9_]*`.
43 +Support Pi's complete current set: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
44 +Update the bundled skill, canonical reference, README, tool schema guidance, and lockstep tests where they currently stop at `xhigh`.
46 +##
Semantic Synchronization 48 +Update `extensions/ultra/AGENTS.md` so runtime code, tool prompts/schema guidance, and bundled skill guidance must remain semantically synchronized.
49 +Add lockstep tests proving the generated tool schema carries the schema-reference, interpolation, and read-only fan-out rules already documented by the bundled skill/reference.
53 +- `extensions/ultra/spec.ts`: add shared schema descriptions, phase-ID pattern, and duplicate-ID rejection.
54 +- `extensions/ultra/index.ts`: add concise tool-level invocation guidance and run-argument descriptions.
55 +- `extensions/ultra/__tests__/spec.test.ts`: cover phase-ID syntax and uniqueness.
56 +- `extensions/ultra/__tests__/skill.test.ts`: enforce semantic guidance lockstep.
57 +- `extensions/ultra/__tests__/harness.test.ts`: verify registered tool guidance reaches callers.
58 +- `extensions/ultra/skills/authoring-workflows/SKILL.md`, its canonical reference, and `extensions/ultra/README.md`: synchronize current thinking levels and invocation semantics.
59 +- `extensions/ultra/AGENTS.md`: persist the synchronization rule.
63 +Run focused Ultra tests, the complete Ultra suite, formatting, lint, and repository checks through `mise` sequentially.