Introduction

A Field Guide to Designing and Shipping AI Agent Systems

Why this book exists

Most teams adopting AI agents discover the same pattern within a quarter:

• The first demo is fast and impressive. The second pilot is slower than expected. By the third, the team is debugging output instead of shipping outcomes.
• Architectural coherence quietly degrades because no one is reviewing what the agent decided to do — only whether the test passed.
• The "AI made a mistake" incident reveals that nobody actually agreed, in writing, what the agent was authorized to do, what it must never do, or who was supposed to catch it when it drifted.
• Adding agents made the team faster on individual tasks and slower at shipping reliable systems. The bottleneck moved, but nobody renegotiated the work to match.

This is a structural problem, not a model problem. The model is doing what it was told. The trouble is that being told — what we ask of the agent, what we forbid it, how we check what it did — is the part the team did not learn how to do.

This book is the discipline that addresses that gap. It is a field guide for the people writing the spec, building the agent, and owning the on-call pager when something breaks.

What is the Architecture of Intent?

The framework's one-page definition lives in Part 0 — Foundations, What is the Architecture of Intent?: three questions every delegated system has to answer; five activities that answer them (Frame · Specify · Delegate · Validate · Evolve); three properties that make this an architecture rather than an art (intent as a designed artifact; fixes live in structure, not prompts; calibration is deliberate). Read that chapter once; come back when you get lost.

For the visual version of the same content, see The framework on one page below.

The framework on one page

The five activities and every load-bearing list in the framework — five archetypes, four calibration dimensions, twelve spec sections, eight pattern categories, four oversight models, seven failure categories, four signal metrics — fit on a single page. The canvas below is that page, with each construct in the activity row where it does work. The rest of the book elaborates this picture; when you get lost, return here.

The book is organized around the five activities, with a sustaining-operations layer that runs alongside them. Part 1 — FRAME stands up the archetypes, the four dimensions, and composition first-class. Part 2 — SPECIFY stands up the canonical spec template, the Composition Declaration and Cost Posture sub-blocks, the Intent Design Session, and the repertoires. Part 3 — DELEGATE stands up agent classes, capability and tool-manifest patterns, MCP, oversight, and the patterns that bind to what the spec implies. Part 4 — VALIDATE stands up failure diagnosis (the seven Cats), the four signal metrics, evals, red-team protocol, and the safety / observability / testing patterns that emit the validation signal. Part 5 — EVOLVE stands up the closed loop, the anti-pattern catalog, framework versioning, the Minimum Viable Architecture of Intent, and the deployment patterns (canary, rollback, spec versioning, model-upgrade validation, deprecation) — what changes about the system over time as diagnosed failures become structural amendments. Part 6 — OPERATIONS is not a sixth activity; it is the sustaining layer that runs alongside the five — governance cadence, cost and latency engineering, cacheable prompt architecture, production telemetry, the Adoption Playbook, and DevSquad mapping and co-adoption. The activity count stays five; Part 6 collects the ongoing-ops chapters that previously sat inside Part 5 and now have room to be reference-grade rather than spine narrative. Part 7 — REFERENCE is the catalog: cross-cutting coordination and state patterns, code standards, and the appendices.

Each of Parts 1–5 ends with three short in practice chapters that walk one of three running scenarios — a customer-support agent, a coding-agent pipeline, and an internal docs Q&A agent built by a DevSquad team — through that activity. You can read the book linearly by phase, or follow one scenario end-to-end across all five activities; the in practice chapters cross-link both ways.

What you will have at the end

A pilot you can defend. Concretely, the artifact each row of the canvas above should produce by the time you ship:

1. An archetype (Frame). A pre-committed answer to "what kind of system is this — Advisor, Executor, Guardian, Synthesizer, or Orchestrator?" — with the agency, autonomy, responsibility, and reversibility profile that follows from that choice.
2. A spec (Specify). A written, reviewable artifact in twelve sections that says what the agent must do, what it must never do, what success looks like, and what context it operates in. The agent executes against this. Humans review against this.
3. An agent (Delegate). A system prompt, a set of skills, a tool manifest, and a capability boundary that match the archetype, with the cross-cutting patterns (safety, observability, coordination, state) bound to what the spec implies.
4. An oversight model (Delegate). A specific answer to "who reviews what, when, and what triggers escalation?" — one of Monitoring, Periodic, Output Gate, or Pre-authorized — proportional to the blast radius of the agent's actions.
5. Metrics that mean something (Validate). Four signal metrics — spec-gap rate, first-pass validation, cost per correct outcome, and oversight load — that tell you whether the pilot is healthy without manufacturing a dashboard for its own sake.
6. A deployment plan (Validate). Canary, rollback, and spec versioning so you can ship without making the change irreversible.
7. A closed-loop discipline (Evolve). A spec evolution log, a Discipline-Health Audit cadence, and an explicit commitment that diagnosed failures produce structural amendments — not prompt patches — so the practice compounds across teams and survives turnover.

If you finish the book and don't have those seven things, the book has failed you. Tell us what was missing.

Who this is for

This book has one primary reader: the tech lead, staff engineer, or platform-team member who is on the hook for an agent system going to production. Everything in the book is aimed at making that person's next decision better.

It is also useful for:

• Architects and principal engineers responsible for the structural integrity of systems that agents now help build. Parts 1, 4, and 5 are most relevant.
• Engineering managers trying to understand what their teams are actually doing when they "use AI." The Prologue and Part 1 give you the vocabulary; Part 5 gives you what to ask for in reviews.
• Platform teams building shared agent infrastructure (MCP servers, spec templates, archetype catalogs). Parts 3, 4, and the Cross-Cutting Patterns section are the spine of your platform.

This book is not a tutorial on a specific AI tool, a survey of the model landscape, or a strategy document about whether to adopt AI. It assumes you've already decided to ship something with agents and now need to do it without regret.

How to use it

Two reading modes, both supported.

Linear. Start at the Prologue and read straight through. Each Part assumes the previous one. By the end you have the full vocabulary and the full pilot kit. Estimated time: 6–10 hours, but that's not how anyone actually reads a field guide. Read a Part, apply it, come back.

Work-shaped. Enter at the decision you're currently stuck on. The Pattern Index and the Glossary are your navigation tools. Common entry points:

What the book does not promise

It does not promise that following these patterns guarantees a successful pilot. Models change, requirements shift, and some failures are genuinely model-level and unfixable by better specs. What this book gives you is the smallest set of structures that make a pilot's failures diagnosable and correctable rather than mysterious.

It does not promise that every pattern applies to every team. Regulated industries (healthcare, finance, defense) have compliance requirements that go beyond what's covered here. Multi-organizational agent systems — where agents from different orgs interact — have governance problems this framework does not solve. Cost-benefit analysis for adopting these practices depends on factors that vary too widely to generalize.

It does not promise to settle every open question in the field. How precise is "precise enough"? What happens when model capability outpaces governance? Can intent engineering scale to truly autonomous systems? These questions are real and unresolved. This book stakes out a working position; treat it as something to test against your own context, not as final word.

Honest scope: what this book is, and what it isn't

This book's strongest contribution is a design vocabulary and a diagnostic discipline: archetypes, the four dimensions, the failure taxonomy, the spec template, the oversight models. Teams that adopt it report that their conversations about agent systems get sharper — which is exactly what you'd expect when a shared vocabulary replaces ad-hoc framing.

It is not a complete technical playbook. Specifically, the book is light on:

• Prompt caching as architecture (covered briefly in Cost and Latency Engineering; deserves more depth for any system at 100+ runs/day).
• Model-tier selection under specific budget and latency constraints — the Model-Tier Quick-Select Card gives a decision matrix; the underlying chapter goes deeper.
• Multi-tenant fleet governance at very large scale — Multi-Tenant Fleet Governance covers the first layer of fleet discipline (constraint inheritance, cross-tenant isolation, partitioned telemetry, platform-tier failure-locus). The framework's working position is that those four moves carry a fleet from one to fifty tenant teams; at hundreds or thousands of tenants, additional infrastructure-organizational machinery is needed that this book does not develop.
• CI/CD wiring details — when does the eval suite gate a merge versus alert versus observe? The disciplines are described; the specific platform integration is not.

Read the book for the vocabulary, the structural patterns, and the failure diagnosis. Bring your own platform expertise for the wiring.

A note on style

This is a working book, not a literary one. Chapters are short, the vocabulary is consistent, and the templates are meant to be copied. Where a pattern can be stated in two pages, it is. Where a pattern needs a diagram, a table, or a worked example, it gets one. There is no philosophical preamble, because the reader of this book is presumed to already be working on the problem and to need the tools, not the argument.

If you want to see the framework applied to one concrete system in one screen before going any further, read A Miniature Pilot, End-to-End next. It is the canvas walked top-to-bottom on a recognizable pilot, with one failure traced back to its fix locus.

If you want the argument for why this discipline matters — what changed structurally about software when code stopped being the bottleneck — read the Prologue instead. It's three pages.

If you'd rather just start with the first decision you have to make, go to Pick an archetype.

Continue to A Miniature Pilot, End-to-End to see the framework applied to one concrete system, or jump to the Prologue for why this work matters.

A Miniature Pilot, End-to-End

One screen. One canvas walk. One pilot.

You have read the definition and seen the canvas. This page shows what they look like in practice, applied to one concrete system, in the order the canvas presents.

The pilot: a meeting-notes synthesizer that drafts a 5-bullet, owner-attributed action-item summary after each team meeting and posts it — after human approval — to the project's Slack channel. Recognizable, bounded, has a few interesting failure modes, and is small enough to fit on one screen. Not in Part 6's worked pilots; those are richer. This one is a finger exercise.

The canvas, walked

The three questions

Frame — pick the archetype

Primary act: synthesize a transcript into a structured artifact. Synthesizer is the right shape. Risk override: a wrong attribution can damage trust. Not safety-critical; reputation-critical. Keep the archetype, tighten oversight.

Calibrate — set the four dimensions

Specify — the load-bearing clauses of the spec

Twelve sections; here are the ones that carry weight:

• §3 Scope. In scope: action items, decisions, owner attributions. Out of scope: compensation, hiring, performance discussions, off-topic chat, anything tagged private.
• §6 Invariants. Never post without human approval. Never include content tagged private. Always disambiguate names by full name when more than one participant shares a first name. Never invent action items not present in the transcript.
• §8 Authorization Boundary. Read access to transcripts. No write access to Slack until the human Approve button is pressed.
• §9 Acceptance. ≥95% of transcript-listed action items captured in the draft (recall). 100% correct attributions for named participants (precision-of-named-fields). Zero leaks of private-tagged content in 100 consecutive runs before promoting from Output Gate to Periodic.

Delegate — bind patterns to what the spec implies

Reading the spec aloud, the Bind Patterns phase of the Intent Design Session pulls the following:

Each pattern is bound to a specific clause. Patterns the spec does not justify do not enter.

Pick oversight — proportional to autonomy × reversibility

Output Gate (Model C) at launch. Re-evaluate at 30 days: if first-pass validation is ≥95% and zero private-tag leaks have surfaced, propose moving to Periodic (sample 1 in 5 drafts) and document the de-escalation in the spec evolution log.

Validate — instrument the four signal metrics

The first failure, diagnosed by fix locus

Day 14. The agent attributes an action item to Alex when there are two Alexes on the team. The team lead edits the draft, approves it, and adds a note: "please disambiguate by full name when there are duplicates."

What just happened: the diagnostic protocol names this as Cat 1 (Spec). The agent did exactly what the spec said. The spec said "attribute owners" — it did not say "disambiguate by full name when more than one participant shares a first name." The fix locus is the spec, not the prompt. The team amends §6 (Invariants) to add the disambiguation rule and bumps the spec to v1.1 in §13 (Spec Evolution Log).

Note what did not happen: the team did not patch the system prompt with "remember to disambiguate Alex from Alex." A prompt patch would not compound — it would silently accumulate as model context without ever entering the artifact that other team members read. The structural fix lives in the spec; it survives a model upgrade, a team transition, a context loss. That is the load-bearing discipline named in the Introduction: structural fixes live in spec, manifest, CI, or platform — never only in the prompt.

What this page is not

Not a complete spec. Not a worked pilot in the Part 6 sense — those are richer, with full specs, agent instructions, evals, and post-mortems. This is the canvas applied to one concrete system in one screen, so the reader can see the shape of a pass through the framework before reading the chapters that elaborate each row.

Real specs are longer. Real failures take longer to diagnose. Real teams disagree about calibration dials and resolve it during the Intent Design Session. The miniature pilot is the smallest concrete instance the canvas can carry; the rest of the book builds out from here.

Continue to How to Read This Book, or skip to the Prologue for why this discipline matters, or jump straight to Pick an archetype to begin your own pass through the framework.

How to Read This Book

This book is structured as a field guide, organized in the order in which the decisions actually have to be made.

The eight Parts

Each of Parts 1–5 ends with three in practice chapters that walk one of three running scenarios (a customer-support agent, a coding-agent pipeline, an internal docs Q&A agent built by a DevSquad team) through that activity, so you can read by Part or by scenario.

Two reading modes

Linear. Read straight through. Each part assumes the previous one. By the end you have all six things on the introduction's punch list — archetype, spec, agent, oversight, metrics, deployment plan.

Work-shaped. Enter at the decision you're currently stuck on. Use the table below, the Pattern Index, or the Glossary. Then radiate outward through the Connections section at the bottom of each chapter.

Chapter format

Each chapter is short and follows a consistent shape so you can scan it:

1. Context — Where this pattern applies and what it assumes.
2. The Problem — The specific tension this chapter resolves.
3. The Solution — The structure, with examples and tables. Where useful, a worked anti-pattern.
4. Therefore — The resolution in one bold sentence. Many readers read only this.
5. Connections — What this chapter assumes, and what it enables next.

Some chapters also include code examples, spec fragments, or named anti-patterns.

About the code

Code in this book is authoritative by intent, not by completeness. Snippets are written to the patterns described in the Cross-Cutting Patterns section and code standards, and are meant to anchor agent behavior — structures that can be extended, not copied verbatim.

Languages covered: C# / .NET, TypeScript / Node, Python, REST API design, infrastructure as code.

Every code example includes:

• A comment naming the pattern it instantiates
• The spec constraint it satisfies
• The boundary it must not cross

About the archetypes

The five archetypes — Advisor, Executor, Guardian, Synthesizer, Orchestrator — are the core vocabulary of this book. They appear in specs, in agent instructions, in design reviews, and in governance conversations.

If you encounter a reference to "the Executor archetype" or "the Guardian pattern" and don't recognize it, the Archetype Quick-Select Card gives you a one-page summary. The full deep-dives live in frame/archetypes/.

You're ready. Begin with the Prologue, or jump to Pick an archetype.

Prologue

What changed, and what's at stake

This is the short version of why this book exists. If you want the long version, read someone else's book — there are several good ones. This one is for people who already know they need to ship an agent system and now need to do it without regret.

What changed

For most of computing history, the rate-limiting step in software was translation: business intent was ambiguous, machines were literal, and the developer was the bridge. The whole edifice of software engineering — requirements documents, design patterns, code reviews, hiring pipelines, career ladders — was built around the scarcity of people who could reliably do that translation.

Code generation is no longer scarce. Models can produce syntactically correct, structurally sound code at machine speed. The bottleneck moved.

It moved upstream, to the things teams used to do imperfectly because code was the expensive part:

• Framing — what problem are we actually solving?
• Constraints — what must never happen?
• Scope — what is genuinely out of scope?
• Success — what does done mean, measurably?
• Accountability — who is responsible for what outcome?

These questions existed before agents. They were addressed loosely. A skilled developer compensated for a vague requirement by exercising judgment late in the process. The compensation was invisible — nobody measured it — but it was the real reason senior engineers were valuable.

That compensation mechanism does not exist when an agent is doing the implementation. The agent executes the spec with high fidelity and without the compensatory judgment. Every gap in the spec gets filled with probability, at scale, across systems that interact in ways no single conversation can anticipate.

What's at stake

Three structural risks emerge when teams add agents without changing how they work:

1. Capability scales faster than judgment. Agent capability grows by model release. Human judgment about when and how to use that capability grows by experience and reflection — much more slowly. Any domain where power scales faster than judgment produces predictable disasters. Output increases, quality becomes inconsistent in ways that are hard to diagnose, architectural coherence erodes, and technical debt accumulates exactly where no human exercised judgment.

2. Authorship gets murky. When a human wrote the code, the decision trail was legible. When an agent writes code from a spec written by one person, configured by a platform team, running on a model trained on billions of documents, and validated by tests written by another agent — who authored the harm when something goes wrong? The answer is not "the AI." The answer is the chain of human decisions that allocated agency to the agent. The question is whether that chain is legible, or whether it dissolves into "the AI did it."

3. Architecture stops being enforceable through culture. In slow systems, architectural coherence is preserved through code review and shared understanding. In fast systems, agents make thousands of small architectural choices a day, and informal convention cannot keep up. Architecture has to become encoded — in archetypes, in specs, in constraints that apply whether or not anyone remembers to apply them. The alternative is invisible drift until the cost of correction is enormous.

What this book gives you

A discipline for the specific problem the existing frameworks weren't designed for: how to specify, govern, and oversee the delegation of work to AI agents at scale.

It is not a replacement for Agile, DevOps, or systems thinking. It runs inside those practices. Sprints still happen. CI/CD still ships. The difference is that the spec — not the conversation, not the ticket, not the pull request — becomes the primary artifact of engineering judgment.

Specifically, the book gives you:

• A vocabulary that lets a team distinguish between intent and implementation, agency and autonomy, reversibility and risk, and reason precisely about each.
• Five archetypes — Advisor, Executor, Guardian, Synthesizer, Orchestrator — that pre-commit a system to a category before any specific behavior is designed.
• A canonical spec template that the agent executes against and humans review against.
• Four oversight models matched to agency level and reversibility.
• A failure taxonomy with seven categories — six common to text-based agents plus a seventh for perceiving-then-acting systems — and a diagnostic protocol that lets you fix what actually broke instead of patching the output.
• Four signal metrics to tell you whether your pilot is healthy.
• Two worked end-to-end pilots to calibrate against.

A short note on responsibility

A specification is not a neutral technical document. Every constraint in it is a commitment about how the people affected by the system will be treated. Every gap in it is a decision delegated to probability. When the agent acts, the author of the spec authored the action.

You don't have to take this as philosophy. Take it as engineering: the more powerful the system, the more load-bearing the specification, and the more seriously the spec author has to treat what's written and what's missing. Everything else in this book follows from that.

Continue to Part 1: Decisions — pick an archetype.

What is the Architecture of Intent?

Part 0 — Foundations

"Three questions, five activities, one canvas. Read this once; come back when you get lost."

Context

This is the one-page definition of the framework. It opens Part 0 — Foundations because every other chapter in the book references the vocabulary it establishes — the three questions, the five activities, the three properties that make the discipline an architecture rather than an art. A reader can decline to read the rest of the book; this chapter is the minimum the framework asks you to keep.

If you're skimming, the canvas figure in the Introduction's framework on one page section is the ~15-second version. If you want the canonical statement, read on.

The framework, in one paragraph

The Architecture of Intent is the discipline of designing intent — what a delegated system is supposed to do, what it must never do, and how we will know it is working — so that a non-human executor can act on it reliably and a human can validate the action accurately.

Three questions every delegated system has to answer

1. What is this system trying to achieve?
2. Within what constraints?
3. How will we know it is working?

These three questions are the conceptual minimum. A team that cannot answer them does not yet have an Architecture of Intent for the system they are about to build, regardless of whether they have a spec, a model, a deployment plan, or a Slack channel named after the project. The discipline begins by answering them.

Five activities that answer them

• Frame. Commit to an archetype (Advisor, Executor, Guardian, Synthesizer, or Orchestrator) and to a calibration of the four dimensions — agency, autonomy, responsibility, reversibility — before any spec is written. The category is the strongest single predictor of how the system will behave under stress; choosing it deliberately costs an hour and saves a quarter.
• Specify. Write the artifact the agent executes against and humans review against. Twelve canonical sections; each section operationalizes one of the four dimensions. The spec is not a requirements document for humans, not a design document for developers — it is an operating instruction for machines that humans can audit.
• Delegate. Bind cross-cutting patterns (capability, integration, coordination, safety, observability, testing, state, deployment) by what the spec implies, not by what the team likes building. Pick one of four oversight models — Monitoring, Periodic, Output Gate, or Pre-authorized — proportional to autonomy and reversibility.
• Validate. Track four signal metrics. When something fails, diagnose by fix locus — which artifact upstream needs to change — across seven failure categories. The diagnosis closes the loop back to the next intent.
• Evolve. Turn each diagnosed failure into a structural change — a spec amendment, a manifest tightening, a CI guard, or a framework version bump — never only a prompt patch. The closed-loop discipline is what makes the practice survive the team that built it; it is also where the framework itself versions and where adoption either compounds or quietly degrades.

The activities map 1:1 to the book's five Parts (Part 1 — FRAME through Part 5 — EVOLVE). Each Part ends with three in practice chapters — one per running scenario — that walk a real team through the activity for one specific system.

Three properties that make this an architecture, not an art

• Intent is a designed artifact. Distinct from implementation (what the executor produces), distinct from requirements (what stakeholders ask for), distinct from policy (what the organization or law requires across all systems). The author of the spec is the author of the system that executes it.
• Fixes live in structure, not in prompts. When a spec gap surfaces as a wrong agent action, the durable response amends the spec, the manifest, the oversight model, or the CI guard. A patch in the prompt layer does not compound across teams or runs; a change in the structural layer does. This is the load-bearing discipline of the framework: structural fixes live in spec, manifest, CI, or platform — never only in the prompt.
• Calibration is deliberate. Each system commits to specific levels of agency and autonomy within its archetype's envelope, rather than getting as much of either as the model technically allows. The framework's worked claim is that the four calibration dimensions are orthogonal — independently controllable — and that collapsing them into a single "automation level" loses design space practitioners need.

Where the framework applies

The framework's primary worked instance is AI agent systems, which are the most-acute current case of delegation. The book defaults to that frame. The same vocabulary — archetypes, dimensions, fix-locus failure categories, signal metrics — applies to other delegated systems too: automated pipelines, organizational delegation, regulated workflows. The book notes generalizations where they hold and stops short of claiming them where they don't.

Where to go next

• For the visual summary, see the framework on one page in the Introduction.
• For the foundations the rest of the book stands on, continue reading Part 0 in order: Intent vs. Implementation → Calibration → Failure as a Design Signal → What Changes for the Senior Engineer → The Intent Design Session.
• For the working ritual that turns the vocabulary into practice for one specific system, jump ahead to The Intent Design Session.
• For a worked pilot in one screen, see A Miniature Pilot, End-to-End.
• To read along a single scenario rather than linearly, see the Reading Paths appendix.

The Intent–Implementation Boundary

Part 0 — Foundations

"If you fix the code when something goes wrong, you are an implementer. If you fix the spec, you are an intent engineer."

Context

Tuesday morning, sprint review. The engineering manager points at the dashboard: "the agent's PR-merge-without-amendment rate dropped from 84% to 71% over the last week." The team's first instinct is to look at the agent's recent commits — what code did it write that's not landing? Two engineers open the agent's last 30 PRs side-by-side. After 20 minutes, one of them looks up: "the code is fine. The agent is doing exactly what the spec says. The spec is wrong about how cross-service refactors should be planned."

That moment — recognizing that the wrong-output is in the spec, not the code — is what this chapter is about. It is the most fundamental distinction in intent engineering, and the moment of recognition is harder to reach than it sounds because in traditional software development, the developer's own judgment was the bridge between the spec and the code, and that bridge made the distinction invisible.

You are working in a spec-driven system and something has gone wrong. An agent produced incorrect behavior. A system does not satisfy its users. A test passes but the outcome is wrong. Before you can fix it, you need to diagnose it — and the most important diagnostic question is: was the problem in the intent or in the implementation?

This pattern introduces the most fundamental distinction in intent engineering: the difference between what a system is trying to do and how it does it. This distinction sounds obvious. It is not. Teams collapse it constantly — and the collapse is the source of most of the chronic dysfunction that SDD is designed to cure.

This pattern assumes the framing established in the Prologue.

The Problem

In traditional software development, intent and implementation were tightly coupled. The specification was informal, the code was the real artifact, and the developer's judgment was the bridge between them. When something went wrong, the developer held both sides of the problem simultaneously. They could tell, through experience and institutional knowledge, whether the problem was a mistake in the code or a mistake in the understanding of what the code should do.

In agent-mediated development, this coupling breaks. The agent holds the implementation. The human holds the intent. When the output is wrong, the question of which side is broken is now an explicit decision that must be made deliberately.

If you cannot tell the difference between an intent failure and an implementation failure, you will fix the wrong thing almost every time:

• Fixing the code when the spec is wrong produces correct implementation of wrong intent, which will fail again in a different way
• Fixing the spec when the code is wrong produces a more elaborate description of the same failure, which the agent will faithfully implement
• Both together, without distinguishing them, produces confusion that compounds across iterations

The inability to systematically distinguish intent from implementation is the hidden cause of most "the agent keeps getting it wrong" complaints.

Forces

• Coupled history vs. decoupled reality. Traditional development integrated intent and implementation in one person's judgment; agent systems split these across humans and machines, demanding the ability to diagnose failure origins.
• Transient code vs. persistent spec. Code execution is temporary and repeatable; specs are the persistent artifacts governing repeated executions, yet traditional debugging focuses on implementation rather than specification.
• Speed of fixing code vs. difficulty of fixing intent. It is faster and more satisfying to patch implementation; acknowledging and fixing spec gaps requires confronting incomplete thinking.

The Solution

The Definition

Intent is what a system is meant to achieve — the purpose it serves, the outcomes it must produce, the constraints it must respect, and the criteria by which its behavior will be judged correct or incorrect.

Intent lives in the specification. It is owned by humans. It changes when the understanding of the problem changes, when business requirements evolve, or when validation reveals that what was specified does not match what was actually needed.

Implementation is how a system achieves its intent — the code, configuration, infrastructure, agent instructions, tool calls, and runtime decisions that produce concrete outputs.

Implementation lives in the code and agent outputs. It is produced (increasingly) by machines. It changes when better techniques are discovered, when performance requirements shift, or when the implementation was simply wrong.

The Diagnostic Test

When something goes wrong in a system involving agents, apply this test before acting:

If a perfectly competent agent had executed this spec exactly as written, would the outcome have been correct?

• If yes: the problem is in the implementation. The agent failed to execute the spec correctly. Diagnose and fix the execution, not the spec.
• If no: the problem is in the intent. The spec was incomplete, ambiguous, or wrong. Fix the spec first. Then let the agent re-execute.
• If you can't answer this question: the spec is too ambiguous to reason about. That is itself an intent failure — a spec that cannot be evaluated against an outcome has not specified anything.

This test is simple. Applying it rigorously is not. It requires being willing to locate the problem in your own specification — in the thing you wrote — rather than in the tool that executed it.

Three Failure Modes That Blur This Distinction

Over-specified intent

A spec that describes how to implement something has collapsed intent into implementation. It is no longer specifying what to achieve — it is specifying how to achieve it. This is dangerous because it prevents agents from applying better approaches, locks in decisions at the wrong level, and makes the spec brittle: any change in implementation requires rework of the spec.

Signs of over-specification: the spec contains specific library names, class structures, algorithm choices, or file organization. The spec uses the word "use" when it should use the word "ensure."

Anti-pattern: "Use a Redis cache with a 5-minute TTL."
Correct form: "Response time for authenticated requests must be under 200ms at p99. Implement caching as appropriate."

Under-specified intent

A spec that does not constrain behavior enough to distinguish correct from incorrect implementations. The agent fills the gaps with probability — often producing something that looks plausible and is wrong in subtle ways.

Signs of under-specification: the spec contains words like "appropriate," "as needed," "handle edge cases," or "follow best practices" without defining what those mean in this context. The spec has no success criteria. The scope section is empty.

Anti-pattern: "Build a user authentication system following security best practices."
Correct form: "Users must authenticate via OAuth 2.0. Sessions must expire after 30 minutes of inactivity. Failed login attempts must be rate-limited to 5 per minute per IP. Do not implement username/password authentication."

Intent drift

A spec that was correct at time of writing but has not been updated when the problem changed. The implementation may be a faithful execution of the original intent — but the original intent is no longer what is wanted.

Intent drift is the most insidious failure mode because the system is behaving as specified, which makes it hard to identify as a spec problem. The diagnostic: if the system does exactly what it was told to do, and that is still wrong, the spec needs to change.

The Hierarchy of Fixes

This distinction establishes a strict hierarchy for how to respond to failures:

Something is wrong
│
├─ Is the spec ambiguous or incorrect?
│   └─ YES → Fix the spec first. Always. Then re-delegate.
│
└─ Is the spec correct but the agent failed to execute it?
    └─ YES → Debug the execution.
              Is this a systematic agent failure?
              ├─ YES → Improve context, constraints, or archetype selection
              └─ NO  → Isolated failure; correct the output, document the case

The rule at the top of this hierarchy is sometimes called the spec-first discipline: when something is wrong, the spec is the first thing you look at — not the code. This rule feels counterintuitive to engineers trained in implementation-first thinking. It requires rewiring.

Why This Matters for Agent Systems Specifically

In human development teams, collapsing intent and implementation had a natural corrective mechanism: the developer who understood both could bridge the gap. The "implementation" always contained implicit intent — the developer's tacit judgment about what was really needed.

Agents do not carry tacit judgment. They execute the spec with high fidelity and without the compensatory reasoning that human developers applied. This means that the quality of the intent is now directly proportional to the quality of the implementation — far more directly than it ever was with human developers.

This is the reason for the rule "fix the spec, not the code." Fixing the code without fixing the spec means the next execution will repeat the mistake. The spec is the persistent artifact. The implementation is transient.

A Note on Shared Understanding

One underappreciated dimension of this distinction is its role in team communication.

When an implementation team and a product team disagree about whether a system is working correctly, they are almost always in an implicit argument about intent vs. implementation — they just do not have the vocabulary to name it.

"The agent is doing it wrong" (implementation claim) and "no it isn't, that's not what we asked for" (intent claim) are not the same disagreement. Confusing them produces conversations where everyone is right from their own frame and nothing gets resolved.

Having explicit vocabulary for this distinction — and a shared diagnostic process — turns ambiguous conflict into solvable problems.

Resulting Context

After applying this pattern:

• Intent failures become explicitly recognizable. A diagnostic test reveals whether a failure originated in the specification or execution, enabling targeted fixes that address root cause rather than symptoms.
• Specs stabilize while implementations iterate. The spec becomes the control artifact governing multiple implementation attempts; implementing agents can be corrected, replaced, or improved without touching the persistent intent layer.
• Teams gain shared diagnostic language. Disputes about system correctness shift from blame attribution ("the agent is wrong") to shared problem-solving ("the spec needs to be clarified").

Therefore

Intent and implementation are distinct artifacts with distinct owners, distinct failure modes, and distinct fixes. When something goes wrong, the first diagnostic question is always: was the spec correct? If yes, fix the execution. If no — or if you cannot answer the question — fix the spec first. The spec is the persistent artifact. The implementation is its shadow.

Connections

This pattern assumes:

• Prologue: What Changed and What's at Stake

This pattern enables:

• Three Dimensions of Delegation — who decides what in each layer
• The Spec as Control Surface — the mechanism by which intent controls implementation
• The Spec Lifecycle — how intent and implementation evolve together
• The Living Spec — the fix-the-spec discipline in practice
• Intent Review Before Output Review — applying this distinction in review processes

Calibrate Agency, Autonomy, Responsibility, Reversibility

Part 0 — Foundations

"Autonomy without authority is a faster way of doing what you were told. Agency without accountability is a faster way of causing harm. Reversibility is what determines whether either of those matters."

Context

A team is mid-Frame, debating whether their data-export agent should be "high autonomy" or "medium autonomy." The conversation goes in circles for fifteen minutes — every argument for high autonomy turns up a counter-example where high autonomy would be reckless, and every argument for medium turns up a case where medium would be paralyzing. The tech lead stops them: "We're conflating four things into one word. The agent's autonomy from us during a single export is one decision. Its agency to choose what to export when our instructions don't cover the case is a different decision. Who's accountable when an export goes wrong is a third. And how easily we can undo an export is a fourth. Let's split them out." Forty minutes later, the team has four committed dial positions instead of one unresolved argument.

You have selected an archetype. Now you have to decide, for the system you are about to specify, how much of each of four things it gets:

• Autonomy — how much of its work runs without human intervention at each step.
• Agency — how much discretion it exercises when its instructions don't fully cover the situation.
• Responsibility — how accountability for what it does is distributed across the people around it.
• Reversibility — how easy or hard it is to undo what it does.

These four are the dials. Every archetype comes with default settings, but the specifics of your system live in how you tune them. Tune them deliberately, in the spec, before the agent runs — or they will be tuned for you by accident.

The Problem

Most teams collapse these four into a single intuition: "how autonomous is the agent?" That intuition hides the calibration work that actually matters.

A deployment pipeline that runs on commit is "autonomous." So is an agent that decides to delete files it considers redundant. Treating these with the same design pattern is a category error: the first has high autonomy and almost no agency; the second has high autonomy and high agency and potentially low reversibility, and it should not be deployed without explicit oversight design.

Similarly, "responsibility" gets used to mean legal liability, ethical answerability, operational accountability, and technical error-catching — all in the same conversation. Without distinguishing them, accountability discussions produce more confusion than clarity.

If you cannot describe an agent's profile across all four dimensions, you cannot decide whether your oversight is proportional, whether your spec is precise enough, or whether deployment is safe.

What is novel here, and what is borrowed

Reversibility as a governance dial, the autonomy spectrum, and distributed responsibility are all well-established in adjacent literatures. SAE J3016 (the canonical "levels of driving automation" reference) gives a six-level autonomy taxonomy. The HITL / HOTL / HOOTL (Human-In/On/Out-Of-The-Loop) typology has organized human-oversight design in defense and safety-critical systems for over a decade. Shavit, Agarwal et al. (OpenAI, 2023, Practices for Governing Agentic AI Systems) explicitly cover action-space, default behaviors, reversibility, attributability, and interruptibility as governance dimensions. NIST AI RMF and ISO 42001 cover responsibility distribution. None of those are being claimed here as new.

What this chapter contributes — and what the rest of the book is built on — is the insistence that autonomy and agency are different dials, calibrated separately, with different oversight implications. Most practitioner sources blur the two; this conflation is the single most common source of mis-calibrated agent oversight.

A nightly git push script is highly autonomous and exercises essentially no agency: it follows a predetermined sequence with no discretion. A research agent that runs once a week but plans its own multi-step investigation is much less autonomous (one invocation per week, often with checkpoints) but exercises much more agency (it interprets goals and fills gaps in instructions). These two systems require qualitatively different oversight even though "how often does a human have to click?" suggests the opposite.

Hold those two dials separately. The rest of the framework — archetype dimensions, oversight models, the spec template — depends on it.

Forces

• Automation desire vs. control necessity. Teams want high autonomy to reduce labor; high autonomy paired with high agency over irreversible actions is ungovernable without explicit accountability structure.
• System capability vs. human understanding. Agents can act in domains the original authors didn't fully anticipate; responsibility cannot be left vague — failures with no diagnosis path become unfixable.
• Probability focus vs. consequence reality. Engineering risk management traditionally emphasizes reducing probability of failure; agent systems must also govern the consequence when failures occur. Reversibility is the dimension that shapes consequence.
• Operational efficiency vs. oversight overhead. Testing and review add latency; for irreversible operations, the cost of an undetected failure is so high that adequate oversight is non-negotiable.

The Solution

Dimension 1 — Autonomy: the operational dimension

Autonomy is the degree to which a system executes a process without requiring human intervention at each step.

It's a spectrum, not a binary. Fully manual sits at one end (a human decides and acts every step). Fully automated sits at the other (the system runs a predetermined sequence with no human involvement). Most real systems sit in between.

Autonomy is primarily an operational concept. It says: how much human labor is required to run this system?

Autonomy alone doesn't tell you how much discretion the system exercises. A nightly git push script is fully autonomous and exercises essentially no discretion. A human who makes one daily deploy decision exercises more discretion than the script despite being "less autonomous."

Key insight: raising autonomy reduces human labor. It doesn't by itself raise risk — unless it raises agency or interacts with low reversibility.

Dimension 2 — Agency: the discretion dimension

Agency is the capacity to make decisions that were not explicitly pre-specified — interpreting goals, weighing options, resolving ambiguity, or acting in situations the original instructors didn't fully anticipate.

Agency is about discretion. An agent exercising genuine agency is doing something qualitatively different from a deterministic script: it's filling gaps in its instructions with its own judgment (probabilistic reasoning, in the case of language models).

Agency has direction — it operates in service of a goal. The system's outputs reflect probabilistic selections among action sequences that, conditioned on the spec and context, the model has been trained to associate with goal advancement. Calling this "the agent's belief" is convenient shorthand; what is actually happening is a constrained search through token sequences that satisfy the prompt.

• Broad agency — wide latitude to decide how to pursue the goal.
• Narrow agency — a tightly defined solution space; the agent can act without human intervention but its options are bounded.

Key insight: agency determines exposure. The more latitude the system has, the more critical it is that the goals, constraints, and escalation paths were specified correctly. Every gap in the spec becomes an output the model will produce probabilistically — not a "decision" in the human sense, but a token sequence selected from the constrained space the spec defines. When the spec is loose, that space is wide and unpredictable; when the spec is tight, the space is narrow and the model's probabilistic behavior is bounded into something a human can review.

Dimension 3 — Responsibility: the accountability dimension

Responsibility in agent systems is distributed across multiple parties, each carrying a distinct kind of accountability:

These responsibilities are concurrent and non-exclusive. A failed outcome usually involves accountability at multiple layers — a spec that under-constrained, an operator who didn't monitor, a reviewer who didn't catch the failure, a platform that behaved unexpectedly. Identifying which responsibility layer failed is prerequisite to preventing recurrence.

The danger zone: high agency + low responsibility clarity. Three common patterns expose this:

• The "AI decided" deflection. When something goes wrong, the response is "the AI did it." This is never a meaningful answer. An AI system acts within a spec, authorized by humans, deployed by humans, running on infrastructure operated by humans. "The AI decided" is shorthand for a chain of human decisions that allocated agency.
• The empty oversight seat. A system with significant agency but no designated human reviewer. The system acts; nobody checks. When the system's outputs go wrong in the discretionary regions the spec didn't constrain, nobody catches it until consequences have compounded.
• The responsibility gap. Authorial, operational, and validation responsibilities belong to different teams who never coordinated on what "accountable" means in practice.

Dimension 4 — Reversibility: the consequence dimension

Reversibility is the degree to which an action can be undone, corrected, or rolled back after it has been taken.

It's a spectrum with four practical zones:

Reversibility is contextual, not intrinsic. The same action type sits at different points on the spectrum depending on infrastructure and operational context. A database write is largely reversible if you have point-in-time backups and a tested rollback procedure; it's effectively irreversible if you don't. A message in an internal Slack channel is partially reversible; the same message sent to an external customer mailing list is irreversible. When assessing reversibility for a spec, evaluate the action as deployed in your specific environment, not the action type in the abstract.

The risk matrix

The practical design tool is the intersection of agency and reversibility:

              LOW AGENCY        HIGH AGENCY

REVERSIBLE    ┌─────────────┬─────────────┐
              │  LOW RISK   │  MEDIUM RISK│
              │  Automate   │  Constrain  │
              │  freely     │  well; light│
              │             │  oversight  │
IRREVERSIBLE  ├─────────────┼─────────────┤
              │  MEDIUM RISK│  HIGH RISK  │
              │  Gate on    │  Maximum    │
              │  human      │  oversight; │
              │  approval   │  mandatory  │
              │             │  human gate │
              └─────────────┴─────────────┘

• Low agency + reversible — default safe zone. Automate freely. Monitoring is sufficient.
• High agency + reversible — productive zone. Grant the agent latitude. Review outputs; don't gate each step. Correct errors cheaply.
• Low agency + irreversible — approval zone. The action itself carries consequence. Require a human gate, not because the agent's discretion is high, but because the cost of any error is non-trivial.
• High agency + irreversible — maximum oversight zone. Both the range of decisions and the consequences are high. Requires explicit constraints in the spec, mandatory human review before any irreversible action, audit logging, clearly assigned responsibility. Never deploy with informal oversight.

Reversibility is a design choice

Reversibility isn't a fixed property of the problem domain. It's often a design choice. Patterns that expand reversibility:

• Soft deletes instead of hard deletes. Data marked deleted is reversible; data purged is not.
• Draft queues before delivery. An email queued for review is reversible; an email sent is not.
• Dry-run modes. An agent that simulates its actions before executing converts irreversible operations into reviewable ones.
• Approval gates. A system that batches decisions for human review before executing any of them is more reversible than one that executes each decision immediately.

These patterns don't eliminate the need for good intent specification — they buy time for the oversight loop to catch mistakes. They are the engineering equivalent of a circuit breaker.

The calibration framework

Given the four dimensions, the primary design question for any agent delegation is:

For this system, at what level of discretion (agency), at what execution speed (autonomy), with what distribution of accountability (responsibility), and over what reversibility profile, are we operating?

Cost is not a fifth dimension

Practitioners often ask: if cost is independently calibratable and shapes every spec choice, why isn't it a fifth dimension alongside agency, autonomy, responsibility, and reversibility?

The framework's working position is that cost is not a fifth calibration dimension. It is a structurally distinct kind of commitment that lives in its own §4 sub-block in the canonical spec template, alongside (and parallel to) the Composition Declaration. Three reasons.

Cost is partially derived, not fully independent. A system's cost is partly a consequence of the four dimensions: high agency, wide autonomy, and engineered reversibility together push cost up. The four behavioral dimensions are causes; cost is partly an effect of how they're set. Promoting cost to a dimension would conflate dial with derived quantity, which is exactly the conflation the orthogonality argument above tries to avoid for agency and autonomy.

Cost is a different category of commitment. The four dimensions are behavioral commitments about what the system does — what decisions it makes, what gates apply, who is accountable, what state it can recover. Cost is a resource commitment about what the system consumes — model tier, latency budget, cache strategy, per-call ceiling. Behavioral and resource commitments compose, but the framework's argument that the four behavioral dimensions are orthogonal does not extend cleanly to a behavioral-plus-resource fifth.

The lineage is thin. The framework's honest accounting (paper §1.3) cites SAE J3016 [@saeJ30162021] and Shavit & Agarwal [@shavitAgarwal2023] as the sources for the four dimensions individually. Neither has cost-as-a-dimension; SAE J3016 treats cost as derived from the automation level, and Shavit & Agarwal's seven operational variables (ability, agency, agency type, autonomy, alignment, accountability, authority) do not include cost. Adding a fifth dimension here would either require a novelty claim (weak — practitioners have been calibrating cost as a resource concern for decades) or a manufactured lineage citation. The framework declines both.

What we do instead. Cost gets a structural seat in the spec, but as a §4 sub-block rather than a calibration dimension. The Cost Posture sub-block declares: model-tier commitment per step; latency budget; prompt-stability invariant; per-call cost ceiling; cost-incident escalation. The Composition Declaration was the precedent — §4 can absorb structural commitments that aren't dimensions. Cost Posture follows the same shape.

What the four dimensions still do. The four-dimension calibration determines the envelope within which cost is calibrated. A Reasoning-tier model on every step is cheap if Agency is narrow and Autonomy is bounded (few calls, simple prompts); the same Reasoning-tier commitment is ruinous if Agency is wide and Autonomy is high (many calls, expanding context). The Cost Posture sub-block makes the cost commitment visible upstream, where the four-dimension calibration has already constrained what is possible. Operators reading the spec can then see how the behavioral and resource commitments interact, instead of discovering the interaction in the production cost graph.

If a future class of system makes cost behave like a dimension — independently calibratable, orthogonal to A/A/R/R, with a clear governance profile no §4 sub-block provides — the framework can revisit. As of v1.x, no such class has surfaced. The §4 sub-block does the work cleanly, and the orthogonality argument the four behavioral dimensions rest on stays uncluttered.

Resulting Context

After applying this pattern:

• Four distinct dials, set deliberately. Autonomy, agency, responsibility, and reversibility become design parameters tuned upfront in the spec rather than emergent properties discovered after deployment.
• Three accountability layers, distributed explicitly. Authorial, operational, and validation responsibilities are assigned to specific teams or individuals before deployment.
• Risk matrix becomes actionable. Different combinations of agency and reversibility receive different oversight structures. Low-risk combinations are streamlined; high-risk combinations get mandatory controls.
• Reversibility becomes a designable property. Soft deletes, draft queues, and approval gates expand the scope of what can be safely automated.

Therefore

Every delegation has four dials: autonomy (how independently it runs), agency (how much discretion it exercises), responsibility (who is accountable for outcomes), and reversibility (how easily an action can be undone). Calibrate them deliberately in the spec. Match oversight to the combination of agency and reversibility, not to the probability of error. Resolve responsibility distribution before deployment.

References

• SAE International. (2021). J3016 — Taxonomy and Definitions for Terms Related to Driving Automation Systems for On-Road Motor Vehicles. — The canonical six-level autonomy taxonomy this chapter draws from for the autonomy dimension.
• Shavit, Y., Agarwal, S., et al. (Anthropic, OpenAI). (2023). Practices for Governing Agentic AI Systems. OpenAI. — Formalizes action-space, default behaviors, reversibility, attributability, interruptibility as governance dimensions; the closest prior art to this chapter's four dimensions.
• NIST. (2023). AI Risk Management Framework (AI RMF 1.0). — Responsibility distribution across "govern, map, measure, manage" functions.
• ISO/IEC 42001:2023. Information technology — Artificial intelligence — Management system. — Organizational accountability framework for AI systems.
• Human-in-the-loop / Human-on-the-loop / Human-out-of-the-loop. — Standard typology for oversight cadence in safety-critical systems; predates AI agent literature.

Connections

This pattern assumes:

• Pick an Archetype

This pattern enables:

• Four Dimensions of Governance — formal encoding of these dials in archetypes
• The Archetype Selection Tree — choosing an archetype that matches your calibration
• Proportional Oversight — designing oversight to match the agency × reversibility profile
• The Canonical Spec Template — where these dials are written down

Failure Modes and How to Diagnose Them

Part 0 — Foundations

"Failure in a well-designed system is rarely noise. It is a signal, sharp and specific, pointing at the assumption that was wrong."

Context

Wednesday morning, post-incident review. The agent issued a refund without checking the cap. The room's first reaction is uniform: "the model hallucinated." The on-call engineer pulls up the trace and stops the conversation: "the model didn't hallucinate. The trace shows the model emitted the right tool call. The Guardian wrap wasn't bound on this code path." The failure was in the manifest, not the model; in the architecture, not the agent.

That moment — re-attribution from "the AI is broken" to "our architecture is broken" — is what this chapter exists to teach. The instinct to attribute failure to the model is strong, comfortable, and almost always wrong in the way that matters; correctly diagnosing the failure determines whether the fix is wait for the next model (stuck) or amend the spec / tighten the manifest / add a CI guard (actionable now).

Your system has produced a wrong outcome. An agent did something incorrect, harmful, or off-target. The instinct is to fix the immediate symptom and move on.

Don't. Every failure in an agent-mediated system carries diagnostic information that, read correctly, prevents a class of future failures. The discipline is: categorize first, fix at the right level, and capture the lesson in a versioned artifact.

This chapter sits in Part 0 — Foundations because the seven-category fix-locus taxonomy is referenced from every Part — scenarios in Frame, Specify, Delegate, and Validate all categorize failures by Cat 1–7, and the closed-loop discipline in Part 5 ships its amendments to the artifact each Cat names. You read it before your pilot runs, not after — knowing the failure taxonomy in advance is how you anticipate where to put oversight, what constraints to add to the spec, and what to log. You return to it during Validate (and during every other phase), when actual failures need categorizing.

The Problem

When an agent produces a wrong output, the instinctive response is attribution: "the AI hallucinated," "the agent misunderstood," "the model got confused." This attribution is often wrong in the way that matters. It locates the failure in the agent, and it is not actionable.

If the failure is the agent's, the only fix is a better agent — wait for the next model. The team is stuck.

If the failure is in the architecture around the agent, the fix is available now. The spec was incomplete. The skill was stale. The oversight model didn't catch the error in time. The tool description was ambiguous. These are fixable without waiting for anyone.

This is not a claim that model-level failures never occur — they do, and the sixth category below names them. (A seventh category, Perceptual Failure, addresses a class of failure specific to perceiving-then-acting systems such as computer-use and browser-use agents.) But teams that systematically categorize their agent failures find that the majority of consequential ones trace back to architectural gaps rather than model limitations. The discipline of failure analysis prioritizes the fixable categories first, because they are the most actionable.

Forces

• Attribution instinct vs. architectural diagnosis. When agents fail, the instinct is to blame the model. Architectural failures (spec gaps, tool gaps, oversight gaps) are more common and more fixable.
• Quick correction vs. root-cause analysis. Patching the output is faster than diagnosing the failure category. But patching without diagnosis means the same failure recurs.
• Model limitations vs. specification gaps. Some failures are genuinely model-level. Others look model-level but are actually spec gaps. Differentiating requires systematic diagnosis.
• Individual failure vs. compounding failure. A single agent failure may be trivial. Failures that compound across steps or agents produce dramatically wrong outcomes.

The Solution

The diagnostic test

Before reaching for the taxonomy, apply this test to every failure:

If a perfectly competent agent had executed this spec exactly as written, would the outcome have been correct?

• If yes — the problem is in execution, not intent. Diagnose and fix the execution layer.
• If no — the problem is in the spec. The spec was incomplete, ambiguous, or wrong. Fix the spec first; then re-execute.
• If you can't answer — the spec is too ambiguous to reason about. That's itself an intent failure: a spec that cannot be evaluated against an outcome has not specified anything.

This test is simple. Applying it rigorously is not. It requires being willing to locate the problem in your own specification — in the thing you wrote — rather than in the tool that executed it.

How this taxonomy relates to the empirical literature

Two academic taxonomies are worth knowing before you adopt this one:

MAST (Multi-Agent System Failure Taxonomy) — Cemri et al., 2025, Why Do Multi-Agent LLM Systems Fail? — empirically analyzes 200+ failure traces across multi-agent systems and partitions failures into three top-level categories (specification issues, inter-agent misalignment, task verification failures) and 14 fine-grained sub-categories. MAST is the most rigorous practitioner-facing failure partition currently published. If you are running a multi-agent system, read it.

The agent-hallucination taxonomies — Zhang et al. (arXiv:2509.18970) and the broader 2024–2025 literature on tool-call hallucination, planning hallucination, and instruction-following inconsistency — give finer-grained partitions of what this chapter calls Category 6.

How the seven categories below differ from those. This chapter's taxonomy is organized by fix locus — which artifact (the spec, a tool, a scope clause, an oversight checkpoint, a model choice, a perception-verification step) you change to prevent recurrence — rather than by failure mechanism. Both partitions are useful; they answer different questions. If you want to understand failure mechanics empirically, use MAST and the hallucination literature. If you want a triage protocol that maps each failure to the artifact a human will edit, use the seven categories below. They are complementary, not competing.

The book takes the practitioner-friendly partition because the discipline it teaches is "fix the right artifact." If your team has the bandwidth to maintain a finer empirical breakdown alongside, do.

The seven failure categories

Failures fall into seven categories. Categories 1–6 cover the failure space common to text-based agent deployments. Category 7 (Perceptual Failure) addresses an additional surface that emerges in perceiving-then-acting systems — computer-use agents, browser-use agents, robotic systems — and which prior taxonomies do not partition. Correctly categorizing a failure determines how to fix it — and what it reveals about the design.

Category 1: Spec Failure

The specification was incomplete, ambiguous, contradictory, or incorrect. The agent executed faithfully against the spec it was given, but the spec did not describe the correct output.

Signs:

• The agent did something reasonable given what it was told
• A reviewer who only saw the spec would not have predicted the problem
• The same spec, re-run, produces the same problem
• Different agents or models produce the same wrong output from the same spec

Common manifestations:

• Agent makes a decision the author would have prohibited if they had thought of it
• Agent handles an edge case in a reasonable but incorrect way
• Agent produces the right structure with the wrong content because content requirements were unstated
• Agent stops at the wrong point because completion criteria were vague

Fix: Update the spec. Re-run. Do not patch the output without fixing the specification — the same gap will produce the same error on the next execution.

Category 2: Capability Failure

The agent lacked a tool it needed, or had a tool that was insufficient for the domain (wrong interface, missing data, incorrect behavior). The agent routed around the limitation in a way that was incorrect or incomplete.

Signs:

• The original task was achievable; the agent found a workaround that technically completes the spec but in the wrong way
• The output is subtly wrong in a way that's hard to trace to a specific spec violation
• Often manifests as a long chain of simple tool calls substituting for one appropriate complex tool

Common manifestations:

• Agent manually constructs a complex SQL query instead of calling a report API, getting edge cases wrong
• Agent uses a file system tool to simulate a database operation it didn't have a proper tool for
• Agent approximates a computation by composing simpler operations, losing precision

Fix: Add the missing capability. This is an infrastructure fix, not a spec fix. Once the capability exists, verify the spec would have used it correctly.

Category 3: Scope Creep Failure

The agent completed the requested task and then continued, doing adjacent work that wasn't asked for. Or it interpreted "complete the billing report" to include "fix the data anomalies I found in the underlying records," because fixing them seemed helpful and wasn't explicitly prohibited.

Signs:

• The core task is complete and correctly done
• Additional work was done that nobody asked for
• The additional work may itself be correct, but authorization was absent

Why it matters: scope creep failures are the most likely to cause governance incidents because the agent was doing something it had no authorization for, even if the action was technically correct. The authorization gap — not the quality of the work — is the problem.

Fix: Update the spec's NOT-authorized section to explicitly prohibit the adjacent category of work. This is a scope boundary fix. Review the spec for other potential adjacent work it didn't anticipate.

Category 4: Oversight Failure

The agent produced a wrong output, the oversight model failed to catch it before consequences landed, and the error became known through downstream effects rather than validation.

Signs:

• The error is real (not a matter of preference), but it had time to propagate
• A human reviewer who saw the output at the right moment would likely have caught it
• The oversight model either didn't have a human reviewing at the right stage, or the review didn't catch the specific class of error

Common manifestations:

• Agent sent an external communication before human review (oversight model didn't require pre-send review)
• Agent deployed a change that passed automated validation but violated a convention no test checks
• Agent's minor error accumulated across 200 records before someone noticed

Fix: Redesign the oversight model. This is an escalation trigger / checkpoint fix. The fix is not "be more careful" — it's a structural change to where human attention is applied in the execution flow.

Category 5: Compounding Failure

An early error created conditions for a later error; the combination produced a result neither error would have produced alone. Common in multi-step agent tasks and multi-agent pipelines.

Signs:

• The final output looks extremely wrong
• Tracing backward reveals a chain: each step was locally plausible given what came before
• Any single step's error, if caught early, would have prevented the cascade

Common manifestations:

• Agent produced a slightly wrong plan in step 1; subsequent steps executed correctly against the wrong plan; by step 8, the output is dramatically incorrect
• Agent A produced output that Agent B interpreted in an unexpected way; Agent B produced output that triggered an unintended action in Agent C
• Agent's approximate calculation in step 3 was within tolerance; multiplied by 10,000 records in step 7, the tolerance accumulated past acceptable range

Fix: Two fixes. First, the spec or capability gap that produced the original error. Second, a checkpoint review at the most critical compounding point — typically the handoff between phases or agents.

Category 6: Model-Level Failure

The agent's underlying model produced incorrect output despite a correct, complete spec, appropriate tools, and proper scope. The failure originates in the model itself — its training data, its reasoning patterns, or its instruction-following limitations.

Signs:

• The spec is correct and complete — a knowledgeable human reviewing the spec would have predicted the correct output
• The same spec produces incorrect output consistently or intermittently across re-executions
• The error is not traceable to a missing tool, a scope violation, or an oversight gap
• Output may be structurally correct but factually wrong, or violate constraints clearly stated

Common manifestations:

• Agent hallucinates data values (names, dates, numbers) despite clear spec constraints against fabrication
• Agent systematically misinterprets domain-specific terminology even with skill files providing correct definitions
• Agent produces outputs that pass structural validation but contain subtle logical errors reflecting training biases
• Agent's confidence is uncorrelated with accuracy — high-confidence outputs are wrong at similar rates to low-confidence outputs

Fix: Model-level failures cannot be fixed through better specs alone. Response depends on frequency and severity:

• Low frequency, low severity — accept as residual risk; rely on validation to catch. Document in the spec gap log as a known model limitation.
• Low frequency, high severity — add automated output validation that checks the specific failure pattern. Add human review checkpoint for the affected output type.
• High frequency — the task exceeds the model's reliable capability boundary. Options: narrow the scope to a subset the model handles reliably, switch to a more capable model, retain the task for human execution, or accept that the agent is not deployable in this domain at this time.

Be honest about the limit. This is the category where the framework reaches its boundary. A perfect spec executed by an unreliable model still produces unreliable output. Validation cannot catch every hallucination, especially the high-confidence ones — research consistently shows that LLM confidence is poorly correlated with accuracy. Sampling-based validation will miss failures in the unsampled fraction. Judge models can themselves hallucinate, and they share systematic errors with the agent they are evaluating when both are based on the same model family.

The framework's contribution here is diagnostic, not curative: by ruling out Categories 1–5, teams avoid two opposite errors — blaming architecture for model limits, and blaming models for architectural gaps. But once you have correctly identified a Category 6 failure with high frequency, the honest answer is sometimes "this task is not currently deployable to this agent, regardless of how well we spec it."

Category 7: Perceptual Failure

The system's perception of the environment diverged from the environment's actual state, and the system acted on the wrong perception. This category is specific to perceiving-then-acting systems: computer-use agents, browser-use agents, and robotic systems. Prior taxonomies (MAST, the hallucination literature) do not partition this surface as a distinct class.

Signs:

• The agent acted on something that was not actually there, or acted on the wrong instance of something that was
• A screenshot or sensor record taken at the moment of action would have shown a discrepancy from the agent's claimed reasoning
• The same spec, with the same authorized scope and the same tools, produces correct behavior in some environments and incorrect behavior in others — environment-shape, not spec-shape, is the differentiator

Four sub-categories:

• Misidentification. The agent identifies an interface element correctly as a category (e.g., "a button") but assigns it the wrong role (e.g., a "Cancel" button identified as "Confirm"). The fix is structural: a confirmation gate before high-consequence actions, where the gate's prompt is generated from the agent's claimed intent ("you are about to click Confirm — is that what you mean?") and surfaces the discrepancy to a human reviewer or a Guardian.
• Missed element. The agent fails to perceive an element that is visually present (a modal dialog, an error banner, a required field). The fix is screenshot-then-verify: before any consequential action, the agent re-grounds on a fresh screenshot and reconciles its planned action against what is currently visible.
• Hallucinated element. The agent acts on an element that is not present in the rendered DOM but that the vision-language model believes it sees. The fix is an element-allowlist plus DOM-grounded verification: every claimed element must resolve to a DOM node before action is permitted.
• State miscount. The agent is correct about elements but wrong about position or count (clicks the third row when the second was intended; processes 9 of 10 records and reports 10). The fix is re-verification of position-based facts at the moment of action rather than at the moment of planning.

Common manifestations:

• Lookalike-domain navigation (homoglyph or subdomain confusion) where the agent's visual reading of the URL bar diverges from the actual destination
• Visual instruction injection on a rendered page (text rendered to look like an instruction is treated as authoritative)
• Modal popup interception where an adversarial dialog is processed as a legitimate prompt

Fix: Perceptual failures are not fixed in the prompt. They are fixed at the structural-controls layer — sandboxed environment, authentication-scope minimization, domain allowlist, high-consequence confirmation gates — and at the verification protocol layer — confirmation gate, screenshot-then-verify, multimodal grounding, element-allowlist, DOM-grounded verification, re-verification at action time. None of these live in the agent's instructions; all live in the spec's authorized scope, the tool manifest, or the per-action verification step.

When Cat 7 applies. Cat 7 is the load-bearing diagnostic category for any deployment where the agent's input includes a perceptual layer — vision, audio, sensor — that can diverge from the underlying state. Text-only agent deployments do not encounter Cat 7. Computer-use deployments encounter it routinely; browser-use deployments encounter it whenever the page is rendered rather than parsed; robotic deployments encounter it whenever the sensor reading is the input to the action.

The diagnostic protocol

When a failure occurs, resist the impulse to fix immediately. Apply this protocol:

1. Reproduce the failure deliberately
   (If it can't be reproduced, this is likely Category 6)

2. Apply the diagnostic test:
   "If a competent agent had executed this spec as written,
    would the outcome have been correct?"

3. Walk the categories in order:
   - Would a reviewer who saw only the spec have predicted this?  → Cat 1: Spec
   - Did the agent route around a missing or insufficient tool?    → Cat 2: Capability
   - Did the agent do correct adjacent work it wasn't authorized?  → Cat 3: Scope creep
   - Did the error propagate past where review should have caught? → Cat 4: Oversight
   - Did one early error compound through later steps?              → Cat 5: Compounding
   - Spec correct, tools correct, scope correct, but model wrong?   → Cat 6: Model-level
   - Did the agent's perception of the environment diverge from
     the actual state, and was the action taken on that wrong
     perception? (Computer-use / browser-use / robotic only)        → Cat 7: Perceptual

4. Trace to the specific artifact:
   - Spec → which section, which missing or ambiguous clause?
   - Capability → which tool call, what was attempted, what was the limit?
   - Scope creep → what adjacent action, where was the boundary?
   - Oversight → at what point in execution did the error exist and go unreviewed?
   - Compounding → where in the chain did the first error occur?
   - Model-level → what specific model behavior? Reproducible? Known limit?
   - Perceptual → which sub-category (misidentification, missed element,
     hallucinated element, state miscount), and which structural
     control or verification step is missing?

5. Fix the artifact, not the output

6. Log the gap (see The Spec Gap Log below)

7. Re-execute with the fixed artifact and verify the fix prevents the
   failure category, not just the specific symptom

The spec gap log

Every diagnosed spec failure should be recorded in a Spec Gap Log. Not a bug tracker (which tracks implementation errors) — a record of every time a failure pointed to something that should have been in the spec but wasn't.

A Spec Gap Log entry captures:

• What was missing
• When it was discovered
• Which spec section was affected
• What spec change was made

Over time, the log becomes:

• A source of constraint additions that make future specs more complete
• A record of tacit knowledge that was made explicit
• Training data for the team's calibration of "what needs to be in a spec"
• Evidence for governance conversations about where oversight should be increased

This is what it means to say failure is a design signal: each failure, properly diagnosed, makes the system of specs stronger. The goal is not zero failures — it is zero unlearned-from failures.

Common spec failure modes

Within Category 1 (Spec Failure), a few recurring shapes show up so often they're worth naming:

• The Missing Invariant — an assumption so obvious to the author that it was never written; the agent violated it.
• The Scope Ambiguity — the spec didn't define what was out of scope; the agent built too much.
• The Implicit Audience — the spec was written assuming the agent shared the author's cultural and institutional context; it did not.
• The Success Vacuum — the spec had no measurable success criteria; the agent optimized for something that wasn't what was meant.
• The Frozen Context — a constraint in the spec was true at time of writing but is no longer true; the system continues to enforce a rule that no longer applies.

If you find yourself diagnosing the same shape repeatedly, it's a signal that your spec template or review process should explicitly check for it.

Anti-patterns in failure response

• Spec debt. Fixing the output without fixing the spec that produced it. The output is now correct; the spec will produce the same problem on the next execution. Spec debt accumulates until addressed — at which point the fixes are much more expensive, because the gaps have multiplied and the context has been forgotten.
• Oversight theater. Adding more oversight after a failure without fixing the underlying cause. "We'll have a human review every output from now on" is not a fix — it's a compensating control that adds cost without eliminating risk, and creates a false sense of security.
• AI attribution evasion. Blaming the model for failures that are architectural. "The AI got it wrong" is true in a narrow sense and useless in a design sense. The model produced the most probable output for the inputs it received. Fix the inputs.
• Tooling over specification. Investing in better observability, logging, and dashboards while the underlying specs remain under-specified. Observation infrastructure makes failures visible; it does not prevent them. Fix the spec first; build the visibility layer to verify the fix held.

Failure as organizational learning

The most valuable property of a well-structured failure is that it is specific. A failed output, properly diagnosed, points precisely at the assumption that was wrong — and that assumption, now corrected, will be correct for every future execution against the same class of task.

This is the compounding return on spec-driven development: every diagnosed failure improves a spec or a skill, and that improvement is durable. It lives in a versioned artifact applied to every future task in the domain. The organization gets smarter about each class of work as that work accumulates failures and those failures are properly attributed and corrected.

Compare this to a conversational agent workflow: failures are addressed in the conversation ("try again, but this time…"), and the correction lives only in the conversation history. It does not propagate. The organization forgives the failure without learning from it.

The Spec Gap Log, the skill review cycle, and checkpoint adjustment processes are how agent systems turn failure into institutional knowledge. They transform a cost — the failure — into an investment.

Resulting Context

After applying this pattern:

• Failure analysis becomes a structured discipline. Seven categories with a diagnostic protocol replace ad-hoc blame attribution with systematic root-cause identification.
• Fixable failures are distinguished from model limitations. Categories 1–5 are fixable through better specs, tools, scope definitions, or oversight. Category 6 requires model-level responses. Category 7 is fixable through structural controls and verification steps at the perception–action interface.
• Spec gap logs accumulate organizational learning. Each diagnosed failure enriches the team's understanding of what specs need to specify.
• Compounding failures become preventable. By identifying the earliest error in a chain, checkpoint reviews can be placed at the most critical juncture.

Therefore

Agent failures fall into seven categories — spec, capability, scope creep, oversight, compounding, model-level, and perceptual (for perceiving-then-acting systems) — each with a distinct mechanism, a specific architectural fix, and a different lesson. Diagnose before you fix. Fix the artifact, not the output. Log the gap. Re-execute. Failures attributed to "the AI" are unactionable; failures attributed to their architectural category are fixable, and the fixes are durable.

References

• Cemri, M., et al. (2025). Why Do Multi-Agent LLM Systems Fail? — MAST: A Multi-Agent System Failure Taxonomy. — Empirical 14-category partition derived from 200+ multi-agent failure traces; the strongest published practitioner-facing failure taxonomy.
• Zhang, Y., et al. (2025). LLM-based Agents Suffer from Hallucinations: A Survey of Taxonomy, Methods, and Directions. arXiv:2509.18970. — Fine-grained partition of model-level (Category 6) failures.
• Where LLM Agents Fail and How They Can Learn from Failures. (2025). arXiv:2509.25370. — Failure-mode-driven self-correction in agent systems.
• Reason, J. (1990, 1997). Human Error / Managing the Risks of Organisational Accidents. — The Swiss-cheese model and the active-vs-latent failure distinction informing this chapter's "log the gap, fix the artifact" discipline.
• Ohno, T. (1988). Toyota Production System: Beyond Large-Scale Production. — Origin of the "5 Whys" practice that the diagnostic protocol simplifies.

Connections

This pattern assumes:

• Intent vs. Implementation
• Calibrate Agency, Autonomy, Responsibility, Reversibility

This pattern enables:

• The Living Spec — failure-driven spec evolution as practice
• Proportional Oversight — designing oversight that catches the failure categories you can't prevent
• Four Signal Metrics — measuring spec quality through failure signal
• Evals and Benchmarks — the empirical layer that complements the diagnostic protocol
• Post-mortem Through Intent — a worked example of this protocol applied to a real incident

What Changes for the Senior Engineer

Part 0 — Foundations

"Late judgment was the compensation that made vague specs work. The compensation does not survive automation. The judgment has to move."

Who this chapter is for

This is the one Foundations chapter with a specific audience rather than a universal one. The book's primary reader is the tech lead, staff engineer, or platform-team member on the hook for an agent system; this chapter speaks to that reader's career question, not their system-design question. The other Foundations chapters (What is AoI, Intent vs. Implementation, the four dimensions, the failure taxonomy, the Intent Design Session) are load-bearing for every reader — without them, the rest of the book does not parse. This chapter is not load-bearing in the same way. A reader who is not personally navigating the transition can skip it on first read; the chapters in Parts 1–5 do not assume it.

It is in Part 0 anyway because the reframe it offers — late judgment moves upstream into the spec — is the personal counterpart of the framework's structural claim, and many senior engineers will not adopt the framework's discipline without working through that reframe first.

Context

The senior engineer reading this book is the person who, until recently, was the framework. They compensated for vague specs by exercising late judgment. They escalated ambiguities rather than executing them. They rewrote tickets into what was clearly meant. The compensation was invisible — nobody measured it — but it was the real reason senior engineers were valuable.

The Prologue named this and called it the reason the discipline matters now: that compensation mechanism does not exist when an agent is doing the implementation. This chapter is the response to the question the Prologue leaves open — if my late judgment used to be the value-add, what is the value-add now?

This is the most personal chapter in the book. It is also the one where the framework's discipline gets honestly tested against the question of what gets lost in the transition, not just what gets gained. The book's typical reserve applies: this is a working position, not career advice.

This pattern assumes the Prologue, What is the Architecture of Intent?, and The Intent Design Session.

The Problem

Two structural changes do most of the work.

1. Late-judgment work shrinks. The work senior engineers used to do — read a vague spec, supply missing constraints from experience, escalate when something looked off, rewrite the ticket into what was actually meant — is precisely the work that has no equivalent when the implementer is an agent. The agent does not pause; it commits. The senior engineer's compensatory move was temporal (happening during implementation); the framework's response is structural (happening before implementation). That structural move is the rest of this book.

2. Tribal knowledge decays as leverage. The senior engineer who knew the codebase deeply, who remembered why a particular invariant existed, who could spot the bug that mattered without grep — they had leverage because that knowledge was scarce and locally embedded. Agents have read the codebase too, faster, and without the lossy compression of human memory. The leverage that used to come from "knowing the code" decays; the leverage that comes from having authored the spec the code is judged against rises.

Both changes are real, neither is total, and both have personal costs the framework should not minimize. The rest of this chapter is about where the judgment goes, what is honestly lost in the move, what is gained, and where the career ladder fails to keep up.

Forces

• Sunk cost vs. honest reframe. A senior engineer's career is years of investment in late-judgment skill. Telling someone "your late judgment is now upstream" can sound like devaluing the investment. It isn't — but it requires honest reframe, not minimization.
• Personal preference vs. industry direction. Some senior engineers genuinely enjoyed late-judgment work — the flow state of complex debugging, the satisfaction of a clean fix to an architectural drift. That preference is real; the industry's shift away from rewarding it is also real. Both are true.
• The career ladder vs. the work. Most engineering ladders measure lines-shipped, code-review-counts, mentoring of juniors. The shift in where senior judgment lands implies the ladder needs to update — but ladders update slower than the work.
• Personal continuity vs. personal change. A senior engineer can be valuable without doing the same things they used to do; the value just lands in a different part of the lifecycle. But "becoming valuable for different things" is a substantial personal transition with real costs.

The Solution (or, more honestly: how to think about it)

Where the judgment goes

The compensatory judgment doesn't disappear. It moves upstream, and it changes shape. Specifically:

Into Frame. The judgment that used to ask "what was clearly meant by this ticket?" now asks "what is this system trying to achieve, within what constraints, and how will we know it is working?" Same question, asked earlier, with a different set of stakeholders in the room. The senior engineer is the domain owner, the architect, or the spec author — whichever role best matches their actual leverage.

Into Specify. The judgment that used to fix a bad PR description after the fact now writes the spec clauses that prevent the bad PR description from causing damage in the first place. The §6 Invariants section, the §3 Out of Scope clauses, the §8 Authorization Boundary — all of these are senior judgment encoded once so it doesn't have to be exercised every time.

Into Bind Patterns. The judgment that used to know "this codebase needs Y safety pattern because we burned ourselves last quarter" now goes into the IDS's Bind Patterns phase. The patterns aren't "general best practice"; they're bound to specific spec clauses by someone who has seen the failure mode the pattern prevents.

Into Skeptic. The judgment that used to ask "what could go wrong?" during code review now asks the same question during the IDS, when the answer can become a constraint instead of a comment. The skeptic's role in the framework is, in effect, a senior engineer's late-judgment instinct given a structural seat.

Into Validate. The judgment that used to debug a confusing failure now diagnoses by fix locus — naming whether the failure was Cat 1 (Spec) or Cat 4 (Oversight) or Cat 7 (Perceptual), and amending the artifact whose modification prevents recurrence. The senior engineer's reading of "this is the kind of failure where..." becomes the categorization that drives the spec evolution log and, downstream, the Discipline-Health Audit.

The pattern across all five: late-judgment skill is not lost; it is shifted in time and externalized into artifacts. The skill itself — knowing what's wrong, knowing what to ask, knowing what could go wrong — is the same skill. Where it lands is different.

What is lost honestly

The framework should not pretend the transition is painless or universal. Some real losses, named without minimization:

The flow state of late-judgment debugging. Some seniors found a particular satisfaction in inheriting a confusing system, debugging it deeply, and producing a clean fix. The framework's structural response — make the failure diagnosable upstream so it doesn't have to be debugged downstream — eliminates much of that flow. For some practitioners, this is a real loss. The work they liked is rarer.

Tribal knowledge as a competitive moat. The senior engineer who was the keeper of "why we don't use library X" or "the right way to add a new feature in this module" had value precisely because that knowledge was hard to replicate. Encoding that knowledge into specs, ADRs, and constraint libraries is the framework's directive — and it dilutes the moat. The directive is correct; the dilution is real. A senior engineer whose value lived mostly in their head is being asked to externalize it into artifacts. That feels different even when the externalization is the right move.

Pure-implementation seniority. A senior engineer whose seniority lives mostly in how fast they can write correct code faces a competitive surface that has shifted. Code generation is no longer the bottleneck. Seniority that does not move upstream into Frame, Specify, or Validate is competing on an axis that is becoming less differentiated.

Some senior engineers will not make the transition. This is the hardest thing to say honestly. The transition is real and not always comfortable. Not everyone wants to do upstream work. Some practitioners chose the field because they liked the late-judgment fix, and being told the work has moved feels like being told the work they signed up for is gone. That is correct. "I don't want to" is a legitimate response. Organizations that pretend otherwise will lose some of their best practitioners to other work or other industries — which is itself a form of organizational drift the framework cannot fix from the inside.

What is gained

Authorship that compounds. A spec the senior engineer authored governs every run the agent does against it. The leverage is no longer per-incident; it is per-deployment, then per-team, then per-organization. A single hour of careful spec authorship can constrain thousands of agent decisions correctly, indefinitely.

Durable artifacts. The judgment that used to be ephemeral — in the engineer's head, in their PR comments, in their hallway conversations, in their on-call notes — becomes a durable artifact: the spec, the manifest, the constraint library, the ADR, the spec evolution log. It survives the engineer leaving the team. It scales beyond a single conversation.

Leverage across teams. The patterns, the archetypes, the spec templates a senior engineer establishes get reused. The work doesn't have to be redone for each new system. The framework's Repertoire is the explicit artifact for this kind of compounding.

A different kind of seniority. The senior engineer's role becomes more architectural and less tactical. They are still doing engineering — but the engineering is now more about designing the surfaces other people (and other agents) operate against, less about being the one who writes the next line of code. For some practitioners this is the work they always wanted to do but didn't have the structural permission to. For others, it is a substantial change in what the day feels like.

The career-ladder problem

Most engineering ladders measure things that no longer correlate well with senior value. "Lines shipped" measures implementation throughput; if implementation is automated, the metric measures the wrong thing. "Code-review counts" measures involvement; if the spec is doing more of the review work, the metric measures the wrong thing. "Number of bugs fixed" measures late-judgment debugging; if structural fixes are landing earlier, the metric measures the wrong thing. "Mentoring juniors" measures one form of knowledge transfer; if the framework's discipline is to encode knowledge into specs and constraint libraries, that measure misses the codified part.

A ladder that measures the right thing in 2026 measures structural artifacts: specs amended, invariants articulated, oversight gates designed, post-mortems with fix-locus categorization, evolution-log entries authored, repertoire entries contributed, Discipline-Health Audits led. These are harder to count than lines or PRs, which is why most ladders haven't updated. Organizations that don't update theirs will systematically reward the wrong work, and their senior engineers will gradually drift toward the rewarded work, regardless of whether it is the valuable work.

The framework cannot fix the ladder. It can name the gap. The senior engineer who reads this chapter and recognizes the gap is in a position to be a credible voice for changing how their organization measures senior contribution. The book takes the position that this is part of the senior engineer's responsibility under the new discipline: not just to do the upstream work, but to make the case that the upstream work is what should be measured. Otherwise the ladder will pull good practitioners back to the work that gets noticed, and the discipline will not survive its first few quarters.

What does not change

The values that made senior engineering valuable still apply: judgment under uncertainty; taste about what good looks like; willingness to say "this isn't right" before there is evidence; stewardship of artifacts other people will inherit; refusal to ship things you don't trust. These don't go away. They just attach to different artifacts.

If anything, those values matter more now, because the structural artifacts the framework produces (specs, manifests, constraint libraries, oversight models) are load-bearing in a way that ad-hoc late-judgment never was. The senior engineer who exercises judgment about a spec is exercising judgment about every future run of the system the spec governs. The amplification goes both ways: a careful spec compounds; a careless one compounds too.

A note on rate

The transition is not happening to every senior engineer at the same rate, and it is not happening to every domain at the same rate. Codebases with a long history of brittle implicit invariants will move slower than greenfield agent systems. Regulated domains will move slower than consumer-internet domains. Teams whose seniors already lived upstream (architects, platform leads, framework maintainers) are already in the new regime; teams whose seniors lived in late-implementation flow have further to travel.

The book makes no prediction about how long the transition takes in any specific organization. It only stakes out the position that the direction is settled: late-judgment compensation is shrinking as a senior-engineer value-add, and the work the framework names is what fills the gap.

Resulting Context

After this chapter has done its work:

• The senior engineer has a vocabulary for the transition. The Prologue named the problem; this chapter names the response. They can describe what they used to do, what is changing, where their judgment now lands, and what is honestly lost in the move.
• The losses are visible and named. The chapter does not pretend the transition is painless or universal. Some practitioners will not make the move; that is named explicitly rather than glossed over.
• The career-ladder gap is named. Organizations that haven't updated their ladders will systematically reward the wrong work. The senior engineer is in a position to advocate for measurement that matches the work — and the framework takes the position that doing so is part of the new senior responsibility.
• What does not change is also visible. The values that made senior engineering valuable in the first place — judgment, taste, stewardship, refusal to ship things you don't trust — don't go away. They attach to different artifacts and matter more, not less.

Therefore

The senior engineer's compensatory late judgment — the invisible value-add that made vague specs work — does not survive automation. The judgment moves upstream: into Frame, Specify, Bind Patterns, Skeptic, Validate. The framework's discipline is what makes that move structural rather than aspirational. What is lost is real (the flow of late-judgment debugging, tribal knowledge as a moat, pure-implementation seniority); what is gained is also real (authorship that compounds, durable artifacts, leverage across teams, a different kind of seniority). Some senior engineers will make this transition; some will not. Organizations that do not update their ladders to measure structural artifacts rather than implementation throughput will lose the ones who do. The framework cannot fix the ladder; the senior engineer who recognizes the gap is the credible voice for fixing it.

Connections

This pattern assumes:

• Prologue: What Changed and What's at Stake — the framing this chapter responds to
• What is the Architecture of Intent? — the discipline this chapter situates the senior engineer within
• The Intent Design Session — the operational ritual where the senior engineer's judgment lands

This pattern enables:

• Roles & Responsibilities (RACI) Card — the role-to-activity matrix that locates the senior engineer's judgment by activity
• Adoption Playbook — the path by which an organization moves to the practice this chapter describes
• Signs Your Architecture of Intent Is Degrading — the audit that catches when the discipline has decayed back to late-judgment compensation in a different form

The Intent Design Session

Part 0 — Foundations · The exit chapter

"A discipline you cannot run on a calendar invite is a discipline you do not have. The session is where the framework becomes work."

Why this is the Foundations exit

This is the last chapter of Part 0 by design, not by file number. The five chapters that precede it — What is AoI, Intent vs. Implementation, the four dimensions, the failure taxonomy, and (for readers personally navigating the transition) What Changes for the Senior Engineer — establish the vocabulary. The Intent Design Session is the ritual that turns vocabulary into a commitment for one specific system. Without the ritual, the framework stays decorative; with it, the framework becomes work.

Every subsequent Part (Frame, Specify, Delegate, Validate, Evolve) elaborates one phase of the work the IDS schedules in compressed form. The session is therefore the bridge: a reader who finishes Part 0 and runs an IDS the following week has used the framework once; a reader who finishes Part 0 and starts writing a spec without running an IDS will reproduce the failure modes the rest of the book catalogs.

When you are lost later in the book, the question to ask is usually: what phase of the Intent Design Session does this chapter sharpen? — and the answer maps it back to this ritual.

Context

9 AM Monday. The team has the framework's vocabulary, has read the book, has agreed they need to ship a new agent next quarter. Someone opens a doc and starts typing the spec. The tech lead stops them: "We're skipping a step. Read the framework, write the spec — that's the failure pattern Part 1 named. We need the session in between." They book a 4-hour conference room for Wednesday and put the spec doc away.

What gets skipped, when teams skip it, is the working session that turns the framework's vocabulary into a calibrated commitment for one specific system. The session is what bridges the abstract framework and the concrete spec. Without it, the spec is written against an implicit shape the team never agreed on, which is the most-common source of "this system grew into something we didn't intend" a quarter later.

You have read Part 1. You understand archetypes, dimensions, failure modes, intent versus implementation. You have seen the canvas in the Introduction. You know what a spec looks like (Part 2) and roughly which patterns exist (Parts 3–4). What you do not yet have is a ritual that puts these pieces together for one specific system you are about to build.

This chapter gives you the ritual.

The Intent Design Session is a time-boxed working session — typically 3 to 4 hours, run once per system or once per major spec revision — that walks a team through the four activities of the framework (Frame · Specify · Delegate · Validate) in seven concrete phases. It produces a calibrated archetype commitment, a draft spec, a bound set of patterns, an oversight model, and a rollout plan. By the end of the session, the team has the artifacts it needs to start building. By the next session (the post-launch retrospective), the team has the artifacts it needs to learn.

This pattern is the connective tissue between Part 1 (the decisions) and Part 2 (the spec). It assumes you have read Pick an Archetype, Calibrate Agency, Autonomy, Responsibility, Reversibility, and Failure Modes and How to Diagnose Them. It produces an artifact you will write up using The Canonical Spec Template.

The Problem

Without a ritual, a framework's pieces stay disconnected. A team that has read the book does not automatically run a coherent design pass. Five common failure modes recur:

• Patterns picked by team taste. Someone on the team likes building MCP servers, so the system gets an MCP layer. Someone else has been reading about RAG, so the system gets retrieval. Neither was driven by what the spec implies. The patterns were picked by enthusiasm, not by intent.
• Oversight bolted on at the end. The spec gets written, the agent gets built, and only late in the cycle does someone ask "wait, who reviews the output?" — at which point the answer is whichever model produces the least friction at launch, which is rarely the model the system actually needs.
• Calibration left implicit. The team commits to "an Executor" and "high autonomy" without writing down what those mean, what the agency boundary is, where reversibility is irrecoverable, or who carries authorial versus operational responsibility. When the system misbehaves, the post-mortem cannot diagnose which calibration was wrong.
• Spec written by one person, alone. The spec is the artifact the agent executes against and humans review against. If only one person was in the room when it was written, only one person's mental model is encoded in it. The first divergence between agent output and intent is usually a difference between that person's tacit assumptions and someone else's — and the gap shows up at runtime, not at review time.
• No commitment to learning. Without a planned post-launch retrospective, every spec gap stays a private surprise. Without a record, the same gap recurs in the next system.

The Intent Design Session addresses all five at once. It puts the right people in the room for the right amount of time, walks them through the framework's activities in order, and ends with a written set of artifacts that other people can read.

Forces

• Time pressure vs. design depth. Teams will not sit through a multi-day design retreat for every system; they will sit through a focused half-day for a system that matters. Time-boxing is what makes the discipline scalable.
• Discipline vs. flow. A rigid script kills the conversation; a script-less session reverts to whoever talks loudest. The session needs phases that constrain what gets discussed without scripting how.
• Senior judgment vs. team ownership. The strongest ideas in a session often come from senior practitioners; the strongest commitment comes from the team that will operate the system. The session has to extract both.
• Specificity vs. portability. The artifacts the session produces must be specific enough to drive implementation and portable enough that someone joining the team a quarter later can read them and understand the design.

The Solution

Who attends

Five roles, all required. Two people may share a role; one person should not hold more than one role unless the system is small enough that a one-person session is honest.

If you cannot fill the five roles, do not run the session — write the spec alone and accept that you have not done the discipline. Calling a single-person spec-write an "Intent Design Session" defeats the purpose.

These five roles are a subset of the seven canonical roles in the framework's Roles & Responsibilities (RACI) Card, which extends the picture to two more (the builder who implements the agent and the reviewer who validates outputs at the oversight gate) and maps all seven against the six operational activities. The IDS is when the RACI is enacted for one specific system; the card is the matrix the team enacts against.

What to bring

• The canvas (Introduction) — printed or projected, used as the running agenda.
• The archetype catalog (Repertoire) — for phase 2.
• The canonical spec template (Spec Template) — populated live during phase 4.
• The pattern index (Pattern Index) — referenced during phase 5.
• Any prior post-mortem from a related system — concrete failures in phase 5 are sharper than imagined ones.
• Absence of laptops for everyone except the spec author and the architect. The other roles should be present, not editing.

The seven phases

The phases follow the canvas top-to-bottom. The time-boxes assume a 3.5-hour session for a medium-scope system. Scale up or down by ±50% for larger or smaller scopes.

Phase 1: Frame (15 min, domain owner leads)

The domain owner answers the three questions on the canvas's top strip:

1. What is this system trying to achieve?
2. Within what constraints?
3. How will we know it is working?

The output is one paragraph per question, captured by the spec author. No archetype talk yet. No pattern talk yet. No spec writing yet. The phase ends when the team can repeat each question's answer back without looking at notes.

If a team cannot agree on the framing in 15 minutes, stop and reschedule. There is no point continuing — the rest of the session will design a system the team has not yet agreed exists.

Phase 2: Categorize (20 min, architect leads)

The architect walks the archetype selection tree against the framing from phase 1. The team commits to one of the five archetypes. If a risk override applies (irreversible state, regulated data, safety-critical control), the team applies it explicitly and records the elevated archetype.

If the system genuinely composes archetypes (an Orchestrator over Executors with a Guardian on the boundary), the team commits to the primary archetype and names the composed components. Each composed component will get its own row in the spec; do not collapse them into a single archetype label.

Output: one line in the spec, e.g. "Archetype: Executor (with Guardian-on-boundary for sensitive-data validation), risk override applied because output triggers external state change."

Phase 3: Calibrate (20 min, architect + operator co-lead)

The architect and operator set the four dimensions on the canvas's calibration bar:

• Agency — what classes of decision can the system make without consulting a human?
• Autonomy — what steps run without per-step approval?
• Responsibility — who owns the spec (authorial), who runs each call (operational), who approves the output (validation)?
• Reversibility — what is the worst-case state the system can leave behind, and what is the cost to recover?

Each dimension gets a one-sentence answer recorded in the spec's Archetype Declaration section. Disagreement between the architect and the operator at this phase is productive — it is the point at which "what we want the system to do" meets "what I will be paged about at 3am." Resolve before moving on.

Phase 4: Populate Spec (45–60 min, spec author leads, all participate)

The spec author opens the canonical spec template and the team walks all twelve sections in order. Most sections take 2–5 minutes; sections §3 (Scope), §6 (Invariants), and §8 (Authorization Boundary) take longer because they encode the calibration from phase 3 into testable clauses.

The spec author writes; everyone else watches and challenges. Do not draft offline and present; the value of this phase is the conversation that produces each clause. A clause no one questioned in the session will be the clause everyone disputes during the first incident.

Output: a draft spec covering all twelve sections, marked Draft. It is not Approved yet — phases 5–7 will surface gaps that send some sections back for revision.

Phase 5: Bind Patterns (45–60 min, skeptic leads, architect + operator participate)

This is the connective tissue. The team reads the draft spec aloud, clause by clause, and binds patterns to what each clause implies. The skeptic asks "what could go wrong?" at each clause; the team answers with a pattern.

The binding is driven by what the spec implies, not by what the team likes. Use the table below as the starting point:

The table is not exhaustive — it is a starting set. The skeptic's job is to surface implications the table misses. Every bound pattern goes into the spec's Implementation Notes section with a one-line justification ("we bind output-validation-gate because §3 authorizes external state change").

If the team finds itself binding patterns that the spec does not yet imply, that is a signal: either the patterns are unnecessary or the spec is missing a clause. Resolve by amending the spec, not by accepting unjustified patterns.

Phase 6: Oversight & Metrics (20 min, operator leads)

The operator commits to one of the four oversight models — Monitoring, Periodic, Output Gate, or Pre-authorized — proportional to the autonomy and reversibility set in phase 3. The mapping is straightforward: high autonomy + low reversibility forces Output Gate; low autonomy + high reversibility allows Pre-authorized; the middle cases pick Periodic or Monitoring based on the cost of a missed signal.

The operator also commits to the four signal metrics — spec-gap rate, first-pass validation, cost per correct outcome, oversight load — and where each is instrumented. The metrics are not optional; a system without them cannot diagnose its own failures.

Output: §11 (Agent Execution Instructions) and the metrics-instrumentation plan in the spec.

Phase 7: Stage Rollout (15 min, all)

The team commits to a rollout plan: canary scope, success criteria for graduation, rollback trigger, and the date of the post-launch retrospective. The retrospective is non-negotiable; it is the next Intent Design Session for this system, run with the spec gap log open.

Output: §13 (Spec Evolution Log) seeded with the launch entry; §14 (Planned Evolution) seeded with the retrospective date.

What the session produces

By the end of a properly run session, the team has:

1. A draft spec in twelve sections, marked Draft, ready for asynchronous review.
2. A bound pattern set justified by spec clauses, recorded as an Implementation Notes section.
3. An oversight model commitment with a metrics instrumentation plan.
4. A rollout plan with a scheduled retrospective.
5. A list of open questions captured during the session that did not block the design — these go into §10 (Assumptions and Open Questions) for follow-up.

The artifacts together are sufficient to start implementation. The spec is not yet Approved — it goes through asynchronous review against the Intent Review Before Output Review discipline before promotion.

When to break the script

The seven-phase structure is the default. Deviate when:

• Scope is small (a one-week pilot, a throwaway prototype). Compress to a 90-minute session: combine Frame + Categorize, combine Calibrate + Populate Spec, keep Bind Patterns and Oversight as full phases. Skip Stage Rollout for true throwaways and document that you skipped it.
• Stakes are very high (regulated domain, safety-critical, irreversible at scale). Expand to a two-day session with the skeptic role split into a dedicated security pass and a dedicated domain-expert pass. Schedule a second Intent Design Session after the first implementation iteration; do not assume one session is enough for a high-stakes system.
• The system is a refactor (rewriting an existing agent that already shipped). Run the session with the existing spec as the starting artifact and the post-mortem log as the skeptic's input. Phase 5's pattern binding is more important than Phase 4's spec drafting in this case.
• A team member is remote. Allow it; do not split the session across two timezones. The conversation density that makes the session work depends on everyone being mentally present at the same time.

Anti-patterns

• The retrofit session. Running the session after the system has shipped, "just to document the design we already built." This is not an Intent Design Session — it is a post-mortem disguised as a design session, and it produces a spec that rationalizes existing implementation rather than constraining it. Run a real retrospective instead.
• The single-person session. "I ran the IDS by myself last weekend." A session of one is a spec write. Call it that.
• The hand-wave at Bind Patterns. Listing pattern names in the spec without binding each to a clause. The pattern list becomes inventory rather than design. The fix: every bound pattern has a one-line justification tied to a specific spec clause; if you can't write the justification, drop the pattern.
• Skipping the skeptic. A session that is all builders produces a spec that is all enthusiasm. The skeptic's role is to ask the questions the builders' incentives suppress. If the team lacks an internal skeptic, borrow one from a different team for the session.
• Recording without writing. Recording a session you intend to write up later means you will not write it up. Write during the session. The participants leave with the artifact, not with a promise of it.

Resulting Context

After this pattern is in place:

• Patterns are picked by spec implications, not team taste. The bound-patterns table makes this explicit: every pattern in the system traces back to a clause that justifies it. Patterns the spec does not justify do not enter.
• Oversight is calibrated, not bolted on. The operator owns the oversight commitment in the same session that sets the dimensions, so the oversight model is matched to the autonomy and reversibility from the start.
• Calibration is written down. Disagreements about agency or autonomy surface during phase 3 instead of during the first incident, and the resolved values are recorded as spec clauses rather than as tribal knowledge.
• The spec is a team artifact. Five people watched each clause get written; five people will recognize the divergence when an agent's output drifts from the clause; the spec gap log gets entries that all five people agree on.
• Learning is scheduled. The retrospective is on the calendar before launch. The spec gap log is opened with the launch entry. The next session for this system has a date.

This is what the framework looks like as a working practice. Without the session, the framework is a vocabulary; with it, the framework is a discipline.

Therefore

The Intent Design Session is the time-boxed working ritual through which a team applies the Architecture of Intent to one specific system. It runs in seven phases that follow the canvas top-to-bottom — Frame, Categorize, Calibrate, Populate Spec, Bind Patterns, Oversight & Metrics, Stage Rollout — with five required roles in the room, takes 3–4 hours for a medium-scope system, and produces the artifacts (a draft spec, a bound pattern set, an oversight commitment, a rollout plan with a scheduled retrospective) the team needs to start building and to start learning. Run it before every system worth building deliberately; the systems for which the session is genuinely too heavy are also the systems too small to need the framework.

Connections

This pattern assumes:

• Pick an Archetype — the categorization vocabulary used in phase 2
• Calibrate Agency, Autonomy, Responsibility, Reversibility — the calibration dimensions used in phase 3
• Failure Modes and How to Diagnose Them — the failure taxonomy the skeptic uses in phase 5
• The Canonical Spec Template — the spec artifact populated in phase 4

This pattern enables:

• Spec-Driven Development — the SDD operating model has the IDS as its origin ritual
• Intent Review Before Output Review — the post-session asynchronous review discipline
• Four Signal Metrics — the metrics committed during phase 6
• Adoption Playbook — running the IDS is the first concrete practice a new team adopts
• Roles & Responsibilities (RACI) Card — the canonical role-to-activity matrix the IDS enacts

This pattern is calibrated by:

• The canvas in the Introduction — used as the running agenda

Pick an Archetype

Part 1 — Frame

"You do not invent your relationship to power every time you wield it. You inherit a form — or you build one deliberately. The archetypes are the forms built deliberately."

Context

A team in a Frame session, 30 minutes in. The whiteboard has the system's three questions answered. The product manager is impatient — they want to start naming features. The tech lead writes one word at the top of the board: ARCHETYPE. "We pick this first. Everything else writes itself once we commit." The product manager pushes back: "can't we just start specifying and figure out the shape as we go?" The tech lead's answer is no. Picking the shape after the spec means the spec was written against an implicit shape that the team never agreed on, which is the most-common source of the "this system grew into something we didn't intend" failure pattern.

This is the first decision of the pilot. Before any spec is written, before any agent is configured, before any tool is wired up — you commit to a category for the system you're about to build.

The category is the archetype. There are five canonical archetypes — Advisor, Executor, Guardian, Synthesizer, Orchestrator — and the rest of the book follows from which one you pick.

Detailed per-archetype specifications live in the Archetype Catalog and the individual archetype pages linked at the end of each section.

Where this sits in the work: the chapters in Part 1 elaborate the Frame phase of the Intent Design Session. The IDS is the ritual that schedules archetype selection, calibration, and the rest of the framework's decisions into one working session; when you are lost, return to it to see where this chapter fits.

What an archetype is

An archetype is a pre-committed behavioral frame for a class of system. It is not a template you fill in. It is not a best practice you can ignore. It's a category you operate within.

An archetype defines five things:

1. Identity — what kind of system this is at the categorical level (Advisor / Executor / Guardian / Synthesizer / Orchestrator).
2. Agency Level — the range of discretion the system is authorized to exercise. What classes of decision can it make autonomously?
3. Oversight Model — how human oversight is required to function. Not "some oversight" but: what kind, at what frequency, triggered by what conditions, performed by whom?
4. Reversibility Posture — what is the reversibility profile of this system's actions, and what design requirements follow? A system with irreversible action potential has a different minimum design standard than one without.
5. Invariants — the constraints that cannot be violated under any implementation of this archetype. These are the boundaries between "still this kind of system" and "something that has crossed into a different category."

Why archetype before spec

Archetypes and specs are different artifacts with different owners and different lifetimes:

A spec that attempts to authorize behavior that violates the governing archetype is invalid. The archetype represents decisions made by those with the authority to make them. The spec operates within that frame.

In practice, this means archetype selection is the first decision in any spec development process — before any behavioral specification is written. Getting the category right is more important than getting any specific behavior right, because all specific behaviors must remain consistent with the category.

A note on enforcement

The archetype is enforced through organizational discipline — spec review, governance cadence, authority matrices — not through technical mechanisms that prevent violations at runtime. An agent system can technically take actions outside its declared archetype; nothing in the runtime stops it. The enforcement is procedural and social. This is the same model by which most organizational governance operates, and it works only as well as the review and oversight practices around it. Proportional Governance and Intent Review Before Output Review are how that enforcement becomes operational.

The Problem

Agent systems vary enormously along multiple dimensions: how much they act vs. advise, how much discretion they exercise, how often humans review their outputs, how reversible their actions are. Without a shared vocabulary for these variations, every system is designed from scratch — with no inherited wisdom about which design decisions are consequential and which are flexible.

The result is systems that are miscalibrated: advisors that gradually acquire executor behaviors, executors deployed without adequate oversight, guardians that are actually orchestrators in disguise. The miscalibration is not always intentional — often it is the product of incremental feature additions, each of which seemed reasonable in isolation.

The five archetypes solve this by naming five recurring forms that have so far covered most production agent systems we have classified — categories that emerge from principled reasoning about agency, authority, and consequence. Most systems fit one of these forms; the rest are deliberate compositions. The taxonomy is held provisionally, not settled (see "A working taxonomy, not a settled one" later in this chapter).

Forces

• Specificity vs. completeness. A single archetype framework cannot account for every variation without becoming too granular to be useful. Yet too few categories leave genuine differences in risk and governance unmarked.
• Stability vs. emergence. The framework should be stable enough to guide decisions across organizations and time; yet if real systems emerge that don't fit the five archetypes, the framework should be extended rather than forced.
• Authority clarity vs. discretion. Some systems need significant autonomy while others should be highly constrained. Each archetype must give enough discretion to be useful while remaining governable.
• Reusability vs. context-sensitivity. The archetypes should be recognizable across multiple systems. Yet each system is unique. The framework must allow both consistency and specialization.

The Solution

How the Five Archetypes Were Derived

The archetypes are not a taxonomy invented for convenience. They emerge from two axes:

Axis 1: What is the system's primary act? Does it inform (produce knowledge or recommendations for humans to act on), execute (take actions in the world), enforce (protect constraints and prevent violations), synthesize (compose or transform information), or orchestrate (coordinate the work of other agents)?

Axis 2: What is the scope of its discretion? Does the system decide how to present information (minimal discretion), how to perform a defined task (bounded discretion), whether to allow or block an action (veto discretion), how to combine inputs (compositional discretion), or how to allocate work across agents (coordination discretion)?

The five archetypes emerge from consistent positions on these axes:

Archetype 1: The Advisor

Identity: A system whose role is to surface information, produce analyses, generate recommendations, or suggest options — without taking any action in the world on behalf of the user.

Defining characteristic: The human always decides and always acts. The Advisor never acts on the human's behalf. Its outputs are inputs to human decision-making, not substitutes for it.

Typical forms: Recommendation engines, analytical dashboards, conversational assistants that answer questions, code review tools that suggest (not apply) changes, trend analysis systems, diagnostic tools that identify problems for human resolution.

What makes this category distinct: The Advisor archetype carries the lowest inherent risk of the five, because every consequential action passes through a human decision point. The advisor can be wrong — its recommendation can be poor, its analysis can be flawed — and the harm is bounded by the human's willingness to act on it. This is the primary reason to keep systems in the Advisor category when advisement meets the need: it preserves human judgment at the point of consequence.

The violation to watch for: An Advisor that begins writing (not just suggesting) changes to code, emails, or production data has drifted into Executor territory. The line is whether the system takes consequential action, not whether it produces text.

→ Full specification: The Advisor Archetype

Archetype 2: The Executor

Identity: A system that carries out well-defined tasks autonomously — taking actions in the world within a precisely specified scope of authority.

Defining characteristic: The Executor acts. It produces real outputs: modified files, sent messages, created records, deployed infrastructure. Its agency is bounded but genuine: within its authorized scope, it decides how to accomplish the task.

Typical forms: CI/CD pipeline agents, code-generation agents operating within a defined module, automated test writers, infrastructure provisioners, content publishing agents, data transformation pipelines with write access.

What makes this category distinct: The Executor's power comes from its ability to act reliably within a defined space without requiring human approval at each step. Its safety comes from the precision with which that space is defined. A well-constrained Executor is highly productive and manageable. An under-constrained Executor is dangerous at speed.

The critical design requirement: Every Executor must have explicit scope boundaries (what it can affect), explicit invariants (what it must never do even within scope), and an escalation path for situations that fall outside the designed scope. An Executor that encounters ambiguity and guesses is the most common source of compounding failures.

The violation to watch for: An Executor that begins making decisions about what the scope should be — that expands its own authority based on what seems locally reasonable — has drifted into Orchestrator territory without the corresponding oversight structure.

→ Full specification: The Executor Archetype

Archetype 3: The Guardian

Identity: A system whose primary function is to enforce constraints, protect invariants, validate integrity, and prevent violations — acting as a gatekeeper between a request or state and a consequential outcome.

Defining characteristic: The Guardian's agency is primarily negative: it can block, flag, abort, or alert. It does not initiate actions toward positive goals. It polices boundaries. This one-directional power is intentional — a Guardian that can also act positively is an Executor with a Guardian's constraints, which is a different and more complex design.

Typical forms: Security policy enforcers, compliance validators, PII detection layers, schema validators, rate limiters, approval gates in workflows, content safety filters, financial limit enforcers, contract invariant checkers.

What makes this category distinct: The Guardian operates on a principle of minimum necessary power: it needs only enough authority to block what should be blocked. This deliberate limitation is what makes Guardian systems trustworthy. An organization can deploy a Guardian broadly, with relatively liberal permissions to inspect, because its action space is restricted to refusal.

The violation to watch for: A Guardian that begins remediating violations (not just flagging them) — rewriting the content that failed the check, substituting compliant behavior for non-compliant behavior — has acquired Executor characteristics that require a different oversight model.

→ Full specification: The Guardian Archetype

Archetype 4: The Synthesizer

Identity: A system that aggregates, distills, transforms, or composes information from multiple sources into structured outputs — exercising discretion about how to combine and present, but not about what to act upon.

Defining characteristic: The Synthesizer's output is a new artifact — a summary, a report, a combined analysis, a transformed dataset, a generated draft. Its discretion is compositional: it decides how to weigh sources, how to structure the output, how to resolve conflicts between inputs. It does not decide what real-world actions the output should trigger.

Typical forms: Research synthesis agents, multi-source report generators, knowledge base builders, code documentation agents, meeting transcript summarizers, multi-API data aggregators, contract review systems that produce structured findings.

What makes this category distinct: The Synthesizer is the highest-agency archetype that reliably keeps consequential action in human hands — the human acts on the synthesized output, rather than the synthesizer itself triggering real-world change. This makes it appropriate for situations where the breadth and depth of information processing needed exceeds human capacity, but where the judgments about what to do must remain human.

The violation to watch for: A Synthesizer that begins taking action based on its own outputs — sending the report it just generated, implementing the recommendations it just produced — has become a hybrid that requires both Synthesizer and Executor governance simultaneously.

→ Full specification: The Synthesizer Archetype

Archetype 5: The Orchestrator

Identity: A system that coordinates the work of multiple agents, tools, or services toward a compound goal — exercising discretion over how work is divided, sequenced, assigned, and integrated.

Defining characteristic: The Orchestrator manages agency. It does not primarily do the work itself; it directs systems that do. Its discretion is coordinative: deciding which capability is needed for which step, how to handle partial failures, when to proceed vs. wait, and how to integrate results. Because it is directing systems that themselves have agency, the Orchestrator's errors propagate multiplicatively.

Typical forms: Multi-agent development pipelines, research orchestration systems, complex workflow engines, systems that coordinate between customer-facing AI and backend services, automated release orchestrators, multi-step business process agents.

What makes this category distinct: The Orchestrator is the only archetype that inherits and multiplies the risk profile of the systems it directs. An Orchestrator managing a set of Executors carries the combined risk of all those Executors plus its own coordination decisions. This is why Orchestrator systems require the most careful governance — not because the Orchestrator itself is particularly powerful, but because it controls what is.

The violation to watch for: An Orchestrator with no escalation path — one that is expected to resolve all ambiguity, all partial failures, and all unexpected situations autonomously — is a system where the entire accumulated agency of the orchestrated systems operates without a reliable human decision point.

→ Full specification: The Orchestrator Archetype

A working taxonomy, not a settled one

Why five? And why these five?

The five archetypes are not arbitrary. They are the regions of design space that emerge from applying two axes — primary act and discretion scope — consistently, and they are currently sufficient for most production agent systems we have encountered. Every system we have classified fits one of the five, or a deliberate composition of them.

But "currently sufficient" is the right honest claim. This is a working taxonomy — held provisionally, tested against new systems, and extended when extension is genuinely warranted. It is not a settled categorization of agency types and shouldn't be read as one.

Where the taxonomy is under most pressure. Three classes of system, all increasingly common as of 2026, do not fit any single archetype:

• Coding agents (Cursor, Cline, Devin, Claude Code, Codex CLI). Within one session they synthesize structured artifacts (Synthesizer), execute against repositories (Executor), and increasingly orchestrate sub-tasks across files and tools (Orchestrator). The system moves between modes within a single session.
• Deep-research agents (long-horizon research with self-directed planning). They synthesize a final report and orchestrate sub-research recursively. The decision tree puts them in Orchestrator; the spec template fits them awkwardly because their sub-agents are often instances of themselves.
• Self-improving / training agents (whose primary act is to evaluate or fine-tune another agent's behavior). The honest reading is that the deployment is two systems with a clean handoff — a meta-system (Synthesizer over the inner agent's outputs) and an inner agent — rather than one system with a missing archetype.

Composition is the answer, not a workaround. Each of these classes pressures the five-archetype frame to extend. The framework's commitment is the opposite: composition is a first-class design surface in this book — one governing archetype, embedded components or modes, declared transitions, cross-mode invariants. The chapter on Composing Archetypes develops the structural surface in full, including a Composition Declaration sub-template fragment for §4 of the canonical spec, and a mode-switching pattern that handles the three pressure-point classes above directly.

Why we do not propose a sixth archetype. Adding a sixth would have to name a primary act that is not inform, execute, enforce, synthesize, or orchestrate. Coding agents and deep-research agents do not have a sixth primary act — they have several of the existing five, used in sequence within a session. Naming the absence of a primary act ("operates in multiple modes") would not give a new archetype any governance profile of its own; it would merely re-name composition while losing the structural clarity of declared transitions and cross-mode invariants. Self-improving agents are honestly two-system deployments, not one-system compositions; documenting them as two systems with a clean handoff is the right move.

The bar for actually adding a sixth. The framework remains open to extension. A genuine sixth archetype must demonstrate a governance profile — agency level, oversight model, reversibility posture, invariant set — that no composition of the existing five provides. Use the Governed Archetype Evolution process. As of 2026, no class of system has met that bar; composition does the work cleanly.

Treat the five as a vocabulary that has earned its keep, not as a taxonomic claim about all possible agents. Treat composition as the structural surface that absorbs the pressure. The book is more useful that way, and so is the framework.

Resulting Context

After applying this pattern:

• Shared vocabulary reduces miscalibration. With named archetypes, discussions about what kind of system is being built become precise. Miscalibration — advisors that drift into executor territory — becomes visible because the category is explicit.
• Governance inherits from category choice. Once an archetype is selected, the minimum oversight model, risk profile, and authority boundaries follow. Teams do not reinvent governance from scratch for each system.
• Risk profiles are transparent. Each archetype carries a canonical risk posture. Teams can reason about whether a particular system matches the risk the organization is accepting, before implementation begins.
• Composition becomes deliberate. When multiple archetypes must be combined in one system, the combination is recognized and named as a design decision, rather than emerging accidentally from feature creep.

Therefore

There are five canonical intent archetypes — Advisor, Executor, Guardian, Synthesizer, and Orchestrator — each defined by its primary act (inform / execute / enforce / synthesize / orchestrate) and its discretion scope. These are not stylistic categories but governance categories: each carries a different minimum oversight model, a different risk posture, and different design requirements. Selecting the correct archetype before writing any spec is the most consequential design decision in agent system development.

Connections

This pattern assumes:

• Prologue — what's at stake when delegating power to agents

This pattern enables:

• Calibrate Agency, Autonomy, Responsibility, Reversibility — tune the four dials within the archetype's defaults
• Four Dimensions of Governance — formal axes for describing archetype properties
• The Archetype Selection Tree — how to choose when the answer isn't obvious
• Individual archetype specifications: Advisor, Executor, Guardian, Synthesizer, Orchestrator
• The Intent Archetype Catalog — the reference implementation of all five

The Advisor Archetype

Part 1 — Frame

"The task of the advisor is not to decide. It is to make deciding possible."

Context

A team is reviewing a Frame artifact. The proposed system "summarizes the meeting and emails the summary to the attendees." The reviewer pauses: "Does the agent send the email, or does the human send it after reviewing the draft?" The room splits — half thinking it's an Advisor (it just produces a summary), half thinking it's an Executor (it sends the email). The answer is whichever the spec commits to in §3 — but the team has to pick. Choosing wrong here doesn't break the system; it breaks the governance, because Advisor and Executor have different oversight models and different reversibility profiles.

This chapter is the canonical reference for the Advisor archetype: what it is, what its defining characteristic is, when to choose it, and the failure modes that recur when teams misclassify a system as Advisor that has crossed into Executor territory.

Identity

Primary Act: Inform
Discretion Scope: Narrow — chooses what information is relevant and how to present it; does not choose what to do

The Advisor surfaces relevant information, analysis, or recommendations to a human decision-maker. It produces outputs for evaluation. It does not act on those outputs. The human act of accepting, rejecting, or acting on the Advisor's output is a hard boundary between the Advisor and consequences.

The Defining Characteristic

The Advisor's defining characteristic is its non-actuation rule: no change to external state, database, service, or system is caused by its output. The Advisor presents; humans execute.

This rule is frequently bent — and every bend is the beginning of misclassification. "It just sends an email to summarize the meeting" is not an Advisor if that email changes something. "It just inserts a draft record" is not an Advisor if drafts flow automatically to production. "It just flags the anomaly in the log" is an Advisor if a human reviews the flag before acting; it is not an Advisor if the flag triggers an automated response.

The test is not the format of the output (a report, a recommendation, a flag, a response). The test is: between this output and any consequential change, is there a required human act?

Typical Forms

An Advisor appears as:

• Retrieval and synthesis: A query assistant that reads from knowledge bases and surfaces relevant context for a human writing a response.
• Diagnostic aid: A system that analyzes error logs and recommends candidate root causes for an engineer to investigate.
• Recommendation engine (human-gated): A system that recommends configuration changes for a human to apply.
• Document generator (pre-human-edit): A system that generates a draft document a human will review and publish.
• Analysis reporter: A system that produces a structured report on the state of a system for a human operator to read.
• Decision support tool: A system that surfaces options with tradeoffs for a human to choose between.

Agency Profile

Why Agency Level 1–2 only: An Advisor at Agency Level 3 or above is a misclassification. Level 3 is "bounded discretion — decides how to accomplish defined tasks within a constrained module scope." If the system is choosing how to accomplish a task with external scope, it is not an Advisor; it is an Executor or Synthesizer in disguise.

Why always fully reversible: The output of an Advisor — a text, a report, a recommendation — can always be disregarded. If discarding the output has no effect, the action is reversible in the fullest sense. The moment disregarding the output is harder than acting on it (e.g., the output was automatically forwarded to another system), the system is no longer Advisor-class.

Invariants

These constraints apply to every Advisor-class system and cannot be weakened by local context, performance requirements, or product convenience:

1. No external writes. The Advisor writes to no external system — no database, no file system, no API endpoint, no message queue — except to a dedicated output channel (dashboard, UI, log file) that is read by humans before any downstream action.

2. No automatic forwarding. The Advisor's output is not automatically consumed by another system that takes action. If the output flows to another system, it must pass through a human confirmation step.

3. Non-rejection has no effect. If a human ignores, dismisses, or never reads the Advisor's output, the world is unchanged. The output has no timeout that triggers an action.

4. Scope declared, not inferred. The Advisor's information scope — what sources it reads, what data it has access to — is declared in the spec and reviewed. It does not expand autonomously.

5. Opinion clearly attributed. Any recommendation, analysis, or conclusion the Advisor produces is clearly labeled as its output — not presented as ground truth. The Advisor presents a perspective; the human makes the determination.

Violation to Watch For: The Soft Executor

The most common way an Advisor fails is by becoming a Soft Executor — a system that accumulates small automatic consequences:

• The summary email is sent to 50 recipients who treat it as authoritative.
• The recommended action is pre-populated in a form that takes two clicks to override.
• The flag appears in a dashboard where the default action is "apply."
• The draft document is automatically submitted unless the reviewer explicitly cancels within 24 hours.

None of these is unambiguously wrong in isolation. Together, they describe a system that has practical agency — its outputs have reliable real-world consequences — even if it was designed as an Advisor.

The diagnostic for this violation: Calculate the compliance rate. If the Advisor's recommendations are accepted more than ~85–90% of the time without substantive modification, ask whether the human review step is a genuine gate or a rubber stamp. This threshold is not arbitrary — it reflects the observation that in functioning advisory relationships (medical second opinions, code review, editorial review), a meaningful fraction of recommendations are modified or rejected by the reviewing human. A compliance rate approaching 100% suggests the human is not exercising independent judgment, which means the system has acquired practical agency without the governance to match. A genuine gate is sometimes rejected. A rubber stamp is an Executor without the governance.

Spec Template Fragment

## Archetype

**Classification:** Advisor  
**Agency Level:** 2 — Contextual (selects and synthesizes relevant information; 
                  applies judgment about what is material)  
**Risk Posture:** Low (output is consumed by human before any action; Medium if 
                  output scope includes sensitive personal or financial data)  
**Oversight Model:** A — Monitoring (output quality reviewed via sampling and 
                  user feedback; alert on anomalous output volume or latency)  
**Reversibility:** R1 — Fully reversible (output can be disregarded with no 
                  external consequence)

## Authorization Boundary

This system is authorized to:
- Read: [list data sources]
- Generate: [types of outputs]
- Write to: [output channel only — specify dashboard, log, UI widget, etc.]

This system is NOT authorized to:
- Write to any system other than [output channel]
- Trigger downstream actions
- Represent its output as authoritative without source citation

## Invariants

1. No output of this system causes an external state change without an 
   intervening human act.
2. This system never writes to [list prohibited targets].
3. All recommendations include a confidence signal and source references.
4. Output ignored/dismissed by the user has no timeout consequence.

Failure Analysis

Connections

Archetype series: Executor →
Governing patterns: Canonical Intent Archetypes · Four Dimensions of Governance · Decision Tree
Composition: Composing Archetypes — Advisor as the advisory layer in a confirm-then-act Executor pattern
SDD: The Canonical Spec Template

The Executor Archetype

Part 1 — Frame

"Power without boundary is not capability. It is liability."

Context

A team is two months into operating an Executor agent. The agent's authorized scope was clear at launch: edit files in the assigned ticket's repo. Six weeks later, an engineer asks the agent to "fix the failing test in the related repo as part of this PR." The agent does it. The change works, the PR merges, the team celebrates the convenience. Two months later, a new engineer notices the cross-repo edit, asks "wait, when did we authorize that?", and discovers the agent's actual operating scope no longer matches its spec.

That is archetype drift in action — the agent didn't break its rules, the team's interpretation of the rules expanded silently. Drift is the dominant Executor failure mode and the reason this archetype carries the highest design-cost-of-misclassification of the five.

This chapter is the canonical reference for the Executor archetype: what its pre-authorization model means, why bounded scope is the load-bearing constraint, the four properties that distinguish a healthy Executor from one drifting into Orchestrator territory, and the worked examples in Scenario 1 (customer-support, governing-Executor) and Scenario 2 (coding-pipeline, Executor with Pattern E mode-switching).

Identity

Primary Act: Execute
Discretion Scope: Bounded — decides how to accomplish a defined task within an authorized scope; does not decide whether the task should be done or what system it should act upon

The Executor takes consequential autonomous action on target systems within a pre-authorized scope. It is the workhorse of agent design — the archetype that actually changes things. It also carries the highest frequency of misdesign in practice, because the line between an authorized scope and an overreach is often invisible until it is crossed.

The Defining Characteristic

The Executor's defining characteristic is its pre-authorization model: the scope of action is defined before the Executor runs, not discovered at runtime. The Executor decides how to execute within a defined space; it does not decide to expand the space.

This is the critical architectural constraint. An Executor that decides at runtime that a particular action is "probably fine" even though it's outside the declared scope has violated the pre-authorization model. This violation is common, locally defensible each time it occurs, and cumulatively catastrophic.

The inverse failure is also real: an Executor whose pre-authorized scope is so tightly bounded that it cannot accomplish its actual purpose will route around its constraints or require constant human intervention. A scope that is too narrow doesn't produce safety — it produces either a blocked system or a system that has learned to frame its overreaches as within-scope.

Typical Forms

• Code automation: Refactoring, test generation, PR creation within a specified codebase scope
• Data pipeline worker: Reads from source, transforms, writes to defined destination tables
• Infrastructure provisioner: Creates/modifies resources within a declared infrastructure scope
• Ticket resolver: Applies a predefined resolution pattern to a qualifying support ticket
• Notification dispatcher: Sends messages to specified channels under defined trigger conditions
• Scheduled maintenance agent: Runs defined cleanup, archival, or rotation tasks on a schedule

Agency Profile

Why Agency Level 3–4: The Executor decides how to accomplish tasks — selecting specific implementation paths, handling edge cases — but within a bounded scope. Agency Level 5 (fully autonomous goal pursuit) is not Executor territory; it is the Orchestrator or a misclassified system.

Why Oversight Model D (default): The pre-authorized scope declaration is the oversight mechanism for the Executor. Every action within scope is pre-approved; every action outside scope triggers the exception gate. This is why the scope declaration is the most important sentence in an Executor spec. A vague scope defeats Oversight Model D entirely.

Invariants

1. Scope is declared, bounded, and specific. The Executor's authorization boundary is written in the spec as an explicit enumeration of authorized targets, actions, and conditions — not as a general description of intent.

2. Out-of-scope actions are halted and surfaced, never silently skipped or quietly extended. When the Executor encounters a situation that its scope doesn't cover, it stops and raises an exception. It does not attempt to handle the situation by reasoning that it's "close enough."

3. Actions are logged at the point of execution. Every consequential action is recorded with: what was done, to what target, under what authorization, at what time. This log is not advisory — it is the accountability record.

4. Irreversible actions require explicit pre-authorization. Any action in R3 or R4 (partially reversible through significant effort, or irreversible) must be explicitly listed in the scope declaration. A general authorization does not cover irreversible actions by implication.

5. Scope does not self-expand. The Executor may not add items to its own authorized scope. Only the governance process for archetype evolution (Governed Archetype Evolution) may expand scope.

The Scope Declaration

The most consequential artifact for an Executor-class system is its scope declaration. Scope declarations fail in two ways:

Too vague: "The system is authorized to manage the codebase." This is not a scope — it is an intent. A scope declaration names specific targets, action types, conditions, and exclusions.

Too focused on happy-path: "The system is authorized to create pull requests in the service-a repository." This is better, but: Can it modify any branch? Can it modify .github? Can it delete branches? Can it push directly? The scope should describe not only what it can do but what it explicitly cannot.

Canonical scope declaration structure:

## Authorization Boundary

**Authorized targets:**
- Repository: `org/service-a`, branches matching `fix/*` and `feat/*`
- No access to: `main`, `release/*`, `.github/`, CI configuration files

**Authorized actions:**
- Create commits on authorized branches
- Open pull requests targeting `main` (not merging)
- Read all files within the repository

**Authorized conditions:**
- Only when triggered by: [specific event type]
- Only when: [precondition]

**Explicitly NOT authorized:**
- Merging pull requests
- Deleting branches
- Modifying workflow files
- Acting on any repository other than `org/service-a`

**Exception gate:** Any action not covered above → halt, log, and surface 
to [designated reviewer] before proceeding.

Violation to Watch For: Scope Creep Through Exception Handling

The most common Executor failure is not an explicit scope expansion — it is exception handling that quietly becomes a capability.

An Executor authorized to create PRs encounters a case where the target branch doesn't exist. It could halt and surface this. Instead, it "helpfully" creates the branch — which is not in its authorized scope. The first time this happens, it looks like good behavior. The tenth time, it is an unreviewed capability.

The fix is not more sophisticated exception handling — it is simpler exception handling. The Executor's default behavior for anything outside its scope is halt-and-surface. Always. The exception gate catches everything that the pre-authorization didn't define.

Spec Template Fragment

## Archetype

**Classification:** Executor  
**Agency Level:** 3 — Bounded (decides how to accomplish defined tasks within 
                  the declared authorization scope)  
**Risk Posture:** Medium (writes to [target]; [reversibility assessment])  
**Oversight Model:** D — Pre-authorized scope + exception gate  
**Reversibility:** R2 — Largely reversible ([specific recovery mechanism, e.g.,
                  git history, soft delete, backup restore])

## Authorization Boundary

[Scope declaration as above]

## Invariants

1. No action outside the declared authorization boundary without exception gate.
2. All actions logged at time of execution with target, action type, and trigger.
3. Irreversible actions [list] require explicit per-execution authorization.
4. This system never expands its own scope.

Failure Analysis

Connections

Archetype series: ← Advisor · Guardian →
Governing patterns: Canonical Intent Archetypes · Four Dimensions of Governance · Decision Tree
Composition: Composing Archetypes — Executor as governing archetype in confirm-then-act and Act+Guardian patterns
Evolution: Governed Archetype Evolution — scope expansion is archetype evolution
SDD: The Canonical Spec Template

The Guardian Archetype

Part 1 — Frame

"The value of a fence is not in the wood. It is in the boundary it marks. Remove the fence and the boundary may persist — or it may not. Build the boundary into the system, and it cannot be removed without a decision."

Context

Day 51 of a customer-support agent's operation. A customer's ticket asks for a $2,400 refund. The agent's Guardian wrap fires before the issue_refund tool can execute, blocking the call because the amount exceeds the cap. The agent enters Advisor mode and emits a clean escalation to the human reviewer.

The Guardian did exactly what it was supposed to do — and the customer ended up getting the refund anyway because the human reviewer misinterpreted the escalation message and processed the refund manually. The Guardian's behavior was correct; the failure was downstream. (See Scenario 1's Evolve chapter for the full incident and its structural amendments.)

That distinction — between "the Guardian failed" and "the failure was downstream of a working Guardian" — is the key diagnostic move for this archetype. A Guardian whose behavior is correct cannot save a system whose escalation handoff is broken; the structural fix lives in §10 (oversight model) plus the runbook, not in the agent.

This chapter is the canonical reference for the Guardian archetype: its negative-first design, its asymmetric authority (strong on prevention, none on initiation), and the four properties that make it trustworthy.

Identity

Primary Act: Enforce
Discretion Scope: Narrow on enforcement, none on exception — the Guardian enforces declared constraints; it does not grant exceptions to itself

The Guardian's purpose is to protect a boundary. It watches for violations of declared invariants — policy boundaries, safety conditions, compliance rules — and acts when those invariants are in danger of being breached. Its action is fundamentally negative: it blocks, halts, or reverses. It does not initiate positive action toward a goal.

This negative-first design is the Guardian's essential characteristic and the source of its trustworthiness.

The Defining Characteristic

The Guardian is distinguished by the asymmetry of its action authority: it has strong authority to prevent or halt; it has no authority to create, modify, or initiate.

An Executor that also validates its own outputs before acting has a Guardian component — but it is still an Executor as the governing archetype. A system whose only autonomous action is to block or halt when a condition is violated is a Guardian.

The test: if the Guardian were removed from the system, positive actions would continue to happen. The Guardian's removal means boundaries are no longer enforced, not that work stops.

Typical Forms

• Policy enforcement layer: Checks that content, actions, or outputs comply with declared organizational policy before they proceed.
• Rate limiter / circuit breaker: Enforces usage or error-rate thresholds; halts when limits are exceeded.
• Compliance validator: Checks that data, code, or configurations meet regulatory or security requirements; blocks non-compliant items.
• Safety check pre-executor: Evaluates a proposed action against declared safety invariants before the Executor is permitted to proceed.
• Access control enforcer: Validates that the requesting agent has authorization for the requested action; denies what isn't authorized.
• Drift detector: Monitors system behavior for deviation from spec; alerts or halts when drift exceeds threshold.

Agency Profile

Why Agency Level 2: The Guardian applies declared rules; it does not make judgment calls about whether the rules are right. If a Guardian is regularly making discretionary exceptions, it has drifted to Agency Level 3 and is no longer operating as a Guardian — it is acting as an Executor with enforcement capability.

Why Oversight Model A + alert: The Guardian's operation is visible by design — every block or halt it generates is an event that should be logged and monitored. Oversight consists of reviewing: (1) that violations are being caught as expected, (2) that the false-positive rate is acceptable, and (3) that the Guardian hasn't been bypassed.

Invariants

1. Constraints are declared, not inferred. The Guardian enforces what the spec says it enforces. It does not block based on its own assessment of what seems like a violation — it applies the declared rule.

2. The Guardian cannot grant exceptions to itself. If a violation is detected, the Guardian halts and surfaces. It does not decide that the violation is acceptable in this particular case. Exception granting is a separate human process.

3. Blocks are logged at the point of enforcement. Every block includes: what was blocked, which invariant was triggered, what the actual observed value was, and when it occurred. Silent blocks are not permitted — they are invisible and unauditable.

4. The Guardian cannot be bypassed by the systems it governs. The Guardian sits in the execution path, not alongside it. An architecture that allows the Executor to route around the Guardian when the Guardian would block it is not a Guardian architecture — it is theater.

5. False positives are surfaced as policy feedback. When a Guardian blocks something that turns out to be legitimate, that event is a policy feedback signal — the declared constraint may be wrong. The resolution is to update the constraint, not to train the Guardian to be more lenient.

The Bypass Problem

The most dangerous Guardian failure is not a false negative (missing a real violation). It is being architects out of the execution path.

Common bypass mechanisms:

• Performance pressure: the Guardian adds latency, so an exception is added for "time-sensitive" operations
• Urgency exceptions: a flag that bypasses the Guardian for high-priority cases, initially intended for emergencies, becomes standard practice
• Environment exemptions: the Guardian is skipped in staging "for convenience," and staging gradually becomes the path for certain production actions
• Interface shortcuts: a new API endpoint is added that doesn't route through the Guardian's check

Each of these seems individually reasonable. Together, they describe a Guardian that exists in the architecture diagram but not in the actual execution path.

The design principle: a Guardian must be in the execution path with no lateral bypass. If bypassing the Guardian is ever the right answer, the constraint the Guardian enforces is wrong — and the resolution is to fix the constraint, not to add a bypass.

Violation to Watch For: The Punitive Guardian

A Guardian that is technically correct but systematically wrong about which things matter will be circumvented — by users, by other systems, and eventually by architectural decisions.

A Guardian that blocks 20% of otherwise valid operations because its declared constraints are too strict is not protecting the system. It is creating pressure for the bypass mechanisms listed above.

The calibration check: Over a rolling period, what percentage of Guardian blocks are overturned by the human exception process? If the answer is high (>10%), the Guardian's constraints are miscalibrated. This threshold is a heuristic, not a universal constant — the principle is that a Guardian whose blocks are routinely overridden is not enforcing the organization's actual intent. The right threshold for your context depends on domain: a safety-critical Guardian might warrant investigation at >2%, while a content-formatting Guardian might tolerate >15%. The diagnostic question remains the same: are the constraints the right constraints? The spec needs to be fixed, not the Guardian's strictness. The Guardian is supposed to enforce what the spec says; if the spec says the wrong things, that is a spec problem.

Spec Template Fragment

## Archetype

**Classification:** Guardian  
**Agency Level:** 2 — Declarative enforcement (applies specified rules; 
                  does not make discretionary exceptions)  
**Risk Posture:** Medium (enforces [specific constraints]; false positives 
                  impact [volume/type of legitimate operations])  
**Oversight Model:** A — Monitoring with alert (every block logged; alert 
                  on block rate >X% or on zero-block periods exceeding Y days)  
**Reversibility:** R1 — Fully reversible (blocks/halts only; no state mutation)

## Enforcement Boundary

**Enforced invariants:**
1. [Specific constraint with specific threshold or condition]
2. [Specific constraint]

**Enforcement action on violation:**
- Block: [what is stopped]
- Log: [what is recorded]
- Surface: [where the block notification goes, and to whom]

**Explicitly NOT within enforcement scope:**
- [What the Guardian does not check or enforce]

**Exception process:**
- Who can override a Guardian block: [role/process]
- Override requires: [documentation / approval]
- Override is logged: [yes — all overrides recorded with reason]

Failure Analysis

Connections

Archetype series: ← Executor · Synthesizer →
Governing patterns: Canonical Intent Archetypes · Four Dimensions of Governance · Decision Tree
Composition: Composing Archetypes — Guardian as embedded enforcement layer in Executor systems
SDD: The Canonical Spec Template

The Synthesizer Archetype

Part 1 — Frame

"The value of synthesis is not the aggregation. Any database can aggregate. The value is the judgment about what to include, what matters, and how to present it so the right decision becomes clear."

Context

A docs-team's internal Q&A agent answers a question about service deployment with a confident summary citing three internal docs. The asker accepts the answer and acts on it. The summary turns out to be technically grounded — every citation contains the claim — but the cited passages, read in their full context, complicated rather than supported the answer. The Synthesizer satisfied the citation-grounding check but failed the understanding check the citation discipline was supposed to enable.

This is citation theater, the Synthesizer-specific anti-pattern in the Discipline-Health Audit. It is the failure mode every Synthesizer needs to defend against — because the agent has learned to satisfy the check at the level the check operates on, without the citation actually grounding the asker's understanding. The structural fix is a contextual-completeness score plus a sample-audit cadence; the prompt patch ("read more context before citing") does not compound. Scenario 3 (Internal docs Q&A) is the worked example.

This chapter is the canonical reference for the Synthesizer archetype: its multi-source compositional judgment, why that judgment is real discretion that must be bounded, and the four properties that distinguish a Synthesizer from a glorified retrieval pipeline.

Identity

Primary Act: Compose
Discretion Scope: Moderate — selects what to include, how to structure, and what emphasis to apply; does not act on the produced artifact

The Synthesizer aggregates information from multiple sources, applies compositional judgment — deciding relevance, structure, and emphasis — and produces a coherent artifact for human consumption or downstream use. It acts on information, not on external systems. Like the Advisor, it produces rather than executes. Unlike the Advisor, it operates across multiple sources and applies meaningful compositional judgment.

The Defining Characteristic

The Synthesizer's defining characteristic is its multi-source compositional judgment: it is not merely retrieving and presenting a single source, nor executing a transformation with a defined mapping. It is deciding across sources what matters and assembling it into a coherent whole.

This is why the Synthesizer has a higher agency level than the Advisor. The Synthesizer exercises genuine judgment about what to include, what to omit, how to weight competing signals, and how to structure the output for clarity. That judgment is real discretion — and it must be bounded.

The boundary: the Synthesizer's discretion applies to the artifact it produces, not to what happens to the artifact. The Synthesizer does not decide whether the artifact gets published, deployed, or acted upon.

Typical Forms

• Research synthesizer: Reads multiple sources (documents, databases, search results), produces a structured summary or analysis for a human researcher.
• Status report generator: Aggregates data from multiple systems (metrics, tickets, alerts, deployments), produces a coherent status digest for a human reviewer.
• Code review synopsis: Reads multiple PRs, issues, or test results, produces a prioritized synthesis for an engineering lead.
• Risk assessment composer: Reads from multiple risk signals (logs, dependency data, policy checks), produces a composed risk profile for a security reviewer.
• Competitive intelligence report: Aggregates from multiple market sources, produces a structured briefing for a human strategist.
• Meeting notes synthesizer: Processes multiple inputs (transcript, agenda, action items), produces a structured meeting record for human distribution.

Agency Profile

Why Agency Level 3 (not 1–2 like the Advisor): The Synthesizer exercises meaningful compositional judgment — it decides what is relevant across sources, which signals outweigh others. This is not retrieval; it is editorial. Agency Level 3 is appropriate for editorial judgment within a bounded domain.

Why Risk Posture Low to Medium: The Synthesizer's direct output is an artifact for human consumption. The risk is in the quality and accuracy of the synthesis — an incorrect or misleading synthesis can cause a human to make a poor decision. This is real risk, but it is mediated by human judgment. The risk escalates to Medium when the synthesis domain is high-stakes (medical, financial, security), because the errors are hard to detect and the downstream decisions are consequential.

Invariants

1. The artifact is produced for human evaluation, not for automated consumption. If the Synthesizer's output automatically feeds another system that takes action, the composition has changed — the Synthesizer is now embedded in an Executor or Orchestrator, and its governance requirements have escalated.

2. Source references are preserved. The Synthesizer does not strip attribution. Any factual claim in the synthesized artifact is traceable to a source, either inline or in an appendix. A synthesis that cannot be verified is an assertion, not a synthesis.

3. The scope of sources is declared. The Synthesizer does not autonomously expand what it reads. The declared sources — databases, APIs, document collections — are specified in the spec and reviewed. Reaching outside declared sources is a constraint violation.

4. Compositional criteria are specified. The spec declares what the Synthesizer prioritizes: recency? relevance score? specific signal types? These criteria are not left to the system's general intelligence. They are declared, so the synthesis can be audited against them.

5. Uncertainty is surfaced, not hidden. When the Synthesizer cannot confidently resolve a question from its sources — conflicting data, insufficient coverage — it says so. It does not synthesize a confident answer from insufficient evidence.

The Quality Problem

The most common failure of a Synthesizer-class system is not scope violation — it is quality degradation that erodes trust and, eventually, oversight.

When a Synthesizer is trusted, humans read its output carefully and validate against sources. When a Synthesizer is highly trusted, humans skim it and assume it's right. When a Synthesizer has been wrong occasionally without anyone noticing, it is operating in the most dangerous condition: it produces confident output, humans trust it implicitly, and errors compound.

The design principle: build skepticism triggers into the synthesis itself. Explicit confidence signals, flagged uncertainties, and surface-level consistency checks in the output are not signs of weakness — they are the mechanism by which human judgment remains engaged.

A synthesis that always looks equally confident regardless of source quality, coverage gaps, or conflicting signals is training its readers to stop thinking. That is a design failure.

Synthesizer vs. Advisor (The Distinction)

An Advisor answers: "Here is the relevant information."
A Synthesizer answers: "Here is my assessment, assembled from these sources."

The "my assessment" is the difference. Agency Level 3 names that judgment explicitly, so it can be scoped and governed.

Spec Template Fragment

## Archetype

**Classification:** Synthesizer  
**Agency Level:** 3 — Editorial (exercises compositional judgment about 
                  relevance, structure, and emphasis across declared sources)  
**Risk Posture:** Low / Medium (produces artifact for human evaluation; 
                  risk scales with stakes of downstream decisions)  
**Oversight Model:** B — Periodic review (output quality reviewed on cadence 
                  [weekly/per-run]; alert on anomalous output patterns)  
**Reversibility:** R1 — Fully reversible (artifact can be disregarded; 
                  no external state mutation)

## Source Scope

**Authorized sources:**
- [Source 1]: [access level — read only, specific tables/endpoints]
- [Source 2]: [access level]

**Explicitly NOT in scope:**
- [Excluded sources]

## Compositional Criteria

Priority signals:
1. [Signal type] — weighted [high/medium/low]
2. [Signal type] — weighted [high/medium/low]

Conflict resolution: [how conflicting signals are handled]
Confidence threshold: [when uncertainty must be stated rather than resolved]

## Invariants

1. All factual claims in output include source attribution.
2. Source scope does not expand autonomously.
3. Conflicting or insufficient signals are surfaced, not silently resolved.
4. Output is produced for [specific consumer]; automated downstream consumption 
   requires separate Executor governance.

Failure Analysis

Connections

Archetype series: ← Guardian · Orchestrator →
Governing patterns: Canonical Intent Archetypes · Four Dimensions of Governance · Decision Tree
Composition: Composing Archetypes — Synthesizer + Executor composition in compose-then-publish patterns
SDD: The Canonical Spec Template

The Orchestrator Archetype

Part 1 — Frame

"The conductor does not play the instruments. The conductor is responsible for everything that is played."

Context

A team is debating whether their multi-step agent — a Frame mode that reads the codebase, a Plan mode that proposes changes, an Implement mode that writes the code, a Review mode that opens the PR — is an Orchestrator coordinating four sub-agents, or an Executor with mode-switching composition. The distinction matters: Orchestrator implies the agent dispatches other agents, with all the inter-agent state and accountability that follows. Executor with Pattern E mode-switching implies the agent operates in different modes against the same tool manifest within one session.

The right answer for a coding agent is usually the latter; framing it as an Orchestrator inflates the governance surface without adding structure. (See Scenario 2's Frame chapter for the worked example, where the team explicitly considers and rejects the Orchestrator framing.)

The Orchestrator is the highest-agency archetype, and the most-misused. Most systems that feel like Orchestrators are actually mode-switching Executors with accidental complexity. This chapter is the canonical reference for when you genuinely need an Orchestrator (when you really are coordinating other agents, not your own modes), what compositional accountability means, and why the inflation of governance is the design cost of misclassification in this direction.

Identity

Primary Act: Coordinate
Discretion Scope: Strategic — decides which agents to invoke, in what order, with what inputs, and how to handle their outputs; does not perform the work itself

The Orchestrator is the highest-agency archetype. It allocates work across agents, tools, and services; manages inter-agent state and coordination; handles failure and retry at the system level; and is accountable for the entire composed operation. Its power is multiplied by every agent it coordinates. So is its risk.

The Defining Characteristic

The Orchestrator's defining characteristic is its compositional accountability: it is responsible not only for its own decisions but for the quality and scope of the work done by every agent it directs.

An Orchestrator that dispatches an Executor to take action in production is, in the relevant sense, the author of that action. The Executor acted within its spec; the Orchestrator authorized the invocation. The accountability chain runs through the Orchestrator to its human principal.

This is why the Orchestrator carries the highest default governance tier of any archetype. It is not because the Orchestrator does dangerous things directly — it is because it can authorize other systems to do dangerous things, at scale, in parallel.

Typical Forms

• Pipeline coordinator: Manages a multi-step workflow across retrieval, transformation, validation, and execution agents.
• Agentic customer support system: Coordinates a Synthesizer (retrieval/analysis), an Executor (ticket resolution), and a Guardian (policy compliance) to handle a support scenario end-to-end.
• Code change pipeline: Routes a specification through analysis, implementation, test, review, and merge agents.
• Remediation coordinator: Detects an alert, diagnoses the issue, selects a remediation agent, monitors execution, and reports outcome.
• Multi-source research pipeline: Dispatches retrieval agents to multiple sources, coordinates synthesis, routes to approval.
• Infrastructure change coordinator: Validates a change request, coordinates provisioning agents, monitors for completion, handles rollback on failure.

Agency Profile

Why Agency Level 4–5: The Orchestrator exercises goal-directed multi-step discretion (Level 4) or fully autonomous goal decomposition and execution (Level 5). An agent coordinating others with less than Level 4 agency is either not really an Orchestrator (it's an Executor with a complex pipeline), or it has been under-classified.

Why Risk Posture High to Critical: The Orchestrator amplifies risk. A single bad decision by an Orchestrator can cause N downstream agents to take N concurrent wrong actions. The impact scope is multiplied; the detectability window may be narrow if agents act in parallel. High is the minimum; Critical applies when the downstream agents can take irreversible actions.

Why Oversight Model C minimum: An Orchestrator without an output gate is an Orchestrator that can authorize consequential multi-agent actions without any checkpoint. Oversight Model D (pre-authorized scope) may be appropriate for well-defined, narrow Orchestrators with mature operational records — but this requires formal justification and is not the default.

Invariants

1. The Orchestrator's task contract is declared. The spec describes: what goal the Orchestrator is pursuing, what agents it may invoke, what decisions it may make autonomously, and what decisions require escalation.

2. Sub-agent authorization boundaries are respected. The Orchestrator invokes agents within their declared specs. It does not pass inputs that circumvent sub-agent constraints. It does not instruct agents to act outside their authorization boundaries.

3. Goal decomposition is bounded. The Orchestrator decomposes a declared goal into tasks. It does not autonomously expand the goal definition — if completing the declared goal requires actions that weren't anticipated, it surfaces this rather than expanding scope.

4. Failure is handled at the system level, not silently. When a sub-agent fails, the Orchestrator's failure handling is declared in the spec. The options are: retry, fallback, halt-and-surface. "Silently skip and continue" is not a valid option for any failure that affects the correctness of the outcome.

5. Compound irreversibility requires compound authorization. If an Orchestrator directs multiple agents to take R3 or R4 actions, the collective irreversibility is higher than any individual action. The spec must explicitly address this compound risk and specify additional authorization requirements.

The Accountability Problem

The Orchestrator is the archetype most likely to diffuse accountability to the point of invisibility.

In a multi-agent system, when something goes wrong, the question "who is responsible?" becomes complex: the sub-agent that took the action? The Orchestrator that authorized it? The spec author who defined the authorization boundary? The platform that ran the agents?

The answer is: all of them, in different senses. But the Orchestrator is the operational accountability point — the place where the decision to act was made and where the compound scope was assembled. The person who approved the Orchestrator spec is the person who authorized everything the Orchestrator could do.

This is why the Orchestrator's spec must answer four questions that other archetypes can sometimes leave implicit:

1. What can this system do?
2. What can it NOT do?
3. What happens when something goes wrong?
4. Who is accountable for this operating?

These are not bureaucratic questions. They are the questions an on-call engineer needs to answer in the first five minutes of an incident. The Orchestrator spec is the incident response playbook.

Sub-Agent Typing

Every agent the Orchestrator may invoke should be typed in the spec. This is not optional:

## Sub-Agent Inventory

| Agent | Archetype | Authorization Scope | Failure Behavior |
|-------|-----------|---------------------|------------------|
| Retrieval agent | Advisor | Reads [source A, source B] — no writes | Retry 3x, then surface |
| Analysis agent | Synthesizer | Compositional analysis of retrieval output | Surface if confidence < threshold |
| Action agent | Executor | [Specific pre-authorized scope] | Halt-and-surface, no retry |
| Validation agent | Guardian | Enforces [specific constraints] | Block escalates to human |

An Orchestrator spec that says "it coordinates various agents as needed" is not a spec. It is an authorization for an undefined system to take undefined actions. No one should approve that spec, and no one should build that system.

Spec Template Fragment

## Archetype

**Classification:** Orchestrator  
**Agency Level:** 4 — Multi-step goal-directed (decomposes a declared goal 
                  into tasks, coordinates agents, manages inter-agent state)  
**Risk Posture:** High (coordinates [N agents]; maximum reachable impact: 
                  [describe compound worst case])  
**Oversight Model:** C — Output gate (each complete orchestration cycle 
                  produces a structured output reviewed before any downstream 
                  consequential action; or: specific checkpoints at [stages])  
**Reversibility:** R2 — Largely reversible (sub-agent actions within 
                  [reversibility window]; compound irreversibility risk: 
                  [assessment])

## Task Contract

**Goal this Orchestrator pursues:** [Specific, bounded goal statement]

**Goal boundaries (what it does NOT pursue):**
- [Explicit exclusion 1]
- [Explicit exclusion 2]

## Sub-Agent Inventory

[Table as above]

## Decision Authority

**Decides autonomously:**
- [Routing decision 1]
- [Retry decision]

**Escalates to human:**
- [Any situation that falls outside declared task contract]
- [Any compound irreversible action exceeding threshold]
- [Any sub-agent failure that cannot be resolved by retry/fallback]

## Failure Handling

[Declared failure response for each sub-agent type]

Failure Analysis

Connections

Archetype series: ← Synthesizer · Begin Part 2 (The Spec) →
Governing patterns: Canonical Intent Archetypes · Four Dimensions of Governance · Decision Tree
Composition: Composing Archetypes — Orchestrator with typed sub-agents (Pattern C)
Evolution: Governed Archetype Evolution — Orchestrators are the most common subject of scope drift
SDD: The Canonical Spec Template

The five archetype deep dives are complete. Continue to Part 2 (The Spec).

Four Dimensions of Governance

Part 1 — Frame

"A compass gives you four directions. Navigation gives you precision. Dimensions give you the ability to place any system on the map — not just name its rough category."

Context

You know the five archetypes. Now you need to characterize them precisely — and more importantly, to characterize any real system in a way that reveals its design requirements clearly.

This pattern introduces the four formal dimensions along which archetypes (and systems) are described: Agency, Risk, Oversight, and Reversibility. Together these four dimensions form the governance profile of any agent system.

A note on the two "four-dimension" frames in this book. The framework's calibration layer (Calibrate Agency, Autonomy, Responsibility, Reversibility) names four dials a spec author tunes per system: agency, autonomy, responsibility, reversibility. This chapter's governance profile names four dimensions an archetype declares as a published design contract: agency, risk, oversight, reversibility. The two frames overlap on agency and reversibility and diverge on the middle pair. Autonomy and responsibility (calibration) are inputs the spec author sets; risk and oversight (governance) are outputs the archetype publishes. Read the calibration chapter to set the dials; read this chapter to read off the resulting governance contract. The paper's canonical statement of the calibration dimensions uses the calibration framing (agency, autonomy, responsibility, reversibility); this chapter is the book-only governance encoding.

This pattern is the conceptual bridge between archetype identity (the archetype catalog) and the practical decision tools (the Archetype Selection Tree). It is also the vocabulary used in every individual archetype specification and in the Archetype Catalog.

The Problem

Naming an archetype is necessary but not sufficient for design. "This is an Executor" tells you the category. It does not tell you:

• How much autonomous discretion this particular Executor should have
• What the oversight cadence should be
• How to calibrate the spec's constraint section
• Whether a human approval gate is required before certain actions

Two systems are both Executors: a CI/CD pipeline that runs tests and a financial transaction processing agent. The category is the same. The governance requirements are radically different. The dimensions are the tool for expressing that difference precisely.

Forces

• Category vs. detail. The archetype names the kind of system, but two systems of the same type can differ drastically in their oversight requirements. Yet specifying every system from first principles recreates the classification problem at every decision point.
• Standardization vs. customization. Systems need enough behavioral similarity that the archetype label carries meaning. Yet every real system differs in risk, scope, and consequence.
• Expressiveness vs. learnability. Four dimensions can express the nuance needed to distinguish one Executor from another. Adding more multiplies complexity; removing dimensions loses important distinctions.
• Metric-driven vs. judgment-based. Dimensions should be assessable by analyzing the system itself. Yet some dimensions require subjective assessment. The framework must accommodate both.

The Solution

The Four Dimensions

Dimension 1: Agency Level

Definition: The degree of discretion the system is authorized to exercise — the range of decisions it can make without human input.

Agency is described on a five-point scale:

Most production systems should operate at levels 2–4. Level 5 requires exceptional governance. Level 1 is appropriate for pure advisors.

Design implication: Each increment in agency level upward should be matched with a corresponding increment in constraint specificity and oversight investment. Agency level and constraint density must grow together.

Dimension 2: Risk Posture

Definition: The potential for system outcomes to cause harm — to users, to the organization, to third parties, or to data integrity — if the system fails, errs, or is misused.

Risk is assessed across three factors:

Impact scope: How many people or systems are affected if the system produces a wrong output?

• Narrow — affects one user or one isolated process
• Broad — affects many users, critical data, or inter-system state

Severity: How bad is the worst plausible bad outcome?

• Low — incorrect output that can be ignored or corrected easily
• High — output that causes financial, reputational, legal, or safety harm

Detectability: How quickly will a problem be noticed?

• Fast — problem surfaces in seconds or minutes (test failure, UI error, metric alert)
• Slow — problem surfaces over days or weeks (subtle bias, gradual data degradation)

Composite risk label used in archetype profiles:

• Low — Narrow + Low + Fast
• Medium — Mixed profile; requires explicit assessment
• High — Broad or High severity or Slow detectability present
• Critical — Broad + High + Slow; full governance tier required

Dimension 3: Oversight Model

Definition: The required structure of human involvement in reviewing, correcting, or authorizing the system's behavior.

Four oversight models cover the space of practical agent systems:

Model A — Monitoring Human attention is triggered by anomalies or metrics, not by every output. The system runs continuously; humans review exceptions. Appropriate for: low-risk, high-reversibility systems with automated failure detection.

Requirements: Defined alert thresholds, automated anomaly detection, clear escalation path, designated reviewer.

Model B — Periodic Review Human reviews a sample of outputs on a scheduled cadence. Not real-time. Appropriate for: medium-risk systems with medium reversibility where continuous monitoring would be overwhelming but some regular human eyes are needed.

Requirements: Defined sample size and sampling method, review schedule, review log, owner responsible for each scheduled review.

Model C — Output Gate Human reviews and approves (or rejects) before any output is released or acted upon. Real-time review. Appropriate for: high-risk systems, irreversible outputs, or systems with broad impact.

Requirements: Review queue, defined reviewer, maximum review latency, clear approve/reject criteria, escalation for ambiguous cases.

Model D — Pre-authorized Scope + Exception Gate Human defines the authorized scope in advance (the spec's constraint section). The system acts within scope without per-output review. Except: any action outside the pre-authorized scope must surface for human decision before executing.

Requirements: Precise scope definition in spec, reliable boundary detection, exception escalation path, logs of all scope-boundary events for review.

Model D is the most powerful production model — it enables high-velocity autonomous execution while preserving human authority at the boundaries. It is also the model that fails most expensively when scope definition is imprecise.

Dimension 4: Reversibility Posture

Definition: The inherent reversibility profile of this class of system's actions, and the minimum design requirements that follow.

Building on the reversibility spectrum from Calibrate Agency, Autonomy, Responsibility, Reversibility, each archetype carries a default reversibility posture:

The reversibility posture of a specific system may differ from the archetype's default if the implementation makes otherwise-irreversible actions reversible (e.g., through soft deletes, draft queues, or paper-journal patterns).

The Canonical Dimension Profiles

Applying all four dimensions to the five archetypes produces their canonical governance profiles:

A note on the Guardian's agency level. The Guardian shares a numeric agency level (2) with an Advisor at level 2, but the kind of discretion is qualitatively different. An Advisor at level 2 chooses among pre-enumerated presentation options — its discretion is compositional. A Guardian at level 2 exercises veto discretion: the authority to block, halt, or reject actions that violate constraints. Veto power is a categorically different capability from selection among options, even though both sit at level 2 on the numeric scale. The label "veto only" is essential — it signals that the Guardian's agency is directionally negative (it prevents, rather than initiates) and narrower than a general level-2 system. | Synthesizer | 3 | Low–Medium | Periodic review or Output gate | Largely reversible | | Orchestrator | 4–5 | High | Model C or D + escalation | Irreversible (coordinates irreversible agents) |

These are minimums. A specific implementation may require stronger governance than the canonical profile if its risk posture, impact scope, or reversibility profile is elevated above the archetype default.

Using Dimensions to Validate Spec Design

The four dimensions are not just descriptive — they are diagnostic. When reviewing a spec, use the dimensions as a checklist:

Agency check: Is the agency level claimed in the spec consistent with the archetype? A system claiming Executor designation but with Agency Level 5 has miscategorized itself.

Risk check: Have all three risk factors (impact scope, severity, detectability) been explicitly assessed? An unassessed risk is an accepted risk — often unknowingly.

Oversight check: Does the oversight model described in the spec match the minimum requirement for this archetype and risk level? "The team will review occasionally" is not a Model B — it is the absence of an oversight model.

Reversibility check: For each action the system can take, has the reversibility been assessed? For irreversible actions: is there a human approval gate explicitly in the spec?

A spec that fails any of these checks is not ready for agent execution.

Resulting Context

After applying this pattern:

• Governance profiles become diagnostic. The four dimensions make it visible when a system is under-governed or over-governed. Mismatch becomes discussable because the dimensions are explicit.
• Constraints flow from structure. Once a system's dimensions are established, the required constraints follow. The spec's constraint density can be calibrated to the dimensions.
• Risk is owned explicitly. By assessing all four dimensions, the organization can no longer ignore risk quietly.
• Evolution becomes checkable. When a system's dimensions change, the change is visible and auditable.

Therefore

The four archetype dimensions — Agency Level, Risk Posture, Oversight Model, and Reversibility Posture — together form the governance profile of any agent system. They transform archetype names from categories into design specifications: they tell you what the spec must contain, what the oversight structure must look like, and what design requirements cannot be waived. Every serious spec review should evaluate all four.

Connections

This pattern assumes:

• The Five Archetypes
• Calibrate Agency, Autonomy, Responsibility, Reversibility

This pattern enables:

• The Archetype Selection Tree — putting the dimensions to practical use
• The Canonical Spec Template — the oversight and constraint sections
• The Intent Archetype Catalog — full dimension profiles per archetype
• Proportional Oversight — implementing the four oversight models

The Archetype Selection Tree

Part 1 — Frame

"The most expensive design decision is not the one that costs the most to make. It is the one you made without realizing you were making it."

Context

You are at the beginning of specifying an agent system — or you are reviewing a system that already exists and wondering if it was designed coherently. You need a practical tool for selecting (or validating) the correct archetype.

This pattern provides the decision tree. It is meant to be used — in design sessions, in spec reviews, when onboarding a new system. It is deliberately brief at the top, expanding into nuance as needed.

This pattern assumes The Five Archetypes and Four Dimensions of Governance.

The Problem

The five archetypes describe stable categories, but real systems don't announce what they are. A brief description — "it automates customer support" — does not tell you which archetype applies. "It helps users find answers" could be an Advisor. "It resolves tickets autonomously" could be an Executor. "It checks that responses comply with policy" could be a Guardian.

The wrong archetype selection is not just an organizational mistake. It produces tangible design failures: oversight models that don't fit the actual risk, capability boundaries that don't match the real action space, invariants that weren't designed for the system's true function.

A decision tree that is fast to use and hard to game is the antidote to archetype drift before it begins.

Forces

• Speed vs. precision. A decision tree must be fast enough to use in active development. Yet speed must not sacrifice correctness \u2014 misclassification early leads to wrong governance from the start.
• Generality vs. ambiguity. Some questions are clear-cut. Others are genuinely ambiguous. The tree must resolve ambiguity without requiring extended conversation.
• Objective inquiry vs. contextual judgment. The earliest questions should be observable facts about the system. Yet eventually judgment is required. The tree must bridge from observation to judgment.
• Reusability vs. customization. The tree should be the same for every organization. Yet some organizations have specific concerns. The tree must be both standard and customizable.

The Solution

The Primary Decision Tree

Apply these questions in order. Stop at the first match.

┌─────────────────────────────────────────────────────────────────────┐
│ QUESTION 1: Does this system take any consequential action           │
│ in the world — writing data, sending messages, calling APIs,         │
│ executing code, modifying state — without a human act between        │
│ its output and the consequence?                                      │
└─────────────────────────────────────────────────────────────────────┘
         │
         ▼
    NO   ──────────────────────────────────────────► ADVISOR
         
    YES  ──────────────────────────────────────────► continue to Q2
         
┌─────────────────────────────────────────────────────────────────────┐
│ QUESTION 2: Is the system's PRIMARY purpose to protect a boundary,   │
│ enforce a constraint, or prevent a violation — rather than to        │
│ accomplish a positive goal?                                          │
└─────────────────────────────────────────────────────────────────────┘
         │
    YES  ──────────────────────────────────────────► GUARDIAN
         
    NO   ──────────────────────────────────────────► continue to Q3
         
┌─────────────────────────────────────────────────────────────────────┐
│ QUESTION 3: Does this system's work fundamentally involve            │
│ directing, coordinating, or allocating work across OTHER agents,     │
│ tools, or services — rather than doing the work itself?              │
└─────────────────────────────────────────────────────────────────────┘
         │
    YES  ──────────────────────────────────────────► ORCHESTRATOR
         
    NO   ──────────────────────────────────────────► continue to Q4
         
┌─────────────────────────────────────────────────────────────────────┐
│ QUESTION 4: Is this system's primary output a synthesized artifact   │
│ — a summary, report, combined analysis, or composed document —       │
│ rather than an action taken on a target system or service?           │
└─────────────────────────────────────────────────────────────────────┘
         │
    YES  ──────────────────────────────────────────► SYNTHESIZER
         
    NO   ──────────────────────────────────────────► EXECUTOR

Resolving Ambiguity at Each Question

Q1 — Ambiguous cases:

"It writes to a staging environment, not production." — The staging write is still a consequential action; the system is not an Advisor. Proceed to Q2.

"It shows users what it would do before doing it." — If the preview-then-confirm pattern includes a human confirmation step before execution, this can be Advisor-class for the advisory phase, and Executor-class for the execution phase. This is a composition. See Composing Archetypes.

"It only writes to a scratch file for the user to review." — Review carefully. If the user's review is a genuine gate (they can reject the output and nothing happens), this is Advisor-class with a draft artifact. If the output typically gets applied without substantive review, treat as Executor.

Q2 — Ambiguous cases:

"It validates AND fixes compliance issues." — This system has a Guardian component (enforcing the constraint) and an Executor component (taking remediation action). This is a composition — it needs both governance models. See Composing Archetypes.

"It enforces rate limits but can also provision resources." — Rate limit enforcement is Guardian behavior. Resource provisioning is Executor behavior. These are separate components with separate governance requirements. Do not blend into one archetype.

Q3 — Ambiguous cases:

"It calls one external API." — Calling one external service is not orchestration in the archetype sense. Orchestration means systematically allocating work across agents or services with coordination logic. A single API call is an Executor capability.

"It has a pipeline with three steps." — A linear pipeline is not necessarily an Orchestrator. If the steps are always the same and there is no conditional routing, parallel dispatch, or inter-agent coordination, this is an Executor with multiple actions. If there is dynamic routing, parallelism, or inter-agent state management, it is an Orchestrator.

Q4 — Distinguishing Synthesizer from Executor:

The key test: does the system produce an artifact for humans to evaluate (Synthesizer) or produce a change in a target system (Executor)?

A system that generates a structured report: Synthesizer.
A system that generates a structured report and publishes it to the company portal: Synthesizer + Executor composition.
A system that reads multiple APIs and writes the combined result to a database: Executor (the primary act is writing state, not producing an artifact for review).

The Risk Override

After selecting an archetype, apply one override check:

If the system's consequence-of-failure is Critical (broad impact, high severity, or slow detectability), document that explicitly and escalate the governance tier — regardless of archetype category.

An Advisor system that advises millions of people on medical decisions is still an Advisor by structure, but it carries Critical risk by impact scope. It needs Oversight Model C (output gate) even though most Advisors use Monitoring. The archetype defines the minimum. Risk overrides the minimum upward.

Archetype Profile Card (Quick Reference)

Documenting the Selection

Every spec should include an explicit archetype declaration. This is not bureaucracy — it is a design decision that the reader needs to understand quickly, and that the agent needs as architectural context.

Canonical form in a spec:

## Archetype

**Classification:** Executor  
**Agency Level:** 3 — Bounded (decides how to accomplish defined tasks 
                  within a constrained module scope)  
**Risk Posture:** Medium (impacts production codebase; partially reversible 
                  via git history)  
**Oversight Model:** D — Pre-authorized scope with exception gate  
**Reversibility:** Partially reversible (commits can be reverted; PR creation 
                  is observable; no direct production writes)

One paragraph. Written before behavioral specification begins. Reviewed by the same person who would authorize the archetype definition itself.

Resulting Context

After applying this pattern:

• Classification becomes observable. A decision tree grounded in observable questions makes the archetype classification verifiable by examining the system, rather than debating its intent.
• Risk overrides are explicit. The tree acknowledges that risk can require a governance tier higher than the archetype minimum. The override is named and documented.
• Misclassification risk is reduced. By starting with the most discriminating question and proceeding downward, the tree minimizes misclassification.
• Newcomers can classify consistently. With an explicit decision tree, a new team member can classify a system using the same reasoning as an experienced architect.

Therefore

Archetype selection follows a four-question decision tree: Does it act? Does it primarily enforce? Does it coordinate agents? Does it produce an artifact? The first three questions determine whether you have a Guardian, Orchestrator, or need to distinguish Synthesizer from Executor. Nothing should be specced until the archetype is declared and reviewed. The declaration is the most consequential sentence in the spec.

Connections

This pattern assumes:

• The Five Archetypes
• Four Dimensions of Governance

This pattern enables:

• Archetype Composition — when one archetype isn't enough
• The Canonical Spec Template — the archetype declaration section
• SpecKit — SpecKit's archetype integration

Archetype Composition

Part 1 — Frame

"A city is not a simple object but a complex of objects that arise together in a particular way. The parts are not less important than the whole — they are the whole."
— Christopher Alexander, The Timeless Way of Building

Context

A team is reviewing the spec for an Executor agent. The reviewer points at §11: "this part where the agent checks its own output before sending — that's a Guardian behavior. And §10's escalation flow looks like an Advisor handoff. Are we doing composition by accident, or composition by design?" The room goes quiet. The team had committed to Executor in Frame, then quietly accumulated Guardian and Advisor behaviors as the spec evolved, without ever declaring the composition. The result was a system whose actual shape was not the shape its spec advertised — the most-common cause of the composition by accident anti-pattern the Discipline-Health Audit catches.

You have assigned an archetype to a system. You know it is, say, an Executor — it takes bounded, pre-authorized action. But the system also has a component that checks its own outputs before applying them, another that reports results to a dashboard, and a third that refuses to act if a given condition is violated.

Real systems are not atomic. They are compositions. The question is how to manage that composition without losing the clarity the archetype gave you.

This pattern assumes The Five Archetypes, Four Dimensions of Governance, and The Archetype Selection Tree.

The Problem

Two failure modes emerge when multiple functional concerns are present in one system:

Failure Mode 1: Archetype blending. The system is classified as "mostly an Executor with some Advisor-like features," and a single governance model is applied to the whole. The embedded advisory component gets Executor-level constraints (too strict for its risk) or the Executor component gets Advisor-level oversight (too loose for its risk). Neither is correct.

Failure Mode 2: Archetype fragmentation. Every sub-function is classified separately, producing a sprawling multi-archetype design document that no one reads, with overlapping and sometimes contradictory governance requirements. The boundaries between sub-components are not enforced.

The first failure produces incorrect governance. The second produces unreadable governance. Both eventually produce the same outcome: a system that is harder to reason about than if no archetype framework had been used at all.

There is a structural solution — and it requires treating composition as a first-class design operation.

Forces

• Atomicity vs. reality. The five archetypes describe atomic types, but real systems combine multiple functions. Forcing one archetype onto a multi-archetype system either miscategorizes it or fragments the spec.
• Clarity vs. expressiveness. Allowing composition means accepting systems that resist a single label. Yet disallowing composition creates pressure to misclassify or physically decompose architecturally coherent systems.
• Simple governance vs. complex reality. A pure archetype inherits a clear governance profile. A composed system requires per-component governance that must integrate coherently.
• Reusability vs. specificity. If composition is ad-hoc, every composed system requires custom governance reasoning. Named composition patterns allow pre-thought-through governance.

The Solution

The Composition Principle

A system has one governing archetype and zero or more embedded components that serve different archetype roles. The governing archetype is determined by the highest-risk autonomous action in the system. Embedded components are declared explicitly and governed by their own constraints within the parent system.

The governing archetype determines:

• The default oversight model for the system as a whole
• The risk posture label in the spec
• The invariants that cannot be overridden

Embedded components determine:

• Which behaviors inside the system require additional, locally-specific constraints
• Which outputs of embedded components are visible vs. internal
• Whether the embedded component needs its own spec section or is sufficiently covered by the governing spec

The key move: you do not blend. You layer.

Common Composition Patterns

Pattern A: Advisor → Executor (Confirm-then-Act)

The system shows the user what it intends to do before acting. The advisory phase is Advisor-class; the execution phase is Executor-class.

┌─────────────────────────────────────────────────────────────┐
│  GOVERNING ARCHETYPE: Executor                               │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  Embedded advisory layer: Advisor                     │  │
│  │  • Generates proposed action with rationale           │  │
│  │  • Outputs to human confirmation step                 │  │
│  │  • Human confirmation IS the oversight gate           │  │
│  └───────────────────────────────────────────────────────┘  │
│                         ↓ (confirmed)                        │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  Executor core: acts within pre-authorized scope      │  │
│  │  • Governed by Oversight Model C (output gate)        │  │
│  │  • The advisory phase IS the output gate              │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Governing archetype: Executor. The advisory phase is explicitly how this Executor implements Oversight Model C — the human confirmation serves as the output gate. The architectural insight is that a confirm-then-act pattern is not two archetypes; it is an Executor implementing its required oversight model via an embedded advisory step.

Pattern B: Executor + Guardian (Act-within-enforced-limits)

The system takes action but has a Guardian component that enforces a non-negotiable constraint. The Guardian is not optional or configurable — it is always in the path.

┌─────────────────────────────────────────────────────────────┐
│  GOVERNING ARCHETYPE: Executor                               │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  Guardian layer: invariant enforcement                │  │
│  │  • Cannot be disabled or bypassed                     │  │
│  │  • Evaluated before every consequential action        │  │
│  │  • Violation → halt + surface, never silent skip      │  │
│  └───────────────────────────────────────────────────────┘  │
│                         ↓ (passes)                           │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  Executor core                                        │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

The Guardian layer is specified with Guardian-class constraints: what exactly it enforces, what constitutes a violation, and what happens when a violation is detected. The Executor core is specified with Executor-class constraints. These are separate sections in the spec, with the Guardian layer having its own invariants that cannot be overridden by the Executor section.

Pattern C: Orchestrator with typed sub-agents

An Orchestrator coordinates several distinct agents, each of which is a different archetype.

┌─────────────────────────────────────────────────────────────┐
│  GOVERNING ARCHETYPE: Orchestrator                           │
│                                                              │
│  Coordinates:                                                │
│  ┌────────────────┐  ┌───────────────┐  ┌──────────────┐   │
│  │ Agent A        │  │ Agent B       │  │ Agent C      │   │
│  │ (Advisor)      │  │ (Executor)    │  │ (Guardian)   │   │
│  │ • Summarizes   │  │ • Takes       │  │ • Validates  │   │
│  │   retrieved    │  │   remediation │  │   all outputs│   │
│  │   context      │  │   actions     │  │   pre-post   │   │
│  └────────────────┘  └───────────────┘  └──────────────┘   │
└─────────────────────────────────────────────────────────────┘

Each sub-agent in an Orchestrator composition should be specced with its own archetype. The Orchestrator's spec defines: what it coordinates, how it routes, what it does with results, and what it is not permitted to do itself. The Orchestrator should not be acting as an Executor, Advisor, Guardian, or Synthesizer simultaneously — if it is, it has a sub-agent that should be made explicit.

This pattern is particularly common in complex support systems: an Advisor agent surfaces options, an Executor agent applies a selected resolution, a Guardian agent validates that the resolution doesn't violate support policy.

Pattern D: Synthesizer + Executor (Compose-then-Publish)

The system produces a composed artifact and then publishes or deploys it. The composition is Synthesizer-class; the publication is Executor-class.

The governing archetype is Executor — the final action is what determines the risk profile. The synthesis phase is how the Executor prepares its output. The spec should describe both the synthesis behavior and the execution behavior, with particular attention to the approval gate between them: who reviews the synthesized artifact before it is executed?

If there is no review gate — synthesis automatically triggers publish — this system is a pure Executor with a complex preparation step. Document it that way. Do not refer to it as a "Synthesizer with an execution capability" because that construction hides the autonomous action.

Pattern E: Mode-switching compositions (the 2026 pressure-point classes)

The four patterns above are layered compositions — every archetype is active simultaneously. Pattern E names a different shape: at any given moment the system is in one archetype's mode, and it transitions between modes within a single session. The transitions are first-class events with their own invariants. This is the structural answer to the three pressure-point classes named in Pick an Archetype — A working taxonomy, not a settled one.

Coding agents. A Cursor / Claude Code / Cline / Devin session moves between Synthesizer mode (planning, summarizing changes, explaining intent) and Executor mode (writing files, running tests, opening PRs). On harder tasks the same session may also enter Orchestrator-over-self mode (delegating sub-tasks to itself or to subordinate agents). The governing archetype is Executor — it is the highest-risk action mode the system reaches — and the embedded modes are Synthesizer and (sometimes) Orchestrator.

GOVERNING ARCHETYPE: Executor
  Mode 1: Synthesizer (plan, explain, summarize)
  Mode 2: Executor (write files, run tests, open PR)  ← governing
  Mode 3: Orchestrator-over-self (delegate sub-task)

Cross-mode invariants (cannot break, regardless of active mode):
  • File-system scope: identical in every mode
  • Test-deletion: forbidden in every mode
  • Authorized-domain list for outbound traffic: same in every mode

The structural insight: invariants that hold in every mode go in the spec at the system level (a sub-section of §6 Invariants in the canonical spec template, declared in §4's Composition Declaration). Invariants that hold only within a mode go in that mode's component spec. This is the failure-prevention discipline — every documented coding-agent failure (deleted tests, unauthorized refactors, scope-creep PRs) has been a cross-mode invariant that was not declared as cross-mode.

Deep-research agents. A long-horizon research agent moves between Synthesizer mode (composing the final report from gathered sources) and Orchestrator-over-self mode (planning what to search next, dispatching parallel sub-research). The governing archetype is Synthesizer — its deliverable is a composed artifact and it does not act on the world during research. Embedded: Orchestrator-over-self for planning.

GOVERNING ARCHETYPE: Synthesizer
  Mode 1: Synthesizer (compose report)              ← governing
  Mode 2: Orchestrator-over-self (plan further searches)

Cross-mode invariants:
  • Do not act on the world: never make API calls outside the
    read-only research tool manifest
  • Every claim in the synthesized report cites a source URL
    (see Grounding with Verified Sources)
  • The agent does not recurse beyond depth N (cost cap)

Self-improving / training agents. A system whose primary act is to evaluate or fine-tune another agent's behavior. The honest reading is that this is two systems with a clean handoff, not one mode-switching system: the meta-system is a Synthesizer (it produces a training signal or fine-tune dataset); the inner agent is an Executor or whichever archetype its deployment shape calls for. Document them with two specs and an explicitly-defined handoff. The handoff itself is the design surface — what data crosses, who validates it, what audit trail the meta-system leaves on the inner agent's training history.

META-SYSTEM (Synthesizer)         INNER AGENT (Executor, separate spec)
  Reads inner agent's outputs       Operates on its own deployment
  Composes a training signal        ↑ Handoff (validated, audited)
  Outputs to fine-tune queue  ─────→ Loaded as new model weights

The contrast with the layered patterns. In Patterns A through D, all archetypes are active simultaneously and the layering is structural. In Pattern E, the system is in one mode at a time and the transitions are temporal. This places extra weight on the spec's transition logic — what triggers a mode change, what state the agent carries across the change, and what invariants from the previous mode persist. A spec that documents the modes but not the transitions is missing the load-bearing surface.

The Composition Declaration in the spec

For systems with embedded components (Patterns A–D) or mode-switching (Pattern E), §4 of the canonical spec template (Archetype Declaration) is extended with a Composition Declaration sub-block. The fragment below is the canonical form:

## 4. Archetype Declaration

**Classification:** Executor (governing)

**Composition:** Mode-switching (Pattern E) — coding agent shape
- Mode 1: Synthesizer — plan, explain, summarize the change
- Mode 2: Executor — write files, run tests, open PR  (governing)
- Mode 3: Orchestrator-over-self — delegate sub-tasks across files

**Mode transitions:**
- Synthesizer → Executor: when the user accepts a plan
- Executor → Synthesizer: when a sub-task is blocked or the spec
  is ambiguous; produce a clarification request, do not guess
- Executor → Orchestrator-over-self: when a sub-task requires
  more than 5 file edits; surface a sub-task plan for confirmation

**Cross-mode invariants** (hold regardless of active mode):
- File-system scope: read+write limited to repository root,
  excluding the test directory in every mode
- Test deletion forbidden
- No outbound traffic except to whitelisted domains
- Spec amendments cannot be made by the agent; only by humans
  via spec review

**Per-mode oversight** (referenced in §11 Agent Execution Instructions):
- Synthesizer mode: Periodic — sample 1 in 5 plans
- Executor mode: Pre-authorized scope, exceptions escalate
- Orchestrator-over-self mode: Output Gate at PR boundary

Two things this fragment guarantees:

1. Cross-mode invariants are written down where the spec author had to think about them. They cannot be "implicitly assumed" across modes. A reviewer reading §4 sees them as first-class declarations, not as scattered constraints.
2. The transitions become a reviewable surface. A reviewer can ask "what triggers this transition? what state carries across? which invariants persist?" before the system ships, instead of after the first incident.

Without this fragment, mode-switching systems often have implicit transitions that nobody specced. Cat 1 (Spec) failures in coding agents are disproportionately transition failures: the agent moved from Synthesizer mode into Executor mode without re-checking a constraint that the spec only declared in one of the two modes. Declaring the transitions makes those failures visible at review time.

For Patterns A–D (layered compositions), the Composition Declaration is simpler — it names the governing archetype and lists the embedded components with their archetype roles, instead of naming modes and transitions. The cross-component invariants section still applies: invariants that hold across all components go in §6 at the system level, not inside any single component's section.

Worked example: spec-conflict resolution in an Advisor + Executor composition

The four patterns above describe well-formed compositions. In practice, two archetypes' specs eventually conflict on a specific case the framework didn't anticipate. The resolution rules from Multi-Agent Governance — (1) higher-tier invariant wins; (2) earlier-in-pipeline-wins-on-read, later-on-write; (3) tie-break: surface, don't resolve — apply here too. This worked example shows the rules in action.

The system. A customer-facing financial-planning agent. Pattern A (Advisor → Executor confirm-then-act). The Advisor surfaces investment options; the Executor places trades on the user's confirmation.

The Advisor's spec (excerpt):

• §3 Scope: "Surface up to five options across the user's stated risk profile, including options that maximize expected return."
• §5 Constraint A1: "Always include at least one option above the user's stated risk profile when available, clearly flagged. Users may want to be aware of higher-return options even if they ultimately choose conservatively."

The Executor's spec (excerpt):

• §3 Scope: "Place trades for options the user confirms."
• §5 Constraint E1 (invariant): "Never place trades that exceed the user's stated risk profile. Any such request must surface."
• §5 Constraint E2: "Trade size limited to $5,000 per session without secondary confirmation."

The conflict. The Advisor surfaces a higher-risk option per A1. The user, attracted by the return, confirms it. The Executor receives a confirmation for a trade that violates E1. Two specs are in tension: A1 expects the system to surface higher-risk options; E1 forbids placing those trades.

Naive resolutions, both wrong:

• "The user confirmed, so the Executor should proceed." This treats user confirmation as overriding the Executor's invariant. It does not. Invariants are not waivable by user request — they are by definition the constraints that cannot be traded.
• "The Advisor should not surface options the Executor cannot place." This treats the Advisor's job as constrained by the Executor's authorization. But the Advisor's job (per A1) is to inform — including about options the user may not be authorized for. Restricting it would lose information value.

Correct resolution, applying the three rules:

1. Rule 1 (higher-tier invariant wins). E1 is declared as an invariant. A1 is a constraint. The invariant binds. The trade does not happen.
2. Rule 2 (earlier-on-read, later-on-write). The Advisor reads the user's risk profile and informs; that is its read-side authority. The Executor writes (places the trade); on the write side, the Executor's constraints bind. Rule 2 reinforces Rule 1 here.
3. Rule 3 (surface, don't resolve). Even with Rules 1 and 2 deciding the outcome, the user needs to know what happened. The system surfaces: "You selected an option above your stated risk profile. To proceed with this trade, please update your risk profile through [process Y] and reconfirm. Otherwise, please select a different option."

What the system spec should encode (above the per-component specs):

Conflict resolution policy:
- Advisor's information surface is bounded only by Advisor §3 and §5.
- Executor's authorization-to-act is bounded by Executor §3 and §5.
- When user confirms an Advisor-surfaced option that the Executor's
  invariant forbids: do not act; surface the conflict to the user
  with the specific invariant cited and the path to resolve it
  (update risk profile, choose different option).
- The system never silently downgrades a user's selection. The user
  is told their selection cannot be acted on and why.
- The Advisor's flagging discipline (A1's "clearly flagged") is the
  first line of defense — if the user is well-informed about which
  options exceed their profile, the conflict rate drops. This is
  measured: target conflict-surface rate < 5% of confirmed selections.

The lesson, generalizing. Spec conflicts in compositions are common and expected. The rule is not "design specs that never conflict" — that's not achievable. The rule is "make the resolution policy explicit at the system level, before the conflict happens." The three rules give a default; the system spec can refine them per case. What is forbidden is silent resolution by either component, which is itself a Cat 1 spec failure of the system spec even when both component specs are individually correct.

The Composition Checklist

When a system involves more than one archetype role, verify:

• The governing archetype has been identified (highest-risk autonomous action)
• Each embedded component or mode has been named and typed
• Guardian-class embedded components cannot be bypassed by the governing layer
• Advisory-class embedded components feeding confirm-then-act patterns are recognized as oversight model implementations, not separate systems
• Each sub-agent in an Orchestrator composition has its own archetype declaration
• For mode-switching systems (Pattern E): every transition between modes is documented with its trigger and the state that carries across
• For mode-switching systems: every invariant that must hold across modes is declared once at the system level, not duplicated (or worse, omitted) in mode-specific sections
• The spec includes a §4 Composition Declaration naming the governing archetype, the embedded components or modes, the transitions (if any), the cross-mode/cross-component invariants, and the per-component or per-mode oversight notes
• The governing invariants are written at the system level, not the component level
• No section of the spec says "mostly X with some Y" — each component has a definite type

What Composition is Not

Composition is not a license to make a system do anything by slicing it into enough pieces.

If you find yourself classifying a system as "Advisor for the retrieval step, Executor for the action step, Guardian for the safety step, Synthesizer for the reporting step, Orchestrator at the top" — you are probably describing a system that is too large to govern coherently as a single entity.

The question to ask: Would a single on-call engineer be able to understand and halt any part of this system within five minutes? If not, the system is not too complex to classify — it is too complex to run. Break it into separately deployable systems with separately governable boundaries.

Composition is meant to clarify layering within a coherent unit. It is not a way to make complexity legible in documentation while leaving it ungovernable in production.

Resulting Context

After applying this pattern:

• Governing archetype determines risk. By identifying the highest-risk autonomous action and using that to set the governing archetype, the composition privileges safety.
• Embedded components are constrained separately. Guardian components embedded in an Executor cannot be bypassed by Executor-level decisions. The Guardian operates in its own governance tier.
• Confirm-then-act becomes a governance pattern. An Advisor phase feeding into an Executor phase is recognized as an Executor implementing its required oversight gate.
• Coherence without fragmentation. A composed system has one authoritative spec, not multiple specs in contradiction.

Therefore

Real systems layer or mode-switch across multiple archetype roles, and composition is the structural surface that captures both. Give the system one governing archetype — determined by its highest-risk autonomous action — and declare embedded components or modes explicitly with their own constraints, transitions, and cross-mode invariants in a §4 Composition Declaration. A Guardian embedded in an Executor cannot be disabled by Executor-level decisions. An Advisor embedded as a confirmation step is how the Executor implements its oversight model. A coding agent's Synthesizer-Executor-Orchestrator mode-switching is a single Executor with declared transitions, not three systems and not a missing archetype. Composition clarifies layering and mode-switching; it is not a substitute for decomposing a system that is too complex to govern.

Connections

This pattern assumes:

• The Five Archetypes
• Four Dimensions of Governance
• The Archetype Selection Tree

This pattern enables:

• Governed Archetype Evolution
• The Canonical Spec Template — multi-component spec structure
• Each archetype deep-dive: Advisor, Executor, Guardian, Synthesizer, Orchestrator

Governed Archetype Evolution

Part 1 — Frame

"A building is not a building. It is a process — a process which, over time, unfolds. And the quality of the process determines the quality of the result."
— Christopher Alexander, The Nature of Order

Context

You have classified a system, specced it, and shipped it. Three months later, a stakeholder wants to expand what it does. Or six months later, the system has quietly accumulated capabilities it was never formally authorized to have. Or a year later, you inherit a system and have no record of why it was classified the way it was.

Archetypes are not permanent — but changing them must be a deliberate act, not an accumulation of small decisions.

This pattern assumes all the prior archetype chapters: Pick an Archetype, Four Dimensions of Governance, The Archetype Selection Tree, and Composing Archetypes.

The Problem

The hardest archetype problem is not classification — it is drift.

A system begins as an Executor within a tight pre-authorized scope. Over time, individual decisions expand the scope slightly: this API call is basically the same as the authorized ones, this additional write is necessary for the feature to work, the exception gate is too slow for this case, let's skip it just this once. No single decision is dramatic. Each is locally defensible.

Six months later, the system is taking consequential actions across a much broader domain with less oversight than was originally designed. It is still technically classified as an Executor, but it is now functioning as an uncontrolled Orchestrator. The archetype became a fiction.

This is archetype drift — and it is more dangerous than a wrong initial classification, because at least a wrong initial classification can be discovered and corrected. Drift is invisible until a consequential failure reveals it.

The inverse problem also occurs: a system is over-constrained for its actual risk. An Advisor that was given Guardian-class oversight because someone was nervous during initial design never gets simplified. Friction accumulates, engineers route around it, and eventually the oversight process exists on paper while real oversight happens not at all.

Archetypes need to evolve — but evolution must be governed differently from initial classification.

Forces

• Archetype permanence vs. operational reality. Systems change in scope and capability over months and years; treating archetypes as immutable produces governance models increasingly divorced from actual behavior.
• Drift invisibility vs. explicit evolution. Small incremental decisions that expand scope are invisible until a failure reveals them; formal review processes are heavyweight but catch drift that informal change control misses.
• Speed vs. governance. Formal reclassification takes time. Systems are under deadline pressure. The process cannot be so heavy that teams route around it, yet cannot be so light that drift happens invisibly.
• Accountability vs. flexibility. When an archetype changes, someone made that decision. There must be a record of who and why. Yet expecting formal notification of every scope expansion may create incentives to classify loosely from the start.

The Solution

The Distinction Between Evolution and Drift

Drift is when a system's actual behavior diverges from its archetype classification because of accumulated, unreviewed decisions.

Evolution is when a system's archetype classification is formally updated to match a deliberate, reviewed change in scope or capability.

The mechanisms that distinguish them:

The spec is the primary instrument for distinguishing drift from evolution. If the spec was not updated before the behavior changed, the change was drift.

Triggers for Archetype Review

A formal archetype review should be triggered when any of the following occur:

Capability expansion triggers:

• The system can now write to a new target system it couldn't before
• The system can now make decisions it previously surfaced to humans
• The system's action scope has expanded beyond what the pre-authorized scope declaration describes
• The system now routes work to or from other agents it didn't interact with at time of classification

Risk change triggers:

• The system now processes data it didn't before (especially personal, financial, or safety-critical data)
• The potential impact scope has grown (more users, more downstream systems affected)
• A failure mode has been identified that wasn't considered in the original Risk Posture

Oversight degradation triggers:

• The agreed oversight process is being routinely bypassed or skipped
• The exception gate is generating so many exceptions that it has become nominal
• Human reviewers in the oversight chain are no longer making substantive reviews

Third-party trigger:

• Any security audit or incident post-mortem that references the system
• A significant change to any external system the agent integrates with
• Regulatory or policy change that affects the data or actions the system handles

The Archetype Review Process

An archetype review is not a re-evaluation starting from scratch. It is a comparison of the current behavior against the current spec, against the original archetype declaration.

Step 1 — Behavior audit. Without looking at the spec, describe what the system actually does today. What data does it read? What actions does it take? What decisions does it make autonomously? What does it escalate? This description should come from logs, code, and team knowledge — not the spec.

Step 2 — Spec gap identification. Compare the behavior audit against the current spec. Document every discrepancy. There will always be some. The question is whether they are structural (affecting archetype, dimensions, or invariants) or peripheral (affecting implementation detail).

Step 3 — Re-run the decision tree. Apply The Archetype Selection Tree to the system as described by the behavior audit. Does the result match the current archetype classification?

If yes: Update the spec to close the peripheral gaps. The archetype stands.

If no: proceed to Step 4.

Step 4 — Reclassification proposal. Document: what the current archetype is, what the correct archetype appears to be, what changed, and who authorized or permitted those changes. This is an accountability document, not a blame document. Its purpose is to ensure that reclassification is owned.

Step 5 — Dimension and invariant review. If the archetype changes, all four dimensions must be re-evaluated from scratch. The prior dimensions are not inputs to the new evaluation — they are a comparison check after the new evaluation is complete. Invariants from the old archetype must be audited: do they still apply? Are they sufficient? Are any of them now wrong?

Step 6 — Spec update and redeployment. Update the spec before deploying any new behavior. The spec must describe the system as it will be, not as it was.

Integrating Archetype Reviews Into CI/CD

In continuous deployment environments, archetype evolution must be integrated into the delivery pipeline rather than treated as an offline governance exercise:

• Spec-as-code. Store specs alongside application code in the repository. Spec changes follow the same pull request and review process as code changes. Archetype reclassification is a PR that requires explicit approval from the authority level defined in Proportional Governance.
• Automated drift detection. CI checks can validate that the system's declared capabilities (tool manifest, API surface, data access) are consistent with its archetype's authorized scope. A new tool added to the manifest that exceeds the current archetype's boundaries should fail the pipeline and trigger a review.
• Gated promotion for archetype changes. When an archetype is reclassified, the deployment requires a manual gate — the spec reviewer signs off before the pipeline proceeds. This is not bureaucracy; it is the minimum governance for a change that alters oversight requirements, risk posture, and invariants.
• Feature flags for planned evolution. Planned transitions (Advisor → Executor) can be gated behind feature flags that are enabled only after transition criteria are met and the spec is updated. The flag flip is a logged event, not a silent change.

Planned Evolution

Some archetype evolution is anticipated from the beginning. A system built to validate content may be planned to take enforcement action in future phases. An Advisor may be planned to become an Executor once trust is established.

Planned evolution should be documented in the initial spec, not as a commitment but as a declared transition path:

## Planned Evolution

**Current classification:** Advisor (Agency Level 2)  
**Target classification (Phase 2):** Executor (Agency Level 3)  
**Transition criteria:**  
  - 90-day operational record with <0.1% false positive rate  
  - Formal sponsor review and approval  
  - Spec updated before any autonomous action is enabled  
**What will NOT change at transition:** The Guardian layer invariants apply in 
Phase 2 as they do in Phase 1.

This declaration serves two purposes. First, it makes the future intent visible so that teams operating the Phase 1 system know what the goal is. Second, it creates a formal threshold — the transition criteria — that must be met before the archetype changes. The transition becomes an event, not a drift.

The Hardest Case: Downgrading an Archetype

Systems almost always expand in scope. Downgrading — reducing from Executor to Advisor, or from Orchestrator to Executor — is rare and requires the same formal review as upgrading.

A common reason for downgrading: a system was over-built for its actual risk, and the overhead of its governance model is disproportionate. The correct response is a formal reclassification, not a quiet relaxation of the oversight model while keeping the archetype label.

The reclassification removes the liability of governing a system by the wrong model — including the liability of having a governance model that nobody follows.

The Constitutional Record

Every archetype classification, review, and reclassification should be recorded in the spec's version history. Not just "updated classification" — the actual record:

• Date
• Previous classification
• New classification
• Reason for change
• Reviewer(s)
• Transition criteria (if applicable)

This record is the constitutional history of the system. It is the document a future engineer reaches for when they need to understand why the system is the way it is. It is the document an auditor reaches for when accountability matters.

Write it with that reader in mind.

Resulting Context

After applying this pattern:

• Drift becomes detectable. With a defined separation between drift and evolution, audit can identify when a system has drifted and require remediation. The archetype is no longer fiction.
• Transitions are loadbearing. Planned evolution is now a named transition with explicit criteria. The transition itself is a checkable event.
• Constitutional history becomes auditable. With version history recorded in the spec, any reviewer can see what the system was classified as, when it changed, and why.
• Reclassification authority is aligned. The authority to reclassify a system is the same as the authority to originally classify it, preserving the constitutional principle.

Therefore

Archetype drift occurs when small decisions accumulate without review, producing a system whose actual behavior no longer matches its governance model. Evolution is when the classification is formally updated to reflect a deliberate change — with a behavior audit, the decision tree re-applied, dimensions re-evaluated, and the spec updated before deployment. Planned transitions should be declared upfront with explicit criteria. Every reclassification should be recorded in the spec's constitutional history.

Connections

This pattern assumes:

• Pick an Archetype
• Four Dimensions of Governance
• The Archetype Selection Tree
• Archetype Composition

This pattern enables:

• The Canonical Spec Template — the spec version history section
• Living Specs — how specs evolve over time
• Part 5 (Ship) — governance cadences in production

Part 1 (Decisions) is complete. Continue to Part 2 (The Spec), or to the archetype deep dives: Advisor · Executor · Guardian · Synthesizer · Orchestrator

Multi-Agent Governance

Part 1 — Frame

"A system of agents is not the sum of its agents' specs. It is the agents' specs, plus the spec of how they coordinate, plus the spec of what happens when coordination breaks. The third is the one most teams forget to write."

Context

You are designing or operating a system in which more than one agent participates in producing an outcome — an Orchestrator with sub-agents, a pipeline of specialized agents, peer agents that hand off work, or a self-similar architecture where one agent class spawns instances of itself.

The single-agent disciplines from the rest of the book (archetype selection, spec template, oversight model, eval stack) all still apply to each agent individually. This chapter is about what those disciplines miss when you compose them: the failure modes that emerge from coordination, not from any single agent's behavior.

Composing Archetypes addresses two-archetype layering — an Advisor sitting in front of an Executor, a Guardian wrapping a Synthesizer. This chapter goes one level up: how do you govern a system of N agents as a system, not as N independently-specified components?

The Problem

The empirical literature on multi-agent LLM failures is sobering. Cemri et al. (2025), Why Do Multi-Agent LLM Systems Fail?, analyzed over 200 multi-agent failure traces across published frameworks (MetaGPT, AutoGen, ChatDev, LangGraph supervisors) and found that the dominant failure categories were not the ones the per-agent literature emphasizes. Their MAST taxonomy partitions failures into three top-level categories:

• Specification issues — task specs incomplete, agent role specs ambiguous, success criteria unstated. (Roughly 40% of observed failures.)
• Inter-agent misalignment — agents working at cross-purposes, redundant work, contradicting assumptions, conversation derailment. (Roughly 35%.)
• Task verification failures — no agent owned validation, premature termination, incorrect handoffs. (Roughly 25%.)

The implication for governance: a multi-agent system can have correctly-specified individual agents and still fail systematically because nothing in the per-agent specs covers the seams between them.

This chapter is about engineering the seams.

Forces

• Specialization vs. coordination cost. Each specialized agent reduces the surface a single context must hold; each coordination interface adds a new failure mode. There is a productivity sweet spot, and most teams cross it before they realize it.
• Per-agent reliability vs. compound reliability. A two-agent pipeline of 95%-reliable agents is 90% reliable end-to-end; a five-agent pipeline of 95%-reliable agents is 77% reliable. Compounding multiplies, and per-agent improvement does not save you.
• Local correctness vs. global correctness. Each agent can satisfy its own spec while the system fails. The classic shape: agent A returns "I cannot answer this question"; agent B faithfully forwards the non-answer; the user receives a polite refusal where a substantive answer was possible. No agent failed its own spec.
• Debugging granularity vs. observability cost. Multi-agent systems require traces that span agents, sessions, and tool calls. Without that, post-mortems devolve into speculation — and speculation does not produce spec-gap-log entries.

The Solution

Three governance artifacts beyond the per-agent spec

A multi-agent system requires three artifacts that single-agent systems do not:

1. The system spec. A document above the per-agent specs that names: the system's overall objective; the participating agents and their roles; the protocol they use to coordinate (handoff rules, message formats, termination conditions); the oversight model for the system, distinct from per-agent oversight; and the validation step that checks the system's output against the system's objective, not just each agent's against its own.

2. The seam contracts. For every pair of agents that hand off work, an explicit contract: what schema the handoff message carries, what the receiver may assume, what the receiver must check, what happens when the input violates the contract. Without explicit seam contracts, agent A's output ambiguity becomes agent B's silent failure.

3. The compounding-failure runbook. A pre-written playbook for the failure shapes the team has decided to plan for: what counts as a system-level error, who gets paged, how to bisect across agents, how to roll back the system as a unit when one agent's failure cascaded.

Coordination patterns and their governance implications

Three coordination patterns dominate production multi-agent systems. Each has a different governance profile.

Supervisor / orchestrator pattern. One privileged agent (the supervisor) decomposes work, dispatches to specialized sub-agents, integrates results, and decides termination. LangGraph's create_supervisor and Anthropic's Building Effective Agents "orchestrator-workers" pattern are the canonical references.

• Governance posture: The supervisor is the single accountable agent for system-level outcomes. Its spec must include explicit failure-handling rules for sub-agent failure, contradictory sub-agent outputs, and termination criteria. Sub-agents are spec'd individually but their outputs are inputs to the supervisor's judgment, not direct user outputs.
• Where it fails: Supervisor scope creep — the supervisor starts doing the work itself instead of delegating, because that's the path of least resistance under uncertainty. Sub-agent contract violation — the supervisor accepts malformed sub-agent output rather than rejecting it. Termination loops — the supervisor cannot decide it's done and runs forever.

Pipeline pattern. Agents in a fixed sequence, each transforming the output of the previous one. Anthropic's "prompt chaining"; LangGraph's linear graphs.

• Governance posture: Each pipeline stage has a tight spec on its input contract and output contract. The pipeline as a whole has an end-to-end acceptance test. Validation happens after the last stage, not after each stage (otherwise you're paying for redundant review).
• Where it fails: Compounding errors that grow stage by stage. Schema drift between stages when one agent's output evolves and downstream stages don't notice. Over-pipelining — using N stages where N-1 would do.

Peer / handoff pattern. Agents that pass work to each other dynamically based on their role (a "router" agent that hands off to specialists; OpenAI Swarm's handoff model).

• Governance posture: Each agent declares which other agents it may hand off to and under what conditions. The seam contracts are now M×N — every potential handoff edge needs its own protocol. The system spec must define termination (when does work stop being handed off?) and detect cycles.
• Where it fails: Handoff cycles. Loss of context across handoffs. Agents that hand off rather than do work because handoff is "safer" — the agent equivalent of management overhead.

The book's recommendation, following Anthropic's guidance, is to start with the simplest pattern that solves the problem. Most production teams should use a workflow (deterministic sequence) before they use a pipeline; a pipeline before a supervisor; a supervisor before peer handoffs. Each escalation in pattern complexity should be justified by a measured reason, not by aesthetic appeal.

Agent-to-agent protocols and the 2026 standardization arc

By 2026, agent-to-agent (A2A) communication has begun to standardize, with multiple competing-but-interoperable protocols emerging. The most-cited of these is Google's Agent2Agent (A2A) Protocol (announced 2025), which defines how independent agents — possibly from different vendors, possibly running in different organizations — discover each other, negotiate capabilities, exchange tasks, and report results. Anthropic's MCP, originally tool-focused, has begun to extend toward agent-as-server patterns. OpenAI's Agent SDK ships its own coordination primitives. LangGraph's supervisor and handoff patterns continue to be the dominant in-vendor reference.

For the governance discipline this chapter teaches, the protocol-layer specifics matter less than the conceptual question: does your team's multi-agent system communicate via a standard protocol, or via bespoke point-to-point integration?

The 2026 default position should be: standard protocol where possible. The reasoning is the same as for MCP at the tool layer:

• Standard protocols centralize observability and governance. Cross-agent traces, contract validation, and authorization boundaries can be enforced at the protocol layer rather than re-implemented per integration.
• Standard protocols enable cross-vendor portability. If today's orchestrator is in LangGraph and tomorrow's is in OpenAI Agent SDK, a system spec written against a standard A2A protocol composes; one written against in-vendor coordination primitives does not.
• Standard protocols expose the seam contracts. The protocol-level message schema is the seam contract — formalized, validated, and version-able rather than implicit in the orchestrator's code.

What does NOT change with standardization: the seam contracts still need to be designed, the spec-conflict resolution rules still apply, the compounding-failure runbook is still required. The protocol gives you the wire format; the governance is your responsibility.

The governance addition for protocol-mediated multi-agent systems:

• Section 7 (Tool Manifest) of the system spec lists the A2A protocols and the agents reachable through them, with their respective authorization scopes.
• Each cross-agent message type has a Section 6 (Invariants) entry: what content the message may carry, what authority it grants the receiver, what happens on contract violation.
• The multi-agent observability stack (per Production Telemetry) consumes the protocol's standard trace format. OpenTelemetry's GenAI semantic conventions cover the cross-agent message attributes alongside the per-agent ones.

Specific protocol references for further reading:

• A2A (Agent2Agent) Protocol — Google's open standard for cross-vendor agent communication. As of 2026, the most fully-specified A2A protocol; reference at a2aprotocol.dev.
• MCP (Model Context Protocol) — Anthropic's tool-focused protocol, increasingly used in agent-as-server patterns. See The Model Context Protocol.
• OpenAI Agent SDK — vendor-specific but widely adopted; ships handoff primitives that approximate A2A semantics within OpenAI's ecosystem.
• OpenTelemetry GenAI semantic conventions — the cross-protocol observability layer that lets you trace through any of the above. opentelemetry.io/docs/specs/semconv/gen-ai.

Treat the protocol choice as an architectural decision worth recording in an ADR. The ADR's Spec Mapping should connect to the system spec's Section 7 (the protocols allowed) and Section 6 (the invariants on cross-agent messages).

Spec-conflict resolution

Composing Archetypes raises but does not resolve the case where one agent's spec authorizes behavior another agent's spec forbids. In a multi-agent system this is common — a Synthesizer's "must produce a unified output" can conflict with a Guardian's "must flag contradictions rather than resolve them silently."

Three resolution rules, ordered:

1. Higher-tier invariant wins. If one spec's clause is an invariant (Section 6) and the other's is a constraint or preference, the invariant wins. The system spec must declare which agent's invariants are system-level (binding on all participants) versus agent-local.
2. Earlier in the pipeline wins on read; later wins on write. If agent A reads upstream and agent B writes downstream, A's constraints on input shape bind B; B's constraints on output shape bind A's choice of output schema. This rule prevents A from producing outputs B cannot consume.
3. Tie-break: surface, do not silently resolve. If neither rule disambiguates, the system spec must say which agent has the right to escalate the conflict and how. Silent resolution by either agent is a Cat 1 (Spec) failure of the system spec, not of the local agents.

Encode these rules in the system spec. The per-agent specs should reference them rather than re-deriving them.

MAST as a diagnostic frame

The MAST taxonomy (Cemri et al. 2025) is the most rigorous practitioner-facing partition of multi-agent failures published. Its three top-level categories — specification issues, inter-agent misalignment, task verification failures — and 14 sub-categories give an empirical vocabulary that complements (not replaces) the seven categories from Failure Modes and How to Diagnose Them.

Mapping MAST onto the book's seven categories:

Use MAST when post-morteming a multi-agent failure: it gives finer-grained diagnostic vocabulary. Use the book's seven categories when deciding which artifact to edit (which is what the diagnostic protocol is for).

Observability requirements

Single-agent observability is insufficient for multi-agent systems. Three additions:

• Cross-agent correlation IDs. Every message and tool call carries a system-level trace ID plus per-agent span IDs. Without this, post-mortem traces cannot be reconstructed.
• Seam logging. Every handoff between agents logs the input contract, the actual input, the receiving agent's acceptance decision, and any contract violation. This is what makes inter-agent misalignment debuggable.
• Token and cost attribution per agent role. A multi-agent system that costs 5x a single-agent system is fine if it's worth it; it is not fine if no one notices. Per-role attribution makes the cost visible.

OpenTelemetry's GenAI semantic conventions (under active development as of 2026) cover most of this. Langfuse, LangSmith, and Phoenix all implement multi-agent traces in production-ready form.

When NOT to go multi-agent

The strongest position the book takes on multi-agent systems is to talk teams out of them when possible. The conditions under which a single agent is preferable:

• The total task fits in a single context with margin.
• The reliability ceiling of a single capable model on the task is acceptable.
• Latency budget cannot absorb sequential agent calls.
• Cost per task matters and per-agent overhead would dominate.
• Debuggability matters more than specialization.

Conditions that justify multi-agent:

• The task's natural decomposition has measurable handoff points (e.g., research → draft → review → publish).
• Specialization gives a measured reliability gain that cannot be matched by a single agent with the right tools.
• Independent oversight is required (a Guardian must be a separate agent from the actor it guards).
• Concurrent execution gives a meaningful latency win.

If none of those apply, the multi-agent architecture is paying coordination cost for no measured benefit.

Resulting Context

After applying this pattern:

• The system spec is written. The system's objective, the agents' roles, the coordination protocol, the system-level oversight, and the system-level validation are all named in a document above the per-agent specs.
• Seam contracts exist. Every agent-to-agent handoff has an explicit contract on input schema, contract violation handling, and termination conditions.
• Spec-conflict resolution is rule-governed. When per-agent specs conflict, the system spec's resolution rules apply rather than letting either agent resolve silently.
• MAST diagnostics are in the toolkit. Post-mortems use MAST sub-categories for diagnosis and the book's seven categories for fix-locus.
• Observability spans the system. Cross-agent traces, seam logs, and per-role cost attribution make multi-agent failures debuggable.

Therefore

A system of agents requires governance artifacts that single-agent systems do not: a system spec, seam contracts at every handoff, and a compounding-failure runbook. The MAST taxonomy is the empirical frame for diagnosing where multi-agent systems fail; the book's seven categories tell you which artifact to edit. Start with the simplest coordination pattern that solves the problem and only escalate when you have measured a reason. Most teams should not be running multi-agent systems they could solve with a workflow.

References

• Cemri, M., et al. (2025). Why Do Multi-Agent LLM Systems Fail? — MAST: A Multi-Agent System Failure Taxonomy. — Empirical 14-category partition; the most rigorous practitioner-facing multi-agent failure taxonomy currently published.
• Anthropic. (2024). Building Effective Agents. anthropic.com/research/building-effective-agents. — The orchestrator-workers and prompt-chaining patterns; the "start simple" guidance applied here.
• Hong, S., et al. (2023). MetaGPT: Meta Programming for Multi-Agent Collaborative Framework. arXiv:2308.00352. — SOPs as multi-agent coordination protocol; useful comparison to the supervisor model.
• Wu, Q., et al. (2023). AutoGen: Enabling Next-Gen LLM Applications via Multi-Agent Conversation. arXiv:2308.08155. — Conversation-driven multi-agent coordination.
• LangChain. LangGraph Supervisor and Hierarchical Multi-Agent. langchain-ai.github.io/langgraph. — Production reference implementation.
• OpenTelemetry. Semantic Conventions for GenAI. opentelemetry.io/docs/specs/semconv/gen-ai. — Cross-agent observability standard.

Connections

This pattern assumes:

• Pick an Archetype
• Composing Archetypes — for two-archetype layering; this chapter generalizes to N agents
• Failure Modes and How to Diagnose Them

This pattern enables:

• The Orchestrator Archetype — multi-agent governance is the operational specification of Orchestrator deployments
• Coding Agents — when coding-agent deployment is multi-agent (Devin-style), the governance treatment lives here
• Evals and Benchmarks — multi-agent evals require system-level acceptance plus per-seam contract checks
• Red-Team Protocol — multi-agent systems have specific adversarial surfaces (cross-agent injection, handoff manipulation)

Frame in practice — Customer-support agent

Part 1 · FRAME · Scenario 1 of 3

"We haven't framed yet. Pick the archetype first; the spec writes itself once the archetype is committed."

Setting

Mid-stage e-commerce SaaS, ~200 employees, ~50,000 active customers. The customer-support team handles ~3,000 inbound chats per day across two tiers; tier-1 (account questions, order status, returns within policy, refunds within $500) absorbs ~80% of volume. The product manager has greenlit "AI-assisted tier-1 support for the next quarter" with a specific revenue-protection target — 1% reduction in human-support cost, no SLA degradation, no measurable change in CSAT.

The team:

• Maya — engineering tech lead, owns the system end-to-end
• Ari — ML engineer, will write the spec
• Sam — SRE, will own the build and the on-call rotation
• Jordan — full-stack engineer
• Priya — customer-support manager, domain owner (per the RACI Card)

The team gathers for a 90-minute Frame session in a conference room with a whiteboard. Their first instinct, as engineers, is to start specifying — Jordan opens a doc and types "the agent must...". Maya stops them: "We haven't framed yet. Pick the archetype first; the spec writes itself once the archetype is committed." The doc gets closed. The whiteboard gets marker.

The three questions

Before the archetype tree, the team answers the three questions every delegated system has to answer. The whole Architecture of Intent hangs on getting these right; rushing them is the most common Frame failure.

1. What is this system trying to achieve?

The room agrees on: "resolve tier-1 support tickets that fit a documented response repertoire, and route the rest to humans without losing context." Note what the framing rejects: "answer customer questions" (too broad — would license the agent to invent facts about the product), "reduce support cost" (too vague — describes a business outcome, not a system intent), "deflect tickets" (frames the customer as adversarial, sets the wrong incentive).

2. Within what constraints?

Priya owns this answer. The team writes:

• Refund authority is bounded at $500 per transaction; above that, escalate.
• The agent cannot communicate outside the support channel (no email, no SMS, no calls).
• The agent cannot change account ownership, security settings, or billing details.
• The agent cannot promise behavior of other systems ("your refund will arrive in 3 days") without grounding in current SLAs.
• PII may not leave the support context — no copying account numbers into KB lookups, no logs that retain conversational history beyond 90 days.

These are constraints, not preferences. They become §4 NOT-authorized clauses in the spec next phase.

3. How will we know it's working?

The team commits to four signals (the four signal metrics, instantiated for this system):

• Spec-gap rate — amendments per 1000 conversations. Target trajectory: high in month 1 (the spec is new), declining through month 3.
• First-pass validation — % of agent responses Priya's team accepts without rework. Target: ≥ 92% by day 30.
• Cost per resolved ticket — tokens + escalation cost / tickets resolved without human takeover. Target: ≤ $0.40.
• Oversight load — Priya's team's review minutes per 1000 conversations. Target: < 30 minutes.

These are written down before any spec is drafted. If the team can't agree on the targets, they don't yet have the framing they think they have.

The archetype call

The team walks the archetype selection tree, question by question:

Q1 — does the system act, or only inform? It acts: it issues refunds, drafts customer-facing responses, escalates with context. Not Advisor alone.

Q2 — does the system coordinate other agents, or act directly? It acts directly. There is no other agent in the deployment. Not Orchestrator.

Q3 — is the system's primary purpose to block or veto (Guardian) or to act within scope (Executor)? It acts within scope. The refund cap is an invariant the system enforces on itself but the system's primary job is to take action, not to gatekeep someone else's action. Executor.

Q4 — does the action involve combining inputs into a new whole (Synthesizer)? No. The agent retrieves canned responses from a KB and parameterizes them; it doesn't compose a novel response from disparate sources. Not Synthesizer.

The archetype is Executor.

The team considers the risk-override caret on the canvas: "irreversible · regulated · safety-critical → elevate one step toward Orchestrator." Refunds are partially irreversible (a refund to a closed account is not recoverable), and the company is regulated (PCI, GDPR for EU customers). Does this warrant elevation?

The team decides no, for two specific reasons: (1) the refund cap of $500 makes the irreversible portion bounded — even a worst-case unauthorized refund is recoverable through the chargeback workflow; (2) PCI / GDPR concerns are addressed by the §4 NOT-authorized clauses, not by the archetype. Elevating to Orchestrator would imply a coordinator-of-agents shape that the deployment doesn't have. The team commits to Executor and writes the rejection of the elevation in the Frame artifact — so a future reviewer doesn't second-guess the decision without the context.

Composition declaration

The team uses composition first-class (Pattern A — Confirm-then-Act and Pattern B — Executor + Guardian) rather than treating the system as a single Executor. Specifically:

• Executor (governing). The agent acts on tier-1 tickets within the documented response repertoire.
• Advisor (embedded). When the agent escalates to a human supervisor, it does so in Advisor mode — surfacing the relevant KB articles, the candidate response it would have drafted, and its uncertainty. The human picks; the agent doesn't decide for them.
• Guardian (embedded). The refund cap is enforced as a Guardian invariant, not as a soft check. The Guardian fires before the issue_refund tool can be called; if the proposed refund exceeds the cap, the action is blocked and the request escalates.

The Composition Declaration is written explicitly. It will land in §4 of the spec next phase as the Composition Declaration sub-block. The cross-mode invariant — "every customer-facing message is generated by Executor or Advisor mode; Guardian never speaks to customers, only to Executor" — is also written down.

Calibration of the four dimensions

The team works the four orthogonal calibration dials (Calibrate Agency, Autonomy, Responsibility, Reversibility). The temptation is to collapse them into "how autonomous is the agent?" — Maya rejects that explicitly: "Set them independently. Treat each dimension as its own commitment."

The asymmetric Reversibility commitment is the calibration that drives the most downstream design. It means the §11 execution instructions will gate the issue_refund tool differently from the draft_response tool, and the oversight model in §10 will treat refund-bearing conversations differently from message-only conversations.

What this Frame produces

A one-page Frame artifact lands in the team's planning doc:

SYSTEM:        Customer-support agent (tier-1)
ARCHETYPE:     Executor (governing)
COMPOSITION:   + Advisor (embedded, escalation mode)
               + Guardian (embedded, refund-cap invariant)
CALIBRATION:   Agency low · Autonomy low-medium · Responsibility shared · Reversibility mixed
RISK OVERRIDE: Considered (refund irreversibility, PCI/GDPR); rejected — bounded by cap, addressed by §4
THREE QS:      [as above]
SIGNALS:       [the four metric targets, with month-1/month-3 trajectory]

This artifact is the input to Specify in practice — Customer-support agent. The discipline is that nothing in the spec contradicts what's on this page; if a spec section pushes back on the Frame artifact, the team re-runs the Frame discussion before continuing the spec.

The Frame session takes 90 minutes. Maya circulates the artifact for sign-off the same day. Priya signs off as the domain owner. The team starts on the spec the next morning.

Reading path through this scenario

Conceptual chapters this scenario binds to

• Pick an Archetype — the Executor archetype
• Composing Archetypes — Pattern A (Confirm-then-Act), Pattern B (Executor + Guardian)
• Calibrate Agency, Autonomy, Responsibility, Reversibility — the four-dial model
• The Intent Design Session — Frame is its first phase
• Roles & Responsibilities (RACI) Card — Priya as the domain owner

Source material

The earlier v1.x version of this worked pilot is preserved in Designing an AI Customer Support System for reference. The v2.0.0 phase-by-phase form supersedes it; both are kept so readers comparing the framings can see the difference the activity-spine reorganization makes.

Frame in practice — Coding-agent pipeline

Part 1 · FRAME · Scenario 2 of 3

"This is Pattern E, not embedded. The agent doesn't have one shape it sticks to — it shifts modes inside a session, and we have to declare the shift triggers and the cross-mode invariants up front."

Setting

Same e-commerce SaaS as Scenario 1. Sixty days after the customer-support agent's launch, the platform-engineering team meets to commit to the framework for their next system: an in-loop coding agent for tier-1 engineering tasks.

Maya — tech lead from the customer-support team — has been invited to advise as the company's most-experienced framework adopter. The platform team is four people:

• Daniel — platform tech lead, on the hook for the rollout
• Naomi — DevX engineer, will write the spec
• Theo — SRE, will own the build and on-call
• Jess — full-stack engineer, will own integration with the existing CI

The system: an in-loop coding agent in the sense of paper §4.3 — assigned a ticket, produces a branch with commits, surfaces as a pull request for human review. The deployment target is to absorb tier-1 engineering tickets — small bugs, dependency updates, test additions, low-risk refactors — across the company's 17 services. Excluded by category: schema migrations, anything in the auth or billing services, performance-critical paths, public-API contracts. The team's bet is that 30% of tier-1 tickets across the 17 services fit the in-scope shape, and the agent absorbing them frees the engineers for the harder 70%.

The Frame session takes 90 minutes. Daniel opens by naming the pattern Maya warned them about: "the temptation to start prompting now and call it framing later. We won't do that." The team commits the same Frame-before-Specify discipline the customer-support team used.

The three questions

1. What is this system trying to achieve?

The room agrees on: "resolve tier-1 engineering tickets within an authorized scope by producing reviewable PRs, escalating when the ticket is ambiguous or out of scope." What the framing rejects: "reduce engineering toil" (a business outcome, not a system intent), "write code" (too broad — would license arbitrary changes), "do what Cursor does but in CI" (frames the system around a tool rather than around its work). The Frame artifact will reference the agent acts on tickets, produces PRs, and escalates, not the agent writes code.

2. Within what constraints?

Naomi captures these as the seed of §4 NOT-authorized clauses:

• The agent does not push to main or any protected branch under any condition.
• The agent does not modify CI workflows; that surface is platform-team-only.
• The agent does not delete or skip existing tests — the canonical Cat 1/Cat 3 hybrid that paper §4.3 names as the recurring failure pattern.
• The agent does not install global dependencies; package installations are restricted to the curated allowlist.
• The agent has no unrestricted shell access; tool calls are explicitly scoped per mode.
• The agent does not act on tickets in the auth, billing, or payment services. Those touch the regulated surface that Scenario 1's NOT-authorized clauses also bound, and the platform team agrees they are out of scope for v1.

3. How will we know it's working?

The team commits to four signal metrics, instantiated for this system shape:

• Spec-gap rate — amendments per 1000 ticket attempts. Target trajectory: high in month 1, declining through month 3.
• First-pass validation — % of agent PRs merged without the spec being amended in the same window. Target: 80% by day 30 (lower than Scenario 1's 92% because PR review is more involved than message review).
• Cost per merged PR — tokens + reviewer-minutes / merged PRs. Target: under $4.50.
• Oversight load — reviewer-minutes per agent session. Target: < 8 minutes per session by day 30.

The metric definitions are written down before any spec is drafted. The team explicitly chooses cost per merged PR over cost per ticket attempted because the team wants to count successes, not attempts — a session that fails and escalates costs both tokens and reviewer time without producing a merged PR, and the cost ratio should reflect that.

The archetype call

The team walks the archetype selection tree:

Q1 — does the system act, or only inform? It acts (creates branches, writes commits, opens PRs). Not Advisor alone.

Q2 — does the system coordinate other agents, or act directly? It runs a multi-step internal sequence (read repo → plan → implement → review → push → open PR), but it does not coordinate other agents. Each step is an internal mode of the same agent against the same tool manifest. Not Orchestrator.

The team pauses on Q2. The discussion is real: an in-loop coding agent that runs multiple steps internally feels like orchestration. Maya pushes back: "orchestration is when you have multiple agents you're coordinating. This agent has multiple modes. The composition declaration is what captures the modes; the archetype is what governs the deployment as a whole." The team accepts the distinction and moves on.

Q3 — block-or-veto, or act-within-scope? Act within scope (the agent's primary purpose is to produce PRs, not to gatekeep). Executor, not Guardian.

Q4 — compose disparate inputs into a novel whole? Yes-but-secondary — the agent reads the repo, the ticket, the docs, and the existing test suite, and synthesizes a code change. Synthesizer is a candidate archetype. The team's call: synthesis is happening inside the modes (specifically, inside Frame mode and Plan mode), not as the deployment's governing identity. The deployment's job is to act on the synthesis. Executor, with Synthesizer used inside Frame and Plan modes.

The governing archetype is Executor. The system uses Pattern E (mode-switching) composition — the strongest case the framework's composition-first-class commitment from §3.2 of the paper covers.

The risk-override caret is considered: the agent runs without per-step human gates (high autonomy), and writes code that ships when reviewers merge. Is the autonomy too high to be Executor? The team's answer is no — high autonomy is what makes the in-loop deployment shape useful, and the bound on autonomy lives in the manifest, the branch protection, the test-skip-set check, and the spec-conformance CI gate. Each is a structural control that paper §4.3 names. Elevating to Orchestrator wouldn't add structure; it would just rename. The team commits Executor with mode-switching composition. The risk-override consideration is logged.

The mode-switching composition

The team works the four modes the agent will operate in across a session:

The mode transitions are emitted as agent-side markers (<frame>, <plan>, <implement>, <review>) that the trace pipeline records. The transition triggers are deterministic, not model-judgment-based: Frame ends when the agent emits a Plan; Plan ends when the engineer approves the plan or the agent escalates; Implement ends when tests pass and the linter is clean; Review ends when the PR is opened.

The cross-mode invariants are non-negotiable and ship as CI guards, not as prompt rules:

1. Test-skip set is monotonic non-increasing across the session. No test the agent encountered passing may be made to skip or be deleted.
2. Branch protection on main is not bypassed. Even if the model produces a git push origin main command, the manifest does not bind git_push_protected; the call simply fails.
3. No unrestricted shell. No mode binds a generic shell tool.
4. PR description names the spec section the change implements. A PR description without a spec-section reference fails the spec-conformance CI gate.

The Composition Declaration sub-block in §4 of the spec captures all of this. The team's discipline: if a mode transition produces a behavior that violates an invariant, the invariant should fire structurally rather than the prompt being patched to prevent the behavior.

Calibration of the four dimensions

The high-autonomy, medium-reversibility combination is what makes this deployment archetype-distinct from the customer-support Executor: the customer-support agent had low-medium autonomy and mixed reversibility with asymmetric per-class gates; the coding agent has high autonomy and uniform medium reversibility with structural controls compensating for the absent per-step gates.

What this Frame produces

A one-page Frame artifact lands in the platform team's planning doc:

SYSTEM:        In-loop coding agent (tier-1 engineering tickets)
SCOPE:         17 services minus auth, billing, payments, perf-critical paths
ARCHETYPE:     Executor (governing) with Pattern E (mode-switching)
MODES:         Frame (Synthesizer) → Plan (Advisor) → Implement (Executor)
                → Review (Guardian)
CROSS-MODE
INVARIANTS:    test-skip-set monotonic; no protected-branch push; no
                unrestricted shell; PR description names spec section
CALIBRATION:   Agency medium · Autonomy high · Responsibility shared
                · Reversibility medium
RISK OVERRIDE: Considered (high autonomy); rejected — autonomy is bounded
                by structural controls (manifest, CI guards, branch
                protection) rather than per-step gates
THREE QS:      [as above]
SIGNALS:       [the four metric targets]

This artifact is the input to Specify in practice — Coding-agent pipeline. The team starts on the spec the next morning. Maya's parting note: "the spec for a coding agent reads weirder than the spec for the customer-support agent because most of §11 reads like CI rules instead of conversation rules. That's correct — your invariants live in the manifest and CI, so §11 is mostly about how the agent talks about its work, not what it can or can't do."

Reading path through this scenario

Conceptual chapters this scenario binds to

• Pick an Archetype — Executor with mode-switching
• Composing Archetypes — Pattern E (mode-switching)
• Coding Agents — the agent class
• Calibrate Agency, Autonomy, Responsibility, Reversibility

Source material

The earlier v1.x worked pilots in A Code Generation Pipeline and Designing an AI Coding Agent inform this scenario; the v2.0.0 phase-by-phase form unifies them around the in-loop session-scoped shape that paper §4.3 develops.

Frame in practice — Internal docs Q&A (DevSquad)

Part 1 · FRAME · Scenario 3 of 3

"The agent's job is to surface what we have. The valuable thing it does, accidentally, is reveal what we don't."

Setting

Same e-commerce SaaS as Scenarios 1 and 2. Logan's docs-platform team is the third in the company to adopt the Architecture of Intent — they were one of the two teams that asked the platform team for help in Scenario 2's Evolve chapter. Logan's team is small: four people across engineering and docs.

• Logan — tech lead, docs-platform team
• Pri — full-stack engineer, will own the spec and the build
• Devon — DevX engineer, integrations and the eval surface
• Yuki — engineering manager and docs-team representative; serves as domain owner — Yuki owns the company's internal docs at the editorial level

Maya from Scenario 1 is invited to the kickoff in an advisory role — the first-adopter has now mentored two teams. The platform team from Scenario 2 (Daniel/Naomi) provides the spec template and the CI guard scaffolding, but does not run the IDS for Logan's team; the discipline of each team owns its own framing is held.

The system: an internal docs Q&A agent for the company's roughly 200 internal engineers. The agent retrieves and summarizes from the company's engineering documentation — README files across ~80 service repos, an internal Notion space with ~600 pages, an internal wiki (~200 pages), and a curated subset of Slack archives (search-indexed). The deployment target: reduce the time engineers spend answering each other's "where is X documented?" questions, with ~12 minutes saved per question across roughly 180 such questions per week (rough numbers from a one-week instrumentation period).

This team uses Microsoft DevSquad Copilot for their iterative development cycle. The platform team from Scenario 2 set up DevSquad three months ago; Logan's team has been running it for their normal feature work. This scenario is the first time they're applying both DevSquad's eight-phase cadence and the framework's five-activity discipline to the same system. The chapter shows the AoI ↔ DevSquad mapping inline, which is what makes Scenario 3 structurally different from Scenarios 1 and 2.

DevSquad mapping at this phase

The Frame session happens during DevSquad's envisioning phase (the first DevSquad ceremony, before the slice is sized) and the kickoff ceremony at the start of Spec the next slice (DevSquad Phase 2). DevSquad's envision agent and kickoff agent surface prompts that align with the framework's three questions; the team answers them in the DevSquad envision document, and the AoI Frame artifact is a derivative of that document with the archetype, composition, and calibration commitments added.

The composition is clean because both frameworks were derived from observation of practice — DevSquad's envisioning ceremony asks roughly what the framework's three questions ask, and DevSquad's kickoff agent is shaped to land on an ADR that aligns with the framework's archetype call.

The three questions (as the DevSquad envision document captures them)

The team works the three questions during the DevSquad envision ceremony, with envision's prompts surfacing as Socratic questions in the team's IDE. The answers land in envision/01-customer-docs-qa.md per DevSquad's convention.

1. What is this system trying to achieve?

Answer factual questions about the company's engineering documentation with explicit citations to the documents that ground each answer; refuse cleanly when no document grounds the answer with adequate confidence.

The framing rejects: "answer engineering questions" (too broad — would license fabrication), "replace the docs" (frames the agent against rather than alongside the docs team), "make engineers more productive" (a business outcome, not an intent).

2. Within what constraints?

Yuki captures, as the seed of §4 NOT-authorized clauses:

• The agent answers from indexed-public docs only. Unindexed-private docs (HR records, security incidents, payroll, individual performance reviews) are out of scope and not in the retrieval index.
• The agent does not fabricate citations. A claim without a grounded citation does not get emitted.
• The agent does not generate code. Code-generation questions route to engineers' coding-agent pipeline (Scenario 2's system) or to a human reviewer.
• The agent does not make decisions on behalf of teams. Recommendations grounded in docs are answers; recommendations not grounded in docs are out of scope.
• The agent does not answer HR, legal, or security-incident questions. Those route to the appropriate human team.
• The agent does not produce content (drafts, summaries) intended to substitute for a doc. It surfaces what the docs say; it does not synthesize a doc that doesn't exist.

3. How will we know it's working?

The team commits to four signal metrics, instantiated for a Synthesizer:

• First-answer-satisfaction rate — the asker's ★/✘ feedback on each answer; target ≥ 80% in 30-day rolling window.
• Refusal precision — when the agent refuses, was the refusal correct? Target ≥ 92% (the agent should refuse confidently when it should refuse, and answer confidently when it should answer; the rare confused-refusal is acceptable, the systematic-refusal-of-answerable-questions is not).
• Cost per accepted answer — tokens / answers the asker rated ★. Target ≤ $0.012.
• Docs-gap-finding rate — questions that triggered the docs team to author or amend a doc. The team commits to this as a positive signal — high values are good. The agent's most-valuable accidental product is revealing real gaps in the docs.

The team's commitment to the docs-gap-finding metric as positive is the most important framing decision in the Frame session. If the team had framed refusal as a negative metric (which is the obvious framing — refusals are agent failures), the agent would be incentivized to fabricate answers when it shouldn't. By framing refusal that surfaces a real gap as a positive — and by counting docs-amendments-triggered as a separate positive — the team aligns the agent's behavior with what the docs team actually wants from it.

The archetype call (during DevSquad kickoff)

The team walks the archetype selection tree during the DevSquad kickoff ceremony. The kickoff ADR lands on the same call:

Q1 — does the system act, or only inform? It produces text that informs; it does not take actions. Advisor candidate.

But: the system composes an answer from multiple retrieved docs. The compose-an-answer behavior is more shaped than pure Advisor, which would surface options without recommendation.

Q4 — compose disparate inputs into a novel whole? Yes — the agent reads multiple docs, identifies the relevant passages, and composes a coherent answer with citations. Synthesizer.

The team commits Synthesizer as the governing archetype. The kickoff ADR records the call:

ADR-001. Governing archetype: Synthesizer. Rationale: the system's primary act is composing an answer from multiple retrieved documents, with citation discipline. Alternative considered: Advisor. Rejected because the system makes a recommendation (the assembled answer) rather than surfacing options for the asker to choose between.

The risk-override caret is considered: the agent doesn't take actions, so the irreversibility/regulated/safety-critical surface is small. There is one risk worth naming explicitly, though: the citation-fabrication failure mode. A Synthesizer that emits a confident answer with a fabricated citation is the most-dangerous Synthesizer failure — the asker trusts the citation, the citation doesn't ground the claim, and the asker acts on a false premise. The team logs this risk in the kickoff ADR and commits to a §6 invariant covering citation grounding (every cited URL must contain the claimed information; CI-tested with synthetic answer-with-fake-citation probes).

The team rejects elevation to Orchestrator. Synthesizer with embedded Advisor mode for the "I don't have a confident answer" path is the right shape.

Composition declaration

GOVERNING ARCHETYPE:    Synthesizer
EMBEDDED COMPONENTS:    Advisor (low-confidence path)

MODE TRANSITIONS:
  Synthesizer → Advisor: Triggered by retrieval-confidence < threshold
                         (no doc grounds the question with adequate
                         confidence). Advisor mode says "I don't have
                         a confident answer; here's where to look or
                         who to ask."
  Advisor → Synthesizer: Not allowed within a single question. A
                         question that goes to Advisor mode stays
                         there.

CROSS-MODE INVARIANTS:
  • Every output names whether it's a synthesis or an "I don't know" —
    never blurs.
  • Every Synthesizer-mode output cites at least one doc URL and the
    URL contains the claimed information.
  • No Synthesizer-mode answer claims certainty without grounding;
    answers grounded in docs say "the docs say X"; answers grounded
    in inference from the docs say "the docs imply X" or escalate.

The cross-mode invariant every output names whether it's a synthesis or an "I don't know" — never blurs is the load-bearing discipline for this system. A Synthesizer that emits "I think the answer is X but I'm not sure" is the worst shape — it provides false confidence without the structural marker the asker needs to know whether to trust it.

Calibration

The calibration is conspicuously uniform-high-reversibility / low-agency / high-autonomy — the simplest of the three scenarios' calibrations. The simplicity is the point: a Synthesizer that doesn't act has the smallest design surface among the three running scenarios. The team's Frame session takes 60 minutes (vs 90 for Scenarios 1 and 2) because the design surface is smaller.

What this Frame produces

A one-page Frame artifact lands in the team's planning doc, and a companion DevSquad envision document captures the same content per DevSquad's structure:

SYSTEM:        Internal docs Q&A agent (engineering documentation)
ARCHETYPE:     Synthesizer (governing) + Advisor (embedded, low-conf path)
CALIBRATION:   Agency low · Autonomy high · Responsibility distributed
                · Reversibility high
RISK OVERRIDE: Considered (citation-fabrication risk); addressed via §6
                invariant rather than archetype elevation
THREE QS:      [as above; counted in DevSquad envision document]
SIGNALS:       FAS ≥ 80% · refusal precision ≥ 92% · cost ≤ $0.012/accepted ·
                docs-gap-finding rate (positive signal — high is good)

The artifact is the input to Specify in practice — Internal docs Q&A. The Specify phase begins during DevSquad's Spec the next slice phase.

Maya's note at the kickoff: "the docs-gap-finding metric is what makes this scenario interesting. Most teams adopting a docs Q&A agent measure refusal as a negative. By measuring docs-gap-finding as a positive, you've turned the agent into a docs-coverage-discovery instrument that happens to also answer questions. That's a stronger framing than the obvious one."

Reading path through this scenario

Conceptual chapters this scenario binds to

• Pick an Archetype — the Synthesizer entry
• Composing Archetypes — Synthesizer + Advisor (low-confidence path)
• Mapping the Framework to the DevSquad 8-Phase Cadence
• Co-adoption with DevSquad Copilot

Why a third scenario at all

The book commits to three running scenarios for two structural reasons. First, archetype coverage: Scenarios 1 and 2 are both Executor-flavored (customer-support is governing-Executor; coding-pipeline is Executor-with-Pattern-E-mode-switching). Without a Synthesizer-flavored scenario, the framework's archetype taxonomy is demonstrated unevenly — Synthesizer would be a vocabulary commitment without a worked example. Scenario 3 fills that gap.

Second, DevSquad-native team coverage: Scenarios 1 and 2 are framework-only teams (the customer-support team and the platform team adopt the framework but do not use DevSquad). Without a DevSquad-native scenario, the Co-adoption with DevSquad Copilot chapter's vocabulary mapping would be demonstrated only at vocabulary grain. Scenario 3 demonstrates the composition at scenario grain — the DevSquad mapping shows up at every phase chapter, in the actual artifacts the DevSquad team produces alongside the AoI artifacts.

The third scenario is therefore not redundant; it covers a class of system (Synthesizer) and a class of working practice (DevSquad-native) that the other two scenarios do not.

Spec-Driven Development

Part 2 — Specify

"We don't scale by writing more code. We scale by expressing intent clearly enough that systems can build correctly on our behalf."

Context

You have an agent that can write code, call APIs, modify databases, compose documents, and coordinate other agents. You have been using it. Some of its outputs are excellent. Others require significant correction. You are not sure whether the corrections are the agent's fault, your instructions' fault, or simply the nature of the work.

You are about to discover that most of the corrections are the spec's fault — and that you didn't know you were writing a spec in the first place.

This pattern opens Part 2 (The Spec) and assumes the conceptual vocabulary of the prologue and Part 1: intent vs. implementation, agency levels, failure categories, and the archetype framework.

Where this sits in the work: the chapters in Part 2 elaborate the Specify phase of the Intent Design Session — the working session that turns the framework's vocabulary into a calibrated commitment for one specific system. When you are lost, return to the IDS to see where this chapter fits in the per-system rhythm.

The Problem

When organizations first deploy AI agents seriously, they observe a pattern: the first few uses are impressive. The agent produces results rapidly — work that might have taken a developer hours is drafted in minutes. Then, as tasks become more complex, the rework begins. The agent's output needs correction — sometimes small, sometimes large. The team concludes, usually too quickly, that the agent "isn't good enough yet" or that "AI still needs a lot of human oversight."

Both conclusions miss the important point. The agent may well be capable. The more common problem is that the human didn't specify what they wanted precisely enough to tell the difference between a good output and a bad one before seeing it. The specification — whether it was a five-line prompt, a Jira ticket, or a verbal briefing — was insufficient to produce the correct output, and also insufficient to validate it. The human is doing both production and quality control in their head.

This is primarily a clarity problem, though not exclusively. Some failures are genuinely model-level — hallucination, confidence miscalibration, distribution mismatch. But clarity failures are the most common and the most fixable. The clarity gap has always existed in software — it was previously hidden because human developers could read between the lines, ask questions, interpret intent, and apply professional judgment. Agents do not do that. They execute what they are told. The gap between what you intended and what you expressed is now fully visible.

Spec-Driven Development (SDD) is the discipline that closes that gap — not by making agents smarter, but by making humans more precise about what they want before they ask for it.

Forces

• Human comprehension vs. agent execution. Humans tolerate ambiguity and resolve it implicitly; agents execute literal text, making human imprecision immediately visible as incorrect outputs.
• Implicit judgment vs. explicit specification. Human developers applied professional judgment silently; agents have no embedded judgment. Either the judgment goes into the spec, or the agent fills the gap with probability.
• Feedback speed vs. feedback quality. With human developers, feedback was immediate and conversational. Agent-mediated work is slower but buys precision: outputs can be validated against explicit criteria.
• Completeness vs. pragmatism. A complete spec seems heavy. Yet incomplete specs produce more rework. The actual time cost of precision is often less than the perceived cost.

The Solution

What SDD Is

Spec-Driven Development is a development discipline in which a complete, validated specification precedes all agent execution. The spec is:

• Written before any code, test, or implementation artifact is produced
• Detailed enough that a knowledgeable person could verify the output against it without seeing the work in progress
• Structured to be directly consumed by an agent as its primary input
• Treated as the authoritative source of truth — not the code, not the conversation history, not "what we talked about in the standup"

The spec is not documentation. Documentation is produced after the work and describes what was done. A spec is produced before the work and describes what must be done. Documentation explains. Specs constrain.

The spec is not a requirements document in the traditional sense. Traditional requirements documents are written for humans — they use natural language, allow ambiguity, and rely on the reader's judgment to resolve gaps. A spec in SDD is written so that the primary reader is an agent executing the work, and the secondary reader is a human validating the output. Both readers need the same unambiguous interpretation.

The spec is not a conversation. The most common substitute for a spec is a prompt — a sentence or paragraph that gets refined in a conversation with an agent. Conversations are excellent for exploration. They are terrible for execution at scale, because they cannot be reviewed independently, cannot be reused, and cannot be enforced. A spec is not a conversation that got long enough.

What SDD Is Not

SDD is not a return to heavyweight upfront design. The spec is intended to be minimal, not comprehensive — it captures what must be true, not everything that might be relevant. A good spec is shorter than the code it produces.

SDD is not a way to remove human judgment. The human who writes the spec is the person exercising judgment about what matters. Agents execute against that judgment; they do not replace it. SDD concentrates judgment at the front of the process rather than distributing it across a conversation.

SDD is not a way to make agents infallible. Even a perfect spec will occasionally produce an imperfect output. SDD exists to make failure diagnostic — when the output is wrong, you can ask: was the spec right? If yes, it is an implementation failure. If no, fix the spec first.

The Foundational Rules of SDD

Four rules are non-negotiable:

Rule 1: No agent execution without a spec.
Every task delegated to an agent must have a spec that precedes it. The spec may be short. It must exist. A prompt is not a spec unless it contains a complete specification. The test: could a new team member validate the output without talking to you?

Rule 2: Fix the spec, not just the code.
When agent output is wrong, the reflex is to correct the output. The discipline is to ask first: is the spec correct? If the output was wrong because the spec was ambiguous or incomplete, fix the spec and re-execute. Only fix the output directly if the spec was correct and the output violated it.

Rule 3: Review outcomes against the spec, not personal preference.
"I don't like how this is structured" is not a spec violation unless it contradicts something the spec required. Validation questions are: Does this match the spec? If yes, the output is valid independent of preference. If no, the spec governs, not the preference.

Rule 4: The spec is the source of truth.
If the spec and the code disagree, the spec is right. The code is wrong. This is not bureaucratic pedantry — it is the mechanism by which the agent's work remains governable. A spec that is silently overridden by code changes is not a spec anymore; it is a historical document.

The Discipline Shift

SDD requires a genuine shift in where engineering effort is applied. In a pre-agent workflow, engineers spend most of their time producing code and iteratively correcting it via tests and review. In an SDD workflow, engineers spend significant effort producing clear specifications before any production work starts — then validate the output, update the spec based on findings, and re-execute.

The column on the right is not slower. It requires more discipline at the front. But the rework rate is dramatically lower, and the organizational learning is durable — captured in specs that can be reused, reviewed, and evolved — rather than locked in the heads of individuals who were in the room.

Why "Development"

The word "development" in Spec-Driven Development is deliberate. SDD is not spec-driven documentation or spec-driven process. It is a development discipline — it governs how software is built, not just how it is described.

This means SDD applies everywhere a developer would have previously applied their own judgment without writing it down: choosing an architecture, handling an edge case, deciding how an error should be surfaced. In SDD, those judgments belong in the spec. Not because the agent can't make them — but because when it does, they are invisible. When they are in the spec, they can be reviewed, challenged, and revised.

Resulting Context

After applying this pattern:

• Rework rate drops dramatically. When output is validated against explicit criteria, agents produce correct results more often.
• Judgment is concentrated but visible. Rather than judgment being distributed across conversations, it is concentrated in the spec and reviewable before execution.
• Agents become reliable. An agent executing against a clear spec produces consistent, auditable results.
• Organizational memory is durable. The spec captures decision rationale and constraints that transfer when people leave.

Therefore

Spec-Driven Development is the discipline of writing a complete, validated specification before any agent executes work. The spec precedes code; it is the source of truth; and when output is wrong, the first question is whether the spec is wrong. SDD does not make agents smarter — it makes human intent precise enough that execution and validation both become possible.

Connections

This pattern assumes:

• Intent vs. Implementation
• Failure Modes and How to Diagnose Them

This pattern enables:

• The Spec as Control Surface
• The Spec Lifecycle
• The Canonical Spec Template

The Spec as Control Surface

Part 2 — Specify

"A constitution is not a description of government. It is the mechanism that constrains government. The description is history. The constraint is law."

Context

You have adopted the discipline of writing specs before agent execution. Specs exist. Agents use them. But the team still experiences drift — the spec was followed in letter but not in spirit, or the scope widened incrementally without the spec catching it, or a new version of the agent behaved differently against the same spec.

Something is missing. The specs exist as documents, but they are not functioning as control mechanisms. They are being read, not enforced.

This pattern assumes Spec-Driven Development and Pick an Archetype.

The Problem

The most common failure in SDD adoption is treating specs as documentation rather than as control surfaces.

A control surface is something you can act on to change the behavior of a system. A cockpit's controls are not a description of where the plane should go — they are the mechanisms by which the pilot's intent becomes the plane's behavior. Remove a control surface and the intent still exists; it just has no effect.

A spec functions as a control surface when:

• It is consulted before execution begins
• Its clauses are evaluated during validation
• Violations of it trigger a response (either fixing the output or fixing the spec)
• It changes when the intent changes — not after the implementation changes

A spec ceases to function as a control surface when:

• It is written and then not consulted during execution
• Validation consists of human aesthetic judgment rather than spec-conformance checking
• Violations of it are corrected directly in the output without updating the spec
• The implementation evolves and the spec is updated afterward to match

The second pattern looks like SDD. It produces documents that resemble specs. But the spec is not controlling anything — the human is, using the spec as a post-hoc rationalization. The agent is not being constrained by the spec; it is being directed by prompts and corrected by inspection. This is prompt engineering with a document attached.

The distinction matters because the benefits of SDD come specifically from the spec functioning as a control surface. Reusability requires a stable spec that can be run again. Audibility requires a spec that was actually enforced. Organizational learning requires that failures get encoded into the spec, not just corrected in the output.

Forces

• Documentation vs. mechanism. A spec can describe what a system should do or control what it does. The distinction is clear in principle but easy to slip on in practice.
• Constraint vs. preference. Specs must constrain behavior that matters while teams tend to enforce preference. The spec's authority gets divided between non-negotiable and negotiable, weakening both.
• Precision vs. readability. A control surface requires precise, testable language. Making specs precise enough to control agent behavior makes them harder for casual readers.
• Enforcement vs. trust. Making a spec a control surface requires that violations be actioned. Without enforcement, the spec documents what should have happened, not what does happen.

The Solution

What a Control Surface Is

A control surface has three properties:

1. It is consulted at decision points.
The spec is read by the agent at the moment it is executing, not as background context from a conversation. The agent's behavior is directly shaped by the spec's clauses: what it is authorized to do, what it must not do, what it should produce, and what constitutes success. This requires that the spec be structured so relevant sections are accessible when the agent needs them — not buried in prose that requires interpretation.

2. It is checked at validation points.
A human (or a validation agent) explicitly checks the output against the spec. Not "does this look right?" but "does this satisfy clause 6.2? Does it violate invariant 3?" The spec has sections that map to checkable questions. If the spec is so general that you cannot check a specific violation of it, it is not functioning as a control surface — it is providing cover.

3. Changes to it change behavior.
When a spec clause is tightened, the next execution should produce different output. When a scope boundary is clarified, the next execution should respect that boundary. If you can change the spec and the output doesn't change, the agent isn't reading the spec — it's reading the conversation history, the examples, or making up what seems reasonable.

The Hierarchy of Control

Specs are not the only control surface in an intent-engineered system, but they are the primary one. The control hierarchy:

Constitutional layer    — Archetype definitions (what kinds of systems 
                          we're allowed to build and under what terms)
                                ↓
Spec layer              — Intent specification (what this system must do,
                          must not do, and what success looks like)
                                ↓
Invariant layer         — Non-negotiable constraints (clauses that cannot
                          be overridden by any execution)
                                ↓
Execution layer         — Agent action (operates within all layers above)
                                ↓
Validation layer        — Human verification (checks output against spec;
                          feeds back into spec layer)

Each layer constrains the one below it. Constitutional law constrains what kinds of specs can be written. The spec constrains what the agent can do. Invariants within the spec constrain even specification updates. Validation checks that execution respected the spec.

When feedback from the validation layer reveals a problem, the fix propagates upward: if the output was wrong because the spec was wrong, the spec changes. If the spec was wrong because the archetype classification was wrong, the classification changes. If the invariant was too restrictive, the invariant changes — but only through the governance process established for that layer.

Spec Clauses as Control Mechanisms

A spec functions as a control surface through its specific clauses, not its general description. The difference:

Descriptive (not a control surface):

The system should handle errors gracefully and provide useful feedback to users.

Control surface:

Invariant: If any external API call returns a non-2xx status, the system must:

1. Log the failure with: timestamp, endpoint, status code, correlation ID
2. Return a structured error response — not a raw exception
3. Not retry more than once
4. Never surface raw stack traces to the user interface

The descriptive version is not checkable. The control surface version produces a specific set of tests and a specific set of agent behaviors. You can look at an output and determine, clause by clause, whether it was followed.

The key forcing question when writing a spec clause: Could I write a test for this? If you cannot write a test, the clause is not a control surface. It is a preference.

The Spec Is Not the Only Check

Control surfaces require active use. A spec that exists in a repository but is never consulted during execution or validation has no control effect. The organizational practice around specs matters as much as the spec's content:

• Was the spec consulted at the start of execution? (Input control)
• Was the output validated against the spec, not just reviewed generally? (Output control)
• Did a spec violation trigger a spec update, not just an output patch? (Feedback control)
• Was the spec version known at validation time? (Traceability)

These practices are the organizational infrastructure that makes the control surface work. A spec without these practices is a document. A spec with them is a mechanism.

The Temporal Contract

A spec establishes a temporal contract: it describes what must be true at the moment of execution and at the moment of validation. This is different from a living document that logs what happened.

The spec says: "Before this agent runs, these things must be true. After it runs, these things must be verified."

This temporal structure is what makes specs reusable. The same spec can be run again tomorrow, next month, by a different agent, and produce an equivalent outcome because the spec's clauses still describe what must be true. If the clauses are no longer valid — the system changed, the intent changed, the constraints changed — the spec must be updated before the next execution. Not after.

Resulting Context

After applying this pattern:

• Compliance becomes checkable. A spec that is a control surface produces outputs that conform or don't. Conformance can be checked against spec clauses.
• Intent persists through iteration. When the spec is the source of truth, the intent remains stable even as implementation details change.
• Drift becomes costly. When violations must be addressed, there is no incentive to ignore the spec.
• Feedback loops function. Violations feed back into the spec, improving it. The spec becomes richer with use, not stale.

Therefore

A spec functions as a control surface when it is consulted before execution, checked during validation, and updated when intent changes — not after implementation changes. Specs that describe rather than constrain are documentation, not control. The transition from documentation to control requires testable clauses, active use at decision and validation points, and feedback that flows upward into the spec, not sideways into the output.

Connections

This pattern assumes:

• Spec-Driven Development
• Pick an Archetype
• The Intent-Implementation Boundary

This pattern enables:

• The Spec Lifecycle
• Writing for Machine Execution
• The Living Spec

Five Phases of the Spec

Part 2 — Specify

"You do not understand a thing until you can write it. You do not know you have written it correctly until someone can build from it."

Context

You know that specs must precede execution and that they function as control surfaces. Now you need the process: how does a task become a spec, and how does a spec become a validated outcome?

This is the procedural backbone of Spec-Driven Development. It is deliberately not a software development methodology in the project-management sense — it has no sprints, no ceremonies, no artifacts beyond the spec itself. It is a discipline applied to individual tasks delegated to agents.

This pattern assumes Spec-Driven Development and The Spec as Control Surface.

The Problem

Without a named lifecycle, the "spec-first" principle collapses into ad-hoc practice. Different engineers apply the discipline differently. Some write rich specs; others write prompts they call specs. Some validate rigorously; others skim. The feedback loop — the mechanism by which failures become spec improvements — is not practiced because it was never made explicit.

A lifecycle gives the discipline repeatability. It makes the required activities visible, so they can be audited, measured, and improved. It also makes handoffs possible: you can hand a spec to an agent you've never worked with before, and both you and the agent have a shared understanding of what exists at each stage.

Forces

• Discipline vs. freedom. A named lifecycle constrains how teams work. Not having one avoids that constraint but makes practices inconsistent.
• Efficiency vs. completeness. Phase 1 (intent capture) can seem excessive. Yet skipping it produces specs that answer 'how' before establishing 'what.'
• Heavyweight vs. visible. Making the lifecycle explicit creates pressure. But visibility also enables noticing when it is being skipped.
• Reusability vs. context-binding. Each phase produces reusable artifacts. Yet each task is unique. The lifecycle must help without being so prescriptive it prevents legitimate variation.

The Solution

The Five Phases

The SDD lifecycle has five phases. Each phase has a defined input, a defined output, and a defined responsibility assignment.

Phase 1: Intent Capture

Input: A task, goal, or problem statement — in any form.
Output: A written problem statement (one paragraph max) that answers: What problem is being solved? Who is affected? Why now? What breaks if this is not done?
Responsibility: Human (author/requester)

This is the "WHY" phase. Its product is not the spec — it is the raw material the spec will be built from.

The problem statement is deliberately narrow: one paragraph, no implementation. Its only job is to establish that the problem is real, bounded, and understood. If you cannot write a one-paragraph problem statement that survives five minutes of scrutiny, you do not understand the problem well enough to spec it. Stop here and think.

Common failure: skipping Phase 1 entirely and writing a solution first. The output of a Phase 1 skip is a spec that answers "how" before it has established "what" — which reliably produces systems that are built correctly for the wrong purpose.

Phase 2: Specification

Input: Problem statement (Phase 1)
Output: The complete spec, following the canonical template
Responsibility: Human (author, with archetype review if applicable)

This is the "WHAT" phase. The spec captures:

• Desired outcomes (primary and secondary)
• Scope boundaries (in/out)
• Functional intent (what the system must do)
• Non-functional constraints (what it must never violate)
• Invariants (what must always be true)
• Acceptance criteria (how to verify success)
• Assumptions and open questions
• Agent execution instructions
• Archetype declaration (for agent systems)

The spec must be complete enough that a person not involved in writing it can validate an output against it without asking questions. This is the completeness test: Can validation happen independently?

If the spec requires the author to explain it before it can be used, it is not done. Write the explanation into the spec.

Agent-assisted drafting is appropriate here. An agent can generate a first-draft spec from the problem statement. The human reviews and approves it. The approved version is what governs execution — not the draft, not the conversation that produced the draft.

Phase 3: Clarification

Input: Draft spec (Phase 2)
Output: Resolved open questions, refined spec
Responsibility: Human (author) + agent (for clarifying questions); reviewer (for spec approval)

Before execution, the spec is reviewed for gaps:

• Are any assumptions unverified?
• Are any scope boundaries ambiguous?
• Are invariants contradictory or incomplete?
• Can every acceptance criterion be tested?

This phase uses agents effectively: a clarification pass where the agent asks what's missing is one of the highest-value uses of agent capability. "Given this spec, what would you need clarified before you could proceed without asking questions?" The agent's uncertainties are a diagnostic of spec quality.

Phase 3 ends with a formal approval — the spec is marked Approved and the version is locked for the next execution. An approved spec can be changed; the change requires a new version and a new approval. Execution against an unapproved spec is a process violation.

Phase 4: Execution

Input: Approved spec (Phase 3)
Output: Implementation artifacts (code, tests, documents, configuration)
Responsibility: Agent (constrained by spec)

The agent executes against the approved spec. The rules:

• Agents do not make product decisions
• Agents do not override constraints
• Agents surface uncertainty instead of inventing answers
• Agents do not expand scope

If the agent encounters a situation the spec does not cover, it halts and surfaces the gap — it does not resolve the gap autonomously. The gap is a spec deficiency. It becomes an open question that flows back to Phase 3.

During execution, the spec is the agent's primary reference. Not the conversation history. Not the examples in the training data. Not what seems sensible. The spec.

Phase 5: Validation & Learning

Input: Implementation artifacts (Phase 4)
Output: Approved outcomes or identified spec gaps; updated spec
Responsibility: Human (validator)

Validation is performed by a human against the spec, not against personal preference. The validation questions are:

• Does the output satisfy the acceptance criteria in section 7?
• Were the invariants in section 6 respected?
• Were any out-of-scope behaviors produced (violating section 3)?
• What assumptions from section 8 were revealed to be wrong?

After validation, one of three outcomes:

A — Output accepted. The spec was correct, the execution was correct. Log to the spec evolution section: what was learned, any invariants that were confirmed, any assumptions that were validated. The spec is now slightly richer.

B — Output rejected, spec gap. The output was wrong because the spec was incomplete or ambiguous. Fix the spec first. Re-execute. Do not patch the output directly — the patch is local and will not influence future executions. The spec fix is permanent.

C — Output rejected, implementation failure. The spec was correct; the output violated it. This is an implementation-level issue. Fix the output. Also document the failure in the spec evolution log, noting which clause was violated and the failure type. This documentation may eventually suggest that the spec clause needs to be more explicit.

The Lifecycle at a Glance

┌──────────────────────────────────────────────────────────────────┐
│  PHASE 1: Intent Capture                                          │
│  Human writes problem statement (one paragraph)                   │
│  Output: Why we're doing this                                     │
└──────────────────────────────────┬───────────────────────────────┘
                                   ↓
┌──────────────────────────────────────────────────────────────────┐
│  PHASE 2: Specification                                           │
│  Human (± agent draft) writes complete spec                      │
│  Output: Full spec, status = Draft                               │
└──────────────────────────────────┬───────────────────────────────┘
                                   ↓
┌──────────────────────────────────────────────────────────────────┐
│  PHASE 3: Clarification                                           │
│  Agent surfaces gaps; human resolves; reviewer approves          │
│  Output: Spec, status = Approved, version locked                 │
└──────────────────────────────────┬───────────────────────────────┘
                                   ↓
┌──────────────────────────────────────────────────────────────────┐
│  PHASE 4: Execution                                               │
│  Agent executes against approved spec                            │
│  Output: Implementation artifacts                                │
└──────────────────────────────────┬───────────────────────────────┘
                                   ↓
┌──────────────────────────────────────────────────────────────────┐
│  PHASE 5: Validation & Learning                                   │
│  Human validates against spec; categorizes gaps                  │
│  Output A: Accepted + spec evolution log updated                 │
│  Output B: Spec gap → back to Phase 3 with fix                   │
│  Output C: Implementation failure → output fix + log             │
└──────────────────────────────────────────────────────────────────┘

What the Lifecycle Is Not

The lifecycle is not a Waterfall process. Each phase is short — for a well-understood task, Phases 1–3 can be completed in under an hour. The lifecycle applies to an individual task, not a project. A project may have dozens of spec cycles running in parallel.

The lifecycle is not a gate-heavy process. Its approvals are lightweight: "Does this spec answer the completeness test?" The weight is in the thinking, not the ceremony.

The lifecycle is not final on completion. Phase 5 feeds back into Phase 2. Specs accumulate evolution entries. Over time, a reused spec becomes a rich document of what was learned — a form of organizational memory that is directly executable by the next agent that needs it.

Resulting Context

After applying this pattern:

• Handoff becomes possible. With a named lifecycle, a task can be handed off at any phase. The phases make handoff explicit.
• Failure categories are visible. When an outcome is rejected, the reason is clear: spec gap or implementation failure.
• Learning is systematic. Each phase produces a formally validated artifact that becomes organizational history.
• Gatekeeping becomes strategic. Gates are at phase transitions: spec approved before execution, outcomes validated against spec. Few gates, but loadbearing.

Therefore

The SDD lifecycle has five phases: intent capture, specification, clarification, execution, and validation. Each phase has a defined input, output, and responsibility. The feedback from validation flows back into the spec — not into the output — so that every failure makes the next execution better. The lifecycle is not a project methodology; it is a discipline applied to every individual task delegated to an agent.

Connections

This pattern assumes:

• Spec-Driven Development
• The Spec as Control Surface

This pattern enables:

• SpecKit
• Writing for Machine Execution
• The Living Spec
• The Canonical Spec Template

Writing for Machine Execution

Part 2 — Specify

"If you can't specify it, you don't understand it well enough yet."

Context

You know what a spec needs to contain and how it functions as a control surface. Now you are sitting down to write one. The blank page presents the same challenge it always does — but with a new constraint: your primary reader is not a human colleague. It is an agent that will execute against your words without asking for clarification, without applying professional judgment, and without reading between the lines.

Writing for an agent requires different craft than writing for a human. This pattern describes the specific differences.

This pattern assumes all preceding SDD patterns and Four Dimensions of Governance.

The Problem

Most technical writers — including experienced engineers — have internalized that their audience is human. Human readers tolerate ambiguity, resolve contradictions using context, ask questions when confused, and apply tacit knowledge that was never written. Professional communication is full of compressed meaning that expert readers expand correctly.

Agents do not do any of this. They execute the literal text. Ambiguity produces arbitrary resolution. Contradiction produces unpredictable behavior. Missing context produces questions, hallucinations, or failures. Tacit knowledge that wasn't written doesn't exist.

This is not a limitation to be engineered around. It is a clarifying property: writing for agents reveals what was actually imprecise in your thinking. The places where you struggle to write a clause that an agent could follow without asking questions are exactly the places where a human colleague would have silently applied their own judgment — judgment that might not match yours.

The discipline of writing for agents closes the gap between what you intended and what you expressed. It makes implicit decisions explicit, which makes them reversible, auditable, and transferable.

Forces

• Natural language vs. formal specification. Natural language is expressive but ambiguous. Agents need precision but teams want readability. The spec must bridge both.
• Expert knowledge vs. explicit knowledge. Domain experts have mental models of what should be done. Encoding that knowledge explicitly is work. Yet it is the only way the knowledge transfers to an agent.
• Completeness vs. brevity. Adding detail makes specs more correct but longer. The spec must be minimal yet complete enough for execution without questions.
• Inspiration vs. direction. Some teams use specs to inspire creativity. Agents cannot work from inspiration; they need direction.

The Solution

Principle 1: Specify WHAT and the constraints, never HOW

A spec specifies observable outcomes, not implementation paths.

Weak (specifies how):

The system should use a caching layer to optimize performance. Use Redis with a 5-minute TTL on user profile lookups.

Strong (specifies what and constraint):

User profile data must be returned in under 100ms at P95 for authenticated requests. The solution must not require a database hit on every request for data unchanged in the last hour.

The first version locks an implementation. It will be followed literally — the agent will use Redis with a 5-minute TTL even if caching is not the right solution, or if the TTL should be different for different use cases. The second version constrains what must be true while leaving the implementation open. The agent can choose the best approach; you can evaluate whether the constraint was met.

The forcing question: Am I specifying what the system must do, or am I specifying how I would implement it?

Principle 2: Name every constraint explicitly

Agents do not infer constraints from adjacent context. A human reading "this system processes medical records" immediately applies their knowledge of HIPAA, data handling standards, and the general sensitivity of the domain. An agent applies what you wrote.

Write the constraints. All of them.

Missing constraint:

The system processes patient medication schedules and sends reminders.

Explicit constraints:

The system processes patient medication schedules and sends reminders.

Constraints (non-negotiable):

• No patient data is stored beyond the active session; only medication schedule IDs are persisted
• Reminder messages must not include medication names or dosage details — only appointment times
• System errors visible to patients must never include technical detail or data references
• All outbound messages require a confirmed opt-in on record before dispatch

Each of these would be obvious to a domain expert. An agent is not a domain expert unless you make it one — in the spec.

Principle 3: Write success criteria that can be tested without you

Acceptance criteria in a spec are not a description of what good looks like. They are a set of verifiable conditions that, if all true, constitute success.

Not testable:

The interface should be intuitive and responsive.

Testable:

• All primary user actions (create, edit, delete, submit) complete within 2 seconds for datasets up to 1000 records
• On any page, a user who has not seen the product before can identify the primary action within 30 seconds (validated via usability review with 3+ test users)
• No action requires more than 3 steps from the main navigation

The test for a good acceptance criterion: Could a person who has never spoken to me determine whether this criterion was met by examining the output? If yes, it is a good criterion. If no, it needs to be rewritten.

Principle 4: State the invariants separately from the behaviors

Invariants are constraints that are always true, under all conditions, regardless of other decisions an agent might make. They are different from non-functional requirements (which may have acceptable degradation) and different from acceptance criteria (which describe success on the primary path).

Invariants are non-negotiable, unconditional, and frequently the clauses that an agent will silently violate if they are only implied.

Write invariants as their own section. Use absolute language.

Behavioral requirement (can be traded off):

The system should retry failed API calls up to 3 times.

Invariant (cannot be traded off):

The system must never send a user-facing message that contains raw exception text, stack traces, or internal error codes.

The first requirement can be loosened under certain conditions. The second cannot. Agents make decisions about requirements; they must obey invariants. If you write them in the same section with the same tone, the agent will treat them with equal discretion.

Principle 5: Write agent execution instructions as a direct address

The agent execution section of the spec is not documentation about what the agent will do. It is a direct instruction to the agent. Write it in second person, imperative.

Documentation voice (not direct):

The agent will generate source code based on the functional intent above. It should avoid making product decisions and escalate when scope is unclear.

Direct instruction (effective):

Agent instructions:

• You are authorized to: generate source code, generate tests, generate inline documentation
• You are NOT authorized to: make architectural decisions not specified here, expand scope beyond section 3, resolve open questions in section 8 without surfacing them
• If you encounter a situation this spec does not cover: stop execution, list the specific gap, and present it for human resolution before continuing
• If the spec appears to have a contradiction: do not resolve it by choosing one side; surface the contradiction

This distinction matters because agents read documents from the perspective of their role. A section labeled "Agent Instructions" in second-person imperative is read as instructions. A section describing what the agent will do is read as context — and context is lower-priority than instructions.

The Three Anti-Patterns

Anti-pattern 1: The Vision Document

Signs: Lofty goals, no scope limits, no acceptance criteria.

"Build a system that delights customers by providing instant, intelligent answers to their questions."

An agent executing against a vision document is writing the spec itself — which means it is making all the decisions the spec should have made. The output will be coherent but wrong, because the implicit decisions the agent made are not the ones you would have made.

Anti-pattern 2: The Implementation Prescription

Signs: Specific technology choices, class names, function signatures, data structures not derived from constraints.

"Create a class called UserSessionManager with a method invalidateSession(userId: string) that calls the Redis client to delete the key session:{userId}. Use LRU eviction with a max of 10,000 keys."

An agent executing against an implementation prescription is a transcription service. It will follow the instructions, produce exactly what was specified, and miss any better approach the agent would have found if given the freedom to. More practically: the output is predetermined, so why involve an agent at all?

Anti-pattern 3: The Conversation Transcript

Signs: Context that builds over many paragraphs, references to "we discussed" or "as mentioned above," requirements that only make sense in context of preceding paragraphs.

A spec must stand alone. It will be read by an agent — and by future humans — who were not present for the conversation that produced it. Every decision in the spec should be self-evidently justified within the spec. If it requires context that isn't in the spec, put the context in the spec.

The Quality Signals

A spec ready for agent execution shows these properties:

• Can be handed to someone who wasn't involved in writing it and used immediately
• Has no acceptance criteria that requires the author to explain it
• Has explicitly stated invariants distinct from requirements
• States scope out-of-bounds explicitly, not just what's in-scope
• Has agent execution instructions in direct, second-person imperative
• Has an archetype declaration (for agent systems)
• Contains no implementation choices not derived from stated constraints

A spec that passes this checklist is machine-executable. A spec that fails it will require conversation during execution — which collapses SDD back into prompt engineering.

Resulting Context

After applying this pattern:

• Imprecision becomes visible. Writing for agents reveals where human communication relies on impression and judgment. Making this explicit allows deliberate decisions about what to specify vs. delegate.
• Requirement clarity improves. Specs written for agents often end up clearer for other humans too.
• Validation becomes independent. A spec written precisely enough for an agent can be validated by someone who was not involved in writing it.
• Reuse becomes possible. A clear, complete spec can be run again months later, by a different agent, and produce an equivalent outcome.

Therefore

Writing for agents requires specifying WHAT and constraints, never HOW; naming every constraint explicitly that a human expert would know but an agent would not; writing acceptance criteria that can be tested without the author present; stating invariants as a separate unconditional section; and writing agent instructions as direct second-person imperatives. The anti-patterns — vision documents, implementation prescriptions, and conversation transcripts — all fail by either under-constraining or over-specifying, leaving the agent to make decisions the spec should have made.

Connections

This pattern assumes:

• Spec-Driven Development
• The Spec as Control Surface
• The Intent-Implementation Boundary

This pattern enables:

• The Canonical Spec Template — every section in the template was designed for this reading audience
• Spec Template Library

The Living Spec

Part 2 — Specify

"A spec that is never wrong has never been used."

Context

You have been practicing SDD. Specs are written before execution. Agents execute against them. Outputs are validated. Some validations reveal problems.

Now you need to decide what to do when the spec was wrong. How should the spec change? When should you fix the spec versus fix the output? How do you make sure the learning from a failure is encoded so the next execution benefits from it?

This pattern assumes all preceding SDD patterns.

The Problem

Two failure modes appear in teams that practice SDD but haven't closed the feedback loop:

Failure Mode 1: Output patching. The validation in Phase 5 reveals a problem. The engineer fixes the output directly. The spec remains unchanged. The next time a similar spec is written, or the same spec is run, the same problem reappears. The engineer patches it again. The spec is a fossil — it preserves the original intent at the moment of writing, not the current understanding.

Failure Mode 2: Spec churn. Every validation triggers a spec update. The spec is modified constantly, often in response to preference changes rather than genuine spec deficiencies. The spec version history is noise rather than signal. No one knows which version of the spec represents current practice. The spec has become a conversation transcript in markdown format.

Both failures share a diagnosis: the feedback loop from execution to spec is not governed. Either nothing flows back, or everything does. A living spec requires a governed feedback loop — specific conditions that trigger spec updates, and a version history that records why the spec changed, not just what changed.

Forces

• Learning vs. stability. Specs must change as understanding deepens, but continuous change makes the spec unstable. The feedback loop must allow learning without allowing constant thrashing.
• Spec gaps vs. implementation failures. When output is wrong, there are two possible explanations. The response is dramatically different. Yet being certain which applies requires judgment.
• Organizational memory vs. noise. The spec evolution log should record what was learned. But if every preference change gets logged, the log becomes noise.
• Experimentation vs. governance. Some changes are worth trying as experiments. Other changes are constitutional. The feedback loop must allow experimentation while protecting constitutional constraints.

The Solution

What Makes a Spec "Living"

A living spec is not a spec that changes all the time. It is a spec that:

1. Evolves as understanding deepens — when a failure reveals that the spec was wrong, the spec is updated to correct the understanding
2. Has a traceable history — every version carries the reason for the change, who made it, and what triggered it
3. Can be run at any version — any historical version of the spec represents a complete, valid specification that could be executed, even if it is no longer the current version
4. Accumulates validation evidence — over time, the spec records which assumptions were confirmed, which invariants were tested, and what was learned from failures

A living spec is an organizational memory artifact. It records not just what was intended, but the process of learning what the right intention is.

The Feedback Trigger Taxonomy

Not every validation finding should trigger a spec update. The taxonomy:

Spec gap (always triggers spec update):
The output was wrong because the spec didn't say what was needed. The spec was silent on an important behavior, the scope boundary was ambiguous, or an invariant that should have been stated wasn't. Fix the spec. Re-run.

Example: The spec said "process all incoming orders." An agent processed cancelled orders. The spec needed to say "process all orders with status = active."

Spec ambiguity (always triggers spec update):
The spec said something that could be interpreted two reasonable ways, and the agent's output reflected the wrong interpretation — not because the model "chose," but because the prompt left both readings within the probable-output region and the model produced one of them. This is also a spec failure: the expression was imprecise. Rewrite the clause to be unambiguous so the probable-output region narrows to the intended reading.

Example: The spec said "log all errors." The agent logged errors to stdout. The spec needed to say "log all errors to the structured error log at [path], with schema [defined schema]."

Spec over-constraint (may trigger spec update, requires judgment):
The spec stated an invariant or requirement that turned out to be incorrect given the actual system behavior. A Guardian's rejection rate is too high because the constraint was miscalibrated. Consider carefully before relaxing — the constraint may have been too tight, or the system may need to change.

Example: An invariant said "never delete records." The system needs soft deletes for compliance. The invariant should say "never permanently delete records without archival."

Implementation failure (does NOT trigger spec update, may trigger spec clarification):
The spec was correct; the agent violated it. Fix the output. If the failure suggests the spec clause could be more explicit to prevent recurrence, add an explanatory note or example to the spec — but do not change the clause itself.

Preference change (does NOT trigger spec update):
The spec was correct, the output matched the spec, but the engineer prefers a different approach. This is not a spec failure. If the preference represents a genuine requirement, it should be added to the spec for future executions — explicitly, as a requirement, not retroactively applied to the current output.

How this taxonomy relates to Cat 1–7

The feedback-trigger taxonomy above asks "should this update the spec?" The book's diagnostic taxonomy (Cat 1–7) asks "which artifact has to change?" They are complementary, not duplicative:

A finding that's pure Cat 6 (model limit) doesn't trigger a spec update; it triggers acceptance and a structural mitigation. Everything else in this table flows into the evolution log below.

The Spec Evolution Log

Every spec should have a version history section — the spec evolution log. It is not optional.

Structure:

## Spec Evolution Log

| Version | Date | Change | Trigger | Author |
|---------|------|--------|---------|--------|
| 1.0 | 2025-01-10 | Initial specification | New work | J. Smith |
| 1.1 | 2025-01-18 | Added invariant: no-delete | Validation gap (v1.0 execution produced hard deletes) | J. Smith |
| 1.2 | 2025-02-03 | Clarified scope: active orders only | Spec ambiguity (agent processed cancelled orders) | A. Chen |
| 1.3 | 2025-02-28 | Updated acceptance criteria: P95 latency to 150ms | System changed (new downstream latency budget) | J. Smith |

The evolution log has three functions:

Diagnostic: When something goes wrong, the evolution log tells you whether this kind of problem has occurred before — and whether it was fixed at the spec level or just patched in the output.

Educational: A new team member reading the spec evolution log understands the history of decisions: what was tried, what failed, and what was learned. This is organizational memory that would otherwise exist only in the minds of the people who were present.

Governance: The evolution log makes it possible to audit whether the "fix the spec" rule was followed. If the log is sparse while the issue tracker is full of bugs that appeared in repeated executions of the same spec, the feedback loop is broken.

The Spec Gap Log

Related to the evolution log, but distinct: the spec gap log is a running record of situations that fell outside what any existing spec covers. It is the place where "this came up and we didn't have a spec for it" goes.

The spec gap log is input to new spec creation, not to existing spec updates. Its entries look like:

- 2025-02-14: Agent asked about handling cases where an order has 
  no items. No coverage in current spec. Resolved ad hoc (skip). 
  Needs a spec clause or separate spec for empty-order handling.
  
- 2025-03-01: Two engineers made different decisions about whether 
  validation errors should abort the full batch or skip individual 
  records. Needs a declared invariant.

Spec gaps are not failures. They are opportunities. A team that maintains a spec gap log is systematically discovering the boundaries of their current understanding and scheduling the work to fix them.

The Rule: Fix the Spec, Not the Code

The central discipline of the living spec is this: when the output is wrong because the spec is wrong, fix the spec first.

This rule is harder to follow than it sounds. The direct path is to fix the output — it is visible, immediate, and satisfying. The spec fix is invisible; no one sees the evolution log entry; the benefit is deferred to future executions.

The organizational cost of not following this rule is the gradual loss of the spec as a control surface. A spec that is routinely overridden by output patches is a spec where the agents are not actually constrained by the document — they are constrained by whatever the last human correction was. The spec describes an intent that no longer governs anything.

The way to make this rule stick: make the spec update part of the same change as the output fix. If you are fixing output and the fix represents a genuine spec gap, update the spec in the same PR. The habit is "spec update + output fix together," never "output fix alone when the spec was wrong."

When a Spec Becomes a Repository Asset

Over time, a well-maintained living spec becomes something more valuable than a task description: it becomes a repository of decisions.

A spec that has been run five times, validated five times, and evolved through three rounds of feedback carries:

• The original problem statement
• The decisions made about scope
• The constraints discovered through operation
• The invariants that were tested and confirmed
• The failure modes that were encountered and addressed

This is the spec as organizational learning. It is the documentation that actually gets read, because it contains the map of what went wrong and why. It is the onboarding artifact for a new engineer or agent. It is the audit trail for a compliance review.

The teams that create this kind of asset are not more disciplined than others. They are teams that closed the feedback loop: they made spec updates the response to spec failures, consistently, over time.

Resulting Context

After applying this pattern:

• Failure drives improvement. When a failure triggers a spec update instead of an output patch, the next execution learns from the failure. The spec gets richer.
• Organizational learning is durable. The spec evolution log records what was learned, when, and why. This becomes institutional memory.
• Spec authority is preserved. A spec that is consistently updated on failure remains the source of truth.
• The feedback loop closes. Validation flows back into the spec, making the system self-improving.

Therefore

A living spec is not a spec that changes constantly — it is a spec that evolves when failures reveal that the spec was wrong, with a traceable history of why each change was made. The feedback loop from validation to spec must be governed: spec gaps and ambiguities always trigger spec updates; preference changes and implementation failures do not. The rule "fix the spec, not the code" protects the spec's function as a control surface. Over time, a well-maintained living spec becomes an organizational memory artifact: the full map of what was intended, what was learned, and what was decided.

Parallel work

The "living spec" framing is convergent across several practitioner sources arriving at the same conclusion through different routes:

• GitHub spec-kit uses living specs as the source-of-truth artifact in its spec-driven development methodology.
• Microsoft DevSquad Copilot treats specifications and ADRs as continuously refined artifacts forming a "shared memory" across multi-developer teams, with formal amendment processes triggered when implementation reveals mismatches. See Microsoft DevSquad Copilot.

The convergence is informative: independent teams approaching agent-augmented development from different angles end up with the same load-bearing concept. This isn't original to the book and shouldn't be treated as such.

Connections

This pattern assumes:

• The Spec as Control Surface
• The Spec Lifecycle
• Failure as Diagnostic Signal

This pattern enables:

• The Canonical Spec Template — the spec evolution log section
• Governed Archetype Evolution — the same feedback principle applied to archetype classification

The Canonical Spec Template

Part 2 — Specify

"A spec is a contract between humans and agents. Its clauses are the terms. The agent's output is the performance. Validation is the audit."

Context

A team has finished its Frame session. The Frame artifact is on the wall: archetype committed, dimensions calibrated, three questions answered. Now someone has to write the spec. The lead opens an empty doc and pastes in the canonical 12-section template. The cursor sits at §1. "Where do I start?"

This chapter is the answer. The template is reference material, not a checklist; you don't fill it out from §1 through §12 in order. You fill the structural commitments first — §3 Authorized scope, §4 NOT-authorized scope (with the Composition Declaration and Cost Posture sub-blocks), §6 Invariants — and let the rest fall out from those. This chapter walks each section with examples of strong and weak entries, so the cursor at §1 has somewhere to go.

You have understood the principles of Spec-Driven Development. You need the artifact.

This pattern is different from the others in Part 2: it is primarily reference material. It presents the canonical spec template in full, with an explanation of each section, the key questions each section must answer, and examples of what good and weak entries look like.

Use this pattern as:

• The primary reference when writing a new spec
• The evaluation framework when reviewing a spec
• The structural model when building project-specific template variants
• The template fragment library when adding spec sections to SpecKit's constitution

This pattern assumes all of Part 2.

The Canonical Spec Template

Copy the template below as the starting point for any spec. Sections marked [required] must be present and complete before the spec is marked Approved. Sections marked [required for agent systems] are required when the spec describes an agent-class system.

# [Spec Title]

**Status:** Draft | Approved | In Progress | Validated | Superseded  
**Version:** 1.0  
**Owner:** [Name / Role]  
**Date:** [YYYY-MM-DD]  
**Archetype:** [Classification / Agency Level] — [required for agent systems]

---

## 1. Problem Statement [required]

*One paragraph maximum.*

[What problem are we solving? Who is affected? Why does this matter now? 
What would break or be lost if this were not solved?]

---

## 2. Desired Outcome [required]

**Primary Outcome**

[The single most important thing that must be true when this is successful.
Written as an observable state, not an activity.]

**Secondary Outcomes** *(optional)*

- [Additional benefit that would be valuable but is not required for success]
- [Another secondary outcome]

> Success is defined by observable outcomes, not implementation choices.

---

## 3. Scope [required]

**In Scope**

- [Explicitly included behavior or capability]
- [Another included behavior]

**Out of Scope**

- [Explicitly excluded behavior or capability — what this will NOT do]
- [Another excluded behavior]

> This section prevents agents and humans from over-building.
> If something is not listed here, it is out of scope by default.

---

## 4. Archetype Declaration [required for agent systems]

**Classification:** [Advisor | Executor | Guardian | Synthesizer | Orchestrator]  
**Agency Level:** [1–5] — [Label and one-line justification]  
**Risk Posture:** [Low | Medium | High | Critical] — [One-line rationale]  
**Oversight Model:** [A | B | C | D] — [One-line description of the oversight mechanism]  
**Reversibility:** [R1 | R2 | R3 | R4] — [One-line description of recovery options]

**Composition Declaration** *(required for systems with embedded components or mode-switching; omit for single-archetype systems)*

For composed systems, declare the governing archetype above and list the embedded components or modes here. See [Composing Archetypes](../frame/05-composing-archetypes.md) for the patterns and the structural rationale.

- **Composition pattern:** [A: Confirm-then-Act | B: Executor + Guardian | C: Orchestrator with typed sub-agents | D: Compose-then-Publish | E: Mode-switching | Other — describe]
- **Embedded components or modes:**
  - [Component / Mode 1] — [archetype role, one-line purpose]
  - [Component / Mode 2] — [archetype role, one-line purpose]
- **Mode transitions** *(Pattern E only)*: [Transition 1 — trigger, what state carries across]; [Transition 2]
- **Cross-mode / cross-component invariants** (hold regardless of active mode or layer): [list — these are what §6 Invariants enforces at the system level]
- **Per-component / per-mode oversight notes** (referenced from §11): [Component 1: oversight model]; [Component 2: oversight model]

**Cost Posture** *(required for systems running in production at any scale; omit only for true throwaways at the [MVP-AoI](../evolve/16-minimum-viable-aoi.md) floor)*

Cost is *not* a fifth calibration dimension — it is a *resource* commitment that the four behavioral dimensions partly determine and partly leave open. Declare the parts left open here. See [Calibrate Agency, Autonomy, Responsibility, Reversibility — Cost is not a fifth dimension](../foundations/03-agency-autonomy-responsibility.md#cost-is-not-a-fifth-dimension) for the structural rationale, and [Cost and Latency Engineering](../operate/02-cost-and-latency.md) for the operational treatment this sub-block sits above.

- **Model-tier commitment** (per step where relevant): [step-name → tier (Reasoning / Frontier / Mid / Fast); one-line rationale]; [next step → tier]; *…*
- **Latency budget**: p50 = [value]; p95 = [value]; p99 = [value]. *Behavior on breach:* [degrade · alert · halt — one of].
- **Prompt-stability invariant**: [which prompt elements (system prompt, skill files, persistent context) are guaranteed stable across runs to support caching; what change would break the invariant and trigger a spec amendment]. See [Cacheable Prompt Architecture](../operate/03-cacheable-prompt-architecture.md).
- **Per-call cost ceiling**: hard cap = [tokens or dollars]. *Behavior on breach:* [escalate to §11 oversight gate · halt with audit-log entry · degrade to a cheaper tier — one of].
- **Cost-incident escalation**: [what cost-side condition triggers a stop or a human-review gate — e.g. "any single call exceeding the per-call ceiling," "cumulative cost exceeding $X across N runs," "cache-hit-rate dropping below Y for M consecutive runs"]. Connects to §11 Agent Execution Instructions.

*The operational target this calibration serves is the **cost-per-correct-outcome** signal metric (§12 Validation Checklist; [Four Signal Metrics](../validate/06-metrics.md)). The Cost Posture sub-block is what the spec author commits to upstream; the metric is what the operator measures downstream.*

*For archetype definitions, see the [Intent Archetype Catalog](../frame/02-canonical-intent-archetypes.md). For composition patterns and the Pattern E mode-switching structure, see [Composing Archetypes](../frame/05-composing-archetypes.md).*

---

## 5. Functional Intent [required]

*Describe what the system must do, not how.*

**Core Capabilities**

- The system must [capability 1 — observable, testable]
- The system must [capability 2]
- The system must [capability 3]

**The system must NOT:**

- [Forbidden behavior 1 — explicit exclusion]
- [Forbidden behavior 2]

**Key Flows** *(for complex systems)*

- Flow A: [User/system action] → [system response] → [outcome]
- Flow B: [User/system action] → [system response] → [outcome]

> Use clear declarative language: "The system must..." and "The system must not..."
> Do not describe implementation. Describe observable behavior.

---

## 6. Invariants [required]

*These conditions must always be true. They cannot be traded off for 
performance, convenience, or edge-case handling. Violations are failures 
regardless of other spec compliance.*

1. [Invariant 1 — absolute, unconditional]
2. [Invariant 2]
3. [Invariant 3]

> If any invariant is ever wrong, it must be updated via the spec evolution 
> process — never silently violated.

---

## 7. Non-Functional Constraints [required]

| Category | Constraint | Testable Threshold |
|---|---|---|
| Performance | [Requirement] | [e.g., P95 response < 200ms] |
| Reliability | [Requirement] | [e.g., graceful degradation on downstream failure] |
| Security | [Requirement] | [e.g., no PII in logs] |
| Compliance | [Requirement] | [e.g., must satisfy policy X] |
| Cost | [Requirement] | [e.g., < $X/month at 10k requests/day] |
| Scalability | [Requirement] | [e.g., must support N concurrent users] |
| Observability | [Requirement] | [e.g., all errors logged with correlation ID] |

*Remove rows that genuinely don't apply. Add rows for constraints specific to 
this system.*

---

## 8. Authorization Boundary [required for agent systems]

**This system is authorized to:**

- Read: [specific data sources, scopes, access levels]
- Write to: [specific targets, with conditions]
- Call: [specific APIs or services, with rate limits or conditions]
- Invoke: [specific sub-agents or tools, with invocation conditions]

**This system is NOT authorized to:**

- [Explicit exclusion 1]
- [Explicit exclusion 2]

**Exception gate:**  
Any situation not covered above → [halt | escalate | log and continue] and surface to [designated role/process].

---

## 9. Acceptance Criteria [required]

*Define success in testable terms. If it cannot be tested or measured, it is 
not complete.*

**Functional Acceptance**

- Given [precondition], when [action], then [expected result]
- Given [precondition], when [action], then [expected result]
- [Edge case]: given [precondition], when [action], then [expected result]

**Non-Functional Acceptance**

- [Metric/threshold that proves a non-functional constraint was met]
- [Another metric]

> Acceptance criteria are what Phase 5 validation checks. Write them so 
> they can be evaluated independently of the author.

---

## 10. Assumptions and Open Questions

**Assumptions** *(things believed to be true but not verified)*

- [Assumption 1] — *Owner: [who should verify this]*
- [Assumption 2]

**Open Questions** *(decisions that must be made before execution)*

- [Question 1] — *Owner: [who decides]* · *Decision needed by: [date or phase]*
- [Question 2]

> Agents must surface uncertainty rather than invent answers. If an open 
> question remains unresolved at execution time, the agent should halt and 
> surface it rather than decide autonomously.

---

## 11. Agent Execution Instructions [required for agent systems]

*Written directly to the agent. Second person, imperative.*

**Skills to load** *(optional)*

- [skill-name]: [Why this skill is relevant to this task]
- [skill-name]: [Scope or conditions under which to apply it]

> Skills teach domain-specific workflows and organizational context. List only 
> skills that are directly relevant. If no skills apply, omit this sub-section.
> See [Agent Skills](../delegate/05-agent-skills.md) for the skills framework.

**You are authorized to:**

- [Action type 1]: [Scope or conditions]
- [Action type 2]: [Scope or conditions]

**You are NOT authorized to:**

- Make decisions not specified in this spec
- Expand scope beyond section 3
- Resolve open questions in section 10 without surfacing them first
- [Specific forbidden action]

**If you encounter a situation this spec does not cover:**  
Stop execution. List the specific gap. Present it for human resolution before continuing.

**If this spec appears to have a contradiction:**  
Do not resolve it by choosing one side. Surface the contradiction.

**Required outputs from this execution:**

- [ ] [Output artifact 1]
- [ ] [Output artifact 2]
- [ ] [Any additional deliverable]

---

## 12. Validation Checklist [required]

*Completed by the human validator after execution. Check against the spec, 
not against preference.*

- [ ] Output satisfies the Desired Outcome (section 2)
- [ ] All acceptance criteria in section 9 are met
- [ ] No invariants in section 6 were violated
- [ ] No out-of-scope behaviors were produced (section 3)
- [ ] Authorization boundary (section 8) was respected
- [ ] All assumptions in section 10 were either validated or remain pending
- [ ] Spec evolution log updated based on findings (section 13)

> If validation fails: categorize the failure (spec gap, spec ambiguity, 
> or implementation failure) before deciding how to respond.

---

## 13. Spec Evolution Log [required]

*Specs are living artifacts. Every change is recorded here with its reason.*

| Version | Date | Change Summary | Trigger | Author |
|---------|------|----------------|---------|--------|
| 1.0 | [date] | Initial specification | New work | [name] |
| | | | | |

---

## 14. Planned Evolution *(optional)*

*Use when this spec represents Phase 1 of a planned transition.*

**Current classification:** [Archetype and agency level]  
**Target classification (Phase N):** [Target archetype and agency level]  
**Transition criteria:**

- [Criterion 1 that must be met before transitioning]
- [Criterion 2]

**What will NOT change at transition:** [Invariants that carry forward]

Section-by-Section Guidance

Section 1: Problem Statement

Purpose: Establish shared understanding of why this work exists.

Key questions it must answer:

• What is broken, missing, or inadequate?
• Who experiences the problem, and how?
• Why address it now? (If the answer is "we're just supposed to," that's a sign the problem statement isn't done.)
• What is the observable cost of not solving it?

Weak:

"We need a better way to handle customer support."

Strong:

"Customer support agents spend an average of 12 minutes per ticket searching across 4 internal systems for relevant account history. This delay causes a 23% first-contact-resolution gap against our SLA. The information exists; the problem is retrieval time. This becomes critical in Q2 when support volume is projected to double."

The strong version is falsifiable: you can measure the 12 minutes, the 23% gap, the Q2 projection. The solution can be validated against it.

Section 2: Desired Outcome

Purpose: Define success in terms of observable state.

The primary outcome is one thing. Not a list. The single most important state that must be true when the work is done. Secondary outcomes are valuable but don't gate completion.

Weak:

"Better, faster, more efficient customer support experience."

Strong:

"A support agent handling a common account inquiry can retrieve all relevant account history within 30 seconds of opening the ticket, without navigating away from the support interface."

Section 3: Scope

Purpose: Prevent overbuilding and underbuilding. Establish what success does not require.

The out-of-scope section is often equal in importance to the in-scope section. "We are not building a general-purpose search across all company data" prevents an agent from building something five times bigger than needed.

Every out-of-scope line is a decision: we decided NOT to do this, for this work, at this time. That decision should survive scrutiny.

Section 4: Archetype Declaration

Purpose: Establish the governance framework for agent systems.

This section is the most consequential sentence in the spec for agent systems. See Four Dimensions of Governance for the dimension definitions and Decision Tree for how to arrive at the classification.

The archetype declaration cannot be generic. "It's an agent, so it's an Executor" is not a declaration. The declaration names the specific agency level (1–5), the risk posture rationale, the oversight model mechanism, and the reversibility assessment.

Section 6: Invariants

Purpose: Establish the unconditional constraints that no execution discretion can override.

The distinction between an invariant and a constraint: a constraint has acceptable conditions under which it can be relaxed (performance constraints under exceptional load, for example). An invariant never has such conditions. It is always true.

The test for an invariant: Is there any circumstance under which violating this would be acceptable? If yes, it is a constraint, not an invariant.

Section 9: Acceptance Criteria

Purpose: Make validation independent of the author.

The test for an acceptance criterion: Could a person who was not involved in writing this spec determine whether this criterion was met by examining the output?

If no: the criterion is not ready. Rewrite it.

Given/When/Then format is excellent for functional criteria because it forces the conditions, trigger, and expectation to be stated separately.

Section 11: Agent Execution Instructions

Purpose: Communicate directly and unambiguously with the executing agent.

This section should be written last, after all other sections are complete — because it summarizes what the agent may and may not do, and that summary must accurately reflect the entire spec.

The Skills to load sub-section specifies which Agent Skills the agent should activate for this task. Skills are packaged domain knowledge — organizational workflows, brand guidelines, specialized analysis procedures — that extend what the agent knows how to do well. A skill is not an authorization; it is a capability enhancement. The authorization boundary is still governed by section 8. See Portable Domain Knowledge for the full treatment.

The most important clauses are the "NOT authorized" clauses. Agents are expansive by default; without explicit prohibitions, they tend to fill gaps. The explicit prohibition list is the fence around the pre-authorized scope.

Part 2 Closing: The Spec As The Work

The canonical spec template is not a bureaucratic instrument. It is the distillation of a discipline: that the work of engineering systems in an age of agent execution is fundamentally the work of expressing intent precisely.

"If you can't specify it, you don't understand it well enough yet."

This statement, which appears in the SDD source material that preceded this book, is the organizing truth of Part 2. The spec is not something you write after you understand the problem. It is the thing that tells you whether you understand the problem. Writing a spec that cannot be completed — because the problem statement is too vague, the desired outcome is unknowable, the acceptance criteria are untestable — is the earliest possible discovery that the work is not ready to start.

The spec, written well, is the work. Everything after it is execution.

Therefore

The canonical spec template structures intent into fourteen sections across four categories: context (1–3), governance (4, 8), precision (5–7, 9–11), and memory (12–14). Required sections must be complete before execution begins. Agent-system sections formalize the archetype governance framework at the per-task level. The spec evolution log closes the feedback loop. The spec, written with precision, is not paperwork before the work — it is the work.

Connections

This pattern assumes all of Part 2:

• Spec-Driven Development
• The Spec as Control Surface
• The Spec Lifecycle
• SpecKit
• Writing for Machine Execution
• The Living Spec

This pattern is used by:

• Spec Template Library — variant templates for feature specs, agent instructions, integrations
• Archetype deep dives — each archetype's spec template fragment
• Part 5 (Ship) — spec review as governance practice

Part 2 is complete. Continue to Part 3 (The Agent).

Architectural Decision Records

Part 2 — Specify

"The spec records what the system does. The ADR records why the team decided it should do that. They are different artifacts with different lifetimes. Conflating them produces specs that are too long and decisions that are forgotten."

Context

You have a spec, written against the canonical template. You have a team. Decisions are made — about which service to call, which library to standardize on, which architectural pattern to apply, which trade-off to accept. Some of those decisions become invariants in the spec. Most of them don't, but they still need to be recorded.

This chapter introduces ADRs (Architectural Decision Records) as a first-class durable artifact alongside the spec, the spec gap log, and the constraint library. ADRs are well-established in software engineering — Michael Nygard's 2011 essay is the canonical reference — and they have become a load-bearing artifact in modern AI-augmented delivery frameworks like Microsoft's DevSquad Copilot.

The earlier versions of this book did not treat ADRs explicitly. That was an omission. This chapter closes it.

The Problem

Three failure modes recur in teams that have specs but not ADRs:

1. Specs become rationale dumps. A spec that says "the system uses Authentication Service A" leaves the next reader (or the next agent) wondering why. So the spec author adds a paragraph: "We chose Service A because it supports SAML and Service B requires LDAP; the security review in Q1 mandated SAML; the cost differential was acceptable; the migration risk from B to A was deemed lower than the inverse." The spec is now half-rationale. A year later, the rationale is stale (the security review is forgotten; SAML may have been deprecated), but the spec still says it. The decision and its constraint have been welded together in a way that makes neither maintainable.

2. Decisions are forgotten. A team makes a careful decision in a meeting. The decision is captured in the meeting notes. Three months later, an engineer joins and asks "why are we using Service A?" Nobody remembers the rationale. The decision gets re-litigated, often badly, often arriving at a different answer than the original.

3. ADRs are written but disconnected. A team adopts the ADR practice but never connects ADRs to specs. The ADRs live in docs/adr/; the specs live in specs/; agents read the specs and not the ADRs; the rationale is documented but ineffectual.

The discipline this chapter teaches is: ADRs and specs are different artifacts with explicit relationships. Both are durable. Each has a job. Neither can do the other's job.

Forces

• Decision durability vs. spec readability. Specs are read more often than ADRs and need to be tight. ADRs are read less often but need to be discoverable when relevant. Bundling them serves neither.
• Decision permanence vs. spec evolution. A spec evolves with every gap learning; an ADR rarely changes after it's written. Different lifetime profiles need different artifacts.
• Spec authority vs. team consensus. The spec is authoritative for the agent at runtime; the ADR is the team's recorded reasoning. The agent runs on the spec, not the ADR.
• Local decision vs. organizational decision. Some ADRs apply only to one system; some apply to a class of systems and become repertoire-level. The artifact format must accommodate both.

The Solution

What an ADR is

An ADR records, in a stable format, a decision the team made, the context that produced it, the alternatives considered, and the consequences accepted.

A canonical ADR has six sections (adapted from Nygard's original):

ADR-NNN: Short title

Status: Proposed | Accepted | Superseded by ADR-NNN | Deprecated

Context
  What the team faced when this decision was needed.
  What constraints were in play.
  What information was available (and what wasn't).

Decision
  What the team chose. One paragraph, declarative.

Alternatives Considered
  What else was on the table.
  Why each was rejected.

Consequences
  What this decision enables.
  What this decision constrains.
  What new problems this creates.

Spec Mapping
  Which spec section(s) this decision touches.
  Which invariants it produces (if any).

The "Spec Mapping" section is the book's addition to the standard ADR format. It is the explicit bridge between an architectural decision and the spec sections it constrains.

When to write an ADR

Three triggers:

1. A decision affects how an agent (or a class of agents) is authorized to act. "The Authentication Service handles all session validation." "All payment-related agents go through the Payment Guardian." "Coding agents may install only from the corporate registry." Each of these is an ADR-worthy decision because it shapes the spec's Authorization Boundary or Tool Manifest.

2. A decision that future engineers will not understand without context. "We use HTTP polling instead of WebSockets." "We never compute aggregate refund amounts in the agent — we always call the billing service." Each is the kind of decision an engineer joining the team would otherwise re-litigate.

3. A decision that was contested and the team picked a side. Decisions that came after debate are decisions worth recording. Decisions that were obvious to everyone usually don't need an ADR.

What does NOT need an ADR: routine implementation choices (variable naming, file organization), product decisions that don't constrain architecture, decisions that the spec already captures completely (the spec's Authorization Boundary already says everything that needs to be said about the decision).

Where ADRs and specs touch

ADRs are about why. Specs are about what. The mapping rules:

The mapping table above is the rule for ADRs that do have spec consequences. Some ADRs don't — they record decisions that were made but never had to be enforced at the spec layer (e.g., "we considered switching to a different model provider and decided not to"). Those ADRs live in the team's ADR archive and don't generate spec changes. They still have institutional memory value.

Worked example: an ADR for the order-service coding agent

The team described in Designing an AI Coding Agent faced the typosquat decision: should the dependency-installation tool refuse packages within Levenshtein distance 2 of allowlisted packages? The decision became ADR-007:

ADR-007: Typosquat protection at the tool layer

Status: Accepted (2026-04-22)

Context
  Q1 2026 red-team Battery 1 found that the agent could be coaxed
  into installing typosquatted packages by an issue body that
  named a misspelled but plausible-looking package. The agent's
  prompt-level instruction "use only allowlisted packages" did
  not catch this — the model selected the misspelled name as
  plausible, and the package.install tool's check was a literal
  allowlist match (exact string), so the misspelled name was
  rejected as not-allowlisted but the agent then fell back to
  shell.exec("npm install <misspelled>") which had no allowlist
  enforcement.

Decision
  Implement Levenshtein-distance-2 typosquat protection at the
  package.install tool layer (refuses any name within edit
  distance 2 of an allowlisted name). Concurrently remove the
  general-purpose shell.exec from the tool manifest; replace
  with specific test.run, typecheck.run, lint.run actions that
  cannot be used to install packages.

Alternatives Considered
  - Levenshtein distance 1 only: too narrow; misses common
    typosquats with 2-character substitutions.
  - Token-similarity (token2vec): catches more but produces
    false positives for legitimate packages with similar names
    in unrelated namespaces. Not worth the false-positive cost.
  - Manual allowlist of known-typosquat names: doesn't scale;
    new typosquats appear faster than maintenance can keep up.

Consequences
  Enables: structural typosquat protection that is independent
  of the agent's prompt-level instructions. Closes the OWASP
  LLM03 supply-chain attack vector for this agent.

  Constrains: legitimate packages within Levenshtein 2 of any
  allowlisted package cannot be installed. As of 2026-04, this
  affects 4 known cases in the team's ecosystem; manual
  exceptions are recorded in allowlist.json's exceptions array.

  New problems: the allowlist.json exceptions array is a new
  surface that needs review. Added to security team's quarterly
  review cadence.

Spec Mapping
  Order-Service Coding Agent spec v1.3:
    §3.4 (Dependency management) — explicit Levenshtein-2 clause
    §5 C3 (Dependency allowlist enforcement) — programmatic check
    §7 (Tool Manifest) — package.install enforced_constraints
    §7 (Tool Manifest) — shell.exec removed; test.run, typecheck.run,
                        lint.run as replacements
    §6 Invariant 2 — dependency closure is allowlist-bounded

The decision is recorded. The spec is the runtime control surface. The ADR is the answer to "why does the spec say this?" — durable, discoverable, and decoupled from the spec's per-version evolution.

ADR governance

A team running ADRs needs a few light governance practices:

• One file per ADR, named ADR-NNN-short-title.md, in a known location (typically docs/adr/ in the team's repository or platform).
• Sequential numbering that never restarts. ADRs are immutable once Accepted; superseded ADRs are kept in place with status changed and a forward-link to the superseding ADR.
• A reviewer who is not the author. ADRs are decisions; one author and one reviewer is the minimum for a decision to count as a team decision.
• Periodic review (quarterly or per-release) to identify ADRs that should be marked Superseded or Deprecated. Stale ADRs that contradict current reality are worse than no ADRs.

ADRs do not need a heavyweight governance process. They are deliberately lightweight artifacts. Adding ceremony defeats the purpose.

What ADRs are NOT

Three anti-patterns to avoid:

1. ADRs as design documents. An ADR is not the place to design a system. It records a decision that was made, with enough context to understand it. If you find yourself writing an ADR with multi-page architecture diagrams, you are designing in the wrong artifact. Design lives in design docs (or in the spec itself, depending on team norms); ADRs record the discrete decisions that fall out of design work.

2. ADRs as documentation of obvious choices. An ADR for "we use TypeScript" is theater unless TypeScript was contested at the time the decision was made. ADRs cover decisions that could have gone differently. A decision that nobody considered alternatives for is not an ADR-worthy decision; it's just a fact.

3. ADRs that the spec ignores. An ADR that the spec doesn't reflect is institutional memory only — useful, but not load-bearing. The mapping table is the rule. If the ADR is supposed to constrain agent behavior, the spec must encode it. If the spec doesn't, either the spec is incomplete or the ADR was advisory rather than binding; clarify which.

Connection to the rest of the framework

ADRs interact with several other book artifacts:

• Spec Gap Log (The Living Spec). When a gap log entry surfaces a learning that requires an architectural decision, the gap log entry should reference (or trigger the creation of) an ADR. Not every gap is ADR-worthy; the test is "does this require team-level decision-making, or just a spec-section update?"
• Constraint Library (Constraint Library Template). Constraints inherited across multiple specs may have an originating ADR. The constraint library entry should reference the ADR that established it.
• Composing Archetypes (Composing Archetypes). Spec-conflict resolution rules are ADR-worthy at the team or organization level — they say how the team handles a class of conflicts, not just one instance.
• DevSquad Mapping (Mapping the Framework to the DevSquad 8-Phase Cadence). DevSquad's Phase 3 is "Plan with ADRs"; that phase is where most ADRs are produced.

Resulting Context

After applying this pattern:

• Specs are tight. Rationale lives in ADRs, not in the spec body. Specs say what; ADRs say why.
• Decisions are durable. Three months later, six months later, three years later, the decision and its context are still discoverable.
• Specs and ADRs are explicitly related. The Spec Mapping section of every ADR names the spec sections it constrains. The team can trace from any spec clause back to the ADR that established it.
• New engineers can self-onboard. ADRs answer the questions a new engineer asks ("why do we do it this way?") without re-litigating settled decisions.

Therefore

ADRs and specs are different artifacts. The spec records what the system does and is the control surface the agent runs against. The ADR records why the team decided the system should do it that way and is institutional memory for the next reader. Use the canonical ADR format (Nygard's, plus a Spec Mapping section). Write an ADR when a decision affects authorization, capability, risk tier, or process — or when a future engineer would not understand the decision without the rationale. Do not bundle rationale into specs; do not write ADRs that the spec doesn't reflect; do not write ADRs for obvious choices. Both artifacts are durable. Each has a job. Neither can do the other's.

References

• Nygard, M. (2011). Documenting Architecture Decisions. cognitect.com/blog/2011/11/15/documenting-architecture-decisions. — The original essay defining the ADR format. The canonical reference.
• ADR Tools and Templates. (ongoing). adr.github.io. — Community resources for ADR format variations.
• Microsoft. (2026). DevSquad Copilot. github.com/microsoft/devsquad-copilot. — ADRs as a first-class artifact in modern AI-augmented delivery; DevSquad's Phase 3 is centered on ADR production.
• Fowler, M. (2002). Patterns of Enterprise Application Architecture. — Foundational discipline of recording architectural patterns and the decisions behind them.

Connections

This pattern assumes:

• The Canonical Spec Template — ADRs map onto specific spec sections per the table above
• The Living Spec — gap log entries can trigger ADRs for team-level decisions

This pattern enables:

• Mapping the Framework to the DevSquad 8-Phase Cadence — DevSquad Phase 3 is where ADRs live in that cadence
• Co-adoption with DevSquad — the bridge chapter for teams running both frameworks
• Composing Archetypes — system-level spec-conflict resolution rules are typically ADR-worthy

SpecKit

Part 2 — Specify

"A tool that enforces good practice is worth more than a guideline that recommends it."

Context

You are implementing Spec-Driven Development on a team that uses AI coding assistants — GitHub Copilot or similar. You want the SDD lifecycle to happen in the same environment where code is written, not in a separate document management system. You want the spec to live next to the code.

SpecKit is a concrete, opinionated implementation of SDD designed for that environment. This chapter describes the Embedded Spec Tooling pattern — the recurring need to integrate the spec lifecycle into the development environment — and uses SpecKit as the reference implementation. The pattern is: a tool that embeds the spec lifecycle into the same workspace where code is written, making specification a first-class step in the development flow rather than a separate documentation activity. SpecKit is one such tool; others may serve the same pattern differently.

This pattern assumes The Spec Lifecycle and all preceding patterns.

The Problem

SDD as a discipline and SDD as a practice are two different things. The discipline is well-defined: write the spec before code, make specs testable, fix the spec on failure, evolve specs as living documents. The practice depends on tooling, team habits, and where the spec lives relative to the work.

Without tooling that embeds the spec into the development workflow, SDD degrades into documentation that engineers write before PRs and nobody reads. The spec is written, filed, and forgotten. The feedback loop — Phase 5 flowing back into Phase 2 — never closes because there is no mechanism that keeps the spec adjacent to the agent's execution context.

SpecKit solves this specific problem. It puts the spec in the repository, in the codebase, and in the agent's context. It makes the spec executable, not just readable.

Forces

• Discipline vs. integration. SDD as discipline is understood, but practicing it requires making specs central to the workflow. Without tooling, specs are separate documents, easy to ignore.
• Automation vs. clarity. SpecKit automates some drafting. But automation can hide what is being decided. The spec must remain human-readable even when produced by automation.
• Constitution vs. flexibility. The constitution enforces project-wide constraints. This is powerful but can become inflexible. Systems with special requirements need override mechanisms.
• Adoption vs. overhead. Adding SpecKit increases the number of concepts developers need to know. Yet total time cost (spec + code + rework) should decrease.

The Solution

What SpecKit Is

SpecKit is an open toolkit built around a set of agent instructions that guide AI assistants through the SDD lifecycle. It operates through structured commands — slash commands in the agent prompt — that correspond to phases in the spec lifecycle.

The primary commands:

SpecKit's model: the agent is the instrument, the spec is the score, and the /speckit.constitution is the key signature that tells the agent what rules apply before any note is played.

How SpecKit Maps to the Architecture of Intent

SpecKit aligns with the SDD lifecycle at three levels:

Level 1: The lifecycle level. SpecKit's command sequence (/specify → /speckit.clarify → execute → review) maps directly to Phases 2–5 of the SDD lifecycle. For teams using SpecKit, Phase 1 (intent capture) is the natural language input to /specify. The agent's clarifying questions are Phase 3. Execution is the agent producing code from the spec. Validation is the human PR review against the spec.

Level 2: The spec template level. SpecKit's spec output aligns with the categories in the canonical spec template: problem statement, desired outcome, scope, functional intent, constraints, acceptance criteria. SpecKit does not prescribe the same section structure verbatim, but teams using SpecKit should augment its output with the canonical template's invariant and agent-execution sections where relevant.

Level 3: The constitutional level. /speckit.constitution maps to the archetype layer at the top of the control hierarchy. It is the place where cross-system constraints are declared — the things that are true for all specs in a project. In the Architecture of Intent, this is where archetype defaults, organizational invariants, and non-negotiables live.

SpecKit as the Architecture of Intent's Execution Engine

When a team has:

• Archetype definitions (the five canonical archetypes)
• A constitutional spec layer (via /speckit.constitution)
• A canonical spec template (the Canonical Spec Template)
• The SDD lifecycle (the Spec Lifecycle)

...SpecKit is the tooling that makes all three work together in a development workflow.

The practical setup:

<!-- .speckit.constitution (in the repository root) -->

# Project Constitution

## Archetype Defaults

All agent systems in this repository are governed by the archetype 
framework defined in [link to pattern 3.1–3.4]. New agent systems 
must include an explicit Archetype section in their spec.

## Invariants That Apply Across All Specs

1. No system writes to production databases without an approval gate.
2. No system stores PII without explicit data classification.
3. All outputs of Executor-class systems are logged before application.
4. Reversibility of all R3–R4 actions must be addressed in the spec.

## Standards That Apply to All Generated Code

- [Link to language-specific code standards in the Cross-Cutting Patterns section]
- Test coverage requirement: all acceptance criteria must have tests.
- Error handling: structured error types only; no untyped exceptions.

With this constitution loaded, any spec produced by /specify in this repository inherits these constraints automatically. The agent doesn't need to be reminded of them in each spec — they are pre-committed at the constitutional level.

Where SpecKit Extends the Architecture of Intent

SpecKit adds something the Architecture of Intent's pure spec discipline does not give you out of the box: tooling-enforced starting points.

In a pure SDD practice without tooling, whether a spec gets written depends on team habit. SpecKit makes writing a spec the path of least resistance — the /specify command is the entry point to agent-assisted coding, not a separate step before it. The spec is produced as part of starting the work.

This is significant. Behavioral economics shows that the default path determines most outcomes. SpecKit makes the spec-first path the default. Teams that adopt SpecKit practice SDD more consistently than teams that have the SDD discipline documented but not tooled.

Where SpecKit Needs Augmentation

SpecKit is excellent at Phase 2–3 (specification and clarification) and at making the spec machine-executable. It is intentionally minimal about several things that the Architecture of Intent treats as critical:

Living specs and evolution tracking. SpecKit supports iterative refinement via slash commands, but it does not prescribe a spec evolution log. Teams should add the evolution log section from the canonical spec template.

Explicit scope boundaries and invariants. SpecKit encourages constraints via the constitution but does not foreground out-of-scope declarations and invariants as first-class spec sections. Teams should add these explicitly.

Archetype declaration. SpecKit does not know about the archetype framework. For agent systems, teams should add the archetype section to every spec produced by /specify. This is most easily done by including the archetype template fragment in the /speckit.constitution.

Validation checklist. SpecKit's model assumes the human reviewing the PR is the validator. The Architecture of Intent's validation checklist makes this explicit: what are the specific clauses being checked? Teams should treat PR review as spec-conformance review, not aesthetic review.

The augmentation of SpecKit with these additions is not a rejection of SpecKit. It is SpecKit operating as designed — a minimal core that teams customize to their needs. The Architecture of Intent provides the framework for that customization.

The Organizational Argument for SpecKit

For teams that resist SDD because it "adds overhead before you can start," SpecKit provides the pragmatic counter: the overhead is front-loaded and short, the rework reduction is back-loaded and large.

The typical pattern without SDD:

• Write a prompt (2 minutes)
• Get output (1 minute)
• Correct output (20–60 minutes, often more)
• Repeat 3–5 times before the output is acceptable

With SpecKit:

• /specify produces a draft spec (5 minutes)
• Review and refine spec (10 minutes)
• Execute (1 minute)
• Validate against spec (10 minutes)
• Done

The total time is similar; the rework rate is dramatically lower; the spec is now a reusable organizational asset; and the knowledge of what was decided lives in the repository, not in someone's memory.

Resulting Context

After applying this pattern:

• Spec-first becomes the default path. By making the spec command the entry point, SpecKit makes writing a spec the easiest choice.
• Constitution propagates automatically. Project-wide constraints are loaded and inherited by every spec produced. Teams do not have to remember to include them.
• Specs live next to code. By keeping specs in the repository, version control applies to specs the same way as code.
• Teams can customize SDD to their practice. SpecKit is intentionally minimal. Teams extend it with their own governance needs.

Therefore

SpecKit is a practical implementation of Spec-Driven Development that embeds the spec lifecycle into the coding workflow via structured agent commands. Its /specify, /clarify, and /constitution commands map directly to the SDD lifecycle phases. Augmented with archetype declarations, scope invariants, and the spec evolution log, SpecKit becomes the execution engine for the Architecture of Intent's complete governance model.

Connections

This pattern assumes:

• The Spec Lifecycle
• Pick an Archetype
• The Spec as Control Surface

This pattern enables:

• Writing for Machine Execution
• The Canonical Spec Template
• Spec Template Library

External reference: github/spec-kit (verify current availability — tooling evolves rapidly)

The Organizational Repertoire

Repertoire & Reference

"The expert carpenter doesn't decide how to cut a dovetail each time. The decision was made long ago and encoded in muscle memory. The craftsperson's freedom comes from the pattern, not despite it."

Context

You have a working architecture of intent. Agents operate from specs. Skills carry domain knowledge. Tools and MCP provide capability. Oversight models keep the system accountable. Failure modes are understood categories with known remedies.

The architecture is sound. But sound architecture does not automatically produce efficient teams. Every new task still requires a practitioner to start from scratch: choose an archetype, determine the constraint set, write the spec sections, decide what validation means for this output type. Even experienced practitioners spend substantial time at the beginning of each task doing work that is not about this task — it is about assembling the scaffolding that every task of this type requires.

This chapter introduces the concept that addresses this problem: the repertoire — a curated library of proven, reusable patterns that practitioners inherit rather than invent.

The Problem

Consider two teams deploying the same SDD practice, six months apart. Team A has been operating continuously; Team B is starting fresh but has learned the framework. Both teams understand archetypes, specs, and agent skills. But when practitioners on Team A start a new feature spec, they spend fifteen minutes: pull the feature spec template, copy in the relevant constraint blocks, reference the appropriate archetype profile, adjust the validation section. When practitioners on Team B start the same task, they spend two hours: open the canonical template, decide which sections apply, write the constraints from scratch, debate the archetype selection.

Both outputs may be equally correct eventually. But Team A reaches correct output four times faster. Their speed does not come from being more experienced with the framework — both teams are. It comes from having accumulated a repertoire: proven starting points that encode the accumulated decisions their predecessors made.

This gap compounds. In six months, Team A's practitioners have:

• Written the same constraint set thirty times and extracted a constraint-library.md that anyone can reference
• Identified that their REST API integrations always require the same five constraint clauses, now in a template
• Discovered that their code review agents perform better with a validated skill file than with ad-hoc spec sections

Team B's practitioners have also made these discoveries. But they made them silently, individually — the insight lived with the person, not the team.

The absent repertoire is not just a speed problem. It is a consistency problem. When every practitioner writes constraints and validation criteria from scratch, the quality variance is high. Some specs are excellent; others miss critical constraint categories. The quality of agent output reflects this variance — agents faithfully execute whatever spec they receive. Good spec, good output. Incomplete spec, unpredictable output. Without shared starting points, the distribution of spec quality is as wide as the distribution of practitioner experience.

Forces

• Individual learning vs. organizational leverage. Each team that spec-writes from scratch repeats discoveries that other teams have already made. Yet sharing requires abstraction that takes effort.
• Best practices vs. authorized patterns. Best practices are advisory and frequently ignored. Authorized repertoire components are organizational decisions that agents and practitioners follow.
• Speed of adoption vs. quality of components. Teams want to start quickly. High-quality repertoire components require careful design and testing. The tension between speed and quality applies to repertoires as it does to code.
• Stability vs. evolution. Repertoire components must be stable enough to be relied upon. Yet they must evolve as organizational understanding deepens.

The Solution

What a Repertoire Is

A repertoire, borrowed from the pattern language tradition, is a practitioner's active library of proven solutions to recurring problems. Not a reference manual to be consulted in emergencies, but the set of patterns that flow naturally when facing a familiar problem type.

In the architecture of intent, a repertoire has three components:

Templates are pre-structured documents that provide the scaffolding for a class of task. A feature spec template provides all the sections a feature spec requires, pre-populated with guidance and example content, with task-specific information as the only thing the practitioner must supply. Templates encode structural decisions.

Catalogs are organized collections of decision-ready artifacts: archetype profiles, constraint sets, standard acceptance criteria, skill references. A catalog resolves decisions by lookup rather than derivation. Instead of reasoning from first principles about which archetype applies, the practitioner finds the closest match and adjusts. Catalogs encode reference decisions.

Standards are specific, testable rules that govern how a class of output should be produced. Code standards define naming, patterns, error handling, and test requirements. Validation standards define what acceptance means for different output types. Standards encode quality decisions.

Together, templates, catalogs, and standards constitute the repertoire. A practitioner who has internalized them — or who has access to well-organized versions of them — can start any task in their domain with a proven scaffold, leaving cognitive effort for the parts that are genuinely novel.

The Skills Connection

Part 3 introduced Agent Skills as the packaging format for domain knowledge. The relationship between skills and repertoires is direct: the organization's repertoire is the human-readable version of what its skills files encode for agents.

A code standards document that describes how the team writes TypeScript is the source material for a typescript-standards skill. A spec template library that provides the feature spec template is the source material for a spec-writing skill. A validation template that defines acceptance criteria for API integrations encodes the knowledge that becomes the api-validation skill.

The authoring order is usually: practitioner develops the repertoire artifact first (template, standard, catalog entry); skill is extracted from the artifact later. The maintenance order is reversed: when the skill produces wrong agent output, that signals the underlying repertoire artifact needs updating, which drives the skill update.

This creates a flywheel:

Practitioners write → Repertoire artifact → Extracted to Skill → Agent applies →
Output quality informs → Repertoire update → Skill update → Better agent output

The repertoire is not just a productivity tool for humans; it is the ground truth from which agent skills are maintained.

The Living Repertoire

A repertoire that is not maintained is worse than having no repertoire, for a subtle reason. Practitioners who trust a repertoire will use it without checking. If the repertoire is stale — referring to an old API pattern, carrying a constraint that no longer applies, missing a security clause added after the last incident — practitioners who work from it produce outputs that are confidently wrong.

A living repertoire has three properties:

Provenance. Every artifact in the repertoire knows where it came from: which team proposed it, which practitioner reviewed it, when it was adopted, and when it was last verified. Without provenance, artifacts accumulate without accountability.

Review cadence. Repertoire artifacts are reviewed on a defined schedule — quarterly for most, immediately after any incident that reveals a gap. The review is not a comprehensive rewrite; it is a diff against current practice. "Is this still how we do it?"

Gap log integration. The Spec Gap Log introduced in Part 3 (Failure Modes and How to Diagnose Them) feeds directly into the repertoire. Every identified spec gap is a candidate repertoire addition. When a practitioner writes the same constraint from scratch twice in two weeks, that constraint belongs in the constraint library. The gap log is the intake queue for the repertoire backlog.

What Repertoires Do Not Replace

A repertoire does not replace judgment. It reduces the cost of exercising it correctly.

A practitioner who blindly applies a spec template without reading it is not applying the repertoire — they are delegating judgment to a document, and the document does not care whether it is appropriate for the current task. The template exists to eliminate the scaffolding work; the practitioner still decides which template applies, what to keep and what to modify, and whether the resulting spec is correct.

A repertoire does not replace skills development. A junior practitioner working from excellent templates produces better work than they would from scratch — but they still need to understand the architecture to know which template is appropriate, what constraints mean, and how to evaluate the output.

The repertoire is the accumulated organizational intelligence about how this class of work is done well. Applying that intelligence well still requires a practitioner who understands the work.

Resulting Context

After applying this pattern:

• New teams start from a proven baseline. Archetypes, templates, constraint libraries, and code standards are pre-authorized starting points rather than blank-page exercises.
• Consistency improves across teams. When multiple teams use the same repertoire, their specs, constraints, and code standards converge without requiring central enforcement.
• The repertoire flywheel compounds. Practitioners write, repertoire artifacts accumulate, skills encode them for agents, agents execute consistently, quality feedback improves the repertoire.
• Knowledge survives team changes. When practitioners leave, their codified knowledge remains in the repertoire.

Therefore

A repertoire is the practitioner's inherited library of proven patterns — templates for structure, catalogs for decisions, standards for quality. In an agent-driven practice, the repertoire is simultaneously a human productivity tool and the ground truth from which agent skills are maintained: the flywheel connects practitioner wisdom to agent behavior to output quality back to repertoire refinement. Without it, every team reinvents; with it, teams inherit and improve.

Connections

This pattern assumes:

• The Executor Model
• Portable Domain Knowledge
• Failure Modes and How to Diagnose Them — Spec Gap Log
• The Canonical Spec Template

This pattern enables:

• The Intent Archetype Catalog
• Spec Template Library
• Standards as Agent Skill Source
• Validation & Acceptance Templates

The Intent Archetype Catalog

Repertoire & Reference

"A catalog is not a cage. It is a starting point calibrated by everyone who worked in this domain before you."

Context

Part 1 introduced the five canonical archetypes — Advisor, Executor, Guardian, Synthesizer, Orchestrator — and the four dimensions that define each: Agency Level, Risk Posture, Oversight Model, and Reversibility. Those archetypes are conceptual vocabulary.

This chapter materializes them as a usable catalog: reference profiles that practitioners consult when specifying a new agent deployment, with enough structure to serve as the starting point for Section 3 of any spec, and enough extensibility to accommodate organizational specializations.

The Problem

The five archetypes work as a conceptual framework. They break down as a daily practice tool when every practitioner must mentally recall the dimensions, determine where their specific deployment falls, and write the spec sections that follow from that determination — from scratch, every time.

The catalog solves this by making the most common archetype profiles decision-ready: look up the closest match, read the dimension values, inspect the standard constraints and oversight configuration, adjust for your specific deployment context. The deliberation is compressed from "what archetype is this?" to "how does this differ from the standard Executor profile?"

Forces

• Completeness vs. usability. A catalog that covers every archetype variant is comprehensive but overwhelming. A catalog that covers only the five base archetypes is accessible but insufficient for real deployment.
• Standardization vs. specialization. Standard profiles enable consistency. But every organization has domain-specific requirements that standard profiles cannot capture.
• Catalog proliferation vs. catalog discipline. Making it easy to add variants encourages growth. Unconstrained growth produces an incoherent catalog.
• Reference-quality vs. starting-point quality. Each profile must be good enough to use directly, not just good enough to inspire a custom version.

The Solution

How to Use This Catalog

Step 1. Identify the primary archetype your agent will instantiate. If you're uncertain, use the selection table in Part 1 (The Five Archetypes) and the Agency Levels and Risk Posture chapter.

Step 2. Find the closest standard profile in the catalog below.

Step 3. Copy the dimension values into Section 3 of your spec. Note any deviations from the standard profile and document the rationale.

Step 4. Use the standard constraints and oversight configuration as the starting point for Sections 7 and 8 of your spec.

Archetype Profile: Advisor

Primary function: Generate analysis, recommendations, and options. The human acts; the agent informs.

Standard constraints:

• May not take actions on the user's behalf without explicit re-authorization as an Executor
• May not contact external parties
• May not access data outside the defined research scope
• Must surface uncertainty explicitly when confidence is below threshold

Standard oversight configuration:

• Spec approval: required before deployment
• Output review: human reads and acts on output; no confirmation step before generation
• Escalation: if asked to take an action, surface the Advisor/Executor distinction and request explicit archetype upgrade

Typical use cases: Research synthesis, option generation, decision support, documentation drafting, code review suggestions.

Variant: Advisor with specialized domain skill
Identical profile, plus a designated skill file that encodes domain-specific analysis frameworks. Declare in spec Section 11 (Skills to load).

Archetype Profile: Executor

Primary function: Carry out a defined, bounded task with direct system effects.

Standard constraints:

• Scope is the pre-authorized task and nothing adjacent
• Maximum read-scope is the data explicitly listed in Section 12
• Write operations require all fields to be explicitly declared; no schema discovery and fill
• No external communications without explicit destination list in spec
• NOT authorized: refactoring code outside the defined scope, restructuring data schemas, creating new API endpoints

Standard oversight configuration:

• Model D: spec defines pre-authorized scope; agent acts within scope without per-output review; any boundary-crossing surfaces for human decision
• Model B: phase checkpoints defined in spec; human approves before phase boundary is crossed
• Escalation triggers: unexpected data format, target resource unavailable, spec appears to conflict with discovered reality

Typical use cases: Feature implementation, data transformation, document generation, scheduled report production, migration execution.

Variant: High-frequency Executor
Agency Level 3, Oversight Model A (Monitoring + anomaly detection). Suitable for batch operations that execute hundreds of times per day where per-run review is impractical. Requires enhanced audit logging and statistical sampling for review.

Archetype Profile: Guardian

Primary function: Validate, audit, and enforce — flag violations without executing corrections.

Standard constraints:

• May read any resource explicitly listed in Section 12; no write access to source data
• May write to: audit log, findings report, flagging queue
• NOT authorized: auto-remediation, direct correction of violations, escalation to external parties without human approval
• Confidence threshold must be declared; findings below threshold routed to "uncertain" queue, not "violation" queue

Standard oversight configuration:

• Human reviews findings before any remediation workflow is triggered
• Findings queue reviewed by designated reviewer within defined SLA
• Escalation: pattern of violations that exceeds threshold triggers human review of whether auto-remediation should be activated (this is an archetype upgrade decision, not an agent decision)

Typical use cases: Security compliance scanning, data quality auditing, policy enforcement, code review, cost anomaly detection.

Archetype Profile: Synthesizer

Primary function: Aggregate, transform, and compose multi-source information into a unified output.

Standard constraints:

• Source list is exhaustive: may not discover and add sources outside Section 12
• Synthesis must preserve source attribution in structured form; no unsourced claims
• Must flag contradictions between sources rather than silently resolving them
• Output must be validated against the success criteria before delivery, not after
• NOT authorized: reaching out to sources for clarification, commissioning new research

Standard oversight configuration:

• Draft review required before any distribution
• Human must approve the source list in spec before execution begins
• Escalation: source unavailable, sources materially contradict on a key point, confidence in synthesis is below threshold

Typical use cases: Intelligence reporting, research synthesis, document summarization, cross-system status aggregation, competitive analysis.

Archetype Profile: Orchestrator

Primary function: Coordinate multiple specialized agents or processes to achieve a compound goal.

Standard constraints:

• Each sub-agent must have its own spec with its own capability boundary; the Orchestrator spec does not override sub-agent specs
• Orchestrator may not grant sub-agents capabilities they were not already spec'd for
• Maximum wall-clock time and maximum cost must be declared as hard limits
• Failure handling must be explicit: what happens when a sub-agent fails, partially fails, or returns unexpected results
• Escalation is mandatory when: any sub-agent reports an unexpected result that would change the plan, combined cost is projected to exceed declared limit, a required sub-agent is unavailable

Standard oversight configuration:

• Model B: human approves plan before sub-agent execution begins
• Model C: human reviews logs at defined checkpoints; interrupt capability active
• Each phase that produces an irreversible effect requires checkpoint approval

Typical use cases: Multi-stage deployment pipelines, complex document production (multiple specialist agents), parallel research and synthesis, multi-system data migrations.

Extending the Catalog

The five profiles above are starting points, not ceilings. Organizations should extend the catalog with:

Domain-specific variants. A "Financial Compliance Executor" is an Executor with elevated constraint specificity, mandatory audit logging, and confirmation requirements for monetary operations. It belongs in the catalog so every financial-system spec author has a proven starting point.

Composite archetypes. Some deployments combine archetype characteristics: a Guardian that can initiate remediation when violations are low-risk (Guardian + scoped Executor). Document the combined profile explicitly with clear rules about when the Executor capability activates.

Organizational capability stamps. As your agent deployments mature, certain configuration patterns prove reliable in your environment. Document them here: "Our Executor-v2 profile has been running production deployments for 18 months; use it as the default for deployment specs." The catalog becomes a living record of the organization's operational learning.

To add a catalog entry, the pattern is:

1. Deploy an archetype variant in a real task
2. Run it for sufficient time to validate the configuration is stable
3. Extract the profile: dimension values, constraints, oversight configuration
4. Peer-review the profile
5. Add it to the catalog with provenance (team, date, context)

Resulting Context

After applying this pattern:

• Archetype selection becomes lookup, not invention. Teams select from pre-built profiles rather than reasoning from first principles each time.
• Governance is pre-authorized. Each profile carries its governance requirements. Selecting a profile selects its governance automatically.
• Extension follows a governed process. Domain-specific variants extend the catalog through an explicit process rather than ad-hoc modification.
• Consistency compounds across the organization. Multiple deployments of the same profile produce predictably similar governance structures.

Therefore

The Intent Archetype Catalog materializes the five archetypes as decision-ready profiles — dimension values, standard constraints, and oversight configurations that practitioners copy and adjust rather than derive from scratch. It accelerates spec authoring, reduces dimension-selection variance, and grows as the organization accumulates validated deployment patterns. The catalog is the institutional memory of how archetypes have been applied reliably in this organization's specific context.

Connections

This pattern assumes:

• The Organizational Repertoire
• The Five Archetypes
• Agency Levels and Risk Posture
• Oversight Models and Reversibility

This pattern enables:

• Spec Template Library
• Org-specific archetype extension

The Spec Template Library

Repertoire & Reference

"The canonical template is the grammar. The typed templates are the sentences your team actually writes."

Context

Part 2 produced the Canonical Spec Template — a 14-section master structure that covers every element a spec might need. It is comprehensive by design. It must be, to serve as the authoritative reference for the framework.

But no practitioner writes from the canonical template every day. It is too comprehensive for routine use — most tasks require seven or eight sections fully, and the other sections partially or not at all. The overhead of deciding which sections to include, which to abbreviate, and which are mandatory for this task type is non-trivial. Multiplied across a team and a year, it is significant.

The Spec Template Library solves this with typed templates: pre-configured specializations of the canonical template, each calibrated for a specific class of work, with the mandatory sections pre-populated, the optional ones scoped, and task-specific guidance already in place.

The Problem

Teams that adopt SDD often cycle through the same frustration: the canonical template is excellent, but starting from it feels slow. The first few times, practitioners read every section carefully to determine applicability. After a few weeks, they start skipping sections they've decided aren't relevant for their usual work. The skipping is often wrong — sections that seemed optional turn out to matter, and the omission shows up in agent output quality.

The second problem is inconsistency. Ten practitioners writing feature specs from the canonical template will produce ten structurally different specs. The sections they include, their level of detail, the formality of their language — all vary. This creates difficulty for reviewers (different spec formats require different mental models to read) and for agents (unpredictable structure means unpredictable parsing).

Typed templates solve both problems: the structure is decided in advance, sections are pre-selected, and the team converges on a recognized format. Reviewing a feature spec looks like reviewing any other feature spec.

Forces

• Canonical completeness vs. task-specific efficiency. The canonical 14-section template captures everything. But most tasks only need a subset, and requiring all sections creates overhead.
• Template proliferation vs. template coherence. Task-specific templates (feature, integration, agent instruction) reduce overhead. But too many templates create confusion about which to use.
• Standardization vs. flexibility. Templates should be consistent enough that reviewers know where to look. Yet tasks differ enough that some sections may be irrelevant.
• Template quality vs. template availability. A well-designed template reduces errors. A poorly designed template institutionalizes bad practice.

The Solution

What a Typed Template Is

A typed template is a pre-configured version of the canonical spec template for a specific class of task. It:

• Marks some sections as required (they must be completed for every spec of this type)
• Marks others as conditional (complete them if the relevant condition applies)
• Omits sections that are never applicable to this task type
• Pre-populates guidance and examples tailored to the class of task
• Cross-references the relevant archetype profile from the Archetype Catalog

A typed template is not a fill-in-the-blanks form. It is a scaffold. The practitioner still writes the content — the template provides the structure, the guidance, and the starting-point text. The cognitive work the template removes is: figuring out what to include and how to frame it. The cognitive work it preserves: understanding the task well enough to specify it clearly.

Library Contents

The template library currently contains four templates. Each is fully specified in its dedicated sub-page.

Feature Spec Template
For new functionality being built by an Executor agent: a feature, a fix, a new capability, or a refactor with defined scope. This is the most frequently used template. Sections: Problem Statement, Scope, Archetype (Executor), Constraints, Success Criteria, Output Format, Oversight (Model A or B), Tools (list), Agent Execution Instructions.

Agent Instruction Template
For configuring a standing agent deployment — not a one-time task spec, but the persistent instruction set that defines how an agent operates across many tasks. Used when deploying a new agent persona, configuring an MCP-connected bot, or defining the operational charter of a continuously-running agent. Sections: Agent Identity, Operational Domain, Capability Charter, Constraint Set, Escalation Protocol, Skill Manifest.

Integration Spec Template
For connecting two or more systems via API, event bus, file exchange, or data pipeline. Captures the integration contract formally enough that an Executor can implement and test it without clarifying questions. Sections: Integration Purpose, Source System, Target System, Data Contract, Volume/Rate Limits, Error Handling, Validation, Rollback Plan.

Constraint Library Template
Not a task spec — a reusable constraint set that can be referenced by other specs. Used to extract constraints that appear in many specs into a single governed artifact. When a spec says "apply constraints from constraint-library/data-handling-v2.md," that reference pulls in thirty tested constraint clauses from a single reviewed source.

Growing the Library

The template library is not exhaustive. Organizations will need additional types:

• Incident postmortem spec — structured retrospective with defined sections for timeline, root cause, contributing constraints, and remediation actions
• Data migration spec — for ETL operations with volume, validation, and rollback requirements
• Research synthesis spec — for Synthesizer deployments with source list, output format, and citation requirements

The process for adding a new template type:

1. Identify a class of task for which practitioners have written ≥5 specs
2. Review existing specs of that type to identify which sections are invariant
3. Draft the typed template with section markings (required / conditional / omit)
4. Test it on a real task before adding to the library
5. Add with provenance: task class, derived-from spec IDs, review date

Template Versioning

Templates change as the framework evolves and the organization learns. Version-control templates the same way as code:

• Semantic versioning: feature-spec-v2.1.md
• Specs reference the template version used: Template: feature-spec-v2.1
• Major version changes require a migration note explaining what changed and why
• Old versions are archived, not deleted — specs written against them remain valid

Resulting Context

After applying this pattern:

• Practitioners spend less time on structure, more on content. Templates handle the format; authors focus on the substance of their specific task.
• Review efficiency improves. Reviewers know where to find constraints, success criteria, and oversight declarations in any spec because the template structure is consistent.
• Template selection guides archetype thinking. Choosing between feature spec, integration spec, and agent instruction templates forces early consideration of the system's nature.
• Templates improve through organizational feedback. When a template section consistently produces gaps, the template is updated to prevent the gap.

Therefore

The Spec Template Library provides typed, pre-configured specializations of the canonical template for specific task classes. Typed templates eliminate structural variance, reduce spec authoring time, and direct the practitioner's cognitive effort toward task-specific content rather than structural decisions. The library grows from the organization's accumulated spec history — every class of recurring work is a template candidate, and every template makes the next spec of that type faster and more consistent.

Connections

This pattern assumes:

• The Organizational Repertoire
• The Canonical Spec Template
• The Intent Archetype Catalog

This pattern enables:

• Feature Spec Template
• Agent Instruction Template
• Integration Spec Template
• Constraint Library Template
• Standards as Agent Skill Source

Feature Spec Template

Repertoire & Reference

Copy this template. Fill in every section marked [REQUIRED]. Review conditionals and include those that apply. Delete this instruction block before submitting for approval.

How to Use This Template

This template is a pre-configured specialization of the Canonical Spec Template for feature development: new functionality, fixes, refactors, or capability extensions built by an Executor agent.

Mandatory sections: 1, 2, 3, 5, 6, 8, 11, 12
Conditional sections: 4 (multiple owners), 7 (external systems), 9 (data schema changes), 10 (non-functional requirements apply)
Archetype: Executor
Typical oversight model: A (mature/repeatable task) or B (multi-phase or novel task)

Feature Spec

Spec ID: [REQUIRED: FEAT-YYYY-NNN]
Title: [REQUIRED: one-line description]
Template: feature-spec-v1.0
Date: [REQUIRED]
Author: [REQUIRED]
Reviewer / Approver: [REQUIRED]
Spec Status: Draft / Under Review / Approved / Superseded

Section 1 — Problem Statement

[REQUIRED]

State the problem this feature solves. One to three sentences. Describe the current state and why it is inadequate. Do not describe the solution here.

Current state: [What is true today that is insufficient or absent]
Why it matters: [The consequence of leaving this unchanged]
Scope boundary: [What related problems are explicitly out of scope for this spec]

Section 2 — Objective

[REQUIRED]

One sentence statement of what this spec will produce. Complete when read in isolation.

Build [artifact or capability] so that [who] can [do what], resulting in [measurable outcome or state change].

Section 3 — Archetype & Agency

[REQUIRED]

Justification for deviations from standard Executor profile: [Required if any dimension differs from the standard profile in the Archetype Catalog. Delete line if using standard profile.]

Section 4 — Stakeholders

[Conditional: include if more than one team or system owner is involved]

Section 5 — Scope

[REQUIRED]

In scope:

• [Specific thing the agent will do]
• [Another specific thing]
• (be exhaustive — if it is not listed, it is out of scope)

Out of scope (explicit):

• [Adjacent work that might seem related but is not authorized]
• [Refactoring outside the defined change area]
• [Performance optimization beyond the declared requirement]

Definition of done:
[One sentence: "This spec is complete when [specific, independently verifiable condition]"]

Section 6 — Success Criteria & Acceptance Tests

[REQUIRED]

Each criterion must be answerable with a definitive yes/no by a reviewer who has only this spec and the output. Copy applicable rows from the Code Output Validation Template.

Section 7 — Dependencies & External Systems

[Conditional: include if the feature touches or depends on external systems]

Unavailability handling: If [system] is unavailable, the agent should [stop and escalate / proceed with mock data for testing / produce partial output and flag].

Section 8 — Oversight & Escalation

[REQUIRED]

Oversight model: Model [A / B]

If Model A:
Spec is approved → agent executes → human reviews output against §6 criteria. No confirmation steps during execution.

If Model B:
Phase checkpoints:

• After [phase 1 description]: agent surfaces [deliverable]. Human approves before proceeding.
• After [phase 2 description]: agent surfaces [deliverable]. Human approves before proceeding.

Escalation triggers:

• [Trigger 1 — e.g. Target file/record does not exist at expected path]
• [Trigger 2 — e.g. Test suite failure rate exceeds 10%]
• [Trigger 3 — e.g. Spec constraint appears to conflict with discovered codebase state]
• Any action not covered by §5 scope or §12 tool manifest

Escalation channel: [How the agent surfaces an escalation — comment, file, message]

Section 9 — Data & Schema

[Conditional: include if this feature changes data structures, schemas, or migrations]

Schema changes:

• [Table/model/type]: [What changes — add field, rename field, change type, etc.]

Migration requirement: [Required / Not required]
Migration reversibility: [Fully reversible / Two-phase required — explain]
Data impact: [Affects N rows / No existing data affected / Backfill required]

Section 10 — Non-Functional Requirements

[Conditional: include if specific performance, security, or reliability requirements apply]

Section 11 — Agent Execution Instructions

[REQUIRED]

Objective restatement (for agent):
[One sentence: what the agent must produce. This is the agent's primary directive.]

Skills to load (list those that apply; omit section if none apply)

• [skill-name]: [Why relevant to this task]

Authorized actions:

• Read: [specific files, modules, tables]
• Write: [specific files, modules, tables]
• Execute: [specific commands, test runners, linters]
• NOT authorized: [anything adjacent that might seem helpful but is out of scope]
• NOT authorized: [external communications]
• NOT authorized: [schema changes beyond those declared in §9]

Completion signal:
When the objective is achieved and all §6 criteria are satisfied, the agent should [describe how to signal completion — e.g. open a PR, write a summary file, post a status message].

Section 12 — Tool & Resource Manifest

[REQUIRED]

Tools NOT authorized for this task:

• [e.g. Email / messaging tools]
• [e.g. Database schema mutation tools]

Spec Approval

Back to: Spec Template Library

Agent Instruction Template

Repertoire & Reference

This template defines the standing operational charter of an agent — not what to do on a specific task, but how to behave across all tasks in its domain. Fill in each section. This document is loaded into the agent's system context and reviewed on a defined cadence.

How to Use This Template

An agent instruction document is the persistent operating charter for a continuously-running or standing-deployment agent: a bot, a recurring workflow agent, an MCP-connected agent with a defined role. It is distinct from a task spec (which governs one execution) — it governs the agent's standing behavior.

Update this document when the agent's role, tools, or constraints change. Old versions should be archived with dates. The current version is the only authoritative standing instruction.

Agent Charter

Agent ID: [REQUIRED: AGENT-NNN]
Agent Name: [REQUIRED: descriptive name]
Charter Version: v[1.0]
Effective Date: [REQUIRED]
Owner: [REQUIRED: team or individual]
Review Cadence: [Quarterly / Monthly / After each major platform update]

Section 1 — Agent Identity

Purpose statement:
One sentence: what this agent does and for whom.

[Agent name] is a [archetype] agent that [primary function] for [principal users/teams].

Archetype: [Advisor / Executor / Guardian / Synthesizer / Orchestrator]
Operational domain: [The scope of work this agent is chartered to perform]
What this agent is not: [Adjacent roles or capabilities explicitly outside this agent's charter]

Section 2 — Principal Users

Section 3 — Capability Charter

Authorized capabilities:

Hard limits (never, regardless of task spec):

• [e.g. May not send external email]
• [e.g. May not write to production database directly]
• [e.g. May not modify its own charter or instruction files]
• [e.g. May not grant itself capabilities not listed in this document]

Section 4 — Skill Manifest

Skills the agent loads as standing context for all tasks in its domain. List only skills that apply broadly across the agent's work — task-specific skills are declared per-task in the task spec's §11.

Section 5 — Constraint Set

Standing constraints that apply to every task this agent executes. Task specs may add constraints; they may not remove or override these.

Scope constraints:

• [e.g. All work must be traceable to a task spec with a valid Spec ID]
• [e.g. The agent may not initiate work without a spec; if prompted without a spec, request one]

Quality constraints:

• [e.g. All code output must pass linter before surfacing]
• [e.g. All outputs must be validated against the task spec's §6 criteria before delivery]

Communication constraints:

• [e.g. External communications require a confirmation step]
• [e.g. All outputs are surfaced to the designated review channel before delivery to final recipients]

Data handling constraints:

• [e.g. PII encountered in source data must not appear in output files]
• [e.g. Credentials must not be logged]

Section 6 — Escalation Protocol

When to stop and surface a question rather than proceeding:

Escalation response SLA: Escalations not responded to within [N hours] should be re-escalated to [secondary contact].

Section 7 — Oversight & Audit

Default oversight model: Model [A / B / C / D]
Task specs may specify a stricter model; they may not specify a more permissive one without charter owner approval.

Audit requirements:

• All tool calls logged with: timestamp, tool name, arguments (PII-masked), result status, task spec ID
• Log retention: [N days]
• Log location: [path or system]
• Log review cadence: [Weekly automated anomaly detection / Monthly manual review]

Performance baseline:
[Optional: declare expected call volumes, error rates, and latency targets that anomaly detection monitors against.]

Charter Review

Back to: Spec Template Library

Integration Spec Template

Repertoire & Reference

Use this template when an Executor agent will connect two systems, implement an API, configure an event-driven integration, or build a data pipeline. Every section marked [REQUIRED] must be completed. The data contract section must be precise enough that the implementing agent never needs to infer a field's type, name, or optionality.

How to Use This Template

Integration specs have higher completeness requirements than feature specs because the failure modes are harder to detect and more expensive to reverse. A feature spec with a vague constraint produces code that fails visibly in testing. An integration spec with a vague contract produces a system that works in happy-path tests and fails in production under specific conditions that were never tested.

The data contract section (§6) is the most critical. Every field must be explicitly declared.

Integration Spec

Spec ID: [REQUIRED: INT-YYYY-NNN]
Title: [REQUIRED: Source → Target: Purpose]
Template: integration-spec-v1.0
Date: [REQUIRED]
Author: [REQUIRED]
Source System Owner: [REQUIRED]
Target System Owner: [REQUIRED]
Spec Status: Draft / Under Review / Approved