vibeflow

VibeFlow

Governed, multi-AI software delivery for Claude Code. Requirements to release as a single, auditable, self-improving loop.

---

Most AI coding tools stop at generate code. VibeFlow governs the whole delivery lifecycle — requirements through deployment — as one orchestrated, auditable loop, and adds the three things teams actually need before they trust AI in delivery:

• Truth-validated requirements — every requirement is scored for testability; specs that can't be tested block the build at the source, where defects are cheapest to kill.
• Multi-AI consensus review — critical artifacts (the PRD, the architecture, the release decision) are cross-checked by Claude + ChatGPT + Gemini until they reach a quorum, or the system escalates to a human. No silent passes.
• Risk-proportional quality gates — the release bar is tuned to the domain's risk (healthcare ≥ 95, financial ≥ 90, e-commerce ≥ 85, general ≥ 80), so a marketing site and a payments core aren't held to the same standard.

It runs entirely on your own machine as a Claude Code plugin. All durable state is plain files in your Git repo — no server, no database, no telemetry. And it learns from its own history to improve over time, with strict safety rails that auto-revert any change that makes outcomes worse.

This repository is the reference implementation — a working, hardened demonstration of what a governed AI-orchestrated SDLC looks like when it is engineered rather than improvised.

---

Why it exists

The bottleneck in software has moved from writing code to trusting it. AI can produce a great deal of plausible code, quickly — and that is exactly the danger. An ambiguous PRD yields confident code that solves the wrong problem; a single model is confidently wrong with no second opinion and no record of why a decision was made; quality scrutiny bolted on at the end surfaces problems when they are most expensive to fix.

VibeFlow is an opinion about how to close that gap: deterministic where it must be, intelligent where it helps — and the architecture keeps the two in their lanes.

The four principles

1. Truth-driven — requirements are the source of truth; untestable requirements gate development.
2. Consensus-based — multiple AIs review critical work and must converge; disagreement escalates to a person, never passes silently.
3. Quality-gated — automated, risk-proportional gates at every phase boundary; nothing advances on a hunch.
4. Self-improving — safely — the system mines its own review history and auto-tunes within strict, allow-listed bounds, reverting anything that regresses.

The seven governed phases

Each phase boundary is a gate with machine-checked exit criteria; /vibeflow:advance refuses to move on until they are satisfied.

Phase	What VibeFlow guarantees
1 · Requirements	Testability scored; ambiguity flagged; score < 60 blocks the build
2 · Design	Wireframes, design tokens, accessibility checks
3 · Architecture	Decision records (ADRs), 3-AI vote
4 · Planning	Epic breakdown, dependency graph, test strategy
5 · Development	Quality gates on every commit
6 · Testing	Coverage, mutation testing, chaos injection
7 · Deployment	GO / CONDITIONAL / BLOCKED release decision + rollback

Architecture at a glance

VibeFlow is built entirely from Claude Code native primitives — skills, sub-agents, hooks, and MCP servers — with no separate server process and no database. Four layers, each with a deliberate job:

Layer	Primitive	Responsibility
Orchestration	Skills (prose + bash)	Phase walks, consensus loops, operator commands
Specialization	Sub-agents	Deep artifact rewrites & reviews in isolated context
Enforcement	Hooks	Gate writes, run consensus, persist & restore state
Computation	MCP servers (TypeScript + Zod)	State transitions, validation, analysis, integrations

All durable state lives in your repo:

.vibeflow/state/<project>/
  project.json   # rollup: current phase, satisfied criteria, metrics
  events/        # append-only log of every transition
  archive/       # per-phase snapshots
.vibeflow/state/consensus/history.jsonl

Because state is text, Git is the time machine — you diff it, blame it, branch it, and review it like any other artifact. bin/replay-events.sh reconstructs project.json byte-for-byte from the event log.

The five MCP servers