Name: Agent Artifact Protocol (AAP)
Kind: filesystem convention + JSON Schema
Version: 0.3.0 (experimental, pre-1.0)
AAP makes repository context addressable without requiring it to be loaded. It is a small, runtime-agnostic navigation convention for repositories and optional durable artifacts. It is not a context engine, agent framework, retrieval protocol, dependency graph, or authorization system.
An agent starts with one small .aap/map.yaml, then opens only the repository, path, or artifact relevant to the task. Linked maps are explicit hops and MUST NOT be recursively preloaded.
version: 2
workspace: { id: my-repository }
self: { id: my-repository, kind: repository, path: . }
layout: { code: src/, artifacts: docs/artifacts/ }
nodes: []workspaceidentifies the opened workspace.selfdescribes its repository.self.parent, when present, is one bounded navigation/container pointer; it does not imply ownership, authorization, dependency, inherited policy, or recursive traversal.nodesare direct navigational hops to related repositories or products, not a dependency graph.locatoridentifies a node independently of a local checkout;mappoints at its map when deeper inspection is needed.layoutmaps vocabulary keys to directory roots in the current workspace (see below).overlaysis optional machine-local checkout GPS (see Overlays).profilesis an optional free-form enable list (see Profiles block).
The normative schema is schemas/map.schema.json. Consumers pin a release tag or commit; ordinary sessions read the local map rather than fetching upstream.
Every layout value is a resourceRef, either a backward-compatible path string or an object:
layout:
artifacts:
- path: docs/features/
access: read-write
- path: legacy/features/
access: read-only
description: Historical corpus; keep discoverable for reading.- A string normalizes to
{ path: <string>, access: read-write }. - Object
accessdefaults toread-writewhen absent. - Paths are workspace-relative and MUST NOT be absolute or traverse through
... accessisread-onlyorread-write. It is an agent coordination fence, not OS/Git/IAM authorization.- A durable write home for a layout key is the first reference whose normalized access is not
read-only. - If no writable reference exists, an agent MUST fail closed for a durable write and ask; it MUST NOT invent a parallel root.
write on a node is an optional, deployment-defined role hint. It is separate from path access and does not grant filesystem permission. Git permissions, CODEOWNERS, protected branches, and sandboxes enforce real boundaries.
Core documents common keys (code, tests, artifacts, scratch, plus seed examples such as scripts, infra, devops). The schema allows additional layout keys; each value remains a resourceRef (or list of them).
Extension keys:
- MAY name local placement roots (
surfaces,verify, …) when a team needs them. - SHOULD stay sparse and path-shaped — not procedure essays or tool catalogs.
- MUST NOT be required for Orientation conformance in other repositories.
- Do not treat an extension key as a natural-language intent router.
Repository validators MAY constrain which extension keys are allowed locally; Core does not.
overlays (on the map) and the preferred gitignored sibling map.local.yaml supply machine-local navigation GPS only.
# Prefer gitignored map.local.yaml so absolute checkouts never fork the shared map.
overlays:
nodes:
orders-api: { path: /Users/you/src/orders-api }
# local_paths: alternate GPS shape allowed by schemaRules:
- Overlays resolve where a node is checked out on this machine.
- Overlays never grant write authority and MUST NOT override
access/ write-home selection. - Committed maps SHOULD avoid absolute paths; put GPS in a gitignored local file.
- Consumers MAY extend a local file with non-schema profile indexes (stream catalogs, orientation pointers). Those keys are not part of Map v2 Core validation — see cookbook
local-bootstrap.md.
The schema allows an optional top-level profiles object:
profiles:
enabled:
- brownfield-artifacts
- feature-surface # free-form local name — not a Core registryprofiles.enabledis a list of strings. Core does not define a closed registry of names.- Enabled entries are hints for humans and local tooling; they do not change map validity by themselves.
- Named behaviors (brownfield artifacts, stream packs, done-bar, …) live in SPEC prose or the cookbook as optional profiles.
- Enabling a profile MUST NOT expand Core L0: agents still start from the map unless a consumer runtime chooses a stricter bootstrap.
brownfield-artifacts is an optional profile for repositories with a legacy documentation corpus:
- Declare at most one writable
layout.artifactshome. - Keep old roots addressable as
read-onlyrather than removing history or bulk-moving it. - On a material update, create or update the canonical successor in the write home and retain a compatibility pointer in the legacy record.
- Typos or urgent factual corrections may be fixed in place without making the old root a home for new durable documents.
This profile does not reserve path names or mandate a migration date.
These files MAY exist beside a map. They are not required for map validity or Orientation conformance:
| File | Role |
|---|---|
map.local.yaml (often gitignored) |
Machine GPS (overlays) and optional profile index |
Thin orientation card (e.g. .aap/local/orientation.md) |
Short workspace card after the map |
Stream packs (e.g. .aap/local/streams/*.yaml) |
One task-class procedure pack per session |
Accept bar (e.g. _accept-default.yaml) |
Honesty checks before “done” / PR-ready |
Runtime dispatcher (AGENTS.md / local equivalent) |
Harness-injected thin bootstrap — runtime policy |
Documented shapes: cookbook/local-bootstrap.md, cookbook/stream-packs.md.
MUST NOT treat these as a mandatory preload corpus for Core.
Artifacts remain optional Markdown (or profile-defined) durable units. The existing v0.1 artifact envelope is retained as a separate historical draft; map v2 does not automatically redefine artifact placement metadata. A future artifact-envelope revision may generalize its zone field based on usage evidence.
| Level | Read | When |
|---|---|---|
| L0 | map only | workspace orientation |
| L1 | targeted path/index | after choosing a layout key or node |
| L2 | one artifact | durable memory is needed |
| L3 | code and normal tools | implementation evidence |
Maps should stay sparse. Essays, whole corpora, graph indexes, embeddings, adapters, and workflow machinery do not belong in the mandatory L0 read.
Core levels are only L0–L3. Additional labels used by a deployment (orientation cards, stream packs, capability files) are profile elaborations of the same law — they do not rename or replace Core levels.
Map v2 is a breaking replacement for the historical v1 zones dialect. A v1 map is not auto-converted and MUST be deliberately migrated. Keep a tagged v0.1.1-draft checkout for historical validation. Additive v2 changes preserve existing string-layout maps; a breaking rename/removal requires a map version bump, migration note, and changelog entry.
pip install pyyaml jsonschema
python scripts/validate.pyThe validator checks schemas, v2 examples, resource-reference path safety, and invalid fixtures. Repository-specific policies—such as requiring external nodes to be read-only—belong in that repository's own validator or profile.
| Label | Means |
|---|---|
| Orientation | A discoverable sparse map; layout-based discovery is possible. Requires only the L0 read. |
| Artifact | The envelope field set, claimed only when artifacts are addressable. |
| Topology | Nodes are direct hops, and listed paths are meant to resolve in the checkout. |
| Disclosure profile (optional) | Streams, accept bars or thin orientation cards. Not required for Orientation. |
AAP is a convention with schemas, not a complete cross-file protocol suite.