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.

1. Consensus-based — multiple AIs review critical work and must converge;

disagreement escalates to a person, never passes silently.

1. Quality-gated — automated, risk-proportional gates at every phase

boundary; nothing advances on a hunch.

1. 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 / 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

| Server | Surface | Tests |
|---|---|---|
| `sdlc-engine` | phase state machine, consensus recording, exit criteria, config schemas | 199 |
| `codebase-intel` | structure analysis, dependency graph, hotspots, tech-debt scan | 48 |
| `design-bridge` | Figma fetch, design-token extraction, style generation, impl comparison | 57 |
| `dev-ops` | GitHub + GitLab clients, pipelines, deploy/rollback | 72 |
| `observability` | metric collection, flaky-test tracking, perf trend, health dashboard | 76 |

Every server is TypeScript with Zod-validated inputs and an enforced
80/80/80/80 coverage threshold.

## How consensus works

1. An analysis skill produces an artifact and writes a **consensus-needed
   marker** naming the primary artifact (the PRD itself, not a summary).
2. A PreToolUse hook (`consensus-gate.sh`) blocks further tool calls until
   consensus runs — the loop **cannot be skipped**.
3. The orchestrator forks the available reviewers (claude-reviewer + the
   `codex` and `gemini` CLIs *if present on PATH* — graceful degradation),
   feeds each the primary artifact, and collects verdicts.
4. Verdicts are aggregated into an agreement score; critical findings are
   deduplicated so three reviewers flagging one line counts once.

**Thresholds:** `APPROVED` (≥ 90% agreement, 0 critical) ·
`NEEDS_REVISION` (50–89%) · `REJECTED` ( Using the interactive `/plugin` menu instead? In the **Add Marketplace**
> field enter `mytechsonamy/VibeFlow` (bare `owner/repo` — **no `github:`
> prefix**, the menu rejects it); the `github:` form is only for the slash
> command above.

Then **restart Claude Code** and verify with `/vibeflow:flow-status` (it
should report "project not initialized"). Start your first project with:

/vibeflow:onboard

**Prerequisites:** Claude Code, Node 18+, Git, and **`jq`** (the hooks need
it). For multi-AI consensus install at least one of the **`codex`** / **`gemini`**
CLIs (authenticated). Optional: a Figma token (DESIGN) and a GitHub/GitLab
token (DEPLOYMENT) — these integrations activate only when present.

Full walkthrough: [`docs/GETTING-STARTED.md`](docs/GETTING-STARTED.md).
Developing the plugin itself? Clone it and run with
`claude --plugin-dir ./` (see GETTING-STARTED, Option B).

> A runnable demo lives in [`examples/demo-app`](examples/demo-app).

## Documentation

- **Presentation kit** — executive & technical decks + briefs:
  [`docs/presentation/`](docs/presentation/)
- **Consensus flow** — [`docs/CONSENSUS-FLOW.md`](docs/CONSENSUS-FLOW.md)
- **Learning loop** — [`docs/LEARNING-LOOP.md`](docs/LEARNING-LOOP.md)
- **Auto-apply & safety rails** — [`docs/AUTO-APPLY.md`](docs/AUTO-APPLY.md)
- **Cross-project learning** — [`docs/CROSS-PROJECT-LEARNING.md`](docs/CROSS-PROJECT-LEARNING.md)
- **Roadmap** — [`ROADMAP.md`](ROADMAP.md)

## Status & scope

- **v2.26.0** — 38 engineering sprints; the autonomous-learning arc is
  feature-complete, plus guided DESIGN + ARCHITECTURE phases (Figma /
  Claude-native design, ADR authoring) and a hardened consensus pipeline.
- This is a **governance layer and a reference architecture**, not a SaaS
  product. It is a plugin: your machines, your files, your Git.
- It depends on the Claude Code runtime and, for non-Claude reviewers, on
  external CLIs — by design.

## License

Released under the **Apache License 2.0**. See [`LICENSE`](LICENSE).

## Author

Built by **Mustafa Yıldırım** — a technology leader with 25+ years in core
banking, payment infrastructure, and regulated fintech, exploring how
AI-orchestrated delivery can be made *governable* for high-stakes domains.

*If VibeFlow is useful to you, a ⭐ helps others find it.*

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mytechsonamy](https://github.com/mytechsonamy)
- **Source:** [mytechsonamy/VibeFlow](https://github.com/mytechsonamy/VibeFlow)
- **License:** Apache-2.0
- **Homepage:** https://www.linkedin.com/in/mustafa-yildirim-tech/

Install and usage instructions live in the source repository linked above.