MDAAIProtocol documentation
TEMPLATESGH

First-generation template

The first-generation MDAAI template family uses Work Orders, corrective records, architecture decisions and checkpoints to govern project work.

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 whenInformation owner and update rule
AGENTS.md (root)Checked; template copyAgent navigation/contract pointer; inherited instructions.
project-meta.yaml (root)Checked; customize at instantiationOperator 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.mdChecked; template copy, always-sync listConstitution and protocols; AI read-only, maintained upstream.
GOVERNANCE/DOCUMENTATION-PROTOCOL.md; LIFECYCLE-PHASES-PROTOCOL.md; BETA-PHASE-PROTOCOL.mdPresent and always synced; not separately checkedBinding subject-specific governance; not routine task files.
CLASSIFICATION-REGULATIONS.mdPresent, referenced for formal initializationFormal classification/reference-number rules.
MANAGEMENT/AGENTS.md; PROJECT-ELABORATION.mdChecked; template scaffolding + project customizationNavigation is inherited; Elaboration owns task plan/progress/WO links under first-generation rules and is never synced.
MANAGEMENT/VISION.md; ROADMAP.mdExplicitly optional; presentOperator-owned direction/timeline; AI read-only, never synced.
MANAGEMENT/PROJECT-RULES.md; ENVIRONMENT.mdPresent; project-specificOperator-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.mdChecked; template copy; registry project-specificTemplates/navigation inherited; registry owns order allocation/index; agents reserve/register.
WORK-ORDERS/WO-YYYY-NNN-short-description.mdCreate before implementationExecutor authors authorized objective, specification, files and verification; completes/registers order.
WORK-ORDERS/CORRECTIVE/CWO-YYYY-NNN-short-description.mdCreate for remediation/protocol correctionExecutor records incident, cause, correction and prevention; links original work where applicable.
WORK-ORDERS/DIAGNOSTIC/DWO-YYYY-NNN-short-description.mdOptional investigation recordDiagnostic 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.mdChecked; template copyDecision-process scaffolding and accepted foundational ADR.
ARCHITECTURE/ADR-NNN-description.mdSignificant architecture decisionHuman 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.jsonChecked; template copyRead-only function contracts. Their presence does not prove tools are installed; direct document/registry updates are permitted when unavailable.
CHECKPOINTS/AGENTS.md; checkpoint-template.mdChecked; inherited template scaffoldingMilestone certificate navigation/template; authored checkpoint needs operator approval.
CHECKPOINTS/CP-NNN-PHASE-X-DESCRIPTION.mdAuthor when phase/version/ADR/significant milestone ends or operator requestsExecutor prepares from plan, WOs/CWOs, files and actual verification; operator approves; immutable after creation.
ANALYSIS/AGENTS.md; analysis-report-template.mdChecked; template scaffoldingExecutor 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.mdChecked; project-owned living documents after template copyExecutor 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 scaffoldingMachine-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. Reserve a number in WORK-ORDERS/registry.json and open the work-order-template.md record before implementation. Pending and active Work Orders may be updated with scope, files and actual verification; close only when acceptance evidence and actual expenditure are recorded. Closed WOs, corrective records and checkpoints remain immutable: later corrections use a linked corrective or superseding record. Register completion and WO links in Project Elaboration. The released template reconciles the prior editing-rule conflict; declarative rules and schemas do not themselves enforce permissions or prove evidence.

Selected headings from work-order-template.md
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

MDAAI 1.0 is a template name; its independent release is 1.0.1. Its constitution internal revision is 1.8, with historical 1.7/header metadata retained as origin history. Neither number is the standalone MDAAI protocol version (1.0.0). The corrected public release permits pending/active work-record updates and protects closed history. Original upstream sources and their historical hashes remain unchanged; 43 historical source-link gaps are documented separately from verified canonical public payloads.

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.md
  • First-generation template: .template/sync-manifest.yaml
  • First-generation template: .template/scripts/validate.sh
  • First-generation template: project-meta.yaml
  • First-generation template: PROJECT-INTERNAL/GOVERNANCE/AI-INSTRUCTIONS.md
  • First-generation template: PROJECT-INTERNAL/GOVERNANCE/WORK-ORDER-PROTOCOL.md
  • First-generation template: PROJECT-INTERNAL/GOVERNANCE/CHECKPOINT-PROTOCOL.md
  • First-generation template: PROJECT-INTERNAL/GOVERNANCE/MULTI-AGENT-PROTOCOL.md
  • First-generation template: PROJECT-INTERNAL/GOVERNANCE/DOCUMENTATION-PROTOCOL.md
  • First-generation template: PROJECT-INTERNAL/GOVERNANCE/LIFECYCLE-PHASES-PROTOCOL.md
  • First-generation template: PROJECT-INTERNAL/GOVERNANCE/BETA-PHASE-PROTOCOL.md
  • First-generation template: PROJECT-INTERNAL/GOVERNANCE/AGENTS.md
  • First-generation template: PROJECT-INTERNAL/CLASSIFICATION-REGULATIONS.md
  • First-generation template: PROJECT-INTERNAL/MANAGEMENT/AGENTS.md
  • First-generation template: PROJECT-INTERNAL/MANAGEMENT/PROJECT-ELABORATION.md
  • First-generation template: PROJECT-INTERNAL/MANAGEMENT/VISION.md
  • First-generation template: PROJECT-INTERNAL/MANAGEMENT/ROADMAP.md
  • First-generation template: PROJECT-INTERNAL/MANAGEMENT/PROJECT-RULES.md
  • First-generation template: PROJECT-INTERNAL/MANAGEMENT/ENVIRONMENT.md
  • First-generation template: PROJECT-INTERNAL/WORK-ORDERS/AGENTS.md
  • First-generation template: PROJECT-INTERNAL/WORK-ORDERS/work-order-template.md
  • First-generation template: PROJECT-INTERNAL/WORK-ORDERS/registry.json
  • First-generation template: PROJECT-INTERNAL/WORK-ORDERS/CORRECTIVE/corrective-work-order-template.md
  • First-generation template: PROJECT-INTERNAL/ARCHITECTURE/AGENTS.md
  • First-generation template: PROJECT-INTERNAL/ARCHITECTURE/adr-template.md
  • First-generation template: PROJECT-INTERNAL/ARCHITECTURE/ADR-000-record-architecture-decisions.md
  • First-generation template: PROJECT-INTERNAL/AI/AGENTS.md
  • First-generation template: PROJECT-INTERNAL/AI/functions/work-orders.json
  • First-generation template: PROJECT-INTERNAL/AI/functions/registry.json
  • First-generation template: PROJECT-INTERNAL/AI/functions/reporting.json
  • First-generation template: PROJECT-INTERNAL/CHECKPOINTS/AGENTS.md
  • First-generation template: PROJECT-INTERNAL/CHECKPOINTS/checkpoint-template.md
  • First-generation template: PROJECT-INTERNAL/ANALYSIS/AGENTS.md
  • First-generation template: PROJECT-INTERNAL/ANALYSIS/analysis-report-template.md
  • First-generation template: PROJECT-INTERNAL/KNOWLEDGE/AGENTS.md
  • First-generation template: PROJECT-INTERNAL/KNOWLEDGE/DEVELOPER-GUIDE.md
  • First-generation template: PROJECT-INTERNAL/KNOWLEDGE/DEVELOPMENT-PRACTICES.md
  • First-generation template: PROJECT-INTERNAL/KNOWLEDGE/GOTCHAS.md
  • First-generation template: PROJECT-INTERNAL/KNOWLEDGE/ERROR-CATALOG.md
  • First-generation template: .template/agent-rules.yaml

Search documentation

Search runs locally. No query leaves your browser.

↑ ↓ move · Enter open · Esc close