Pi Flows YAML DAG Multi-Agent Orchestration

pi-flows adds multi-agent workflow orchestration to the Pi Coding Agent. You define reusable workflow templates as YAML DAGs (directed acyclic graphs) where each step connects to an isolated agent session with scoped tools and filesystem access. The engine schedules independent steps in parallel up to a configurable max_concurrent limit. A built-in Flow Architect agent analyzes your conversation context, selects agents from a catalog, and designs a complete flow DAG automatically. Each agent runs in an isolated session with its own model role tier (@coding, @planning, @research, @compact), tool allowlist, and filesystem sandbox. The agentic reasoning step happens at fork and loop nodes where the flow-decision router evaluates branching conditions and makes autonomous routing decisions based on intermediate outputs. The live TUI dashboard shows per-agent status, elapsed time, files modified, and tests passed — all while the main session stays fully interactive.

BUSINESS PROBLEM

A senior developer at a 30-person SaaS company spends 14 hours per week manually switching between coding contexts — researching API docs, planning architecture, writing implementation code, reviewing changes, running tests — each requiring a separate mental model and tooling setup. According to the Microsoft Work Trend Index 2025 Annual Report, 73% of knowledge workers spend more than 2 hours per day switching between tools without completing a single task. At a fully loaded cost of $100/hr, that’s $1,400/week per developer in context-switching overhead — $72,800/year per developer.

WHO BENEFITS

FOR senior engineers at 10-100 person startups using Pi Coding Agent daily SITUATION: You’re doing research, architecture, implementation, and review all in one Pi session. PAYOFF: Each phase gets its own clean session. The Flow Architect designs the DAG. Parallel phases run concurrently.

FOR tech leads managing 3-8 developer teams on agentic coding workflows SITUATION: Your team adopted Pi but every developer has their own ad-hoc workflow. PAYOFF: YAML flow templates codify best practices. New hires run the same flows as senior devs.

FOR open-source maintainers triaging issues and reviewing PRs across multiple repos SITUATION: Each issue requires exploration, reproduction, fix implementation, and test verification. PAYOFF: pi-flows runs repo-scouting, fix-implementation, and review-verification as parallel agent chains.

HOW IT WORKS

1. Flow Design (Flow Architect agent — 5-10 sec) Input: Natural language task description Action: Flow Architect queries agent_catalog, designs DAG with node types and blockedBy edges Output: Validated YAML flow definition

2. Role Resolution (Pi runtime — <100ms) Input: Agent role tier declarations from flow YAML Action: Runtime maps each tier to concrete model via /roles configuration Output: Resolved agent configurations with validated tool sets

3. Parallel Scheduling (pi-flows engine — ~200ms) Input: Resolved DAG with dependency edges and max_concurrent limit Action: Engine topologically sorts nodes into waves for concurrent execution Output: Execution plan with wave assignments

4. Agent Execution (Isolated Pi subprocesses — variable per task) Input: System prompt + task description + file context Action: Each agent runs in isolated session with scoped tools Output: Structured results with status, elapsed time, files modified

5. Fork/Loop Decision (flow-decision Router — ~800ms) Input: Previous node outputs + branch conditions Action: Router evaluates conditions against output data for autonomous routing Output: Routing decision signal — continue, branch, loop, or terminate

6. Result Synthesis (Debrief agent — 2-4 sec) Input: All completed node outputs Action: Debrief agent merges findings, resolves conflicts Output: Structured JSON summary with per-node results

7. Human Review (TUI Dashboard — ~30 sec) Input: Completed flow summary in live TUI dashboard Action: Human reviews agent outputs, expanded detail views Output: Approval decision — accept, modify, or abort

TOOL INTEGRATION

Pi Coding Agent v0.74+ Role: Primary runtime — provides agent loop, tool execution, TUI framework, extension API Install: pi.dev — curl-based install for macOS/Linux API key: No API key needed — uses your existing LLM provider keys Config step: Run /roles to map role tiers to concrete models Gotcha: Allowlist-based tool security means agents can only use listed tools

pi-flows npm package v0.x Role: Extension engine — adds flow tool, YAML DAG parser, parallel scheduler Install: pi install npm:pi-flows from within a Pi session Config step: Create agents/ directory with markdown agent files Gotcha: Flows run on Flow Architect’s initial analysis. Run /flows:new to regenerate DAG if context shifted

ROI METRICS

1. Context-switch reduction: 14 hours/week → 4-5 hours/week
2. Multi-step task completion: 3-4 hours → 45-90 minutes
3. Parallel agent throughput: 1 task at a time → up to 6 concurrent agents
4. First-week win: /flows:new generates DAG in 10 seconds from conversation context

CAVEATS

1. Token cost per flow (significant): Each agent session consumes tokens independently. 6-agent flow = 6x tokens. Set max_concurrent to 3-4 for daily use.
2. Flow Architect quality (moderate): Depends on agent catalog quality. Invest in clear system prompts.
3. YAML validation errors (minor): Cyclic DAGs produce silent failures. Validate before running.
4. Cross-agent context loss (moderate): Parallel agents cannot communicate mid-execution. Use sequential chains for overlapping files.