vibe-dev

Vibe Dev v9

🌐 English: this file · Русский: README.ru.md

A harness-first plugin that turns a business idea into a shipped product — for founders who build with Codex and Claude Code.

Vibe Dev is built for entrepreneurs who don't write code but ship real products with AI agents. You stay at the level of business and architecture; the agent makes the technical decisions and does the work. The point of the plugin is to make the agent reliable — so "done" means done, not "the code compiled."

"The harness is enforcement, not documentation."

Every principle is backed by a real mechanism (hook / gate / agent / self-check), not a line in an instruction file that the agent can quietly ignore. Discipline is broken by exactly the link that's supposed to keep it — the agent itself. So the rules are turned into checkpoints that are actually enforced.

The number of mechanisms and their live status live in docs/traceability.md — the single source of truth (87 tracked today; some rows are honestly marked as discipline or a display-only layer — the on-screen jargon catcher, the secret-output mask, the /checkpoint nudge — and are not counted as enforcement). Each mechanism carries three attributes: where it's defined / what enforces it / what happens if you try to bypass it. The plugin's self-check verifies completeness — a claim without a live mechanism doesn't pass.

New in v9: the work is split across three models by stage — the top level (architecture, planning, critique, audit) runs on Fable 5.1 and writes no code; code is written by Opus 5, and only once there is a spec and a command that proves the result. Guards stopped lying when they break: 26 of 26 used to answer "no objections" when a helper utility was broken — now zero. Evidence of completion is produced by running: a receipt carrying the exit code and a fingerprint of the output, which cannot be written in prose. v8 made feature history append-only (provenance as an event log), turned context unloading into a deliberate /checkpoint instead of the roulette of auto-compaction, and physically denied the verifying agent the right to write code. v7 added auto-memory (a snapshot before compaction + a return brief), a browser tester that looks at the page with its own eyes, and secret locks. Every new guard was verified with live runs on the Claude Code 2.1.x engine — the verification date is recorded in each mechanism's row.

---

Who it's for

• Founders and non-engineers who want to ship a working product, not learn to code.
• People who already work with Codex and Claude Code and want the agent to behave like a disciplined senior engineer instead of an eager intern.
• Anyone tired of agents that declare "done" on code that was never actually run.

You describe the business. The agent picks the stack, writes the code, tests it, and only reports "done" when a verification command passed and the behavior matched expectations.

---

How it works (the harness in plain words)

An AI coding agent announces key moments: "about to save a file," "about to run a command," "showing a message to the human," "opening/closing a session." The plugin attaches small inspectors to those moments (hooks). Each inspector looks at the intent and returns one verdict:

• block — the action is cancelled (e.g. you can't mark a feature "done" without evidence);
• warn / inject — the action proceeds, but a note appears for the agent or a flag for the human;
• pass — all clear, stay silent.

The map of "on this event, call this inspector" lives in hooks/hooks.json and is loaded automatically on install (Claude Code v2.1+) — no manual wiring. Some posts sit outside the plugin, in the project's git pre-commit — they keep working even if the plugin is removed. Strictness is per-project: minimal / standard / strict (existing projects aren't broken — they're migrated with /upgrade-project, softly if needed: --soft).

---

What it catches (key mechanisms)

A. "Done" means verified, not claimed

Mechanism	What it catches	What it does
UI-evidence gate	a UI feature is marked "done" on typecheck/tests, but a real click shows nothing	block (a screenshot / live run is required)
Surface-aware evidence (v6.2)	a "no-UI" feature (API / scheduled job / CLI) is closed with no trace of a real call; a UI feature hides as a "library"	the surface is inferred from files and can only tighten: ui → block, others → warn with an acceptance recipe
Runtime evidence on logic + negative gate (v8)	green tests lie: a logic feature is closed on typecheck alone; a medium/large one ships with no "what if we break it" check	passing with no trace of a real run → block; M/L without a mutation or leak check → block
Adversarial fresh-context verifier (v8)	the same agent both writes the code and "confirms" it works	the verifier runs in assume broken until proven mode and is physically denied write access (the engine forbids it Write/Edit)
Test-strategy before build	a medium/large feature goes into work without a thought-through verification plan	block (no docs/test-strategy.md → it can't enter active)
Detailing stage (v8)	a large feature is dragged into work "verbally," with no broken-down plan	an M/L feature can't enter work without docs/changes/<id>/proposal.md carrying a prioritized user story in Given/When/Then → block
Data-model review gate	a DB schema is written without a separate critical review (the model "freezes," reworks are expensive)	block (no docs/data-model-review.md → it can't enter active)
State-machine transitions	a feature jumps to an invalid state / a corrupted state file	block (current project) / warn (legacy)

A2. Hook activation as a provable fact (v6.2)

Mechanism	What it catches	What it does
Heartbeat	hooks "look installed" but don't physically run (silent strictness theater)	every live event writes a stamp with the version; readers check freshness
Two-phase profile	profile says "strict" but enforcement never turned on	bootstrap writes pending-strict; only a live hook promotes it to real strict — the promotion is the proof
Git pre-commit backstop	the plugin was removed/broken and nobody noticed	an INDEPENDENT post in .git/hooks: a pending profile or stale heartbeat → block the commit
Fail-loud + crash artifacts	a guard crashed and silently "allowed everything" (a real bug, 2026-06-06)	crash → loud warning + crash log + a probe at session start
Real-shape fixture corpus	a gate green on synthetic data, broken on real files	self-check runs gates against 6 anonymized real feature_list files
/doctor	"why are the guards silent?"	self-diagnosis: profile / heartbeat / crashes / install + a fix table

A3. Feature history can't be rewritten (provenance, v8)

Mechanism	What it catches	What it does
Append-only event log	history is edited or erased after the fact	an edited/removed log line → reject the commit
Requirement-edit invariant	a feature's requirement (name, description, size, business invariant) is silently rewritten, or the feature is "cancelled" with no trace	an edit with no covering history event → reject the commit; ordinary work progress (active → verified → done) stays free
Crash-safe writer	an interruption mid-write tears the state apart	the single write path commits log then head in a safe order: an interruption is replayable, not lost
Archive by reference + evidence hash	finished features bloat the hot file, and the "done" evidence can be swapped	the body moves to an archive, a one-line reference stays in the working file; the hash is verified at commit time without loading the body into context
Open-tasks gate at ship	a feature is archived with unfinished items inside	archiving → block until the tasks are closed

A4. Context under control, not up to luck (v8)

Mechanism	What it catches	What it does
Deliberate /checkpoint	state lives only in the conversation — auto-compaction eats it at a random moment	checkpoint on command: provenance recovery → archive what's finished → cold-start gate: a templated or stale SESSION.md / incoherent history → block completion
Three-tier context	the body of a finished feature sits in the hot file forever	hot ≤200 lines (head + index) / on demand via search / cold = archive; a bloated hot file → warn at commit
Narrowed returns from reading agents	a research subagent dumps raw material into the main thread and eats the context	full result to a file, a ≤2 KB digest + path into the thread (critics' opinions are never trimmed)
Pre-compaction snapshot (v7)	auto-compaction happened anyway — facts were lost	before compaction a digest of FACTS is saved (not a "done" status); on return, a brief with "check the files, don't trust your memory of what's finished"

B. Safety and money

Mechanism	What it catches	What it does
Bulk-API gate	a mass external-API job with no limit check (real case: a project banned for 2 days + wasted money)	block without a pre-launch checklist (the checklist now requires explicit volume × price)
Model-swap guard	an edit introduces a model / setting that affects every answer (real case: 3 days of dropped client replies after "newer = drop-in")	warn "this is a contract change, run a smoke test"
Vendor-lock research gate	a specific provider is hard-wired into the architecture blindly, with no comparison	block an integration feature without docs/research/*.md
Hardcoded live key (v7)	a production key is written straight into source and rides into git	writing a file with a live key → block; lifted only by an explicit user phrase
Secret-in-prompt (v6.2)	the user pasted a live key into a message	warn: the key is compromised → rotate + move to .env
Secret-in-output (v6.2)	a CLI printed a token — it lingers in the session context	warn to the model: don't reuse the literal, suggest rotation (+ output masking on engines that support it)
Writes outside the project root (v7→v8)	the agent writes a file past the project, into someone else's folder	warn + a log entry; the corpus accumulates toward a future block
Concurrent-write advisory	two sessions write to one file (real case: data loss)	warn (advisory)

C. Anti-stall

Mechanism	What it catches	What it does
User stop-signal	the human writes "wrong way / stop / that's not it" and the agent keeps grinding tactically	inject "change the level, not the method; launch a diagnostic subagent"
Interrupt-recovery (v6.2.1)	a dropped connection (closed laptop lid) or an inbound message kills the running tool — the system falsely logs "user rejected," and the agent stalls for hours	the next message without a stop-word → inject "that was a disconnect, not a veto — continue the plan"; a real "stop" keeps its force
Repeated-failure detector	the same command is launched a 3rd time in a row with no success and no structural change	warn before running: prompt for a diagnostic subagent
Circuit breaker (v7)	even at double the repeat threshold the agent keeps grinding the same thing	a hard escalation into /stuck — stalling stopped being a matter of discipline