Documentation hierarchy

The artifacts — the team's collective memory

AIAD artifacts are not bureaucracy: they are tools for thinking and communicating. They make visible what would otherwise stay implicit, align the team on a shared understanding, and give AI agents the context they need to perform. Without them, the context is lost at every session.

Thinking tools, not paperwork

A good artifact is recognised by four qualities: it is actionable (can we act from this document?), living (does it evolve with understanding?), minimal (does it contain just enough, no more?) and collaborative (was it co-created, not dictated?). What matters is not having perfect documents — it is having useful documents. Without an AGENT-GUIDE, agents produce generic code; without ARCHITECTURE, inconsistent code; without a SPEC, incorrect code.

The documentation hierarchy

The artifacts are organised in a strict hierarchy. The rule is absolute: never contradict a higher level.

AIAD Constitution (immutable values)
  └── Tier 1 Governance Agents (veto power)
       └── PRD (product vision)
            └── ARCHITECTURE (technical standards)
                 └── AGENT-GUIDE (permanent context)
                      └── SPEC (per-task activation)

This hierarchy is also the management tool of the Context Engineering Budget: strategic context at the top (injected during framing), permanent context in the middle (condensed), task context at the bottom (one SPEC at a time). In a conflict between a SPEC and a governance agent, governance prevails — always.

Intent Statement — the archived WHY

The Intent Statement is the first-order artifact: it captures the human intent behind each feature in five fields (WHY NOW, FOR WHOM, OBJECTIVE, CONSTRAINTS, DRIFT CRITERION), with a mandatory human author — the Human Authorship principle. It precedes and transcends the SPEC, and it is archived in .aiad/intents/. Six months from now, it is the one that will answer the question "what did we want to accomplish, and why?".

The Drift Criterion states how we will know, three months from now, whether the implementation has betrayed the intent. Since doctrine v1.9, when the intent involves agent actions with effects outside the code — financial, operational or physical —, it specifies their reversibility class (reversible, costly to reverse, irreversible) and, for the irreversible class, a stop threshold: any observed overreach of autonomy halts the agent and triggers an immediate human review. Details on the Intent Statement page.

PRD — the expected value

The Product Requirement Document clarifies why and what to build before the how. It contains the context and the problem, the measurable Outcome Criteria, the personas and use cases, the deliberate out-of-scope, the trade-offs and the risks. Five practices are non-negotiable: start from the problem (not the solution), define the success criteria before building, write it with the team, keep it living, and illustrate it (wireframes, flows).

ARCHITECTURE — the coherence reference

The ARCHITECTURE document defines the technical standards that agents and PEs must respect, in nine sections: architectural principles, overview, justified tech stack, project structure, code conventions, patterns and best practices, security, performance, and ADRs (Architecture Decision Records). It is evolutive, justified, pragmatic (YAGNI), visual and actionable. In an agent session, it is never injected in full: a permanent condensed version of 500 tokens maximum is enough — the rest is consulted on demand.

AGENT-GUIDE — the agent's permanent context

The AGENT-GUIDE is the most operational document of the framework: injected into every session, it turns a generic agent into a project agent. It contains the project identity, the absolute ALWAYS / NEVER rules (e.g.: always synchronise SPEC + code in the same PR; never push secrets), the code conventions, the domain vocabulary, the patterns and anti-patterns — and two complementary learning sections:

To structure the Human Learnings, the taxonomy of Tang et al. (arXiv, 2026) — drawn from 20,574 real sessions — provides seven forms of misalignment (misinterpretation of the intent, scope creep, off-spec solution, hallucinated requirement…): categorising each entry by the observed form reveals the recurring patterns of poorly expressed intent. By naming them, the Human Learnings prevent cognitive debt (Fowler/Joshi, 2026).

A category of their own: oversight failures

Among the Human Learnings, some are not due to a poorly expressed intent but to oversight that is absent or has become nominal. Doctrine v1.9 gives them their own category, because they recur in different forms. Two cases serve as references:

• An agent acting without approval (Meta, March 2026, according to press reports): an internal agent posted its answer on an internal forum on its own initiative, without the consent of the engineer who had asked it; another employee followed that advice, exposing sensitive data to unauthorised people for nearly two hours.
• Stacked automated reviews ("CVE-2026-LGTM", Andrew Nesbitt, June 2026): this story is satirical fiction, not a real incident. In it, a malicious package passes seven automated checks, each failing for a different reason, while two review agents lock themselves into a costly disagreement. Practitioners recognised their own pipelines in it: correlated blind spots across AI tools, and no human left to decide.

The question to ask in the retrospective: at what point should a human have been consulted, and why weren't they? The agent stop points are the preventive answer.

A guide with a hundred rules is less effective than a guide with ten well-chosen ones: the AGENT-GUIDE is bounded by the Context Budget (condensed ≤ 500 tokens per session). For the same reason, review exemplars are not included in it: they are only loaded in review sessions.

SPECs — the agent's work instruction

A SPEC bridges the intent (PRD, Intent) and the agent's implementation. A quality SPEC makes it possible to generate 80%+ of correct code on the first pass — it is the framework's best-ROI investment. Four criteria define it: atomicity, precision, testability, completeness — scored by the SQS at the Execution Gate (≥ 4/5 required). Each SPEC carries its own Drift Criterion and stays synchronised with the code on every PR.

Two sections, added by doctrine v1.9, frame what the agent is authorised to do: "Agent stop points" (optional — when the agent comes back to a human: approval, expert opinion, plurality of viewpoints, witness) and "Agent execution scope" (conditional — required as soon as the agent holds credentials or write access to a shared resource, "Not applicable" otherwise). See SPEC and Agent autonomy.

The Definitions of Done

The Definition of Output Done (DoOD) sets the standard for an increment to be shippable, in six categories: technical, security, performance, functional, deployment, review. The principle is non-negotiable: all criteria or nothing — "90% Done is not Done".

The Definition of Outcome Done (DoOuD) measures whether the expected value was realised: User Outcomes (NPS, adoption, retention), Business Outcomes (MRR, conversions, efficiency) and Learning Outcomes (hypotheses validated or invalidated, insights). The output is the means; the outcome is the goal — a feature shipped but not adopted is not a success.

The .aiad/ tree

.aiad/
├── PRD.md                  ← Product vision (injection: framing only)
├── ARCHITECTURE.md         ← Technical standards (permanent condensed version)
├── AGENT-GUIDE.md          ← Permanent context + Lessons Learned + Human Learnings
├── gouvernance/            ← Tier 1 agents with veto power
│   ├── _index.md
│   ├── AIAD-AI-ACT.md
│   ├── AIAD-RGPD.md
│   ├── AIAD-RGAA.md
│   ├── AIAD-RGESN.md
│   └── AIAD-CRA.md         ← Delivered as a complement (software products)
├── intents/                ← Intent Statements (WHY)
│   └── _index.md
├── specs/                  ← Technical SPECs (HOW)
│   └── _index.md
├── review-exemplars/       ← Review exemplars (optional, review sessions only)
├── facts/                  ← /sdd fact traces
├── metrics/
│   ├── security/           ← /sdd security reports
│   ├── audit/              ← /sdd audit reports
│   └── traceability/       ← /sdd trace snapshots (Markdown + JSON + HTML)
└── CHANGELOG-ARTEFACTS.md  ← Update history

The doctrine counts four Tier 1 guides (AI-ACT, RGPD, RGAA, RGESN). The AIAD-CRA agent is delivered as a complement by the package for software products: the reporting obligation to ENISA under the Cyber Resilience Act has been in force since 11/09/2026. The review-exemplars/ directory is an optional doctrine convention, to be created by the team.

Artifact anti-patterns