Configuration

Configuration

VCP is configured via a .vcp/config.json file in your project root. This file is created by /vcp-init and read by all VCP skills and hooks.

Use /vcp-config to view and modify your configuration via natural language commands (e.g., /vcp-config ignore core-architecture, /vcp-config enable database scope). See the Skills Reference for the full list of supported commands.

Global Configuration

VCP supports a global configuration file at ~/.vcp/config.json that provides machine-wide constants and defaults. This file is created by /vcp-init the first time you run it.

Location

~/.vcp/config.json

Schema

https://raw.githubusercontent.com/Z-M-Huang/vcp/main/schemas/vcp-global.schema.json

Fields

standards_url (required)

URL to the VCP standards manifest. Points to the root manifest.json file.

"standards_url": "https://raw.githubusercontent.com/Z-M-Huang/vcp/main/standards/manifest.json"

pluginRoot (required)

Absolute path to the VCP plugin installation directory.

"pluginRoot": "/home/user/.claude/plugins/vcp"

debug (optional)

Enable diagnostic logging to .vcp/vcp.log in the project root. When true, all hooks write timestamped log entries recording what they checked and decided. When false (the default), no log file is generated.

"debug": false

Use /vcp-config global set debug true to enable, or edit ~/.vcp/config.json directly.

defaults (optional)

Machine-wide defaults. At runtime, only severity and ignore are applied — severity is used when a project omits it, and ignore entries are merged (union) with the project's list. The scopes and compliance defaults are only used as starting points when /vcp-init creates a new project config — they are not applied at runtime because both are required fields in .vcp/config.json.

"defaults": {
  "severity": "medium",
  "scopes": {
    "web-frontend": false,
    "web-backend": false,
    "database": false
  },
  "compliance": [],
  "ignore": []
}

Full Example

{
  "$schema": "https://raw.githubusercontent.com/Z-M-Huang/vcp/main/schemas/vcp-global.schema.json",
  "standards_url": "https://raw.githubusercontent.com/Z-M-Huang/vcp/main/standards/manifest.json",
  "pluginRoot": "/home/user/.claude/plugins/vcp",
  "debug": false,
  "defaults": {
    "severity": "high",
    "scopes": {
      "web-frontend": true,
      "web-backend": true,
      "database": false,
      "mobile": false,
      "desktop": false,
      "cli": false,
      "devops": false
    },
    "compliance": ["gdpr"],
    "ignore": ["CWE-117"]
  }
}

Config Resolution

VCP resolves configuration from two sources: the global config (~/.vcp/config.json) provides machine constants and defaults, while the project config (.vcp/config.json) provides per-project overrides.

Field	Resolution Order	Notes
standards_url	Project → Global → Not available	Project config can override the global standards URL
pluginRoot	Project → Global → Not available	Project config takes precedence (set by /vcp-init)
severity	Project → Global default → "medium"	Falls back to hardcoded "medium" if neither config specifies
scopes	Project wins entirely	No merge — project config replaces global defaults completely
compliance	Project wins entirely	No merge — project config replaces global defaults completely
ignore	Union of global default + project	Only field that merges — combines both lists

Important: The ignore field is the only field that merges. If the global config has ["CWE-117"] and the project config has ["core-architecture"], the final ignore list is ["CWE-117", "core-architecture"].

Schema

The configuration conforms to the JSON schema at:

https://raw.githubusercontent.com/Z-M-Huang/vcp/main/schemas/vcp.schema.json

Fields

version (required)

Always "1.0".

"version": "1.0"

standards_url (optional)

URL to the VCP standards manifest. Overrides the global config's standards_url if specified.

"standards_url": "https://raw.githubusercontent.com/your-fork/vcp/custom-branch/standards/manifest.json"

Rarely needed. Most projects should rely on the global config's standards_url instead of setting this per-project. Only override this if you need to pin a specific project to a custom standards fork or branch.

scopes (required)

Object declaring which VCP scopes apply to your project. Each scope enables additional standards beyond the core set.

"scopes": {
  "web-frontend": true,
  "web-backend": true,
  "database": false
}

Scope	Standards Enabled	When to Use
web-frontend	Frontend security, structure, performance, accessibility	Project has client-side web code (React, Vue, Svelte, etc.)
web-backend	Backend security, structure, data access, API design, realtime, caching	Project has server-side web code (Express, Django, FastAPI, etc.)
database	Database encryption, schema security	Project interacts directly with databases
mobile	Mobile security, platform configuration	Project targets mobile platforms (React Native, Flutter, Swift, Kotlin)
desktop	Desktop application security	Project builds desktop apps (Electron, Tauri)
cli	CLI security and quality	Project is a command-line tool
devops	Container, CI/CD, IaC, Kubernetes security	Project has infrastructure/deployment config

Core standards (security, architecture, quality, error handling, testing, dependency management, root cause analysis) are always active regardless of scope settings.

compliance (required)

Array of compliance frameworks that apply to your project. Leave empty if none apply.

"compliance": ["gdpr", "pci-dss"]

Value	Standard Enabled
"gdpr"	GDPR & CCPA/CPRA — Data deletion, retention, consent, PII handling
"pci-dss"	PCI DSS v4.0 — Tokenization, card masking, CDE isolation
"hipaa"	HIPAA — PHI encryption, audit logging, retention, minimum necessary
"accessibility"	Accessibility Compliance — ADA, Section 508/504, EAA, PSBAR, AODA, ACA, EN 301 549, WCAG conformance mapping

frameworks (optional)

Array of framework names detected in your project. Used by /vcp-dependency-check to determine which package ecosystem to check.

"frameworks": ["react", "express", "postgresql"]

exclude (optional)

Array of glob patterns for paths to skip during scanning. The patterns node_modules/** and .git/** are always excluded regardless of this setting.

"exclude": [
  "node_modules/**",
  "dist/**",
  "build/**",
  "coverage/**",
  "*.min.js"
]

severity (optional)

Minimum severity threshold for reporting findings. Only findings at or above this level are included in scan results.

"severity": "medium"

Value	Reports
"critical"	Critical only
"high"	Critical + High
"medium" (default)	Critical + High + Medium
"low"	All findings

ignore (optional)

Array of entries to suppress. Supports three formats:

"ignore": [
  "core-architecture",
  "core-security/rule-3",
  "CWE-798"
]

Format	Example	Effect
Standard ID	"core-architecture"	Suppresses the entire standard — no rules from it are checked
Rule reference	"core-security/rule-3"	Suppresses a single rule from a specific standard
CWE pattern	"CWE-798"	Suppresses the security gate pattern for that CWE

Important: When security-scoped standards or compliance standards are suppressed, skills will display a warning:

WARNING: Critical security findings suppressed by ignore config. Review .vcp/config.json ignore list.

Most projects should start with an empty ignore list. Add entries only when you have a specific, justified reason to suppress a rule.

pluginRoot (optional)

Absolute path to the VCP plugin installation directory. Set automatically by /vcp-init — you should not edit this manually.

"pluginRoot": "/home/user/.claude/plugins/vcp"

This path is validated by all skills before use:

• Must be an absolute path
• Must contain /.claude/ (or \.claude\ on Windows)
• Must not contain shell metacharacters
• Must contain the marker file lib/vcp-context-core.ts

Full Example

{
  "$schema": "https://raw.githubusercontent.com/Z-M-Huang/vcp/main/schemas/vcp.schema.json",
  "version": "1.0",
  "scopes": {
    "web-frontend": true,
    "web-backend": true,
    "database": true
  },
  "compliance": ["gdpr", "pci-dss"],
  "frameworks": ["react", "express", "postgresql", "prisma"],
  "exclude": [
    "node_modules/**",
    "dist/**",
    "build/**",
    "coverage/**",
    "migrations/**"
  ],
  "severity": "medium",
  "ignore": [
    "core-architecture/rule-5"
  ],
  "pluginRoot": "/home/user/.claude/plugins/vcp"
}

How Ignore Filtering Works

Before processing, ignore entries from the global config's defaults.ignore and the project's .vcp/config.json ignore field are merged (union) to create the final ignore list.

Ignore entries are then processed at three levels:

1. Standard-level filtering (in resolve-config.ts) — Entire standards matching an ignore entry are removed from the applicable standards list before skills fetch them. This means the standard's rules are never even loaded.

2. Rule-level filtering (in skills and vcp-context-core.ts) — Individual rule references like "core-security/rule-3" are filtered after rules are extracted. The standard is still loaded, but the specific rule is suppressed.

3. CWE-level filtering (in security-gate.ts) — CWE patterns like "CWE-798" disable the corresponding real-time blocking pattern in the security gate hook.

Version Control

.vcp/config.json should be committed to your repository so all team members use the same configuration. The pluginRoot field will differ per machine but is resolved at runtime by /vcp-init.