repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs(ultra): sync workflow authoring semantics

f3c3a69a7252350a3bce8e0da27127af080c748c

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (3)

extensions/ultra/__tests__/skill.test.ts

Modified
68 68 expect(reference).toContain("re-evaluate each assignment");
71 + it("matches runtime positional and structured-output semantics", () => {
72 + const skill = fs.readFileSync(SKILL_PATH, "utf8");
73 + const reference = fs.readFileSync(SPEC_FORMAT_PATH, "utf8");
75 + expect(reference).toContain(
76 + "last declared parameter absorbs all remaining tokens",
77 + );
78 + expect(reference).not.toContain("extra tokens ignored");
79 + expect(reference).toContain("Every step returns a JSON object");
80 + expect(reference).toContain("`schema` validates");
81 + expect(skill).toContain(
82 + "how tightly its structured JSON output must be constrained by a schema",
83 + );
84 + });
71 86 it("keeps the reference doc and the validator in lockstep: every complete JSON example parses", () => {
72 87 // Extract every ```json fenced block from the canonical reference and run
73 88 // each *complete* spec (one with both `name` and `phases`) through the
94 109 "phases" in parsed;
95 110 if (isCompleteSpec) {
96 111 completeSpecs += 1;
97 - expect(() => parseWorkflow(parsed)).not.toThrow();
112 + const spec = parseWorkflow(parsed);
113 + for (const phase of spec.phases) {
114 + expect(phase.step.model).toMatch(/^(small|medium|big)$/);
115 + expect(phase.step.thinkingLevel).toMatch(
116 + /^(off|minimal|low|medium|high|xhigh)$/,
117 + );
100 121 // The doc must carry at least one full worked example, not only fragments.

extensions/ultra/skills/authoring-workflows/SKILL.md

Modified
47 47 - `fanout` needs an `over` — a literal array, or an interpolation token over
48 48 a prior phase's results (e.g. `{review.results[].findings[]}`).
49 49 - Optional `when` uses one existing selector; empty/false skips the phase and produces empty results.
50 - - The step `prompt`, its `tools`, and whether it needs structured output.
50 + - The step `prompt`, its `tools`, and how tightly its structured JSON output must be constrained by a schema.
52 52 3. **Apply the read-only fan-out rule.** A `fanout` step with tools must stay
53 53 within `read`, `grep`, `find`, `ls`, `bash` **and** the prompt must forbid

extensions/ultra/skills/authoring-workflows/references/spec-format.md

Modified
17 17 | `return` | no | string (one selector token) | Selects the workflow's final value from phase results. |
19 19 `args` may also declare `params`: an ordered list of input names. A bare
20 -`/ultra <name> tokA tokB` line then maps `tokA`, `tokB` onto them positionally
21 -(extra tokens ignored), exposed as `{args.NAME}`. Without `params`, pass inputs
22 -as a trailing JSON object — `/ultra <name> {"k": "v"}`. A missing `{args.NAME}`
23 -renders to the empty string.
20 +`/ultra <name> tokA tokB` line 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 <name> {"k": "v"}`. A missing `{args.NAME}` renders to the empty string.
25 22 ## Phases
58 55 | `tools` | no | string[] | Tool allowlist. Omit for a tool-less completion (pure reasoning). |
59 56 | `model` | no | string | `provider/id` override, or configured tier `small`/`medium`/`big`; defaults to the session model. |
60 57 | `thinkingLevel` | no | off…xhigh | Reasoning budget for this step. |
61 -| `schema` | no | string \| JSON Schema | A `schemas` name, or an inline schema. Forces structured output. |
58 +| `schema` | no | string \| JSON Schema | A `schemas` name, or an inline schema that validates structured output. |
63 -A string `schema` is a **name reference** and must resolve in the spec's
64 -`schemas` map, or validation fails.
60 +Every step returns a JSON object through completion parsing or the terminating `structured_output` tool.
61 +Without `schema`, any JSON object is accepted.
62 +A `schema` validates that object and is required when downstream phases depend on a stable shape.
63 +A string `schema` is a **name reference** and must resolve in the spec's `schemas` map, or validation fails.
66 65 Configured model tiers live in Pi settings under `ultra.modelTiers`.
67 66 If a step sets `model` to `small`, `medium`, or `big`, ultra resolves it through that map; an unset tier falls back to the session model.
137 136 "step": {
138 137 "prompt": "Read the file at {item} and return JSON with two string fields: path (the file path you were given) and summary (one sentence). Do not modify anything.",
139 138 "tools": ["read"],
139 + "model": "small",
140 + "thinkingLevel": "low",
140 141 "schema": {
141 142 "type": "object",
142 143 "properties": {
155 -## Worked example — two phases with a join key (the shipped `review`)
156 +## Worked example — two phases with a join key
157 158 Fan out a review across dimensions, then fan out verification over the flattened
158 159 findings. `Findings.file` → `Verdict.file` is the join key; `return` filters to
206 207 "step": {
207 208 "prompt": "Review the diff for {item} issues. Inspect it with `git diff {args.base}` (no base ref → the working tree; a base ref → everything since that ref), plus read/grep as needed; do not modify any files. Return JSON matching the Findings schema, and set each finding's file to the path it concerns.",
208 209 "tools": ["read", "bash", "grep", "find", "ls"],
210 + "model": "small",
211 + "thinkingLevel": "medium",
209 212 "schema": "Findings"
215 218 "over": "{review.results[].findings[]}",
216 219 "step": {
217 220 "prompt": "Adversarially try to refute this finding. Default to real=false if uncertain. Echo the finding's file verbatim in your verdict's file field so the verdict ties back to its finding. Finding: {item}",
221 + "model": "big",
222 + "thinkingLevel": "high",
218 223 "schema": "Verdict"