← ADEL
Version 2026.09

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.

Download Markdownadel-framework.md
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 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.

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.

ADEL conceptual model
Governance
Governance principles
Project-wide rules and who may approve exceptions
Commonly a constitution, engineering principles or a project charter

What project-wide rules must the work follow, and who may approve exceptions?

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
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.

Figure 1ADEL conceptual model. Designed to be adapted across projects, teams, technology stacks and AI coding tools.

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.

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.

Governance
Project knowledge carried
Project principles and policy
Question answered
What project-wide rules must the work follow, and who may approve exceptions?
Product Definition
Project knowledge carried
Product intent and requirements
Question answered
What must we build, for whom, and why?
System Design
Project knowledge carried
Approved design and decision records
Question answered
How will the system work, and why did we choose that design?
Delivery Planning
Project knowledge carried
Delivery plan
Question answered
Which work is ready, in what order, and who will do it?
Execution
Project knowledge carried
Work item
Question answered
What exactly is being changed, and how will we know it is done?
Assurance
Project knowledge carried
Verification evidence and traceability
Question answered
What evidence shows that the result works as required?
Agent execution overlay
Project knowledge carried
Agent instructions
Question answered
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.

01

Why does this change exist, and what outcome or requirement does it serve?

02

What principles, requirements and design decisions constrain it?

03

Who may make or approve each important decision?

04

What clearly scoped work implements the current decision?

05

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.

Section 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.

Three questions per risk
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?

01

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.

02

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.

03

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.

Section 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.
01

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.

02

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.

03

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.

04

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.

05

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.

06

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.

07

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.

08

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.

Section 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.

Layer
Meaning
A continuing responsibility for a particular kind of project decision and knowledge. A layer is not a phase that is completed once.
Delivery lifecycle
Meaning
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
Meaning
Agent instructions that tell coding agents how to find and use project knowledge while following decision authority and enforced permissions.
Section 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
Product Definition
Project knowledge
Product intent and requirements
Possible record
Product brief or product requirements document (PRD)
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.

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

Product Definition

System Design

Delivery Planning

Execution

Assurance

Agent execution overlay

Section 5

Delivery lifecycle and feedback flow

The delivery lifecycle describes the activities that move work from an understood need to a verified and closed result. Use it to determine what the work needs next and when existing project knowledge may need to be created, updated or checked.

The lifecycle is not another set of layers and it is not a strict waterfall. Layers identify where decisions and project knowledge belong; lifecycle steps describe what people and agents are doing. Each step names the layer or layers most directly responsible, but it may also use information from other layers and can return decisions to them when something changes.

The seven lifecycle steps

Each step shows its main focus and primary ADEL layer or layers. The primary layer is the one most involved in that step. Other layers may also provide information or receive updates.

  1. 1

    Understand the need

    Main focusProblem and circumstances
    Primary layerProduct Definition

    Clarify the problem or opportunity, who it affects, the desired outcome, the relevant constraints and what success should look like.

  2. 2

    Define the required outcome

    Main focusRequirements and success
    Primary layerProduct Definition

    Create or refine the product requirements until the intended behavior, scope and success criteria are clear enough for design and later verification. Add only the detail the work needs.

  3. 3

    Design the solution

    Main focusArchitecture and decisions
    Primary layerSystem Design

    Create or update the approved design needed to meet the requirements. Record an important architectural decision separately when future work will need its reason, alternatives or consequences.

  4. 4

    Prepare the work

    Main focusScope and sequencing
    Primary layerDelivery Planning

    Organize how the approved change will move into implementation. Define the delivery scope, identify dependencies, decide the sequence and confirm that enough is known to begin.

    Use a separate delivery plan only when it improves coordination, transfer or recovery of that information.

  5. 5

    Break down the work as needed

    Main focusClearly scoped work items
    Primary layersDelivery PlanningExecution

    Divide the work only as much as delivery needs. Give each work item a clear outcome, boundary and acceptance criteria. For a small change, an existing issue, ticket or concise instruction may be sufficient.

  6. 6

    Implement the change

    Main focusCode, tests and documentation
    Primary layerExecution

    Inspect the current system, make the required change and update the relevant tests and documentation. Keep the implementation within the agreed scope and the approved design.

    If implementation would change an approved requirement or System Design decision, return that decision to the responsible layer instead of changing it silently in the code.

  7. 7

    Verify and close

    Main focusAcceptance, evidence and traceability
    Primary layerAssurance

    Check the delivered change against the relevant requirements, design decisions, constraints, acceptance criteria and required checks. Retain enough evidence to show what was evaluated and state the result of each expectation.

    A failed, unperformed or unverifiable requirement cannot be reported as verified. Closing despite that result is a separate acceptance decision: project policy must permit an exception, and the approver must accept it.

    If verification reveals a requirement, design or implementation gap, return each affected decision to the responsible layer before considering the work complete.

Delivery lifecycle and feedback loop

Each step includes its main focus; this is not a required output or document. “Primary” names the layer or layers most directly responsible for that step.

1Understand the needFocus: Problem and circumstances
2Define the required outcomeFocus: Requirements and success
3Design the solutionFocus: Architecture and decisions
4Prepare the workFocus: Scope and sequencing
5Break down the work as neededFocus: Clearly scoped work items
6Implement the changeFocus: Code, tests and documentation
7Verify and close2Focus: Acceptance, evidence and traceability
Used in every stepGovernance principlesAgent instructionsOrganizational security policy, when applicableRequired checks
Figure 2 — Delivery generally flows forward, but new information can return work to an earlier lifecycle step. Changes are made in the layer responsible for each affected decision, then delivery continues.
  1. 1
    Feedback / revisit

    Any step may return work to an earlier one when new information changes an assumption, requirement, design or plan. Return only as far as needed, update the source of truth for the affected decision, and then update later work before continuing.

  2. 2
    Verify and close

    Verification can occur throughout delivery. At closure, the available evidence is checked against the relevant requirements, design decisions, constraints and acceptance criteria. A finding can return work to the earlier step responsible for the affected decision.

Work generally moves through the seven steps in order, from Understand the need to Verify and close. If new information changes an earlier decision, return to the step and layer responsible for that decision. Update the source of truth and any later work that depends on it before continuing. Governance principles, agent instructions, security policy and required checks apply in every step.

Section 6

Source of truth and conflict handling

A source of truth is the record the project treats as correct for a particular kind of information or decision. ADEL does not treat one document, tool or repository as the source of truth for every question. Each layer is responsible for different decisions, and the project identifies the source of truth for each one.

A conflict exists when a record, instruction or implementation contradicts a source of truth. Resolve it by separating the decisions involved, finding the responsible layer and approver for each one, and updating the affected records before work continues.

A project has several sources of truth, each with a defined responsibility.

A record is a source of truth only for the decisions it was approved to hold. The newest file, latest prompt or current code is not automatically the one to follow.

For example, an accepted decision record holds one architectural choice, while the approved design describes the system as a whole. If they disagree, determine which decision is current and update the approved design so the two records agree.

6.1 Find where the decision belongs

Start by identifying the question the conflict raises. The question points to the ADEL layer responsible for the decision and the project knowledge that normally carries it.

Decision question
What project-wide rules must the work follow, and who may approve exceptions?
ADEL layer or Agent execution overlay
Governance
Project knowledge
Governance principles
Decision question
What must we build, for whom, and why?
ADEL layer or Agent execution overlay
Product Definition
Project knowledge
product intent and requirements
Decision question
How will the system work, and why did we choose that design?
ADEL layer or Agent execution overlay
System Design
Project knowledge
the approved design and decision records
Decision question
Which work is ready, in what order, and who will do it?
ADEL layer or Agent execution overlay
Delivery Planning
Project knowledge
a delivery plan or existing work records
Decision question
What exactly is being changed, and how will we know it is done?
ADEL layer or Agent execution overlay
Execution
Project knowledge
the current work item
Decision question
What evidence shows that the result works as required?
ADEL layer or Agent execution overlay
Assurance
Project knowledge
verification evidence and traceability
Decision question
How should a coding agent work in this repository?
ADEL layer or Agent execution overlay
Agent execution overlay
Project knowledge
agent instructions

Code and configuration show what currently exists, but they do not decide what the product or approved design should be. Treat the current system as evidence to inspect. If it contradicts an approved decision, resolve the disagreement rather than assuming the code is the source of truth.

6.2 Find who may decide

First identify what kind of decision is being made; this determines the ADEL layer responsible for it. Then identify the approver. For example, a database architecture choice belongs to System Design, while project policy may name a technical lead as its approver through the decision-record process.

How sources of truth relate

The two views below show where to look when different layers or records disagree. They do not rank every document from most to least important. Each source of truth applies only to the decisions it was approved to hold.

Across ADEL layers

Read from Governance down. Each layer provides rules or decisions that the next layer must follow. A source of truth applies only to the decisions held by its own layer.

Governance

01

Sets project boundaries, decision authority and rules for change or exception.

Product Definition

02

Defines the required outcomes, behavior and acceptance criteria within those boundaries.

System Design

03

Defines how the system is intended to meet the approved requirements.

Delivery Planning

04

Organizes the approved work, dependencies, conditions required to start and release approach.

Execution

05

Carries the information and limits for implementing a specific work item.

Assurance

06

Records what was checked, the evidence obtained and the verification result.

Assurance appears last because it evaluates the delivered result. Its verification record is the source of truth for what was checked, but it does not redefine Governance, requirements or design.

Agent execution overlay

Agent instructions apply across all six layers. They tell an agent how to use this knowledge, but they do not override decisions made in any layer.

Between records in the same layer

Do not use the filename or modification date as the first test. Compare which decisions the records cover and whether the project has made one the source of truth.

Compare scope

Do the records address the same decision?

No

Both can apply

Each record applies to its own work. Neither one replaces the other just because it is newer.

Yes

Has the project marked one record as current and approved for this decision?

Yes

Use the source of truth

Mark the other record as replaced, or update it, so nobody follows it by mistake.

No

Treat it as a conflict

Do not choose the newer file by assumption. Ask the approver to resolve the overlap.

Example: two task files

Two task files normally describe separate pieces of work, so neither automatically outranks the other. A newer task file replaces an earlier one only when it says so and has been approved.

6.3 Separate the decisions inside the conflict

A new request, technical limitation, failed check or other fact learned during delivery may affect more than one part of the project. Identify the separate decisions it creates before choosing a response, so each decision is resolved in the correct ADEL layer by its approver.

Example: a new homepage video conflicts with approved constraints

The project is already implementing a marketing website. Its approved Governance principles require an accessible experience and a defined homepage performance budget. The client then asks for a large autoplay background video. Before adding it, the team separates the decisions raised by the request.

Governance
Question to resolve

Must the existing accessibility and performance rules remain unchanged, or may an approved exception be considered?

Product Definition
Question to resolve

Is the background video now a requirement, and what visitor outcome is it expected to improve?

System Design
Question to resolve

How can the media be delivered without violating the approved constraints—for example, through a poster image, reduced motion behavior or deferred loading?

Delivery Planning
Question to resolve

Does the approved change require a new work item, additional content preparation or more verification before release?

Ask the approver for each question to resolve it, update the affected project knowledge and later work, and then continue delivery. The work returns to several layers in this example, but it does not restart from the beginning.

6.4 Resolve the conflict and update the records

Read the diagram from top to bottom for each decision affected by the conflict. Each box is a step in resolving the disagreement, not a required document. “Resolve” means the approver decides what should apply. “Update” means bringing the affected records, instructions and work back into agreement before continuing.

Resolving a conflict
Conflict found
Identify every decision affected
Find the layer responsible for each decision
Find the source of truth and approver
Ask the approver to resolve or change each decision
Update the affected project knowledge and work
Continue when the affected sources agree

Repeat the flow for each decision affected by the same finding. Continue only when the relevant project records and work agree—not merely because someone selected the newest file.

6.5 Common conflict patterns

The relationship column shows whether each example compares knowledge across layers, within one layer or between the Agent execution overlay and a layer. A higher layer constrains a lower layer only for its own decisions. For two records in the same layer, check what each one covers, whether it is approved and whether one says it replaces the other.

Implementation conflicts with a product requirement or governing principle
Relationship
Across layers — Execution compared with Product Definition or Governance
What to do
Pause the affected implementation. Correct the work, or have the approver intentionally change the requirement or principle before continuing.
Implementation conflicts with the approved design
Relationship
Across layers — Execution compared with System Design
What to do
Treat the disagreement as a System Design question. Change the implementation to follow the approved design, or have the approver revise the design and record the important decision when future work will need it.
A decision record and the approved design disagree
Relationship
Within System Design — two records may cover the same decision
What to do
Determine whether the decision record is current, accepted and relevant to the affected part of the system. If it is, apply that decision and update the approved design. If it is not, correct or replace the record.
Agent instructions conflict with product or design information
Relationship
Agent execution overlay to layer — agent instructions compared with Product Definition or System Design
What to do
Correct the agent instructions. They tell agents how to use project knowledge; they cannot redefine requirements, System Design or governing principles.
Existing code conflicts with the approved design
Relationship
Across layers — current implementation compared with the approved design
What to do
Do not assume the code is correct because it already exists. Determine whether the code is outdated, incomplete or evidence that the approved design needs review, then ask the approver to resolve the disagreement.
Two records in the same layer disagree
Relationship
Within one layer — two records have overlapping scope
What to do
Determine which decision is current, approved and relevant to the affected work. Update or replace the other record so the project no longer has two approved interpretations.
Section 7

Traceability

Traceability connects a requested feature, fix or behavior change to the project knowledge and work that followed from it. It allows someone to understand why the change exists, what guided its implementation and how the result was checked.

7.1 Start with three practical questions

Choose a feature, fix or configuration change that affects the delivered system and try to answer the questions below. If an answer cannot be found from the project’s existing records and tools, at least one required connection is missing.

Why are we making this change?

Find the business need or approved requirement that explains it.

What tells us how to build it?

Find the relevant approved design, any important recorded decision and the project constraints.

How do we know the result works?

Find the checks performed, their results and the implementation revision they evaluated.

You do not need a dedicated traceability tool or document to answer them. For many projects, references between requirements, design documents, work items, pull requests, tests and CI results provide enough information.

7.2 The general trace from need to evidence

This diagram is the reusable pattern. It answers which kinds of information should be connected for any feature or fix, without prescribing filenames or tools. Each box represents project knowledge or work, not necessarily a separate file. An arrow means the later item keeps a reference to the earlier item that explains or authorizes it.

General pattern · A basic trace from need to evidence
Business need
Product requirement
Approved designDecision record, if needed
Work item
Implemented change
Verification evidence

Each arrow is a reference, such as a requirement ID in a work item, a work-item link in a pull request or a test result linked to the requirement it checked. These references may be fields or links in tools the project already uses; they do not require separate files.

Figure 3 — The information path connecting a requested change to evidence that the delivered result was checked.

7.3 Add references while working

Add each reference when you create or update the later record. For example, a work item should name the requirement it implements, and a verification result should name the requirement or work item it checked. The examples use BN for business need, FR for functional requirement and NFR for non-functional requirement. Recording these links during the work avoids reconstructing the history afterwards.

Requirement
Keep a reference to
The business need or outcome it supports
Example
Supports: BN-01
Approved design
Keep a reference to
The requirement or requirements it meets
Example
Meets: FR-08
Decision record, when needed
Keep a reference to
The design or requirement affected by the decision
Example
Applies to: FR-08; Contact submission design
Work item
Keep a reference to
The requirement and relevant approved design
Example
Implements: FR-08; Contact submission design
Implementation / pull request (PR)
Keep a reference to
The work item that authorized the change
Example
Completes: Task 01
Verification
Keep a reference to
The requirement or work item being verified and the supporting evidence
Example
Verifies: FR-08; PR #12; CI run #1842

7.4 Example: trace a website contact form

This is the general pattern from 7.2 applied to actual project records. A marketing website needs a contact form so prospective clients can send an inquiry. The example follows that need through the requirement, approved design, work item, pull request and verification result, using identifiers and references someone could search. Here, the project also records server-side email delivery as an important design decision; a project that keeps the same decision clearly in its approved design would not need a separate decision record.

Worked example · The contact form trace
Start from the need

Use this direction to check delivery coverage: did the original need become an approved requirement, guide the design and implementation, and result in evidence that the expected behavior works?

01
Business need
BN-01 — Prospective clients need a simple way to contact the firm.
02
Product requirement
FR-08 — A valid inquiry is delivered to the firm’s shared inbox.Supports: BN-01
03
Approved design
Contact submission — validate on the server and send accepted inquiries to the shared inbox.Meets: FR-08
Optional decision record
ADR-002 — Send inquiries through a server-side email service.Applies to: FR-08; Contact submission design
04
Work item
Task 01 — Deliver the marketing websiteImplements: FR-08; Contact submission designDecision: ADR-002
05
Implemented change
PR #12 — Marketing websiteCompletes: Task 01Revision: 9c1f2ab
06
Verification result
Verifies: FR-08; Task 01; PR #12Identified test inquiry reached the approved shared inboxCI run #1842 · revision 9c1f2ab
Start from the code

Use this direction before changing or removing code: find the work item that authorized it, the design decisions and constraints it must follow, the requirement it satisfies, and the business need that may be affected.

Read downward when checking whether an approved need was fully delivered and verified. Read upward when investigating existing code, assessing the impact of a change or deciding whether the code can be removed safely. The optional decision record remains attached to System Design rather than becoming another required rung.

7.5 Choose the amount of traceability the project needs

Choose based on how difficult the relationships are to follow and how serious a missed connection would be. A small project may need only direct links. Add consistent identifiers, a shared view or formal controls when work spans more records and systems, or when the project must prove that every requirement was addressed.

01

Direct references

The complete path fits within a few records in one repository or tool.

Example project: one person and a coding agent building a marketing website.

What to maintain

Keep links or identifiers between the requirement, work item, pull request and verification result. Do not create a central traceability view while these links remain easy to follow.

Example trace

FR-08 → Task 01 → PR #12 → CI run #1842

02

Shared traceability view

Related work spans several teams, repositories, releases or planning systems.

Example project: an online software product with separate web, service and platform teams.

What to maintain

Use consistent identifiers across requirements, the approved design, work items, pull requests and CI. Add a central traceability table or generated view when search and tracker backlinks no longer show the complete path.

Example trace

FR-142 links to two design sections, three work items assigned to different teams, four pull requests and their test runs.

03

Controlled traceability

The project must formally demonstrate coverage, approval and verification.

Example project: a payment authorization service subject to audit and controlled release.

What to maintain

Maintain reviewed mappings from each relevant requirement through design and implementation to verification evidence, including status, approval and the exact revision evaluated.

Example trace

REQ-27 → design control DC-08 → change CHG-104 → test report TR-61 → release approval

These are examples, not fixed project-size rules. A small but high-risk change may require controlled traceability, while a large but low-risk project may still be understandable through well-maintained links and search.

Section 8

Organizing project records

Section 4 defined the kinds of project knowledge ADEL uses. This section explains how a project can record and store that knowledge without reorganizing every tool or creating a directory for every layer.

A record may be a Markdown file, a Jira item, a page in a product or architecture platform, a continuous integration (CI) result or another source the project already trusts. People and agents with access must be able to find the current information, understand which decisions it records and know which source to follow if records disagree.

A practical order for organizing records

Start with the information itself, then decide how and where to keep it. The same order works for a new project, an existing project, a Git-based workflow or a project that uses several external systems.

01
Identify the ADEL layer

Identify which ADEL layer the information belongs to.

02
Reuse or choose a record

Use an existing file, page or tool when it already carries the information clearly.

03
Name the source-of-truth location

Name the source of truth and make it clear who can access it.

04
Add structure only when needed

Create, copy, split or move a record only when the source of truth is hard to access, unclear, likely to disappear or insufficient as evidence.

8.1 Layer, record and location

For any important piece of project knowledge, answer three questions separately: which ADEL layer does it belong to, which file, page or tool records it and where is the current record stored? ADEL defines the layers; each project chooses its records and locations.

Layer
Defined by ADEL

The type of project knowledge: Governance, Product Definition, System Design, Delivery Planning, Execution or Assurance.

Record
Chosen by the project

The file, page, ticket, report or other source that keeps the information available. Product briefs, PRDs, architecture documents, ADRs, tickets, handoffs and verification reports are examples, not names required by ADEL.

Location
Chosen by the project

The repository or external system where the current source of truth is kept.

Three ways those choices can work

These examples follow the same order—layer, record, then location—but end in different storage arrangements.

Repository holds the source of truth
ADEL layer
Execution
How it is recorded
TASK-021.md
Where it lives
docs/delivery/tasks/

The work item is maintained with the code, so the person or agent doing the work can retrieve its approved scope, constraints and acceptance criteria from the repository.

External tool holds the source of truth
ADEL layer
Product Definition
How it is recorded
PRD / requirements
Where it lives
Product platform

The product platform remains the source of truth for the requirements. The repository work item cites it and carries only the approved information needed when direct access is unavailable.

Responsibility is split across systems
ADEL layer
Assurance
How it is recorded
Verification evidence + VER-021
Where it lives
CI + repository

CI retains the raw test output. The repository record states what was verified, the conclusion and the link to the relevant CI run.

Common choices for each ADEL layer

The table expands the same three questions across all six layers. The record names and locations are examples, not required ADEL filenames or directories.

Governance
How it may be recorded
Governance principles, policies
Where it can live
Repository, engineering handbook or a governance platform
Product Definition
How it may be recorded
Product requirements document (PRD), requirements or an existing product specification
Where it can live
Repository, wiki or a product-management platform
System Design
How it may be recorded
Blueprint, architecture documentation
Where it can live
Repository or an architecture platform
System Design
How it may be recorded
Architecture decision records (ADRs), when an important decision and its reason must be kept
Where it can live
Usually the repository, close to the code the decisions affect
Delivery Planning
How it may be recorded
Delivery plan, handoff, sequencing and dependency information
Where it can live
Repository, planning system or both
Execution
How it may be recorded
A work item, such as a task or issue
Where it can live
Repository when the person or agent needs the project knowledge outside the tracker; may reference an external work item
Execution
How it may be recorded
Implementation
Where it can live
The source repository
Assurance
How it may be recorded
Verification evidence and, when useful, a verification record
Where it can live
CI or test platform, repository or both
Assurance
How it may be recorded
Traceability links and, when useful, a central table, matrix or tool view
Where it can live
Across the connected systems; a repository table when one shared view must remain available
Instructions used across all layers

Agent execution overlay

Not a seventh layer

Provides practical instructions for how agents should find project knowledge, work within project boundaries and verify their changes.

How it may be recorded
AGENTS.md or equivalent agent instructions
Where it can live
A repository location the intended agents can find before they begin work

The Agent execution overlay is shown separately because it supports work across all six layers. It does not become a seventh layer or take responsibility for Governance, Product Definition, System Design, Delivery Planning, Execution or Assurance decisions.

8.2 Judge a record by its content, not its filename

After identifying the ADEL layer, check whether an existing file, page or tool already carries that information clearly. Its name does not need to match ADEL terminology. What matters is which decisions it contains and whether the project treats it as the source of truth for those decisions.

The examples below use familiar names while still serving clear ADEL responsibilities.

product-spec.md
ADEL responsibility
Product Definition
Why it fits
It states the intended users, scope, requirements and acceptance criteria.
technical-overview.md
ADEL responsibility
System Design
Why it fits
It describes the intended components, boundaries and interactions.
docs/decisions/
ADEL responsibility
System Design decision records
Why it fits
It preserves important technical choices, their rationale and replacement status.
AGENTS.md
ADEL responsibility
Agent execution overlay
Why it fits
It gives agents repository-specific instructions, limits and verification commands.

Keep terminology the team already understands. Rename or recreate a record only when the existing name or structure makes its purpose difficult to understand.

8.3 Make the source of truth accessible

After choosing the source of truth and its location, confirm that the people and agents doing the work can reach the relevant information. The source may stay in Jira, Confluence, a continuous integration system, an architecture platform or the repository; ADEL does not require it to be moved into Git.

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.

Confirm how the agent will obtain the required project knowledge before work starts

Naming Confluence, Jira or another system as the source of truth is not enough if the agent cannot reach it. The work must provide either approved direct access or an approved work-item-specific copy of the relevant information.

Access check

Can the agent access the relevant part of the source of truth through an approved connection or account?

Yes — use the source directly

Give the agent only the access needed for the work, preferably read-only. The work item identifies the relevant page or section and, when later changes could matter, the version or date used.

No — provide only the approved information needed

An approver copies or approves the requirements, constraints and acceptance criteria needed for the work item, then places them in a record the agent can access.

Can that information be provided and confirmed as current?

Yes — continue with the approved information

Record the source of truth, link, version or retrieval date, and who supplied or approved the copied information when that confirmation matters.

No — stop the affected work

The agent reports the missing information and waits for approved access or an approved work-item-specific copy. It must not guess what the inaccessible source says.

Example: a PRD in Confluence

In this example, the agent cannot open Confluence. The product owner places only the requirements needed for Task 01 in the accessible work item and records the Confluence page, version and retrieval date. Confluence remains the source of truth; this block identifies the version used for the work item.

TASK-01.md · excerpt
## Source details

Source of truth: Confluence — Contact Form PRD
Source location: [internal Confluence link]
Version used: 12
Retrieved: 10 September 2026
Copied information approved by: Product owner

Relevant requirements for Task 01:
- FR-05: Invalid input is rejected in the browser and on the server, with accessible errors.
- FR-07: Show a useful response when delivery fails.
- FR-08: Deliver valid inquiries to the shared inbox.
- NFR-04: The form-handling path does not retain a copy of an inquiry after forwarding.

The copied block is not a second PRD. If the Confluence requirements change, the work item must be checked and updated before the agent relies on it again.

Do not give an agent unrestricted enterprise access or a person’s credentials. Direct access should follow the project’s security controls and be limited to the systems, spaces and actions needed for the work.

External source and repository roles

These examples show when the external system can stand alone and when an approved copy in the repository serves a different purpose.

Jira tracks priority, assignment, dependencies and workflow state
What to add in the repository, when useful
Add a repository work item when the person or agent doing the work needs approved scope, constraints or acceptance criteria without relying on Jira access
CI executes the automated checks and retains their raw results
What to add in the repository, when useful
Add a verification record when the project must keep what the results showed, what else was checked and what remains unverified
An architecture platform may hold the diagrams and the system model used as the source of truth
What to add in the repository, when useful
Add a summary of the approved design in the repository only when developers or agents need that information beside the code and cannot reliably use the platform directly
A pull request records a specific change, its review discussion and its diff
What to add in the repository, when useful
Add traceability references in the pull request, or maintain a shared view when direct links no longer reveal the requirement, design, work item and verification connected to the change

8.4 Keep project knowledge available for future work

Section 8.3 asks whether the person or agent doing the work can reach the information now. This subsection asks a different question: will the next person or agent still be able to find the decision, information or conclusion after the current conversation, meeting, CI run or work session is over?

8.5 Example: organize the records of an existing project

This example applies Sections 8.1–8.4 to a project that already has documents and tools. It covers how to identify and organize the project’s existing records. Section 11 combines this work with the other steps needed to adopt ADEL across the project.

01
List the records and systems the project already uses
02
Identify the ADEL responsibilities each source already covers
03
Confirm the source of truth for each decision
04
List the missing information and conflicting sources that affect the work
05
Add or reorganize records only to resolve those specific problems

What existing sources may already provide

Use this list as a starting point for the inventory. A source may support more than one layer, so inspect its actual content rather than assigning it by filename alone.

README.md
What it may already provide
Project overview, setup and entry-point information
docs/system-design.md
What it may already provide
Approved design
Jira epics
What it may already provide
Product requirements, delivery scope or planning information
GitHub Issues
What it may already provide
Work tracking, and possibly work-item details
docs/decisions/
What it may already provide
Decision records and architectural decision history
Pull requests
What it may already provide
Implementation history, review information and traceability links
CI runs and test reports
What it may already provide
Verification evidence
Engineering handbook
What it may already provide
Governance principles, engineering policy or working guidance
CONTRIBUTING.md, developer guide
What it may already provide
Repository working conventions
Existing agent instructions
What it may already provide
Agent instructions

Missing and conflicting information require different responses. If no approved design exists and the gap is causing problems, create one. If three architecture documents disagree, first use Section 6 to identify the source of truth for each disputed decision.

8.6 Use the smallest record structure that works

Use the smallest record structure that keeps current project knowledge easy to find and the necessary evidence available. This changes how knowledge is divided across files, pages or tools; it does not remove an ADEL responsibility.

The distinction below separates information used across many changes from records created only when a specific decision, work item, handoff or verification result must be kept.

Maintain the shared foundation

These records carry project knowledge used across many changes. They may be short, combined with other records or stored outside the repository, but the current knowledge must remain available.

Governance principles

Review when project-wide rules, constraints or decision authority change.

Product intent and requirements

Review when the intended users, outcomes, scope or requirements change.

Approved design

Review when system boundaries, components, data flows or integrations change.

Agent instructions

Review when agent instructions, boundaries or required checks change.

Then, as the work produces decisions, work items, delivery plans or evidence
Create another record when the work requires it

Create another record when a decision, work item, handoff or result must remain available and the information is not already preserved elsewhere.

Future work needs the reason or history behind an important design decision
Decision record
A clearly scoped change needs a work item outside the current tool or session
Work item
Sequencing, dependencies or responsibility must transfer between people or teams
Separate delivery plan
A verification result must remain available after the immediate review
Verification record
Direct links no longer show the complete path from intent to evidence
Shared traceability view
Information is already preserved or will not be needed later
Do not create another record

The left column shows the information that is always needed. The other two columns show when a short entry is enough and when a separate record is useful.

Verify the result before claiming completion
A lightweight form may be enough

Tests, review and CI evidence may be enough for the immediate change.

Use a separate record when

Keep a verification record when the conclusion, revision checked or remaining gaps must be available later.

Keep the path from intent to evidence traceable
A lightweight form may be enough

Direct links between the requirement, work item, change and test result may be enough.

Use a separate record when

Add a central traceability table, matrix or tool view when those links span too many records or an audit requires one view.

Keep the approved design understandable
A lightweight form may be enough

A concise section in an existing technical document may be enough.

Use a separate record when

Use a separate or more detailed design record when the system can no longer be understood or maintained from the concise description.

Example record structures

These two repository layouts apply the same ADEL responsibilities with different amounts of separation. They are examples, not required directories or migration targets.

concise project
project/
|-- README.md
|-- AGENTS.md
|
|-- docs/
|   |-- project-principles.md     # A short list of principles is enough
|   |-- prd.md                    # As short as the intent allows
|   |-- blueprint.md              # As short as the design allows
|   |-- adr/                      # Added when important design decisions need a record
|   |-- tasks/                    # Added when work-item details must remain available
|   `-- verification/             # Added when results must remain available
|
|-- src/
`-- tests/

Governance principles, product intent and requirements, and the approved design each use one short file. Decision, work-item and verification directories are added only when work creates a continuing need for those records.

Section 9 explains how complexity, risk and legal, contract or audit requirements affect how much detail and separation a project needs.

Section 9

Scaling the framework to the project

Scaling ADEL means choosing how much detail, record separation and change control the project needs. It does not mean removing layers from a small project or requiring every possible document in a large one.

Choose from the project’s actual complexity, lifespan, contributors, risks and legal, contract or audit requirements—not from team size alone. A five-person medical-device project may need stricter approvals and more evidence than a fifty-person internal application. Section 8.6 explains which records can remain concise or be created only when needed. This section helps decide the detail, record organization and change control each project area needs.

How to use this section

Use the steps in order. The profile provides a starting point; the project’s actual conditions determine the final choices.

  1. Understand the dimensions

    Learn how much detail to keep, how to organize records and how changes will be controlled.

  2. Choose a starting profile

    Pick the example closest to your project to get starting values and guidance.

  3. Adjust each dimension

    Change any starting value that does not fit the project’s actual conditions.

  4. Revisit the choices

    Review them when risk, scope, contributors, lifespan or legal, contract or audit requirements change.

Understand the three dimensions

Each dimension answers a different question: how much to write, how to divide records and how strictly changes are approved. A profile suggests a starting value for each, but the values do not have to move together. For example, a small application may use concise, combined records while still requiring strict change control because it handles regulated data.

Detail

Question to answer

How much information must each layer record for people and agents to work without guessing?

MinimalDetailed
At the lower end

Short statements cover the important intent, rules, design and evidence.

At the higher end

Structured and versioned specifications cover several product areas, user scenarios and constraints.

Increase this when
  • More business rules or technical interactions
  • More possible failure cases
  • A longer expected project life

Record organization

Question to answer

How should project knowledge be divided across files, pages, tickets or systems?

CombinedSeparated by team or area
At the lower end

Related information shares a small number of records that remain easy to navigate.

At the higher end

Different layers, domains or subsystems use separate records with clear record maintainers and links.

Increase this when
  • More contributors or delivery teams
  • Independent domains or components
  • Frequent handoffs between people and agents

Change control

Question to answer

How much review, approval and evidence is required before a decision or change is accepted?

InformalFormal approval
At the lower end

Contributors update records directly when project policy allows it, and changes use the normal review workflow.

At the higher end

Named record maintainers, approvers, version status and retained evidence control important changes.

Increase this when
  • Greater safety, security, legal or financial consequences
  • Regulatory or contractual requirements
  • Audit and evidence requirements

Choose the closest starting profile

Each profile combines a practical example with typical starting values for the three dimensions. Choose the closest one, then change any value that does not fit the project.

Guidance for

Prototype / experiment

Example

A clickable prototype used to test whether prospective users understand a new service.

Useful when

Few contributors, limited lifespan and low consequences if the experiment is discarded.

Typical starting point

The marker shows a relative starting position, not a score or target.

Detail
Minimal
Record organization
Combined
Change control
Informal

Guidance by project area

The guidance for each profile is a starting point. Adjust any project area that does not fit. Every ADEL layer still applies.

GovernanceProject-wide rules, decision authority and exception handling.
Write only the project-wide rules that affect the experiment, such as data boundaries or who may approve release.
Product DefinitionIntended users, outcomes, scope, requirements and acceptance criteria.
State the problem, intended user, hypothesis and evidence that would make the experiment useful.
System DesignThe intended components, boundaries, data flows and integrations.
Record only the design choices and boundaries needed to build and evaluate the experiment safely.
Design decisionsThe rationale, consequences and status of important technical choices.
Preserve only a decision whose rationale will matter while evaluating or extending the experiment.
Agent instructionsRepository-specific instructions, boundaries and required checks for agents.
Provide short setup, boundary and verification instructions when an agent participates.
Delivery Planning and ExecutionClearly scoped work, dependencies, sequencing and coordination.
Use short instructions; add a separate work item only when its scope, constraints and acceptance criteria must stay available or pass to someone else.
VerificationChecks and evidence showing whether the expected result was delivered.
Record whether the experiment tested its hypothesis and what the result showed.
TraceabilityConnections from the original need through the change to its evidence.
Use direct references between the hypothesis, change and result.
A closer look at record organization

9.1 When to separate records

A profile suggests a starting value for record organization, such as Combined or Separated. Apply that guidance to each kind of project knowledge. Keep related information together while the record remains easy to read and update. Split it when parts have different maintainers, change at different times, need different reviews or make one record too long.

Product intent and requirements

Keep together while

One record remains easy to navigate, and its product areas are maintained and reviewed together.

Separate when

Product areas become difficult to navigate together or have different record maintainers and change schedules.

Approved design

Keep together while

One design explains the important components, boundaries and flows clearly.

Separate when

Independent subsystems or domains need different record maintainers or deeper design detail.

Governance principles

Keep together while

The rules apply project-wide and can be reviewed by the same approver.

Separate when

A distinct governance domain requires its own record maintainer, approval process or policy—for example, a separate data-retention policy.

Decision record

Keep together while

A decision log still keeps each decision, rationale, status and replacement relationship distinguishable.

Separate when

An important decision must be reviewed, linked, replaced or found independently.

Agent instructions

Keep together while

The same setup, boundaries and checks apply throughout the repository.

Separate when

A directory or subsystem genuinely needs different commands, constraints or verification instructions.

Work item

Keep together while

The work produces one clear outcome with one set of acceptance criteria.

Separate when

It contains independently deliverable outcomes, different assignees or sequencing that must be tracked separately.

Verification evidence

Keep together while

The evidence supports one reviewed conclusion for the same change or release.

Separate when

Evidence belongs to distinct capabilities, releases, risk domains or independently accepted work.

Section 10

Using optional starter templates

Section 4 explains what project knowledge each layer needs and shows common ways to record it. This section helps you choose a blank template when the project needs a new record. It does not redefine the project knowledge or require a separate file for every item.

Choose a starter template because the project is missing a useful record, not because every ADEL project must use the complete set. If an existing document, ticket, wiki page or project system already holds the information as a source of truth, keep using that source.

The blank, copyable versions are kept on the ADEL Starter Templates page. Work with ADEL shows completed examples inside one project. The Framework keeps only this overview so the rule, the reusable structure and the worked example are not confused.

The original ADEL templates are covered by the ADEL license and additional permission. Organizations and consultants may adapt them for delivery work under those terms.

10.1 Records used across many changes

These records keep information that remains useful across many changes. Start with a short record only when an existing source of truth does not already serve the same purpose.

Governance principles
ADEL responsibility
Governance
Use it when
The project needs one maintained place for rules that apply to every change and identify who may approve exceptions.
Product intent and requirements
ADEL responsibility
Product Definition
Use it when
The project needs one maintained source for its users, intended outcomes, scope, requirements and measures of success.
Approved design
ADEL responsibility
System Design
Use it when
People and agents need one maintained source showing the intended components, boundaries, data flows, integrations and operating design.
Agent instructions
ADEL responsibility
Agent execution overlay
Use it when
An agent needs repository-specific instructions, boundaries, commands and required checks.

10.2 Records created when needed

Create one of these records when a decision, handoff, work item or verification result must remain available after the current conversation or agent session ends.

Decision record
ADEL responsibility
System Design
Use it when
An important design decision and its rationale need to remain understandable after the immediate work ends.
Delivery plan
ADEL responsibility
Delivery Planning
Use it when
Another person, agent, team or session needs the approved scope and supporting information required to continue delivery.
Work item
ADEL responsibility
Execution
Use it when
One piece of work needs clear scope, an assignee, constraints and acceptance criteria that must remain available beyond the current conversation.
Verification record
ADEL responsibility
Assurance
Use it when
The result of a check, what was checked or its supporting evidence must remain available after the current work item or tool run.

10.3 Recording traceability in one place

A central traceability table gives the project one maintained view of the connections between needs, requirements, design, decisions, work, implementation and evidence. Direct links are enough while people can still follow the complete path.

Central traceability table
ADEL responsibility
Traceability across the six layers
Use it when
People need one maintained view connecting requirements to design, decisions, work items, implementation and verification evidence.
Section 11

Adopting ADEL

You can apply ADEL to a new or existing project without replacing its tools or rewriting all its documents. First identify where the project already keeps each kind of project knowledge defined by ADEL. Then address the missing, conflicting or inaccessible information that affects the work.

Adoption sets up how a project will use ADEL. It is different from the delivery lifecycle in Section 5, which describes how each piece of work moves from an understood need to verification and closure. All six layers and the Agent execution overlay still apply, but their records can start small. A new project can begin with concise Governance principles, product intent and requirements, an approved design and agent instructions. An existing project should keep the sources that already work and add or reorganize records only when the work requires it.

Use Section 9 to choose how much detail, record separation and change control the project needs. These choices may differ across parts of the same project.

Review

List what the project already uses

For an existing project, list the documents, tickets, tools, instructions and evidence people already use. Identify the ADEL layer or Agent execution overlay each record supports. For a new project, decide where the initial project knowledge will be kept.

Establish

Make core project knowledge easy to find

Make sure people and agents can find the Governance principles, product intent and requirements, approved design and agent instructions. Keep an existing source when it already provides the right information. Otherwise, create a concise record.

Confirm

Identify sources of truth and approvers

For each important decision, identify its source of truth and approver. An approver may be a named person, a role or a process defined by project policy. Link to existing sources instead of creating competing copies.

Record

Add records when the work creates a need

Create a decision record when an important System Design decision and its rationale need to remain available. Keep a delivery plan when scope, dependencies or responsibility must transfer. Create a work item when its scope, constraints and acceptance criteria must remain available beyond the current conversation or session.

Verify

Check the result and preserve the evidence

Check the implementation against the relevant Governance principles, requirements, approved design, accepted decision records and acceptance criteria. Keep the results and evidence when future work, review or policy will need them. Use direct references for traceability and add a central view only when those references are difficult to follow.

Improve

Fix recurring gaps and remove duplication

After several work items, review what happened. Combine records that repeat the same information. Add detail or clearer links where people or agents repeatedly miss project knowledge, cannot find a decision or lack evidence.

11.1 Check before implementation

Before implementation starts, confirm that this work is ready.

The goal, in-scope work and out-of-scope work are clear.
The relevant Governance principles, requirements, approved design and accepted decision records are available or linked, together with the delivery plan when one exists. If this work is intended to create missing design information, the work item says so.
Dependencies, blockers, migration needs, rollout constraints and significant risks are understood well enough to begin.
The person or agent can access the required project records, repository areas and tools.
The agent’s stop conditions and who or where to ask are stated.
Acceptance criteria describe an observable result.
The required checks are identified.

11.2 Check before closing the work

Before closing this work, confirm that the result and its evidence are complete.

Each relevant acceptance criterion has supporting evidence.
The required checks passed. Otherwise, each result is recorded as Failed, Not verified or Unable to verify.
If a requirement remains unmet, project policy allows an exception and the approver recorded the acceptance, reason and follow-up. Rules that allow no exceptions cannot be skipped.
The implementation remains consistent with the current Governance principles, requirements, approved design and accepted decision records.
Affected documentation, migrations, operational instructions and agent instructions are updated.
No important requirement or System Design decision exists only in the code or conversation history.
Someone can follow the references from the work back to its intent and forward to its verification evidence.
Remaining risks, limitations, unverified areas and follow-up work are recorded in the work item, verification record or delivery system.
Section 12

Common failure modes

This section lists common problems that can occur when a project applies ADEL. A project may create records and approval steps that add no value, fail to preserve information that people and agents need, allow the wrong layer to change a decision, or claim completion without enough evidence. Each table describes the problem, what happens and how to correct it.
12.1

Too much structure

The project creates files or process steps even when they do not help anyone make a decision, perform the work or verify the result.

Governance principles contain coding rules
What happens
Project-wide rules become difficult to find among implementation details that change frequently.
How to correct it
Keep project-wide rules, constraints and decision authority in Governance principles. Put repository instructions in agent instructions and coding conventions in the project’s engineering guidance or automated checks.
Agent instructions copy all project knowledge
What happens
Requirements, design information and rules are duplicated. The copies can become outdated, and the agent receives more information than the current work needs.
How to correct it
Keep agent instructions concise. Tell the agent where to find the Governance, Product Definition, System Design, work-item and Assurance sources of truth instead of copying their contents.
Every implementation choice gets a decision record
What happens
The project accumulates many low-value records, making important System Design decisions harder to find.
How to correct it
Create a decision record when an important System Design decision and its rationale need to remain understandable after the immediate work ends.
Every change requires a formal handoff
What happens
A separate handoff repeats information already available in the work item and delays straightforward work.
How to correct it
Use a separate delivery plan when sequencing, dependencies, release scope, migration needs or responsibility must transfer between people, agents, teams or sessions.
Every template becomes a required file
What happens
The project creates empty, repeated or irrelevant files simply because a template is available. People stop trusting or maintaining them.
How to correct it
Use a template only when the project needs that information in a separate record. Keep project knowledge used across changes as concise as the project allows, and create other records when a decision, handoff, work item or verification result needs to be preserved.
Traceability adds identifiers without useful links
What happens
Records receive IDs, but people still cannot find the need, design, work or verification connected to a change.
How to correct it
Add direct references between the related records. Use a central traceability table, matrix or tool view only when direct references are difficult to follow.
12.2

Missing or inaccessible project knowledge

Information needed for decisions, implementation or verification remains in memory, conversations, code or a system that the next person or agent cannot access.

A small project keeps no project records
What happens
The product intent, rules, design and verification results exist only in memory or agent sessions. Later work must guess or reconstruct them.
How to correct it
Keep concise records for the project knowledge people and agents need. A small project may combine information, but it still needs accessible sources for its important decisions and evidence.
Important decisions remain in conversations
What happens
The next person or agent cannot find the decision, its reason or the work it affects.
How to correct it
Update the source of truth for the layer responsible for the decision when the information must remain available after the conversation or session ends.
The source of truth is not updated
What happens
People and agents follow requirements, design information or instructions that no longer describe the current approved decision.
How to correct it
Update the source of truth when its decision changes. Include that update in the same work when later implementation or verification depends on it.
Copied external information has no source or version
What happens
People and agents cannot tell whether the repository copy still matches the source of truth in Jira, Confluence or another system.
How to correct it
Name and link the source of truth. Copy only the information needed for the work, and record the source version, date or revision when later changes could make the copy outdated.
12.3

Decisions or verification happen in the wrong place

A decision is made or recorded in the wrong ADEL layer, or the project reports a result as complete without checking all relevant requirements and acceptance criteria.

Product Definition and System Design contain the same decision
What happens
People cannot tell whether a statement defines the required outcome or the way the system should deliver it.
How to correct it
Keep required outcomes and behavior in Product Definition. Keep components, boundaries, flows and technical design in System Design. Link the records instead of repeating the same decision in both.
Passing tests are treated as complete verification
What happens
The tests may not cover every relevant requirement, System Design constraint, security requirement or acceptance criterion.
How to correct it
Check the delivered change against every relevant requirement and acceptance criterion, and record the supporting evidence. Record anything not checked as Not verified or Unable to verify rather than reporting the whole change as verified.
Implementation silently changes a requirement or System Design decision
What happens
A local code choice changes an approved outcome or system boundary without review by the approver for that decision.
How to correct it
Stop the affected implementation, identify the layer responsible for the decision and ask its approver to resolve it. Update the affected sources of truth before continuing.
Section 13

Foundations and related practices

ADEL provides one operating model for keeping human decisions and agent actions aligned from the initial need to completion. It builds on established software-engineering practices and connects them through explicit decision authority, agent boundaries, feedback and evidence. This section identifies those foundations and explains ADEL’s distinct contribution to human-agent delivery.

The entries are grouped by the role they play: an engineering foundation that ADEL complements, an independent approach that addresses a related problem, or a tool-specific example of how one part of ADEL can be implemented. Each entry explains what the referenced work provides and what ADEL contributes when people and agents use it together. None is a required product, provider, standard or development method.

External standards, conventions and product documentation were last reviewed in September 2026. Use the linked original sources for current details.

Third-party product and company names are used only to identify the referenced tools and sources. Their inclusion does not imply affiliation with or endorsement of ADEL.

Established engineering foundations

ADEL complements these established practices. It shows where their outputs fit, who approves related decisions, how agents find them and how they connect to later work and evidence. It does not replace a requirements standard, architecture practice or organizational software lifecycle.

Relates toProduct Definition
What this work provides

ISO/IEC/IEEE 29148 defines requirements-engineering processes and the information they produce across a system or software lifecycle.

What ADEL adds

ADEL places product intent and requirements in Product Definition, requires the project to name who may approve changes and links the requirements to the approved design, work items and verification evidence. People and agents can use the format the project already has; ADEL does not replace the standard or require its document structure.

Relates toSystem Design
What this work provides

Michael Nygard’s ADR practice gives a significant architectural decision a short record of its background, decision, status and consequences.

What ADEL adds

ADEL treats an ADR as a decision record in System Design. The project names its approver and links it to the requirements, work items and verification it affects. An ADR is one possible record, not a requirement for every implementation choice.

MADR — Markdown Architectural Decision Records

Relates toSystem Design
What this work provides

MADR provides a structured decision-record template covering the problem, decision drivers, considered options, outcome, consequences, confirmation and decision participants.

What ADEL adds

When a project uses a MADR-style record, ADEL identifies the responsible layer, while the project identifies the approver and links the decision to affected requirements, work items and evidence. MADR remains a separate template practice; ADEL does not require its format.

Relates toSystem Design
What this work provides

arc42 provides an adaptable structure for architecture documentation. The C4 model provides a hierarchy of system, container, component and code views.

What ADEL adds

ADEL treats relevant architecture records and views as part of the approved design. The project names who may approve changes and links the design to requirements, work items and verification. A project chooses how much architecture documentation it needs; ADEL does not require either structure or diagram set.

Relates toDelivery lifecycle and Assurance
What this work provides

ISO/IEC/IEEE 12207 provides a broad framework for software lifecycle processes and allows organizations to use different lifecycle models and methods.

What ADEL adds

Within the lifecycle a project already uses, ADEL shows where decisions are recorded, how agents find them and which evidence supports closure. It is not a substitute for an organizational software lifecycle or the standard.

Related approaches for working with agents

These independent projects also give agents specifications or instructions that remain available between sessions. ADEL can use their outputs while adding approval, conflict and verification responsibilities around them. ADEL does not reproduce or require these approaches.

GitHub Spec Kit — spec-driven development and constitution

Relates toGovernance, Product Definition, System Design, Delivery Planning and Execution
What this work provides

Spec Kit provides a command-based workflow for creating project principles, specifications, plans, tasks and implementation.

What ADEL adds

A project can use suitable Spec Kit outputs as ADEL records. ADEL adds Governance, Assurance, a requirement for the project to name an approver for each important decision and rules for conflicts with records outside the Spec Kit workflow. It does not copy or require Spec Kit’s commands, sequence or templates.

OpenAI Harness Engineering — concise agent instructions and deeper project records

Relates toAgent instructions and project-record organization
What this work provides

OpenAI describes using a short AGENTS.md as a “table of contents” that points coding agents to a structured repository knowledge base.

What ADEL adds

ADEL separates agent instructions, which say how an agent works, from project decisions, which say what the project must do. It connects the instructions to six responsible layers. A source of truth can remain in Jira, Confluence, CI or another approved system when the agent can access it or receives an approved copy of the information needed.

Kiro Specs — requirements, design and implementation tasks

Relates toProduct Definition, System Design, Delivery Planning and Execution
What this work provides

Kiro Specs uses a structured workflow that turns a feature or bug description into requirements, a technical design, and implementation tasks.

What ADEL adds

A project can use Kiro requirements, designs and tasks as ADEL records. ADEL also covers Governance, Assurance, approvers, conflicts and traceability across other tools. It remains independent of Kiro and does not require records to move.

BMAD Method — planning and implementation workflows

Relates toProduct Definition, System Design, Delivery Planning, Execution and Assurance
What this work provides

BMAD provides workflows that can produce product briefs, PRDs, architecture information, specifications, epics and stories before implementation and review.

What ADEL adds

A project can use suitable BMAD outputs as ADEL records. ADEL identifies the responsible layer for each important decision; the project names its approver and connects those outputs to records and evidence outside the BMAD workflow. It does not require BMAD’s sequence or roles.

AGENTS.md — open format for coding-agent instructions

Relates toAgent instructions
What this work provides

AGENTS.md is an open Markdown convention for giving coding agents instructions and project information, including more specific guidance in nested directories.

What ADEL adds

ADEL connects agent instructions to the six layers and states which project decisions they may not override. The framework does not require the AGENTS.md filename or define a competing file format.

Tooling examples

These product documents show that coding tools can find instructions stored at repository or directory level and use them in later sessions. They are implementation examples only: each tool defines its own supported files, which instructions to follow first and its limits.

Relates toFinding instructions and deciding which one to follow first
What this work provides

Codex documents how it finds AGENTS.md instructions in global, project and nested directory scopes, and how instructions closer to the working directory take precedence when guidance conflicts.

What ADEL adds

ADEL connects the instructions Codex finds to the project’s responsible layers, approved decisions and evidence. Codex documentation remains the source of truth for Codex behavior.

Relates toWhere instructions are found and which files apply
What this work provides

GitHub documents repository-wide, path-specific and agent instruction files supported by different Copilot surfaces.

What ADEL adds

ADEL connects Copilot instructions to the project’s responsible layers, approvers and verification evidence. ADEL does not require Copilot or replace GitHub’s rules for supported files and instruction scope.

Closing perspective

ADEL keeps people and AI agents working from the same current project knowledge. Each important action links back to the need, requirement, rule, design decision or work item behind it. It also links forward to the evidence used to review and close the work.

The six layers give each kind of decision a responsible place. The seven lifecycle steps show how people and agents use those decisions while work moves from an initial need to a verified result.

When new information changes an earlier decision, the project returns to the responsible layer. The approver resolves the decision, its source of truth is updated and later work is checked before delivery continues.

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. It supports every layer without replacing the decisions held there.

Projects may use different files, tools and amounts of documentation. What matters is that people and agents can find the current decision and its approver, trace it to the work it affects and see the evidence used to close that work.

Core operating idea

Write decisions down where people and agents can find them, link every change to the decision behind it and verify the result with evidence.

Every meaningful action should connect back to the need, requirement, rule, design decision or work item that authorized it and forward to the evidence used to verify it. Keep this information current and accessible so people and agents can continue the work without relying on memory or previous conversations.

License

How ADEL may be used

© 2026 Mark A. Basco. The ADEL content published at marklesterbasco.com/adel—including the Framework, Playbook, Work with ADEL walkthrough and starter templates, and their original text, diagrams and prompts—is licensed under Creative Commons Attribution–NonCommercial 4.0 International (CC BY-NC 4.0), with the additional permission stated below.

This license applies to ADEL’s published content, not the website source code, software, fonts or third-party assets. Third-party names, trademarks and works linked or referenced in these materials remain the property of their respective owners and are not covered by this license.

Additional permission for delivery work

In addition to the rights granted by CC BY-NC 4.0, anyone may copy, share and adapt ADEL material for commercial purposes when applying it to plan, govern, design, implement, verify or close software projects:

  • within your own organization, including a for-profit organization and across more than one project;
  • for a client or organization as part of paid consulting or contracting services; or
  • within one or more open-source software projects.

The organization, client or open-source project may retain, use and adapt the resulting adoption and project records for its own software work. Those records may be kept in private or public project repositories. All other CC BY-NC 4.0 conditions continue to apply. Private internal records and records delivered privately to a client do not require a credit line. When a public repository or another public release includes ADEL material or an adaptation, keep the copyright notice, attribution and license link, and identify changes as required by CC BY-NC 4.0.

This permission includes internal onboarding, coaching and knowledge transfer reasonably needed to adopt or apply ADEL during software delivery. It does not cover a paid engagement that reproduces, displays, distributes or adapts ADEL material primarily to teach ADEL, including a private workshop, course or train-the-trainer program. That use requires separate written permission.

Uses that require separate permission

Separate written permission is required to commercially sell, license or publish a book, course, training resource, certification program, template product or similar offering that reproduces, displays, distributes or adapts substantial ADEL material. This includes using ADEL’s protected text, diagrams, prompts, examples or templates as a significant part of the offering. Noncommercial sharing and publishing remain permitted under CC BY-NC 4.0. These terms do not restrict independently written discussion of the underlying ideas or any use that applicable copyright law permits without permission.

For commercial permission, contact Mark A. Basco.

Use of the ADEL name

The license does not grant trademark rights in the ADEL name or visual identity. You may accurately state that a software project applies ADEL or that independently created commentary discusses ADEL. You may not describe or market a product, service, publication, course, workshop or certification as “official ADEL,” “ADEL certified,” endorsed by ADEL or otherwise authorized by Mark A. Basco without written permission.

Suggested attribution

When sharing unmodified material
ADEL — Agentic Delivery & Engineering Lifecycle, © 2026 Mark A. Basco (marklesterbasco.com/adel), licensed under CC BY-NC 4.0 (creativecommons.org/licenses/by-nc/4.0/).
When sharing an adaptation
Adapted from ADEL — Agentic Delivery & Engineering Lifecycle, © 2026 Mark A. Basco (marklesterbasco.com/adel), licensed under CC BY-NC 4.0 (creativecommons.org/licenses/by-nc/4.0/). Changes were made.

In digital formats, link the title and license name. In print, show the web addresses.