agent-graph-flow
Open-source CLI (agf, v0.20) that turns requests into persistent execution graphs and runs an autonomous SHAPE → BUILD → SHIP cycle with non-negotiable guardrails: WIP=1, TDD, Definition of Done, Provenance. Skill precision via ACO (Ant Colony Optimization). Local-first, no Docker.
This project started as mcp-graph (documented in the blog’s origin-story posts) and was rewritten and renamed to agent-graph-flow (
agf). The core methodology shifted from a coordinated MCP mesh to ACO (Ant Colony Optimization) applied to skill precision, and versioning was reset (mcp-graph’s v7.0 doesn’t correspond to the current v0.20 — they’re different codebases).
The problem
AI coding agents are powerful, but the way most developers use them — so-called vibe coding — creates concrete problems:
- Every session starts from scratch. The agent doesn’t remember what it did yesterday. You spend tokens re-explaining context, re-reading files, re-describing the architecture.
- Requests become disconnected tasks. No dependencies, no calculated priorities, no traceability.
- Agent CLIs fail two ways: the wrong skill gets picked for the right intent, or the right skill gets followed imprecisely — and better docs alone don’t fix this, since docs don’t self-correct when behavior changes.
- No discipline is enforced. The agent generates code without tests, without typing, without following project patterns.
The solution
agent-graph-flow (agf) is a local-first TypeScript CLI — no Docker, no external infra — that turns what you ask for into a persistent execution graph, and runs an autonomous SHAPE → BUILD → SHIP cycle with non-negotiable guardrails: WIP=1 (Little’s Law), TDD, Definition of Done, and Provenance (no quality claim without concrete evidence).
ACO — precision as the core methodology
agf borrows concepts from Ant Colony Optimization (ants reinforcing successful paths, abandoning bad ones) for skill routing and precision: commands that work well for a given task type gain priority over time, ones that fail lose priority, and a health dashboard aggregates these signals to flag when the system as a whole is degrading.
Provenance (epistemic integrity): every quality claim about the code needs concrete evidence before it counts as true — no evidence doesn’t count, a passing test counts, a deterministic check counts even more.
Verified numbers (v0.20)
| Metric | Value |
|---|---|
| Version | 0.20 |
| Full test suite | 16,681 tests |
| Standalone binaries | macOS (arm64), Linux (x64), Windows (x64) |
| TypeScript | strict mode |
| License | AGPL v3 |
Technologies used
- TypeScript / Bun (strict mode)
- SQLite (local graph storage)
- Vitest (hierarchical test gates — from an isolated file up to the full suite before each push)
License
AGPL v3 (commercial use under a separate license via COMMERCIAL.md)