pi-ext bugabingas pi extensions
owned by bugabinga
README Source History Refs Compare Notes Search feat(ultra): positional base-ref args + rename ultra-review → review 9eb707fb4f857221d2cdc91376d11c1cf56b9acd
Oliver Jan Krylow <oliver@bugabinga.net > · 29 Jun 2026
unsigned
Browse files Compare with HEAD
Add an optional `args.params` to the workflow spec: a bare `/ultra <name>
<tok…>` line maps whitespace tokens onto the declared positional names in
order (exposed as `{args.NAME}`). So `/ultra review main` now scopes the
review via `git diff {args.base}`, while a bare `/ultra review` leaves
`base` empty and falls back to the working tree. The model-callable
`workflow` tool is unchanged — it still passes a structured `args` object.
Rename the sole shipped workflow `ultra-review` → `review` (git mv) and wire
`{args.base}` into its review prompt. Update the spec/example tests, README,
and the authoring skill + spec-format reference (incl. a `params` note). The
generic `ultra-review` strings in wire.test.ts stay — they are prefix-match
and parser fixtures, not references to the shipped file.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Changed files (11) extensions/ultra/README.md Modified 42 42 2. **global** — `~/.pi/agent/workflows/*.json`
43 43 3. **project** — `<cwd>/.pi/workflows/*.json`
45 - The shipped `ultra-review` workflow reviews the working diff across dimensions,
46 - then adversarially verifies each finding — run it with
47 - `/ultra ultra-review [base-ref]`.
45 + The shipped `review` workflow reviews the diff across dimensions, then
46 + adversarially verifies each finding — run it with `/ultra review [base-ref]`
47 + (no base ref reviews the working tree; a base ref reviews everything since it).
extensions/ultra/__tests__/example.test.ts Modified 10 10 const here
= path.
dirname (
fileURLToPath (
import .
meta .url));
11 - const EXAMPLE_PATH
= path.
join (here,
".." ,
"workflows" ,
"ultra-review.json" );
11 + const EXAMPLE_PATH
= path.
join (here,
".." ,
"workflows" ,
"review.json" );
19 19 return fs.
readFileSync (EXAMPLE_PATH,
"utf8" );
22 - describe (
"ultra-review shipped example" , ()
=> {
22 + describe (
"review shipped example" , ()
=> {
23 23 it (
"parses through parseWorkflow without error (validates the actual shipped file)" , ()
=> {
25 25 const spec
= parseWorkflow (
loadRaw ());
26 - expect (spec.
name ).
toBe (
"ultra-review" );
26 + expect (spec.
name ).
toBe (
"review" );
27 27 expect (spec.phases).
toHaveLength (
2 );
28 28 expect (spec.phases[
0 ].
id ).
toBe (
"review" );
29 29 expect (spec.phases[
1 ].
id ).
toBe (
"verify" );
32 + it (
"declares the base-ref positional and scopes the review diff by {args.base}" , ()
=> {
33 + const spec
= parseWorkflow (
loadRaw ());
36 + expect (spec.args?.params).
toEqual ([
"base" ]);
37 + const review
= spec.phases.
find ((p)
=> p.
id === "review" );
39 + expect (review?.step.
prompt ).
toContain (
"{args.base}" );
32 42 it (
"Verdict schema includes required `file` and the verify prompt echoes the finding's file (correction #6b)" , ()
=> {
33 43 const spec
= parseWorkflow (
loadRaw ());
115 - it (
"is discoverable as a bundled workflow named `ultra-review`" , ()
=> {
125 + it (
"is discoverable as a bundled workflow named `review`" , ()
=> {
118 128 const emptyCwd
= fs.
mkdtempSync (path.
join (os.
tmpdir (),
"ultra-cwd-" ));
119 129 const emptyHome
= fs.
mkdtempSync (path.
join (os.
tmpdir (),
"ultra-home-" ));
121 131 const found
= discoverWorkflows (emptyCwd, { home: emptyHome });
122 - const review
= found.
find ((w)
=> w.
name === "ultra-review" );
132 + const review
= found.
find ((w)
=> w.
name === "review" );
123 133 expect (review).
toBeDefined ();
124 134 expect (review?.
source ).
toBe (
"bundled" );
extensions/ultra/__tests__/spec.test.ts Modified 37 37 required : [
"title" ,
"real" ,
"file" ],
42 42 function validSpec ()
: any {
44 - name:
"ultra-review" ,
46 46 "Review the diff across dimensions, then adversarially verify each finding." ,
47 47 args: { hint:
"[base-ref]" },
76 76 describe (
"parseWorkflow" , ()
=> {
77 - it (
"parses a valid ultra-review-shaped spec (object input)" , ()
=> {
77 + it (
"parses a valid review-shaped spec (object input)" , ()
=> {
78 78 const parsed
= parseWorkflow (
validSpec ());
79 - expect (parsed.
name ).
toBe (
"ultra-review" );
79 + expect (parsed.
name ).
toBe (
"review" );
80 80 expect (parsed.phases).
toHaveLength (
2 );
81 81 expect (parsed.phases[
0 ].kind).
toBe (
"fanout" );
82 82 expect (parsed.return).
toBe (
"{verify.results | where real}" );
85 85 it (
"parses a valid spec from a JSON string" , ()
=> {
86 86 const parsed
= parseWorkflow (
JSON .
stringify (
validSpec ()));
87 - expect (parsed.
name ).
toBe (
"ultra-review" );
87 + expect (parsed.
name ).
toBe (
"review" );
90 90 it (
"accepts a single phase without `over`" , ()
=> {
extensions/ultra/__tests__/wire.test.ts Modified 4 4 import { describe, expect, it, vi }
from "vitest" ;
5 5 import type { UltraProgressEvent }
from "../progress.ts" ;
6 6 import type { DiscoveredWorkflow, WorkflowSpec }
from "../spec.ts" ;
8 8 completeWorkflowNames,
9 9 makeToolProgressSink,
11 12 resolveWorkflowInput,
12 13 }
from "../wire.ts" ;
13 14 phases : [{ id:
"p" , kind:
"single" , step: { prompt:
"hi" } }],
17 + const specWithParams = (name
: string , params
: string [])
: WorkflowSpec => ({
20 + phases: [{ id:
"p" , kind:
"single" , step: { prompt:
"hi {args.base}" } }],
16 23 const discovered = (
18 25 source
: DiscoveredWorkflow [
"source" ],
155 162 expect (out.args).
toBeUndefined ();
165 + it (
"maps a bare positional remainder to the spec's declared args.params" , ()
=> {
166 + const wf
: DiscoveredWorkflow = {
169 + path:
"/bundled/rev.json" ,
170 + spec:
specWithParams (
"rev" , [
"base" ]),
172 + const out
= resolveWorkflowInput ({ name:
"rev" }, [wf],
"main" );
173 + expect (out.args).
toEqual ({ base:
"main" });
176 + it (
"ignores a positional remainder when the spec declares no params" , ()
=> {
177 + const out
= resolveWorkflowInput ({ name:
"audit" }, list,
"main" );
178 + expect (out.args).
toBeUndefined ();
181 + it (
"prefers an explicit JSON args object over the positional remainder" , ()
=> {
182 + const wf
: DiscoveredWorkflow = {
185 + path:
"/bundled/rev.json" ,
186 + spec:
specWithParams (
"rev" , [
"base" ]),
188 + const out
= resolveWorkflowInput (
189 + { name:
"rev" , args: { base:
"dev" } },
193 + expect (out.args).
toEqual ({ base:
"dev" });
158 196 it (
"throws with the available names for an unknown name" , ()
=> {
159 197 expect (()
=> resolveWorkflowInput ({ name:
"missing" }, list)).
toThrow (
160 198 /ultra-review | audit/ ,
203 241 expect (
parseCommandLine (
"ultra-review" )).
toEqual ({ name:
"ultra-review" });
206 - it (
"parses a trailing JSON object as args" , ()
=> {
244 + it (
"parses a trailing JSON object as args (retaining the raw rest)" , ()
=> {
207 245 expect (
parseCommandLine (
'ultra-review {"base":"main","n":2}' )).
toEqual ({
208 246 name:
"ultra-review" ,
209 247 args: { base:
"main" , n:
2 },
248 + rest:
'{"base":"main","n":2}' ,
213 - it (
"ignores malformed / non-object trailing text but keeps the name" , ()
=> {
214 - expect (
parseCommandLine (
"ultra-review not json" )).
toEqual ({
252 + it (
"keeps non-JSON trailing text as `rest` (for positional mapping)" , ()
=> {
253 + expect (
parseCommandLine (
"ultra-review main" )).
toEqual ({
215 254 name:
"ultra-review" ,
217 257 expect (
parseCommandLine (
"ultra-review [1,2]" )).
toEqual ({
218 258 name:
"ultra-review" ,
268 + describe (
"mapPositionalArgs" , ()
=> {
269 + it (
"fills declared params in order from whitespace tokens" , ()
=> {
270 + expect (
mapPositionalArgs (
"main" , [
"base" ])).
toEqual ({ base:
"main" });
271 + expect (
mapPositionalArgs (
"a b" , [
"x" ,
"y" ])).
toEqual ({ x:
"a" , y:
"b" });
274 + it (
"ignores tokens beyond the declared params" , ()
=> {
275 + expect (
mapPositionalArgs (
"main extra" , [
"base" ])).
toEqual ({ base:
"main" });
278 + it (
"returns undefined for an empty remainder or no declared params" , ()
=> {
279 + expect (
mapPositionalArgs (
" " , [
"base" ])).
toBeUndefined ();
280 + expect (
mapPositionalArgs (
"main" , [])).
toBeUndefined ();
extensions/ultra/index.ts Modified 192 192 let resolved
: { spec
: WorkflowSpec ; args
?: Record <
string ,
unknown > };
194 - const { name, args }
= parseCommandLine (argString);
195 - resolved
= resolveWorkflowInput ({ name, args },
discover (ctx.cwd));
194 + const { name, args, rest }
= parseCommandLine (argString);
195 + resolved
= resolveWorkflowInput (
198 202 err
instanceof Error ? err.message
: String (err),
extensions/ultra/skills/authoring-workflows/SKILL.md Modified 49 49 4. **Design schemas and join-keys.** Give a step a `schema` (named in `schemas`,
50 50 or inline) when a later phase consumes its output. When phase B fans out over
51 51 phase A's findings, add a shared field (a join-key) to both schemas and tell
52 - B to echo it, so each result ties back to its source. See the `ultra-review`
52 + B to echo it, so each result ties back to its source. See the `review`
53 53 worked example in the reference.
55 55 5. **Wire interpolation.** Use only the closed grammar (`{args.NAME}`, `{item}`,
extensions/ultra/skills/authoring-workflows/references/spec-format.md Modified 16 16 | `phases` | yes | array (≥1) of phases | The ordered stages. Each is `single` or `fanout`. |
17 17 | `return` | no | string (one selector token) | Selects the workflow's final value from phase results. |
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.
21 27 A phase has an `id` (referenced by interpolation and `return`), a `kind`, a
113 - ## Worked example — two phases with a join key (the shipped `ultra-review`)
119 + ## Worked example — two phases with a join key (the shipped `review`)
115 121 Fan out a review across dimensions, then fan out verification over the flattened
116 122 findings. `Findings.file` → `Verdict.file` is the join key; `return` filters to
117 - the verdicts the verifier judged `real`.
123 + the verdicts the verifier judged `real`. The single `params` entry lets a bare
124 + `/ultra review main` map `main` to `{args.base}` (a missing arg renders empty, so
125 + the diff falls back to the working tree).
121 - "name": "ultra-review",
122 130 "description": "Review the diff across dimensions, then adversarially verify each finding.",
123 - "args": { "hint": "[base-ref]" },
131 + "args": { "hint": "[base-ref]", "params": ["base"] },
126 134 "type": "object",
160 168 "kind": "fanout",
161 169 "over": ["correctness", "security", "performance"],
163 - "prompt": "Review the working diff for {item} issues. Use git (via bash) and read tools to inspect the changes; do not modify any files. Return JSON matching the Findings schema, and set each finding's file to the path it concerns.",
171 + "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.",
164 172 "tools": ["read", "bash", "grep", "find", "ls"],
165 173 "schema": "Findings"
extensions/ultra/spec.ts Modified 63 63 description : Type.
Optional (Type.
String ()),
64 64 args : Type.
Optional (
66 - { hint: Type.
Optional (Type.
String ()) },
67 + hint: Type.
Optional (Type.
String ()),
71 + params: Type.
Optional (
72 + Type.
Array (Type.
String ({ pattern:
"^[A-Za-z_][A-Za-z0-9_]*$" })),
67 75 { additionalProperties:
true },
extensions/ultra/wire.ts Modified 111 112 export function parseCommandLine (raw
: string )
: {
113 114 args
?: Record <
string ,
unknown >;
115 117 const trimmed
= raw.
trim ();
116 118 if (
! trimmed)
return {};
126 128 typeof parsed
=== "object" && 127 129 ! Array .
isArray (parsed)
129 - return { name, args: parsed
as Record <
string ,
unknown > };
131 + return { name, args: parsed
as Record <
string ,
unknown >, rest };
136 + return { name, rest };
146 + export function mapPositionalArgs (
148 + params
: readonly string [],
149 + )
: Record <
string ,
unknown >
| undefined {
150 + const tokens
= rest.
trim ().
split (
/\s + / ).
filter (
Boolean );
151 + if (tokens.
length === 0 || params.
length === 0 )
return undefined ;
152 + const out
: Record <
string ,
unknown >
= {};
153 + params.
forEach ((name, i)
=> {
154 + if (i
< tokens.
length ) out[name]
= tokens[i];
156 + return Object .
keys (out).
length > 0 ? out
: undefined ;
149 171 export function resolveWorkflowInput (
150 172 input
: WorkflowInput ,
151 173 discovered
: readonly DiscoveredWorkflow [],
152 175 )
: ResolvedWorkflow {
153 176 if (input.spec
!== undefined ) {
154 177 return { spec:
parseWorkflow (input.spec), args: input.args };
168 - return { spec:
parseWorkflow (found.spec), args: input.args };
191 + const spec
= parseWorkflow (found.spec);
192 + let args
= input.args;
195 + if (args
=== undefined && rest
&& spec.args?.params?.
length ) {
196 + args
= mapPositionalArgs (rest, spec.args.params);
198 + return { spec, args };
171 201 'ultra: provide either a workflow "name" or an inline "spec".' ,
extensions/ultra/workflows/review.json Added new file mode 100644 3 + "description" :
"Review the diff across dimensions, then adversarially verify each finding." ,
4 + "args" : {
"hint" :
"[base-ref]" ,
"params" : [
"base" ] },
14 + "title" : {
"type" :
"string" },
15 + "file" : {
"type" :
"string" },
16 + "detail" : {
"type" :
"string" }
18 + "required" : [
"title" ,
"file" ]
22 + "required" : [
"findings" ]
27 + "title" : {
"type" :
"string" },
28 + "real" : {
"type" :
"boolean" },
29 + "why" : {
"type" :
"string" },
32 + "description" :
"echo of the reviewed finding's file, for correlation" 35 + "required" : [
"title" ,
"real" ,
"file" ]
42 + "over" : [
"correctness" ,
"security" ,
"performance" ],
44 + "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." ,
45 + "tools" : [
"read" ,
"bash" ,
"grep" ,
"find" ,
"ls" ],
46 + "schema" :
"Findings" 52 + "over" :
"{review.results[].findings[]}" ,
54 + "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.\n\nFinding: {item}" ,
59 + "return" :
"{verify.results | where real}" extensions/ultra/workflows/ultra-review.json Deleted deleted file mode 100644 2 - "name" :
"ultra-review" ,
3 - "description" :
"Review the diff across dimensions, then adversarially verify each finding." ,
4 - "args" : {
"hint" :
"[base-ref]" },
14 - "title" : {
"type" :
"string" },
15 - "file" : {
"type" :
"string" },
16 - "detail" : {
"type" :
"string" }
18 - "required" : [
"title" ,
"file" ]
22 - "required" : [
"findings" ]
27 - "title" : {
"type" :
"string" },
28 - "real" : {
"type" :
"boolean" },
29 - "why" : {
"type" :
"string" },
32 - "description" :
"echo of the reviewed finding's file, for correlation" 35 - "required" : [
"title" ,
"real" ,
"file" ]
42 - "over" : [
"correctness" ,
"security" ,
"performance" ],
44 - "prompt" :
"Review the working diff for {item} issues. Use git (via bash) and read tools to inspect the changes; do not modify any files. Return JSON matching the Findings schema, and set each finding's `file` to the path it concerns." ,
45 - "tools" : [
"read" ,
"bash" ,
"grep" ,
"find" ,
"ls" ],
46 - "schema" :
"Findings" 52 - "over" :
"{review.results[].findings[]}" ,
54 - "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.\n\nFinding: {item}" ,
59 - "return" :
"{verify.results | where real}"