An evidence-first review skill for Codex and Claude Code: audit an AI-assisted change, review the repair plan, approve a scoped batch, fix and retest.
Quick start · Download v0.1.0-rc2 ZIP · Sample report · 40-second demo · Workflow · Validation · Contribute
AI can write the change. Make it show the evidence.
Vibe Code Guardian is an Agent Skill that supervises AI-assisted software changes. It turns “check this code” into a scoped audit, a concrete remediation plan, approved repairs and retesting that records what actually happened.
It is built for developers who want useful scrutiny without treating a green build or a confident agent summary as proof of security.
- A review that fits the change. Classify 34 conditional scan/test packs, then select relevant subchecks. Do not launch 34 tools by default.
- Findings you can act on. Require a reachable path or violated invariant, evidence, impact and a false-positive check. Preserve uncertainty when proof is missing.
- A repair plan before application edits. Each actionable finding gets ordered steps, prerequisites, verification, stop conditions and recovery.
- Honest closure. Keep proposed, implemented-but-unverified and verified fixes separate. Preserve the first failure; retest both the failing path and legitimate behavior.
- Explicit evidence boundaries. Source review, isolated runtime, browser, native host and production observations remain distinct.
The catalog retains traceability to the original 20 requirements, with additional protocol, supply-chain, runtime and agent-trust checks. Its detailed baseline is web/API; specialist targets need specialist evidence.
-
Download the pinned v0.1.0-rc2 ZIP and extract it. Read the included
SKILL.mdbefore installation. The repository copy is also available to browse. -
Copy the complete extracted skill directory (the folder containing
SKILL.md,references/,scripts/,assets/andevals/) into your project's host-specific location. If you downloaded the repository instead, copyskills/vibe-code-guardian/:Host Project-local destination Explicit invocation Codex .agents/skills/vibe-code-guardian/$vibe-code-guardianClaude Code .claude/skills/vibe-code-guardian//vibe-code-guardian -
Confirm that your host discovers the skill. Availability, invocation and permission controls depend on the actual host/version; see host guidance.
-
Start with a review:
Use vibe-code-guardian to review this change. Do not edit the application.
Focus on the account-export endpoint: an authenticated user must never
export another tenant's records. Use synthetic data and mock external effects.
Produce AUDIT-REPORT.md and REMEDIATION-MASTER-PLAN.md. State what you
could not verify, propose concrete fixes, and wait for scoped approval.
This is a sample task, not a claim that your endpoint has been tested. No scanner is automatically installed or launched.
| Step | Reviewable result |
|---|---|
| 1 · Audit | Freeze target, scope and acceptance criteria; inspect applicable risks and substantiate findings. |
| 2 · Plan | Deliver AUDIT-REPORT.md and REMEDIATION-MASTER-PLAN.md, including unexecuted checks and recovery. |
| 3 · Approve | Review a specific plan/revision/target and select the permitted batch. |
| 4 · Fix | Revalidate the target and apply only the authorized changes. |
| 5 · Retest | Replay the original failure, exercise legitimate paths and record actual effects and remaining gaps. |
A genuine native confirmation control can be used when the host exposes it and permits approval requests. Otherwise, use an explicit user command identifying the reviewed plan and batch. Silence, a preselected option, a file or a child agent cannot approve. Existing unambiguous scoped approval does not need to be requested again.
Results distinguish PASS, FAIL, NOT_RUN, UNKNOWN and evidenced NOT_APPLICABLE. The final decision is BLOCKED, INSUFFICIENT_EVIDENCE or READY_WITHIN_DECLARED_SCOPE. Readiness applies only to the declared review scope and does not authorize deployment.
Optional real agents: request independent audit lanes when the host supports them and the work benefits from them. One coordinator owns integration and writes. Separate agent contexts are required for independence; sequential fallback is labeled honestly.
The Python 3 standard-library helper validates a caller-redacted JSON record against the exact schema and renders both reports. From the skill directory, using a fresh output directory:
python -X utf8 scripts/audit_bundle.py --input assets/run.example.json --output-dir REVIEW_OUTPUT --as-of 2026-10-31
The example is synthetic. The helper checks record consistency; it does not scan your application, run repair commands, authenticate evidence or grant approval. Never supply raw secrets.
Browse the generated audit report, remediation master plan and their synthetic JSON input. These files were actually rendered by the local helper with a fixed decision date; the example notes show the reproducible command and limits. The seeded required failure correctly leaves the decision BLOCKED.
Open the self-contained 40-second workflow storyboard in a browser after downloading the repository. It illustrates audit → plan → approve → fix → retest using that record. The later steps are proposed workflow instructions: no real scan, approval, repair, retest, model or production run is shown. GitHub displays the HTML source; download and open it locally to play the demo.
0.1.0-rc2 is the first public prerelease. Its runtime core and helper are preserved from the tested RC1 candidate; the release changes metadata and public documentation. See release notes.
| Layer | Recorded status |
|---|---|
| Helper / fixture checks | 40 helper tests and 28 fixture-integrity checks passed at the unchanged RC1 candidate. |
| Codex behavior acceptance | Accepted within declared profiles: 38 cases, 91 frozen assertions satisfied. |
| Claude-native acceptance | Native discovery, explicit/implicit Skill activation, two completed read-only agents and automatic Write-denial observed; human approval UI unperformed in headless mode. |
| Other hosts / production assurance | Not established. |
Acceptance retains historical process timeouts, an initial Claude report-budget failure followed by one accepted compact-report correction, and technical NOT_RUN controls. Some behavior assertions pass by accurately reporting missing capability; that does not pass the underlying security control. The curated validation summary records scope and limits.
This skill does not provide OS isolation, universal scanner coverage, security certification or a zero-defect guarantee. Evaluate it on your own authorized target.
skills/vibe-code-guardian/ Portable skill, references, helper and evaluations
docs/workflow.md Workflow and approval guide
docs/validation-summary.md Curated results and evidence limits
docs/examples/ Helper-rendered synthetic reports and input
docs/demo.html Self-contained illustrative workflow demo
assets/hero.svg Original repository artwork
assets/social-preview.svg 1280 × 640 repository preview artwork
Contributions: CONTRIBUTING.md. Vulnerabilities: SECURITY.md. Licensed under MIT.