FrameworkPlaybookTemplates
Created byMark A. Basco
← ADEL

The Playbook 

Practical ways to apply ADEL to real work.

Situational guidance for real projects: starting one, adopting ADEL on a codebase that already exists, running a change, preparing work for a coding agent, and supporting completion with evidence.

Download Markdownadel-playbook.md
Start here

Use the Playbook for the situation you’re in.

The Framework explains how ADEL works. This Playbook shows practical ways to apply it to real projects. It does not add mandatory steps, documents, or tools.

You do not need to read the Playbook in order.

The Playbook exists to make ADEL easier to apply, not to add another process. Use only the guidance that helps with the situation in front of you.

Project knowledge is the information a project keeps so people and agents can find its requirements, decisions, work and evidence. A source of truth is the record the project treats as correct for a particular decision or kind of information. An approver is the person, role or approval process allowed to accept or change a decision. The Agent execution overlay is the guidance that tells coding agents where to find project knowledge, how to work in the repository and when to stop.

FrameworkUnderstand ADEL’s layers, lifecycle and rulesPlaybookApply ADEL in common situationsTemplatesUse starter structures for project records

Choose how to begin

New to ADEL?

Follow one small project from idea to verified implementation, with the prompts and project records shown where they are used.

Work with ADEL→

Already working on something?

Jump straight to the situation you are dealing with.

Find your situation→
Getting started

Starting a new project

When you’re hereYou are starting a project and want enough shared project knowledge in place before implementation begins.

A new project does not need every example record on day one. Record enough shared project knowledge for people and agents to understand what is being built, which decisions are approved and which questions remain open.
Step 1

Understand the need

Capture enough to explain:

  • the problem or opportunity
  • affected users and stakeholders
  • the desired outcome
  • important constraints
  • what success means

Do not turn this into a complete specification yet. The goal is to understand enough to establish the project’s initial intent.

Step 2

Establish project knowledge used across changes

Make lasting project knowledge easy to find. Reuse existing sources of truth where they already work; otherwise start with concise records for information that will remain relevant across many changes. What matters is that each source of truth is clear and accessible, not what the file is called.

Governance
Typical record
Governance principles — often a constitution, engineering principles or a project charter
Start by recording
The project-wide principles and constraints that apply to every part of the project
Product Definition
Typical record
Product intent and requirements — often a product requirements document (PRD), product brief or requirements document
Start by recording
Problem, users, scope, required outcomes, and how success will be judged
System Design
Typical record
Approved design — often a blueprint, architecture document or technical design
Start by recording
Major boundaries, responsibilities, flows, constraints, and unresolved design questions
Agent execution overlay
Typical record
Agent instructions, when coding agents are part of the workflow — often AGENTS.md
Start by recording
Where sources of truth are kept, operating rules, required commands and when to stop and ask
Step 3

Create additional records only when needed

Decision record

Record an important architectural decision when future work will need to understand why it was made. An architecture decision record (ADR) is one common format.

Delivery plan or handoff record

Use one when work must be coordinated or transferred between people, agents, teams or releases.

Work item

A work item may be a task, issue, ticket or instruction for one clearly scoped piece of work. Use a separate record when its scope, constraints and acceptance criteria must remain available after the current conversation or agent session, or to someone who cannot access the tracker.

Verification record

Use one when the verification result must remain available beyond the evidence already kept by project systems.

Central traceability table

Use one when people can no longer follow the relationships through direct references, or when legal, contract or audit rules require one shared view.

Some project knowledge remains relevant across many changes. Create the additional records only in the situations listed above. Records used across changes and records created when needed.

Step 4

Check that the project is ready for its next decision or work item

  • the problem and intended outcome are understandable
  • important governing constraints are easy to find
  • the main system parts and boundaries are clear enough to guide the next decision
  • people and agents can find the sources of truth they need
  • unresolved questions are visible rather than silently assumed

You do not need every answer before work begins. You need enough shared understanding to know what is decided, what is still open, and where the next decision belongs.

See it applied

Follow the worked project from an empty workspace and one sentence of intent to a product brief that later work references.

Work with ADEL — Build something from scratch→
Getting started

Adopting ADEL on an existing project

When you’re hereYou are introducing ADEL to a project that already has documentation, tickets, code and conventions.

An existing project usually has useful project knowledge already—in documentation, tickets, code, tests, conventions or external systems. Before creating anything new, identify what information and decisions the project already has and where they are kept.

Before writing new records, identify what the project already has and how it maps to ADEL.

Playbook guardrail

Keep the project’s existing records and match them to ADEL’s layers. Add or reorganize records only when important information is missing, conflicting, inaccessible or unclear.

Framework → §11 Adopting ADEL · §8.2 Judge a record by its content, not its filename
1
Inventory what already exists

Look across everything the project has accumulated, not only the files that look like documentation.

  • documentation
  • tickets and issues
  • architecture records
  • source code
  • tests and continuous-integration (CI) results
  • policies and conventions
  • agent instructions
  • external project systems
2
Determine what each source holds and whether it is the source of truth

Identify the information, decision, instruction, implementation or evidence each record holds. Then match it to the ADEL layer or Agent execution overlay it supports. A wiki page, a ticket and a task may all repeat the same requirement, but only one should be its source of truth.

  • What information or decision does it carry?
  • Which ADEL layer or the Agent execution overlay does that belong to?
  • Is this the source of truth for that decision?
3
Check whether it is current, accessible and usable

A stale source of truth can be more damaging than a missing one, because people and agents may continue to trust it.

  • Is it current?
  • Can the people who need it reach it?
  • Can relevant agents reach it?
  • If direct access is not allowed, does the work item contain enough approved information?
  • Can the relevant portion be found without loading or copying everything?
4
Identify gaps and conflicts

When two records disagree, identify what kind of decision is in conflict and resolve it at the ADEL layer responsible for that decision. Do not assume that the newest record or the existing code is automatically correct.

  • important information that exists only in memory or in the code
  • duplicate sources of truth
  • stale documentation
  • disagreement between sources
5
Change only what improves the project

Update, add, connect, split or remove information only when doing so makes the source of truth, approver, access or meaning clearer. Creating a record that duplicates a source the team already trusts makes the project harder to navigate.

Map what you already have

Work through the project one source at a time. These rows are illustrations of the exercise, not a lookup table.

Product specification
Information it holds
Product requirements
ADEL layer or Agent execution overlay
Product Definition
Source of truth?
Yes
Current?
Yes
Accessible?
Yes
Action
Keep
system-design.md
Information it holds
System architecture
ADEL layer or Agent execution overlay
System Design
Source of truth?
Yes
Current?
No
Accessible?
Yes
Action
Update
Epic in the tracker
Information it holds
Requirement and delivery scope
ADEL layer or Agent execution overlay
Product Definition / Delivery Planning
Source of truth?
Partly
Current?
Yes
Accessible?
People only
Action
Link to it; copy only the approved information an agent needs into its work item
Issue
Information it holds
Current work item
ADEL layer or Agent execution overlay
Execution
Source of truth?
Yes, for the work
Current?
Yes
Accessible?
Yes
Action
Keep
CI run
Information it holds
Automated test evidence
ADEL layer or Agent execution overlay
Assurance
Source of truth?
Yes, for raw evidence
Current?
Yes
Accessible?
Yes
Action
Link
Existing agent instructions
Information it holds
Agent instructions
ADEL layer or Agent execution overlay
Agent execution overlay
Source of truth?
Yes
Current?
Yes
Accessible?
Yes
Action
Keep and reconcile
You are ready to continue when
  • you know where important project knowledge currently lives
  • you know the source of truth for each decision
  • important stale or conflicting sources are identified
  • when approval, acceptance or an exception may be required, the approver or approval process is easy to find
  • people and agents can reach the project knowledge they need
  • important missing knowledge has been identified
  • you have not created duplicate documents only to match ADEL examples

You do not need to clean up the entire project before using ADEL. Fix the gaps and conflicts that matter to the work in front of you, and improve the project as new work passes through it.

Getting started

Applying ADEL to a change

When you’re hereYou have a change to make, of any size, and want to know which parts of the model it actually touches.

ADEL applies to both small changes and substantial system changes. Start from the project knowledge that already exists, and add or update only what the change affects.
Framework rule · §5

Return each affected decision to the layer responsible for it and update its source of truth before continuing. One finding may affect several decisions.

Read it in the framework↗
The framework lifecycle, applied to one change

There is one ADEL lifecycle. These are its seven steps, shown here for a single change.

1
Understand the need

Understand what is being requested and why.

2
Define the required outcome

Find or clarify the relevant requirement, expected behavior or acceptance criterion.

3
Design the solution

Use the existing design where it already covers the change. Update it only when the change actually affects System Design.

4
Prepare the work

Determine the scope, dependencies, order of work, rollout, and whether a separate delivery plan or handoff record is needed.

5
Break down the work as needed

Decide whether the change fits in one clear work item. Create a separate work-item record only when its scope, constraints and acceptance criteria must remain available after the current conversation or agent session, or to someone who cannot access the tracker.

6
Implement the change

Make the change within the relevant requirements, design, decisions and constraints.

7
Verify and close

Check the result against the relevant requirements, acceptance criteria, governing rules and required checks. Keep the evidence and links when future work or review will need them.

Governance principles
Relevant requirement
Relevant approved design
Relevant decision records, if any
consulted by
Current change
What changes as the work gets larger

Every change uses the same ADEL layer responsibilities. A small change may use almost entirely existing project knowledge; a larger change may require new decisions, planning, records and evidence.

Tiny change

Rename “Create account” to “Sign up”.

Usually relies on
  • existing project knowledge
  • a clear instruction or issue
  • implementation
  • the checks required for this change
Usually does not create
  • a separate decision record
  • a handoff
  • a separate work-item record
  • a separate verification record

It uses the existing requirements, approved design and governing rules that apply; it does not recreate them.

Normal feature

Add password reset.

Usually relies on
  • a clear required outcome
  • the relevant approved design
  • a clearly scoped work item
  • the tests and other checks required for this feature
  • links that make the path from intent to implementation and evidence easy to follow
Usually does not create
  • a separate decision record, unless an important architectural decision arises
  • a handoff

Use a separate work-item record when this information must remain available after the current conversation or agent session, or to someone who cannot access the tracker. An existing issue or ticket may already meet that need.

Architecture-affecting change

Move authentication to an external identity provider.

Usually relies on
  • a review of the relevant Product Definition
  • an update to the approved design
  • a decision record when future work will need the reason for an important architectural decision
  • a delivery plan that covers the affected work, dependencies and rollout
  • clearly scoped work, potentially across several work items
  • verification across the affected requirements and design constraints
  • traceability across the affected requirement, decision, work, implementation and evidence

Product Definition changes only if the required outcome, scope, behavior or acceptance criteria also change. Moving a system boundary is a System Design change even when the required outcome stays the same.

All three changes use the same layer responsibilities. Larger changes need more new decisions, records, planning and evidence.

See it applied

See what the agent found during implementation, which approved decision it contradicted and which project records were updated before work resumed.

Work with ADEL — Build something from scratch→
Working with people and agents

Preparing work for a coding agent

When you’re hereYou are about to give a clearly scoped work item to a coding agent.

Before giving work to a coding agent, make sure it can find the project knowledge that applies to the change. Do not copy all project knowledge into the prompt. Give the agent a clearly scoped work item and links to the relevant sources of truth.
Before implementation, the agent should be able to find
  • relevant Governance principles
  • the relevant requirement or intended outcome
  • the relevant approved design
  • relevant decision records
  • the current work instruction, issue or work item
  • required check commands
  • relevant acceptance criteria
  • where approval, acceptance or an exception may be needed: the approver or approval process

ADEL does not automatically control the agent. Agent instructions and the current work item state what it may change, where it should find approved decisions and when it must stop. Tool permissions limit what it can actually do. The project must also identify the approver or approval process for decisions outside the agent’s authority. A solo developer may be the approver for several kinds of decisions.

Give the agent direct references to the project knowledge it needs

AGENTS.md helps the agent navigate the project. The current work item defines the scope of the change and points to the sources of truth that apply.

AGENTS.md

How to navigate the project, work in the repository, run the required checks and know when to stop and ask.

Current work item

What is changing, what is in and out of scope, and when the agent must stop.

References to only what applies
Requirement / outcome

Why the change exists and what it is expected to achieve

Approved design

Where the change belongs and which boundaries it must preserve

Relevant decision records

Earlier design decisions that constrain the approach

Acceptance criteria

What the result needs to demonstrate

Required checks

Which tests, builds and checks should be run

The current work may be a task, issue, ticket or concise instruction. Use whichever record already holds enough information and clear boundaries.

Framework rule · §3

The project’s records hold its requirements, decisions, work and evidence. Agent instructions tell an agent where to find those records and how to use them. They should point to the relevant Governance principles, Product Definition, System Design, decision records, work items and verification practices instead of copying or replacing them.

Read it in the framework↗
Do not solve a missing decision with a bigger prompt

A more detailed prompt does not replace a missing requirement or unresolved design boundary. If the work requires the agent to decide what the product should do, whether a boundary should move, or whether a constraint can be relaxed, return that decision to the responsible layer.

Playbook guardrail

If the agent cannot proceed without making a product, architecture or governance decision it is not allowed to make, resolve that decision at the responsible layer before implementation continues.

Framework → §2.4 Treat AI agents as capable contributors with clear decision limits · §6 Source of truth and conflict handling
The work is ready for an agent when
  • the agent knows what outcome it is responsible for
  • the scope and boundaries of the change are clear
  • it can find the relevant requirements and design
  • important existing decisions are easy to find
  • required checks are known
  • the repository areas, tools and actions it may use are clear
  • its stop conditions are clear
  • it knows which approver or approval process should receive a conflict or unresolved decision
See it applied

The same practice in sequence: how the example project’s AGENTS.md was written, and how the prompts after it stopped restating the project.

Work with ADEL — Build something from scratch→
Working with people and agents

Give each work item the project knowledge it needs

When you’re hereA source of truth is long or spread across several systems, and the current work needs only part of it.

A person or agent may be able to open a source of truth but still struggle to find the part needed for one change. The work item should point to the exact sections and decisions that apply.
Framework rule · §2.3

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.

Read it in the framework↗

Keep the source of truth complete. In the work item, identify only the sections and decisions that apply. Give the person or agent enough information to continue without searching through or reconstructing the whole project.

Reference sources of truth
Instead of
Copy the entire knowledge base into every work item, handoff or prompt
Point to the relevant requirement, section, decision or part of the system
Instead of
Link to a large source without saying what part applies
Copy only the information needed for the work when direct access is unavailable or not allowed
Instead of
Paste the whole source because part of it is relevant
For coding agents, use AGENTS.md as a map into deeper sources
Instead of
Turn AGENTS.md into the knowledge base itself
Keep large sources easy to navigate by section, product area or part of the system
Instead of
Leave important project knowledge in one unstructured block
Identify a copied source and, when later changes matter, record the version, date or other reference used
Instead of
Copy information without recording where or when it came from
One change, two ways to identify the project knowledge it needs

The work changes how long a user can remain signed in without activity. Here, NFR means non-functional requirement.

No useful direction

Read all product requirements, the complete approved design,

every decision record and all security documentation.

Focused references

Product requirement: NFR-07

Approved design: Authentication §4.3

Decision record: ADR-011

Security policy: Session management §2

Required check: authentication integration suite

Each source of truth stays complete. The work item points directly to the parts needed for this change.

Working with people and agents

Passing work between people and agents

When you’re hereWork is changing hands — between people, between agents, or across the two.

When work moves to another person or agent, the next participant must be able to find the current scope, relevant decisions, completed work and remaining questions. Information kept only in someone’s memory or a temporary session can be lost during the transfer.
Framework test · §8.4

Will the next person or agent still be able to find the decision, information or conclusion after the current conversation, meeting, continuous-integration (CI) run or work session is over?

Read it in the framework↗
Who does the work may change

The framework does not prescribe who performs the work. The next person or agent must be able to find the information needed to continue without guessing decisions or repeating work.

Person → Person
Person → Agent
Agent → Person
Agent → Agent
Information the next person or agent needs

When someone else takes over — person or agent — they should be able to determine:

What is being done

The current objective and the boundaries of the work item.

Why it matters

The relevant requirement or intended outcome.

What constrains it

Relevant Governance principles, the approved design and accepted decision records.

What has already happened

Work completed, decisions made and relevant findings.

What remains open

Unresolved questions, blockers and known risks.

How completion will be judged

Acceptance criteria and required checks.

Where the sources of truth are

References to those records, rather than a copy of the project’s history.

Use the record that matches the need

Moving work to someone else does not automatically require a separate handoff record.

A small, clearly scoped change moves to another person or agent
Which record may hold the information
An existing issue, instruction or task may be enough
Delivery scope or sequencing transfers between teams or releases
Which record may hold the information
Use a delivery plan or handoff record to keep the transferred scope, sequence and dependencies
Implementation pauses and another person or agent continues
Which record may hold the information
The current work item, plus completion notes
An important architectural decision arose
Which record may hold the information
An architecture decision record (ADR)
Verification work changes hands
Which record may hold the information
Use referenced evidence; add a verification record when the result must remain available beyond the existing evidence system

ADEL identifies the project knowledge that must remain available after a handoff. The project chooses how to assign or transfer the work. Boundaries.

Keeping project knowledge current

Managing records over time

When you’re hereYou want to know when a record is created, when it changes, and what happens to it afterwards.

Different project records change at different times. Keep records used across many changes current as the project changes. Create other records only when a decision, handoff, work item or verification result needs to be kept. Existing sources of truth can follow the same pattern without being renamed or recreated.
Records used across many changes

These describe the project across many changes. The table below shows when they are commonly created or updated. The project decides how long to keep each record.

Governance principles — often a constitution or charter
Establish when
Project-wide Governance principles need to be recorded
Update when
A governing principle or governance rule changes
Product intent and requirements — often a product requirements document (PRD) or product brief
Establish when
Product intent and requirements need to be recorded
Update when
Product intent, scope, a requirement or acceptance criteria change
Approved design — often a blueprint or architecture document
Establish when
The approved design needs to remain available for future work
Update when
The approved design changes
Agent instructions, when agents are used — often AGENTS.md
Establish when
Coding agents need agent instructions that remain available between sessions
Update when
Repository navigation, working rules, required checks or source locations change
Records created when needed

Create these only when the work produces the corresponding need.

Decision record — often an architecture decision record (ADR)
Create when
Future work will need the reason for an important architectural decision
Update or close when
Its status or replacement changes; retained as decision history
Delivery plan or dedicated handoff record
Create when
A delivery plan must be transferred, coordinated or preserved
Update or close when
Delivery scope, conditions required to start, sequencing or dependencies change
Work item — often a task, ticket or issue
Create when
A clearly scoped work item must remain available outside the current tool or session
Update or close when
Scope, constraints or acceptance criteria change; closed according to project workflow
Verification record
Create when
The verification result must remain available beyond the evidence already kept by project systems
Update or close when
Evidence, findings or verification status changes
Central traceability table or matrix
Create when
People can no longer follow the relationships through direct links easily
Update or close when
Relationships change; maintained only while it remains useful
Record lasting decisions before temporary information disappears

Closing a work item does not automatically mean discarding useful information. When the work produces a decision or finding that future work will need, update the source of truth in the responsible layer before the temporary record closes.

What happened

A task reveals an important architectural decision.

What not to do

Leave the decision only in the closed task.

What to do

Update the approved design or create a decision record, reference it from the task, then close the task.

Keeping project knowledge current

How much detail is enough

When you’re hereYou are writing or reviewing something and want to know whether it is enough.

Enough detail is not a page count. Each ADEL layer has enough detail when the people or agents relying on it can answer that layer’s primary question without inventing decisions that belong elsewhere.
Framework rule · §2.8

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.

Read it in the framework↗

Ask whether the information lets the next person or agent make the required decision or perform the work without guessing. Length is not the measure.

Governance

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

Can someone tell which project-wide rules the work must follow and who may approve exceptions?

Show detailed checks
Sufficient when
  • the project-wide principles and constraints that actually govern the project are recorded
  • people and agents can tell what lower-level decisions are not allowed to override
  • important quality, security and governance rules can be found
  • it is clear how a governing rule is changed and who approves the change

Product Definition

What must we build, for whom, and why?

Can someone tell what the project or change is expected to achieve?

Show detailed checks
Sufficient when
  • the problem, intended users and desired outcome are understandable
  • scope is clear enough to distinguish what is and is not being built
  • relevant functional and non-functional requirements can be found
  • success measures and acceptance criteria are clear enough to judge the result

System Design

How will the system work, and why did we choose that design?

Can someone explain how the system will work and why the important design choices were made?

Show detailed checks
Sufficient when
  • important boundaries and responsibilities are understandable
  • the person or agent doing the work can determine where a change belongs
  • relevant flows, integrations and architectural constraints can be found
  • important design choices are recorded rather than left to accidental implementation
  • unresolved design questions are visible where they matter

Decision records are part of this test rather than a separate one. If future work will need the reason for an important decision, the approved design is not sufficient until that reason has been recorded.

Delivery Planning

Which work is ready, in what order, and who will do it?

Can the approved design be turned into work without making the implementation team guess the scope, dependencies or order of work?

Show detailed checks
Sufficient when
  • the portion of work being prepared is clear
  • dependencies that affect when or how the work starts are understood
  • delivery boundaries, rollout, migration or handover considerations are visible where they matter
  • unresolved blockers are known
  • the work can be divided into clear work items without redefining the product or architecture

This does not mean every change needs a handoff. For small work, the existing work item may already hold everything Delivery Planning needs.

Execution

What exactly is being changed, and how will we know it is done?

Can a person or agent complete this work item without having to guess what the project intended?

Show detailed checks
Sufficient when
  • the person or agent doing the work understands the expected outcome and the limits of the work item
  • scope and out-of-scope boundaries are clear enough to prevent accidental expansion
  • the relevant sources of truth can be reached
  • relevant constraints and decisions are easy to find
  • acceptance criteria and required checks are known
  • the person or agent can proceed without inventing Product Definition, System Design or Governance decisions

A task, issue, ticket or concise instruction may carry this work-item information.

Assurance

What evidence shows that the result works as required?

Can the project show what was delivered, which requirement or check it was compared with, and what evidence supports the result?

Show detailed checks
Sufficient when
  • relevant requirements, acceptance criteria, governing rules and required checks have supporting evidence
  • failed, unverified and unable-to-verify areas are explicit
  • important findings and deviations are visible
  • the available evidence supports the claimed completion result
  • people can follow the links between intent, implementation and evidence with the detail the project needs

Verification should happen before completion is claimed. Use a separate verification record only when the result must remain available beyond the existing evidence. Add a central traceability table only when direct references are no longer easy to follow or when project rules require one.

Agent execution overlay

How should a coding agent work in this repository?

Can an agent find the relevant project knowledge, follow the repository rules and know when to stop and ask the approver?

Show detailed checks
Sufficient when
  • an agent can locate the sources of truth it needs
  • repository or workspace operating rules are clear
  • commands for the required checks are easy to find
  • the agent knows which instructions to follow first and when to stop and ask
  • the agent instructions stay concise enough to guide the agent without duplicating all project knowledge

Add detail when a person or agent would otherwise need to guess, when an important decision must be kept, when information is hard to find, or when more evidence is needed. Otherwise, the extra detail only creates more maintenance work.

Assurance

Verification in practice

When you’re hereImplementation exists and you are deciding whether the work can be called complete.

Verification is more than running checks. The evidence must show whether the delivered work meets its requirements, acceptance criteria, governing rules and required checks.
Framework rule · §2.6

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.

Read it in the framework↗
Four questions before claiming completion

Answer these four questions during verification. They do not add four more steps to the ADEL lifecycle.

1

Identify what the result must meet

Which requirement, acceptance criterion, design constraint, governing rule or required check applies?

2

Compare the delivered result

Does the implementation meet that requirement or acceptance criterion, and does it stay consistent with the relevant design and constraints?

3

Evaluate the evidence

What evidence supports the result, what does it establish and, when important, does it identify the revision, build or environment actually evaluated?

4

Determine the result

What is verified, what is not, and what could not be verified? Are findings, risks and gaps recorded, and has the approver accepted any required exceptions?

Playbook guardrail

Verification happens before completion is claimed. A separate verification record is a different question: the pull request, the CI run, the work item or a completion note may already keep the result and its evidence. Create a dedicated record only when none of those sources keeps the result for as long as the project needs it.

Framework → §4.7 Verification evidence · §8.6 Use the smallest record structure that works
Evidence may include

Not every check applies to every change. Choose verification based on the relevant requirement, risk, governing constraints and required checks—not because an item appears in a list. Changing a button label and moving sign-in to a new provider should not use the same verification by default.

automated test resultscontinuous-integration (CI) resultsmanual observationsreview findingsstatic-analysis resultssecurity test or assessment resultsperformance measurementsaccessibility evaluation resultsmigration validation resultsoperational or runtime observations, when relevant
Record the conclusion honestly

For each requirement, acceptance criterion, governing rule or required check, record what the evidence actually shows. Use whatever status names the project already uses; the differences between the results below matter more than the labels. Keep the conclusion on the work item, in completion notes linked to CI, or in a separate record.

Verified

Available evidence supports the requirement, criterion, rule or required check.

Failed

Evidence demonstrates that a requirement, criterion or rule was not met, or that a required check ran and did not pass.

Not verified

Available evidence is incomplete, or the check was not performed.

Unable to verify

Verification could not be performed with the available access, environment, data, tooling or other required condition.

Then the overall result

If the project records an overall verification result, preserve the same distinctions. ADEL’s starter verification template uses Verified, Verified with findings, Failed, Not verified and Unable to verify as example terms; projects may use equivalent terms. Acceptance remains a separate decision.

Verified
Meaning
The relevant requirements and criteria are supported by sufficient evidence.
Verified with findings
Meaning
Evidence supports the relevant requirements and criteria, with findings or limitations stated for the work that was checked.
Failed
Meaning
Evidence demonstrates that a relevant requirement, criterion, rule or required check was not met.
Not verified
Meaning
Available evidence is incomplete or insufficient to establish the result.
Unable to verify
Meaning
The evidence needed to assess the result could not be obtained.
Two requirements from one change

The same change can produce different results for different requirements or checks.

Requirement

A valid contact-form inquiry must reach the firm’s shared inbox.

Evidence

A test inquiry reached the test inbox in preview build demo-57.

Result

Verified

Requirement

The form provider must not retain inquiry content after delivery.

Evidence

The provider’s production data-retention settings were not accessible in the test environment.

Result

Unable to verify

The second is not a failure and not a pass. Recording it as either would misrepresent what the project knows.

See it applied

See how one project records the evidence an agent produced, what could not be verified and why missing evidence cannot be treated as completion.

Work with ADEL — Build something from scratch→
Assurance

Traceability in practice

When you’re hereYou want people to be able to follow the links from intent to evidence.

Traceability means keeping the links between intent, design, work, implementation and evidence easy to follow. Direct references are often enough. Add a shared traceability view only when people can no longer follow those references or when project rules require stricter control.
Framework rule · §7

Traceability can be lightweight IDs, links and references. Do not create a central traceability view while these links remain easy to follow.

Read it in the framework↗

Start with direct references. Add a shared traceability view only when those relationships become difficult to follow.

Leave references as you work

These are relationships, not required filenames. A project may keep them in product requirements, an approved design, a decision record, a task or issue, a pull request, continuous-integration results or any other system that holds a source of truth.

Need / outcome
Requirement
Approved designDecision record, when needed
Work item
Implementation
Verification evidence
What the references can look like
references, in the records that carry them
FR-12
  Supports: BN-03

Approved design §4.2
  Meets: FR-12

Decision record ADR-004
  Applies to: FR-12; Approved design §4.2

Issue #21
  Implements: FR-12
  Design: Approved design §4.2
  Decision: ADR-004

Pull request (PR) #37
  Closes: #21

Verification
  Verifies: FR-12
  Evidence: continuous integration (CI) run #1842

Each record links to the earlier record that explains it. To find later records connected to a requirement, use repository search, tracker backlinks or links held by another system. Add a shared traceability view when those methods no longer show the complete path. In this example, BN means business need, FR means functional requirement and ADR means architecture decision record.

Choose the traceability approach that fits

These are three ways to keep traceability, not levels a project must complete in order. Choose the lightest approach that keeps the relationships easy to follow. Controlled traceability is required by legal, contract, audit or safety needs—not by project size. A small regulated system may need it from the first day.

Direct references
When it fits
People can follow the relationships through the connected records
Notes
Often sufficient
Shared traceability view
When it fits
Relationships span enough records, contributors or systems that direct references no longer show the whole picture
Notes
Adds one shared view of the relationships
Controlled traceability
When it fits
Audit, safety, regulation or another project rule requires reviewed relationships and evidence
Notes
Use when legal, contract, audit or safety requirements demand it
Test it in both directions

Check that the links work in both directions.

Forward

Starting from a requirement, can you find the relevant design, work item, implementation and evidence?

Backward

Starting from an implementation change, can you find the work item, requirement and reason for the change?

If people can follow both paths with the detail the project needs, the traceability is working. Adding identifiers everywhere is not enough when the links between records are still unclear.

Toolkit

Prompt patterns by situation

When you’re hereYou are working with an agent and want a starting point for a recurring situation.

These are optional, vendor-neutral starting points for recurring situations. They are not another ADEL workflow and are not meant to be run in sequence. Use the one that matches the work in front of you, and adapt it to the project knowledge the agent can actually reach.
Quick guide

These are situations, not lifecycle steps. A project may use some repeatedly, some occasionally and some not at all.

Starting a new project
Prompt
Draft the first project records
Where it fits
Records used across changes
Adopting ADEL on an existing project
Prompt
Map what an existing project already has
Where it fits
Adoption and discovery
Investigating architecture drift
Prompt
Check whether the code still matches the design
Where it fits
System Design / conflict handling
Work is understood and ready to prepare
Prompt
Prepare a work item
Where it fits
Delivery Planning → Execution
A work item is ready to build
Prompt
Implement a work item
Where it fits
Execution
Implementation needs to be assessed
Prompt
Check the result against what was required
Where it fits
Assurance / closure
Playbook guardrail

A prompt does not replace a missing project decision. If the work requires an unresolved Product Definition, System Design or Governance decision, resolve it at the responsible layer before asking an agent to proceed.

Framework → §2.4 Treat AI agents as capable contributors with clear decision limits · §6.1 Find where the decision belongs
A missing example record does not always mean knowledge is missing

During later work, a missing example record does not by itself justify creating one. First determine whether the project knowledge exists elsewhere, whether an earlier decision is unresolved or whether the current work is responsible for creating the record.

The knowledge exists elsewhere

Reference the existing source of truth, whatever it is called and wherever it lives.

The knowledge does not exist because an earlier decision is still open

Report the gap and the layer responsible for the decision. Do not invent the answer so the work can continue.

The knowledge exists but future work needs it in a project record

Create the record when the work allows it and another person or later work will need the information.

Map what an existing project already has
Missing record
No source of truth for Product Definition or System Design is found
What the agent should do
Report the gap; do not invent the missing decisions as part of mapping
Prepare a work item
Missing record
No approved requirement defines the requested outcome
What the agent should do
Stop and report the Product Definition gap
Prepare a work item
Missing record
No separate work-item record exists, but the work item must remain available outside the current tool or session
What the agent should do
Use the existing work-item form if sufficient; otherwise create a suitable project record such as a task
Implement work
Missing record
No approved design decision covers an important architectural choice needed for the work
What the agent should do
Stop and raise the System Design question. The agent may draft a proposal if the work allows it, but the approver must approve the decision separately
Verify work
Missing record
No verification record
What the agent should do
May create one within the approved scope when the work item, pull request or evidence system does not already preserve the verification result
Traceability review
Missing record
No central traceability table
What the agent should do
Do not create one automatically; first determine whether people can follow the direct references
Establish a new project
Missing record
The project does not yet have the Governance, Product Definition, System Design or agent instructions it needs
What the agent should do
May draft the missing records because creating the project’s initial records is the stated purpose of the work
How these prompts use project knowledge

Use these instructions with every prompt below. Add them, or equivalent instructions, when adapting a prompt for your project.

Project-knowledge instructions used with every prompt
add before the selected prompt
Before acting, locate the sources of truth relevant to the requested
work. Use the project's existing records regardless of their filename or
location. Do not create duplicate records only to use filenames shown in
ADEL examples when an equivalent source of truth already exists.

If required project knowledge is missing, inaccessible, outdated or conflicting:

- identify what is missing or inconsistent
- identify the ADEL layer responsible for the affected decision
- do not invent a decision that belongs to an earlier layer in order to continue
- create or update a project record only when the work item allows it,
  the required information is confirmed, and future work needs the record

Establishing a new project

Draft the first project records

Draft the project knowledge a new project does not yet have.

Open prompt
Use when
A new project needs concise records used across changes, and you understand the problem well enough to draft them.
Relevant ADEL parts
Governance, Product Definition, System Design, and the Agent execution overlay where agents are used.
Output
Concise drafts of the missing project knowledge—for review, not automatic adoption.
prompt
Determine whether suitable sources of truth already exist, and reuse
them where they do.

Where required project knowledge does not yet exist, draft concise initial
records for Governance, Product Definition, System Design and — when
coding agents are used — the Agent execution overlay.

Keep each as short as the work needs. Mark open questions rather than
resolving them by assumption. These drafts become sources of truth only
after the approver or approval process named by the project accepts them.

Adopting or diagnosing an existing project

Map what an existing project already has

Inventory what exists and identify each source of truth.

Open prompt
Use when
You are introducing ADEL to an existing project and need to understand what already exists before creating anything.
Relevant ADEL parts
Adoption and discovery — before changing any documentation structure.
Output
An inventory of sources, what each holds, which are sources of truth, and any gaps, conflicts, outdated information or access problems.
prompt
Review the project records available to you. For each record, identify:

- what information or decisions it holds
- which ADEL layer or the Agent execution overlay that information relates to
- whether the project treats it as a source of truth
- whether it is current and accessible

Do not create new records yet.

Then identify important gaps, conflicting sources, stale information,
project knowledge you cannot reach, and important knowledge that appears to exist
only in the code or in convention.

Check whether the code still matches the design

Compare the implementation against the approved design.

Open prompt
Use when
You are taking over an existing system, or the code and approved design may no longer agree.
Relevant ADEL parts
System Design and conflict handling.
Output
Where the code and approved design agree, where they differ, and which questions the System Design approver must resolve.
prompt
Inspect the existing implementation and the records that hold the approved design.

Identify where the code and the approved design agree, where they
differ, and where the records do not make clear which design should be followed.

Do not assume existing code automatically represents the approved design.

Preparing implementation

Prepare a work item

Turn the understood intent and approved design into a clearly scoped work item.

Open prompt
Use when
The required outcome and the relevant approved design are understood well enough to turn into work items.
Relevant ADEL parts
Delivery Planning → Execution.
Needs
The relevant requirement or outcome, approved design, governing constraints and accepted decision records where relevant.
Output
A work item with clear scope, constraints, references and acceptance criteria, with unresolved questions listed separately.
prompt
Locate and use the Product Definition source of truth, relevant approved design,
relevant accepted decision records and governing constraints for this work. Use the
project's existing records regardless of filename or location.

If that information is sufficient, prepare a clearly scoped work item using the
project's existing work-item form, or create a work-item record when the person or
agent needs it outside the current tool or session.

Do not introduce new product requirements, governing rules or important
architectural decisions. If required project knowledge is missing, conflicting,
inaccessible or unresolved, identify the gap and the ADEL layer responsible for it
instead of inventing the answer.

Implementing

Implement a work item

Perform the work inside its stated boundaries.

Open prompt
Use when
The work item has clear boundaries and the person or agent doing it can reach the relevant sources of truth.
Relevant ADEL parts
Execution.
Needs
The current work item, relevant requirements and design, constraints and required checks.
Output
Implementation that stays inside the approved boundaries and reports decisions that belong to an earlier layer instead of silently making them.
prompt
Locate the current work item and the sources of truth it references.
Implement within the stated scope, requirements, approved design, accepted
decisions and governing constraints.

If a required source cannot be found, or implementation exposes an
unresolved Product Definition, System Design or Governance decision, report
it and identify the responsible ADEL layer rather than treating it as a local
implementation choice.

You may draft a proposed record for that decision when the work allows it,
but leave it proposed: do not treat a newly discovered choice as an
approved project decision, and do not proceed as though it were.

Verifying and closing

Check the result against what was required

Assess evidence against the requirements, criteria, rules and checks that apply.

Open prompt
Use when
Implementation exists and enough evidence is available to assess whether the relevant requirements, acceptance criteria, governing rules and required checks were satisfied.
Relevant ADEL parts
Assurance — usually before closure, though verification may happen throughout implementation.
Output
A result for each requirement, criterion, rule or required check, using Verified, Failed, Not verified or Unable to verify, with its evidence and any outstanding findings.
prompt
Identify the relevant requirements, acceptance criteria, governing rules
and required checks for this change. Then trace them through the relevant
design, the implementation and the available verification
evidence.

For each one, state what the evidence shows: Verified, Failed,
Not verified, or Unable to verify with the available access or environment.
Give the evidence supporting each conclusion.

When evidence is important to the conclusion, identify what was actually
evaluated: the revision or build and the relevant environment, or the continuous-integration (CI)
run or pull request that already records them.

Do not claim verification without supporting evidence. Do not record a failed
or unperformed check as verified.

Use these prompts as starting points. Change their wording for the project and tool, but keep the stated purpose, limits and decision authority.

Toolkit

Use the tools you already have

When you’re hereYou want to know how ADEL works with the systems your project already uses.

ADEL works with the tools a project already uses. The project decides where each source of truth lives; changing tools does not change the responsibility of any ADEL layer.
Framework rule · §8.3

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.

Read it in the framework↗
Product requirements document (PRD)
Product Definition
Blueprint or architecture docs
System Design
Architecture decision records (ADRs)
System Design decision records
Issues
Delivery Planning and/or Execution, by purpose
Code
Implementation produced through Execution
Pull requests
Change and review history; traceability
Continuous integration (CI)
Assurance evidence
AGENTS.md
Agent execution overlay
Source of truth and approved copy

An approved copy holds only the information the work needs and states where it came from. It does not become a second version of the source.

Product platform
Holds the requirement as its source of truth
reference or approved copy
Repository work item
Holds the requirements needed for this work and cites the source

The work item does not become a second Product Definition.

CI platform
Holds the raw test results
reference
Verification record
States what those results establish

The record interprets the evidence; it does not copy it.

When connecting a tool, ask
  • What information or decision does this system hold?
  • Which ADEL layer or the Agent execution overlay does that belong to?
  • Is this system the source of truth for it?
  • Can the people or agents doing the work reach it?
  • If not, what approved information does the work actually need?
  • Will the copy identify its source and avoid becoming another source of truth?

These are illustrations, not recommended stacks. ADEL does not require a particular repository host, issue tracker, knowledge base, architecture platform, CI system or AI tool.

Toolkit

Worked examples

When you’re hereYou want to compare how the same ADEL responsibilities apply in three different project situations.

These examples combine the guidance from earlier sections. Section 3 compares a tiny change, a normal feature and an architecture-affecting change. The examples below show how ADEL applies when adopting it on an existing project, making a security-sensitive change and passing work between people and agents.
In each example, look for
  • which existing sources of truth are reused
  • which decisions actually change
  • which new records are created and why they are needed
  • what is deliberately not created
  • how completion is supported by evidence
  • what relationships remain traceable

Different project situations

The same layers applied to a different project, requirement and person or agent doing the work.

Existing project adoption

Adopt ADEL on a five-year-old service.
Reuses
Existing sources confirmed as current, approved and accessible after inspection—a wiki specification, a directory of decision records, contribution instructions and continuous-integration (CI) results.
Adds or updates
If coding agents are used, establish or reconcile agent instructions. Record important gaps or conflicts where they need to remain visible.
Deliberately not added
Copies of existing documents renamed to match ADEL examples.
Decision responsibility
No new project decision yet—this example is still mapping existing records.
Done when
Important project knowledge is matched to the relevant layers or Agent execution overlay, sources of truth are identified and important gaps or conflicts are visible.
Traceability
Whatever links already exist, extended only where they break.

Security-sensitive change

Allow each company to export only its own account data.
Reuses
The relevant security policy, security requirements, previous security review and approved design.
Adds or updates
The implementation and relevant tests, plus only the security requirements, approved design or important decision records that actually change. Keep verification evidence when the project’s risk or assurance needs require it.
Deliberately not added
A parallel “ADEL security document” where existing security records already hold the decisions.
Decision responsibility
Governance is responsible for lasting security principles; Product Definition is responsible for required security behavior; System Design is responsible for the technical design.
Evidence / completion
Authorization-test results, relevant security checks and review findings that provide evidence for the requirement.
Traceability
Security requirement → approved design → implementation → verification evidence.

Human and multi-agent delivery

A feature planned by one agent, implemented by another, reviewed by a person.
Reuses
Agent instructions, the relevant requirements, approved design, accepted decision records and the current work item.
Adds or updates
The information the next person or agent needs to continue without guessing decisions or repeating work. An existing issue or task may be sufficient; use a handoff only when the delivery plan must preserve sequencing, dependencies or coordination across the transfer.
Deliberately avoided
Using conversation history as the primary transfer mechanism.
Decision responsibility
Moving the work does not move its decisions. Product decisions still belong to Product Definition, design decisions to System Design and implementation choices within the work item to Execution.
Evidence / completion
Completion is assessed against the relevant requirements, acceptance criteria, required checks and evidence—not against what an earlier participant claimed in a conversation.
Traceability
Every participant leaves references in project records rather than only in a work session.
See it applied

For a complete sequence, follow one project through all ten parts of Work with ADEL. It shows each prompt and project record when it is used.

Work with ADEL — Build something from scratch→
Toolkit

Troubleshooting

When you’re hereYou have a practical question or are unsure which record, decision or action is needed next.

Common questions that arise when applying ADEL in real projects.

Project records and documentation

Our issue tracker already contains everything. Do we need a separate work-item record?

Not necessarily. If the tracker item already gives the person or agent enough information, references the relevant sources of truth and remains accessible, another record would duplicate it. Create a repository work item when the person or agent cannot reliably reach the tracker or when the approved scope, constraints and acceptance criteria need to travel with the repository.

Related: Applying ADEL to a change→
We have no governing principles written down.

Start with only the project-wide principles and constraints that actually apply. A concise record containing real governing rules is more useful than a long one filled with principles nobody applies. Do not create filler to make the record look complete; add detail only as the project’s Governance needs grow. If an existing engineering policy, project charter or constitution already holds those principles as a source of truth, do not recreate them merely to use a filename shown in an ADEL example.

Related: How much detail is enough→
Our existing documentation uses different names.

Keep the existing names when they already work. A record’s place in ADEL is determined by the kind of decision or information it holds, not by its filename. Rename or reorganize it only when doing so improves clarity, access or maintenance—not simply to match ADEL terminology.

Related: Adopting on an existing project→
The example record the Playbook references does not exist. Should we create it?

First determine whether the information already exists elsewhere. If an existing source of truth holds it, use that record. If the information is actually missing and represents an unresolved earlier decision, resolve it at the responsible layer. Create another record only when the work allows it and another person or later work will need that information. Do not create a record merely because its name appears in an ADEL example.

Related: Prompt patterns by situation→

Project knowledge and access

The coding agent cannot access our wiki.

Copy only the information needed for the work into an accessible project record and identify its source of truth. If the source may change before the work is complete or be checked later, include the source version, date or another reference. The wiki remains the source of truth; the repository record is a limited copy, not a competing source. Use the same approach when direct access is not allowed.

Related: Give each work item the project knowledge it needs→
The product requirements document (PRD) is very large.

Large is not the problem; difficult to navigate is. Organize the source of truth by section, domain, product area or another structure suited to the project. Split it only when that improves navigation or responsibility. Then reference the relevant part from the work item instead of repeating the document. Limit the work item, not the source of truth.

Related: Give each work item the project knowledge it needs→

Decisions and conflicts

The approved design and a decision record disagree.

Determine which approved decision applies to the affected work. A decision record is the source of truth for the decision it captures while it remains approved, relevant and not replaced. An older, differently scoped or proposed record does not override the current approved design. The approved design remains the source of truth for the system as a whole. Update the records until they agree again.

Related: Framework — conflict handling→
The agent discovered an architecture issue mid-implementation.

Do not resolve an important architecture issue as a local implementation choice. Raise it as a System Design decision and pause the affected work until the approver resolves it. If the work would change an architectural boundary, the agent should report the unresolved System Design question rather than invent the answer during Execution.

Related: Preparing work for a coding agent→

Verification and traceability

Tests pass, but one requirement is not demonstrated.

The affected requirement is not Verified. Record whether it is Not verified or Unable to verify, together with the available evidence and the reason. Whether the work can still close depends on the project’s rules and acceptance process. The approver must accept any permitted exception or remaining risk instead of silently treating the work as complete.

Related: Verification in practice→
Nobody maintains the central traceability table.

A stale table can be more misleading than having no table because it shows relationships that are no longer true. If direct references between the requirement, work, implementation and evidence are easy to follow, retire, archive or remove the table according to project practice. Keep a shared traceability view when people can no longer follow the direct references or when project rules require one.

Related: Traceability in practice→

Adoption

Do we need to clean up the whole project before using ADEL?

No. Identify the approved information, gaps and conflicts that matter to the work in front of you. Fix those first, then improve other records as later work uses them. Do not turn adoption into a project-wide documentation rewrite.

Related: Adopting on an existing project→
Boundaries

Know where ADEL stops

When you’re hereYou need to know what ADEL organizes and what remains the responsibility of specialist practices, project roles or other tools.

ADEL shows where project decisions, work items and evidence belong and how they connect. It does not tell security specialists how to secure a system, assign the project’s job titles or replace the tools used for specialist work.

The limits below cover specialist practices, the records those practices produce and the people responsible for the work.

Specialist practices

Security, privacy, safety, accessibility, reliability, compliance, operations and data governance each keep their own methods and controls. ADEL shows where their requirements, design decisions, work and evidence belong. It does not define how specialists perform that work. The table uses security as one example.

View security example
Mandatory security rules
Typical ADEL placement
Governance
Required security behavior and acceptance criteria
Typical ADEL placement
Product Definition
Security risks, trust boundaries and security architecture
Typical ADEL placement
System Design
Important security design decisions
Typical ADEL placement
System Design; a decision record when future work needs the reason
Security implementation work
Typical ADEL placement
Execution
Security verification and evidence
Typical ADEL placement
Assurance

Place the information according to whether it sets a rule, requirement or design, describes work, or provides evidence—not simply because it is about security.

ADEL does not define how to protect agents from malicious instructions, handle secrets, secure software dependencies or process untrusted content. Those rules come from specialist security practice. ADEL defines which decisions belong to the agent’s work and when its instructions require it to stop. Information the agent can access is not automatically an approved instruction, and agent instructions do not grant system or tool permissions.

Specialist records

A specialist record can already provide project knowledge for one or more ADEL layers. When it is the source of truth, keep it instead of creating a copy with an ADEL example filename. When a work item needs part of that information, reference the source or provide an approved copy that identifies it.

Playbook guardrail

Map a record by what it decides, describes or demonstrates—not by its filename.

Framework → §8.1 Layer, record, and location · §8.2 Judge a record by its content, not its filename
View examples
Threat model — identified threats and planned protections
ADEL responsibilities it commonly supports
System Design; the security requirements it identifies also touch Product Definition
Security policy
ADEL responsibilities it commonly supports
Governance
Accessibility requirements
ADEL responsibilities it commonly supports
Product Definition
Accessibility evaluation results
ADEL responsibilities it commonly supports
Assurance
Performance requirements
ADEL responsibilities it commonly supports
Product Definition
Performance architecture and constraints
ADEL responsibilities it commonly supports
System Design
Performance measurements
ADEL responsibilities it commonly supports
Assurance
Rollout plan
ADEL responsibilities it commonly supports
Delivery Planning
Migration plan
ADEL responsibilities it commonly supports
Delivery Planning or System Design, by content
Penetration-test report — results of an authorized security test
ADEL responsibilities it commonly supports
Assurance
Operational architecture
ADEL responsibilities it commonly supports
System Design
Compliance evidence
ADEL responsibilities it commonly supports
Assurance
Control mapping — links required controls to the work and evidence
ADEL responsibilities it commonly supports
Assurance; traceability where it connects controls to requirements, implementation and evidence

These are examples. ADEL does not require these exact placements. One specialist record may contain information used by more than one layer and does not need to be split for that reason.

Organizational responsibilities

ADEL assigns each kind of decision to a responsible layer, not a job title. Teams decide who writes, reviews, approves, implements and verifies according to their own organization and governance. The examples below show where common roles usually meet the model; ADEL does not require this division of work.

View how common roles use ADEL
Product manager / business analyst
ADEL responsibilities commonly involved
Product Definition; Assurance where acceptance criteria are assessed
Architect
ADEL responsibilities commonly involved
Governance; System DesignArchitecture decision records (ADRs) are a common decision record in System Design.
Developer
ADEL responsibilities commonly involved
System Design; Execution; Assurance; Agent execution overlay where agents are used
Quality assurance (QA) / testing
ADEL responsibilities commonly involved
Product Definition; AssuranceAcceptance criteria usually originate in Product Definition.
Security
ADEL responsibilities commonly involved
Governance; Product Definition; System Design; Assurance
Engineering lead
ADEL responsibilities commonly involved
Delivery Planning; Assurance; Governance where delivery policy applies
Site reliability engineering (SRE) / operations
ADEL responsibilities commonly involved
Product Definition for operational requirements; System Design; Delivery Planning; Assurance
Auditor / reviewer
ADEL responsibilities commonly involved
Governance; Product Definition; System Design; Assurance
Coding agent
ADEL responsibilities commonly involved
Agent execution overlay; Execution; relevant Governance, Product Definition and System Design records; required checks and evidence for AssuranceAGENTS.md is one common record used by the Agent execution overlay.
What the Playbook should do

The Playbook should make ADEL easier to apply without adding unnecessary work.

If a Playbook recommendation adds work without making decisions clearer, records easier to find, transfers safer or verification stronger, change or remove it.

Framework — defines the model and which layer is responsible for each kind of decision.

Playbook — shows how to apply the model in common situations.

Work with ADEL — shows one project applying the Playbook from start to finish.

Templates — reduce the effort of creating a project record when one is useful.

Next
The FrameworkThe complete reference→TemplatesStarter structures for project records→