Agent Integration Guide

The ADR Ledger is designed to be the foundational knowledge layer for an ecosystem of autonomous agents. This guide explains how agents interact with the ledger and consume its artifacts.

Overview

The ledger transforms human-readable Markdown ADRs into machine-optimized JSON artifacts. Agents are "ledger-agnostic" in their internal logic but depend on these artifacts for up-to-date architectural context.

The Sync Process

When adr sync is executed (manually or via post-commit hook), the following happens:

  1. Parsing: The Python AST parser (.parsers/adr_parser.py) reads all accepted ADRs.
  2. Validation: Artifacts are validated against .schema/adr.schema.json.
  3. Generation: Five primary artifacts are generated in the knowledge/ directory:
    • knowledge_base.json: Flattened list of all decisions.
    • spectre_corpus.json: Text-heavy corpus for NLP patterns.
    • phantom_training.json: ML features and classification data.
    • graph.json: Adjacency list representing decision relationships.
    • knowledge_base.jsonl: Streaming-optimized lines for large-scale ingestion.

Agent Specifics

CEREBRO (RAG)

  • Artifact: knowledge/knowledge_base.json
  • Mechanism: CEREBRO monitors this file for changes. Upon update, it re-indexes modified ADRs into its vector store (e.g., pgvector) using embeddings.
  • Goal: Provide natural language answers to architectural queries with direct citations.

SPECTRE (NLP)

  • Artifact: knowledge/spectre_corpus.json
  • Mechanism: Periodically scans the corpus for "sentiment drift" or "pattern violations."
  • Goal: Identify tech debt or "forced decisions" by analyzing the tone and keywords of ADRs.

PHANTOM (Security/ML)

  • Artifact: knowledge/phantom_training.json
  • Mechanism: Uses the feature set to classify new PRs or ADRs.
  • Goal: Ensure no sensitive data (PII/Secrets) leaks into the public ledger.

NEUTRON (Infrastructure)

  • Artifact: knowledge/knowledge_base.json (via Nix)
  • Mechanism: Imports the ledger as a flake input. Uses lib functions to extract compliance tags.
  • Goal: Enforce decisions (e.g., "All DBs must use TLS") at the NixOS configuration level.

Developing New Agents

To build a new agent that consumes the ledger: 1. Use a Ledger Subscriber (see crates/ledger-subscriber) to receive notifications of sync events. 2. Parse the relevant JSON artifact from the knowledge/ directory. 3. Map the id, status, and knowledge_extraction fields to your internal model.

For implementation details, see scripts/adr sync.