Model-Agnostic Communication Layer

Model-Agnostic Communication Layer (MACL) is a portable way to share MSPR-D with other projects and users.

MSPR-D means:

• MSPR: Machine-readable Sparse Priming Representation.
• D: Keyword-guided human decompression.

In plain language: MACL gives agents a small, structured packet to read before work, and gives humans readable review cards only when context needs attention.

What This Repository Is

This repository is a communication protocol and adoption kit.

It provides:

• readable concepts and operating rules;
• packet types for agent priming;
• keyword maps for decompression;
• review-card and decision-brief templates;
• handover and work-envelope shapes;
• JSON schemas for validation;
• adoption manifests for host repositories;
• fetch, subtree, submodule, and vendor-copy guidance;
• small optional helper scripts.

What This Repository Is Not

MACL is not:

• a replacement for a host repo's AGENTS.md;
• a replacement for canonical documentation;
• a runtime or autonomous agent framework;
• a permission system;
• a hidden memory database;
• a RAG system;
• a deployment tool;
• a source of truth for the adopting project.

The host project always owns its truth.

Host canonical docs govern.
MACL primes, structures, validates, and explains.
MACL never silently promotes or overwrites host truth.

Why MSPR-D Exists

Agents lose context, handovers get long, and summaries often become more trusted than they should be. MSPR-D solves this by separating three things:

1. Canonical truth: the files that govern the host project.
2. Machine priming: small structured packets that help agents start with the right boundaries.
3. Human decompression: readable review cards when a keyword, risk, stale context, or decision gate needs attention.

The Core Flow

Source files
  -> journal or evidence
  -> derived synthesis
  -> MSPR packet
  -> decompression trigger
  -> human review card or decision brief
  -> optional governed promotion

Promotion is never automatic. A decompressed review card may recommend a canonical update, but it may not perform one by itself.

Quick Start For A Host Repository

1. Fetch or vendor this repository under a non-authoritative path:

vendor/model-agnostic-communication-layer/

2. Copy the adoption manifest template:

templates/adoption-manifest.template.yaml

to a host-owned path such as:

.agent/macl.adoption.yaml

3. Fill in the host canonical sources.

4. Copy one profile from profiles/.

5. Create one local prime packet from templates/project.prime.yaml.

6. Run optional checks:

node vendor/model-agnostic-communication-layer/tools/validate-adoption.mjs .agent/macl.adoption.yaml
node vendor/model-agnostic-communication-layer/tools/validate-mspr.mjs .agent/project.prime.yaml

The scripts are helper checks only. They do not prove that the host project is correct.

Repository Map

docs/       Human-readable guidance.
spec/       MSPR-D protocol details.
contracts/  JSON schemas and package metadata.
templates/  Copyable starting points.
profiles/   Adoption profiles for different host needs.
examples/   Example host integrations.
tools/      Optional local helper checks.
fetch/      Git integration recipes.

Recommended Adoption Levels

Level	Use When	Includes
Minimal	A repo only needs agent re-entry context	project prime + review card
Strict	A repo needs fail-closed boundaries	source anchors, stale policy, no-secret checks
Workspace	A multi-repo workspace needs routing help	workspace prime, project primes, handover
Repo-local	A product repo needs local agent context	local canonical sources and task packets

Safety Rules

• Do not store secrets in MSPR packets.
• Do not use MSPR as canonical truth.
• Do not promote derived knowledge without review.
• Do not overwrite host docs from MACL templates.
• Do not claim runtime, deployment, permission, or readiness state unless host files prove it.
• Stop when owner, authority, or validation is unclear.

Maintainer Rule

Keep this repository readable first. A user should understand the logic before they inspect schemas or scripts.