Get Started

Install pandoc-a2ml

Clone the pandoc-a2ml repository and note the path to the Lua scripts. No compilation needed — the reader, writer, and filter are pure Lua.

git clone https://github.com/hyperpolymath/pandoc-a2ml.git
cd pandoc-a2ml

The key files are:

• a2ml-reader.lua — reads .a2ml files into Pandoc's AST
• a2ml-writer.lua — writes Pandoc AST as .a2ml output
• a2ml-filter.lua — Lua filter for attestation processing

You can either add these to your Pandoc data directory (~/.local/share/pandoc/) or reference them by path.

Install the VS Code Extension

For syntax highlighting while editing .a2ml files:

1. Open VS Code 2. Go to Extensions (Ctrl+Shift+X) 3. Search for "A2ML" 4. Click Install

Alternatively, clone and install manually:

git clone https://github.com/hyperpolymath/vscode-a2ml.git
cd vscode-a2ml
code --install-extension .

You should now see syntax highlighting for .a2ml files, including directive blocks, headings, and comments.

Create Your First Manifest

Create a file called 0-AI-MANIFEST.a2ml in your repository root. This is the entry point that AI agents and tooling will read first.

;; SPDX-License-Identifier: PMPL-1.0-or-later

# AI Manifest — my-project

@abstract:
This repository contains my-project, a tool for doing useful things.
This manifest declares the AI agents that operate on this repository
and the policies that govern their behaviour.
@end

@provenance:
created-by: Your Name
created: 2026-03-16
source: https://github.com/your-org/my-project
version: 1.0.0
@end

## Repository Structure

- Source code in `src/`
- Machine-readable metadata in `.machine_readable/`
- CI/CD workflows in `.github/workflows/`

## Agents

No AI agents currently operate on this repository.

@refs:
[1] A2ML Specification, https://a2ml.hyperpolymath.dev/specification.html
@end

Validate with Pandoc

Check that your manifest parses correctly by converting it to HTML:

pandoc -f path/to/a2ml-reader.lua 0-AI-MANIFEST.a2ml -o manifest.html

If the file is well-formed, Pandoc will produce clean HTML output. Open manifest.html in a browser to verify the structure.

For deeper validation using the A2ML filter (checks attestation structure):

pandoc -f path/to/a2ml-reader.lua \
       --lua-filter path/to/a2ml-filter.lua \
       0-AI-MANIFEST.a2ml \
       -o validated.html

Add Machine-Readable Metadata

For full Rhodium Standard compliance, create the .machine_readable/ directory and add A2ML metadata files:

mkdir -p .machine_readable/anchors .machine_readable/policies

Create .machine_readable/STATE.a2ml:

;; SPDX-License-Identifier: PMPL-1.0-or-later

# Project State

@abstract:
Current state of my-project development.
@end

## Status

- Phase: initial setup
- Completion: 10%
- Next milestone: core functionality

## Blockers

None currently.

Create .machine_readable/META.a2ml:

;; SPDX-License-Identifier: PMPL-1.0-or-later

# Project Metadata

@abstract:
Architecture decisions and governance for my-project.
@end

## Architecture Decisions

- Language: chosen based on team expertise
- License: PMPL-1.0-or-later for original code

These files give AI agents and automated tooling a structured understanding of your project's state, architecture, and ecosystem position.

Add an Agent Attestation

When you introduce an AI agent to your workflow (a CI bot, a code reviewer, a security scanner), declare it in the manifest:

;; Add this to 0-AI-MANIFEST.a2ml or a dedicated agent file

@attestation:
agent-id: my-ci-bot
attested-by: my-ci-bot
trust-level: self-declared
timestamp: 2026-03-16T12:00:00Z
capabilities:
  - lint-checking
  - test-execution
scope: repository
@end

As the agent is reviewed and verified, add higher-trust attestations:

@attestation:
agent-id: my-ci-bot
attested-by: security-team
trust-level: verified
timestamp: 2026-03-20T15:00:00Z
verifies: my-ci-bot/self-declared/2026-03-16
signature: sha256:your-signature-here
@end