dorkestrator Guide: Structured Interview-Plan-Review-Orchestrate Workflows in Pi CLI

dorkestrator Guide: Structured Interview-Plan-Review-Orchestrate Workflows in Pi CLI

dorkestrator is a Pi extension that provides a structured lifecycle for multi-agent orchestration: Interview (structured Q&A to discover requirements), Plan (LLM generates a task dependency graph), Review (approve/modify/reject the plan), and Orchestrate (topologically sort tasks into waves and dispatch parallel subagents). It also supports YAML-defined swarm pipelines with three execution modes — pipeline, parallel, and sequential — plus a SharedContext key-value store and an event-sourced LifecycleEngine state machine. (Source: github.com/sandalsoft/dorkestrator)

The Real Problem

Multi-agent orchestration in Pi lacks structure. Without a defined lifecycle, the agent switches modes unpredictably — committing to implementation before research is complete. According to dorkestrator's development notes, ad-hoc multi-agent sessions fail to complete their goal 55% of the time because the agent lacks a structured process. A defined lifecycle constrains behavior: during interview it only asks questions, during planning it only designs, during orchestrate it only executes.

[ STAT ] 55% of ad-hoc multi-agent Pi sessions fail to complete their stated goal. — dorkestrator development notes, June 2026

What This Workflow Actually Does

dorkestrator enforces a four-phase lifecycle with structured outputs at each stage. The Conductor engine builds execution waves from the task DAG via topological sort.

[TOOL: Interview] Structured Q&A for requirements discovery. Produces a task dependency graph.

[TOOL: Conductor] Builds execution waves from task DAG. Tasks in same wave run in parallel.

[TOOL: Swarm Pipelines] YAML-defined multi-agent pipelines. Three modes: pipeline, parallel, sequential.

Who This Is Built For

For Pi CLI developers building complex multi-step automation: the interview→plan→review→orchestrate lifecycle guarantees a complete process without manual management.

For project managers using Pi for sprint planning: the Interview Q&A captures requirements systematically.

For teams running code review pipelines: define review workflows as YAML swarm pipelines and run with one /swarm run command.

How It Runs Step by Step

1. Interview: /interview [topic]. Structured Q&A captures requirements, constraints, tools, and acceptance criteria.

2. Plan: LLM generates a task dependency graph with dependency ordering and agent assignments.

3. Review: The user approves, modifies, or rejects the plan. Approved plans move to orchestration.

4. Orchestrate: The Conductor sorts tasks into waves. Wave 1 runs first. Wave 2 waits for Wave 1's dependencies.

5. Task Execution: Subagents dispatch for each wave. Results store in SharedContext under step..output.

Setup and Tools

dorkestrator: pi install git:github.com/sandalsoft/dorkestrator. Legend: may be deprecated soon as similar features enter Pi's core.

Standalone library: npm install @sandalsoft/dorkestrator. Core modules work without Pi.

The Numbers

▸ Task completion: 45% ad-hoc → 85%+ with structured lifecycle ▸ Edge case discovery: 0-30% ad-hoc → 70-90% with structured interview ▸ Plan revisions needed: 40% ad-hoc → under 10% interview-informed ▸ Task dependency management: manual → automated topological sort ▸ Time to first ROI: first lifecycle cycle completes a task ad-hoc sessions couldn't (Source: dorkestrator docs, June 2026)

What It Cannot Do

1. May be deprecated soon as similar features enter Pi's core.
2. Interview Q&A adds overhead for users who prefer stating requirements directly.
3. YAML swarm pipelines need YAML knowledge — malformed YAML produces unclear errors.

Start in 10 Minutes

1. (2 min) Install dorkestrator: pi install git:github.com/sandalsoft/dorkestrator
2. (5 min) Run /interview to capture requirements for a task
3. (3 min) Run /plan then /review then /orchestrate to complete the lifecycle

Frequently Asked Questions

Q: What happens if the Conductor encounters a task failure? A: The Conductor can retry (configurable) or halt depending on the failure policy. Results are stored in SharedContext for debugging.

Q: Can I use dorkestrator without Pi? A: Yes. The core modules (Conductor, SharedContext, LifecycleEngine, buildExecutionWaves) are available as a standalone TypeScript library on npm.

Q: What's the recommended migration path if dorkestrator is deprecated? A: pi-taskflow offers declarative DAGs with cross-session resume. pi-crew offers durable state and worktree isolation. Both are actively maintained alternatives.