Machine-readable Engineering and Technical Architecture files.
Part of the A2ML Format Family — A2ML (Annotated Markup Language) TOML-like key-value data formats for software engineering workflows.
This repository is part of the A2ML Format Family — 7 A2ML formats for software engineering workflows. All specification repos are satellites of hyperpolymath/standards.
| Format | Tier | Purpose | Specification |
|---|---|---|---|
|
Primary |
Architecture decisions (ADRs), development practices |
This repo |
|
Primary |
Project state, phase, milestones, session history |
Companion (this repo) |
|
Primary |
Ecosystem positioning, related projects |
Companion (this repo) |
|
Execution |
Executable plans, procedures, alerts |
|
|
Execution |
AI agent operational gating, entropy budgets |
|
|
Execution |
Symbolic semantics, proof obligations |
|
|
Intervention |
Project recalibration/realignment |
All implementations MUST respect this ordering:
1. META validation <- Constitutional authority check
2. AGENTIC gating <- Operational safety
3. NEUROSYM semantics <- Proof obligations
4. PLAYBOOK derivation <- Build executable plan
5. Execution
6. ECOSYSTEM check <- Integrity verification
7. STATE update <- Record outcome
INTERVENTION: ANCHOR.a2ml can override any levelMETA.a2ml is a format specification for documenting software project metadata, architecture decisions, and development practices in machine-readable A2ML (Annotated Markup Language) TOML-like key-value syntax.
# SPDX-License-Identifier: PMPL-1.0-or-later
[meta]
project = "my-project"
[meta.architecture-decisions.adr-001]
title = "Use Event Sourcing"
status = "accepted"
date = "2025-01-15"
context = "Need complete audit trail for orders"
decision = "Implement event sourcing for order service"
consequences = ["Full history", "Replay capability", "Eventual consistency"]
[meta.development-practices.testing]
framework = "pytest"
coverage-minimum = 80
[meta.development-practices.versioning]
scheme = "Semantic Versioning 2.0.0"
[meta.design-rationale]
why-event-sourcing = "Event sourcing provides immutable audit trail and temporal queries."| Feature | Benefit |
|---|---|
Machine-Readable |
Tooling can parse, validate, and generate documentation |
Human-Readable |
TOML-like key-value pairs are readable without special editors |
Structured ADRs |
Architecture decisions in queryable format |
VCS-Friendly |
Plain text diffs, merges, and history |
Extensible |
Add custom sections without breaking compatibility |
Cross-Format |
STATE.a2ml can reference META.a2ml for project context |
Structured Architecture Decision Records (ADRs):
-
Unique identifier (
adr-NNN) -
Title, status, date
-
Context (problem statement)
-
Decision (what was decided)
-
Consequences (implications)
Codified development standards:
-
code-style- Formatters, linters, type systems -
security- Security requirements -
testing- Test frameworks, coverage requirements -
versioning- Version scheme, changelog format -
deployment- Deployment strategy, environments -
review- Code review process
# SPDX-License-Identifier: PMPL-1.0-or-later
# SPDX-FileCopyrightText: 2026 Your Name
# META.a2ml -- Architecture Decisions and Development Practices
[meta]
project = "your-project"
[meta.architecture-decisions.adr-001]
title = "Your First Decision"
status = "accepted"
date = "2025-01-01"
context = "Describe the problem or situation"
decision = "What you decided"
consequences = ["Consequence 1", "Consequence 2"]
[meta.development-practices.code-style]
formatter = "your-formatter"
linter = "your-linter"
[meta.design-rationale]
why-this-decision = "Explain the reasoning behind your key decisions."The formal specification is in the spec/ directory:
-
SCM-FORMAT-FAMILY.adoc - A2ML format family overview
-
UNIFIED-STANDARDS-STRATEGY.adoc - Coordinated standards approach
-
META-FORMAT-SPEC.adoc - Complete specification
-
schema/meta.schema.json - JSON Schema
-
VERSION-POLICY.adoc - Version policy
-
STANDARDS-TRACK.adoc - Standardization roadmap
-
IANA-MEDIA-TYPE.adoc - Media type registration
See the examples/ directory:
-
minimal.scm - Minimal valid META file
-
comprehensive.scm - Full-featured example
STATE.a2ml files (AI session checkpoints) can reference META.a2ml for project context:
# In STATE.a2ml
[state.projects.my-project]
path = "/home/user/my-project"
meta-ref = "META.a2ml"
active-adrs = ["adr-001", "adr-003"]
relevant-practices = ["security", "testing"]This enables AI assistants to:
-
Query architecture decisions during implementation
-
Enforce development practices
-
Understand design rationale
-
Maintain context across sessions
The A2ML Format Family is on track for formal standardization:
| Phase | Target | Status |
|---|---|---|
Community Specification |
Reference implementations, community adoption |
In Progress |
IANA Registration |
|
Planned |
IETF RFC Series |
Core syntax + format-specific RFCs |
Planned |
See UNIFIED-STANDARDS-STRATEGY.adoc for the coordinated roadmap.
-
MIME Type:
application/vnd.meta+a2ml -
File Extension:
.a2ml(conventionallyMETA.a2ml) -
Encoding: UTF-8
| Status | Meaning |
|---|---|
|
Under consideration |
|
Decided and in effect |
|
No longer recommended |
|
Replaced by another decision |
|
Considered but not adopted |
-
VS Code extension with syntax highlighting and validation
-
CLI tool for linting and documentation generation
-
CI/CD integration for ADR policy enforcement
-
Markdown/HTML documentation generator
-
Shared A2ML parser library (Rust, ReScript)
See CONTRIBUTING.md for contribution guidelines.
Standards Hub:
-
standards — Organization standards hub
-
SATELLITES.a2ml — Machine-readable satellite registry
A2ML Format Family (Siblings):
-
playbook-a2ml — PLAYBOOK.a2ml (execution tier)
-
agentic-a2ml — AGENTIC.a2ml (execution tier)
-
neurosym-a2ml — NEUROSYM.a2ml (execution tier)
-
anchor-a2ml — ANCHOR.a2ml (intervention tier)
Related Standards:
-
MADR - Markdown ADR format
-
SPDX - Software Package Data Exchange
-
ISO/IEC 5962:2021 - SPDX as ISO standard