# VibeFlow

> A Claude Code plugin that governs the full SDLC through multi-AI consensus, testability-gated requirements, and risk-proportional quality gates — 100% local, file-backed state.

- **Type:** MCP server
- **Install:** `agentstack add mcp-mytechsonamy-vibeflow`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mytechsonamy](https://agentstack.voostack.com/s/mytechsonamy)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [mytechsonamy](https://github.com/mytechsonamy)
- **Source:** https://github.com/mytechsonamy/VibeFlow
- **Website:** https://www.linkedin.com/in/mustafa-yildirim-tech/

## Install

```sh
agentstack add mcp-mytechsonamy-vibeflow
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-mytechsonamy-vibeflow
- Seller: https://agentstack.voostack.com/s/mytechsonamy
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.