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.
memory.md and task.md work as a pair. Together they solve the hardest problem in long-running AI-assisted development: preserving context across sessions, token limits, and model switches. Each file has a distinct responsibility, and understanding the boundary between them is essential for using dbv-specs-ops effectively.
The Core Distinction
The framework defines the boundary between the two files precisely:
| File | Type of information | Question it answers |
|---|
memory.md | Qualitative / thematic | Why did we make this decision? What did we learn? |
task.md | Operational / state | Where are we right now? What is the exact next step? |
If information has an exact date/step → task.md.
If information contains reasoning, lessons, or “why” → memory.md.
When information could fit both, use both — but keep each file’s copy focused on its own dimension.
memory.md
memory.md is the AI’s persistent technical memory. It is read at the start of every session to recover the engineering thread from the previous session. Without this file, the AI starts each session cold — unaware of past decisions, past mistakes, and the current technical direction.
Section Reference
🎯 Active Context
The current development state at a thematic level. This is not a step-by-step task list — that belongs in task.md. This is the headline: what is being worked on and what the immediate engineering focus is.
## 🎯 Active Context
- **Current development state:** v2.0.0 release completed successfully.
The framework has been fully updated to support agentic engineering
methodology and harness optimization.
- **Immediate focus:** Distribution and documentation of v2.0.0 for
team developers.
🏗️ Technical Decisions Log (Lightweight ADR)
A chronological log of architectural and technical decisions. Each entry is a lightweight Architecture Decision Record (ADR): it records the date, the decision title, and — most importantly — the rationale. This log is what allows a new session (or a new team member) to understand why the codebase looks the way it does.
## 🏗️ Technical Decisions Log (Lightweight ADR)
- **2026-06-15 - Transition to dbv-specs-ops v2.0.0 (Agentic Engineering):**
Implemented Google white paper principles. Unified non-deterministic AI
Evals into the `/test` phase to simplify the flow, and added security
audit in `/code-simplify` to prevent credential leakage or hallucinated
packages (slopsquatting). Transitioned the MCP section in architecture
to an explicit Agent Harness definition.
- During
/plan — if the Adversarial Review identifies a risk that is consciously accepted.
- During
/build — immediately when a decision in ARCHITECTURE.md is modified or contradicted.
- During
/test — if a test reveals that an assumption in SPECIFICATIONS.md was wrong.
- During
/ship — via the Memory Gate, before closing the task.
⚠️ Lessons Learned / Errors Avoided
A record of bugs, configuration failures, and refactors attempted — written to prevent repetition. These entries are direct and specific, naming the exact failure mode and its cause.
## ⚠️ Lessons Learned / Errors Avoided
- **[Usability Feedback]:** It is better to integrate new concepts
(like Evals) into existing phases (`/test`) and delegate execution
modes (Conductor/Orchestrator) implicitly, rather than overloading
the developer with complex configurations or confusing questions.
- **[Onboarding Structure]:** In existing projects with consolidated
root files (like `README.md` and `CHANGELOG.md`), it is preferable
to download the framework into a dedicated subfolder (`dbv-specs-ops/`)
and point the agent to it via a lightweight activation file
(`CLAUDE.md`, `GEMINI.md`). This avoids file collisions and keeps
production code clean.
🗺️ Relationship Map
A brief description of how the current modules interact. This helps the AI navigate the codebase without having to re-read every file on each session.
## 🗺️ Relationship Map
- **[Module/Component]:** [Responsibility and Dependencies]
- Example: `auth_service.js` manages JWT and depends on `api_client.js`.
Maintenance Policy
Keep memory.md under approximately 200 active lines. If the file grows beyond this threshold, the AI cannot read it entirely in a single context window — which defeats its purpose. Apply the maintenance policy during every Major release or whenever the 200-line limit is approached.
| Operation | When to apply |
|---|
| Consolidate | Merge related decisions into a single entry |
| Archive | Move lessons already embedded in the codebase to memory.archive.md (create if it does not exist) |
| Delete | Remove entries about decisions that have been reverted or are now obsolete |
| Goal | Keep the file under ~200 active lines so the AI can read it entirely without attention loss |
task.md
task.md is the operational task tracker. It records what is being done right now, what is queued, and — most importantly — the Context Snapshot that lets the AI resume work precisely where it left off after a session ends.
Section Reference
🏗 In Progress
Tasks currently being worked on. Each entry should be specific enough that the AI knows exactly what “done” means for that item.
## 🏗 In Progress / En Curso
- [ ] **Implement authentication middleware**
- [ ] JWT validation on protected routes
- [ ] Refresh token rotation logic
⏳ Pending / Backlog
Tasks that are defined but not yet started. This section also holds Technical Debt items registered by the AI during /build when it encounters improvements outside the current task scope.
## ⏳ Pending / Backlog
- [ ] **Technical Debt:** Refactor the query builder to remove
duplication between `list` and `search` handlers.
- [ ] **Feature:** Export dashboard data as CSV (deferred from v1.0.0).
✅ Completed
A chronological record of completed tasks. This section is the project’s progress log and serves as input for CHANGELOG.md entries during /ship.
## ✅ Completed
- [x] **Phase 2: Planning and Preparation**
- [x] Create `implementation_plan.md` and update `task.md`.
- [x] Obtain final user approval on proposed changes.
- [x] **Phase 3: Build (`/build`)**
- [x] Modify `project.config.md` to add Agent Readiness property
and bump version to 2.1.0.
🔄 Context Snapshot
The Context Snapshot is the most important entry in task.md. It is written by the AI whenever a session is about to end before work is complete. It contains four fields that allow any future session — with the same or a different model — to resume exactly where work stopped.
## 🔄 Context Snapshot / Snapshot de Contexto
> **Last update:** 2026-06-17
> **Exact point:** Version 2.1.0 (Agent Readiness Integration) finalized
> and documented in walkthrough and changelog.
> **Pending:** Execute commit and tag in local repository.
> **Next step:** Inform the human user of the successful release and
> provide the Git commands.
| Field | Purpose |
|---|
| Last update | Date of the snapshot — used to detect stale context |
| Exact point | The precise state of the work, not a vague summary |
| Pending | What was left undone at session end |
| Next step | The first concrete action for the next session |
When the AI Triggers Updates
The framework defines specific trigger points for memory and task updates:
Memory Triggers (writes to memory.md)
| Phase | Trigger condition |
|---|
/plan | Adversarial Review identifies a risk that is consciously accepted |
/build | A decision documented in ARCHITECTURE.md is modified or contradicted |
/test | A test reveals that an assumption in SPECIFICATIONS.md was incorrect |
Memory Gate (mandatory at /ship)
Before closing any task, the AI must print a <memory_update_proposal> block in the chat:
<memory_update_proposal>
<section>Lessons</section>
<entry>Bug X occurs because of Y when Z condition is present.
Resolved by adding null check at the entry point.</entry>
</memory_update_proposal>
<memory_update_proposal>none</memory_update_proposal>
<reason>This cycle was a minor style refactor with no new architectural
decisions.</reason>
The Memory Gate cannot be skipped. Even a none result must be explicitly declared with a reason. This forces the AI to consciously evaluate whether the session produced persistent knowledge — rather than silently moving on.
