Spec-driven development
for AI agents
Define what to build, then let the agent build it right.
New in 1.17: the Hermes Agent edition →Four core commands.
Idea to audited code.
The main pipeline, plus 6 more commands for every workflow.
analyze
Scans your codebase. Learns patterns, conventions, architecture. Builds a local knowledge base.
gen-spec
Generates a spec with binary Definition of Done, scope, anti-scope, and file budget.
implement
Builds from the spec. Follows your patterns, respects budget, runs tests, self-verifies. With --loop, an executor and an independent audit work in fresh sessions.
audit
Checks every DoD item with evidence, from a review package of the diff. Pattern compliance. Verdict: PASS, PARTIAL, or FAIL.
Whoever built it
does not approve it.
New in 1.16 and off by default, implement --loop splits the work between sessions that cannot grade themselves. An auditor in a session that did not see the work finds what the implementer let slip.
- 1
Orchestrator
The session where you call
implement. Cuts the work into parts, writes each round's briefing, checks from outside and keeps the ledger. It does not implement. - 2
Executor
Implements one part in a fresh session, red before green, with a progress file at each milestone. It does not commit.
- 3
Audit
An independent audit checks the part in another fresh session, from a review package of the diff. PASS closes the part.
- 4
Fixes
At most two fix rounds, each re-audited on its own diff only. A third one runs only with your OK.
- 5
Pull request
With every part in PASS, company mode opens the pull request with the evidence. You review and merge it.
Turning it on
- Off by default. Without
--loop,implementruns phases 0 to 8 as before, and specs written before 1.16 stay valid. implement <spec> --loopfor one run, orloop: truein.vibeflow/loop/config.mdfor the project.--no-loopturns it off for one run, even with the config on.- One OK per feature to commit each round on the feature branch (or
commit-rounds: true). The loop never runs on the default branch.
A fresh session in each host
- Claude Code: the plugin's
vibeflow:executorandvibeflow:auditoragents. - Codex: a native subagent, or a new task given the briefing's path.
- Hermes: one
delegate_tasktask per round, with thegoalpointing at the briefing. The result comes back as a new turn, or in the call itself in a one-shot CLI run or a cron. - Cursor and Copilot: a new chat you open with the one-line instruction the orchestrator writes.
Company mode
- With every part in PASS, the orchestrator pushes the branch and opens the pull request with
gh, with the evidence in its body, then watches the checks. - Draft or ready by your repository's convention; draft when there is none.
- The agent never merges, deploys, applies a migration to a shared environment or reads production.
- It needs a remote on GitHub (or GitHub Enterprise) and
gh auth statusok. Without it, the loop pushes the branch and writes the body to.vibeflow/reviews/<feature>-pr-body.mdfor you to open the pull request by hand.
Requirements
- In Claude Code, version 2.1.69 or newer, for the loop and for the audit's review package.
- Node.js 18 or newer for the kit's scripts.
ghonly for the pull request in company mode.- The kit: Codex, Claude Code and Hermes get it with the plugin. In Cursor and Copilot, CLI 0.17.0 installs it, and an earlier install gets it with
--force.
From vague idea to verified code.
Watch Vibeflow turn a feature request into audited, pattern-compliant implementation.
Built for real workflows.
From solo devs to product teams.
New feature in an existing project
You need to add a payment flow. Instead of letting AI guess, you define scope (Stripe only, no PayPal), anti-scope (no subscription management), and a 5-check DoD. The agent implements exactly that.
Bug fix with proof and a paper trail
A date formatting bug in the dashboard, with a clear reproduction. Hotfix records the symptom before touching code, writes a regression test that fails on the current code, then fixes it. The trail lives in .vibeflow/hotfixes/.
Defining requirements before handing off
You have a feature idea but need to clarify scope before the dev team starts. Discover walks you through the hard questions and produces a clear PRD. No code involved.
Onboarding a new developer
New dev joins the team. Instead of reading 200 files, they run analyze. Vibeflow produces a comprehensive guide to the project: architecture, patterns, conventions, all with real code examples.
10 commands. Full toolkit.
Core pipeline plus power tools for every workflow.
Deep-scans your codebase and produces documentation: stack, architecture, patterns, conventions, all with real code examples.
Generates a technical specification with binary Definition of Done (3-7 pass/fail checks), scope, anti-scope, and risks.
Implements a feature from its spec with guardrails. Follows your patterns, respects budget and anti-scope, runs tests, self-verifies DoD.
Verifies implementation against the spec, from a review package of the diff. Checks DoD, patterns, and tests, tests scenarios, and gives every finding a severity. Produces a PASS, PARTIAL, or FAIL report.
Interactive dialogue that turns a vague idea into a clear PRD. Challenges assumptions, cuts scope, forces decisions.
Creates a self-contained prompt for a coding agent in a separate session. Embeds your real patterns and conventions.
Fast-track for small planned tasks (up to 4 files). Skips discovery, generates spec directly. For changes with clear requirements; a defect with evidence goes to hotfix.
Fixes an observed defect with reproducible evidence in one call: writes a short trace doc before touching code, implements the fix, and backs it with a regression test written before the fix.
Updates .vibeflow/ with corrections, new conventions, architectural decisions, or patterns. Also imports from external repos.
Compiles statistics from audit reports and the loop's ledgers. Pass/fail rates, most violated patterns, common DoD gaps, quality trends over time, and the loop's numbers.
Choose your agent.
One shared plugin for Codex, Claude and Hermes, plus native editions for Cursor and Copilot.
Codex
Native plugin with focused skills that Codex discovers from your request.
Hermes Agent
The same shared plugin, read from the manifest at the package root. Ask in natural language, as in Codex: Hermes has no slash commands for the skills. Start a new session after installing.
Claude Code
Plugin with slash commands for Claude Code and Claude Desktop.
- Open Customize in the sidebar
- Click + → Add marketplace
- pe-menezes/vibeflow
- Click Sync
- Browse plugins → Install Vibeflow
Cursor
Rules and skills for Cursor Agent. Slash commands via /skill-name.
GitHub Copilot
Prompts, agents, skills, and instructions for Copilot Chat.
Loop kit: since CLI 0.17.0, --cursor also installs it into .cursor/skills/vibeflow-implement/loop/ and --copilot into .github/vibeflow/loop/. An earlier install gets it by running the installer again with --force. In Codex, Claude Code and Hermes, the kit ships inside the plugin.
On Hermes, the install scan reads the kit README's description of the secret detector as a secret; --force installs.
By default the installer adds installed files and the .vibeflow/ folder to .gitignore so they are not committed. Remove the "Vibeflow" block from .gitignore if you want to track them in git. If you version .vibeflow/, keep .vibeflow/reviews/ out of it, since it holds working material: the review packages, rewritten on every audit, and the PR body.
Start building with specs.
Created by Pedro Menezes
Have a question or feedback?
Send a message. I'll get back to you soon.