Install dbv-specs-ops into a new or existing project

dbv-specs-ops installs as plain Markdown files — there is no package to install, no CLI to run, and no runtime dependency to manage. The framework works by being present in your project directory so your AI assistant can read it automatically at the start of every session. This page covers both installation paths: starting fresh and adopting an existing codebase.

All Framework Files

The table below lists every file in the framework, its location, and whether it is required for the system to function.

File	Location	Required	Purpose
`MASTER_PROMPT.md`	`docs/`	✅ Required	The SDD workflow brain. Rules, lifecycle, and constraints the AI must follow.
`project.config.md`	root	✅ Required	Project identity: name, author, license, language stack, framework version.
`CLAUDE.md`	root	✅ One activation file required	Auto-loaded by Claude Code and Cursor.
`GEMINI.md`	root	✅ One activation file required	Auto-loaded by Gemini CLI and Antigravity.
`.windsurfrules`	root	✅ One activation file required	Auto-loaded by Windsurf.
`SPECIFICATIONS.md`	`docs/`	✅ Required (AI-generated)	The what and why. Generated during `/spec`.
`ARCHITECTURE.md`	`docs/`	✅ Required (AI-generated)	The how. Generated during `/plan`.
`task.md`	root	✅ Required (AI-maintained)	Task checklist, backlog, and Context Snapshots.
`memory.md`	root	✅ Required (AI-maintained)	Qualitative context: ADRs, lessons learned, relations map.
`CHANGELOG.md`	root	✅ Required (AI-maintained)	Version history. AI updates `[Unreleased]` during `/build` and `/test`.
`ADOPTION_PROMPT.md`	`docs/`	⚙️ Existing projects	Guides the AI through adopting an existing codebase into SDD.
`UPGRADE_PROMPT.md`	`docs/`	⚙️ Upgrades only	Used to migrate framework files to a newer version.
`DESIGN.md`	`docs/`	Optional	Visual design system: color tokens, typography, components. UI projects only.
`ANTIGRAVITY.md`	root	Optional	Antigravity-specific Planning Mode and Knowledge Items configuration.
`.github/copilot-instructions.md`	`.github/`	Optional	Activation file for GitHub Copilot in VS Code / JetBrains.
`implementation_plan.md`	root	Optional (AI-generated)	Detailed plan for complex tasks. Created during `/plan`, requires explicit approval before `/build`.
`walkthrough.md`	root	Optional (AI-generated)	Delivery summary. Created during `/ship`.
`README.template.md`	root	Optional	Bootstrap template the AI uses to generate the initial `README.md`.

You only need one activation file — the one that matches your AI platform. You can safely keep all three (CLAUDE.md, GEMINI.md, .windsurfrules) in the project root if your team uses multiple platforms; they do not conflict with each other.

Installation Methods

Fresh Project
Existing Project

Starting a new project from scratch is the simplest path. The recommended approach is to use the GitHub Template so you get all framework files with a clean git history.

Option A — GitHub Template (Recommended)

Go to github.com/davidbuenov/dbv-specs-ops.
Click “Use this template” → “Create a new repository”.
Name your new repository and choose its visibility.
GitHub creates a fresh repo under your account with all framework files and no history from the original.

Your project is immediately independent — no upstream connection, no submodule, no fork.

Option B — Download ZIP

Click the green “Code” button on the GitHub page → “Download ZIP”.
Extract the archive.
Copy all extracted files into your new project folder.

# Example: create project folder and copy files
mkdir my-new-project
cp -r dbv-specs-ops-main/* my-new-project/
cd my-new-project
git init
git add .
git commit -m "chore: initialize project with dbv-specs-ops framework"

After copying files

Open project.config.md and confirm it contains the default placeholders:

## Project Identity

- **Name:** [Project Name]
- **Description:** [One-line description]
- **Author / Company:** [Your Name or Company · https://yourwebsite.com]
- **License:** [MIT]
- **Languages:** [e.g. Python, JavaScript, HTML, CSS]
- **Agent Readiness (Web):** [Yes / No / Not Applicable]
- **Framework Version:** 2.1.0

Leave the placeholders as-is. When you open your AI assistant and type /spec, it will detect them and run the Bootstrap Interview — proposing all six configuration values at once with assumptions marked for your review, then filling project.config.md automatically after your single confirmation reply.

If you already have a codebase and want to adopt SDD methodology without starting over, use docs/ADOPTION_PROMPT.md. It guides the AI through analyzing your existing code and generating the full set of specification, architecture, and task documents from scratch.

Option A — Root Adoption (Standard)

Use this when you are comfortable adding framework files directly to your project root, and you do not already have conflicting files like README.md or CHANGELOG.md that you want to preserve.

Download the framework files and copy them to the root of your existing project.
Open your AI assistant and send this message:

Follow the instructions in docs/ADOPTION_PROMPT.md to analyze this project
and incorporate it into the SDD methodology.

The AI will:

Analyze your existing source code autonomously.
Present a summary with assumptions marked.
Ask you to confirm or correct its draft in a single reply.
Generate docs/SPECIFICATIONS.md, docs/ARCHITECTURE.md, and task.md based on what it finds.

Option B — Subfolder Isolation (Recommended for existing repositories)

Use this when you want to keep your project root pristine and avoid overwriting existing files. The entire framework lives in an isolated dbv-specs-ops/ subfolder.

Copy the entire dbv-specs-ops folder into the root of your existing project.
Create a minimal activation file at your project root pointing to the subfolder:

# CLAUDE.md (at your project root)

Please read and follow the master instructions in
`dbv-specs-ops/docs/MASTER_PROMPT.md`.

All specs, tasks, and memory logs are located inside
the `dbv-specs-ops/` folder.

Tell your AI assistant:

Adapt this project to the SDD methodology using the framework
configuration inside the dbv-specs-ops/ folder. Refer to
dbv-specs-ops/docs/ADOPTION_PROMPT.md for instructions.

The AI will analyze your code and generate all specification documents, architecture files, and task registries inside the isolated dbv-specs-ops/ folder, never touching your existing source code.

The Subfolder Isolation method requires that your activation file (CLAUDE.md, GEMINI.md, or .windsurfrules) live at the project root, not inside the dbv-specs-ops/ subfolder. The activation file at the root must explicitly point the AI to dbv-specs-ops/docs/MASTER_PROMPT.md, otherwise the AI will not find the framework context.

For complete adoption documentation, see the advanced adoption guide.

How Activation Files Are Auto-Loaded

Each AI platform has a convention for which file it reads automatically when you open a session in a project directory. dbv-specs-ops ships with activation files for every major platform:

Platform	File	Behavior
Claude Code	`CLAUDE.md`	Loaded automatically before the first message in every session
Cursor	`CLAUDE.md`	Read automatically; Claude-compatible format
Gemini CLI	`GEMINI.md`	Loaded automatically by the `gemini` terminal command
Antigravity	`GEMINI.md`	Auto-loaded; `ANTIGRAVITY.md` adds Planning Mode and Knowledge Items setup
Windsurf	`.windsurfrules`	Loaded automatically from the workspace root
GitHub Copilot	`.github/copilot-instructions.md`	Loaded automatically within the VS Code / JetBrains workspace
ChatGPT / Gemini Web	`docs/MASTER_PROMPT.md`	Not automatic — paste the file’s contents as your opening message

All auto-loading activation files are thin pointers. Their content directs the AI to read docs/MASTER_PROMPT.md and follow its workflow strictly, keeping the actual rules centralized in one place and reducing cognitive overhead for the model.

Confirming the Framework Version

The installed framework version is recorded in project.config.md under the Framework Version field. To confirm which version you are running:

grep "Framework Version" project.config.md

You should see output like:

- **Framework Version:** 2.1.0

If your version is outdated and you want to upgrade, download docs/UPGRADE_PROMPT.md from the latest release and tell your AI:

Read docs/UPGRADE_PROMPT.md and upgrade my project.

The upgrade prompt instructs the AI to detect your current version, calculate which framework files changed, and apply only those updates — without touching your source code, specifications, architecture documents, task log, or changelog.

The upgrade process is zero-collision by design. The files the AI will never touch during an upgrade include docs/SPECIFICATIONS.md, docs/ARCHITECTURE.md, task.md, CHANGELOG.md, README.md, and all your source code. Only the framework scaffolding files (MASTER_PROMPT.md, activation files, and optional new docs) are updated.

Get Started

Core Concepts

The SDD Workflow

Platform Setup

Advanced

Install dbv-specs-ops into a new or existing project

All Framework Files

Installation Methods

Option A — GitHub Template (Recommended)

Option B — Download ZIP

After copying files

Option A — Root Adoption (Standard)

Option B — Subfolder Isolation (Recommended for existing repositories)

How Activation Files Are Auto-Loaded

Confirming the Framework Version

Build docs developers (and LLMs) love

Get Started

Core Concepts

The SDD Workflow

Platform Setup

Advanced

Documentation Index

​All Framework Files

​Installation Methods

​Option A — GitHub Template (Recommended)

​Option B — Download ZIP

​After copying files

​Option A — Root Adoption (Standard)

​Option B — Subfolder Isolation (Recommended for existing repositories)

​How Activation Files Are Auto-Loaded

​Confirming the Framework Version

Build docs developers (and LLMs) love

All Framework Files

Installation Methods

Option A — GitHub Template (Recommended)

Option B — Download ZIP

After copying files

Option A — Root Adoption (Standard)

Option B — Subfolder Isolation (Recommended for existing repositories)

How Activation Files Are Auto-Loaded

Confirming the Framework Version