vibe-engineering

38 engineering discipline skills for Claude Code & OpenAI Codex + a CLI for CI/CD enforcement. Extracted from real-world multi-agent system development — not theoretical best practices, but patterns that survived 3 weeks of intensive production development with 205+ test files, 11 agents, and 50+ session observations.

"Vibe coding" meets engineering rigor. Every skill here exists because skipping it caused real pain.

Two commands. Instant engineering discipline.

/plugin marketplace add ash1794/vibe-engineering
/plugin install vibe-engineering@vibe-plugins

Claude automatically discovers and applies the right skill for every task — research before design, quality gates before shipping, structured debugging before guessing, test coverage before claiming "done."

What is this?

A skill collection for Claude Code and OpenAI Codex with 38 skills that enforce engineering discipline across any project, plus a lightweight CLI (vibe-cli) for CI/CD pipelines and automation:

• Research & Decision-Making (5 skills) — Think before building
• Quality Gates & Validation (7 skills) — Catch issues before they ship
• Learning & Knowledge Management (5 skills) — Never solve the same problem twice
• Parallel & Multi-Agent Development (4 skills) — Scale your work safely
• Testing Patterns (5 skills) — Test what matters, not just what's easy
• Deployment & Operations (4 skills) — Ship with confidence
• Gap Analysis & Remediation (2 skills) — Audit and systematically close gaps
• Communication & Process (4 skills) — Stay focused, stay clear
• Meta Skills (2 skills) — Skill discovery and routing

Installation

Claude Code

From inside a Claude Code session:

# 1. Add the marketplace (one-time)
/plugin marketplace add ash1794/vibe-engineering

# 2. Install the plugin
/plugin install vibe-engineering@vibe-plugins

Later, pull updates with /plugin marketplace update vibe-plugins.

Local development (unpackaged, for testing plugin changes):

git clone https://github.com/ash1794/vibe-engineering.git
claude --plugin-dir ./vibe-engineering/plugins/vibe-engineering

All 38 skills are now available in every Claude Code session.

OpenAI Codex

Clone the repo anywhere, then symlink the plugin's skills/ directory into .agents/skills/ so Codex can discover the individual skill folders:

# Clone once, symlink many times
git clone https://github.com/ash1794/vibe-engineering.git ~/src/vibe-engineering

# User-wide (available in all projects)
mkdir -p ~/.agents/skills
ln -s ~/src/vibe-engineering/plugins/vibe-engineering/skills/* ~/.agents/skills/

# Or per-project
mkdir -p .agents/skills
ln -s ~/src/vibe-engineering/plugins/vibe-engineering/skills/* .agents/skills/

Codex discovers skills from .agents/skills/ automatically. Each skill's SKILL.md frontmatter drives implicit matching.

Quick Start

After installation, Claude automatically discovers vibe-engineering skills. The bootstrap skill teaches Claude to check for applicable skills before every action.

Explore available skills interactively:

/vibe-engineering:vibe-help

Invoke any skill directly:

# Claude Code
/vibe-engineering:vibe-quality-loop
/vibe-engineering:vibe-research-before-design

# Codex
$vibe-quality-loop
$vibe-research-before-design

CLI: vibe-cli

The vibe-cli CLI wraps critical skills into CI/CD-friendly commands with proper exit codes and JSON output. No dependencies — pure bash.

Setup

# Make it available system-wide (optional)
ln -s $(pwd)/scripts/vibe-cli /usr/local/bin/vibe-cli

# Or run directly from the repo
./scripts/vibe-cli help

Commands

vibe-cli pre-commit          # Scan staged changes for secrets, debug code, disabled tests
vibe-cli coverage            # Run test coverage and report against tier targets
vibe-cli spec-drift          # Detect spec-code drift from staged changes
vibe-cli decisions           # Extract decisions from staged diff
vibe-cli validate            # Validate skill files and manifests
vibe-cli hook install        # Install as git pre-commit hook
vibe-cli hook uninstall      # Remove git pre-commit hook

Exit Codes

JSON Output

Every command supports --json for machine-readable output:

vibe-cli pre-commit --json
# {"status":"fail","blockers":1,"warnings":3,"findings":[...]}

vibe-cli coverage --json --spec docs/spec.md
# {"status":"pass","tool":"pytest","line_coverage":85,"spec_to_test":{"total":12,"covered":8}}

vibe-cli spec-drift --json --spec docs/spec.md
# {"status":"drift_detected","drift_items":3,"spec":"docs/spec.md","items":[...]}

vibe-cli decisions --json
# {"status":"decisions_found","count":4,"files_changed":7,"decisions":[...]}

CI/CD Integration

GitHub Actions:

- name: Vibe pre-commit check
  run: ./scripts/vibe-cli pre-commit --json

- name: Coverage check
  run: ./scripts/vibe-cli coverage --spec docs/spec.md

GitLab CI:

vibe-checks:
  script:
    - ./scripts/vibe-cli pre-commit
    - ./scripts/vibe-cli coverage --spec docs/spec.md

Pre-commit hook (automatic):

# Install once — blocks commits with secrets, debug code, etc.
./scripts/vibe-cli hook install

Environment Variables

The Spec-Code-Test Loop

Four skills form a connected workflow that keeps spec, tests, and code in sync:

Code changes
    ↓
vibe-decision-journal ──→ Extract decisions from diffs
    ↓
vibe-spec-sync ──→ Update spec to reflect approved decisions
    ↓
vibe-adversarial-test-generation ──→ Generate spec-driven tests with req:ID traceability
    ↓
vibe-coverage-enforcer ──→ Verify 3 dimensions (line + spec-to-test + spec-to-code)
    ↓
vibe-spec-vs-code-audit ──→ Final verification: no remaining gaps

The CLI exposes the critical parts for automation:

• vibe decisions → extract decisions from staged changes
• vibe spec-drift → detect spec-code drift
• vibe coverage → verify all coverage dimensions
• vibe pre-commit → block commits with secrets/debug code

Skill Catalog

Meta Skills

Research & Decision-Making

Quality Gates & Validation

Learning & Knowledge Management

Parallel & Multi-Agent Development

Testing Patterns

Deployment & Operations

Gap Analysis & Remediation

Communication & Process

Why vibe-engineering?

Without discipline skills, AI coding assistants make the same mistakes humans do — skip research, ship without tests, rationalize shortcuts, lose context across sessions. vibe-engineering catches these patterns automatically.

Design Principles

1. Born from pain, not theory — Every skill exists because skipping it caused real problems
2. When to use AND when NOT to use — Every skill has explicit triggers and anti-triggers
3. Composable — Skills work independently or together
4. Advisory first, enforcement when it matters — Skills guide; CLI enforces in CI/CD
5. Cross-project — No project-specific assumptions. Works with any language/framework

How It Works

The repo is a Claude Code marketplace (vibe-plugins) that ships one plugin (vibe-engineering), which doubles as a Codex skill collection. The same SKILL.md files are consumed by both platforms:

• Claude Code: .claude-plugin/marketplace.json at the repo root catalogs the plugin; the plugin itself lives in plugins/vibe-engineering/ with its own .claude-plugin/plugin.json
• Codex: .agents/skills/ symlinks into the plugin's skills/ directory; Codex discovers skills from this standard path

vibe-engineering/                          # repo root = marketplace root
├── .claude-plugin/
│   └── marketplace.json                   # marketplace: "vibe-plugins"
├── plugins/
│   └── vibe-engineering/                  # plugin root
│       ├── .claude-plugin/plugin.json     # plugin: "vibe-engineering"
│       └── skills/                        # 38 skill definitions
│           ├── vibe-help/SKILL.md
│           ├── quality-loop/SKILL.md
│           ├── spec-sync/SKILL.md
│           ├── decision-journal/SKILL.md
│           ├── gap-analysis/SKILL.md
│           └── ... (33 more)
├── .agents/
│   └── skills → ../plugins/vibe-engineering/skills  # Codex discovery (symlink)
├── AGENTS.md                              # Codex project instructions
├── references/
│   └── codex-tools.md                     # Tool name mapping across platforms
├── scripts/
│   ├── vibe-cli                           # CLI for CI/CD enforcement
│   └── validate-skills.sh                 # Skill file validator
└── README.md

Each skill has:

• YAML frontmatter with name, description, and invocation config
• When to Use — explicit triggers
• When NOT to Use — anti-triggers to prevent misapplication
• Steps — the actual workflow
• Output Format — structured output template

Contributing

Found a pattern that keeps saving you? Turn it into a skill:

1. Fork this repo
2. Create plugins/vibe-engineering/skills/your-skill-name/SKILL.md
3. Follow the template (see any existing skill)
4. Include: When to Use, When NOT to Use, Steps, Output Format
5. Submit a PR

Skill Template

---
name: vibe-your-skill-name
description: Performs [action] for [context]. Use when [trigger condition].
user-invocable: true
---

# vibe-your-skill-name

[One paragraph explaining the problem this skill solves]

## When to Use This Skill
- [Trigger 1]
- [Trigger 2]

## When NOT to Use This Skill
- [Anti-trigger 1]
- [Anti-trigger 2]

## Steps
1. [Step 1]
2. [Step 2]

## Output Format
[Template for structured output]

Origin Story

These skills were extracted from building an 11-agent personal assistant system with Go backend, React Native frontend, and 205+ test files.

The numbers:

• 50+ session observations analyzed (310k+ tokens of development history)
• 15 project-specific skills generalized into 38 universal patterns
• 3 weeks of intensive multi-agent development
• Every skill represents a pattern that emerged from real pain — not a theoretical best practice document

Also Check Out

• bart-coaching — Growth-oriented coaching hooks for Claude Code. Provides real-time technical depth insights, operational maturity nudges, and behavioral self-awareness mirrors with compound reflections across sessions. Pairs well with vibe-engineering for engineers who want both discipline tools and growth feedback.

License

MIT — Use it, fork it, make it yours.