pi-taskflow: Declarative Multi-Phase DAG Workflows with Resumable Runs

pi-taskflow is a zero-dependency Pi extension by heggria that provides declarative multi-phase taskflow orchestration with dynamic fan-out, isolated subagent context, and cross-session resumable runs. It ships 18 built-in agents across 6 model roles with a JSON DSL supporting 8 phase types: agent, parallel, map (fan-out), gate, reduce, approval (human-in-the-loop), loop (iterate-until-done), tournament (best-of-N with judge), and flow (composition). The agentic reasoning step occurs at phase-level input-hash resumption — the runtime caches completed phases and skips them on re-run, only re-executing phases whose upstream dependencies changed. This is agentic because the runtime evaluates execution state and makes intelligent cache-invalidation decisions, not just blind replay. pi-taskflow is the only Pi extension combining declarative DAGs, cross-session resume, zero dependencies, and human approval gates.

BUSINESS PROBLEM

Complex multi-step tasks in Pi require manual context management. A developer who needs to research, plan architecture, implement code, review changes, and run tests must either do everything in one bloated session or manually copy results between sessions. According to pi-taskflow's ecosystem analysis (June 2026), the Pi ecosystem has 20+ delegation extensions but none combine all three capabilities: declarative DAGs, cross-session resume, and zero dependencies. Most solutions either force an opinionated pipeline (pi-pipeline, pi-agent-flow), require heavy runtime deps (pi-crew, ultimate-pi), or lack DAG support entirely (pi-subagents). The gap is real: teams building multi-step Pi workflows spend 40% of their time managing tool handoffs rather than doing actual work.

WHO BENEFITS

Pi CLI developers building multi-phase automation pipelines: you need to research, plan, implement, review, and test in sequence — and you need to be able to resume after a session crash without re-running everything. pi-taskflow's phase-hash resume makes this possible. Teams using Pi for code review workflows: you want a repeatable 'review all focused changes' pipeline that saves as a one-word /tf:review-fixes command. pi-taskflow's save-as-command feature turns any flow into a slash command. Engineers running long-running Pi background tasks: pi-taskflow's approval gates let you inject human review at critical decision points without pausing the entire pipeline.

HOW IT WORKS

1. Flow Definition: The user writes a declarative JSON flow — either inline or saved to ~/.pi/flows/. Each phase specifies: type (agent, parallel, map, gate, etc.), task prompt, agent model, dependencies, and optional gates. Output: validated flow definition.
2. Flow Execution: The user runs /tf:run flow-name [args]. pi-taskflow resolves the flow, validates the DAG for cycles, and begins executing phases in dependency order. Phase-level concurrency is configurable.
3. Parallel Execution with Map: For array-based tasks, the map phase fans out — one subagent per array item, with {item} bound to each child's context. pi-taskflow spawns isolated Pi child processes with bounded concurrency.
4. Gate and Approval Checkpoints: When a gate phase runs, the runtime evaluates the subagent output against quality criteria. If the gate fails, the flow halts. Approval phases pause and present output to the human for approve/reject/edit before continuing.
5. Cross-Session Resume: If the Pi session crashes or the user closes it, the flow state is persisted to disk. When the user calls /tf:resume runId, pi-taskflow loads the saved state, computes input hashes for each cached phase, and skips completed phases whose upstream dependencies haven't changed. Only remaining phases execute.
6. Loop Iteration: The loop phase runs a body task repeatedly until a condition is met, convergence is detected, or a cap is reached. Each iteration gets fresh context. The runtime tracks iteration count and total cost.
7. Tournament Select: The tournament phase spawns N variants of a task (e.g., 3 different implementation approaches), a judging agent evaluates each against criteria, and the best result is returned or aggregated.

TOOL INTEGRATION

pi-taskflow (heggria, v0.0.13, MIT): Zero-dependency DAG workflow engine for Pi CLI. Install: pi install npm:pi-taskflow. GitHub: github.com/heggria/pi-taskflow. 18 built-in agents across 6 model roles. Gotcha: The DAG must be acyclic — cycles are rejected at validation. No loop-until-done in current version (on roadmap).

Pi CLI (@badlogic/pi-coding-agent, v0.69+): The hosting agent for pi-taskflow. Required for extension loading and subagent spawning. Gotcha: pi-taskflow spawns Pi child processes for each agent phase. Ensure your Pi binary is in PATH.

Node.js (v20+): Runtime requirement. pi-taskflow uses only built-in modules (fs, path, os, child_process, crypto). No third-party npm dependencies. Gotcha: pi-taskflow relies on child_process.spawn for subagents. Containerized Pi environments must have the spawn syscall available.

ROI METRICS

1. Workflow crash recovery: 100% manual re-run without resume → 80-95% phase reuse with input-hash resume (Source: pi-taskflow ecosystem analysis, June 2026)
2. Multi-phase task completion: 2-3 hours sequential → 20-45 minutes with parallel DAG execution
3. Flow definition time: 30-60 min coding bash scripts → 5-10 min writing declarative JSON DSL
4. Human review overhead: manual context switching between tools → in-flow approval gates with structured output
5. Time to first ROI: first saved flow becomes a permanent /tf:command — each reuse saves the setup time

CAVEATS

1. No detached background execution. The Pi session must remain open for the flow to run. Background execution is on the roadmap but not yet implemented.
2. The map phase requires a JSON array input. Text lists must be converted to JSON via a preliminary agent phase with output: json.
3. Flow definitions are JSON files that must be manually saved. There is no visual flow builder — all DAG design is code-first.
4. Cross-session resume is keyed on phase input hashes. If your upstream tool (e.g., web search) returns different results between runs, downstream phases will re-execute even if the task is the same.