vince-gate

Native Codex plugin

Requires Python 3.11+ and Git. Register the one stable marketplace once:

codex plugin marketplace add elroykanye/vince-gate --ref main
codex plugin add vince-gate@vince-gate

Upgrade that same installation with codex plugin marketplace upgrade vince-gate, then codex plugin add vince-gate@vince-gate and start a fresh chat. For rollback, pinning, migration from the 0.15.0 local folder, and tool permissions, see plugin installation. Use the legacy installer only when you deliberately want flat skills or another harness.

A portable implementer-and-reviewer toolkit for AI coding agents. Vince is not a knowledge base and not a linter — it is a pair of opposed roles that together make "done" mean something:

• vince-implement drives a task end to end: contract first, test-first TDD, an evidence ledger, an end-to-end wire proof, definition-of-done gates, and a self-attack pass before it will hand off.
• vince-review checks the task's stated requirements and relevant tests in a fresh context. All stated points met and relevant tests passing means PASS. Anything else is out of scope. It writes one verdict and stops: no automatic remediation or re-review. It does not impose attack catalogs, mutation campaigns, or extra process gates unless the task requires them.

The two rules that make the rest work: nothing is done without a PASS verdict, and no claim counts without the command and its output behind it.

Vince keeps chat output deliberately small: Result, an optional Problem, and Next. Full test, mutation, and review evidence stays in the task artifacts instead of being poured into chat.

Spec-driven frameworks — OpenSpec, Spec Kit, Superpowers, BMAD, GSD — enforce process: phases, gates, personas, the order you do things in. None of them verify that the work is what it claims to be. vince-gate enforces evidence: a contract copied verbatim, tests proven able to fail, mutants that must die, a wire proof over real transport, and a reviewer that starts from the diff rather than from your summary. It composes with those frameworks rather than replacing them.

New here? INSTALL.md gets it running (paste one block into your agent), then the user guide covers using it.

The skills

Works with any harness

The canonical format is the open Agent Skills layout: one SKILL.md plus conditional reference/ resources. Claude Code, Codex, Gemini CLI, and GitHub Copilot receive native YAML skills with progressive disclosure; Cursor and Windsurf receive conditional rules; the generic binding writes plain markdown plus a small AGENTS.md pointer block.

python scripts/install.py bindings          # claude, codex, gemini, copilot, cursor, windsurf, generic

claude, codex, and generic are live-verified. Gemini CLI and GitHub Copilot follow their documented native skill paths but remain unverified until a real runtime discovers and invokes them. Cursor and Windsurf are also render-tested only. Adding a runtime is a small JSON binding.

The compatibility question that actually matters is not whether the files install, but whether the harness can give the reviewer a fresh context. Claude Code and Codex both can, natively. Cursor, Windsurf, Gemini CLI, and GitHub Copilot may require a second session depending on the runtime surface, so the review becomes a second chat you open yourself — same rigour, one manual step, easier to skip. docs/harnesses.md has the per-harness table.

Deliberate about what it spends

A gate this thorough costs tokens, so the toolkit is built to spend them on judgement and nothing else. scripts/check.py runs the deterministic half of a review — stray files, bot trailers, new skips, debug statements, possible secrets, whole-file rewrites — as one command with a compact report, so ten shell commands and their raw output never enter a model context. Skills keep on-demand detail in reference/ files that load at the step that needs them. T1 tasks spawn no reviewer. And because the ledger holds the contract and the evidence on disk, you can compact or clear between phases and pick up from the file instead of the scrollback.

scripts/resume.py rebuilds a task from its ledger alone and refuses to call it safe if anything is missing — which is what makes "clear context mid-task" a checked claim rather than a hopeful one. With checkpoints: suggest, Vince offers a /compact at the boundaries that pass; it cannot type it for you and does not pretend otherwise.

See skills/_shared/token-discipline.md.

It talks like a person

Vince is dry, a little sarcastic, and allergic to jargon it has not explained. It assumes you are smart and that you do not necessarily know what "surviving mutant" means, so it keeps the precise term and adds the plain-English version beside it.

Three rules keep that from costing you anything. A joke never carries information — strip every one out and the message is still complete. Comedy is in the delivery, never the verdict — severity and PASS/FAIL are always flat. It is never aimed at you — fair targets are the situation, the tooling and itself.

It goes completely straight for security findings, anything destructive, and any time it was wrong. And artifacts — ledgers, verdicts, commit messages — stay professional, because someone reads those later without the context. Set voice: plain or terse in the profile if you would rather it did not.

See skills/_shared/voice.md.

Project-agnostic by construction

Vince ships no assumptions about your stack. Everything project-specific — test commands, integration branch, tracker, versioning rule, data isolation key, locales, wire-proof rigs, extra DoD gates, known traps, tier overrides — lives in .vince/profile.md, written by vince-setup and read by every other skill. Swap the profile and the same discipline applies to a Go service, a React app, or a Python pipeline.

Many repos under one hub? Two profiles: an estate-level one for the repo map, stacks, branch model, tracker and estate-wide gates, and a per-repo one for verified commands and baselines. The invariant that keeps it honest is that a hub profile cannot verify a command — nobody runs a hundred suites from a hub, so its per-stack values are unverified by construction and the first task in a repo is what promotes them. See Many repos.

Self-healing and self-improving

vince-brief is the response layer for a Vince task: action/result first, a visible state only when work is ongoing, and one concrete next action. Say normal mode or verbose mode to turn it off for the current task. It never shortens required safety or evidence.

• Healing. A stale profile is worse than none, because it is trusted. When a recorded command fails mid-task, vince-implement re-derives it once, verifies the replacement, repairs the profile and records the correction — and stops if a second field is wrong, because that means a full refresh. install.py doctor --fix repairs the install layer and safely sanitizes compact profiles/lessons (with backups); vince-doctor covers the profile, the work in flight and leaked worktrees.
• Improving. Every finding carries a [caught: …] tag. At PASS, vince-learn promotes patterns — not incidents — into project config: seen twice becomes a trap, detectable by command becomes a gate, a correction becomes a lesson. It reads .vince/metrics.jsonl to report which attacks actually earn their time in this codebase and whether rounds-to-PASS is falling.

Built against the evidence

Three design rules exist because measurement says they matter, and the skills say why in-line:

• The reviewer reads the diff before it reads your ledger. Reviewers handed text asserting code is sound miss most of what they would otherwise catch, and autonomous agents are far more susceptible to that framing than people are. Start from the stated requirements, not success claims.
• Mutants, not coverage. Suites at 100% coverage routinely kill single-digit percentages of mutants. TAMPER uses the project's mutation tool diff-scoped where one exists, and surviving mutants on changed lines are work, not a score.
• A different model reviews, where you can arrange it. Fresh context breaks the correlation introduced while generating, but not the correlation baked into the model's parameters — the blind spot that wrote the bug is the blind spot that misses it.

And the honest limit: independent review measurably beats same-session review, most clearly on critical errors, but it still finds a minority of defects. That is why the wire proof and the mutation gate carry as much weight here as the review does — they do not depend on a model's judgement at all.

Install

As a Claude Code plugin:

/plugin marketplace add elroykanye/vince-gate
/plugin install vince-gate@vince-gate

Any harness: open INSTALL.md and paste the block into your coding agent — it clones, detects your harness, installs, verifies and reports back.

Releases are git tags, so pinning a version is git checkout v0.1.0 then reinstall — see Versions.

By hand (location-independent; clone anywhere):

git clone https://github.com/elroykanye/vince-gate.git && cd vince-gate
python scripts/install.py install --scope user            # every project, no repo footprint
python scripts/install.py install --target /path/to/repo  # auto-detects the harnesses in use
python scripts/install.py status  --scope user
python scripts/install.py doctor  --target . --fix

Install checksums every file it writes, so status/doctor report drift and install refuses to clobber anything edited in place without --force. Improved a skill at the target? Copy it back into skills/ and reinstall — the toolkit is the source of truth.

Using it

1. /vince-setup          once per project (or when the build changes)
2. /vince-intake         when a request may need READY / CLARIFY / BOUNCE triage
3. /vince-route          choose the exact model and narrowest agent for this harness
4. /vince-implement      for every READY task, before touching code
5. …it hands off to vince-review in a fresh context and will not report done without PASS
6. /vince-learn          at every PASS or FAIL — it gets sharper here, not just done
7. /vince-update         when a new release lands; it migrates your config, not just the files

vince-implement is a gate, not a reference sheet. Invoking it after the code is written gets you a ledger written backwards from the implementation, which is exactly the rationalisation the whole method exists to prevent.

Tiering keeps it survivable: T1 trivial (nothing user-observable) gets a stub ledger and a self-review, T2 is the full sequence, T3 (multi-repo, contracts, auth, migrations) adds confirmed, adversarial pre-code test design. Every tier gets at most one automatic review; review 2+ requires explicit user authorization. The tier changes how much evidence, never whether there is evidence.

Desktop plugin

Vince Gate 0.15.1 bundles the skills, executable Python helpers and four read-only local MCP tools as a native desktop plugin. Start with plugin installation and tools. GitHub releases include a reproducible ZIP, SHA256SUMS and release notes. Public OpenAI directory publication is separate and requires approval; this repository does not claim it is listed.

Layout

vince-gate/
  INSTALL.md                          paste-to-your-agent install guide
  USER-GUIDE.md                       start here
  skills/                             the eleven skills (+ reference/ docs)
  bindings/*.json                     one per harness; no per-harness code
  hooks/                              opt-in enforcement (Claude Code/Codex Stop hook)
  templates/                          profile, ledger, review coverage, verdict, lessons, completion doc
  scripts/install.py                  install / status / doctor / uninstall / list / bindings
  docs/                               methodology, skills, profile, harnesses, install
  .claude-plugin/                     plugin + marketplace manifests
  VERSION

Artifacts live in the project Vince is working on, never in the toolkit:

<project>/.vince/
  profile.md  lessons.md  metrics.jsonl  install.json
  tasks/active/<task-id>/    verification-ledger.md, implementation-status.md,
                             review-verdict.md, completion-documentation.md
  tasks/archive/<task-id>/

Documentation

• INSTALL.md — getting it installed: blocks you can paste to an agent, and the manual equivalents.
• CHANGELOG.md — what changed per release, and how to upgrade, pin or roll back.
• USER-GUIDE.md — first project, reading a verdict, troubleshooting, FAQ.
• docs/methodology.md — why each rule exists and the failure mode it stops.
• docs/skills.md — every phase and attack pass.
• docs/profile.md — every profile field and who reads it.
• docs/harnesses.md — the binding model; adding a runtime.
• docs/install.md — the installer CLI in full: every flag, the drift states, exit codes.

License

MIT — see LICENSE. Contributions welcome; if you verify a binding against a real runtime, promote its status and say what you confirmed.