pi-ext bugabingas pi extensions
owned by bugabinga
README Source History Refs Compare Notes Search docs(ultra): discourage pointless single-agent runs
92233cf0cf69cf83416a78b2afe39b7aaf748dad
Oliver Jan Krylow <oliver@bugabinga.net > · 12 Jul 2026
unsigned
Browse files Compare with HEAD
Changed files (4) extensions/ultra/README.md Modified 20 + Use ultra for fan-out, multi-phase orchestration, or a single agent that specifically needs isolation, background execution, an alternate model, resumability, or strict structured output.
21 + For an ordinary one-agent task, perform the task directly instead of wrapping it in ultra.
20 23 A workflow is a single JSON object — phases (`single` / `fanout`), per-step
21 24 prompts/tools/schemas, and a closed interpolation grammar that pipes one phase's
22 25 results into the next. The authoritative format reference is
extensions/ultra/__tests__/harness.test.ts Modified 1 + import { readFileSync }
from "node:fs" ;
1 2 import { fileURLToPath }
from "node:url" ;
23 24 const [extension]
= t.session.extensionRunner.extensions;
24 25 expect (extension.path).
toBe (indexPath);
25 26 expect (extension.tools.
has (
"workflow" )).
toBe (
true );
27 + expect (
readFileSync (indexPath,
"utf8" )).
toContain (
28 + "Do not use it for an ordinary single-agent task" ,
26 30 expect (extension.commands.
has (
"ultra" )).
toBe (
true );
27 31 expect (extension.commands.
has (
"ultra-runs" )).
toBe (
true );
extensions/ultra/index.ts Modified 237 237 label :
"workflow" ,
239 239 "Run a declarative ultra multi-agent workflow: fan out sub-agents across phases under a " + 240 - "concurrency cap and return aggregated JSON. Pass either a saved workflow `name` " + 240 + "concurrency cap and return aggregated JSON. Do not use it for an ordinary single-agent task; " + 241 + "use one agent only when isolation, background execution, an alternate model, resumability, or " + 242 + "strict structured output is specifically needed. Pass either a saved workflow `name` " + 241 243 "(+ optional `args`), or an inline `spec` object for a one-off run." ,
242 244 parameters : Type.
Object ({
243 245 name: Type.
Optional (
extensions/ultra/skills/authoring-workflows/SKILL.md Modified 29 29 can be deleted. When in genuine doubt with creation language, persist (the
30 30 reversible, lower-regret default).
34 + Do not create or invoke ultra for an ordinary task that one agent can perform directly.
35 + A workflow with one agent is justified only when it specifically needs context isolation, background execution, an alternate model, resumability, strict structured output, or future reuse as orchestration.
36 + Otherwise perform the task directly and skip ultra's orchestration overhead.
32 38 ##
Authoring flow (persisted) 34 40 1. **Understand the goal.** What does each stage do, and what flows between