repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

feat(ultra): add conditional workflow phases

72fc24ffaf5387b3611d4e7f360388b70dc8025b

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare 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.
57 62 ## Results

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([
22 + "investigate",
23 + "regression",
24 + "fix",
25 + "verify",
26 + ]);
27 + });
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");
40 + });
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"]),
49 + );
50 + }
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);
57 + }
58 + });
60 + it("contains no loop construct", () => {
61 + expect(loadRaw()).not.toMatch(/"loop"|"repeat"/);
62 + });
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-"));
67 + try {
68 + const bug = discoverWorkflows(cwd, { home }).find(
69 + (workflow) => workflow.name === "bug",
70 + );
71 + expect(bug?.source).toBe("bundled");
72 + } finally {
73 + fs.rmSync(cwd, { recursive: true, force: true });
74 + fs.rmSync(home, { recursive: true, force: true });
75 + }
76 + });
77 +});

extensions/ultra/__tests__/engine.test.ts

Modified
131 +// ---------------------------------------------------------------------------
132 +// conditional phase skipping
133 +// ---------------------------------------------------------------------------
135 +describe("runWorkflow — phase when", () => {
136 + it.each([
137 + [false, "false"],
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 }));
142 + const s = spec({
143 + return: "{after.results}",
144 + phases: [
146 + id: "conditional",
147 + kind: "single",
148 + when: "{args.enabled}",
149 + step: { prompt: "must not run" },
150 + } as Phase,
152 + id: "after",
153 + kind: "single",
154 + step: { prompt: "saw {conditional.results}" },
155 + },
156 + ],
157 + });
159 + const res = await runWorkflow(
160 + s,
161 + { enabled },
162 + baseDeps({ stepRunner: fr.runner }),
163 + );
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 },
169 + ]);
170 + expect(res.phaseResults.conditional).toEqual([]);
171 + expect(res.result).toEqual(["saw []"]);
172 + });
174 + it("runs a phase when its selector resolves to a non-empty value", async () => {
175 + const fr = fakeRunner(() => ({ ok: true, value: "ran" }));
176 + const s = spec({
177 + phases: [
179 + id: "conditional",
180 + kind: "single",
181 + when: "{args.enabled}",
182 + step: { prompt: "run" },
183 + } as Phase,
184 + ],
185 + });
187 + const res = await runWorkflow(
188 + s,
189 + { enabled: true },
190 + baseDeps({ stepRunner: fr.runner }),
191 + );
193 + expect(fr.calls).toHaveLength(1);
194 + expect(res.phases[0]).toEqual({
195 + id: "conditional",
196 + ran: 1,
197 + ok: 1,
198 + dropped: 0,
199 + });
200 + });
201 +});
131 203 // ---------------------------------------------------------------------------
132 204 // interpolation — engine owns it; runner gets the resolved prompt verbatim
133 205 // ---------------------------------------------------------------------------

extensions/ultra/__tests__/feature.test.ts

Modified
6 6 import { resolveSelector } from "../interp.ts";
7 7 import { discoverWorkflows, parseWorkflow } from "../spec.ts";
9 -// The shipped `feature` workflow — a linearized feature pipeline
10 -// for ultra (which has no gate/loop/conditional): research → plan → critique →
11 -// implement → review. It lives beside the bundled-workflows lookup.
9 +// The shipped `feature` workflow: research → plan → critique → conditional
10 +// implement → conditional review. It lives beside the bundled-workflows lookup.
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[];
81 + };
82 + expect(implementation.required).toContain("implemented");
83 + });
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();
92 + s.phases = [
93 + {
94 + id: "only",
95 + kind: "single",
96 + when: "{args.enabled}",
97 + step: { prompt: "go" },
98 + },
99 + ];
100 + expect(parseWorkflow(s).phases[0].when).toBe("{args.enabled}");
101 + });
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);
107 + });
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) {
119 + if (
120 + phase.when !== undefined &&
121 + !phaseEnabled(resolveSelector(phase.when, { args, results }))
122 + ) {
123 + results[phase.id] = [];
124 + phaseResults[phase.id] = [];
125 + phases.push({ id: phase.id, ran: 0, ok: 0, dropped: 0 });
126 + continue;
119 128 // Resolve `over` and every prompt up-front. Both own the interpolation
120 129 // grammar; a bad token throws here (spec authoring error), before any step
121 130 // launches — it is deliberately not a runtime drop.
255 264 return JSON.stringify({ phase, index, item, step });
267 +function phaseEnabled(value: unknown): boolean {
268 + if (value === false || value === null || value === undefined || value === "")
269 + return false;
270 + return !Array.isArray(value) || value.length > 0;
258 273 /** The fanout/single item list. `single` runs its step exactly once (any `over`
259 274 * is ignored in v1); `fanout` resolves `over` to its element array. */
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
25 25 ## Phases
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({
44 44 id: Type.String(),
45 45 kind: Type.Literal("single"),
46 + when: Type.Optional(Type.String()),
46 47 over: Type.Optional(OverSchema),
47 48 step: StepSchema,
48 49 concurrency: Type.Optional(Type.Number()),
51 52 const FanoutPhaseSchema = Type.Object({
52 53 id: Type.String(),
53 54 kind: Type.Literal("fanout"),
55 + when: Type.Optional(Type.String()),
54 56 over: OverSchema,
55 57 step: StepSchema,
56 58 concurrency: Type.Optional(Type.Number()),

extensions/ultra/workflows/bug.json

Added
new file mode 100644
1 +{
2 + "name": "bug",
3 + "description": "Investigate a bug, prove it with a regression test, implement the fix, then verify adversarially.",
4 + "args": { "hint": "<bug>", "params": ["bug"] },
5 + "schemas": {
6 + "Investigation": {
7 + "type": "object",
8 + "properties": {
9 + "summary": { "type": "string" },
10 + "reproduction": { "type": "string" },
11 + "likely_cause": { "type": "string" },
12 + "files": { "type": "array", "items": { "type": "string" } }
13 + },
14 + "required": ["summary", "reproduction", "likely_cause", "files"]
15 + },
16 + "Regression": {
17 + "type": "object",
18 + "properties": {
19 + "ready": {
20 + "type": "boolean",
21 + "description": "true only when the regression test fails for the expected bug"
22 + },
23 + "test_files": { "type": "array", "items": { "type": "string" } },
24 + "command": { "type": "string" },
25 + "failure": { "type": "string" }
26 + },
27 + "required": ["ready", "test_files", "command", "failure"]
28 + },
29 + "Fix": {
30 + "type": "object",
31 + "properties": {
32 + "fixed": {
33 + "type": "boolean",
34 + "description": "true only when the regression test and relevant checks pass"
35 + },
36 + "summary": { "type": "string" },
37 + "modified_files": { "type": "array", "items": { "type": "string" } },
38 + "checks": { "type": "array", "items": { "type": "string" } }
39 + },
40 + "required": ["fixed", "summary", "modified_files", "checks"]
41 + },
42 + "Verdict": {
43 + "type": "object",
44 + "properties": {
45 + "dimension": { "type": "string" },
46 + "passed": { "type": "boolean" },
47 + "findings": { "type": "array", "items": { "type": "string" } }
48 + },
49 + "required": ["dimension", "passed", "findings"]
50 + }
51 + },
52 + "phases": [
53 + {
54 + "id": "investigate",
55 + "kind": "single",
56 + "step": {
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"
60 + }
61 + },
62 + {
63 + "id": "regression",
64 + "kind": "single",
65 + "step": {
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"
69 + }
70 + },
71 + {
72 + "id": "fix",
73 + "kind": "single",
74 + "when": "{regression.results | where ready}",
75 + "step": {
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"],
78 + "schema": "Fix"
79 + }
80 + },
81 + {
82 + "id": "verify",
83 + "kind": "fanout",
84 + "when": "{fix.results | where fixed}",
85 + "over": ["regression", "correctness", "security"],
86 + "step": {
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"],
89 + "schema": "Verdict"
90 + }
91 + }
92 + ],
93 + "return": "{verify.results}"

extensions/ultra/workflows/feature.json

Modified
58 58 "Implementation": {
59 59 "type": "object",
60 60 "properties": {
61 + "implemented": {
62 + "type": "boolean",
63 + "description": "true only when the feature changes and focused checks completed"
64 + },
61 65 "summary": {
62 66 "type": "string",
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"]
74 78 "Verdict": {
75 79 "type": "object",
120 124 "id": "implement",
121 125 "kind": "single",
126 + "when": "{critique.results | where approved}",
122 127 "step": {
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"
129 134 "id": "review",
130 135 "kind": "fanout",
136 + "when": "{implement.results | where implemented}",
131 137 "over": ["security", "quality"],
132 138 "step": {
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.",