Philosophy
Deterministic orchestration, validation before trust, and honest limits.
Philosophy
The engineering problem
AI coding agents are powerful, but their outputs are not deterministic. Teams still need repeatable workflows: known steps, isolated branches, external validation, visible cost, and audit trails—not opaque runs where nobody can explain what happened or why.
AgentFlow exists to make orchestration explicit. You configure the pipeline, the validation commands, and the economic guardrails; the tool coordinates execution and records what ran.
How AgentFlow approaches it
The default mental model is spec → plan → implement → verify → review → report. Each phase has a defined place in the state machine and in the reports under .agentflow/runs/.
Explicit state means runs and tasks are backed by SQLite with a documented state machine. You can inspect status, resume, and correlate reports with run IDs instead of guessing from chat history.
Local-first investigation runs grep, filesystem scans, and context packing on your machine before cloud calls. The goal is smaller, more relevant prompts—not shipping entire repositories to a model because it is convenient.
Cost awareness applies heuristic token estimates and configurable budgets before execution. Estimates are approximate, but they are far better than discovering spend only after a long agent session.
Git worktree isolation keeps one task on one branch and one working tree. Parallel work stays separated from your main checkout.
Validation by your commands means go test, linters, and scripts you trust—not the agent claiming success. AgentFlow schedules those checks; it does not replace your test suite.
Reproducible reports capture markdown and JSON artifacts so operators and reviewers can audit a run days later.
What we do not claim
Trade-offs worth understanding
| Gain | Cost |
|---|---|
| Predictable pipeline steps | Less “one-shot magic” than ad-hoc agent chats |
| Cost estimates up front | Estimates are approximate (chars/token heuristics) |
| Worktree safety | Extra disk and git complexity |
| Pluggable agents | You must install and configure each CLI |
These trade-offs are intentional. AgentFlow favors control and auditability over the illusion of fully autonomous coding.
Configuration levers
Once you accept that model, a few knobs matter most:
work.auto_verify,work.auto_review— balance automation against manual gatespolicies.require_clean_git— block dirty trees when policy demands itbudgets— economic guardrails before expensive steps run