pi-extensible-workflows 0.3.0

package/evals/cases/custom-model-read.yaml

@@ -0,0 +1,15 @@
+id: custom-model-read
+prompt: "Have one subagent using the model $EVAL_MODEL read README.md with a minimal toolset and report in one sentence what this package does."
+maxCost: 0.1
+expectations:
+  workflowCallCount:
+    min: 1
+  agentPolicies:
+    - callIndex: 0
+      model: "$EVAL_MODEL"
+      tools:
+        mode: exact
+        values: [read]
+semanticCriteria:
+  - id: intent
+    description: "The script configures one agent with the requested model and only the read tool, instructs it to inspect README.md, and returns its one-sentence package description."

package/evals/cases/direct-answer.yaml

@@ -0,0 +1,6 @@
+id: direct-answer
+prompt: "How many lines are in README.md?"
+maxCost: 0.1
+expectations:
+  workflowCallCount: 0
+expectedWorkflowCalls: 0

package/evals/cases/mixed-parallel-pipeline.yaml

@@ -0,0 +1,18 @@
+id: mixed-parallel-pipeline
+prompt: "Gather API and UI evidence independently at the same time, then process each gathered result through the same ordered analysis and summary stages."
+maxCost: 0.1
+expectations:
+  workflowCallCount:
+    min: 1
+  requiredOperations: [parallel, pipeline]
+  minimumAgentCalls: 2
+  requiredAgentStructures:
+    - execution: parallel
+      operation: parallel
+      agents: [{}, {}]
+    - execution: sequential
+      operation: pipeline
+      agents: [{}, {}]
+semanticCriteria:
+  - id: intent
+    description: "The script gathers API and UI evidence in parallel, then passes each result through ordered analysis and summary stages."

package/evals/cases/output-schema.yaml

@@ -0,0 +1,22 @@
+id: output-schema
+prompt: "Use one scout subagent for a structured report containing a numeric count and a text summary."
+maxCost: 0.1
+expectations:
+  workflowCallCount:
+    min: 1
+  requiredRoles: [scout]
+  agentPolicies:
+    - callIndex: 0
+      role: scout
+      forbidOptions: [model, thinking, tools]
+  requireOutputSchema:
+    type: object
+    requiredKeys: [count, summary]
+    propertyTypes:
+      count: number
+      summary: string
+    forbiddenProperties: [extra]
+    count: 1
+semanticCriteria:
+  - id: intent
+    description: "The script configures one scout agent with an output schema requiring a numeric count and text summary."

package/evals/cases/parallel.yaml

@@ -0,0 +1,15 @@
+id: parallel
+prompt: "Run the independent API and UI checks at the same time, then report both outcomes together."
+maxCost: 0.1
+expectations:
+  workflowCallCount:
+    min: 1
+  requiredOperations: [parallel]
+  minimumAgentCalls: 2
+  requiredAgentStructures:
+    - execution: parallel
+      operation: parallel
+      agents: [{}, {}]
+semanticCriteria:
+  - id: intent
+    description: "Independent API and UI checks run in parallel and both outcomes are combined."

package/evals/cases/pipeline.yaml

@@ -0,0 +1,10 @@
+id: pipeline
+prompt: "Process the API and UI artifacts through the same ordered normalization and finalization stages, preserving each item's result."
+maxCost: 0.1
+expectations:
+  workflowCallCount:
+    min: 1
+  requiredOperations: [pipeline]
+semanticCriteria:
+  - id: intent
+    description: "API and UI items pass through the same ordered normalization and finalization stages."

package/evals/cases/ready-for-agent-parallel-merge.yaml

@@ -0,0 +1,32 @@
+id: ready-for-agent-parallel-merge
+prompt: "Fix every ready-for-agent issue. GitHub access is unavailable, so read the two issue descriptions in test/fixtures/ready-for-agent-tasks.md. Do the issues in parallel, each in its own named withWorktree scope. After all work is done, merge their branches into main and leave main clean."
+maxCost: 10
+expectations:
+  workflowCallCount:
+    min: 1
+  requiredOperations: [withWorktree]
+  minimumAgentCalls: 3
+  requiredRoles: [developer]
+  agentPolicies:
+    - callIndex: 0
+      role: developer
+    - callIndex: 1
+      role: developer
+    - callIndex: 2
+      role: developer
+  requiredAgentOrder:
+    - role: developer
+      execution: parallel
+    - role: developer
+      execution: parallel
+    - role: developer
+      execution: sequential
+  requiredAgentStructures:
+    - execution: parallel
+      operation: parallel
+      agents:
+        - role: developer
+        - role: developer
+semanticCriteria:
+  - id: intent
+    description: "Two developer agents fix the local issue tasks concurrently in separate named withWorktree scopes, then a final developer agent receives both results, merges both branches into main, verifies the merged work, and leaves main clean."

package/evals/cases/required-role.yaml

@@ -0,0 +1,14 @@
+id: required-role
+prompt: "Have a reviewer assess the change and return a short review."
+maxCost: 0.1
+expectations:
+  workflowCallCount:
+    min: 1
+  requiredRoles: [reviewer]
+  agentPolicies:
+    - callIndex: 0
+      role: reviewer
+      forbidOptions: [model, thinking, tools]
+semanticCriteria:
+  - id: intent
+    description: "A reviewer-role agent assesses the change and its result is returned."

package/evals/cases/role-model-mixed.yaml

@@ -0,0 +1,18 @@
+id: role-model-mixed
+prompt: "Obtain a reviewer-role assessment first, then use a separate subagent with the explicit model $EVAL_MODEL and no tools to synthesize the final text."
+maxCost: 0.1
+expectations:
+  workflowCallCount:
+    min: 1
+  minimumAgentCalls: 2
+  agentPolicies:
+    - callIndex: 0
+      role: reviewer
+      forbidOptions: [model, thinking, tools]
+    - callIndex: 1
+      model: "$EVAL_MODEL"
+      tools:
+        mode: empty
+semanticCriteria:
+  - id: intent
+    description: "The reviewer assessment is produced first and passed to a separate no-tools synthesis agent."

package/evals/cases/two-agents.yaml

@@ -0,0 +1,10 @@
+id: two-agents
+prompt: "Investigate this repository from two independent angles: inspect the API surface and inspect the user-facing behavior. Combine both findings into one concise plain-text comparison."
+maxCost: 0.1
+expectations:
+  workflowCallCount:
+    min: 1
+  minimumAgentCalls: 2
+semanticCriteria:
+  - id: intent
+    description: "The workflow independently inspects API and user-facing behavior, then combines both findings into one concise comparison."

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "pi-extensible-workflows",
+  "version": "0.3.0",
+  "description": "Deterministic multi-agent workflow orchestration for Pi",
+  "homepage": "https://vekexasia.github.io/pi-extensible-workflows/",
+  "repository": { "type": "git", "url": "git+https://github.com/vekexasia/pi-extensible-workflows.git" },
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "workflow",
+    "multi-agent",
+    "orchestration",
+    "automation"
+  ],
+  "exports": "./dist/src/index.js",
+  "bin": {
+    "pi-extensible-workflows": "./dist/src/cli.js"
+  },
+  "files": [
+    "dist/src",
+    "src",
+    "skills",
+    "evals",
+    "test/fixtures"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/src/cli.js",
+    "inspect": "node dist/src/cli.js inspect",
+    "lint": "eslint .",
+    "test": "npm run build && node --test 'dist/test/*.test.js'",
+    "acceptance": "npm run build && node --test dist/test/runtime-acceptance.test.js",
+    "docs:check": "node scripts/check-docs.mjs",
+    "check": "npm run lint && npm test && npm run docs:check",
+    "evals": "npm run build && node dist/src/workflow-evals.js",
+    "evals:ambient": "node -e \"if (process.env.PI_WORKFLOW_EVAL_AMBIENT !== '1') { console.error('Ambient Tier D evals are opt-in. Set PI_WORKFLOW_EVAL_AMBIENT=1 to run them.'); process.exit(1); }\" && npm run build && node dist/src/ambient-workflow-evals.js",
+    "prepack": "npm run build"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.80.9",
+    "@earendil-works/pi-coding-agent": "0.80.9",
+    "@eslint/js": "10.0.1",
+    "@types/node": "24.12.4",
+    "eslint": "10.0.3",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.63.0"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "acorn": "^8.17.0"
+  }
+}

package/skills/pi-extensible-workflows/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: pi-extensible-workflows
+description: Use when the task is complex enough to require multiple subagents or when the user explicitly asks for a workflow.
+---
+
+# pi-extensible-workflows
+
+Use `workflow` exclusively for genuinely multi-agent orchestration. For one agent, use ordinary tools or `Agent` directly. Do not wrap a single agent in a workflow; define distinct responsibilities and keep the result flow explicit.
+
+## Pattern
+
+```js
+const reportSchema = {
+  type: "object",
+  properties: {
+    summary: { type: "string" },
+    findings: { type: "array", items: { type: "string" } },
+  },
+  required: ["summary", "findings"],
+  additionalProperties: false,
+};
+
+const reports = await parallel("research", {
+  first: () => agent("Research the first target.", { role: "scout", outputSchema: reportSchema }),
+  second: () => agent("Research the second target.", { role: "scout", outputSchema: reportSchema }),
+});
+
+// Add a downstream agent only when synthesis or independent review is a real phase.
+return agent(
+  prompt("Review these reports:\n\n{reports}", { reports }),
+  { role: "reviewer", outputSchema: reportSchema },
+);
+```
+
+To pass structured input from the main agent, include `args`:
+```json
+{ "workflow": "namespace.workflowName", "args": { "issue": 42 } }
+```
+Inside the workflow, read `args.issue`; omitted `args` is `null`.
+If `workflow_catalog` is available, call it once before creating the first workflow for a task. Use the returned global functions, variables, and registered workflows as needed for the rest of that task. Do not try to reinvent already exposed functions.
+
+Pass downstream only needed results. Workflow JavaScript has no imports, filesystem, network, process, or timers; delegate such work to agents with the required tools.
+
+## `agent()` options
+
+```typescript
+interface AgentOptions {
+  label?: string; // optional non-empty display name
+  model?: `${provider}/${model}` | `${provider}/${model}:${thinking}`;
+  thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+  role?: string; // one of the available workflow roles
+  tools?: string[]; // [] = no tools; omitted uses role or launch tools
+  outputSchema?: JsonSchema;
+  retries?: number; // non-negative; use for safe, repeatable work
+  timeoutMs?: number | null; // positive milliseconds; null means unlimited
+}
+```
+
+Agent calls are unnamed. Direct `agent(...)` calls receive hidden source call-site identity; aliases are unsupported. Calls from one source call site must not race outside `parallel` or `pipeline`, whose structural keys keep replay deterministic.
+
+## Shared worktree scope
+
+Use `withWorktree(callback)` or `withWorktree(name, callback)` when top-level agents should collaborate in one worktree:
+
+```js
+const results = await withWorktree("implementation", async () => parallel("implementation", {
+  api: () => agent("Implement the API"),
+  tests: () => agent("Add integration tests"),
+}));
+```
+
+The callback result is returned unchanged and the worktree is created only when the first enclosed agent launches. Concurrent agents share mutable files, so give them non-conflicting work or coordinate explicitly.
+
+`parallel()` tasks may call any workflow function, not only `agent()`:
+
+```js
+const results = await parallel("checks", {
+  security: () => reviewRepository({ focus: "security" }),
+  release: () => reviewRepository({ focus: "release readiness" }),
+});
+```
+
+Use separate named scopes when each parallel branch needs its own worktree:
+
+```js
+const results = await parallel("implementation", {
+  api: () => withWorktree("api", () => agent("Implement the API")),
+  ui: () => withWorktree("ui", () => agent("Implement the UI")),
+});
+```
+
+Registered extension functions receive `withWorktree` in their context, so they may create a shared scope internally. Their public inputs and outputs must remain JSON; callbacks cannot cross the extension-function boundary.
+
+## Rules
+
+- Do not create a workflow for one agent. Phases must have distinct work.
+- Use `log(messageString)` in the script to surface brief status messages to the operator.
+- A role owns its execution policy. When `role` is present, do not also set `model`, `thinking`, or `tools`; only task-specific options such as `outputSchema`, retries, timeout, or a `withWorktree` scope may accompany it.
+- Use `parallel()` for independent tasks with different flows. Use `pipeline()` when each keyed item passes through the same ordered stages; do not duplicate identical stage chains inside `parallel()` branches.
+- Call shapes are `parallel(operationName, tasksRecord)` and `pipeline(operationName, itemsRecord, stagesRecord)`; object keys are stable task, item, and stage names.
+- Preserve item metadata in workflow code between pipeline stages instead of requiring agents to echo it through `outputSchema`.
+- Repeated work uses a JavaScript loop; each direct `agent(...)` call receives deterministic call-site and occurrence identity.
+- Runs default to background; set tool-call `foreground: true` when asked to wait.
+- Omit `maxAgentLaunches` unless an explicit total launch budget is required.
+- `parallel()` and `pipeline()` return keyed bare values. Await results before use.
+- Interpolate results with `prompt("...{value}", { value })`; placeholders in plain strings stay literal.
+- Use `outputSchema` only when another phase must compare, aggregate, or validate the result. Never add it to a final agent whose prose is returned directly. Keep only fields the consumer needs, and avoid repeating the same evidence in multiple schemas.
+- With `outputSchema`, agents must call `workflow_result`; one repair prompt is built in. Omit `retries` unless an additional retry is justified and the work is idempotent.
+- Do not add "persona" specs to the prompt for agents. Just define the task.