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.
SPECIFICATIONS.md is the primary output of the /spec phase and the foundation on which every subsequent phase is built. It captures the “what” and “why” of the system — not the “how”. The AI will not advance to /plan until this document contains real content, and it will not write code that contradicts what is written here. Treating this file as a living contract between the developer and the AI is the core practice of Spec-Driven Development.
The AI checks this file during the Specs Check step at session start. If it finds only placeholder text, it will follow the reconstruction flow from ADOPTION_PROMPT.md before doing anything else.
Every SPECIFICATIONS.md begins with a metadata header that tracks its phase, status, and last revision:
# 📋 Specifications: [Project Name]
> **Phase:** `/spec` (Specification)
> **Status:** In Definition / Validated
> **Last Revision:** [Date]
Section Reference
Section 1 — Context & Objectives
Purpose: Establish shared understanding of the problem before any solution is proposed. This section answers the two most important questions in engineering: What is broken? and How will we know we fixed it?
| Field | What to write |
|---|
| Problem | Describe the pain point or need driving this project. Be concrete — name the friction, the failure, or the gap. |
| Objective (Success) | Define a tangible, observable outcome. Avoid vague goals like “improve performance.” Instead: “Users can retrieve their dashboard in under 2 seconds on a 3G connection.” |
/plan more useful — the more concrete the objective, the sharper the adversary’s challenge.
Section 2 — Users & Scenarios
Purpose: Ground the specifications in real human behavior. Features built without a named user type and a concrete scenario tend to drift toward what is technically interesting rather than what is needed.
| Field | What to write |
|---|
| User Profile | A role label, not a persona novel. Example: Hospital Administrator, End User, DevOps Engineer. |
| Scenario A | A specific task the user needs to accomplish, with a measurable qualifier where possible. |
| Scenario B | A second distinct scenario, ideally one that tests a boundary condition or a system-level behavior. |
Scenario A: “The user needs to retrieve the patient’s medical history in under 2 seconds.”
Scenario B: “The system must alert when a scheduling conflict is detected before the booking is confirmed.”
Section 3 — Main Features (Requirements)
Purpose: Define the “what” of the system as a checklist. Each item becomes a traceable task that will be moved to task.md during /plan. This section is the contract the AI uses to judge whether the /build output is complete.
Each feature entry should follow this pattern:
- [ ] **Feature A:** [Brief description and its acceptance criterion].
- [ ] **Feature B:** [Brief description and its acceptance criterion].
- Each item is atomic — it describes one capability, not a bundle.
- Each item has a clear acceptance criterion: a statement that makes “done” unambiguous.
- Items are scoped to this version. Anything deferred belongs in Section 5 (Out of Scope).
Section 4 — Technical Solution Summary
Purpose: Bridge the requirements to ARCHITECTURE.md. This section does not replace the architecture document — it summarizes the key technical choices made during specification to keep both files aligned.
| Field | What to write |
|---|
| Approach | A brief description of the chosen technical solution. |
| Critical Dependencies | External APIs, specific MCP servers, or third-party services that the solution depends on. |
| Skills & MCPs Opportunities | Analysis of whether the project would benefit from a local MCP server for internal logic, or from dynamic skill packages (skills/) to assist agent orchestration. |
| Design System | If the project has a UI, reference docs/DESIGN.md for color tokens, typography, and component definitions. |
Section 4.1 — Agent Readiness Checklist (Web Projects)
If Agent Readiness (Web): Yes is set in project.config.md, this sub-section must document all the agent-discoverability artifacts to be created:
### 4.1. Agent Readiness Checklist (Web Projects)
- [ ] **robots.txt**: Configure with `Content-Signal: ai-train=no, search=yes,
ai-input=yes` directive and sitemap path.
- [ ] **llms.txt**: Create a Markdown content map to accelerate semantic
reading by AI agents.
- [ ] **auth.md**: Describe registration and access processes for bots.
- [ ] **Metadata in `.well-known/`**: Create `api-catalog`,
`oauth-protected-resource`, `oauth-authorization-server`, and
`http-message-signatures-directory`.
- [ ] **Agent & MCP Cards**: Declare bot identity (`agent.json`) and MCP
server connection (`mcp.json`).
- [ ] **agent-skills/**: Define the `index.json` index and individual
`SKILL.md` skill manifests.
- [ ] **Markdown Negotiation**: Configure routing to return plain Markdown
on `Accept: text/markdown` headers and define HTTP `Link` headers
in the hosting config.
Section 5 — Out of Scope
Purpose: Prevent scope creep — the silent killer of software projects. Explicitly naming what will not be built in this version is as important as defining what will be.
## 🚫 5. Out of Scope
- [ ] [Feature or aspect that will NOT be addressed in this phase/version].
/build. If the developer asks for something that appears in this section during a later session, the AI will flag the contradiction rather than silently implementing it.
Section 6 — Risks & Mitigation
Purpose: Anticipate problems before they become blockers. The framework treats risk identification as a senior engineering skill, not a bureaucratic formality. Each risk must have a corresponding mitigation strategy.
The template defines three risk categories that must always be considered:
Standard risk:
- **Risk:** The external API has rate limits.
- **Mitigation:** Implement a local cache layer.
- **Risk:** Secret leakage, injection of vulnerable code by the agent,
or hallucinated dependency packages (slopsquatting).
- **Mitigation:** Implement deterministic pre-commit hooks with secret
scanning (e.g., gitleaks) and mandatory dependency audit in
/code-simplify.
- **Risk:** AI agents consume excessive tokens parsing complex HTML,
or get lost in registration flows.
- **Mitigation:** Implement an llms.txt file with a Markdown web map
and configure dynamic content negotiation for text/markdown.
A well-written risk entry always names a specific failure mode, not a generic category. “API dependency risk” is weak. “The Stripe API has a 100 req/s rate limit and no documented retry behavior for 429 responses” is actionable.
Section 7 — Open Questions
Purpose: Capture decisions that have not been made yet and cannot be safely assumed. These items must be resolved — or have a clear resolution path — before the AI will advance to /plan.
## ❓ 7. Open Questions
- [ ] Do we need offline support from day one?
- [ ] What data volume do we expect in the first month?
The AI is explicitly instructed not to proceed to /plan while critical open questions remain unresolved. If you try to skip this gate, the AI will pause and ask for resolution rather than guessing.
Section 8 — Evaluation Criteria & AI Evals
Purpose: Define the quality rubrics for non-deterministic AI components integrated in the system. This section applies when the project includes AI prompts, LLM-powered features, or any component whose output cannot be verified with a simple assertion.
| Metric Type | What to define |
|---|
| Output Metrics | Response accuracy, JSON format conformance, absence of hallucinations. |
| Trajectory Metrics | Efficiency of MCP tool calls, API call limits, step count to task completion. |
/test phase, where they become the evaluation suite (Evals) run against the AI components.
## 🧪 8. Evaluation Criteria & AI Evals
- [ ] **Output Metrics:** [e.g., Response accuracy, JSON format conformance,
absence of hallucinations].
- [ ] **Trajectory Metrics:** [e.g., MCP tool call efficiency,
API call limit compliance].
Closing Instruction
The final line of every SPECIFICATIONS.md template carries a binding instruction to the AI:
**AI Instruction:** Do not proceed to `/plan` until all critical
"Open Questions" have been resolved or have a defined resolution path.
