Canonical directory structure and file requirements for all A2ML format specification repositories.
All repositories in the A2ML Format Family (meta-a2ml, state-a2ml, ecosystem-a2ml, playbook-a2ml, agentic-a2ml, neurosym-a2ml, anchor-a2ml) MUST follow this template structure to ensure consistency, discoverability, and machine-readability.
| Format | Repository | Purpose | Media Type |
|---|---|---|---|
META.a2ml |
hyperpolymath/meta-a2ml |
Architecture decisions, development practices |
|
STATE.a2ml |
(defined in meta-a2ml) |
Project state, milestones, session history |
|
ECOSYSTEM.a2ml |
(defined in meta-a2ml) |
Ecosystem positioning, relationships |
|
PLAYBOOK.a2ml |
hyperpolymath/playbook-a2ml |
Executable plans, operational runbooks |
|
AGENTIC.a2ml |
hyperpolymath/agentic-a2ml |
AI agent operational gating, safety controls |
|
NEUROSYM.a2ml |
hyperpolymath/neurosym-a2ml |
Symbolic semantics, composition algebra |
|
ANCHOR.a2ml |
hyperpolymath/anchor-a2ml |
Project recalibration, scope intervention |
|
Every A2ML specification repository MUST have:
{format}-a2ml/
├── .claude/
│ └── CLAUDE.md # AI assistant instructions
├── .github/
│ └── workflows/ # CI/CD workflows
├── .machine_readable/ # 7 A2ML metadata files for THIS repo
│ ├── STATE.a2ml
│ ├── META.a2ml
│ ├── ECOSYSTEM.a2ml
│ ├── AGENTIC.a2ml
│ ├── NEUROSYM.a2ml
│ ├── PLAYBOOK.a2ml
│ └── ANCHOR.a2ml
├── spec/ # Formal specifications
│ ├── {FORMAT}-FORMAT-SPEC.adoc # Primary specification (RFC-style)
│ ├── CONFORMANCE.adoc # Compliance requirements
│ ├── VERSION-POLICY.adoc # Version evolution rules
│ ├── IANA-MEDIA-TYPE.adoc # Media type registration
│ ├── schema/
│ │ └── {format}.schema.json # JSON Schema (for tooling)
│ └── shared/ # Shared with other A2ML specs
│ └── a2ml-common.schema.json # Common JSON definitions
├── examples/ # Reference implementations
│ ├── minimal.a2ml # Minimal valid file
│ └── comprehensive.a2ml # Full-featured example
├── docs/ # Additional documentation
│ ├── INTEGRATION.adoc # How to use with other A2ML formats
│ ├── TOOLING.adoc # Parser/validator info
│ └── FAQ.adoc # Common questions
├── README.adoc # Overview and quick start
├── CONTRIBUTING.md # Contribution guidelines
├── CONTRIBUTING.adoc # Detailed contribution guide
├── SECURITY.md # Security policy
├── CODE_OF_CONDUCT.md # Community standards
├── LICENSE.txt # PMPL-1.0-or-later
├── SATELLITES.a2ml # List of satellite projects (if hub)
├── Justfile # Build/test automation
└── Mustfile # Mandatory checksMUST contain:
-
Format Family Badge: Link to A2ML Format Family
-
License Badges: PMPL-1.0 + Palimpsest
-
Purpose Statement: One-line description of this format
-
The A2ML Format Family: Table showing all 7 formats
-
What is {FORMAT}.a2ml?: Detailed explanation
-
Why {FORMAT}.a2ml?: Feature/benefit table
-
Core Sections: Document structure
-
Getting Started: Minimal example
-
Specification Links: Links to spec/ directory
-
Examples: Links to examples/
-
Integration: How it works with other A2ML formats
-
Standards Track: IETF/IANA roadmap
-
Media Type: MIME type and extension
RFC-style specification MUST contain:
-
Abstract: Summary of the format
-
Status of This Memo: Document status
-
Copyright Notice: License
-
Introduction: Purpose and design goals
-
Terminology: RFC 2119/8174 key words
-
File Structure: Grammar overview
-
Core Sections: Required fields and semantics
-
Extension Sections: How to add custom sections
-
Parsing Requirements: Implementation guidance
-
Security Considerations: Security implications
-
IANA Considerations: Media type registration
-
References: Normative and informative
Minimal valid file demonstrating required structure:
# SPDX-License-Identifier: MIT
# SPDX-FileCopyrightText: 2026 Example Author
# {FORMAT}.a2ml -- Minimal Example
[{format}]
version = "1.0.0"
project = "minimal-project"
[{format}.required-section]
# Minimal required content ┌─────────────────────────────────────┐
│ hyperpolymath/standards │
│ (Organization Hub) │
└────────────────┬────────────────────┘
│
┌────────────────────────────┼────────────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ meta-a2ml│ │agentic- │ │ anchor- │
│(primary) │ │ a2ml │ │ a2ml │
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
┌────┴────┐ │ │
│ │ │ │
▼ ▼ ▼ ▼
STATE.a2ml ECOSYSTEM.a2ml PLAYBOOK.a2ml (intervention
(companion) (companion) NEUROSYM.a2ml format)
(execution layer)All implementations MUST respect this order:
-
META validation (constitutional authority)
-
AGENTIC gating (operational safety)
-
NEUROSYM semantics (proof obligations)
-
PLAYBOOK derivation (executable plan)
-
Execution
-
ECOSYSTEM integrity check
-
STATE update
ANCHOR.a2ml is special: it can be dropped in at any time to trigger a recalibration, reviewing all 6 A2ML files and realigning the project.
All A2ML specification repos MUST be registered in hyperpolymath/standards/SATELLITES.a2ml:
[satellites]
version = "2.0.0"
[satellites.hub]
name = "standards"
url = "https://github.com/hyperpolymath/standards"
description = "Organization-wide standards and policies"
[satellites.repos.meta-a2ml]
url = "https://github.com/hyperpolymath/meta-a2ml"
role = "specification"
format-defines = ["META.a2ml", "STATE.a2ml", "ECOSYSTEM.a2ml"]
description = "META format specification and companions"
[satellites.repos.playbook-a2ml]
url = "https://github.com/hyperpolymath/playbook-a2ml"
role = "specification"
format-defines = ["PLAYBOOK.a2ml"]
description = "Executable plan specification"
[satellites.repos.agentic-a2ml]
url = "https://github.com/hyperpolymath/agentic-a2ml"
role = "specification"
format-defines = ["AGENTIC.a2ml"]
description = "AI agent operational gating specification"
[satellites.repos.neurosym-a2ml]
url = "https://github.com/hyperpolymath/neurosym-a2ml"
role = "specification"
format-defines = ["NEUROSYM.a2ml"]
description = "Symbolic semantics specification"
[satellites.repos.anchor-a2ml]
url = "https://github.com/hyperpolymath/anchor-a2ml"
role = "specification"
format-defines = ["ANCHOR.a2ml"]
description = "Project recalibration intervention format"# In STATE.a2ml - reference META for decisions
[state.current-context]
active-meta-ref = "META.a2ml"
active-adrs = ["adr-001", "adr-003"]
ecosystem-ref = "ECOSYSTEM.a2ml"
# In PLAYBOOK.a2ml - derived from META
[playbook.derivation-source]
meta-rule = "adr-015"
state-context = "current-milestone"
agentic-gate = "entropy-budget-ok"
# In AGENTIC.a2ml - gates based on META authority
[agentic.gating-policy]
authority-source = "META.a2ml"
override-path = "explicit-user-intent"
proof-requirement = "NEUROSYM.verified"All A2ML specifications follow SemVer 2.0.0:
-
MAJOR: Breaking changes to grammar or semantics
-
MINOR: New optional features, backward compatible
-
PATCH: Clarifications, examples, typos
Current versions:
| Format | Version | Status |
|---|---|---|
META.a2ml |
2.0.0-draft.1 |
Community Specification |
STATE.a2ml |
2.0.0-draft.1 |
Companion to META |
ECOSYSTEM.a2ml |
2.0.0-draft.1 |
Companion to META |
PLAYBOOK.a2ml |
2.0.0-draft.1 |
Initial Development |
AGENTIC.a2ml |
2.0.0-draft.1 |
Initial Development |
NEUROSYM.a2ml |
2.0.0-draft.1 |
Initial Development |
ANCHOR.a2ml |
2.0.0-draft.1 |
Initial Development |