AI.a2ml

# AI Assistant Instructions

# Machine-Readable Metadata

Project metadata and AI agent configuration files live under `.machine_readable/`. All metadata files use the `.a2ml` extension; the `.scm` extension is reserved for Guix (`guix.scm`, `.guix-channel`).

## Core 6a2 metadata (`.machine_readable/6a2/`)

- **STATE.a2ml** - Current project state, progress, blockers, next actions, session notes
- **ECOSYSTEM.a2ml** - Position in ecosystem, relationships to sibling projects
- **META.a2ml** - Architecture decisions, governance, development practices
- **PLAYBOOK.a2ml** - Operational runbook, procedures, alerts
- **AGENTIC.a2ml** - AI agent interaction patterns and constraints
- **NEUROSYM.a2ml** - Neurosymbolic integration configuration

## Top-level contractile files (`.machine_readable/`)

- **ADJUST.contractile**, **INTENT.contractile**, **MUST.contractile**, **TRUST.contractile** - Trident-shape commitments
- **CLADE.a2ml** - Phylogenetic context within the estate
- **anchors/ANCHOR.a2ml** - Stable references for tooling

## Agent guidance (`.machine_readable/agent_instructions/`)

- **methodology.a2ml** - Required checks (dune build / dune runtest must pass; see for the full list)
- **coverage.a2ml**, **debt.a2ml** - Tracked metrics
- **README.adoc** - Human-readable summary of agent instructions

**These files are the canonical source of truth for project metadata.**

## Workflow

1. Read `.machine_readable/6a2/*.a2ml` files at session start
2. Check `STATE.a2ml` for current phase, blockers, next actions
3. Follow patterns and constraints from `AGENTIC.a2ml`
4. Follow methodology gates from `agent_instructions/methodology.a2ml`
5. Update `STATE.a2ml` after completing work
6. Sync to database: `~/sync-language-tracker.sh`