dorkestrator: Structured Discovery-to-Execution Agent Orchestration

dorkestrator is a Pi extension by sandalsoft that provides a structured lifecycle for multi-agent workflow orchestration: Interview → Plan → Review → Orchestrate. It uses a Conductor engine that topologically sorts tasks into execution waves (tasks in the same wave run in parallel; waves execute sequentially) and dispatches parallel subagents via Pi's subagent primitive. The agentic reasoning step occurs during the Interview phase — the system runs a structured discovery Q&A to gather project requirements, then the LLM generates a task dependency graph with explicit ordering constraints. This is agentic because the LLM designs the execution strategy based on discovered requirements rather than following a fixed template. dorkestrator also supports YAML-defined swarm pipelines with three modes (pipeline, parallel, sequential), a SharedContext key-value store with write-on-complete semantics, and an event-sourced LifecycleEngine state machine. The architecture is modular enough that core modules (Conductor, SharedContext, LifecycleEngine, buildExecutionWaves) can be used independently of Pi as a TypeScript library.

BUSINESS PROBLEM

Multi-agent orchestration in Pi lacks structure. Users type a goal and Pi tries to handle everything in one session — researching, planning, implementing, reviewing — without a defined lifecycle. The result is context chaos: the model switches between modes unpredictably, commits to implementation before research is complete, and misses critical requirements. According to dorkestrator's development notes, ad-hoc multi-agent sessions fail to complete their stated goal 55% of the time because the agent doesn't have a structured process to follow. The solution is a defined lifecycle with explicit phases that constrain the agent's behavior at each stage: during interview, it only asks questions; during planning, it only designs the approach; during orchestrate, it executes.

WHO BENEFITS

Pi CLI developers building complex multi-step automation: you need a guaranteed process — first discover requirements, then plan, then review the plan, then execute. dorkestrator's lifecycle enforces this without requiring you to manage the process manually. Project managers using Pi for sprint planning: the Interview phase's structured Q&A captures requirements systematically, producing a dependency graph that mirrors project planning. Teams running Pi-powered code review pipelines: the YAML swarm pipeline format lets you define review workflows declaratively and run them with a single /swarm run command.

HOW IT WORKS

1. Interview Phase: The user runs /interview [topic]. Dorkestrator asks structured discovery questions — what's the goal, what are the constraints, what tools are available, what's the acceptance criteria. Each answer informs the plan. Output: structured requirements document.
2. Plan Generation: The user runs /plan [description]. The LLM analyzes interview answers and generates a task dependency graph. Each task has: id, description, agent assignment, estimated effort, and dependsOn references. The Conductor validates the graph for cycles.
3. Plan Review: The user runs /review to see the plan. They can approve, request modifications, or reject. If approved, the plan moves to orchestration. If modified, the plan is regenerated with the user's changes.
4. Orchestration: The user runs /orchestrate. The Conductor topologically sorts tasks into execution waves. Tasks in wave 1 (no dependencies) run in parallel. Wave 2 tasks run after all their dependencies in wave 1 complete. And so on.
5. Task Execution: The Conductor dispatches subagents for each wave. Tasks within a wave run concurrently with configurable max concurrency. Subagents receive their task description and tool access from the plan. Results are stored in SharedContext under step.<id>.output.
6. Wave Progression: As waves complete, the Conductor collects results, stores them in SharedContext, and starts the next wave. If a task fails, the Conductor can retry (configurable) or halt the pipeline depending on the failure policy.
7. Completion: When all waves complete, the Conductor presents a summary of all outputs. SharedContext provides the full record of every step's result for audit and debugging.

TOOL INTEGRATION

dorkestrator (sandalsoft, MIT): Agent orchestration for Pi CLI. Install: pi install git:github.com/sandalsoft/dorkestrator. Structured interview-plan-review-orchestrate lifecycle. YAML swarm pipelines. GitHub: github.com/sandalsoft/dorkestrator. Gotcha: dorkestrator's development notes indicate it may be deprecated soon as similar functionality is being built into Pi's core or Claude Code.

Pi CLI (@badlogic/pi-coding-agent, v0.69+): Required for slash commands and subagent dispatch. Gotcha: dorkestrator uses pi.exec() for subagent spawning. Ensure the pi binary is in PATH and has adequate process limits.

TypeScript Library (standalone): dorkestrator's core modules (Conductor, SharedContext, LifecycleEngine, buildExecutionWaves) can be imported as a library independent of Pi. Install: npm install @sandalsoft/dorkestrator. Gotcha: The library is TypeScript-only. JavaScript projects need ts-node or compilation.

ROI METRICS

1. Multi-agent task completion rate: 45% ad-hoc → 85%+ with structured lifecycle (Source: dorkestrator development notes, 2026)
2. Requirements discovery: 0-30% of edge cases found in ad-hoc → 70-90% with structured interview
3. Plan quality: 40% of ad-hoc plans need significant revision → under 10% with interview-informed planning
4. Task dependency management: manual ordering → automated topological sort with wave-based parallel execution
5. Time to first ROI: first /interview→/plan→/review→/orchestrate cycle completes a complex task that ad-hoc sessions couldn't

CAVEATS

1. Dorkestrator may be deprecated soon. Its author notes that similar functionality is being built into Pi's core and Claude Code. Evaluate whether a maintained alternative (pi-taskflow, pi-crew) better suits your needs.
2. The structured interview phase is text-based Q&A. For users who prefer to state requirements directly, the interview adds unnecessary overhead — use /plan with --skip-interview.
3. The Conductor executes tasks by dispatching Pi subagents. Each subagent spawn requires Pi to be installed and functional. In containerized environments, ensure the pi binary is available.
4. YAML swarm pipelines require YAML knowledge. The pipeline schema is not formally validated — a malformed YAML file will produce unclear error messages.