dbv-specs-ops is a lightweight engineering system designed to maximize software quality and context persistence in AI-assisted development. It acts as a master blueprint that transforms your AI assistant from a simple code generator into a Senior Software Engineer that follows rigorous, repeatable processes — before writing a single line of code.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/davidbuenov/dbv-specs-ops/llms.txt
Use this file to discover all available pages before exploring further.
The Problem: Vibe Coding vs. Engineering Discipline
Most developers using AI assistants today engage in what the industry calls vibe coding: describing a feature loosely, accepting whatever the AI produces, and iterating in an unstructured loop. The result is code that works in demos but accumulates hidden technical debt, lacks specifications, and breaks when context switches between sessions. dbv-specs-ops replaces that pattern with Spec-Driven Development (SDD) — a methodology where the AI must understand the why and what before touching the how. Requirements are formalized, plans are reviewed and approved, and every phase gate is explicit. The AI is no longer a genie you prompt; it becomes a disciplined colleague that follows a process.The Harness Equation
The framework is grounded in a principle from agentic engineering research:Agent = Model (10%) + Harness (90%)The model — Claude, Gemini, GPT-4o, or any other — contributes raw capability. But raw capability without structure produces inconsistency. The Harness is the structured system of files, commands, and rules that surrounds the model and dictates how it behaves: what it reads before acting, what phases it must complete, what it is forbidden to skip, and how context survives between sessions. dbv-specs-ops is the Harness. It is not a plugin, a wrapper, or a package — it is a set of Markdown files your AI reads automatically, and those files contain everything needed to enforce disciplined engineering behavior across any platform.
The 6-Phase Lifecycle
Every task in dbv-specs-ops flows through six phases in order. The AI respects this sequence and will not skip a phase without explicit approval. Each phase is triggered by a slash command you type in the chat.| # | Phase | Command | What the AI Does | Output |
|---|---|---|---|---|
| 1 | Spec | /spec | Reviews or creates requirements in SPECIFICATIONS.md. Runs an Engineering Interview if specs are missing. | Updated SPECIFICATIONS.md |
| 2 | Plan | /plan | Runs an Adversarial Architect Review, classifies work mode (Conductor vs. Orchestrator), breaks work into atomic steps, and waits for your approval on complex tasks. | task.md + implementation_plan.md |
| 3 | Build | /build | Implements logic incrementally — one slice at a time. Adds file headers, sets up Python virtual environments, and updates CHANGELOG.md [Unreleased]. | Source code + updated CHANGELOG.md |
| 4 | Test | /test | Creates and runs unit or integration tests. A task is never marked done without a passing test. Fixes found bugs and logs them. | Test files + updated CHANGELOG.md |
| 5 | Simplify | /code-simplify | Refactors for clarity and runs a mandatory Security Review: checks for credential leaks, dependency confusion (slopsquatting), and input sanitization. | Cleaner, audited code |
| 6 | Ship | /ship | Updates README.md, completes walkthrough.md, asks for the version type (Patch / Minor / Major), finalizes CHANGELOG.md, and proposes a Conventional Commits message and git tag. | Versioned release |
You can jump to any phase by typing its command at any time. For example, typing
/ship when you are ready to deliver will cause the AI to handle versioning, changelog, and git tagging automatically — but only after confirming all prior phases are accounted for.Key Files and Their Roles
The framework consists entirely of Markdown files. There is no build step, no package to install, and no binary to configure. The files fall into two groups: framework files (which define the system’s rules) and project files (which the AI populates as you build). Framework files — define the system:| File | Role |
|---|---|
docs/MASTER_PROMPT.md | The brain of the system. Contains the full SDD workflow, development rules, security constraints, and context management instructions. The AI must read this before acting. |
project.config.md | Project identity: name, author, license, language stack, and the file header template the AI stamps on every source file it creates. Contains the current framework version. |
CLAUDE.md | Auto-loaded by Claude Code and Cursor. Points the AI to MASTER_PROMPT.md and summarizes the core rules. |
GEMINI.md | Auto-loaded by Gemini CLI and Antigravity. Points the AI to MASTER_PROMPT.md and summarizes the core rules. For Antigravity-specific Planning Mode and Knowledge Items setup, see ANTIGRAVITY.md. |
.windsurfrules | Auto-loaded by Windsurf. Equivalent context pointer for that platform. |
| File | Role |
|---|---|
memory.md | Qualitative knowledge base: active context, Architecture Decision Records (ADRs), lessons learned, and a relations map. The AI consults this at the start of every session to recover the technical thread. |
task.md | Quantitative logbook: task checklist, backlog, and Context Snapshots. The AI writes a snapshot here before any session ends so work can resume instantly. |
docs/SPECIFICATIONS.md | The what and why: problem statement, objectives, and acceptance criteria. Generated by the AI during /spec based on your Engineering Interview answers. |
docs/ARCHITECTURE.md | The how: tech stack, design decisions, and system structure. |
docs/DESIGN.md | The look: visual design system with color tokens, typography, spacing, and UI components. Optional for non-UI projects. |
implementation_plan.md | Detailed technical plan created during /plan. Requires explicit approval before /build begins on complex tasks. |
walkthrough.md | Created during /ship. A human-readable summary of what was built, tested, and delivered. |
CHANGELOG.md | Version history. The AI updates the [Unreleased] section during /build and /test, and publishes it on each /ship. |
Supported Platforms
dbv-specs-ops works with every major AI coding assistant. Context loading is automatic on most platforms — you just need the right activation file in your project root.| Platform | Activation File | Context Loading |
|---|---|---|
| Claude Code (CLI / VS Code / Desktop) | CLAUDE.md | Automatic at session start |
| Cursor | CLAUDE.md (compatible) | Automatic |
| Gemini CLI | GEMINI.md | Automatic |
| Antigravity (VS Code · Google DeepMind) | GEMINI.md + ANTIGRAVITY.md | Automatic (+ optional Knowledge Items setup) |
| Windsurf | .windsurfrules | Automatic |
| GitHub Copilot | .github/copilot-instructions.md | Automatic in workspace |
| ChatGPT / Gemini Web | docs/MASTER_PROMPT.md | Manual: paste in first message |
License and Credits
dbv-specs-ops is released under the MIT License and is free to use in any project, commercial or otherwise. It was conceived and directed by David Bueno Vallejo — original idea, methodology vision, document system design, testing and refinement. The framework synthesizes and builds upon several open-source works: Agent Skills by Addy Osmani (Google) for the SDD lifecycle structure, GitHub Spec-Kit for specification quality standards, and the New SDLC With Vibe Coding whitepaper as the theoretical foundation for agentic engineering and the Harness model.Quickstart
Get your first SDD session running in under 5 minutes.
Installation
Copy the framework files into a new or existing project.