# ADEL — Agentic Delivery & Engineering Lifecycle **The ADEL Framework.** A way to run software projects in which people and AI agents work from the same written decisions, link every change to the decision behind it and verify the result with evidence. This page explains where project decisions and evidence belong, who may approve changes and how coding agents should use that information. Author: Mark A. Basco Version: 2026.09 Framework: Designed to be adapted across projects, teams, technology stacks and AI coding tools. --- ## Executive summary Software delivery becomes difficult to control when intent, requirements, constraints, design decisions, implementation work and evidence are scattered across conversations, people’s memory, work items, code and tools. The risk grows when work moves between people and coding agents. An agent can act quickly, but it cannot follow a decision or constraint that it cannot find. People face the same problem when work moves between teams, contributors or sessions. ADEL — the Agentic Delivery & Engineering Lifecycle — is a software delivery framework and way of working. Teams use it to keep people and coding agents aligned around the same approved decisions throughout delivery. Those decisions remain available for reference, changeable by the right approvers and traceable to implementation and evidence. ADEL sorts project decisions into six layers. The project records each decision where people and agents can find it. When a decision changes, its approver updates the source of truth, and the team updates any later work that depended on it. Seven lifecycle steps move work from the initial need to verification and closure. Work can return to an earlier decision when new information appears. The Agent execution overlay tells coding agents where to find each source of truth, which repository rules to follow, which required checks to run and how to report results. > **The framework in one sentence** > > Keep people and AI agents working from the same approved project knowledge, give each important decision a responsible layer and an approver, link every change to the decision behind it and verify the result with evidence. ### The model ADEL has six framework layers and one Agent execution overlay. The layers separate different kinds of decisions. The overlay provides agent instructions across all six. Section 5 shows how work moves through the model in seven lifecycle steps. | Read the model in three parts | Role | | --- | --- | | Governance | Sets the rules every other layer must follow and names who may approve important decisions and exceptions. | | Delivery layers | Hold the requirements, design, plans, work items and evidence that take a change from the original need to a checked result. | | Agent execution overlay | Tells coding agents where to find that project knowledge and how to use it, within Governance and the permissions their tools enforce. |

**Governance — Governance principles** (Governs all project work) - Project-wide rules and who may approve exceptions - Answers: What project-wide rules must the work follow, and who may approve exceptions? **The delivery layers beneath it, connected by a forward flow with feedback to affected decisions:** - Product Definition — Product intent and requirements - System Design — Approved design and decision records - Delivery Planning — Delivery plan - Execution — Work item - Assurance — Verification evidence and traceability **Agent execution overlay: Agent instructions** (Applies to every layer) - Agent instructions used across the repository - Answers: How should a coding agent work in this repository? - Carries: Sources of truth and repository map - Carries: Operating rules - Carries: Required checks - Carries: Completion report **Two responsibilities that are easy to confuse:** - Project governance — Defines project-wide principles, rules and decision authority that every layer and contributor must follow. - Agent instructions — Tells coding agents how to work in the repository while following the project’s approved decisions and rules. ```mermaid flowchart TD C["Governance principles — Governance"] L0["Product intent and requirements — Product Definition"] L1["Approved design and decision records — System Design"] L2["Delivery plan — Delivery Planning"] L3["Work item — Execution"] L4["Verification evidence and traceability — Assurance"] A["Agent instructions — Agent execution overlay"] C -. "Governs all project work" .-> L0 L0 --> L1 L1 --> L2 L2 --> L3 L3 --> L4 A -. "Applies to every layer" .-> L0 A -. "Applies to every layer" .-> L1 A -. "Applies to every layer" .-> L2 A -. "Applies to every layer" .-> L3 A -. "Applies to every layer" .-> L4 ``` Governance holds the project-wide principles, rules and decision authority that every other layer must follow. The five delivery layers hold different project knowledge. Product Definition holds product intent and requirements. System Design holds the approved design and important design decisions. Delivery Planning splits approved work into clearly scoped work items and puts them in order. Execution carries out each work item. Assurance holds verification evidence and traceability. Work generally moves through these layers in that order. When new information changes a decision, return it to the responsible layer, update its source of truth and then update later work that depends on it. The Agent execution overlay works alongside all six layers. It tells coding agents where to find each source of truth, which repository rules to follow, which required checks to run and how to report results. ADEL defines these responsibilities, while each project chooses its own records, filenames and tools. Figure 1 — ADEL conceptual model. Designed to be adapted across projects, teams, technology stacks and AI coding tools.

### The primary question for each layer and the Agent execution overlay Each framework layer and the Agent execution overlay has one primary responsibility, expressed as a question. When several records claim to answer the same question, people and agents may not know which one to follow. | ADEL layer or Agent execution overlay | Project knowledge carried | Question answered | | --- | --- | --- | | Governance | Project principles and policy | What project-wide rules must the work follow, and who may approve exceptions? | | Product Definition | Product intent and requirements | What must we build, for whom, and why? | | System Design | Approved design and decision records | How will the system work, and why did we choose that design? | | Delivery Planning | Delivery plan | Which work is ready, in what order, and who will do it? | | Execution | Work item | What exactly is being changed, and how will we know it is done? | | Assurance | Verification evidence and traceability | What evidence shows that the result works as required? | | Agent execution overlay | Agent instructions | How should a coding agent work in this repository? | ### What successful use looks like ADEL is working when the people and agents making a change can answer these questions from current project records instead of reconstructing decisions from earlier conversations. 1. Why does this change exist, and what outcome or requirement does it serve? 2. What principles, requirements and design decisions constrain it? 3. Who may make or approve each important decision? 4. What clearly scoped work implements the current decision? 5. What evidence supports the conclusion that the result is acceptable? ### Scope ADEL defines which layer is responsible for each kind of decision and what each layer must keep on record. It does not prescribe every process, role, file or tool. The lists below show what ADEL is and what it is not. **ADEL is** - A reusable framework for software projects delivered by people, AI agents or both. - Independent of any vendor; projects can use their existing editors, agents, repositories and technology stacks. - Adjustable to the project; the six layers stay the same while the amount of detail, record separation and change control can vary. **ADEL is not** - A claim that these example records or filenames are an industry standard. ADEL combines established requirements, architecture, decision-record and required-check practices with newer practices for instructing coding agents. - A waterfall process. Requirements and design can change; a project using ADEL records each change and links it to the work it affects, instead of letting it appear unannounced in the code. - A replacement for a complete organizational software development lifecycle (SDLC), security framework, compliance system, or operational and service-management process. Teams use ADEL to keep delivery decisions and evidence connected while those practices continue to govern their own areas. --- ## 1. Why a framework is needed Software teams often rely on information shared between people but never recorded where the project can keep using it. An architect may remember why a system boundary exists, a product owner may know which requirement matters most and a developer may know which checks must pass before a change is considered safe. This problem becomes more visible when work passes to an AI agent. An agent can use only the information it can access, such as project documents, source code, repository instructions, work items and connected tools. If an important requirement, decision, constraint or working rule exists only in someone’s memory, the agent cannot reliably find or apply it. ADEL assigns each kind of information to a responsible layer. The project records it where people and agents can access it and identifies the approver for important decisions. People and agents can then see what to change, why it matters, which rules apply and what evidence the work needs before it can close.

- **Risk** — What can go wrong? - **What it looks like** — How would we notice it happening? - **How ADEL helps** — What does the framework provide to reduce the risk?

### 1.1 People and agents cannot find the project knowledge they need Important requirements, rules, design decisions or instructions are unavailable, scattered or locked in one conversation, person or tool. #### Hidden project knowledge **What it looks like:** Important requirements, constraints, reasons behind design choices or working conventions exist only in people’s memory. A new team member or AI agent therefore cannot reliably find them. **How ADEL helps:** ADEL requires important project knowledge to be kept in records that future work can find: **Governance principles, product intent and requirements, the approved design, decision records and agent instructions**. #### Every prompt repeats too much project knowledge **What it looks like:** Every work item or AI prompt repeats large portions of project documentation because there is no clear way to find the sources of truth. Long prompts become difficult to maintain and may contradict one another. **How ADEL helps:** **Agent instructions** list where each source of truth is kept, so each work item can link to the information it needs instead of repeating it. #### Project knowledge depends on one tool **What it looks like:** Project knowledge becomes embedded in one AI agent’s prompt format, proprietary workflow or vendor-specific configuration, making it difficult to change tools or work without that agent. **How ADEL helps:** Project knowledge stays in **sources of truth that any tool can read**, such as repository files or pages in the project’s tracker. Tool-specific instructions only tell each agent where those sources are; they do not become another source of truth. ### 1.2 Implementation moves away from approved decisions Work continues without a clear connection to the intended outcome, project-wide rules or approved design. #### The latest prompt overrides the approved design **What it looks like:** Implementation follows the latest prompt rather than the approved design. Existing boundaries may be changed because the developer or agent cannot find why they exist. **How ADEL helps:** **Governance, System Design and its decision records** write down the project’s rules, design boundaries and the reasons for design choices, so they do not depend on what one prompt says. #### Implementation no longer matches the requirement **What it looks like:** Working code no longer maps cleanly to the original business need, intended outcome or acceptance criteria. A feature may technically work while solving the wrong problem. **How ADEL helps:** **Product Definition and traceability** connect the business need to requirements, design, implementation work and verification evidence. #### Architecture changes without review **What it looks like:** A developer or agent introduces a new library, pattern, dependency, data flow or boundary as if it were only a local implementation detail. **How ADEL helps:** **Governance, System Design, decision records and conflict rules** require an important architectural decision to be recorded and approved by its approver instead of appearing silently in code. ### 1.3 There is not enough evidence to close the work The delivered change cannot be traced to its purpose or supported by evidence that it meets the relevant requirements and acceptance criteria. #### Work is called complete too early **What it looks like:** Work is reported as complete because code was produced, tests passed or the application builds, even though some requirements, constraints or acceptance criteria were never verified. **How ADEL helps:** **Verification** checks the change against its requirements and acceptance criteria and keeps the evidence. Producing code, passing tests or building the application does not by itself complete the work. #### A change cannot be traced to its source **What it looks like:** Code exists but it is difficult to determine why it was introduced, which requirement it satisfies, which decision authorized it or how its correctness was verified. **How ADEL helps:** **Traceability** connects the original need, requirements, design decisions, implementation and verification evidence. --- ## 2. Core design principles These eight principles explain how to apply ADEL itself. They are not the same as a project’s Governance principles, which are the rules of one particular project. The principles below cover how ADEL separates responsibilities, records decisions, limits what agents may decide, requires evidence and adjusts to the project. ### 2.1 Separate intent from implementation Product Definition is responsible for the intended outcome and requirements. System Design and Execution are responsible for the design and implementation used to meet them. One record may contain both kinds of information when their responsibilities and approvers remain clear. If they are mixed without that distinction, people cannot tell where a change should be decided. ### 2.2 Keep decision responsibility clear across project records If two records describe the same decision differently, people and agents cannot tell which one to follow. A Product Definition record should not become an architecture document, and a work item should not silently redefine System Design. A summary may carry information needed for delivery, but it should identify its source of truth rather than become a second source for the same decision. ### 2.3 Keep project knowledge current and accessible Keep important requirements, principles, decisions, constraints and evidence in project records that the people and agents doing the work can reach. Do not leave them only in chat history. Retain each record for as long as the project or its legal, contract or audit requirements demand. When a person or agent cannot access an external source of truth, provide an approved copy of only the information needed for the work and identify its source. Do not copy the entire project into every work item. ### 2.4 Treat AI agents as capable contributors with clear decision limits Agents can inspect, implement and run checks, but they must not silently change approved requirements, System Design or Governance decisions. ADEL states which decisions belong to the agent’s assigned work; organization policy, access controls and tool permissions enforce what the agent can actually do. A repository instruction cannot grant permissions the agent does not have, and content returned by an external source is information to evaluate, not automatically an instruction to follow. ### 2.5 Write down important architectural decisions Write down an architectural choice and its reason when it significantly affects system structure, portability, security, maintainability or long-term cost. Keep them in the approved design or a decision record. Use a separate decision record when future work needs the choice, alternatives, consequences or history—not for every implementation detail. ### 2.6 Verify completion with evidence Do not treat work as complete because an agent says it is done. Check the acceptance criteria, run the required checks and keep the evidence. If a required check failed, was not performed or could not be performed, record that result. The work may close only if project policy allows an exception and the approver accepts it. Writing down a gap does not approve it, and rules that allow no exceptions still apply. ### 2.7 Use simple links for traceability Traceability can be lightweight IDs, links and references. The goal is to answer why a change exists, not to create paperwork for its own sake. ### 2.8 Adjust detail and controls to the project Use all six layers in every project. Adjust how much detail you write, how many records you keep, how strict approvals are and how much evidence you keep to fit the work’s risk, complexity, contributors and legal, contract or audit requirements. --- ## 3. Framework architecture Section 3 describes the structure of ADEL: where different kinds of project decisions and knowledge belong. It does not define a fixed sequence of work; Section 5 describes the delivery lifecycle. ADEL has six framework layers. Governance establishes the principles, decision authority and constraints that apply across delivery. The other five layers carry the decisions and project knowledge needed to move from Product Definition through Assurance. The Agent execution overlay is not a seventh layer; it provides agent instructions used across the framework. ### Layers, lifecycle and overlay These terms describe different parts of ADEL. A layer identifies the kind of decision it is responsible for. A lifecycle step describes what people and agents are doing at that point in the work. | Term | Meaning | | --- | --- | | Layer | A continuing responsibility for a particular kind of project decision and knowledge. A layer is not a phase that is completed once. | | Delivery lifecycle | The seven steps through which work is understood, defined, designed, prepared, implemented, verified and closed. A step may involve more than one layer. | | Agent execution overlay | Agent instructions that tell coding agents how to find and use project knowledge while following decision authority and enforced permissions. | ### 01 Governance — Project principles and policy *Common records: Engineering principles · Governance policy · Project charter · Constitution · Ways of working · Architecture principles.* **Question answered:** What project-wide rules must the work follow, and who may approve exceptions? **What this layer decides:** The boundaries and rules that apply to every piece of work across the lifecycle: security obligations, compliance constraints, technology standards, agreed ways of working and non-negotiable promises. It defines the limits within which all other layers operate. **Changes when:** A project-wide commitment or constraint changes, or the project formally adopts a new one. A coding agent that encounters a conflict with Governance cannot resolve it alone; it must stop and ask the Governance approver. **How it connects to other layers:** Governance is the foundation. It constrains every delivery layer and gives Assurance the rules against which work is checked. ### 02 Product Definition — Product intent and requirements *Common records: Product brief · Product requirements document (PRD) · Product specification · Feature specification · Requirements document · A product-management system.* **Question answered:** What must we build, for whom, and why? **What this layer decides:** What problem should be solved, for whom, what outcomes are expected, what is in or out of scope and what the product or capability must do. It decides **what the product must achieve or do**, not how the system will meet that outcome. **Changes when:** The business need, user outcome, scope, requirement, priority or acceptance criteria change. If design or implementation reveals that the requirement itself is incomplete or incorrect, the question returns to this layer rather than being resolved silently in code. **How it connects to other layers:** Product Definition turns the business need and governing rules into product intent and requirements. System Design uses those requirements to design the solution, and Assurance uses them to check the delivered result. ### 03 System Design — Approved design and decision records *Common records for the approved design: Architecture document · Technical design · Blueprint · Solution design · C4 or arc42 model.* *Common records for important decisions: Architecture decision record (ADR) · Request for comments (RFC) · Decision record · Decision log.* **Question answered:** How will the system work, and why did we choose that design? **What this layer decides:** How the system should meet the product requirements: architectural boundaries, component responsibilities, interfaces, data flows, integrations, important quality attributes and significant technical choices. It does not decide the detailed sequence of implementation work. **Changes when:** A requirement cannot be satisfied by the approved design, a design assumption changes, an architectural boundary must move or implementation exposes an important technical decision that was not previously resolved. Record a separate decision when its reasoning or consequences will matter later. **How it connects to other layers:** System Design takes the requirements from Product Definition and describes how the system will meet them. Delivery Planning and Execution must stay within the approved design. ### 04 Delivery Planning — Delivery plan *Common records: Delivery plan · Implementation plan · Work package · Epic · Handoff · Release plan.* **Question answered:** Which work is ready, in what order, and who will do it? **What this layer decides:** How approved work is split into work items, the order they happen in, what each one depends on and what is handed from one person or team to another. It does not change product requirements or the approved design. **Changes when:** The sequence, dependencies, delivery scope, assignee or conditions required to start the work change while the requirement and design remain valid. If planning keeps changing because the intended behavior or architecture is unclear, return the unresolved question to Product Definition or System Design. **How it connects to other layers:** Delivery Planning connects System Design to Execution. It turns clear requirements and an approved design into organized work without changing their boundaries. ### 05 Execution — Work item *Common records: Issue · Ticket · Story · Task · Repository work item · A concise instruction, for small changes.* **Question answered:** What exactly is being changed, and how will we know it is done? **What this layer decides:** The implementation choices needed to complete the current work within its requirements, design and constraints. These include code structure, implementation approach, test additions and configuration changes that do not redefine the product or architecture. **Changes when:** The work item changes when its scope, constraints, acceptance criteria, status or implementation information changes. Create or select one for each clearly scoped change and update it as implementation progresses. Its active use normally ends when the work closes; the project’s policy decides how long to retain it. If implementation would change the approved scope, requirement, acceptance criteria, design boundary or delivery assumption, return that decision to the responsible layer instead of changing it silently in code. **How it connects to other layers:** Execution turns a work item into code, configuration, migrations, tests, documentation or other deliverables. It follows the relevant decisions from earlier layers and produces results that Assurance can check. ### 06 Assurance — Verification evidence and traceability *Common records for verification evidence: Continuous integration (CI) and test results · Review findings · Verification report · Quality assurance (QA) sign-off · Release evidence · Verification record.* *Common records for traceability: Direct references · Central traceability table or matrix · Compliance mapping · Relationships an application lifecycle management (ALM) tool already holds.* **Question answered:** What evidence shows that the result works as required? **What this layer decides:** Whether the available evidence shows that the delivered change meets the relevant requirements, design decisions, governing constraints and acceptance criteria. Assurance also checks whether someone can follow the connections from intent through implementation to evidence. It records the verification result. If the project may close with an unresolved result, the approver must make that separate acceptance decision. **Changes when:** The implementation changes, an expectation changes, new verification evidence becomes available or a verification finding reveals a gap. Assurance should be revisited whenever a change could invalidate previously established evidence. **How it connects to other layers:** Assurance supports closure by checking the delivered result and recording the evidence. **Verification** checks whether the result met the relevant requirements and acceptance criteria. **Traceability** connects them to the design, implementation and evidence. Checks may happen throughout delivery, and a finding can return a decision to any earlier layer. ### ↔ Agent execution overlay — Agent instructions *Common records: AGENTS.md · CLAUDE.md · Copilot instructions · Cursor rules · Agent-instructions file.* **Question answered:** How should a coding agent work in this repository? **What this overlay decides:** How coding agents are expected to work in the repository: where each source of truth is kept, which instructions to follow first, what implementation conventions apply, which required checks to run and when an agent must stop and ask the approver. It does not define product requirements, architecture or project principles; it tells the agent how to work with those sources. **Changes when:** The repository structure, development workflow, required commands, agent rules or source-of-truth locations change. Update it when repeated agent mistakes show that an important instruction is missing or unclear. Do not change instructions used across the repository for one feature or work item unless that work introduces a repository-wide rule. **How it connects to other layers:** The Agent execution overlay applies whenever coding agents work in any layer. It must follow Governance and organizational policy, and it cannot grant access beyond the permissions enforced by the platform. It points agents to each layer’s sources of truth without replacing them. **How the project applies it:** ADEL does not automatically enforce agent behavior. A project applies the overlay by placing agent instructions where the coding agent will read them, giving the current work item clear boundaries and stop conditions, making the required project knowledge accessible, and limiting the agent’s tool permissions. Approvers resolve decisions outside the agent’s authority, while Assurance uses the required checks and evidence to determine whether the completed work followed the approved decisions. > **Governance and agent instructions serve different purposes** > > Governance sets project-wide rules. Agent instructions tell coding agents how to follow them. > > Governance defines the project-wide principles and constraints that people and agents must respect. Agent instructions turn those expectations into practical instructions for coding agents. A project may record the first in engineering principles, a constitution or a charter, and the second in AGENTS.md. ADEL defines their responsibilities, not their filenames. > > For example, a governing principle may state: “Authorization decisions must deny by default.” > > The agent instructions may then tell the agent: “Read the security architecture before changing authorization code, preserve deny-by-default behavior, and run the security test suite before declaring the change complete.” > > The project’s records hold its requirements, decisions, work and evidence. Agent instructions tell an agent where to find those records and how to use them. They should point to the relevant Governance principles, Product Definition, System Design, decision records, work items and verification practices instead of copying or replacing them. --- ## 4. Project knowledge and common records Project knowledge is the information a project preserves so people and agents can understand its intent, decisions, work and evidence without depending on memory or an earlier conversation. Each ADEL layer is responsible for a different kind of project knowledge. The Agent execution overlay carries agent instructions. Project knowledge is not another layer or lifecycle step. ### How the terms connect A layer or the Agent execution overlay identifies the responsibility. Project knowledge is the information that responsibility must keep available. A record is the document, ticket, page or tool entry that keeps it. For example: | Layer | Project knowledge | Possible record | | --- | --- | --- | | Product Definition | Product intent and requirements | Product brief or product requirements document (PRD) | > **What ADEL defines, and what it does not** > > ADEL defines the responsibility of each layer and the Agent execution overlay, together with the project knowledge each one needs. It does not prescribe what your organization calls the record that holds that knowledge. A record may be a document, ticket, page or tool entry. The names and filenames in this section are examples. If an existing source already carries the right information and approval, keep it and its current name. ### Overview of project knowledge Use this overview to see what project knowledge each layer or the Agent execution overlay is responsible for, what it is for and when it is usually updated or retained. Open an item to read what it contains, what does not belong there and common ways to record it. | ADEL layer or Agent execution overlay | Project knowledge | What it is for | Usually kept or updated | | --- | --- | --- | --- | | Governance | Governance principles | Keeps project-wide principles, rules and decision authority. | Updated when a project-wide rule or decision-authority rule changes | | Product Definition | Product intent and requirements | Defines the problem, users, outcomes, scope and requirements. | Updated when product intent, scope or requirements change | | System Design | Approved design | Explains how the system is intended to meet the requirements. | Updated when the approved design changes | | System Design | Decision record | Keeps an important architectural decision and the reason for it. | Retained as decision history; status changes if replaced | | Delivery Planning | Delivery plan | Organizes an approved part of the design for implementation. | Used for the delivery scope or release it describes | | Execution | Work item | Defines one clearly scoped piece of work. | Active until the work closes; retained as project policy requires | | Assurance | Verification evidence | Shows what was checked and whether the result met expectations. | Added or updated when the checked result changes | | Assurance | Traceability relationships | Makes the connections from the original need to verification evidence easy to follow. | Updated as requirements, work and evidence change | | Agent execution overlay | Agent instructions | Provides standing instructions to coding agents. | Updated when repository-wide agent instructions change | ### Project knowledge in detail The entries below explain the same project knowledge shown in the overview. “Common records” lists documents or systems that may carry the information. “Possible names” gives example filenames when the project stores it in a file. #### 4.1 Governance principles **ADEL layer or Agent execution overlay:** Governance Governance principles keep the rules, constraints and decision authority that must remain consistent across features, contributors and agent sessions. Write them as clear statements that people can apply to decisions and, where practical, verify. Use terms such as MUST, MUST NOT and SHOULD only when the project needs to show how strongly a rule applies. Examples include architectural independence, security and data rules, supported platforms, accessibility baselines, testing principles and decision authority. If the principles are kept in a dedicated source, retain a history of significant changes. Changing a principle is a Governance decision, not a detail to introduce quietly through a feature or implementation work item. - **Contains:** Purpose and scope; core principles and rationale; project-wide boundaries; decision and exception authority; change history. - **Does not belong here:** Feature details; library versions; step-by-step implementation instructions. - **Common records:** Engineering principles · Governance policy · Project charter · Constitution · Ways of working · Architecture principles - **Possible names:** project-principles.md · governance.md · principles.md · constitution.md · charter.md - **Where it lives:** docs/governance/ · or the repository root #### 4.2 Product intent and requirements **ADEL layer or Agent execution overlay:** Product Definition Product intent and requirements preserve the problem, intended users, required outcomes, scope, constraints and measures of success. Together they carry the project’s Product Definition. This information should be understandable to business, product, design and engineering participants. A technical constraint belongs here when it is a genuine product requirement, but Product Definition does not choose the low-level implementation. - **Contains:** Problem and users; outcomes and success measures; scope; functional and quality requirements; acceptance criteria; assumptions and dependencies. - **Does not belong here:** Detailed class structure; database-specific implementation; coding conventions. - **Common records:** Product brief · Product requirements document (PRD) · Product specification · Feature specification · Requirements document · A product-management system - **Possible names:** product-brief.md · product-definition.md · prd.md · requirements.md · product-spec.md - **Where it lives:** docs/product/ · docs/specs/ #### 4.3 Approved design **ADEL layer or Agent execution overlay:** System Design The approved design explains how the system is expected to meet the product requirements. It describes the main components, boundaries, data flows, integrations, system-wide needs and architectural qualities the implementation must preserve. Include enough detail for different people or agents to make consistent architectural choices. It does not need to prescribe every class, function or line of code. - **Contains:** Design goals; components and boundaries; data and interaction flows; integrations; quality needs; deployment, rollout and recovery; requirement links. - **Does not belong here:** Historical rationale for every decision; work-item checklists. - **Common records:** Architecture document · Technical design · Blueprint · Solution design · C4 or arc42 model - **Possible names:** system-design.md · architecture.md · blueprint.md · design.md - **Where it lives:** docs/architecture/ · or the repository root #### 4.4 Decision record **ADEL layer or Agent execution overlay:** System Design A decision record keeps the background, selected option, alternatives, consequences and reasoning behind an important architectural choice. Create one when future work will need to understand that reasoning after the current conversation or work item ends. An important decision can arise during design, implementation, migration or incident follow-up; decision records are not limited to one lifecycle step. Keep an accepted record as part of the project’s history. If a later decision replaces it, mark the earlier record as replaced and update the approved design where necessary. - **Contains:** Background; decision; alternatives; consequences; status; replacement links. - **Does not belong here:** Broad product requirements; implementation backlog. - **Common records:** Architecture decision record (ADR) · Request for comments (RFC) · Decision record · Decision log - **Possible names:** 0001-.md · adr-0001-