pi-ext bugabingas pi extensions
owned by bugabinga
README Source History Refs Compare Notes Search feat(ultra): add conditional workflow phases
72fc24ffaf5387b3611d4e7f360388b70dc8025b
Oliver Jan Krylow <oliver@bugabinga.net > · 13 Jul 2026
unsigned
Browse files Compare with HEAD
Changed files (11) extensions/ultra/README.md Modified 50 50 (no base ref reviews the working tree; a base ref reviews everything since it).
52 52 The shipped `feature` workflow drives a small feature end to end —
53 - research → plan → adversarial critique → implement → security/quality review —
54 - run it with `/ultra feature <describe the task>` (the whole trailing text is the
55 - task). Only its `implement` phase writes; every other phase is read-only.
53 + research → plan → adversarial critique → conditional implement → conditional security/quality review —
54 + run it with `/ultra feature <describe the task>` (the whole trailing text is the task).
55 + Implementation runs only when critique approves the plan.
56 + Only its `implement` phase writes; every other phase is read-only.
58 + The shipped `bug` workflow drives investigate → regression test → conditional fix → adversarial verification.
59 + Run it with `/ultra bug <describe the bug>`.
60 + The fix runs only after the regression phase proves the expected failure; verification runs only after a fix.
extensions/ultra/__tests__/bug.test.ts Added new file mode 100644 1 + import * as fs
from "node:fs" ;
2 + import * as os
from "node:os" ;
3 + import * as path
from "node:path" ;
4 + import { fileURLToPath }
from "node:url" ;
5 + import { describe, expect, it }
from "vitest" ;
6 + import { discoverWorkflows, parseWorkflow }
from "../spec.ts" ;
8 + const here
= path.
dirname (
fileURLToPath (
import .
meta .url));
9 + const BUG_PATH
= path.
join (here,
".." ,
"workflows" ,
"bug.json" );
10 + const READ_ONLY_TOOLS
= new Set ([
"read" ,
"grep" ,
"find" ,
"ls" ,
"bash" ]);
12 + function loadRaw ()
: string {
13 + return fs.
readFileSync (BUG_PATH,
"utf8" );
16 + describe (
"bug shipped workflow" , ()
=> {
17 + it (
"parses the investigate → regression → fix → verify flow" , ()
=> {
18 + const spec
= parseWorkflow (
loadRaw ());
19 + expect (spec.
name ).
toBe (
"bug" );
20 + expect (spec.args?.params).
toEqual ([
"bug" ]);
21 + expect (spec.phases.
map ((phase)
=> phase.
id )).
toEqual ([
29 + it (
"chains evidence forward and conditionally skips fix and verification" , ()
=> {
30 + const spec
= parseWorkflow (
loadRaw ());
31 + const get = (id
: string )
=> spec.phases.
find ((phase)
=> phase.
id === id);
33 + expect (
get (
"regression" )?.step.
prompt ).
toContain (
"{investigate.results}" );
34 + expect (
get (
"fix" )?.step.
prompt ).
toContain (
"{regression.results}" );
35 + expect (
get (
"fix" )?.when).
toBe (
"{regression.results | where ready}" );
36 + expect (
get (
"verify" )?.step.
prompt ).
toContain (
"{fix.results}" );
37 + expect (
get (
"verify" )?.when).
toBe (
"{fix.results | where fixed}" );
38 + const fix
= spec.schemas?.Fix
as { required
?: string [] };
39 + expect (fix.required).
toContain (
"fixed" );
42 + it (
"writes only in sequential regression and fix phases; verification fans out read-only" , ()
=> {
43 + const spec
= parseWorkflow (
loadRaw ());
44 + for (
const id
of [
"regression" ,
"fix" ]) {
45 + const phase
= spec.phases.
find ((candidate)
=> candidate.
id === id);
46 + expect (phase?.kind).
toBe (
"single" );
47 + expect (phase?.step.tools).
toEqual (
48 + expect.
arrayContaining ([
"edit" ,
"write" ]),
52 + const verify
= spec.phases.
find ((phase)
=> phase.
id === "verify" );
53 + expect (verify?.kind).
toBe (
"fanout" );
54 + expect (verify?.over).
toEqual ([
"regression" ,
"correctness" ,
"security" ]);
55 + for (
const tool
of verify?.step.tools
?? []) {
56 + expect (READ_ONLY_TOOLS.
has (tool)).
toBe (
true );
60 + it (
"contains no loop construct" , ()
=> {
61 + expect (
loadRaw ()).not.
toMatch (
/"loop" | "repeat"/ );
64 + it (
"is discoverable as a bundled workflow" , ()
=> {
65 + const cwd
= fs.
mkdtempSync (path.
join (os.
tmpdir (),
"ultra-bug-cwd-" ));
66 + const home
= fs.
mkdtempSync (path.
join (os.
tmpdir (),
"ultra-bug-home-" ));
68 + const bug
= discoverWorkflows (cwd, { home }).
find (
69 + (workflow)
=> workflow.
name === "bug" ,
71 + expect (bug?.
source ).
toBe (
"bundled" );
73 + fs.
rmSync (cwd, { recursive:
true , force:
true });
74 + fs.
rmSync (home, { recursive:
true , force:
true });
extensions/ultra/__tests__/engine.test.ts Modified 135 + describe (
"runWorkflow — phase when" , ()
=> {
138 + [[],
"empty array" ],
139 + [
"" ,
"empty string" ],
140 + ])(
"skips a phase when its selector resolves to %s (%s)" ,
async (enabled)
=> {
141 + const fr
= fakeRunner ((args)
=> ({ ok:
true , value: args.step.
prompt }));
143 + return:
"{after.results}" ,
148 + when:
"{args.enabled}" ,
149 + step: { prompt:
"must not run" },
154 + step: { prompt:
"saw {conditional.results}" },
159 + const res
= await runWorkflow (
162 + baseDeps ({ stepRunner: fr.runner }),
165 + expect (fr.calls.
map ((call)
=> call.phase)).
toEqual ([
"after" ]);
166 + expect (res.phases).
toEqual ([
167 + { id:
"conditional" , ran:
0 , ok:
0 , dropped:
0 },
168 + { id:
"after" , ran:
1 , ok:
1 , dropped:
0 },
170 + expect (res.phaseResults.conditional).
toEqual ([]);
171 + expect (res.result).
toEqual ([
"saw []" ]);
174 + it (
"runs a phase when its selector resolves to a non-empty value" ,
async ()
=> {
175 + const fr
= fakeRunner (()
=> ({ ok:
true , value:
"ran" }));
181 + when:
"{args.enabled}" ,
182 + step: { prompt:
"run" },
187 + const res
= await runWorkflow (
190 + baseDeps ({ stepRunner: fr.runner }),
193 + expect (fr.calls).
toHaveLength (
1 );
194 + expect (res.phases[
0 ]).
toEqual ({
extensions/ultra/__tests__/feature.test.ts Modified 6 6 import { resolveSelector }
from "../interp.ts" ;
7 7 import { discoverWorkflows, parseWorkflow }
from "../spec.ts" ;
12 11 const here
= path.
dirname (
fileURLToPath (
import .
meta .url));
13 12 const FEATURE_PATH
= path.
join (here,
".." ,
"workflows" ,
"feature.json" );
72 + it (
"implements only approved critiques and reviews only completed implementations" , ()
=> {
73 + const spec
= parseWorkflow (
loadRaw ());
74 + const implement
= spec.phases.
find ((p)
=> p.
id === "implement" );
75 + const review
= spec.phases.
find ((p)
=> p.
id === "review" );
77 + expect (implement?.when).
toBe (
"{critique.results | where approved}" );
78 + expect (review?.when).
toBe (
"{implement.results | where implemented}" );
79 + const implementation
= spec.schemas?.Implementation
as {
80 + required
?: string [];
82 + expect (implementation.required).
toContain (
"implemented" );
73 85 it (
"reviews across security + quality, each echoing its dimension as the join key" , ()
=> {
74 86 const spec
= parseWorkflow (
loadRaw ());
75 87 const review
= spec.phases.
find ((p)
=> p.
id === "review" );
extensions/ultra/__tests__/spec.test.ts Modified 87 87 expect (parsed.
name ).
toBe (
"review" );
90 + it (
"accepts optional phase `when` selectors" , ()
=> {
91 + const s
= validSpec ();
96 + when:
"{args.enabled}" ,
97 + step: { prompt:
"go" },
100 + expect (
parseWorkflow (s).phases[
0 ].when).
toBe (
"{args.enabled}" );
103 + it (
"rejects non-string phase `when` values" , ()
=> {
104 + const s
= validSpec ();
105 + s.phases[
0 ].when
= true ;
106 + expect (()
=> parseWorkflow (s)).
toThrow (
/when/ i );
90 109 it (
"accepts a single phase without `over`" , ()
=> {
91 110 const s
= validSpec ();
92 111 s.phases
= [{ id:
"only" , kind:
"single" , step: { prompt:
"go" } }];
extensions/ultra/engine.ts Modified 116 116 const forward
= makeForwarder (deps, steeredBox);
118 118 for (
const phase
of spec.phases) {
120 + phase.when
!== undefined && 121 + ! phaseEnabled (
resolveSelector (phase.when, { args, results }))
123 + results[phase.
id ]
= [];
124 + phaseResults[phase.
id ]
= [];
125 + phases.
push ({ id: phase.
id , ran:
0 , ok:
0 , dropped:
0 });
255 264 return JSON .
stringify ({ phase, index, item, step });
267 + function phaseEnabled (value
: unknown )
: boolean {
268 + if (value
=== false || value
=== null || value
=== undefined || value
=== "" )
270 + return ! Array .
isArray (value)
|| value.
length > 0 ;
260 275 function phaseItems (phase
: Phase , ctx
: InterpContext )
: unknown [] {
extensions/ultra/skills/authoring-workflows/SKILL.md Modified 46 46 - `single` (one synthesis/judge pass) vs. `fanout` (one agent per item).
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 + - Optional `when` uses one existing selector; empty/false skips the phase and produces empty results.
49 50 - The step `prompt`, its `tools`, and whether it needs structured output.
51 52 3. **Apply the read-only fan-out rule.** A `fanout` step with tools must stay
66 67 6. **Self-check the spec (there is no validator tool).** You can't call
67 68 `parseWorkflow` directly — verify by inspection against the reference: every
68 - required field is present, every `fanout` has an `over`, every string
69 + required field is present, every `fanout` has an `over`, every `when` is one selector, every string
69 70 `schema` names a key in `schemas`, and interpolation uses only the closed
70 71 grammar. The real validator is the load itself: saving and test-running
71 72 (steps 7–8) parses the file through the runtime's `parseWorkflow`, which
extensions/ultra/skills/authoring-workflows/references/spec-format.md Modified 27 27 A phase has an `id` (referenced by interpolation and `return`), a `kind`, a
28 - `step`, and an optional `concurrency` cap.
28 + `step`, an optional `concurrency` cap, and an optional `when` selector.
30 30 - **`single`** — runs the step exactly once, for one synthesis / judge /
31 31 aggregation pass over prior results. (`over` is accepted by the schema but
33 33 - **`fanout`** — runs the step once per element of `over`, concurrently (capped
34 34 by `concurrency` and the engine's global pool). `over` is **required**.
36 + `when` uses the existing single-selector grammar.
37 + If it resolves to `false`, `null`, `undefined`, an empty string, or an empty array, the phase is skipped and records `{ ran: 0, ok: 0, dropped: 0 }` with empty results.
38 + Any other value runs the phase.
39 + A skipped phase may still be referenced later through its empty `{PHASE.results}`.
40 + There are no loops or arbitrary expressions.
36 42 `over` is either a literal array or a single interpolation token string (e.g.
37 43 `"{review.results[].findings[]}"`).
extensions/ultra/spec.ts Modified 43 43 const SinglePhaseSchema
= Type.
Object ({
45 45 kind: Type.
Literal (
"single" ),
46 + when: Type.
Optional (Type.
String ()),
46 47 over: Type.
Optional (OverSchema),
48 49 concurrency: Type.
Optional (Type.
Number ()),
51 52 const FanoutPhaseSchema
= Type.
Object ({
53 54 kind: Type.
Literal (
"fanout" ),
55 + when: Type.
Optional (Type.
String ()),
56 58 concurrency: Type.
Optional (Type.
Number ()),
extensions/ultra/workflows/bug.json Added new file mode 100644 3 + "description" :
"Investigate a bug, prove it with a regression test, implement the fix, then verify adversarially." ,
4 + "args" : {
"hint" :
"<bug>" ,
"params" : [
"bug" ] },
9 + "summary" : {
"type" :
"string" },
10 + "reproduction" : {
"type" :
"string" },
11 + "likely_cause" : {
"type" :
"string" },
12 + "files" : {
"type" :
"array" ,
"items" : {
"type" :
"string" } }
14 + "required" : [
"summary" ,
"reproduction" ,
"likely_cause" ,
"files" ]
21 + "description" :
"true only when the regression test fails for the expected bug" 23 + "test_files" : {
"type" :
"array" ,
"items" : {
"type" :
"string" } },
24 + "command" : {
"type" :
"string" },
25 + "failure" : {
"type" :
"string" }
27 + "required" : [
"ready" ,
"test_files" ,
"command" ,
"failure" ]
34 + "description" :
"true only when the regression test and relevant checks pass" 36 + "summary" : {
"type" :
"string" },
37 + "modified_files" : {
"type" :
"array" ,
"items" : {
"type" :
"string" } },
38 + "checks" : {
"type" :
"array" ,
"items" : {
"type" :
"string" } }
40 + "required" : [
"fixed" ,
"summary" ,
"modified_files" ,
"checks" ]
45 + "dimension" : {
"type" :
"string" },
46 + "passed" : {
"type" :
"boolean" },
47 + "findings" : {
"type" :
"array" ,
"items" : {
"type" :
"string" } }
49 + "required" : [
"dimension" ,
"passed" ,
"findings" ]
54 + "id" :
"investigate" ,
57 + "prompt" :
"Investigate this bug without modifying files: {args.bug}. Reproduce or trace the failing path, inspect callers and shared routes, identify the likely root cause, and list relevant files. Use read/grep/find/bash as needed. Return JSON matching Investigation." ,
58 + "tools" : [
"read" ,
"grep" ,
"find" ,
"ls" ,
"bash" ],
59 + "schema" :
"Investigation" 66 + "prompt" :
"Create the smallest regression test for this bug: {args.bug}. Investigation: {investigate.results}. Do not fix production code. Run the focused test and set ready=true only when it fails for the expected reason, not from a test error. Return JSON matching Regression." ,
67 + "tools" : [
"read" ,
"grep" ,
"find" ,
"ls" ,
"bash" ,
"edit" ,
"write" ],
68 + "schema" :
"Regression" 74 + "when" :
"{regression.results | where ready}" ,
76 + "prompt" :
"Fix the root cause of this bug: {args.bug}. Investigation: {investigate.results}. Regression evidence: {regression.results}. Prefer the shared route over caller-specific patches. Make the minimum production change, run the regression test and relevant checks, and set fixed=true only when they pass. Then return JSON matching Fix." ,
77 + "tools" : [
"read" ,
"grep" ,
"find" ,
"ls" ,
"bash" ,
"edit" ,
"write" ],
84 + "when" :
"{fix.results | where fixed}" ,
85 + "over" : [
"regression" ,
"correctness" ,
"security" ],
87 + "prompt" :
"Adversarially verify the bug fix from the {item} perspective. Bug: {args.bug}. Investigation: {investigate.results}. Regression: {regression.results}. Fix: {fix.results}. Inspect the diff and run focused checks as needed; do not modify files. Set passed=false and list concrete findings if the fix is incomplete, the regression test is weak, or new risk was introduced. Echo dimension as {item}. Return JSON matching Verdict." ,
88 + "tools" : [
"read" ,
"grep" ,
"find" ,
"ls" ,
"bash" ],
93 + "return" :
"{verify.results}" extensions/ultra/workflows/feature.json Modified 58 58 "Implementation" : {
63 + "description" :
"true only when the feature changes and focused checks completed" 63 67 "description" :
"What was changed and why" 69 73 "description" :
"Plan tasks actually completed" 72 - "required" : [
"summary" ,
"modified_files" ]
76 + "required" : [
"implemented" ,
"summary" ,
"modified_files" ]
120 124 "id" :
"implement" ,
121 125 "kind" :
"single" ,
126 + "when" :
"{critique.results | where approved}" ,
123 - "prompt" :
"Implement the feature: {args.task}. Follow the plan and resolve EVERY blocking item from the critique. Plan: {plan.results}. Critique: {critique.results}. Make the actual edits with the edit/write tools, keep the change focused, and follow the conventions surfaced in research. Then return JSON matching the Implementation schema (list the files you changed and a concise summary)." ,
128 + "prompt" :
"Implement the feature: {args.task}. Follow the plan and resolve EVERY blocking item from the critique. Plan: {plan.results}. Critique: {critique.results}. Make the actual edits with the edit/write tools, keep the change focused, and follow the conventions surfaced in research. Run focused checks and set implemented=true only when the changes and checks complete. Then return JSON matching the Implementation schema (list the files you changed and a concise summary)." ,
124 129 "tools" : [
"read" ,
"grep" ,
"find" ,
"ls" ,
"bash" ,
"edit" ,
"write" ],
125 130 "schema" :
"Implementation" 130 135 "kind" :
"fanout" ,
136 + "when" :
"{implement.results | where implemented}" ,
131 137 "over" : [
"security" ,
"quality" ],
133 139 "prompt" :
"Review the just-made implementation of {args.task} from the {item} perspective. What changed: {implement.results}. Inspect the working tree with read/grep and `git diff`; do not modify anything. Set passed=false and list each blocking {item} problem you find. Echo the `dimension` field as \"{item}\" so the verdict ties back. Return JSON matching the Verdict schema." ,