First-generation MDAAI
A template-centered workflow: project plan → authorized Work Order → implementation and verification → registered result. The inspected template is first-generation lineage, not a pristine protocol 1.0 snapshot.
By Eris Margeta Kurdali · Repository
What the template puts in a repository
Instantiation copies a repository template and customizes project-specific metadata and management content. The template includes governance, management, work-order and architecture scaffolding. Work Orders and later decisions are authored during work; they are not all pre-generated by instantiation. The template’s sync manifest separates inherited instructions from project-owned history so upstream synchronization does not overwrite local plans or work records.
First-generation file map
The following groups are present in the inspected canonical template. “Checked” names the template validator’s required-file checks; it does not imply every unchecked policy is optional. Root README.md, VERSION, SECURITY.md, CONTRIBUTING.md and CODE_OF_CONDUCT.md are also baseline template files, not per-task records.
| Exact paths (PROJECT-INTERNAL/ unless root noted) | Required / created when | Information owner and update rule |
|---|---|---|
| AGENTS.md; CLAUDE.md (root) | Checked; template copy | Agent navigation/contract pointer; inherited instructions. |
| project-meta.yaml (root) | Checked; customize at instantiation | Operator identity/classification, template lineage and project conventions; never synced. |
| GOVERNANCE/AI-INSTRUCTIONS.md; MULTI-AGENT-PROTOCOL.md; WORK-ORDER-PROTOCOL.md; CHECKPOINT-PROTOCOL.md; AGENTS.md | Checked; template copy, always-sync list | Constitution and protocols; AI read-only, maintained upstream. |
| GOVERNANCE/DOCUMENTATION-PROTOCOL.md; LIFECYCLE-PHASES-PROTOCOL.md; BETA-PHASE-PROTOCOL.md | Present and always synced; not separately checked | Binding subject-specific governance; not routine task files. |
| CLASSIFICATION-REGULATIONS.md | Present, referenced for formal initialization | Formal classification/reference-number rules. |
| MANAGEMENT/AGENTS.md; PROJECT-ELABORATION.md | Checked; template scaffolding + project customization | Navigation is inherited; Elaboration owns task plan/progress/WO links under first-generation rules and is never synced. |
| MANAGEMENT/VISION.md; ROADMAP.md | Explicitly optional; present | Operator-owned direction/timeline; AI read-only, never synced. |
| MANAGEMENT/PROJECT-RULES.md; ENVIRONMENT.md | Present; project-specific | Operator-owned binding rules and system environment; AI read-only, never synced. |
| WORK-ORDERS/AGENTS.md; work-order-template.md; registry.json; CORRECTIVE/corrective-work-order-template.md | Checked; template copy; registry project-specific | Templates/navigation inherited; registry owns order allocation/index; agents reserve/register. |
| WORK-ORDERS/WO-YYYY-NNN-short-description.md | Create before implementation | Executor authors authorized objective, specification, files and verification; completes/registers order. |
| WORK-ORDERS/CORRECTIVE/CWO-YYYY-NNN-short-description.md | Create for remediation/protocol correction | Executor records incident, cause, correction and prevention; links original work where applicable. |
| WORK-ORDERS/DIAGNOSTIC/DWO-YYYY-NNN-short-description.md | Optional investigation record | Diagnostic type is defined; no standalone diagnostic template was found. Read-only investigation needs no WO. |
| ARCHITECTURE/AGENTS.md; adr-template.md; ADR-000-record-architecture-decisions.md | Checked; template copy | Decision-process scaffolding and accepted foundational ADR. |
| ARCHITECTURE/ADR-NNN-description.md | Significant architecture decision | Human initiates/approves; assistant drafts; implementation recorded through WO. Accepted ADR immutable, superseded by a new ADR. |
| AI/AGENTS.md; functions/work-orders.json; functions/registry.json; functions/reporting.json | Checked; template copy | Read-only function contracts. Their presence does not prove tools are installed; direct document/registry updates are permitted when unavailable. |
| CHECKPOINTS/AGENTS.md; checkpoint-template.md | Checked; inherited template scaffolding | Milestone certificate navigation/template; authored checkpoint needs operator approval. |
| CHECKPOINTS/CP-NNN-PHASE-X-DESCRIPTION.md | Author when phase/version/ADR/significant milestone ends or operator requests | Executor prepares from plan, WOs/CWOs, files and actual verification; operator approves; immutable after creation. |
| ANALYSIS/AGENTS.md; analysis-report-template.md | Checked; template scaffolding | Executor writes authorized durable investigations with scope/evidence/findings; links WO/ADR; analysis alone grants no implementation authority. |
| KNOWLEDGE/AGENTS.md; DEVELOPER-GUIDE.md; DEVELOPMENT-PRACTICES.md; GOTCHAS.md; ERROR-CATALOG.md | Checked; project-owned living documents after template copy | Executor updates technical context, patterns, pitfalls and resolved errors when warranted; reference source WO/CWO. |
| .template/agent-rules.yaml; .template/sync-manifest.yaml (root) | Checked; inherited scaffolding | Machine-readable constraints and inherited/project-owned synchronization policy; presence alone is not automated enforcement. |
A Work Order connects authorization to the change
A task reference points from the order back to the operator request or Project Elaboration; Related ADR and Depends On link decisions and predecessor work. The template describes reserving a number in WORK-ORDERS/registry.json, opening an order before implementation, recording files/verification, and registering the result with completion/WO links in Project Elaboration. However, root AGENTS.md and WORK-ORDER-PROTOCOL.md also prohibit editing WOs after creation, while work-order-template.md expects active updates. Adopters must reconcile this contradiction with operator authority before executing that workflow; this documentation does not silently choose one rule.
AUTHORIZATION
Task Reference
Related ADR
Depends On
OBJECTIVE
TECHNICAL SPECIFICATION
VERIFICATION STEPS
FILES CHANGED
VERIFICATION RESULTS
STATUS
PENDING → IN PROGRESS → COMPLETED (or BLOCKED)CWO and ADR serve different purposes
A CWO captures an error’s classification, root cause, correction, prevention and verification. An ADR captures the context, decision drivers, alternatives, chosen outcome and validation for an architecture decision. Neither is a substitute for the authorized project task. Completed work and accepted decisions retain historical meaning; later decisions supersede rather than silently erase accepted ADRs.
Checkpoints certify milestones, not each edit
CHECKPOINT-PROTOCOL.md requires a checkpoint at phase completion, a major version increment, finalized ADR implementation, a significant milestone or an operator request. Before creating it, synchronize relevant project knowledge, ensure WOs/CWOs are resolved and logged, run the required tests, update documentation and obtain human approval. The checkpoint gathers scope, deliverables, work orders, files, verification and next-phase context. It is immutable after creation; errors require a linked CWO, not an edit to the certificate.
Source note
The currently inspected first-generation constitution labels itself Version 1.7, Revision 8. Other template component metadata uses different protocol labels. “First generation” here names the template workflow and lineage; it does not assert every retained file is version 1.0 or confuse those labels with the separate MDAAI 2.0 package. The template also contains legacy reference/casing inconsistencies; its Markdown templates and function contracts should not be treated as one identical schema.
Source references
Based on original contracts and templates. These are source locations, not installed-file claims. No private source archives are served.
First-generation template: AGENTS.mdFirst-generation template: .template/sync-manifest.yamlFirst-generation template: .template/scripts/validate.shFirst-generation template: project-meta.yamlFirst-generation template: PROJECT-INTERNAL/GOVERNANCE/AI-INSTRUCTIONS.mdFirst-generation template: PROJECT-INTERNAL/GOVERNANCE/WORK-ORDER-PROTOCOL.mdFirst-generation template: PROJECT-INTERNAL/GOVERNANCE/CHECKPOINT-PROTOCOL.mdFirst-generation template: PROJECT-INTERNAL/GOVERNANCE/MULTI-AGENT-PROTOCOL.mdFirst-generation template: PROJECT-INTERNAL/GOVERNANCE/DOCUMENTATION-PROTOCOL.mdFirst-generation template: PROJECT-INTERNAL/GOVERNANCE/LIFECYCLE-PHASES-PROTOCOL.mdFirst-generation template: PROJECT-INTERNAL/GOVERNANCE/BETA-PHASE-PROTOCOL.mdFirst-generation template: PROJECT-INTERNAL/GOVERNANCE/AGENTS.mdFirst-generation template: PROJECT-INTERNAL/CLASSIFICATION-REGULATIONS.mdFirst-generation template: PROJECT-INTERNAL/MANAGEMENT/AGENTS.mdFirst-generation template: PROJECT-INTERNAL/MANAGEMENT/PROJECT-ELABORATION.mdFirst-generation template: PROJECT-INTERNAL/MANAGEMENT/VISION.mdFirst-generation template: PROJECT-INTERNAL/MANAGEMENT/ROADMAP.mdFirst-generation template: PROJECT-INTERNAL/MANAGEMENT/PROJECT-RULES.mdFirst-generation template: PROJECT-INTERNAL/MANAGEMENT/ENVIRONMENT.mdFirst-generation template: PROJECT-INTERNAL/WORK-ORDERS/AGENTS.mdFirst-generation template: PROJECT-INTERNAL/WORK-ORDERS/work-order-template.mdFirst-generation template: PROJECT-INTERNAL/WORK-ORDERS/registry.jsonFirst-generation template: PROJECT-INTERNAL/WORK-ORDERS/CORRECTIVE/corrective-work-order-template.mdFirst-generation template: PROJECT-INTERNAL/ARCHITECTURE/AGENTS.mdFirst-generation template: PROJECT-INTERNAL/ARCHITECTURE/adr-template.mdFirst-generation template: PROJECT-INTERNAL/ARCHITECTURE/ADR-000-record-architecture-decisions.mdFirst-generation template: PROJECT-INTERNAL/AI/AGENTS.mdFirst-generation template: PROJECT-INTERNAL/AI/functions/work-orders.jsonFirst-generation template: PROJECT-INTERNAL/AI/functions/registry.jsonFirst-generation template: PROJECT-INTERNAL/AI/functions/reporting.jsonFirst-generation template: PROJECT-INTERNAL/CHECKPOINTS/AGENTS.mdFirst-generation template: PROJECT-INTERNAL/CHECKPOINTS/checkpoint-template.mdFirst-generation template: PROJECT-INTERNAL/ANALYSIS/AGENTS.mdFirst-generation template: PROJECT-INTERNAL/ANALYSIS/analysis-report-template.mdFirst-generation template: PROJECT-INTERNAL/KNOWLEDGE/AGENTS.mdFirst-generation template: PROJECT-INTERNAL/KNOWLEDGE/DEVELOPER-GUIDE.mdFirst-generation template: PROJECT-INTERNAL/KNOWLEDGE/DEVELOPMENT-PRACTICES.mdFirst-generation template: PROJECT-INTERNAL/KNOWLEDGE/GOTCHAS.mdFirst-generation template: PROJECT-INTERNAL/KNOWLEDGE/ERROR-CATALOG.mdFirst-generation template: .template/agent-rules.yaml