repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

feat(ultra): positional base-ref args + rename ultra-review → review

9eb707fb4f857221d2cdc91376d11c1cf56b9acd

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare 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).
49 49 ## Settings

extensions/ultra/__tests__/example.test.ts

Modified
9 9 // The shipped example lives beside the runtime's bundled-workflows lookup.
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");
13 13 // Read-only tool allowlist for the v1 read-only-`fanout` isolation rule. Every
14 14 // `fanout` step in the shipped example must stay within this set (this example
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)", () => {
24 24 // Pass the raw string so JSON.parse runs too — a malformed file fails loudly.
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());
34 + // The `[base-ref]` hint is backed by a declared positional param, so
35 + // `/ultra review <ref>` maps the bare token to `args.base`.
36 + expect(spec.args?.params).toEqual(["base"]);
37 + const review = spec.phases.find((p) => p.id === "review");
38 + // The prompt actually consumes the arg (empty ⇒ working tree; ref ⇒ since-ref).
39 + expect(review?.step.prompt).toContain("{args.base}");
40 + });
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`", () => {
116 126 // Empty project/global dirs => only the bundled dir (the real shipped file)
117 127 // contributes. `discoverWorkflows` keys on the `name` field.
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");
125 135 } finally {

extensions/ultra/__tests__/spec.test.ts

Modified
37 37 required: ["title", "real", "file"],
40 -// Mirrors the design's ultra-review example (design lines 104-164). Both
40 +// Mirrors the design's review example (design lines 104-164). Both
41 41 // referenced schema names (Findings + Verdict) are defined.
42 42 function validSpec(): any {
43 43 return {
44 - name: "ultra-review",
44 + name: "review",
45 45 description:
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";
7 7 import {
8 8 completeWorkflowNames,
9 9 makeToolProgressSink,
10 + mapPositionalArgs,
10 11 parseCommandLine,
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 => ({
18 + name,
19 + args: { params },
20 + phases: [{ id: "p", kind: "single", step: { prompt: "hi {args.base}" } }],
21 +});
16 23 const discovered = (
17 24 name: string,
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 = {
167 + name: "rev",
168 + source: "bundled",
169 + path: "/bundled/rev.json",
170 + spec: specWithParams("rev", ["base"]),
171 + };
172 + const out = resolveWorkflowInput({ name: "rev" }, [wf], "main");
173 + expect(out.args).toEqual({ base: "main" });
174 + });
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();
179 + });
181 + it("prefers an explicit JSON args object over the positional remainder", () => {
182 + const wf: DiscoveredWorkflow = {
183 + name: "rev",
184 + source: "bundled",
185 + path: "/bundled/rev.json",
186 + spec: specWithParams("rev", ["base"]),
187 + };
188 + const out = resolveWorkflowInput(
189 + { name: "rev", args: { base: "dev" } },
190 + [wf],
191 + "main",
192 + );
193 + expect(out.args).toEqual({ base: "dev" });
194 + });
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",
255 + rest: "main",
217 257 expect(parseCommandLine("ultra-review [1,2]")).toEqual({
218 258 name: "ultra-review",
259 + rest: "[1,2]",
264 +// ---------------------------------------------------------------------------
265 +// mapPositionalArgs — bare `/ultra <name> <tok...>` → declared args.params
266 +// ---------------------------------------------------------------------------
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" });
272 + });
274 + it("ignores tokens beyond the declared params", () => {
275 + expect(mapPositionalArgs("main extra", ["base"])).toEqual({ base: "main" });
276 + });
278 + it("returns undefined for an empty remainder or no declared params", () => {
279 + expect(mapPositionalArgs(" ", ["base"])).toBeUndefined();
280 + expect(mapPositionalArgs("main", [])).toBeUndefined();
281 + });
282 +});

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(
196 + { name, args },
197 + discover(ctx.cwd),
198 + rest,
199 + );
196 200 } catch (err) {
197 201 ctx.ui.notify(
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.
19 25 ## Phases
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).
119 127 ```json
121 - "name": "ultra-review",
129 + "name": "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"] },
124 132 "schemas": {
125 133 "Findings": {
126 134 "type": "object",
160 168 "kind": "fanout",
161 169 "over": ["correctness", "security", "performance"],
162 170 "step": {
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(
65 65 Type.Object(
66 - { hint: Type.Optional(Type.String()) },
66 + {
67 + hint: Type.Optional(Type.String()),
68 + // Declared positional params: a bare `/ultra <name> <tok...>` line
69 + // maps whitespace tokens to these names in order, exposed as
70 + // `{args.NAME}`. Names must be interpolation identifiers.
71 + params: Type.Optional(
72 + Type.Array(Type.String({ pattern: "^[A-Za-z_][A-Za-z0-9_]*$" })),
73 + ),
74 + },
67 75 { additionalProperties: true },

extensions/ultra/wire.ts

Modified
106 - * Parse a raw `/ultra <name> [json-args]` command line: the first whitespace
107 - * token is the workflow name; an optional trailing JSON object is the run args.
108 - * Malformed trailing JSON is ignored (treated as no args) rather than failing
109 - * the command — the name still resolves.
106 + * Parse a raw `/ultra <name> [args]` command line: the first whitespace token is
107 + * the workflow name; the remainder is either a trailing JSON object (used as the
108 + * run args directly) or bare text returned verbatim as `rest` for positional
109 + * mapping against the spec's declared `args.params` (see `mapPositionalArgs`).
110 + * The name always resolves regardless of the remainder's shape.
111 112 export function parseCommandLine(raw: string): {
112 113 name?: string;
113 114 args?: Record<string, unknown>;
115 + rest?: string;
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 };
131 133 } catch {
132 - // non-JSON trailing text → ignore in v1 (name still resolves)
134 + // non-JSON trailing text → kept as `rest` for positional mapping
134 - return { name };
136 + return { name, rest };
139 +/**
140 + * Map a bare command-line remainder to named args using a workflow's declared
141 + * positional `params`: whitespace-split tokens fill `params` in order, extra
142 + * tokens are ignored. Returns `undefined` when nothing maps (empty remainder or
143 + * no declared params). Only the `/ultra` command uses this — the `workflow`
144 + * tool passes a structured `args` object directly.
145 + */
146 +export function mapPositionalArgs(
147 + rest: string,
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];
155 + });
156 + return Object.keys(out).length > 0 ? out : undefined;
137 159 /** Resolved run input: a validated spec + its run args. */
149 171 export function resolveWorkflowInput(
150 172 input: WorkflowInput,
151 173 discovered: readonly DiscoveredWorkflow[],
174 + rest?: string,
152 175 ): ResolvedWorkflow {
153 176 if (input.spec !== undefined) {
154 177 return { spec: parseWorkflow(input.spec), args: input.args };
165 188 // malformed file still lists in the picker) — `/ultra <name>` then fails
166 189 // fast with parseWorkflow's TypeBox path error instead of crashing the
167 190 // engine mid-run on a raw, unvalidated object.
168 - return { spec: parseWorkflow(found.spec), args: input.args };
191 + const spec = parseWorkflow(found.spec);
192 + let args = input.args;
193 + // Positional fallback: a bare `/ultra <name> <tok...>` line (no JSON args
194 + // object) maps to the spec's declared `args.params` in order.
195 + if (args === undefined && rest && spec.args?.params?.length) {
196 + args = mapPositionalArgs(rest, spec.args.params);
198 + return { spec, args };
170 200 throw new Error(
171 201 'ultra: provide either a workflow "name" or an inline "spec".',

extensions/ultra/workflows/review.json

Added
new file mode 100644
1 +{
2 + "name": "review",
3 + "description": "Review the diff across dimensions, then adversarially verify each finding.",
4 + "args": { "hint": "[base-ref]", "params": ["base"] },
5 + "schemas": {
6 + "Findings": {
7 + "type": "object",
8 + "properties": {
9 + "findings": {
10 + "type": "array",
11 + "items": {
12 + "type": "object",
13 + "properties": {
14 + "title": { "type": "string" },
15 + "file": { "type": "string" },
16 + "detail": { "type": "string" }
17 + },
18 + "required": ["title", "file"]
19 + }
20 + }
21 + },
22 + "required": ["findings"]
23 + },
24 + "Verdict": {
25 + "type": "object",
26 + "properties": {
27 + "title": { "type": "string" },
28 + "real": { "type": "boolean" },
29 + "why": { "type": "string" },
30 + "file": {
31 + "type": "string",
32 + "description": "echo of the reviewed finding's file, for correlation"
33 + }
34 + },
35 + "required": ["title", "real", "file"]
36 + }
37 + },
38 + "phases": [
39 + {
40 + "id": "review",
41 + "kind": "fanout",
42 + "over": ["correctness", "security", "performance"],
43 + "step": {
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"
47 + }
48 + },
49 + {
50 + "id": "verify",
51 + "kind": "fanout",
52 + "over": "{review.results[].findings[]}",
53 + "step": {
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}",
55 + "schema": "Verdict"
56 + }
57 + }
58 + ],
59 + "return": "{verify.results | where real}"

extensions/ultra/workflows/ultra-review.json

Deleted
deleted file mode 100644
1 -{
2 - "name": "ultra-review",
3 - "description": "Review the diff across dimensions, then adversarially verify each finding.",
4 - "args": { "hint": "[base-ref]" },
5 - "schemas": {
6 - "Findings": {
7 - "type": "object",
8 - "properties": {
9 - "findings": {
10 - "type": "array",
11 - "items": {
12 - "type": "object",
13 - "properties": {
14 - "title": { "type": "string" },
15 - "file": { "type": "string" },
16 - "detail": { "type": "string" }
17 - },
18 - "required": ["title", "file"]
19 - }
20 - }
21 - },
22 - "required": ["findings"]
23 - },
24 - "Verdict": {
25 - "type": "object",
26 - "properties": {
27 - "title": { "type": "string" },
28 - "real": { "type": "boolean" },
29 - "why": { "type": "string" },
30 - "file": {
31 - "type": "string",
32 - "description": "echo of the reviewed finding's file, for correlation"
33 - }
34 - },
35 - "required": ["title", "real", "file"]
36 - }
37 - },
38 - "phases": [
39 - {
40 - "id": "review",
41 - "kind": "fanout",
42 - "over": ["correctness", "security", "performance"],
43 - "step": {
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"
47 - }
48 - },
49 - {
50 - "id": "verify",
51 - "kind": "fanout",
52 - "over": "{review.results[].findings[]}",
53 - "step": {
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}",
55 - "schema": "Verdict"
56 - }
57 - }
58 - ],
59 - "return": "{verify.results | where real}"
60 -}