Before a single line of code is written, theDocumentation 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.
/spec phase ensures the AI assistant and the developer share a precise, documented understanding of the problem and the solution. This is the foundational principle of Spec-Driven Development: spec before code. Rushing past this phase is the single most common source of costly rework, architectural drift, and scope creep in AI-assisted projects.
If the “what” is not yet clear, the assistant must ask before acting. Ambiguity in specs always becomes bugs in code.
What happens in /spec
Review existing specs and architecture for impact
Before proposing anything new, the assistant reads
docs/SPECIFICATIONS.md and docs/ARCHITECTURE.md to assess whether the incoming request affects existing decisions. Changes that contradict documented architecture must be flagged and discussed before proceeding — they are not silently overridden.Clarify the 'what' before the 'how'
The assistant does not propose a technical solution until the requirement is unambiguous. If the scope, acceptance criteria, or expected behavior cannot be derived from existing documents, open questions are raised in
SPECIFICATIONS.md under Preguntas Abiertas (Open Questions) and the developer is asked to resolve them before moving to /plan.Create DESIGN.md for UI projects
If the project has a user interface and
docs/DESIGN.md does not yet exist, the assistant creates and completes it during this phase. DESIGN.md records the design system’s color tokens, typography scale, and component inventory so that UI decisions are as version-controlled as code decisions.Evaluate Harness & Context needs
The assistant analyses whether the project would benefit from:
- External connectors — integrations that justify a local MCP (Model Context Protocol) server.
- Skills modules — dynamic procedural packages placed in
skills/that are injected into the agent’s context on demand instead of loaded globally, reducing token consumption.
Plan Agent Readiness artifacts (web projects)
If
Each item is listed as a checkbox task in
project.config.md has Agent Readiness (Web): Yes — or a web/API stack is detected — the assistant documents the full discovery interface for external agents inside docs/SPECIFICATIONS.md. The checklist includes:| Artifact | Purpose |
|---|---|
robots.txt | Content-Signal: ai-train=no, search=yes, ai-input=yes directive + sitemap link |
/llms.txt | Markdown navigation map for AI readers |
/auth.md | Access instructions for bots |
.well-known/api-catalog | RFC 9727 API catalog |
.well-known/oauth-protected-resource | OAuth resource descriptor |
.well-known/oauth-authorization-server | OAuth server metadata |
.well-known/http-message-signatures-directory | Signature directory |
.well-known/agent.json | Agent identity card |
.well-known/mcp.json | MCP server card |
agent-skills/index.json | Skills index |
agent-skills/SKILL.md | Individual skill manifests |
| Markdown content negotiation | Return .md on Accept: text/markdown + Link headers |
docs/SPECIFICATIONS.md so it is traceable through the rest of the cycle.Produce the filled SPECIFICATIONS.md
The primary output of
/spec is a fully populated docs/SPECIFICATIONS.md. It must cover: context and objectives, user profiles and key scenarios, functional requirements, the technical solution summary (including MCP/Skills opportunities), Agent Readiness checklist (if applicable), out-of-scope items, risk register, open questions, and evaluation criteria for non-deterministic (AI) components.The assistant does not proceed to /plan while critical open questions remain unresolved.Key output
The completed/spec phase produces at minimum:
- A filled
docs/SPECIFICATIONS.md— the single source of truth for the entire development cycle. - A
docs/DESIGN.md(UI projects only). - An updated Agent Readiness task checklist in
SPECIFICATIONS.md(web projects only).