VibeOps

The Problem

Same prompt. Two outcomes.

The difference between high-quality and low-quality agentic output isn't the model. It's the environment.

Without VibeOps

With VibeOps

Agent guesses the package manager

Agent reads AGENTS.md, uses uv

Hardcoded secrets, weak hashing

Pydantic Settings, bcrypt, env-driven config

Tests deleted to pass CI

Tests protected — code fixed instead

Logic dumped into routers

Layered architecture enforced

Same mistakes repeated every session

Environment learns and self-updates

Framework Architecture

Four Primary Contributions

Composable layers that together form a complete governance system for agentic coding environments.

I

Contribution I · Environment Contract

`AGENTS.md`

A structured, version-controlled configuration file governing agent behaviour at the repository level. The agent's onboarding document, constraint system, and tribal knowledge base — all in one file. It gives agents the context senior engineers carry in their heads.

# Section 5 — Hard Constraints NEVER delete tests to make CI pass. NEVER commit secrets or API keys. NEVER use synchronous I/O in async routes. # Section 2 — Build Commands $ uv run pytest tests/ -v --cov $ uv run ruff check . && mypy src/ # Section 9 — Tribal Knowledge SQLAlchemy sessions must be closed explicitly. Alembic autogenerate misses partial indexes.

II

Contribution II · Methodology Layer

Agent Skills

A portable methodology layer encapsulating reusable engineering knowledge as composable skill modules. Unlike configuration — which is repository-specific — Agent Skills travel across codebases. They encode how a team thinks about problem-solving, not just what tools they use. This is the essence of Factor VIII.

III

Contribution III · Evaluation Framework

VibeEvals

A multi-dimensional evaluation framework treating development sessions as controlled experiments with separable parameters and metrics. VibeEvals moves teams beyond subjective gut-feel toward reproducible, measurable assessments of agent performance — quantified via the Vibecheck Score.

IV

Contribution IV · Design Principles

The 12 Vibing Factors

An opinionated set of design principles for governed AI-assisted development. Inspired by the Twelve-Factor App methodology, the 12 Vibing Factors provide a canonical checklist for teams building and operating agentic coding environments — from reproducibility to observability.

Measurement

The Vibecheck Score

A leading indicator of environment quality — computed before a line of code is written. The higher the score, the smaller the gap between your best engineer and your newest one.

$ uv run vibecheck .

─────────────────────────────

Vibecheck Score: 0.91

─────────────────────────────

├──Security:1.00 ✓

├──Architecture:0.88 ✓

├──Testing:0.91 ✓

├──Compliance:0.85 ~

└──Process:0.94 ✓

─────────────────────────────

Coming in Phase 3. Tracked via MLflow in Phase 4.

The 12 Vibing Factors

Principles for Governed AI-Assisted Development

A canonical checklist for engineering teams operating agentic coding environments at scale.

Factor I

Environment Contract

AGENTS.md as single source of truth

Factor II

Version Control

All agent config tracked in Git

Factor III

Declarative Configuration

Explicit over implicit instructions

Factor IV

Skill Portability

Reusable methodology across repos

Factor V

Bounded Execution

Clear always / ask first / never model

Factor VI

Reproducibility

Sessions as reproducible experiments

Factor VII

Architecture Alignment

Measure distance from blueprint

Factor VIII ★

Methodology / Config Separation

Methodology travels. Configuration stays.

Factor IX

Observability

Session logs as behavioural signals

Factor X

Iterative Environment Design

Environments improve through experimentation

Factor XI

Team Ownership

Config is team property, not individual

Factor XII

Human Governance

Agents operate within human-defined bounds

Factor VIII · The Canonical Principle

"Methodology travels. Configuration stays."

Agent Skills encode how your team thinks — problem decomposition, testing philosophy, code style. These travel across every repository. AGENTS.md encodes what your repository is — its stack, conventions, hard constraints, and tribal knowledge. These stay put. Conflating the two is the most common governance failure in agentic environments.

Living System

AGENTS.md learns from every session

VibeOps environments don't require manual maintenance. They are designed to improve themselves.

The Self-Updating Protocol

When the agent discovers something worth capturing — a gotcha, a missing rule, a pattern — it proposes an update. You approve. The file is updated. The change is logged. Every session makes the environment stronger. This is not a file you maintain — it is a file that learns.

# Agent discovers something in session → "I suggest adding this to AGENTS.md — Section 9: SQLAlchemy async sessions must be explicitly closed in exception branches, or connections leak silently." # Engineer reviews and approves → git add AGENTS.md git commit -m "agents: add session cleanup gotcha (session 2026-03-14)" # Next agent session inherits the fix automatically.

Reference Implementation

fastapi-vibeops-template

Not a minimal starter. A fully primed VibeOps environment — showing what maturity looks like in practice. The AGENTS.md is the product.

Phase 0AGENTS.md + repo structure — the environment contractDone ✓

Phase 1Working FastAPI skeleton with auth, Pydantic Settings, layered architectureIn progress

Phase 2Full todo app — spec → Gherkin (BDD) → implementationPlanned

Phase 3Vibecheck Score CLI — uv run vibecheck .Planned

Phase 4MLflow experiment integration — track Vibecheck Score over timePlanned

Phase 5Self-optimising AGENTS.md via DSPyFuture

Quickstart

From clone to governed agent in 5 minutes

Configure your agent. Clone the template. Prompt your app. Watch governance kick in.

STEP 01

Configure your code agent

Claude Code reads CLAUDE.md automatically. Cursor: add one line to .cursorrules. Any tool: paste AGENTS.md into your system prompt. One rule: read it before doing anything.

STEP 02

Clone the template

Ships with AGENTS.md pre-written — architecture, conventions, hard constraints, and the Feature Kickoff Protocol. Open it. It's the most important file in the repo.

STEP 03

Fire up your agent

Open the project in your tool of choice and start a session. Your agent now knows the stack, the patterns, the constraints — without you having to repeat yourself.

STEP 04

Prompt your app

Say: "New feature: user registration and JWT auth" — and watch what a governed agent does differently.

# Use the template (creates a fresh repo — no git history)
gh repo create my-project --template vibeops-central/fastapi-vibeops-template
# or click "Use this template" on GitHub ↗

# Open in your agent and start a session, then prompt:
# "New feature: user registration and JWT auth"

# A governed agent responds:
# → Entering design mode. No code yet.
# → Producing specs/auth.md
# → Producing tests/bdd/features/auth.feature
# → "Reply proceed to begin implementation."

Get the template ↗ Full walkthrough on DEV.to ↗

Works with: Claude Code · Cursor · Windsurf · Copilot · any agent with a system prompt

Same prompt. Two outcomes.

Four Primary Contributions

AGENTS.md

Agent Skills

VibeEvals

The 12 Vibing Factors

The Vibecheck Score

Principles for Governed AI-Assisted Development

AGENTS.md learns from every session

The Self-Updating Protocol

fastapi-vibeops-template

From clone to governed agent in 5 minutes

VibeOps: A Governance and Optimisation Framework for Agentic Coding Environments

`AGENTS.md`