repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs(ultra): discourage pointless single-agent runs

92233cf0cf69cf83416a78b2afe39b7aaf748dad

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (4)

extensions/ultra/README.md

Modified
18 18 ## Workflows
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";
2 3 import {
3 4 createTestSession,
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",
29 + );
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",
238 238 description:
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).
32 +## Single-agent gate
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