The entire dbv-specs-ops framework is a collection of plain Markdown template files — there is no binary to install, no package manager to run, and no build step required. You get the framework by copying a folder. Each file serves a specific role in the Spec-Driven Development lifecycle: some establish the rules the AI must follow, some capture decisions and state across sessions, some are produced as phase outputs, and some activate the framework on a specific AI platform. Understanding this file map is the fastest way to gain intuition for how the system works as a whole.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.
All paths below are relative to the root of your project (where you placed the framework files). The
docs/ folder holds immutable reference and specification documents; the root holds living operational files that the AI reads and writes throughout development.Comprehensive file reference
| File | Location | Read by | Created when | Purpose |
|---|---|---|---|---|
MASTER_PROMPT.md | docs/ | AI | Session start (manual platforms) | Core rules and constraints. Defines the 6-phase SDD workflow, context management strategy, security boundaries, and development standards the AI must follow. On auto-loading platforms, equivalent rules are delivered via CLAUDE.md, GEMINI.md, or .windsurfrules. |
project.config.md | root | AI | Project bootstrap (template provided) | Project identity: name, author, license, language list, Agent Readiness flag, and file-header template. Also contains the Model Routing Guidelines table. The AI fills in placeholders during the bootstrap interview. |
SPECIFICATIONS.md | docs/ | Both | /spec phase | The “What” and “Why”. Problem statement, user profiles, key scenarios, functional requirements, out-of-scope items, risks, open questions, and Evals criteria. The AI will not proceed to /plan until open questions are resolved. |
ARCHITECTURE.md | docs/ | Both | /plan phase | The “How”. Tech-stack table, directory structure, key technical decisions (auth, state, style), external integrations, and the Agent Harness configuration (MCP servers, sandboxing, guardrails, Agent Readiness architecture). |
DESIGN.md | docs/ | Both | /spec phase, if UI exists | The “Look”. Visual design system: color tokens, typography scale, spacing, and UI component definitions. Created only for projects with a user interface. Optional for pure API or CLI projects. |
memory.md | root | AI | First /plan or /build session | Qualitative persistent context. Stores active context, Architecture Decision Records (ADRs), lessons learned, and a relations map. The AI must consult this at the start of every session to recover technical continuity across token-limit boundaries. |
task.md | root | AI | First /plan session | Operational state. Quantitative progress checklist, backlog items, technical-debt log, and Context Snapshots that let the AI resume work after a session ends. |
CLAUDE.md | root | AI (Claude only) | Template provided | Platform activation file for Claude Code (CLI, VS Code, Desktop) and Cursor. Automatically loaded at session start, delivering the same rules as MASTER_PROMPT.md without manual pasting. |
GEMINI.md | root | AI (Gemini / Antigravity) | Template provided | Platform activation file for Gemini CLI and the primary auto-load trigger for Antigravity (Google DeepMind VS Code extension). Automatically loaded at session start. |
ANTIGRAVITY.md | root | AI (Antigravity) | Template provided | Extended behavior configuration specific to the Antigravity platform, including optional Knowledge Index (KI) setup and Antigravity-specific planning artifact conventions. |
.windsurfrules | root | AI (Windsurf) | Template provided | Platform activation file for the Windsurf IDE. Automatically loaded at session start; contains the same enforcement rules as MASTER_PROMPT.md formatted for Windsurf’s rule loader. |
ADOPTION_PROMPT.md | docs/ | AI | On demand (existing projects) | Onboarding guide for adopting SDD in a project that already has code but no specifications. The AI reads this when instructed to analyze an existing codebase and generate SPECIFICATIONS.md, ARCHITECTURE.md, and task.md from scratch. |
UPGRADE_PROMPT.md | docs/ | AI | On demand (version upgrades) | Zero-collision upgrade agent. Instructs the AI to detect the current framework version from project.config.md, download only the changed framework files, and apply them without touching source code, specs, or changelog. |
AGENTIC_ENGINEERING.md | docs/ | Human | Template provided | Human-facing reference document. Explains the theoretical foundations of Agentic Engineering: Conductor vs. Orchestrator modes, Evals, the Agent Harness, and the transition from interactive prompting to autonomous codebase-factory operation. |
CHANGELOG.md | root | Both | /build phase (first entry) | Version history in Keep-a-Changelog format. The AI writes to the [Unreleased] section during /build and /test, and promotes entries to a versioned section with a date during /ship. |
README.md | root | Both | /ship phase | Human-facing project overview. Generated from README.template.md during bootstrap (template is then deleted). Updated by the AI on every /ship to reflect the current stable version and feature set. |
walkthrough.md | root | Both | /ship phase (AI writes) | Feature walkthrough. A plain-language summary of what was built, tested, and delivered in the current release cycle. Written by the AI at the end of each /ship phase. |
implementation_plan.md | root | AI writes, Human approves | /plan phase (complex tasks only) | Detailed execution plan for complex tasks (those touching more than 3 files, involving auth/payments/sensitive data, or estimated at more than 150 new lines). Includes a YAML frontmatter block with dependencies, risks, and rollback_strategy. The AI waits for explicit human approval before proceeding to /build. |
Minimal required vs. generated on demand
Not all files need to exist before you start. The framework distinguishes two tiers: Minimal required set — these files must be present at session start for the AI to load context and enforce the SDD workflow correctly:project.config.md(project identity and routing rules)CLAUDE.md/GEMINI.md/.windsurfrules(one platform activation file matching your AI tool)docs/MASTER_PROMPT.md(required for manual-load platforms like ChatGPT or Gemini Web)
docs/SPECIFICATIONS.md→ created during/specdocs/ARCHITECTURE.md→ created during/plandocs/DESIGN.md→ created during/spec, only if the project has a UItask.md→ created during the first/plansessionmemory.md→ first written during/planor/buildwhen a decision is loggedimplementation_plan.md→ created during/planfor complex tasks onlywalkthrough.md→ created during/shipCHANGELOG.md→ first entry added during/buildREADME.md→ generated fromREADME.template.mdduring bootstrap
Files grouped by category
Core Rules
Files that define how the AI must behave. These are read at session start and establish the enforcement layer for the entire SDD workflow.
docs/MASTER_PROMPT.md— full rule set (manual platforms)project.config.md— project identity + model routingdocs/AGENTIC_ENGINEERING.md— human reference for agentic principlesdocs/ADOPTION_PROMPT.md— on-demand SDD adoption for existing projectsdocs/UPGRADE_PROMPT.md— on-demand zero-collision framework upgrade
Context Files
Files that persist knowledge across sessions, eliminating AI amnesia and enabling long-running projects without context loss.
memory.md— qualitative decisions and ADRstask.md— quantitative progress and context snapshotsdocs/SPECIFICATIONS.md— requirements and acceptance criteriadocs/ARCHITECTURE.md— technical decisions and harness configdocs/DESIGN.md— visual design system (UI projects only)
Phase Outputs
Files that are written or updated by the AI as it moves through the six development phases.
implementation_plan.md—/planoutput (complex tasks)CHANGELOG.md— updated during/build,/test, and/shipwalkthrough.md—/shipoutputREADME.md— updated on every/ship
Platform Activations
Files that trigger automatic context loading for a specific AI platform. Use only the file that matches your tool — the others are optional.
CLAUDE.md— Claude Code, CursorGEMINI.md— Gemini CLI, AntigravityANTIGRAVITY.md— Antigravity extended config.windsurfrules— Windsurf IDE