Custom Packs

Beyond the 5 built-in vertical packs, you can create your own packs to encode your organization's engineering standards, tech stack decisions, or client-specific requirements. Custom packs work identically to built-in packs.

Creating a pack

Via CLI

vyb init --pack custom --name my-org-standards

This scaffolds .vyb/packs/my-org-standards.yaml with a complete template.

Manually

Create .vyb/packs/my-pack.yaml directly:

.vyb/packs/my-pack.yaml

pack:
  id: my-pack
  name: My Organization Standards
  version: 1.0.0
  description: Engineering constraints for My Org.
  author: engineering@myorg.com

categories:
  security:
    rules:
      - id: my-sec-001
        name: no-eval
        severity: block
        pattern: "\\beval\\s*\\("
        remediation: Use JSON.parse() instead of eval().

Referencing your pack in spec.yaml

After creating the pack file, reference it from your spec:

.vyb/spec.yaml

spec:
  version: 1
  project: my-project
  extends: .vyb/packs/my-pack.yaml

Or apply it via:

vyb init --pack my-pack

Emitting a distributable pack from your spec

If you have already built up rules in your spec and want to package them:

vyb pack --emit --name my-org-standards

This reads your current .vyb/spec.yaml, strips project-specific metadata, and writes a distributable pack YAML to .vyb/packs/my-org-standards.yaml.

vyb pack --emit --name my-org-standards --version 2.0.0

Add --version to set the semantic version explicitly.

Publishing to npm

For organizations with multiple repos, publishing the pack to npm gives every project a versioned, auto-updateable dependency.

# In your standards repo:
npm init -y
cp .vyb/packs/my-org-standards.yaml pack.yaml

package.json (standards repo)

{
  "name": "@my-org/vyb-standards",
  "version": "1.0.0",
  "description": "My Org engineering constraint pack for vybdocs",
  "main": "pack.yaml",
  "files": ["pack.yaml"],
  "keywords": ["vybdocs", "vyb-pack"],
  "license": "UNLICENSED"
}

npm publish --access restricted

In consuming projects:

npm install --save-dev @my-org/vyb-standards
vyb init --pack @my-org/vyb-standards

Version management

Bumping versions

Follow semantic versioning:

Change	Version bump	Example
New rule at info or warn	Patch	1.0.0 → 1.0.1
New rule at block	Minor	1.0.0 → 1.1.0
Existing rule promoted to block	Minor	1.0.0 → 1.1.0
Rules removed or restructured	Major	1.0.0 → 2.0.0

Release candidates for breaking changes

Before promoting a rule to block:

# Publish RC
npm version 1.1.0-rc.1
npm publish --tag rc

# Teams test with:
npm install --save-dev @my-org/vyb-standards@rc
vyb check --dry-run

# After cleanup sprint, promote:
npm version 1.1.0
npm publish

Pack inheritance

Packs can extend other packs:

.vyb/packs/my-org-standards.yaml

pack:
  id: my-org-standards
  name: My Org Standards
  version: 1.0.0
  extends: "@vybdocs/eu-fintech"    # built on top of eu-fintech

categories:
  # Additional org-specific rules on top of eu-fintech:
  frontend:
    rules:
      - id: my-fe-001
        name: no-direct-dom
        severity: warn
        pattern: "document\\.getElementById"
        remediation: Use React refs.

Inheritance is single-level. Circular references are rejected.

Listing applied packs

vyb pack --list

Output:

Applied packs:
  eu-fintech            v2.1.0  (built-in)
  my-org-standards      v1.3.0  (.vyb/packs/my-org-standards.yaml)

Rules:
  Total:   47
  Enabled: 45
  Block:   18
  Warn:    24
  Info:    3

Inspecting a pack

vyb pack --inspect my-org-standards

Shows every rule in the pack with its current effective severity (after any local overrides from the spec).

---

Next: Claude Desktop MCP