Adapter Taxonomy

Goal

This document defines a first concrete taxonomy for AletheIA adapters.

In simple terms:

if Alpha 6 is going to deliver the same framework meaning across different environments, it needs a clearer idea of what kinds of adapter should exist before delivery tooling becomes heavier.

Why this matters

AletheIA is already becoming more reusable as a framework.

But reuse does not only depend on project shape. It also depends on delivery surface.

A team may read the same framework through:

repo-native docs
AGENTS-style files
editor-specific instruction surfaces
handoff packages between agents
future bootstrap or installation flows

Without a clearer adapter model, those delivery surfaces can drift and quietly redefine the framework.

The point of an adapter taxonomy is to prevent that drift.

Core idea

An adapter should be understood as:

an environment-specific delivery mapping that preserves AletheIA’s meaning

An adapter is not a new preset. It is not a new policy pack. It is not a fork of the framework.

An adapter should answer questions such as:

how should the framework be presented in this environment?
what must stay semantically identical across environments?
what can be reformatted without changing meaning?
what should remain human-readable versus agent-facing?

The adapter should change the delivery form. It should not change the framework truth.

AletheIA distinguishes between an Execution Surface and an Adapter.

the execution surface is where the framework is delivered, read, or operated
the adapter is the environment-specific mapping that preserves framework meaning across that surface

For canonical terminology, see:

docs/canonical-vocabulary.md

Three adapter layers

AletheIA adapters should eventually vary along three axes:

1. Surface type

Where is the framework being delivered?

Examples:

repo-native documentation
agent instruction file
editor-specific context surface
handoff artifact
future bootstrap output

2. Delivery audience

Who is the immediate reader or receiver?

Examples:

human contributor
coding agent
reviewing agent
mixed human-plus-agent workflow

3. Compression level

How condensed should the delivery be?

Examples:

full narrative surface
operational summary
restart package
installation-oriented mapping

This doc focuses mainly on the first axis: surface type.

First adapter families

1. Repo-Native adapter

Use when the main goal is:

reading AletheIA in its canonical public form
understanding the full narrative and roadmap
preserving the framework in its most inspectable state

This adapter should emphasize:

README reading order
docs as the primary source of meaning
starter-pack references in native repo structure
explicit distinction between current baseline and future direction

This remains the closest thing to the canonical public surface.

2. Agent Instruction adapter

Use when the main goal is:

delivering AletheIA into an instruction-oriented agent surface
compressing guidance into an operational format that an agent can consume quickly
preserving rules, boundaries, and priorities without full narrative overhead

This adapter should emphasize: