Skip to main content

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.

If your project already has code — even a significant amount of it — you can still adopt the Spec-Driven Development framework without disrupting the work in progress. The adoption agent (docs/ADOPTION_PROMPT.md) acts as a senior engineer who has just joined your team: it reads the codebase silently first, then collaborates with you to reconstruct the context and generate the SDD documents that should have been there from the start. Nothing is deleted, no files are overwritten, and your source code is never touched.
Throughout the adoption process, the AI marks inferred information with [ASSUMPTION: ...]. These are hypotheses, not facts. Review every assumption and correct the ones that are wrong — accuracy at this stage directly determines the quality of your SPECIFICATIONS.md.

​
When to use ADOPTION_PROMPT.md

Use ADOPTION_PROMPT.md when:
  • Your project already has source code but no SDD documents (SPECIFICATIONS.md, ARCHITECTURE.md, task.md).
  • You want to start using the SDD workflow without losing the context that already exists in your codebase.
  • You are onboarding a new AI assistant to a project it has never seen before.
If you are starting a brand-new project from scratch, follow the standard bootstrap flow described in docs/MASTER_PROMPT.md instead.

​
How to trigger the adoption process

Paste the following message to your AI assistant as your first message in a new session: 
Read docs/ADOPTION_PROMPT.md and onboard this project to SDD.
That single instruction kicks off all four phases automatically, in order.

​
Installing the framework in an existing project

For existing projects, it is recommended to install the dbv-specs-ops files into a dedicated subfolder (dbv-specs-ops/) rather than mixing them with your existing root files. The adoption agent respects this layout: when it generates SPECIFICATIONS.md, ARCHITECTURE.md, and task.md, it places them inside the subfolder (e.g. dbv-specs-ops/docs/SPECIFICATIONS.md).

​
The 4-Phase Adoption Process

1

Phase A — Silent Project Analysis

Before asking you a single question, the agent explores the project autonomously. It reads:
  • Configuration files at the root (package.json, pyproject.toml, Cargo.toml, pom.xml, etc.) to identify the stack and key dependencies.
  • Directory structure up to two levels deep.
  • README.md if one exists.
  • Test files to understand what is already covered and what is not.
  • Recent git history via git log --oneline -20 if a repository is present.
  • Existing documentation (wikis, docs/ folders, code comments).
When the analysis is complete, the agent presents a structured summary before moving on:
## Initial Analysis
- **Detected stack:** [technologies and versions]
- **Project status:** [prototype / active development / production / maintenance]
- **Tests:** [none / partial (~X%) / reasonable coverage]
- **Existing documentation:** [none / basic README / partial docs / well documented]
- **Git history:** [no commits / active — last commit X days ago / inactive]
- **Visible technical debt:** [brief list of what stands out]
2

Phase B — Context Interview

Rather than asking you questions one at a time, the agent drafts an initial set of answers to the six critical areas listed below — based entirely on the silent analysis. Each inference is marked with [ASSUMPTION: ...]. You review the full draft and correct or confirm everything in a single reply.The six areas:
  1. Main objective — what problem the project solves.
  2. Working vs. incomplete parts — what already functions and what is broken or missing.
  3. Most urgent task or delivery — what needs to happen next.
  4. Immovable technical decisions — database, framework, external APIs, infrastructure choices that cannot change.
  5. Known technical debt — recurring problems or issues the agent spotted.
  6. Number of contributors — solo developer or a team.
This draft-and-confirm approach means you only need to write one focused reply instead of answering a long series of individual questions.
3

Phase C — Generate SDD Documents

With the analysis and your confirmed answers, the agent creates three files. Each uses transparency markers so you can see exactly what was inferred versus confirmed:
MarkerMeaning
[INFERIDO]Deduced from code or structure — pending your confirmation
[CONFIRMADO]Explicitly confirmed by you in Phase B
[PENDIENTE]Information is missing and must be resolved later
docs/SPECIFICATIONS.md — filled with the project’s goals, users, features, and technical approach as understood from the analysis and your answers.docs/ARCHITECTURE.md — documents the stack and structure as it is today, not as it ideally should be. Includes the immovable technical decisions you confirmed.task.md — a backlog containing:
  • In-progress work detected from branches, TODOs, and failing tests.
  • Pending tasks you indicated in Phase B.
  • A Context Snapshot capturing the real state of the project at this moment, so any AI assistant can resume work from this exact point.
4

Phase D — Kickoff

Once the three documents are ready, the agent presents a status summary and asks:
“I’ve reconstructed the context. The current state is in task.md. Shall we start with [most urgent task identified] or is there anything you want to correct in the specifications first?”
From this point on, the standard SDD workflow defined in docs/MASTER_PROMPT.md takes over. The /spec → /plan → /build → /test → /code-simplify → /ship cycle applies to every subsequent task.

​
What the adoption agent never does

  • It does not delete or overwrite existing source code.
  • It does not restructure your directory layout.
  • It does not execute git init or any git command without your explicit confirmation.

Build docs developers (and LLMs) love

Get started for freeTalk to us