How files work together
One owner for each kind of information; links connect the owners instead of copying their contents.
By Eris Margeta Kurdali · Repository
Startup reading order
Read the applicable AGENTS.md and the assigned TASKS.json row first. Follow scopeRef to Project Elaboration or the actual scope owner; read linked evidence and only relevant governance references. Inspect the current working tree/runtime before resuming. Do not execute deferred tasks merely because they are visible. The source entry point names instructions → assigned task → relevant references; this diagram expands those actual relationships, not a new mandatory ceremony.
Read, write and reference directions
AGENTS.md supplies the operating contract; the rule documents constrain work. TASKS.json points to scope and evidence. Project Elaboration links back to the registry for status. The executor reads these inputs, changes only authorized product files, and writes actual evidence; the task owner/coordinator updates the canonical row. Architecture decisions and other durable records are conditional supporting references.
| From | Direction / destination | Meaning |
|---|---|---|
| AGENTS.md | read → assigned TASKS.json row | Find current task; follow relevant rule links. |
| TASKS.json scopeRef | reference → scope owner | Locate bounded project scope, not another status list. |
| Project Elaboration | reference → TASKS.json | Read state/evidence here; do not copy checkboxes. |
| Task owner / coordinator | write → active TASKS.json row | Update owner, state, disposition, next action, evidence and transition history. |
| Executor | write → authorized product + actual evidence | Implementation and observations, constrained by instructions and scope. |
| TASKS.json evidence.reference | reference → evidence / conditional record | Locate result context and limits. |
| Later correction task | reference → earlier terminal record + new evidence | Preserve the historical result; express correction without erasing it. |
Why not duplicate status?
A project plan may say “implement request validation before UI integration,” while the registry says that validation is active and its next action is a boundary test. Those are different facts. Updating active state in both a Markdown checkbox list and JSON creates competing answers. Put scope/order in Project Elaboration, current progress in TASKS.json, actual observations in evidence, and architectural rationale in the decision record.
What changes during ordinary work
Usually the implementation, relevant tests/docs, evidence artifacts and one active task row change. Governance files do not need an edit for each feature. Project Elaboration changes only for scope/sequence changes. An ADR appears only for a relevant architecture decision; a separate durable record appears only for context the row and evidence cannot carry clearly.
History and recovery
Append a concise transition for lifecycle/disposition changes. Once a record has a coherent terminal result, preserve its meaning. A later discovered defect gets its own task with a link to the earlier result; material corrections use linked supersession. The registry can add that correction link without deleting the old transition. Resumption uses current nonterminal rows, linked evidence and live state—not an unbounded replay of old conversations.
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.mdMDAAI 2.0: CLAUDE.mdMDAAI 2.0: docs/ADOPTION.mdMDAAI 2.0: scripts/validate.pyMDAAI 2.0: PROJECT-INTERNAL/GOVERNANCE/AUTHORITY.mdMDAAI 2.0: PROJECT-INTERNAL/GOVERNANCE/ENGINEERING.mdMDAAI 2.0: PROJECT-INTERNAL/GOVERNANCE/EVIDENCE.mdMDAAI 2.0: PROJECT-INTERNAL/GOVERNANCE/REASONING.mdMDAAI 2.0: PROJECT-INTERNAL/GOVERNANCE/RECORDS.mdMDAAI 2.0: PROJECT-INTERNAL/MANAGEMENT/PROJECT-ELABORATION.mdMDAAI 2.0: PROJECT-INTERNAL/MANAGEMENT/TASKS.json