pi graph
Deterministic YAML workflow graphs for coding agents. Your agent authors the graph; from then on code owns order, gates, retries, and budget — the model does the work inside each node and cannot skip one. Every run leaves per-node evidence.
Features
- Deterministic execution — agents cannot skip, reorder, or half-run a step
- Gates, retries, and budgets enforced by code, not by prompt hope
- Per-node evidence for every run: inspect what happened, node by node
- Crash recovery with explicit resume — no orphaned runs
- Deterministic optimization lifecycle: baseline vs candidate with hypotheses and mechanisms
- Shell-only workflows need no model runtime; model nodes use the provider you already pay for
Setup
- 1git clone https://github.com/ali-abassi/pi-graph.git
- 2cd pi-graph && ./install.sh
- 3piw doctor
- 4piw create review --action parallel-review
- 5piw validate review/steps.yaml
- 6piw run review/steps.yaml --input-file task.md
How It Works
The Problem
Coding agents skip steps. Ask for a plan, a build, and a review, and somewhere around step three the model decides it knows better. Prompts don't fix this — they're suggestions, and the agent is the executor. pi graph inverts the relationship: an authored YAML graph owns control flow, and the model works inside each node.
Graphs Own Order
A steps.yaml file declares nodes, dependencies, gates, retries, and budgets. The piw orchestrator executes that graph deterministically. The model can do work inside a node, but it cannot decide which node comes next or whether one is optional.
Evidence Over Vibes
Every run writes per-node evidence — inputs, outputs, exit codes, timing. You can inspect any node's IO after the fact, compare a baseline run against a candidate run, and prove what happened instead of trusting a summary.