Repository structure

The minimal MDAAI 2.0 adoption map. Required means part of the portable contract, not every file required by the source laboratory’s own validator.

By Eris Margeta Kurdali · Repository

Files and information owners

At adoption, merge the governance instructions and author the two management files for the target project. The map below uses exact core paths. Conditional pattern rows describe record categories, not files an installer creates. Each core file has an explanatory section linked below.

Repository tree

AGENTS.md                                  [required core]
CLAUDE.md                                  [optional pointer]
PROJECT-INTERNAL/
├── GOVERNANCE/                            [required core]
│   ├── AUTHORITY.md
│   ├── ENGINEERING.md
│   ├── EVIDENCE.md
│   ├── REASONING.md
│   └── RECORDS.md
├── MANAGEMENT/                            [required project-owned]
│   ├── PROJECT-ELABORATION.md
│   └── TASKS.json
├── ARCHITECTURE/                           [conditional decisions]
│   └── project-selected ADR files
└── RECORDS/                                [conditional example location]
    └── project-selected durable records

Evidence lives at project-selected paths; no universal evidence folder.

Path / category	Required when	Owns / references	Created and updated by
`AGENTS.md`	Required core	Operating contract and entry point. Names the canonical scope/task owners and links the five rule documents.	Operator-authorized maintainer merges on adoption; change only when the contract changes.
`CLAUDE.md`	Optional pointer	Points to AGENTS.md; owns no independent rules.	Copy or adapt if that assistant entry point is used; keep as a pointer.
`PROJECT-INTERNAL/GOVERNANCE/AUTHORITY.md`	Required core	Authorization, private data and protected work. Read before effects; a task row is not permission.	Merge on adoption; authorized maintainer updates when authority rules change.
`PROJECT-INTERNAL/GOVERNANCE/ENGINEERING.md`	Required core	Domain design, architecture decisions, regression-first defect repair and resource hygiene.	Merge on adoption; executor reads for relevant implementation or defects.
`PROJECT-INTERNAL/GOVERNANCE/EVIDENCE.md`	Required core	Evidence profiles and the limits of acceptance claims. References checks/logs, not a second task list.	Merge on adoption; consult when selecting checks and claiming results.
`PROJECT-INTERNAL/GOVERNANCE/REASONING.md`	Required core	Context economy and single-writer coordination. Coordinator owns integration and status.	Merge on adoption; consult during planning, delegation and resumption.
`PROJECT-INTERNAL/GOVERNANCE/RECORDS.md`	Required core	Task states, scheduling dispositions, durable records and terminal supersession. Links TASKS.json.	Merge on adoption; read when updating or recovering task records.
`PROJECT-INTERNAL/MANAGEMENT/PROJECT-ELABORATION.md`	Required project-owned	Scope and sequence only. Links TASKS.json; does not duplicate task status checkboxes.	Operator/authorized executor writes project-specific scope at adoption; revise when scope/order changes.
`PROJECT-INTERNAL/MANAGEMENT/TASKS.json`	Required project-owned	Only task state, disposition, owner, acceptance evidence, blocker, next action and history source. scopeRef points to scope; evidence references actual artifacts.	Create fresh at adoption; task owner/coordinator updates active rows as work/evidence changes.
Architecture decisions (project-selected paths)	Conditional; no mandated 2.0 filename	Architecture tradeoffs, alternatives, migration/rollback and limits. Link the project’s actual ADR from the task.	Authorized executor writes when architecture changes warrant a compact ADR; not for every edit.
PROJECT-INTERNAL/RECORDS/…	Conditional; project-selected record path	Decision, defect cause, handoff or external-effect context not understandable from task/evidence alone.	Authorized owner creates only when needed. RECORDS/ exists in the source package; adoption does not require this folder.
Evidence artifacts (project-selected paths)	Conditional; paths are not prescribed	Tests, logs and artifact observations supporting acceptance; task evidence.reference locates them.	Executor produces actual evidence appropriate to changed surface; keep private data out.

AGENTS.md

Start here. Its operating contract tells the agent to read the assigned task and only named relevant references, preserves higher-level and nearest-repository constraints, and links authority, engineering, evidence, reasoning and records. It is not the place for a second task list.

CLAUDE.md

The source pointer says: “Read AGENTS.md. It is the only operating contract; this file adds no independent rules.” It is optional for adoption and should not evolve into a competing constitution.

AUTHORITY.md

Owns the boundary between bounded implementation and effects needing action-time authorization. It covers data classification, credentials, Git and protected work. Read before the affected action. Writing an active task or plan never expands permission.

ENGINEERING.md

Owns implementation and defect-repair rules. Domain invariants stay with their domain owner. Architecture changes get a compact ADR when warranted. Defects follow investigation → faithful regression → adjacent-test audit → red → root fix → affected green; expected red tests are not new corrective work orders.

EVIDENCE.md

Owns what level of proof an acceptance claim needs. Documentation checks, unit tests, ordinary startup, real-browser observation and deployed-state verification are distinct. The task stores references and results; the evidence file does not repeat task status.

REASONING.md

Owns economical context gathering and coordination. Read relevant records first, expand only for a concrete uncertainty, give each mutable file one writer, and leave shared integration/status to the coordinator. It does not prescribe a personal model launcher or local agent configuration.

RECORDS.md

Owns task/record semantics and recovery rules. It links the management registry and defines lifecycle states separately from scheduling disposition. Active records can evolve; coherent terminal results are preserved and corrected through linked supersession.

PROJECT-ELABORATION.md

Owns the project’s authorized scope and delivery order. The adopting project writes its own content. It links TASKS.json for live status and evidence, rather than copying progress checkboxes. Change it when project scope or sequencing changes—not for every state transition.

TASKS.json

Owns current tasks and their audit history. A task has a stable project-prefixed ID, owner, scopeRef, acceptance criteria, state, disposition, evidence, blocker, next action, dependencies and history. The owner/coordinator updates active work here. Start with a fresh target-specific registry; do not copy the source package’s tasks.

See a minimal task record →

Conditional decisions

ENGINEERING.md requires a compact ADR for architecture changes. Preserve accepted decisions and supersede them when warranted. The portable 2.0 adoption guide does not mandate a fixed ADR filename or an ADR template; use the target’s decision convention and link the actual file.

Conditional context records

RECORDS.md permits a short durable record when a material decision, defect cause, review, handoff or external effect needs context beyond the task/evidence. Include ID/date, owner, scope, decision/mechanism, result/limits, next action and supersession link as applicable. No routine WO, CWO or checkpoint is required. PROJECT-INTERNAL/RECORDS/ is a source-package location, not a mandatory adoption artifact.

Evidence artifacts

TASKS.json evidence entries reference project-local artifacts when possible. Their exact paths and formats depend on the checks performed. Evidence identifies what was observed; a digest or log alone is not semantic proof. Generated runtime dependencies are not automatically disposable.

Source references

Based on original contracts and templates. These are source locations, not installed-file claims. No private source archives are served.

MDAAI 2.0: AGENTS.md
MDAAI 2.0: CLAUDE.md
MDAAI 2.0: docs/ADOPTION.md
MDAAI 2.0: scripts/validate.py
MDAAI 2.0: PROJECT-INTERNAL/GOVERNANCE/AUTHORITY.md
MDAAI 2.0: PROJECT-INTERNAL/GOVERNANCE/ENGINEERING.md
MDAAI 2.0: PROJECT-INTERNAL/GOVERNANCE/EVIDENCE.md
MDAAI 2.0: PROJECT-INTERNAL/GOVERNANCE/REASONING.md
MDAAI 2.0: PROJECT-INTERNAL/GOVERNANCE/RECORDS.md
MDAAI 2.0: PROJECT-INTERNAL/MANAGEMENT/PROJECT-ELABORATION.md
MDAAI 2.0: PROJECT-INTERNAL/MANAGEMENT/TASKS.json