// SPDX-License-Identifier: CC-BY-SA-4.0
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
= A2ML Repository Template
:toc: left
:toclevels: 3
:icons: font
:sectnums:

Canonical directory structure and file requirements for all A2ML format specification repositories.

== Overview

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.

== The 7 A2ML Formats

[cols="1,2,3,2"]
|===
|Format |Repository |Purpose |Media Type

|**META.a2ml**
|hyperpolymath/meta-a2ml
|Architecture decisions, development practices
|`application/vnd.meta+a2ml`

|**STATE.a2ml**
|(defined in meta-a2ml)
|Project state, milestones, session history
|`application/vnd.state+a2ml`

|**ECOSYSTEM.a2ml**
|(defined in meta-a2ml)
|Ecosystem positioning, relationships
|`application/vnd.ecosystem+a2ml`

|**PLAYBOOK.a2ml**
|hyperpolymath/playbook-a2ml
|Executable plans, operational runbooks
|`application/vnd.playbook+a2ml`

|**AGENTIC.a2ml**
|hyperpolymath/agentic-a2ml
|AI agent operational gating, safety controls
|`application/vnd.agentic+a2ml`

|**NEUROSYM.a2ml**
|hyperpolymath/neurosym-a2ml
|Symbolic semantics, composition algebra
|`application/vnd.neurosym+a2ml`

|**ANCHOR.a2ml**
|hyperpolymath/anchor-a2ml
|Project recalibration, scope intervention
|`application/vnd.anchor+a2ml`
|===

== Directory Structure

Every A2ML specification repository MUST have:

[source]
----
{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 checks
----

== Required Files

=== README.adoc

MUST contain:

1. **Format Family Badge**: Link to A2ML Format Family
2. **License Badges**: PMPL-1.0 + Palimpsest
3. **Purpose Statement**: One-line description of this format
4. **The A2ML Format Family**: Table showing all 7 formats
5. **What is {FORMAT}.a2ml?**: Detailed explanation
6. **Why {FORMAT}.a2ml?**: Feature/benefit table
7. **Core Sections**: Document structure
8. **Getting Started**: Minimal example
9. **Specification Links**: Links to spec/ directory
10. **Examples**: Links to examples/
11. **Integration**: How it works with other A2ML formats
12. **Standards Track**: IETF/IANA roadmap
13. **Media Type**: MIME type and extension

=== spec/{FORMAT}-FORMAT-SPEC.adoc

RFC-style specification MUST contain:

1. **Abstract**: Summary of the format
2. **Status of This Memo**: Document status
3. **Copyright Notice**: License
4. **Introduction**: Purpose and design goals
5. **Terminology**: RFC 2119/8174 key words
6. **File Structure**: Grammar overview
7. **Core Sections**: Required fields and semantics
8. **Extension Sections**: How to add custom sections
9. **Parsing Requirements**: Implementation guidance
10. **Security Considerations**: Security implications
11. **IANA Considerations**: Media type registration
12. **References**: Normative and informative

=== examples/minimal.a2ml

Minimal valid file demonstrating required structure:

[source,toml]
----
# 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
----

== Relationship Hierarchy

[source]
----
                    ┌─────────────────────────────────────┐
                    │      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)
----

=== Execution Pipeline Order

All implementations MUST respect this order:

1. **META** validation (constitutional authority)
2. **AGENTIC** gating (operational safety)
3. **NEUROSYM** semantics (proof obligations)
4. **PLAYBOOK** derivation (executable plan)
5. **Execution**
6. **ECOSYSTEM** integrity check
7. **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.

== Satellite Registration

All A2ML specification repos MUST be registered in `hyperpolymath/standards/SATELLITES.a2ml`:

[source,toml]
----
[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"
----

== Inter-Repository Connections

=== How Formats Reference Each Other

[source,toml]
----
# 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"
----

== Versioning

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
|===

== License

All A2ML specification repositories use:

* **License**: PMPL-1.0-or-later
* **Philosophy**: Palimpsest License overlay

SPDX headers REQUIRED on all source files.

