diff --git a/README.md b/README.md index 84d7a4d..b2e0e5b 100644 --- a/README.md +++ b/README.md @@ -1,216 +1,287 @@ # Agent Artifact Protocol (AAP) **Version:** 0.2.1-prototype -**Status:** experimental Map v2 Core + dogfood-informed **optional** profiles (working-prototype **docs**) +**Status:** experimental prototype (docs + schema + validator) **License:** MIT -**Git tag form:** `v0.2.1-prototype` (documents omit the `v` prefix) +**Git tag:** [`v0.2.1-prototype`](https://github.com/gitpash/agent-artifact-protocol/releases/tag/v0.2.1-prototype) +(Documents omit the `v` prefix: `0.2.1-prototype`.) > **AAP makes repository context addressable without requiring repository context to be loaded.** -> **Map v2** (`0.2.0-draft` lineage) replaced the historical v1 `zones` map with a repository-oriented `workspace` / `self` / `nodes` map. **`0.2.1-prototype`** is a **docs/cookbook** label on that same Core — optional profiles and examples, **not** a claim that Core is a finished interop standard. v1 material remains under `legacy/v1/`. +AAP is a **runtime-agnostic filesystem convention**: a tiny map in the repo so agents (and humans) can **find the right place** without dumping the whole project into the prompt. -AAP is a **runtime-agnostic filesystem convention** for: +| AAP is | AAP is not | +|--------|------------| +| Sparse **map** + progressive disclosure | Context engine / RAG | +| Optional **profiles** in the cookbook | Agent harness or multi-agent runtime | +| Path **`access`** fences + optional node **`write`** role hints (coordination only) | Security sandbox or ACL | +| Pinned templates you copy once | Something fetched every agent turn | -1. **Repository orientation** — a tiny map using **layout categories** → directory root -2. **Optional durable memory** — typed Markdown (or profile-defined) artifacts with a small envelope +**AAP does not replace `AGENTS.md` / `CLAUDE.md`:** those say *how to work*; the map says *where things are*. They can live side by side. -It is **not** a context engine, RAG stack, agent harness, security sandbox, or mandatory preload pack. +--- -In v0.2, a layout key is a **small vocabulary key** such as `code`, `tests`, `artifacts`, or `scratch` — **not** a natural-language task classifier. AAP does not understand phrases like “modernize the API” by itself; the agent (or human) picks a layout key and looks under that root. +## What problem is this for? + +Coding agents often fail on **orientation** and **context pollution**, not on “missing a wiki page.” + +| Failure | What happens | Addressed by | +|---------|----------------|--------------| +| Wrong home | Edits land in the wrong package or “docs that look related” | **Core** (layout) | +| Preload bloat | Session opens constitutions, catalogs, every submodule map | **Core** (L0→L3) | +| No GPS | Multi-repo: path ≠ GitHub name; no clear hop | **Core** (nodes) | +| Fake confidence | “PR ready” with red CI / invented blockers | ***Profile*** ([done-bar](./cookbook/done-bar.md)) | + +**AAP’s bet** (thesis, not a measured claim here): a sparse map + disclosure beats a bigger prompt. See [`MOTIVATION.md`](./MOTIVATION.md); validate with a local A/B (below) before you expand. + +```mermaid +flowchart LR + subgraph before [Without a map] + A[Agent starts] --> B["Read AGENTS.md / wiki,
grep around"] + B --> C[Guess locus] + C --> D[Wrong home or wasted turns] + end + + subgraph after [With AAP] + E[Agent starts] --> F[Read local map only] + F --> G[Pick layout key or node] + G --> H[Open one path / one pack] + H --> I[Code + normal tools] + end +``` -Philosophy (aligned with formats like [Memoryfield](https://github.com/calpaterson/memoryfield-spec)): +--- -- conventions over infrastructure -- discovery over preloading -- progressive disclosure over context dumping -- files over runtime dependencies +## How it works (Core) ---- +### 1. One small map in *your* repo + +Prefer `.aap/map.yaml` (also `map.yaml` or `docs/map.yaml`). -## Progressive disclosure +```yaml +version: 2 +workspace: + id: my-app + description: What this checkout is +self: + id: my-app + kind: repository + path: . + # parent: # optional — see vocabulary + # id: my-hub + # path: ../.. # navigation only +layout: + code: src/ # string ≡ { path: src/, access: read-write } + tests: tests/ + artifacts: + - path: docs/artifacts/ + access: read-write # same resourceRef shape; list allowed + scratch: docs/scratch/ +nodes: + - id: orders-api + kind: repository + path: services/orders + # access: read-only # optional path fence on the hop + # write: [domain] # optional role hints — not an ACL +``` + +| Piece | Role | +|-------|------| +| **workspace / self** | What you opened | +| **self.parent** | Optional **one** navigation/container pointer (no ownership, auth, or recursive preload) | +| **layout** | Keys (`code`, `tests`, `artifacts`, `scratch`, …) → one or more **resourceRef**s | +| **nodes** | Direct **navigation hops** — not a dependency graph | +| **resourceRef** | Path string **or** `{ path, access?, description? }` | +| **`access`** | On a resourceRef or node hop: `read-only` \| `read-write` (default `read-write`). **Path coordination fence**, not OS/Git/IAM. When a layout key lists several refs, the durable place to write is the **first** whose `access` is not `read-only` (write-home — full rule in [SPEC](./SPEC.md)). | +| **`write`** | On a **node** only: optional string list of deployment-defined **role hints** (e.g. `domain`). Separate from `access`; does **not** grant filesystem permission ([SPEC](./SPEC.md)). | + +Layout keys are **not** a natural-language task classifier. The human/agent chooses the task; AAP only says where `code` / `tests` live. + +### 2. Progressive disclosure + +```mermaid +flowchart TD + L0["L0 — Map only
(Orientation conformance)"] + L1["L1 — One layout path or node hop"] + L2["L2 — One durable artifact"] + L3["L3 — Code + grep / LSP / indexes
(outside AAP)"] + P["Optional profile
orientation + one stream pack"] + + L0 --> L1 + L1 --> L3 + L1 -.->|only if durable memory is needed| L2 + L2 -.-> L3 + L0 -.->|optional profile| P +``` | Level | What | When | |-------|------|------| -| **L0** | Map only | Session / workspace start (**Orientation conformance**) | -| **L1** | Targeted path or layout index | After choosing a layout key or node | -| **L2** | One artifact | When durable memory is needed | -| **L3** | Code + normal tools (`grep` / LSP / indexes) | Implementation — outside AAP | +| **L0** | Map only | Session start (**Orientation**) | +| **L1** | One path or node hop | After choosing a key or node | +| **L2** | One artifact | **Only if** durable memory is needed | +| **L3** | Normal engineering tools | Implementation | -**Optional profile bootstrap (not Core L0):** some deployments also open a thin orientation card and **exactly one** task-class stream pack after the map. That is **consumer/runtime policy**. It does **not** redefine L0 and **MUST NOT** become “read the whole cookbook every session.” +**MUST NOT:** force-load this upstream repo, the full SPEC, or an artifact corpus just to begin work. -**MUST NOT:** force agents to load this whole repository, the full SPEC, or an artifact corpus into the model context to begin work. +Full rules: [`SPEC.md`](./SPEC.md). --- ## 60-second start (brownfield) -1. Copy [`templates/minimal-map.yaml`](./templates/minimal-map.yaml) to **one** of: - - `.aap/map.yaml` (preferred) - - `map.yaml` - - `docs/map.yaml` -2. Edit `self`, direct `nodes`, and `layout` paths to match **your** repository (keep it sparse). -3. Tell the agent: *read the map first; do not preload AAP upstream docs.* -4. Compare on a real task: **no map** vs **map only**. -5. **Optional profiles** (after the map-only experiment helps): multi-repo shell → [`cookbook/hub-umbrella.md`](./cookbook/hub-umbrella.md); session procedure → [`cookbook/stream-packs.md`](./cookbook/stream-packs.md) + [`cookbook/local-bootstrap.md`](./cookbook/local-bootstrap.md); honesty exit → [`cookbook/done-bar.md`](./cookbook/done-bar.md). Stubs: [`templates/orientation.md`](./templates/orientation.md), [`templates/stream-pack.yaml`](./templates/stream-pack.yaml). +1. Copy [`templates/minimal-map.yaml`](./templates/minimal-map.yaml) → `.aap/map.yaml` (see pin snippet below). +2. Edit `self`, `layout`, and `nodes` for **your** tree (keep it sparse). +3. Tell the agent: *read the local map first; do not preload AAP upstream docs.* +4. A/B a real task — **A: no map**, **B: map only**. If **B** does not help → **shrink the map**, do not add profiles. +5. Only then optional profiles (hub / one stream pack / done-bar). -For editor/CI validation, pin this repository by immutable tag or commit (see [`cookbook/schema-pinning.md`](./cookbook/schema-pinning.md)). `schemas/map.schema.json` is the current v2 contract; do not validate against a floating branch tip. Validation is never required for L0 orientation. +**Pin** = which tag your copied templates came from. Nothing is fetched at agent runtime. Keep the pin visible in the map file: ```bash -# conceptual pin (no runtime fetch during normal agent sessions) -# git clone --depth 1 --branch v0.2.1-prototype \ -# https://github.com/gitpash/agent-artifact-protocol.git /tmp/aap -# mkdir -p .aap && cp /tmp/aap/templates/minimal-map.yaml .aap/map.yaml +git clone --depth 1 --branch v0.2.1-prototype \ + https://github.com/gitpash/agent-artifact-protocol.git /tmp/aap +mkdir -p .aap +{ + echo "# aap-pin: v0.2.1-prototype" + echo "# source: https://github.com/gitpash/agent-artifact-protocol" + cat /tmp/aap/templates/minimal-map.yaml +} > .aap/map.yaml +# edit .aap/map.yaml — work from YOUR repo, not /tmp/aap ``` -Init tooling, if added later, MUST be **explicit**, **additive**, **dry-run capable**, and **human-reviewed**. It MUST NOT rewrite `CLAUDE.md` / `.specify/` / existing docs homes by default. **If a target file already exists, init MUST stop or require explicit per-file confirmation** — never silent overwrite. +YAML `#` comments do not affect schema validation. More detail: [`cookbook/schema-pinning.md`](./cookbook/schema-pinning.md), [`cookbook/brownfield-init.md`](./cookbook/brownfield-init.md). --- -## Repository layout (this seed) - -```text -README.md -SPEC.md # Map v2 Core (on demand — not L0) -MOTIVATION.md -CONTRIBUTING.md -LICENSE -CHANGELOG.md -schemas/ # current Map v2 schema -legacy/v1/ # historical v1 zones schema and examples -templates/ - minimal-map.yaml - orientation.md # optional thin card stub - stream-pack.yaml # optional pack stub - artifact-*.md -examples/ - single-repo/ shell/ hub-umbrella/ resource-ref/ - stream-packs/ # optional profile samples (not Core maps) - invalid/ # schema fixtures + disclosure anti-pattern notes -cookbook/ - brownfield-init.md - hub-umbrella.md - stream-packs.md - local-bootstrap.md - done-bar.md - schema-pinning.md - glass-box-factory.md # pattern only — no CLI in this repo - orchestrator-session.md # harness-agnostic manager/worker shape - what-not-to-copy.md -scripts/validate.py -.github/workflows/validate.yml +## Multi-repo: hop, don’t preload + +```mermaid +flowchart TB + H["Hub map
workspace + nodes"] + H --> N1["node: orders-api
path: services/orders"] + H --> N2["node: admin-web
path: apps/admin"] + N1 --> C1["Child map optional"] + N2 --> C2["Child map optional"] + C1 -.->|self.parent| H + C2 -.->|self.parent| H ``` -**Not in this seed (on purpose):** product adoption guides, pilot metrics dashboards, partner-repo contracts, agent runtime adapters, factory/conductor CLI, mandatory multi-agent harnesses. +Nodes are **doors**, not “load every submodule into context.” +[`cookbook/hub-umbrella.md`](./cookbook/hub-umbrella.md) · [`examples/hub-umbrella/`](./examples/hub-umbrella/). --- -## Core vs profile +## Optional profiles (not Core L0) -| Layer | In tree | Required for Orientation? | -|-------|---------|---------------------------| -| Map v2 (`workspace` / `self` / `nodes` / `layout`) | Yes | **Yes** | -| Progressive disclosure law (L0 map → … → L3 tools) | Yes | **Yes** (behavior) | -| Artifact envelope (historical draft) | Yes | Only if claiming Artifact addressability | -| `brownfield-artifacts` profile | SPEC prose | **No** | -| Stream packs / accept bars / orientation cards | Cookbook + examples + templates | **No** (Profile) | -| Thin runtime dispatcher (`AGENTS.md` / local bootstrap) | Cookbook only | **No** (Profile) | -| Multi-repo hub-umbrella teaching pattern | Cookbook + examples | **No** (pattern on Core maps) | -| Done bar / schema-pinning ops notes | Cookbook | **No** (Profile / ops) | -| Orchestrator session / glass-box factory **patterns** | Cookbook only (no CLI shipped) | **No** | -| Multi-agent “teams” runtimes | Out of tree | **No** (one possible impl of orchestrator shape) | - -**Core** stays small: sparse maps + disclosure law + optional artifact envelope. -**Profiles** are optional elaborations documented in the cookbook. They **MUST NOT** be treated as a mandatory first-read corpus. +After map-only helps, you **may** add local procedure files (often gitignored): ---- - -## Core ideas (short) - -| Term | Meaning | -|------|---------| -| **Map** | Sparse description of the opened workspace, its layout, and direct navigation nodes | -| **Node** | Direct navigational hop to a related repository/product; not a dependency declaration | -| **Layout key** | `code`, `tests`, `artifacts`, `scratch`, … → resource reference(s); extensions allowed | -| **resourceRef** | A relative path string or `{ path, access?, description? }`; default access is `read-write` | -| **Artifact** | Optional durable note; the historical v1 envelope remains separately versioned | -| **Write / access** | Advisory coordination metadata, never access control | -| **Profile** | Optional named elaboration (streams, accept bar, brownfield-artifacts, …) — not Core L0 | +```mermaid +flowchart LR + M["Map (L0)"] --> O["orientation.md
thin card"] + O --> S["One stream pack
research / feature / …"] + S --> W[Work] + W --> D["Done-bar
at exit"] +``` -### `write` is not security +| Profile | Cookbook | +|---------|----------| +| Stream packs (one task class per session) | [`stream-packs.md`](./cookbook/stream-packs.md) | +| Thin orientation + local index | [`local-bootstrap.md`](./cookbook/local-bootstrap.md) | +| Accept / done bar | [`done-bar.md`](./cookbook/done-bar.md) | +| Schema pin (no tip fetch) | [`schema-pinning.md`](./cookbook/schema-pinning.md) | +| Manager/worker session shape | [`orchestrator-session.md`](./cookbook/orchestrator-session.md) | +| Glass-box factory *pattern* (no CLI in this repo) | [`glass-box-factory.md`](./cookbook/glass-box-factory.md) | -```yaml -# Coordination hint only — NOT access control / sandboxing. -write: [maintainer] -``` +Stubs: [`templates/orientation.md`](./templates/orientation.md), [`templates/stream-pack.yaml`](./templates/stream-pack.yaml). -AAP **cannot** prevent a human or agent from writing outside these paths. Real enforcement requires Git permissions, CODEOWNERS, host policy, or a runtime sandbox. +--- -If no active mutating mode is **explicitly** provided by the user/runtime, the default is **no write grant** (read/orient only). +## Core vs profile -Core artifact `type` values: `capability` | `decision` | `contract` | `gotcha` | `impact` -Recommended stable ids use a namespace-like form such as `//`. Id uniqueness across a corpus is a tooling concern, not distributed allocation provided by Core. -Extension types SHOULD use dots (`diagram.sequence`). The Core JSON Schema validates **envelope shape**; it does not fully police extension namespaces (repository validators MAY). +```mermaid +flowchart TB + subgraph core ["CORE — required for Orientation"] + C1["Map v2: workspace / self / nodes / layout"] + C2["Disclosure law L0 → L3"] + end + + subgraph cond ["CONDITIONAL — only if you claim it"] + C3["Artifact envelope
(Artifact addressability)"] + end + + subgraph prof ["PROFILES — optional, never promoted into L0"] + P1["Stream packs · orientation · done-bar"] + P2["Hub-umbrella teaching · schema-pinning"] + P3["Orchestrator / glass-box patterns"] + end + + C2 ~~~ C3 + C3 ~~~ P1 +``` -External / cross-repo nodes are schema-compatible direct navigation hops; their write policy is deployment-specific. +| Also | | +|------|--| +| **Thin dispatcher** (`AGENTS.md`-style bootstrap) | Profile / runtime policy — not Core MUST | +| **Multi-agent “teams”** | One possible impl of orchestrator shape — not required | +| **Default session posture** | **Runtime recommendation, not a Core MUST:** until the user/runtime **explicitly** enables writes, prefer **read/orient only**. AAP cannot enforce this; sandboxes and Git permissions do. See [SPEC](./SPEC.md). | -Full rules: [`SPEC.md`](./SPEC.md). +Field definitions for **`access`** / **`write`**: [How it works §1](#1-one-small-map-in-your-repo). --- -## Conformance (lightweight) - -| Label | Means | -|-------|--------| -| **Orientation** | A discoverable sparse map exists; agents may use layout-based discovery | -| **Artifact** | Durable notes use the envelope field set when claiming AAP addressability | -| **Topology** | A workspace map lists honest direct navigation nodes and paths | -| **Disclosure profile** *(optional)* | Consumer adds stream packs / accept bars / thin orientation — **not** required for Orientation | +## Vocabulary and conformance -This draft is a **convention + schemas**, not a complete cross-file protocol suite. Schema does not yet prove zone membership of every path, unique ids across a corpus, etc. +| Term | Meaning | +|------|---------| +| **Map** | Sparse description of the opened workspace | +| **Node** | Direct hop to a related repo/product | +| **self.parent** | Optional single navigation/container pointer ([SPEC](./SPEC.md)) | +| **Layout key** | `code`, `tests`, `artifacts`, `scratch`, … → resourceRef(s) | +| **resourceRef**, **`access`**, **`write`** | See [How it works §1](#1-one-small-map-in-your-repo) (canonical) | +| **Artifact** | Optional durable note (envelope when claiming addressability) | +| **Profile** | Optional cookbook elaboration — never mandatory L0 | + +| Conformance label | Means | +|-------------------|--------| +| **Orientation** | Discoverable sparse map; layout-based discovery possible | +| **Artifact** | Envelope field set when claiming addressability | +| **Topology** | Nodes are direct hops; listed paths are meant to resolve in the checkout | +| **Disclosure profile** *(optional)* | Streams / accept / thin orientation — not required for Orientation | ```bash pip install pyyaml jsonschema python scripts/validate.py ``` ---- - -## Relationship to consumer repos - -| This repo (upstream) | Your product repo | -|----------------------|-------------------| -| Spec + templates + examples | **Pinned** copy or reference by tag | -| Evolves via semver / tags | Local `map.yaml` + local artifacts | -| Not fetched on every agent turn | L0 = local map only | -| Cookbook profiles | Opt-in local files (often gitignored) | - -Pin by **tag or commit**. Do not treat `main` as a live runtime dependency. +This is a **convention + schemas**, not a complete cross-file protocol suite. --- -## Experiment before you expand +## What’s in this repository ```text -A) agent without map -B) agent with map only (no SPEC dump) +README.md SPEC.md MOTIVATION.md CONTRIBUTING.md CHANGELOG.md +schemas/ # Map v2 JSON Schema +legacy/v1/ # historical zones map +templates/ # minimal-map, orientation, stream-pack, artifacts +examples/ # single-repo, shell, hub-umbrella, stream-packs, invalid +cookbook/ # optional profiles + patterns +scripts/validate.py ``` -If B does not improve time-to-locus / wrong-home rate, **shrink** the map — do not add schemas and profiles first. - -Only after B helps, try optional profiles (one stream pack, hub umbrella, accept bar). +**Intentionally absent:** product adoption guides, pilot dashboards, runtime adapters, factory/conductor CLI, mandatory multi-agent harnesses. +See [`cookbook/what-not-to-copy.md`](./cookbook/what-not-to-copy.md). For init-tooling rules if you build any, see [`CONTRIBUTING.md`](./CONTRIBUTING.md). --- ## Status -`0.2.1-prototype` — experimental Map v2 Core **plus** a dogfood-informed **cookbook prototype** (hub umbrella, stream packs, local bootstrap, done-bar, schema pinning, session patterns). Useful in multi-repo pilots. **Not** production infrastructure or a finished interoperability standard. Optional profiles do **not** promote Core to stable; pin with git tag `v0.2.1-prototype` (or commit SHA). +**`0.2.1-prototype`** = experimental Map v2 Core (schema + validator) **plus** a dogfood-informed cookbook. Aimed at multi-repo pilots; **not** production infrastructure or a finished interoperability standard. Profiles do not make Core stable. + +Map v2 rules come from the `0.2.0-draft` lineage; this tag adds prototype **docs** on that Core. **Schema unchanged** relative to that lineage; optional fields such as `self.parent`, `access`, and node `write` already exist in Map v2 (they are not newly required). v1: `legacy/v1/`. -Feedback is especially welcome on: +Upstream is pinned by **tag/commit** into your repo; L0 stays the **local** map only (see 60-second start). Tag `v0.2.1-prototype` includes `templates/minimal-map.yaml`. -- map size and usefulness in brownfield repos -- whether layout keys are the right granularity -- interoperability across agent runtimes without preload -- whether Core is still too large -- whether optional profiles stay clearly optional in practice +Feedback: map size, layout-key granularity, cross-runtime use without preload, whether Core is still too large, whether profiles stay optional in practice. -See [`CONTRIBUTING.md`](./CONTRIBUTING.md). Issues and PRs welcome; prefer proposals that keep L0 small. +[`CONTRIBUTING.md`](./CONTRIBUTING.md) · [`CHANGELOG.md`](./CHANGELOG.md) · Issues/PRs welcome; keep L0 small.