@parke.dev/pi-workflows

Multi-phase multi-agent orchestration for the pi coding agent. You write a short JavaScript program; the package runs it in a locked-down sandbox and fans each agent() call out to an isolated child via @parke.dev/pi-subagent (@parke.dev/pi-subagent/sdk).

	What it does
workflow	start/status/wait/cancel/resume/rerun/list orchestration runs
/workflows	overlay of live runs; save / saved / cancel subcommands
/workflow	run a saved workflow by name
/ultracode	session policy: on / off / status (+ interactive ultracode keyword)

Ships with a workflows skill. Active and ready run counts are also exposed through Pi's extension-status API for custom footers such as @parke.dev/pi-dashboard; /workflows remains the detailed inspector.

Install

pi install npm:@parke.dev/pi-workflows
pi install npm:@parke.dev/pi-subagent

Requires a Node build that supports permission mode (>=22.19.0). The sandbox refuses to run without --permission.

When NOT to use this

If you already know the task list, use the subagent tool's tasks array. Reach for workflow only when control flow depends on results you do not have yet (map-reduce, escalate-on-failure, review→fix→re-review, consensus).

Sandbox API

The script parameter is a function body, not a module. Top-level await works. No imports, no require, no fs, no network.

phase(title)
await agent(prompt, options?)
await parallel([() => agent(...)])
await pipeline(items, item => agent(...))   // map a discovered collection
args                                         // structured invocation data
return value                                 // JSON-serializable tool result

agent() never throws — branch on ok. Every call must be awaited. parallel() / pipeline() share the concurrency cap.

Agent options

{
  label?, phase?, model?, thinking?, profile?, schema?,
  isolation?: "workflow" | "worktree",  // default workflow = shared lane
  maxTurns?, maxCost?, timeoutMs?, fallbackModels?
}

Per-call budgets are clamped to trusted config ceilings.

Shared worktree lane

Iterative writer / reviewer / test agents share one workflow-owned worktree. Writes on that lane are serialized; readers wait while a writer is active so re-review sees the fix. Pass isolation: "worktree" for a genuinely independent writer branch (orchestrator-managed).

Background runs, journal, resume

Launches are background by default (workflow.backgroundByDefault, overridable with async: false). The tool returns a run id immediately; completion is delivered as a follow-up message. Actions: status, wait, cancel, resume, rerun, list.

Each run writes an append-only journal under <agentDir>/workflows/runs/<runId>/. Resume restarts the script and replays the contiguous completed prefix of agent() calls (matched by request id + hash of prompt/options). Source, args, and cwd must still match.

Session custom entries (workflow-run-v1) hold lightweight summaries; full outputs stay in the artifact directory.

Approval

There is no model-controlled approved flag. Interactive TUI confirms launches; without UI the gate fails closed unless:

• workflow.approval is "never" in trusted config, or
• a saved workflow sets defaults.preApproved: true.

Saved workflows

Name-based resolution only (never arbitrary paths):

~/.pi/agent/workflows/definitions/<name>.workflow.json
.pi/workflows/<name>.workflow.json          # project, requires trust

{
  "version": 1,
  "name": "audit-routes",
  "description": "Audit route handlers",
  "script": "phase(\"discover\");\n...",
  "defaults": { "size": "medium", "preApproved": false }
}

Invoke with { "name": "audit-routes", "args": { ... } } or /workflow audit-routes.

Ultracode

Thin policy layer — not a new model:

• Interactive keyword: prefix a prompt with ultracode (interactive source only).
• /ultracode on|off|status and /ultracode size <small|medium|large|unrestricted>.
• Session on → thinking xhigh (restored on off); before_agent_start injects orchestration guidance and size guidelines.
• Large-run warnings when the script appears to exceed largeRunWarnAgents.

Configuration

Precedence: defaults ← config file ← environment.

Field	Env	Default	Meaning
defaultModel	PI_WORKFLOW_MODEL	unset	inherit parent session model
defaultThinking	PI_WORKFLOW_THINKING	medium
defaultProfile	PI_WORKFLOW_PROFILE	explore
agentMaxTurns	PI_WORKFLOW_AGENT_MAX_TURNS	20
agentMaxCost	PI_WORKFLOW_AGENT_MAX_COST	0.5
agentTimeoutMs	PI_WORKFLOW_AGENT_TIMEOUT_MS	600000
workflowTimeoutMs	PI_WORKFLOW_TIMEOUT_MS	2700000
maxAgentRequests	PI_WORKFLOW_MAX_AGENTS	32 (≤200)	hard cap
maxConcurrency	PI_WORKFLOW_MAX_CONCURRENCY	4 (≤16)	hard cap
approval	PI_WORKFLOW_APPROVAL	auto	auto / always / never
backgroundByDefault	PI_WORKFLOW_BACKGROUND	true
defaultSize	PI_WORKFLOW_SIZE	medium	ultracode guideline
largeRunWarnAgents	PI_WORKFLOW_LARGE_WARN	15	advisory warning threshold

Example

phase("discover");
const found = await agent("List hook files under src/", {
  label: "discover",
  schema: {
    type: "object",
    required: ["paths"],
    properties: { paths: { type: "array", items: { type: "string" } } },
  },
});
if (!found.ok) return { error: found.error };

const paths = (found.structured?.paths ?? []).slice(0, 20);
phase("audit");
const audits = await pipeline(paths, (p) => agent(`Audit ${p}`, { label: `audit ${p}`, profile: "review" }));

return {
  audited: paths.length,
  failed: audits.filter((a) => !a.ok).length,
  summary: audits.filter((a) => a.ok).map((a) => a.output),
};

License

MIT