# ADEL Playbook **The Playbook.** Practical ways to apply ADEL to real work. Situational guidance for real projects: starting one, adopting ADEL on a codebase that already exists, running a change, preparing work for a coding agent, and supporting completion with evidence. Author: Mark A. Basco Playbook: Framework: © 2026 Mark A. Basco. This ADEL material is licensed under CC BY-NC 4.0 with additional permission for delivery work. Full terms: . --- ## Start here **Use the Playbook for the situation you’re in.** The Framework explains how ADEL works. This Playbook shows practical ways to apply it to real projects. It does not add mandatory steps, documents, or tools. You do not need to read the Playbook in order. *The Playbook exists to make ADEL easier to apply, not to add another process. Use only the guidance that helps with the situation in front of you.* Project knowledge is the information a project keeps so people and agents can find its requirements, decisions, work and evidence. A source of truth is the record the project treats as correct for a particular decision or kind of information. An approver is the person, role or approval process allowed to accept or change a decision. The Agent execution overlay is the guidance that tells coding agents where to find project knowledge, how to work in the repository and when to stop. - **Framework** — Understand ADEL’s layers, lifecycle and rules - **Playbook** — Apply ADEL in common situations - **Templates** — Use starter structures for project records ### Choose how to begin - **New to ADEL?** Follow one small project from idea to verified implementation, with the prompts and project records shown where they are used. — Work with ADEL - **Already working on something?** Jump straight to the situation you are dealing with. — Find your situation ### What are you trying to do? | Situation | Where to go | | --- | --- | | **Start a new project** — Establish enough shared project knowledge for people and agents to understand what is being built and what constrains it. | [Starting a new project](#1-starting-a-new-project) | | **Adopt ADEL in an existing project** — Understand what already exists, identify each source of truth, and add only what is missing or unclear. | [Adopting ADEL on an existing project](#2-adopting-adel-on-an-existing-project) | | **Make a change** — Find the relevant intent and design, prepare the project knowledge the change needs, implement it, then verify the result. | [Applying ADEL to a change](#3-applying-adel-to-a-change) | | **Prepare work for a coding agent** — Give the agent a clearly scoped work item and links to the project knowledge it needs. | [Preparing work for a coding agent](#4-preparing-work-for-a-coding-agent) | | **Introduce ADEL to a team** — Match the team’s existing documents, tools and practices to ADEL before changing anything. | [Adopting ADEL on an existing project](#2-adopting-adel-on-an-existing-project) | | **Verify and trace completed work** — Check the result against its requirements and evidence, then make the links from intent to implementation and evidence easy to follow. | [Verification in practice](#9-verification-in-practice) | --- ## 1. Starting a new project **When you’re here.** You are starting a project and want enough shared project knowledge in place before implementation begins. A new project does not need every example record on day one. Record enough shared project knowledge for people and agents to understand what is being built, which decisions are approved and which questions remain open. ### Step 1 · Understand the need Capture enough to explain: - the problem or opportunity - affected users and stakeholders - the desired outcome - important constraints - what success means Do not turn this into a complete specification yet. The goal is to understand enough to establish the project’s initial intent. ### Step 2 · Establish project knowledge used across changes Make lasting project knowledge easy to find. Reuse existing sources of truth where they already work; otherwise start with concise records for information that will remain relevant across many changes. What matters is that each source of truth is clear and accessible, not what the file is called. | ADEL layer / Agent execution overlay | Typical record | Start by recording | | --- | --- | --- | | Governance | Governance principles — often a constitution, engineering principles or a project charter | The project-wide principles and constraints that apply to every part of the project | | Product Definition | Product intent and requirements — often a product requirements document (PRD), product brief or requirements document | Problem, users, scope, required outcomes, and how success will be judged | | System Design | Approved design — often a blueprint, architecture document or technical design | Major boundaries, responsibilities, flows, constraints, and unresolved design questions | | Agent execution overlay | Agent instructions, when coding agents are part of the workflow — often AGENTS.md | Where sources of truth are kept, operating rules, required commands and when to stop and ask | ### Step 3 · Create additional records only when needed - **Decision record** — Record an important architectural decision when future work will need to understand why it was made. An architecture decision record (ADR) is one common format. - **Delivery plan or handoff record** — Use one when work must be coordinated or transferred between people, agents, teams or releases. - **Work item** — A work item may be a task, issue, ticket or instruction for one clearly scoped piece of work. Use a separate record when its scope, constraints and acceptance criteria must remain available after the current conversation or agent session, or to someone who cannot access the tracker. - **Verification record** — Use one when the verification result must remain available beyond the evidence already kept by project systems. - **Central traceability table** — Use one when people can no longer follow the relationships through direct references, or when legal, contract or audit rules require one shared view. Some project knowledge remains relevant across many changes. Create the additional records only in the situations listed above. ### Step 4 · Check that the project is ready for its next decision or work item - the problem and intended outcome are understandable - important governing constraints are easy to find - the main system parts and boundaries are clear enough to guide the next decision - people and agents can find the sources of truth they need - unresolved questions are visible rather than silently assumed **You do not need every answer before work begins. You need enough shared understanding to know what is decided, what is still open, and where the next decision belongs.** --- ## 2. Adopting ADEL on an existing project **When you’re here.** You are introducing ADEL to a project that already has documentation, tickets, code and conventions. An existing project usually has useful project knowledge already—in documentation, tickets, code, tests, conventions or external systems. Before creating anything new, identify what information and decisions the project already has and where they are kept. **Before writing new records, identify what the project already has and how it maps to ADEL.** > **Playbook guardrail** > > Keep the project’s existing records and match them to ADEL’s layers. Add or reorganize records only when important information is missing, conflicting, inaccessible or unclear. (Framework: §11 Adopting ADEL · §8.2 Judge a record by its content, not its filename.) ### Step 1 · Inventory what already exists Look across everything the project has accumulated, not only the files that look like documentation. - documentation - tickets and issues - architecture records - source code - tests and continuous-integration (CI) results - policies and conventions - agent instructions - external project systems ### Step 2 · Determine what each source holds and whether it is the source of truth Identify the information, decision, instruction, implementation or evidence each record holds. Then match it to the ADEL layer or Agent execution overlay it supports. A wiki page, a ticket and a task may all repeat the same requirement, but only one should be its source of truth. - What information or decision does it carry? - Which ADEL layer or the Agent execution overlay does that belong to? - Is this the source of truth for that decision? ### Step 3 · Check whether it is current, accessible and usable A stale source of truth can be more damaging than a missing one, because people and agents may continue to trust it. - Is it current? - Can the people who need it reach it? - Can relevant agents reach it? - If direct access is not allowed, does the work item contain enough approved information? - Can the relevant portion be found without loading or copying everything? ### Step 4 · Identify gaps and conflicts When two records disagree, identify what kind of decision is in conflict and resolve it at the ADEL layer responsible for that decision. Do not assume that the newest record or the existing code is automatically correct. - important information that exists only in memory or in the code - duplicate sources of truth - stale documentation - disagreement between sources ### Step 5 · Change only what improves the project Update, add, connect, split or remove information only when doing so makes the source of truth, approver, access or meaning clearer. Creating a record that duplicates a source the team already trusts makes the project harder to navigate. ### Map what you already have Work through the project one source at a time. These rows are illustrations of the exercise, not a lookup table. | Record | Information it holds | ADEL layer or Agent execution overlay | Source of truth? | Current? | Accessible? | Action | | --- | --- | --- | --- | --- | --- | --- | | Product specification | Product requirements | Product Definition | Yes | Yes | Yes | Keep | | system-design.md | System architecture | System Design | Yes | No | Yes | Update | | Epic in the tracker | Requirement and delivery scope | Product Definition / Delivery Planning | Partly | Yes | People only | Link to it; copy only the approved information an agent needs into its work item | | Issue | Current work item | Execution | Yes, for the work | Yes | Yes | Keep | | CI run | Automated test evidence | Assurance | Yes, for raw evidence | Yes | Yes | Link | | Existing agent instructions | Agent instructions | Agent execution overlay | Yes | Yes | Yes | Keep and reconcile | > **Map by content, not by name** > > The source name does not determine the mapping. A tracker epic may hold product requirements, delivery scope, acceptance criteria or all three; a contributing guide may hold human conventions and no agent instructions at all. Inspect what the source holds and whether the project treats it as a source of truth. ### You are ready to continue when - you know where important project knowledge currently lives - you know the source of truth for each decision - important stale or conflicting sources are identified - when approval, acceptance or an exception may be required, the approver or approval process is easy to find - people and agents can reach the project knowledge they need - important missing knowledge has been identified - you have not created duplicate documents only to match ADEL examples **You do not need to clean up the entire project before using ADEL. Fix the gaps and conflicts that matter to the work in front of you, and improve the project as new work passes through it.** --- ## 3. Applying ADEL to a change **When you’re here.** You have a change to make, of any size, and want to know which parts of the model it actually touches. ADEL applies to both small changes and substantial system changes. Start from the project knowledge that already exists, and add or update only what the change affects. > **Framework rule** > > Return each affected decision to the layer responsible for it and update its source of truth before continuing. One finding may affect several decisions. ### The framework lifecycle, applied to one change There is one ADEL lifecycle. These are its seven steps, shown here for a single change. 1. **Understand the need** — Understand what is being requested and why. 2. **Define the required outcome** — Find or clarify the relevant requirement, expected behavior or acceptance criterion. 3. **Design the solution** — Use the existing design where it already covers the change. Update it only when the change actually affects System Design. 4. **Prepare the work** — Determine the scope, dependencies, order of work, rollout, and whether a separate delivery plan or handoff record is needed. 5. **Break down the work as needed** — Decide whether the change fits in one clear work item. Create a separate work-item record only when its scope, constraints and acceptance criteria must remain available after the current conversation or agent session, or to someone who cannot access the tracker. 6. **Implement the change** — Make the change within the relevant requirements, design, decisions and constraints. 7. **Verify and close** — Check the result against the relevant requirements, acceptance criteria, governing rules and required checks. Keep the evidence and links when future work or review will need them. > **Reuse before creating** > > A change usually uses existing project knowledge before it creates any. Existing requirements, design, decisions and agent instructions remain valid unless the change changes them. Update a project record when its decision changes or when it becomes inaccurate, unclear or difficult to use. Do not rewrite unrelated records merely because a change used them. **Current change** uses: Governance principles · Relevant requirement · Relevant approved design · Relevant decision records, if any. ### What changes as the work gets larger Every change uses the same ADEL layer responsibilities. A small change may use almost entirely existing project knowledge; a larger change may require new decisions, planning, records and evidence. #### Tiny change *Rename “Create account” to “Sign up”.* **Usually relies on** - existing project knowledge - a clear instruction or issue - implementation - the checks required for this change **Usually does not create** - a separate decision record - a handoff - a separate work-item record - a separate verification record It uses the existing requirements, approved design and governing rules that apply; it does not recreate them. #### Normal feature *Add password reset.* **Usually relies on** - a clear required outcome - the relevant approved design - a clearly scoped work item - the tests and other checks required for this feature - links that make the path from intent to implementation and evidence easy to follow **Usually does not create** - a separate decision record, unless an important architectural decision arises - a handoff Use a separate work-item record when this information must remain available after the current conversation or agent session, or to someone who cannot access the tracker. An existing issue or ticket may already meet that need. #### Architecture-affecting change *Move authentication to an external identity provider.* **Usually relies on** - a review of the relevant Product Definition - an update to the approved design - a decision record when future work will need the reason for an important architectural decision - a delivery plan that covers the affected work, dependencies and rollout - clearly scoped work, potentially across several work items - verification across the affected requirements and design constraints - traceability across the affected requirement, decision, work, implementation and evidence Product Definition changes only if the required outcome, scope, behavior or acceptance criteria also change. Moving a system boundary is a System Design change even when the required outcome stays the same. **All three changes use the same layer responsibilities. Larger changes need more new decisions, records, planning and evidence.** --- ## 4. Preparing work for a coding agent **When you’re here.** You are about to give a clearly scoped work item to a coding agent. Before giving work to a coding agent, make sure it can find the project knowledge that applies to the change. Do not copy all project knowledge into the prompt. Give the agent a clearly scoped work item and links to the relevant sources of truth. ### Before implementation, the agent should be able to find - relevant Governance principles - the relevant requirement or intended outcome - the relevant approved design - relevant decision records - the current work instruction, issue or work item - required check commands - relevant acceptance criteria - where approval, acceptance or an exception may be needed: the approver or approval process ADEL does not automatically control the agent. Agent instructions and the current work item state what it may change, where it should find approved decisions and when it must stop. Tool permissions limit what it can actually do. The project must also identify the approver or approval process for decisions outside the agent’s authority. A solo developer may be the approver for several kinds of decisions. ### Give the agent direct references to the project knowledge it needs AGENTS.md helps the agent navigate the project. The current work item defines the scope of the change and points to the sources of truth that apply. **Project-knowledge map.** AGENTS.md → Current work item → references to only what applies. - **AGENTS.md** — How to navigate the project, work in the repository, run the required checks and know when to stop and ask. - **Current work item** — What is changing, what is in and out of scope, and when the agent must stop. - **Requirement / outcome** — Why the change exists and what it is expected to achieve - **Approved design** — Where the change belongs and which boundaries it must preserve - **Relevant decision records** — Earlier design decisions that constrain the approach - **Acceptance criteria** — What the result needs to demonstrate - **Required checks** — Which tests, builds and checks should be run The current work may be a task, issue, ticket or concise instruction. Use whichever record already holds enough information and clear boundaries. > **Framework rule** > > 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. > **Do not turn this into a giant prompt** > > The goal is not to copy every relevant record into the agent’s prompt. Give the agent a clear work item and a reliable way to reach the sources of truth it needs. ### Do not solve a missing decision with a bigger prompt A more detailed prompt does not replace a missing requirement or unresolved design boundary. If the work requires the agent to decide what the product should do, whether a boundary should move, or whether a constraint can be relaxed, return that decision to the responsible layer. > **Playbook guardrail** > > If the agent cannot proceed without making a product, architecture or governance decision it is not allowed to make, resolve that decision at the responsible layer before implementation continues. (Framework: §2.4 Treat AI agents as capable contributors with clear decision limits · §6 Source of truth and conflict handling.) ### The work is ready for an agent when - the agent knows what outcome it is responsible for - the scope and boundaries of the change are clear - it can find the relevant requirements and design - important existing decisions are easy to find - required checks are known - the repository areas, tools and actions it may use are clear - its stop conditions are clear - it knows which approver or approval process should receive a conflict or unresolved decision --- ## 5. Give each work item the project knowledge it needs **When you’re here.** A source of truth is long or spread across several systems, and the current work needs only part of it. A person or agent may be able to open a source of truth but still struggle to find the part needed for one change. The work item should point to the exact sections and decisions that apply. > **Framework rule** > > 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. Keep the source of truth complete. In the work item, identify only the sections and decisions that apply. Give the person or agent enough information to continue without searching through or reconstructing the whole project. | Do this | Instead of | | --- | --- | | Reference sources of truth | Copy the entire knowledge base into every work item, handoff or prompt | | Point to the relevant requirement, section, decision or part of the system | Link to a large source without saying what part applies | | Copy only the information needed for the work when direct access is unavailable or not allowed | Paste the whole source because part of it is relevant | | For coding agents, use AGENTS.md as a map into deeper sources | Turn AGENTS.md into the knowledge base itself | | Keep large sources easy to navigate by section, product area or part of the system | Leave important project knowledge in one unstructured block | | Identify a copied source and, when later changes matter, record the version, date or other reference used | Copy information without recording where or when it came from | ### One change, two ways to identify the project knowledge it needs The work changes how long a user can remain signed in without activity. Here, NFR means non-functional requirement. *No useful direction* ```text Read all product requirements, the complete approved design, every decision record and all security documentation. ``` *Focused references* ```text Product requirement: NFR-07 Approved design: Authentication §4.3 Decision record: ADR-011 Security policy: Session management §2 Required check: authentication integration suite ``` **Each source of truth stays complete. The work item points directly to the parts needed for this change.** --- ## 6. Passing work between people and agents **When you’re here.** Work is changing hands — between people, between agents, or across the two. When work moves to another person or agent, the next participant must be able to find the current scope, relevant decisions, completed work and remaining questions. Information kept only in someone’s memory or a temporary session can be lost during the transfer. > **Framework test** > > Will the next person or agent still be able to find the decision, information or conclusion after the current conversation, meeting, continuous-integration (CI) run or work session is over? ### Who does the work may change ```text Person → Person Person → Agent Agent → Person Agent → Agent ``` The framework does not prescribe who performs the work. The next person or agent must be able to find the information needed to continue without guessing decisions or repeating work. ### Information the next person or agent needs When someone else takes over — person or agent — they should be able to determine: - **What is being done** — The current objective and the boundaries of the work item. - **Why it matters** — The relevant requirement or intended outcome. - **What constrains it** — Relevant Governance principles, the approved design and accepted decision records. - **What has already happened** — Work completed, decisions made and relevant findings. - **What remains open** — Unresolved questions, blockers and known risks. - **How completion will be judged** — Acceptance criteria and required checks. - **Where the sources of truth are** — References to those records, rather than a copy of the project’s history. ### Use the record that matches the need | When this happens | Which record may hold the information | | --- | --- | | A small, clearly scoped change moves to another person or agent | An existing issue, instruction or task may be enough | | Delivery scope or sequencing transfers between teams or releases | Use a delivery plan or handoff record to keep the transferred scope, sequence and dependencies | | Implementation pauses and another person or agent continues | The current work item, plus completion notes | | An important architectural decision arose | An architecture decision record (ADR) | | Verification work changes hands | Use referenced evidence; add a verification record when the result must remain available beyond the existing evidence system | > **A transfer does not always need a handoff record** > > A transfer does not require a separate handoff record by itself. Use one when a delivery plan must be transferred between people, agents or teams, or kept across releases or work sessions. Otherwise, use the existing record that holds the information the next person or agent needs. > **The common failure** > > Do not use conversation history as the primary handoff record. If information must remain available after the transfer, keep it in the record responsible for that information or reference its source of truth. Conversation history may help explain what happened, but it should not be the only place the project keeps the information. ADEL identifies the project knowledge that must remain available after a handoff. The project chooses how to assign or transfer the work. --- ## 7. Managing records over time **When you’re here.** You want to know when a record is created, when it changes, and what happens to it afterwards. Different project records change at different times. Keep records used across many changes current as the project changes. Create other records only when a decision, handoff, work item or verification result needs to be kept. Existing sources of truth can follow the same pattern without being renamed or recreated. ### Records used across many changes These describe the project across many changes. The table below shows when they are commonly created or updated. The project decides how long to keep each record. | Record | Establish when | Update when | | --- | --- | --- | | Governance principles — often a constitution or charter | Project-wide Governance principles need to be recorded | A governing principle or governance rule changes | | Product intent and requirements — often a product requirements document (PRD) or product brief | Product intent and requirements need to be recorded | Product intent, scope, a requirement or acceptance criteria change | | Approved design — often a blueprint or architecture document | The approved design needs to remain available for future work | The approved design changes | | Agent instructions, when agents are used — often AGENTS.md | Coding agents need agent instructions that remain available between sessions | Repository navigation, working rules, required checks or source locations change | ### Records created when needed Create these only when the work produces the corresponding need. | Record | Create when | Update or close when | | --- | --- | --- | | Decision record — often an architecture decision record (ADR) | Future work will need the reason for an important architectural decision | Its status or replacement changes; retained as decision history | | Delivery plan or dedicated handoff record | A delivery plan must be transferred, coordinated or preserved | Delivery scope, conditions required to start, sequencing or dependencies change | | Work item — often a task, ticket or issue | A clearly scoped work item must remain available outside the current tool or session | Scope, constraints or acceptance criteria change; closed according to project workflow | | Verification record | The verification result must remain available beyond the evidence already kept by project systems | Evidence, findings or verification status changes | | Central traceability table or matrix | People can no longer follow the relationships through direct links easily | Relationships change; maintained only while it remains useful | ### Record lasting decisions before temporary information disappears Closing a work item does not automatically mean discarding useful information. When the work produces a decision or finding that future work will need, update the source of truth in the responsible layer before the temporary record closes. - **What happened** — A task reveals an important architectural decision. - **What not to do** — Leave the decision only in the closed task. - **What to do** — Update the approved design or create a decision record, reference it from the task, then close the task. > **The project decides how long to keep records** > > The Framework defines what these records preserve. The project decides how to archive, combine, retain or remove them according to its working practices and any legal, contract or audit requirements. --- ## 8. How much detail is enough **When you’re here.** You are writing or reviewing something and want to know whether it is enough. Enough detail is not a page count. Each ADEL layer has enough detail when the people or agents relying on it can answer that layer’s primary question without inventing decisions that belong elsewhere. > **Framework rule** > > 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. Ask whether the information lets the next person or agent make the required decision or perform the work without guessing. Length is not the measure. ### Governance — What project-wide rules must the work follow, and who may approve exceptions? **Sufficient when** - the project-wide principles and constraints that actually govern the project are recorded - people and agents can tell what lower-level decisions are not allowed to override - important quality, security and governance rules can be found - it is clear how a governing rule is changed and who approves the change *Can someone tell which project-wide rules the work must follow and who may approve exceptions?* ### Product Definition — What must we build, for whom, and why? **Sufficient when** - the problem, intended users and desired outcome are understandable - scope is clear enough to distinguish what is and is not being built - relevant functional and non-functional requirements can be found - success measures and acceptance criteria are clear enough to judge the result *Can someone tell what the project or change is expected to achieve?* ### System Design — How will the system work, and why did we choose that design? **Sufficient when** - important boundaries and responsibilities are understandable - the person or agent doing the work can determine where a change belongs - relevant flows, integrations and architectural constraints can be found - important design choices are recorded rather than left to accidental implementation - unresolved design questions are visible where they matter Decision records are part of this test rather than a separate one. If future work will need the reason for an important decision, the approved design is not sufficient until that reason has been recorded. *Can someone explain how the system will work and why the important design choices were made?* ### Delivery Planning — Which work is ready, in what order, and who will do it? **Sufficient when** - the portion of work being prepared is clear - dependencies that affect when or how the work starts are understood - delivery boundaries, rollout, migration or handover considerations are visible where they matter - unresolved blockers are known - the work can be divided into clear work items without redefining the product or architecture This does not mean every change needs a handoff. For small work, the existing work item may already hold everything Delivery Planning needs. *Can the approved design be turned into work without making the implementation team guess the scope, dependencies or order of work?* ### Execution — What exactly is being changed, and how will we know it is done? **Sufficient when** - the person or agent doing the work understands the expected outcome and the limits of the work item - scope and out-of-scope boundaries are clear enough to prevent accidental expansion - the relevant sources of truth can be reached - relevant constraints and decisions are easy to find - acceptance criteria and required checks are known - the person or agent can proceed without inventing Product Definition, System Design or Governance decisions A task, issue, ticket or concise instruction may carry this work-item information. *Can a person or agent complete this work item without having to guess what the project intended?* ### Assurance — What evidence shows that the result works as required? **Sufficient when** - relevant requirements, acceptance criteria, governing rules and required checks have supporting evidence - failed, unverified and unable-to-verify areas are explicit - important findings and deviations are visible - the available evidence supports the claimed completion result - people can follow the links between intent, implementation and evidence with the detail the project needs Verification should happen before completion is claimed. Use a separate verification record only when the result must remain available beyond the existing evidence. Add a central traceability table only when direct references are no longer easy to follow or when project rules require one. *Can the project show what was delivered, which requirement or check it was compared with, and what evidence supports the result?* ### Agent execution overlay — How should a coding agent work in this repository? **Sufficient when** - an agent can locate the sources of truth it needs - repository or workspace operating rules are clear - commands for the required checks are easy to find - the agent knows which instructions to follow first and when to stop and ask - the agent instructions stay concise enough to guide the agent without duplicating all project knowledge *Can an agent find the relevant project knowledge, follow the repository rules and know when to stop and ask the approver?* **Add detail when a person or agent would otherwise need to guess, when an important decision must be kept, when information is hard to find, or when more evidence is needed. Otherwise, the extra detail only creates more maintenance work.** --- ## 9. Verification in practice **When you’re here.** Implementation exists and you are deciding whether the work can be called complete. Verification is more than running checks. The evidence must show whether the delivered work meets its requirements, acceptance criteria, governing rules and required checks. > **Framework rule** > > 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. ### Four questions before claiming completion Answer these four questions during verification. They do not add four more steps to the ADEL lifecycle. 1. **Identify what the result must meet** — Which requirement, acceptance criterion, design constraint, governing rule or required check applies? 2. **Compare the delivered result** — Does the implementation meet that requirement or acceptance criterion, and does it stay consistent with the relevant design and constraints? 3. **Evaluate the evidence** — What evidence supports the result, what does it establish and, when important, does it identify the revision, build or environment actually evaluated? 4. **Determine the result** — What is verified, what is not, and what could not be verified? Are findings, risks and gaps recorded, and has the approver accepted any required exceptions? > **Passing checks are not the conclusion** > > A passing test suite is evidence only for what those tests actually checked. Compare every relevant requirement and acceptance criterion with the available evidence, and record anything that was not checked or did not pass. > **Playbook guardrail** > > Verification happens before completion is claimed. A separate verification record is a different question: the pull request, the CI run, the work item or a completion note may already keep the result and its evidence. Create a dedicated record only when none of those sources keeps the result for as long as the project needs it. (Framework: §4.7 Verification evidence · §8.6 Use the smallest record structure that works.) ### Evidence may include Not every check applies to every change. Choose verification based on the relevant requirement, risk, governing constraints and required checks—not because an item appears in a list. Changing a button label and moving sign-in to a new provider should not use the same verification by default. - automated test results - continuous-integration (CI) results - manual observations - review findings - static-analysis results - security test or assessment results - performance measurements - accessibility evaluation results - migration validation results - operational or runtime observations, when relevant ### Record the conclusion honestly For each requirement, acceptance criterion, governing rule or required check, record what the evidence actually shows. Use whatever status names the project already uses; the differences between the results below matter more than the labels. Keep the conclusion on the work item, in completion notes linked to CI, or in a separate record. - **Verified** — Available evidence supports the requirement, criterion, rule or required check. - **Failed** — Evidence demonstrates that a requirement, criterion or rule was not met, or that a required check ran and did not pass. - **Not verified** — Available evidence is incomplete, or the check was not performed. - **Unable to verify** — Verification could not be performed with the available access, environment, data, tooling or other required condition. > **Do not upgrade uncertainty** > > Do not convert “Unable to verify” into “Verified” because the implementation looks reasonable. Keep the three unsuccessful states separate: one says a check ran and did not pass, one says the evidence is incomplete or the check was not performed, and one says the check could not be run. An approved exception does not change any of them—a failed check stays failed. ### Then the overall result If the project records an overall verification result, preserve the same distinctions. ADEL’s starter verification template uses Verified, Verified with findings, Failed, Not verified and Unable to verify as example terms; projects may use equivalent terms. Acceptance remains a separate decision. | Result | Meaning | | --- | --- | | Verified | The relevant requirements and criteria are supported by sufficient evidence. | | Verified with findings | Evidence supports the relevant requirements and criteria, with findings or limitations stated for the work that was checked. | | Failed | Evidence demonstrates that a relevant requirement, criterion, rule or required check was not met. | | Not verified | Available evidence is incomplete or insufficient to establish the result. | | Unable to verify | The evidence needed to assess the result could not be obtained. | > **Acceptance is a separate decision** > > The verification result says what the evidence shows. Whether work may close despite an unmet requirement is a different decision. Project policy must permit an exception, and the approver must accept it with a reason and any follow-up work. Rules that allow no exceptions still apply. Accepting an exception does not change the verification result: a failed or unperformed check stays recorded as one. ### Two requirements from one change | Requirement | Evidence | Result | | --- | --- | --- | | A valid contact-form inquiry must reach the firm’s shared inbox. | A test inquiry reached the test inbox in preview build demo-57. | **Verified** | | The form provider must not retain inquiry content after delivery. | The provider’s production data-retention settings were not accessible in the test environment. | **Unable to verify** | **The second is not a failure and not a pass. Recording it as either would misrepresent what the project knows.** --- ## 10. Traceability in practice **When you’re here.** You want people to be able to follow the links from intent to evidence. Traceability means keeping the links between intent, design, work, implementation and evidence easy to follow. Direct references are often enough. Add a shared traceability view only when people can no longer follow those references or when project rules require stricter control. > **Framework rule** > > Traceability can be lightweight IDs, links and references. Do not create a central traceability view while these links remain easy to follow. Start with direct references. Add a shared traceability view only when those relationships become difficult to follow. ### Leave references as you work These are relationships, not required filenames. A project may keep them in product requirements, an approved design, a decision record, a task or issue, a pull request, continuous-integration results or any other system that holds a source of truth. ```text Need / outcome ↓ Requirement ↓ Approved design — Decision record, when needed ↓ Work item ↓ Implementation ↓ Verification evidence ``` ### What the references can look like Each record links to the earlier record that explains it. To find later records connected to a requirement, use repository search, tracker backlinks or links held by another system. Add a shared traceability view when those methods no longer show the complete path. In this example, BN means business need, FR means functional requirement and ADR means architecture decision record. ```text FR-12 Supports: BN-03 Approved design §4.2 Meets: FR-12 Decision record ADR-004 Applies to: FR-12; Approved design §4.2 Issue #21 Implements: FR-12 Design: Approved design §4.2 Decision: ADR-004 Pull request (PR) #37 Closes: #21 Verification Verifies: FR-12 Evidence: continuous integration (CI) run #1842 ``` ### Choose the traceability approach that fits These are three ways to keep traceability, not levels a project must complete in order. Choose the lightest approach that keeps the relationships easy to follow. Controlled traceability is required by legal, contract, audit or safety needs—not by project size. A small regulated system may need it from the first day. | Approach | When it fits | Notes | | --- | --- | --- | | Direct references | People can follow the relationships through the connected records | Often sufficient | | Shared traceability view | Relationships span enough records, contributors or systems that direct references no longer show the whole picture | Adds one shared view of the relationships | | Controlled traceability | Audit, safety, regulation or another project rule requires reviewed relationships and evidence | Use when legal, contract, audit or safety requirements demand it | ### Test it in both directions - **Forward** — Starting from a requirement, can you find the relevant design, work item, implementation and evidence? - **Backward** — Starting from an implementation change, can you find the work item, requirement and reason for the change? If people can follow both paths with the detail the project needs, the traceability is working. Adding identifiers everywhere is not enough when the links between records are still unclear. > **Before adding a shared traceability view** > > Do not add a shared traceability view just because a template exists. Add one when people can no longer follow the relationships through direct references, or when project rules require it. --- ## 11. Prompt patterns by situation **When you’re here.** You are working with an agent and want a starting point for a recurring situation. These are optional, vendor-neutral starting points for recurring situations. They are not another ADEL workflow and are not meant to be run in sequence. Use the one that matches the work in front of you, and adapt it to the project knowledge the agent can actually reach. ### Quick guide These are situations, not lifecycle steps. A project may use some repeatedly, some occasionally and some not at all. | Situation | Prompt | Where it fits | | --- | --- | --- | | Starting a new project | Draft the first project records | Records used across changes | | Adopting ADEL on an existing project | Map what an existing project already has | Adoption and discovery | | Investigating architecture drift | Check whether the code still matches the design | System Design / conflict handling | | Work is understood and ready to prepare | Prepare a work item | Delivery Planning → Execution | | A work item is ready to build | Implement a work item | Execution | | Implementation needs to be assessed | Check the result against what was required | Assurance / closure | > **Playbook guardrail** > > A prompt does not replace a missing project decision. If the work requires an unresolved Product Definition, System Design or Governance decision, resolve it at the responsible layer before asking an agent to proceed. (Framework: §2.4 Treat AI agents as capable contributors with clear decision limits · §6.1 Find where the decision belongs.) ### A missing example record does not always mean knowledge is missing During later work, a missing example record does not by itself justify creating one. First determine whether the project knowledge exists elsewhere, whether an earlier decision is unresolved or whether the current work is responsible for creating the record. - **The knowledge exists elsewhere** — Reference the existing source of truth, whatever it is called and wherever it lives. - **The knowledge does not exist because an earlier decision is still open** — Report the gap and the layer responsible for the decision. Do not invent the answer so the work can continue. - **The knowledge exists but future work needs it in a project record** — Create the record when the work allows it and another person or later work will need the information. ### What to do when the example record is not there | Prompt purpose | Missing record | What the agent should do | | --- | --- | --- | | Map what an existing project already has | No source of truth for Product Definition or System Design is found | Report the gap; do not invent the missing decisions as part of mapping | | Prepare a work item | No approved requirement defines the requested outcome | Stop and report the Product Definition gap | | Prepare a work item | No separate work-item record exists, but the work item must remain available outside the current tool or session | Use the existing work-item form if sufficient; otherwise create a suitable project record such as a task | | Implement work | No approved design decision covers an important architectural choice needed for the work | Stop and raise the System Design question. The agent may draft a proposal if the work allows it, but the approver must approve the decision separately | | Verify work | No verification record | May create one within the approved scope when the work item, pull request or evidence system does not already preserve the verification result | | Traceability review | No central traceability table | Do not create one automatically; first determine whether people can follow the direct references | | Establish a new project | The project does not yet have the Governance, Product Definition, System Design or agent instructions it needs | May draft the missing records because creating the project’s initial records is the stated purpose of the work | ### How these prompts use project knowledge Use these instructions with every prompt below. Add them, or equivalent instructions, when adapting a prompt for your project. *project knowledge instructions — add before the selected prompt* ```text Before acting, locate the sources of truth relevant to the requested work. Use the project's existing records regardless of their filename or location. Do not create duplicate records only to use filenames shown in ADEL examples when an equivalent source of truth already exists. If required project knowledge is missing, inaccessible, outdated or conflicting: - identify what is missing or inconsistent - identify the ADEL layer responsible for the affected decision - do not invent a decision that belongs to an earlier layer in order to continue - create or update a project record only when the work item allows it, the required information is confirmed, and future work needs the record ``` ### Establishing a new project #### Draft the first project records Draft the project knowledge a new project does not yet have. - **Use when:** A new project needs concise records used across changes, and you understand the problem well enough to draft them. - **Relevant ADEL parts:** Governance, Product Definition, System Design, and the Agent execution overlay where agents are used. - **Output:** Concise drafts of the missing project knowledge—for review, not automatic adoption. *prompt* ```text Determine whether suitable sources of truth already exist, and reuse them where they do. Where required project knowledge does not yet exist, draft concise initial records for Governance, Product Definition, System Design and — when coding agents are used — the Agent execution overlay. Keep each as short as the work needs. Mark open questions rather than resolving them by assumption. These drafts become sources of truth only after the approver or approval process named by the project accepts them. ``` ### Adopting or diagnosing an existing project #### Map what an existing project already has Inventory what exists and identify each source of truth. - **Use when:** You are introducing ADEL to an existing project and need to understand what already exists before creating anything. - **Relevant ADEL parts:** Adoption and discovery — before changing any documentation structure. - **Output:** An inventory of sources, what each holds, which are sources of truth, and any gaps, conflicts, outdated information or access problems. *prompt* ```text Review the project records available to you. For each record, identify: - what information or decisions it holds - which ADEL layer or the Agent execution overlay that information relates to - whether the project treats it as a source of truth - whether it is current and accessible Do not create new records yet. Then identify important gaps, conflicting sources, stale information, project knowledge you cannot reach, and important knowledge that appears to exist only in the code or in convention. ``` #### Check whether the code still matches the design Compare the implementation against the approved design. - **Use when:** You are taking over an existing system, or the code and approved design may no longer agree. - **Relevant ADEL parts:** System Design and conflict handling. - **Output:** Where the code and approved design agree, where they differ, and which questions the System Design approver must resolve. *prompt* ```text Inspect the existing implementation and the records that hold the approved design. Identify where the code and the approved design agree, where they differ, and where the records do not make clear which design should be followed. Do not assume existing code automatically represents the approved design. ``` ### Preparing implementation #### Prepare a work item Turn the understood intent and approved design into a clearly scoped work item. - **Use when:** The required outcome and the relevant approved design are understood well enough to turn into work items. - **Relevant ADEL parts:** Delivery Planning → Execution. - **Needs:** The relevant requirement or outcome, approved design, governing constraints and accepted decision records where relevant. - **Output:** A work item with clear scope, constraints, references and acceptance criteria, with unresolved questions listed separately. *prompt* ```text Locate and use the Product Definition source of truth, relevant approved design, relevant accepted decision records and governing constraints for this work. Use the project's existing records regardless of filename or location. If that information is sufficient, prepare a clearly scoped work item using the project's existing work-item form, or create a work-item record when the person or agent needs it outside the current tool or session. Do not introduce new product requirements, governing rules or important architectural decisions. If required project knowledge is missing, conflicting, inaccessible or unresolved, identify the gap and the ADEL layer responsible for it instead of inventing the answer. ``` ### Implementing #### Implement a work item Perform the work inside its stated boundaries. - **Use when:** The work item has clear boundaries and the person or agent doing it can reach the relevant sources of truth. - **Relevant ADEL parts:** Execution. - **Needs:** The current work item, relevant requirements and design, constraints and required checks. - **Output:** Implementation that stays inside the approved boundaries and reports decisions that belong to an earlier layer instead of silently making them. *prompt* ```text Locate the current work item and the sources of truth it references. Implement within the stated scope, requirements, approved design, accepted decisions and governing constraints. If a required source cannot be found, or implementation exposes an unresolved Product Definition, System Design or Governance decision, report it and identify the responsible ADEL layer rather than treating it as a local implementation choice. You may draft a proposed record for that decision when the work allows it, but leave it proposed: do not treat a newly discovered choice as an approved project decision, and do not proceed as though it were. ``` ### Verifying and closing #### Check the result against what was required Assess evidence against the requirements, criteria, rules and checks that apply. - **Use when:** Implementation exists and enough evidence is available to assess whether the relevant requirements, acceptance criteria, governing rules and required checks were satisfied. - **Relevant ADEL parts:** Assurance — usually before closure, though verification may happen throughout implementation. - **Output:** A result for each requirement, criterion, rule or required check, using Verified, Failed, Not verified or Unable to verify, with its evidence and any outstanding findings. *prompt* ```text Identify the relevant requirements, acceptance criteria, governing rules and required checks for this change. Then trace them through the relevant design, the implementation and the available verification evidence. For each one, state what the evidence shows: Verified, Failed, Not verified, or Unable to verify with the available access or environment. Give the evidence supporting each conclusion. When evidence is important to the conclusion, identify what was actually evaluated: the revision or build and the relevant environment, or the continuous-integration (CI) run or pull request that already records them. Do not claim verification without supporting evidence. Do not record a failed or unperformed check as verified. ``` Use these prompts as starting points. Change their wording for the project and tool, but keep the stated purpose, limits and decision authority. --- ## 12. Use the tools you already have **When you’re here.** You want to know how ADEL works with the systems your project already uses. ADEL works with the tools a project already uses. The project decides where each source of truth lives; changing tools does not change the responsibility of any ADEL layer. > **Framework rule** > > Use the source of truth directly when the person or agent can reliably reach it and is allowed to. Add a copy in the repository only when the work needs information it cannot obtain directly—for example, when a coding agent cannot access Jira. The copy identifies its source and contains only the approved information needed for the work. > **Map by content, not by product** > > Tool names do not determine ADEL placement. Map information according to what the system holds and whether it is a source of truth, not according to the product or platform where it happens to live. ### Repository-centered | Source | Information it commonly holds | | --- | --- | | Product requirements document (PRD) | Product Definition | | Blueprint or architecture docs | System Design | | Architecture decision records (ADRs) | System Design decision records | | Issues | Delivery Planning and/or Execution, by purpose | | Code | Implementation produced through Execution | | Pull requests | Change and review history; traceability | | Continuous integration (CI) | Assurance evidence | | AGENTS.md | Agent execution overlay | ### Tracker and knowledge base | Source | Information it commonly holds | | --- | --- | | Knowledge base | Governance, Product Definition or System Design, depending on what it contains | | Issue tracker | Delivery Planning and/or Execution | | Repository | Implementation, agent instructions and copies needed when direct access is unavailable | | Continuous integration (CI) | Assurance evidence | ### Distributed enterprise | Source | Information it commonly holds | | --- | --- | | Product platform | Product Definition | | Architecture platform | System Design | | Governance, risk and compliance (GRC) system | Governance | | Issue tracker | Delivery Planning and/or Execution | | Repository | Implementation, plus approved copies when direct access is unavailable | | Repository AGENTS.md | Agent execution overlay | | Continuous-integration (CI) or test platform | Assurance evidence | ### Source of truth and approved copy An approved copy holds only the information the work needs and states where it came from. It does not become a second version of the source. | Source of truth | Information in source | Approved copy | Information in copy | Why the copy exists | | --- | --- | --- | --- | --- | | Product platform | Holds the requirement as its source of truth | Repository work item | Holds the requirements needed for this work and cites the source | The work item does not become a second Product Definition. | | CI platform | Holds the raw test results | Verification record | States what those results establish | The record interprets the evidence; it does not copy it. | ### When connecting a tool, ask - What information or decision does this system hold? - Which ADEL layer or the Agent execution overlay does that belong to? - Is this system the source of truth for it? - Can the people or agents doing the work reach it? - If not, what approved information does the work actually need? - Will the copy identify its source and avoid becoming another source of truth? These are illustrations, not recommended stacks. ADEL does not require a particular repository host, issue tracker, knowledge base, architecture platform, CI system or AI tool. --- ## 13. Worked examples **When you’re here.** You want to compare how the same ADEL responsibilities apply in three different project situations. These examples combine the guidance from earlier sections. Section 3 compares a tiny change, a normal feature and an architecture-affecting change. The examples below show how ADEL applies when adopting it on an existing project, making a security-sensitive change and passing work between people and agents. ### In each example, look for - which existing sources of truth are reused - which decisions actually change - which new records are created and why they are needed - what is deliberately not created - how completion is supported by evidence - what relationships remain traceable ### Different project situations The same layers applied to a different project, requirement and person or agent doing the work. #### Existing project adoption *Adopt ADEL on a five-year-old service.* - **Reuses:** Existing sources confirmed as current, approved and accessible after inspection—a wiki specification, a directory of decision records, contribution instructions and continuous-integration (CI) results. - **Adds or updates:** If coding agents are used, establish or reconcile agent instructions. Record important gaps or conflicts where they need to remain visible. - **Deliberately not added:** Copies of existing documents renamed to match ADEL examples. - **Decision responsibility:** No new project decision yet—this example is still mapping existing records. - **Done when:** Important project knowledge is matched to the relevant layers or Agent execution overlay, sources of truth are identified and important gaps or conflicts are visible. - **Traceability:** Whatever links already exist, extended only where they break. #### Security-sensitive change *Allow each company to export only its own account data.* - **Reuses:** The relevant security policy, security requirements, previous security review and approved design. - **Adds or updates:** The implementation and relevant tests, plus only the security requirements, approved design or important decision records that actually change. Keep verification evidence when the project’s risk or assurance needs require it. - **Deliberately not added:** A parallel “ADEL security document” where existing security records already hold the decisions. - **Decision responsibility:** Governance is responsible for lasting security principles; Product Definition is responsible for required security behavior; System Design is responsible for the technical design. - **Evidence / completion:** Authorization-test results, relevant security checks and review findings that provide evidence for the requirement. - **Traceability:** Security requirement → approved design → implementation → verification evidence. #### Human and multi-agent delivery *A feature planned by one agent, implemented by another, reviewed by a person.* - **Reuses:** Agent instructions, the relevant requirements, approved design, accepted decision records and the current work item. - **Adds or updates:** The information the next person or agent needs to continue without guessing decisions or repeating work. An existing issue or task may be sufficient; use a handoff only when the delivery plan must preserve sequencing, dependencies or coordination across the transfer. - **Deliberately avoided:** Using conversation history as the primary transfer mechanism. - **Decision responsibility:** Moving the work does not move its decisions. Product decisions still belong to Product Definition, design decisions to System Design and implementation choices within the work item to Execution. - **Evidence / completion:** Completion is assessed against the relevant requirements, acceptance criteria, required checks and evidence—not against what an earlier participant claimed in a conversation. - **Traceability:** Every participant leaves references in project records rather than only in a work session. --- ## 14. Troubleshooting **When you’re here.** You have a practical question or are unsure which record, decision or action is needed next. Common questions that arise when applying ADEL in real projects. ### Project records and documentation #### Our issue tracker already contains everything. Do we need a separate work-item record? Not necessarily. If the tracker item already gives the person or agent enough information, references the relevant sources of truth and remains accessible, another record would duplicate it. Create a repository work item when the person or agent cannot reliably reach the tracker or when the approved scope, constraints and acceptance criteria need to travel with the repository. *Related: [Applying ADEL to a change](#3-applying-adel-to-a-change)* #### We have no governing principles written down. Start with only the project-wide principles and constraints that actually apply. A concise record containing real governing rules is more useful than a long one filled with principles nobody applies. Do not create filler to make the record look complete; add detail only as the project’s Governance needs grow. If an existing engineering policy, project charter or constitution already holds those principles as a source of truth, do not recreate them merely to use a filename shown in an ADEL example. *Related: [How much detail is enough](#8-how-much-detail-is-enough)* #### Our existing documentation uses different names. Keep the existing names when they already work. A record’s place in ADEL is determined by the kind of decision or information it holds, not by its filename. Rename or reorganize it only when doing so improves clarity, access or maintenance—not simply to match ADEL terminology. *Related: [Adopting on an existing project](#2-adopting-adel-on-an-existing-project)* #### The example record the Playbook references does not exist. Should we create it? First determine whether the information already exists elsewhere. If an existing source of truth holds it, use that record. If the information is actually missing and represents an unresolved earlier decision, resolve it at the responsible layer. Create another record only when the work allows it and another person or later work will need that information. Do not create a record merely because its name appears in an ADEL example. *Related: [Prompt patterns by situation](#11-prompt-patterns-by-situation)* ### Project knowledge and access #### The coding agent cannot access our wiki. Copy only the information needed for the work into an accessible project record and identify its source of truth. If the source may change before the work is complete or be checked later, include the source version, date or another reference. The wiki remains the source of truth; the repository record is a limited copy, not a competing source. Use the same approach when direct access is not allowed. *Related: [Give each work item the project knowledge it needs](#5-give-each-work-item-the-project-knowledge-it-needs)* #### The product requirements document (PRD) is very large. Large is not the problem; difficult to navigate is. Organize the source of truth by section, domain, product area or another structure suited to the project. Split it only when that improves navigation or responsibility. Then reference the relevant part from the work item instead of repeating the document. Limit the work item, not the source of truth. *Related: [Give each work item the project knowledge it needs](#5-give-each-work-item-the-project-knowledge-it-needs)* ### Decisions and conflicts #### The approved design and a decision record disagree. Determine which approved decision applies to the affected work. A decision record is the source of truth for the decision it captures while it remains approved, relevant and not replaced. An older, differently scoped or proposed record does not override the current approved design. The approved design remains the source of truth for the system as a whole. Update the records until they agree again. *Related: [Framework — conflict handling](/adel/framework#conflicts)* #### The agent discovered an architecture issue mid-implementation. Do not resolve an important architecture issue as a local implementation choice. Raise it as a System Design decision and pause the affected work until the approver resolves it. If the work would change an architectural boundary, the agent should report the unresolved System Design question rather than invent the answer during Execution. *Related: [Preparing work for a coding agent](#4-preparing-work-for-a-coding-agent)* ### Verification and traceability #### Tests pass, but one requirement is not demonstrated. The affected requirement is not Verified. Record whether it is Not verified or Unable to verify, together with the available evidence and the reason. Whether the work can still close depends on the project’s rules and acceptance process. The approver must accept any permitted exception or remaining risk instead of silently treating the work as complete. *Related: [Verification in practice](#9-verification-in-practice)* #### Nobody maintains the central traceability table. A stale table can be more misleading than having no table because it shows relationships that are no longer true. If direct references between the requirement, work, implementation and evidence are easy to follow, retire, archive or remove the table according to project practice. Keep a shared traceability view when people can no longer follow the direct references or when project rules require one. *Related: [Traceability in practice](#10-traceability-in-practice)* ### Adoption #### Do we need to clean up the whole project before using ADEL? No. Identify the approved information, gaps and conflicts that matter to the work in front of you. Fix those first, then improve other records as later work uses them. Do not turn adoption into a project-wide documentation rewrite. *Related: [Adopting on an existing project](#2-adopting-adel-on-an-existing-project)* --- ## 15. Know where ADEL stops **When you’re here.** You need to know what ADEL organizes and what remains the responsibility of specialist practices, project roles or other tools. ADEL shows where project decisions, work items and evidence belong and how they connect. It does not tell security specialists how to secure a system, assign the project’s job titles or replace the tools used for specialist work. The limits below cover specialist practices, the records those practices produce and the people responsible for the work. ### Specialist practices Security, privacy, safety, accessibility, reliability, compliance, operations and data governance each keep their own methods and controls. ADEL shows where their requirements, design decisions, work and evidence belong. It does not define how specialists perform that work. The table uses security as one example. | Security concern | Typical ADEL placement | | --- | --- | | Mandatory security rules | Governance | | Required security behavior and acceptance criteria | Product Definition | | Security risks, trust boundaries and security architecture | System Design | | Important security design decisions | System Design; a decision record when future work needs the reason | | Security implementation work | Execution | | Security verification and evidence | Assurance | Place the information according to whether it sets a rule, requirement or design, describes work, or provides evidence—not simply because it is about security. ADEL does not define how to protect agents from malicious instructions, handle secrets, secure software dependencies or process untrusted content. Those rules come from specialist security practice. ADEL defines which decisions belong to the agent’s work and when its instructions require it to stop. Information the agent can access is not automatically an approved instruction, and agent instructions do not grant system or tool permissions. ### Specialist records A specialist record can already provide project knowledge for one or more ADEL layers. When it is the source of truth, keep it instead of creating a copy with an ADEL example filename. When a work item needs part of that information, reference the source or provide an approved copy that identifies it. > **Playbook guardrail** > > Map a record by what it decides, describes or demonstrates—not by its filename. (Framework: §8.1 Layer, record, and location · §8.2 Judge a record by its content, not its filename.) | Existing specialist record | ADEL layers or responsibilities it commonly supports | | --- | --- | | Threat model — identified threats and planned protections | System Design; the security requirements it identifies also touch Product Definition | | Security policy | Governance | | Accessibility requirements | Product Definition | | Accessibility evaluation results | Assurance | | Performance requirements | Product Definition | | Performance architecture and constraints | System Design | | Performance measurements | Assurance | | Rollout plan | Delivery Planning | | Migration plan | Delivery Planning or System Design, by content | | Penetration-test report — results of an authorized security test | Assurance | | Operational architecture | System Design | | Compliance evidence | Assurance | | Control mapping — links required controls to the work and evidence | Assurance; traceability where it connects controls to requirements, implementation and evidence | These are examples. ADEL does not require these exact placements. One specialist record may contain information used by more than one layer and does not need to be split for that reason. ### Organizational responsibilities ADEL assigns each kind of decision to a responsible layer, not a job title. Teams decide who writes, reviews, approves, implements and verifies according to their own organization and governance. The examples below show where common roles usually meet the model; ADEL does not require this division of work. | Example participant | ADEL responsibilities commonly involved | | --- | --- | | Product manager / business analyst | Product Definition; Assurance where acceptance criteria are assessed | | Architect | Governance; System Design. Architecture decision records (ADRs) are a common decision record in System Design. | | Developer | System Design; Execution; Assurance; Agent execution overlay where agents are used | | Quality assurance (QA) / testing | Product Definition; Assurance. Acceptance criteria usually originate in Product Definition. | | Security | Governance; Product Definition; System Design; Assurance | | Engineering lead | Delivery Planning; Assurance; Governance where delivery policy applies | | Site reliability engineering (SRE) / operations | Product Definition for operational requirements; System Design; Delivery Planning; Assurance | | Auditor / reviewer | Governance; Product Definition; System Design; Assurance | | Coding agent | Agent execution overlay; Execution; relevant Governance, Product Definition and System Design records; required checks and evidence for Assurance. AGENTS.md is one common record used by the Agent execution overlay. | --- ## What the Playbook should do **The Playbook should make ADEL easier to apply without adding unnecessary work.** If a Playbook recommendation adds work without making decisions clearer, records easier to find, transfers safer or verification stronger, change or remove it. - **Framework** — defines the model and which layer is responsible for each kind of decision. - **Playbook** — shows how to apply the model in common situations. - ↳ **Work with ADEL** — shows one project applying the Playbook from start to finish. - **Templates** — reduce the effort of creating a project record when one is useful. --- ADEL Playbook. By Mark A. Basco. The rendered Playbook: