<p align="right"><a href="https://github.com/Z-M-Huang/vcp/wiki/Home.zh">中文文档</a></p>

<div align="center">

<img src="assets/logo.png" alt="VCP Logo" width="400">

<img src="assets/hero.png" alt="VCP — Multi-AI Pipelines with Built-in Security" width="700">

VCP — Vibe Coding Protocol

Multi-AI development pipelines with built-in security enforcement.

</div>

One AI writing and reviewing its own code is like grading your own homework. VCP orchestrates multiple AI models through structured pipelines — then enforces 41 security and quality standards with real-time blocking.

<div align="center"> <img src="assets/pipeline.png" alt="Multi-AI Pipeline Orchestration" width="800"> </div>

❌ VCP Security Gate — BLOCKED:
   CWE-798: Hardcoded secret detected. Use environment variables or a secret manager.

Table of Contents

• Quick Start
• Three Plugins, One Protocol
• Why This Matters
• The Echo Chamber Problem
• Dev Buddy — Multi-AI Pipeline
• VCP — Three-Layer Enforcement
• Standards Coverage
• Organization-Wide Standards
• Configuration
• Core Philosophy
• Documentation
• How to Contribute
• Repo Structure
• References
• License

Quick Start

Prerequisites: Bun, plus either Claude Code or OpenAI Codex CLI v0.124.0+. VCP v0.6.0 supports both hosts. See the Getting Started guide for full setup.

Claude Code

# Add the VCP marketplace
/plugin marketplace add Z-M-Huang/vcp

# Install the plugin
/plugin install vcp@vcp

# Initialize your project
/vcp-init

OpenAI Codex CLI

# Clone into Codex's plugin dir
git clone https://github.com/Z-M-Huang/vcp ~/.codex/plugins/vcp
(cd ~/.codex/plugins/vcp && bun install)

# Start Codex; skills auto-load from .codex-plugin/plugin.json
codex

# Initialize your project
$vcp-init

See docs/codex-install.md for the full Codex walkthrough including MCP server registration, host capability differences, and known gaps.

That's it. Standards are injected at session start, dangerous patterns are blocked on every write, and 10 VCP skills are available on demand on either host. Claude Code invokes skills with slash commands (/vcp-audit); Codex CLI invokes them with dollar commands ($vcp-audit).

Docker

Prefer a containerized environment? VCP provides a ready-to-use Docker image with Claude Code, Codex CLI, Gemini CLI, and all dependencies pre-installed:

cd docker/
cp .env.example .env
# Edit .env with your API keys and host paths
docker compose up -d
docker exec -it vcp-docker bash

See docker/README.md for full setup instructions, volume mounts, and platform-specific configuration.

Three Plugins, One Protocol

VCP ships three complementary plugins:

Use VCP alone for standards enforcement. Add Dev Buddy when you want structured multi-AI workflows with cross-model review.

Why This Matters

<div align="center"> <img src="assets/why-vcp.png" alt="Without guardrails vs With VCP" width="800"> </div>

AI coding assistants produce code fast. They also produce code that's 2.74x more likely to contain security vulnerabilities, 40% more complex, and architecturally unsound at scale:

The death spiral: AI generates working code fast. A bug appears. AI patches the symptom, not the root cause. The patch breaks assumptions elsewhere. Each fix compounds the problem — hack on top of hack. The codebase becomes unmaintainable within months.

VCP breaks this cycle by making the AI aware of engineering principles before it writes code, not after.

The Echo Chamber Problem

<div align="center"> <img src="assets/echo-chamber.png" alt="The Echo Chamber Problem" width="800"> </div>

When a single AI family writes and reviews code, it shares the same training biases, the same blind spots, and the same failure modes. A Claude model reviewing Claude-generated code — or GPT reviewing GPT — misses the same classes of bugs because the models share architectural lineage and training distributions. Cross-model review breaks this pattern: routing code through independent models from different providers catches issues that same-family review consistently overlooks. Dev Buddy makes this practical with structured pipelines that enforce cross-model review at every stage.

Dev Buddy — Multi-AI Pipeline

<div align="center"> <img src="assets/dev-buddy-pipeline.png" alt="Multi-AI Pipeline Orchestration" width="800"> </div>

One AI writing and reviewing its own code is like grading your own homework. Dev Buddy implements a Ralph loop workflow — fresh context per iteration, specs on disk, iterate until correct. It orchestrates multiple AI models through a 6-stage pipeline with plan-lint validation, optional per-unit review, and task-based dependencies that prevent skipping stages.

The Ralph Pipeline

unit-review is an optional stage after a unit passes mechanical backpressure. When configured, it runs semantic AC verification before the unit is marked done.

Two nested loops + review gate:

• Inner (BUILD -> CODE REVIEW): per-unit Ralph loop — immutable unit-N.md specs plus persisted .vcp/plan/.state/ralph-{slug}/units/unit-N.json state, fresh context from disk, implementation, mechanical backpressure (test/typecheck/lint), contract verification, optional unit review, retry up to max_build_attempts. Code review can send units back for rework.
• Outer (UAT): integration Ralph loop — real Playwright UAT against running app. Failures identify affected units and loop back through BUILD and CODE REVIEW.
• User checkpoints after Discovery, Requirements, and Decompose — approve, reject, or provide additional context.

Enforcement Stack

Layer 1: Unit plan + contracts       <- intent, data flow traces, authoritative sources
Layer 2: Plan-lint                   <- detects already-satisfied or uncompilable unit tests before build
Layer 3: Mechanical backpressure     <- compilation, types, lint errors
Layer 4: Per-unit semantic review    <- optional AC verification after mechanical pass
Layer 5: Orchestrator verify         <- subagent lies, missing sections, source violations
Layer 6: Code review (multi-AI)      <- flow tracing, stub detection, drift probe
Layer 7: UAT (Playwright)            <- real user scenario failures
Layer 8: User checkpoint             <- everything above missed
Layer 9: TaskManagement              <- process compliance (no skipping)
Layer 10: Disk-backed JSON state     <- state survival after compaction and process restart

Quick Start

# Install dev-buddy alongside VCP
/plugin install vcp@dev-buddy

# Run the full Ralph workflow
/dev-buddy-ralph Add user authentication with JWT

# Configure pipeline stages and providers via web portal
/dev-buddy-config

On Codex CLI, use $dev-buddy-ralph, $dev-buddy-config, and the Dev Buddy MCP tools. The v0.6.0 MCP Ralph path (ralph_start/ralph_next) is wired for cross-host state transitions but its step handlers are skeletons; the legacy Claude stage-skill path remains the production Ralph workflow until those LLM step ports land.

<div align="center"> <img src="assets/real-screenshot.png" alt="Real pipeline in action — 5 concurrent reviews across MiniMax, Qwen, Kimi, GLM, Codex" width="800"> </div>

VCP — Three-Layer Enforcement

<div align="center"> <img src="assets/three-layer-enforcement.png" alt="Three-Layer Enforcement: Prevent, Scan, Block" width="800"> </div>

No single layer catches everything. Layer 1 prevents violations at the source. Layer 3 blocks the most dangerous patterns instantly. Layer 2 catches the nuanced issues through deep analysis. Together they provide defense in depth.

Layer 1: Proactive Context — Prevent Before Writing

At session start, VCP injects a compact summary of all applicable rules into the AI's context. The AI internalizes security, architecture, testing, and quality rules while it writes code — preventing violations at the source.

Run /vcp-context to re-inject rules at any time (useful after context compaction in long sessions).

Layer 2: On-Demand Scanning — Deep Analysis

Skills scan code against 41 standards across 12 scopes using AI-driven analysis:

Layer 3: Real-Time Blocking — Stop Dangerous Code Instantly

A security gate hook runs on every Write, Edit, and Bash call, blocking dangerous patterns before they reach disk:

<details> <summary><strong>21 patterns across 9 CWEs</strong> — click to expand</summary>

</details>

Coverage Backed by Industry Standards

VCP standards are mapped against authoritative security frameworks:

• OWASP Top 10:2025 — All 10 categories covered
• OWASP Agentic AI Security Top 10 (ASI) — All 10 categories covered (ASI01–ASI10)
• CWE Top 25:2024 — 19/25 covered (6 uncovered are memory-safety, out of scope for managed languages)
• OWASP API Security Top 10:2023 — All 10 categories addressed
• OWASP ASVS v5.0 — 15/17 chapters covered
• OWASP Docker Security — 11/13 controls covered

Standards Coverage

41 standards across 12 scopes:

All standards follow a consistent format: WHY (the principle), WHAT (numbered actionable rules), HOW (code examples and anti-patterns). See standards/README.md for the format specification.

Organization-Wide Standards

VCP's manifest system lets organizations enforce their own rules across all projects and developers — alongside or instead of VCP defaults.

Root Manifest (manifest.json)
├── core scope     → https://your-org.github.io/standards/scopes/core.json
│   ├── core-security.md      (VCP default)
│   ├── core-architecture.md  (VCP default)
│   └── org-coding-style.md   (your custom standard)
├── web-backend    → https://your-org.github.io/standards/scopes/web-backend.json
│   ├── web-backend-security.md   (VCP default)
│   └── org-api-conventions.md    (your custom standard)
└── org-internal   → https://your-org.github.io/standards/scopes/org-internal.json
    ├── org-logging-policy.md     (your custom standard)
    └── org-data-classification.md (your custom standard)

<details> <summary><strong>Set up for your organization</strong> — click to expand</summary>

#### 1. Create your standards

Write markdown files following the VCP format spec. Each standard has YAML frontmatter, a principle, numbered rules with code examples, and anti-patterns.

#### 2. Create scope manifests

JSON files listing your standards with severity and tags:

{
  "scope": "org-internal",
  "standards": [
    {
      "id": "org-logging-policy",
      "url": "https://your-org.github.io/standards/org-logging-policy.md",
      "severity": "high",
      "tags": ["logging", "compliance"]
    }
  ]
}

#### 3. Create a root manifest

Point to your scope manifests (include VCP defaults or replace them):

{
  "version": "2.0",
  "repository": "https://github.com/your-org/vcp-standards",
  "scopes": {
    "core": {
      "manifest": "https://your-org.github.io/standards/scopes/core.json",
      "applies": "always"
    },
    "org-internal": {
      "manifest": "https://your-org.github.io/standards/scopes/org-internal.json",
      "applies": "always"
    }
  }
}

#### 4. Point VCP to your manifest

Set the URL globally (applies to all projects) or per-project:

# Global — all projects on this machine use your org's standards
/vcp-config global set standards_url https://your-org.github.io/standards/manifest.json

# Per-project — override for a specific repo
/vcp-config set standards_url https://your-org.github.io/standards/manifest.json

</details>

What this enables:

• Consistent enforcement — Every developer using AI coding tools follows the same rules
• Mix and match — Include VCP's default standards alongside your own, or replace them entirely
• Central updates — Update a standard once, every project picks it up on next session
• Schema validation — Manifests are validated against published JSON schemas for correctness

Configuration

<details> <summary><strong>VCP uses two config files</strong> — click to expand</summary>

Manage via natural language with /vcp-config:

/vcp-config ignore core-architecture          # Suppress a standard
/vcp-config ignore core-security/rule-3       # Suppress a specific rule
/vcp-config ignore CWE-798                    # Suppress a security gate pattern
/vcp-config enable database scope             # Toggle a scope
/vcp-config add gdpr compliance               # Add a compliance framework
/vcp-config set severity to high              # Change severity threshold
/vcp-config global show                       # View global config

</details>

Core Philosophy

1. Security comes first. No feature is worth a vulnerability.
2. Architecture comes second. Every change respects the system's structure.
3. Fix the root cause, not the symptom. Trace bugs to where they originate. Break the death spiral.
4. Principled, not prescriptive. Explain WHY, not just WHAT. Allow alternatives that satisfy the principle.
5. AI-parseable. Standards are structured for machine consumption — consistent format, unambiguous rules.

Documentation

Full documentation is on the [VCP Wiki](https://github.com/Z-M-Huang/vcp/wiki):

• [Getting Started](https://github.com/Z-M-Huang/vcp/wiki/Getting-Started) — Prerequisites, installation, first scan
• [Configuration](https://github.com/Z-M-Huang/vcp/wiki/Configuration) — Scopes, compliance, severity, ignore rules
• [Skills Reference](https://github.com/Z-M-Huang/vcp/wiki/Skills-Reference) — All 10 skills with usage and examples
• [Dev Buddy Quick Start](https://github.com/Z-M-Huang/vcp/wiki/Dev-Buddy-Quick-Start) — Multi-AI pipeline setup and first run
• [Dev Buddy Configuration](https://github.com/Z-M-Huang/vcp/wiki/Dev-Buddy-Configuration) — Pipeline stages, providers, models
• [FAQ](https://github.com/Z-M-Huang/vcp/wiki/FAQ) — Common questions and troubleshooting

How to Contribute

• Report a vibe coding problem — Encountered a real issue from AI-generated code? Open a problem report. Your experience directly informs which standards we prioritize.
• Propose a new standard — Have an idea that would prevent a class of AI coding problems? Propose a standard. Review the format spec first.
• Contribute to existing standards — Pick an open issue, read the requirements, and submit a PR.

Repo Structure

<details> <summary><strong>Project layout</strong> — click to expand</summary>

vcp/
├── standards/           # 41 AI-optimized principled standards across 12 scopes
│   ├── manifest.json    # Root manifest — full HTTPS URLs, org-customizable
│   ├── scopes/          # Per-scope manifest files
│   ├── core-*.md        # Universal: security, architecture, testing, etc.
│   ├── web-*.md         # Frontend and backend web standards
│   ├── database-*.md    # Encryption, schema security
│   ├── mobile-*.md      # Credential storage, cert pinning, biometrics
│   ├── desktop-*.md     # Electron/Tauri isolation, IPC security
│   ├── cli-*.md         # Shell injection, argument injection, exit codes
│   ├── devops-*.md      # Containers, CI/CD, IaC, Kubernetes
│   ├── agentic-ai-*.md  # Agent security, tool security, permissions, supply chain, communication
│   └── compliance-*.md  # GDPR, PCI DSS, HIPAA, Accessibility
├── schemas/             # JSON schemas for config and manifest validation
├── plugins/vcp/         # VCP plugin — 10 skills, 1 agent, 4 hooks, MCP prompts/resources/tools
├── plugins/dev-buddy/   # Dev Buddy plugin — 11 skills, 8 stage defs, 7 role prompts, MCP Ralph skeleton
├── plugins/mcp-doc/     # mcp-doc plugin — 5 skills, MCP Doc guidance server
├── docker/              # Docker image — Claude Code, Codex CLI, Gemini CLI
└── .claude-plugin/      # Claude Code marketplace manifest

</details>

References

Research

• CodeRabbit — State of AI vs Human Code Generation (Dec 2025) — 2.74x vulnerability rate across 470 PRs
• GitClear — AI Copilot Code Quality 2025 — 211M lines, 4x growth in code clones
• Veracode — 2025 GenAI Code Security — 45% AI code has security vulnerabilities
• CMU — Speed at the Cost of Quality (arXiv 2511.04427) — 40.7% complexity increase
• Spracklen et al. — Package Hallucinations (USENIX Security 2025) — 205,474 hallucinated package names

Frameworks

• OWASP Top 10:2025 — OWASP ASVS v5.0 — OWASP API Security Top 10:2023 — CWE Top 25:2024 — OWASP Agentic AI Security Top 10 (Dec 2025)

License

Apache License 2.0