diff --git a/.aap/map.yaml b/.aap/map.yaml new file mode 100644 index 0000000..5dc1c98 --- /dev/null +++ b/.aap/map.yaml @@ -0,0 +1,16 @@ +version: 2 +workspace: + id: agent-artifact-protocol + description: "The AAP specification, its JSON Schemas, examples, the aap-map skill and the optional cookbook." +self: + id: agent-artifact-protocol + kind: repository + path: . +layout: + # REVIEW: the spec itself is SPEC.md at the repository root; layout keys point at folders, so it has no key + schemas: schemas/ + skills: skills/ + examples: examples/ + cookbook: cookbook/ + scripts: scripts/ +nodes: [] diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..4cbf866 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,12 @@ +{ + "name": "agent-artifact-protocol", + "description": "Skills for the Agent Artifact Protocol (AAP), a repository map for coding agents", + "owner": { "name": "gitpash" }, + "plugins": [ + { + "name": "aap", + "source": "./", + "description": "aap-map: write a minimal .aap/map.yaml for any repository, with uncertain parts marked for human review." + } + ] +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..516c9c6 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "aap", + "version": "0.3.0", + "description": "The aap-map skill writes a minimal .aap/map.yaml for a repository and marks its guesses for human review.", + "author": { "name": "gitpash" }, + "repository": "https://github.com/gitpash/agent-artifact-protocol", + "license": "MIT", + "keywords": ["aap", "repository-map", "agent-context", "skill"] +} diff --git a/CHANGELOG.md b/CHANGELOG.md index 6c3fbf1..046c8c9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,29 @@ # Changelog -## Unreleased +## 0.3.0 — 2026-10-28 -(nothing yet) +First release with an agent entry point and an installable skill. The Map v2 schema and its semantics are unchanged from 0.2.0. The "-prototype" suffix is dropped from the version: the project is still experimental, and the README Status section says so in one place. + +### Added + +- `skills/aap-map/`: an agent skill (one `SKILL.md`, no dependencies) that inspects a repository, writes a minimal `.aap/map.yaml` and marks guesses with `# REVIEW:` comments. +- One-command install: `npx skills add gitpash/agent-artifact-protocol`, or in Claude Code `/plugin marketplace add gitpash/agent-artifact-protocol` and `/plugin install aap@agent-artifact-protocol` (`.claude-plugin/` manifests). +- `llms.txt`: an agent-readable entry point (what AAP is, what to open first, the `access` rules, links). +- `.aap/map.yaml`: this repository's own map, written with the skill and checked by `scripts/validate.py`. +- `docs/skill-tests.md`: how the skill was tested and what changed as a result. + +### Changed + +- README rewritten for newcomers: install first, quick start, minimal example, one Status section. Conformance labels moved into `SPEC.md`. +- `MOTIVATION.md` moved to `docs/motivation.md`; its pilot metrics sketch was removed (`cookbook/measuring.md` covers the method). +- Cookbook index is a plain list. Per-page "Profile status" lines were removed. +- Example pins in the cookbook now use `v0.3.0`. +- `schemas/map.schema.json`: `$id` now points at the tagged raw URL in this repository instead of a gist (the template editor hint likewise), and the top-level `description` no longer says "Pilot". Validation is unchanged. + +### Removed + +- `legacy/v1/` (the v1 zones map). It stays in git history and in the `v0.1.1-draft` tag. +- Cookbook pages `glass-box-factory.md`, `orchestrator-session.md` and `what-not-to-copy.md`. They described tooling and provenance that this repository does not ship. ## 0.2.1-prototype — 2026-10-16 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 298f180..828645f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,9 +6,9 @@ Thank you for helping keep the Core **small**. | Place | Form | |-------|------| -| Documents / CHANGELOG | `0.2.1-prototype` (no `v`) | -| Git tags | `v0.2.1-prototype` (with `v`) | -| Prior Core intro label | `0.2.0-draft` / historical commits — Map v2 rules unchanged in `0.2.1-prototype` | +| Documents / CHANGELOG | `0.3.0` (no `v`) | +| Git tags | `v0.3.0` (with `v`) | +| Earlier labels | `0.2.1-prototype`, `0.2.0-draft`; Map v2 rules are unchanged since `0.2.0-draft` | ## What belongs in Core vs elsewhere @@ -22,7 +22,7 @@ Thank you for helping keep the Core **small**. | Deployment-defined mode labels | Universal role vocabulary | | Schema shape validation | Cross-file linters beyond seed | | | **Stream packs**, **accept / done bars**, **orientation cards**, **local dispatcher** templates | -| | Hub-umbrella teaching, glass-box factory *pattern*, orchestrator-session *shape* | +| | Hub-umbrella teaching | | | Schema-pinning ops notes, brownfield init prose | ### Profile PRs are not Core MUST @@ -32,7 +32,6 @@ Pull requests that add or edit: - stream pack samples / templates - accept-default / done-bar checklists - thin orientation cards -- factory or multi-agent session **stories** …are **profile / cookbook** changes. Reviewers **MUST NOT** treat them as new Orientation requirements or as justification to grow mandatory L0. Optional profiles stay optional even when examples look polished. diff --git a/README.md b/README.md index 650e06b..692c805 100644 --- a/README.md +++ b/README.md @@ -1,313 +1,115 @@ # Agent Artifact Protocol (AAP) -**Version:** 0.2.1-prototype -**Status:** experimental prototype (docs + schema + validator) -**License:** MIT -**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`.) +A small map checked into your repository that tells coding agents where things live, so they can open the right place without loading everything first. -> **AAP makes repository context addressable without requiring repository context to be loaded.** +## Install the skill -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. +The `aap-map` skill looks at your repository and writes the map for you. It is one text file with no dependencies. -| 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 | +With the [`skills`](https://skills.sh) installer, which works for Claude Code, Codex, Cursor and many other agents: -The map is checked against **JSON Schema by a validator in CI**, so structure drift is caught by machine—not only by human review. That is a key difference from free-form orientation markdown. - -### How this relates to - -- **`AGENTS.md` / `CLAUDE.md`** — how to work vs where things are; orthogonal, can live side by side. -- **llms.txt-style indexes** — discovery lists of docs/URLs; AAP is a sparse layout/hop map, not a content catalog. Can coexist. -- **Repo-map style tools** — often generate or search structural overviews; AAP is a checked-in, schema-validated convention agents open first. Orthogonal. -- **Agent skills** — procedural how-to packs; AAP does not define skills and does not replace them. - ---- +```bash +npx skills add gitpash/agent-artifact-protocol +``` -## What problem is this for? +In Claude Code, from the plugin marketplace: -Coding agents often fail on **orientation** and **context pollution**, not on “missing a wiki page.” +```text +/plugin marketplace add gitpash/agent-artifact-protocol +/plugin install aap@agent-artifact-protocol +``` -| 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)) | +Then say this to your agent, inside the repository you want to map: -**AAP’s bet** (thesis, not a measured claim here): a sparse map + disclosure beats a bigger prompt. See [`MOTIVATION.md`](./MOTIVATION.md). How to run an honest local A/B: [`cookbook/measuring.md`](./cookbook/measuring.md). +> Use the aap-map skill to add an AAP map to this repo. -```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 +The agent reads the repository, writes `.aap/map.yaml`, marks anything it guessed with a `# REVIEW:` comment and tells you what to check. It does not interview you and it never overwrites an existing map. - 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 -``` +## Quick start ---- +1. **Install the skill** with one of the commands above. +2. **Ask your agent to add the map**, as shown above, and read the `# REVIEW:` lines it left. Fix or delete them, or answer "ok". +3. **Commit `.aap/map.yaml`** and tell the agent to read the map first in future sessions. A line in `AGENTS.md` or `CLAUDE.md` is enough. -## The protocol in three steps +If you would rather not install anything, give your LLM this link and ask it to explain AAP or to work in a repository that has a map. The file is written for an agent to read and points to the spec only when it is needed: -```mermaid -flowchart LR - O[Orient] --> W[Work] --> D[Deposit] +```text +https://raw.githubusercontent.com/gitpash/agent-artifact-protocol/main/llms.txt ``` -1. **Orient** — read the local map (L0); pick a **layout** key or **node**. -2. **Work** — any harness, skills, MCP, or humans; AAP does **not** prescribe how work is done. -3. **Deposit** — durable results under layout **`artifacts`**; drafts under **`scratch`**; follow map rules (not random paths). +## What AAP is -**Core Orientation conformance requires only step 1**; steps 2–3 are **convention**, not conformance MUST. +AAP is a filesystem convention. The map is a short YAML file with the name of the workspace, the folders an agent will want (`code`, `tests`, `docs` and so on) and, for multi-repository setups, a few direct hops to neighbouring repositories. Agents read that file and nothing else at the start of a session, then open one path as the task requires. ---- +The convention comes with a JSON Schema, so any tool can check a map, but the skill itself needs no tool to write one. -## How it works (Core) +## What AAP is not -### 1. One small map in *your* repo +- Not a context engine or retrieval system. Your normal tools (grep, an LSP, an index, MCP) still do the searching. +- Not an agent framework or a multi-agent runtime. +- Not a security boundary. The `access` field is a note between humans and agents, and real enforcement stays with Git permissions, protected branches and sandboxes. +- Not a replacement for `AGENTS.md` or `CLAUDE.md`. Those say how to work, the map says where things are, and the two sit side by side. -Prefer `.aap/map.yaml` (also `map.yaml` or `docs/map.yaml`). +## A minimal map ```yaml version: 2 workspace: id: my-app - description: What this checkout is + description: "What this repository is, one line." 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 } + code: src/ tests: tests/ artifacts: - - path: docs/artifacts/ - access: read-write # same resourceRef shape; list allowed - scratch: docs/scratch/ + - path: docs/decisions/ + access: read-write nodes: - id: orders-api kind: repository + description: "Owns the orders contract this app consumes." 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 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 | - -**MUST NOT:** force-load this upstream repo, the full SPEC, or an artifact corpus just to begin work. - -Full rules: [`SPEC.md`](./SPEC.md). - ---- - -## 60-second start (brownfield) - -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). - -**Pin** = which tag your copied templates came from. Nothing is fetched at agent runtime. Keep the pin visible in the map file: - -```bash -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 -``` - -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). - ---- - -## 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 -``` - -Nodes are **doors**, not “load every submodule into context.” -[`cookbook/hub-umbrella.md`](./cookbook/hub-umbrella.md) · [`examples/hub-umbrella/`](./examples/hub-umbrella/). - ---- - -## Optional profiles (not Core L0) - -Incubator maturity table (status / based on / used by): [`cookbook/README.md`](./cookbook/README.md). - -After map-only helps, you **may** add local procedure files (often gitignored): - -```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"] + access: read-only ``` -| 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) | -| CI validation (pinned schema on consumer maps) | [`ci-validation.md`](./cookbook/ci-validation.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) | -| Measuring map value (A/B method only) | [`measuring.md`](./cookbook/measuring.md) | - -Stubs: [`templates/orientation.md`](./templates/orientation.md), [`templates/stream-pack.yaml`](./templates/stream-pack.yaml). - ---- - -## Core vs profile - -```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 -``` - -| 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). | - -Field definitions for **`access`** / **`write`**: [How it works §1](#1-one-small-map-in-your-repo). +- `layout` maps an intent to a path in this checkout. A plain string means read-write, and the object form adds `access: read-only` for folders that are frozen, generated or vendored. When a key lists several paths, the first one that is not read-only is where durable notes go. +- `nodes` are direct hops to other repositories you would plausibly open during a normal change here. Most standalone repositories use `nodes: []`. +- Paths are relative to the repository root, never absolute and never containing `..`. ---- +Examples for a single repository, a hub with several repositories and path references with `access` are in [`examples/`](./examples/). The starter file is [`templates/minimal-map.yaml`](./templates/minimal-map.yaml). -## Vocabulary and conformance +## How an agent uses it -| 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 | +AAP asks for progressive disclosure in four levels, and only the first is required. -| 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 | +| Level | What the agent reads | When | +|-------|----------------------|------| +| L0 | The map only | Start of a session | +| L1 | One layout path or one node | After choosing a key or node for the task | +| L2 | One durable note | Only if the task needs durable memory | +| L3 | Code, with the usual tools | Implementation | -```bash -pip install pyyaml jsonschema -python scripts/validate.py -``` +Linked maps are hops taken on purpose and are never preloaded recursively. Until you enable writes, an agent should prefer reading and orienting only. -This is a **convention + schemas**, not a complete cross-file protocol suite. +## Beyond the basics ---- +- [`SPEC.md`](./SPEC.md): the short normative specification. +- [`schemas/`](./schemas/): the JSON Schema for the map and for the optional artifact envelope. +- [`cookbook/`](./cookbook/): optional profiles such as a hub map for several repositories, schema pinning, CI validation, stream packs and a done bar. None of them is needed for the basic map. +- [`docs/motivation.md`](./docs/motivation.md) explains why the map exists, and [`docs/skill-tests.md`](./docs/skill-tests.md) describes how the skill was tested. +- [`CONTRIBUTING.md`](./CONTRIBUTING.md) and [`CHANGELOG.md`](./CHANGELOG.md). -## What’s in this repository - -```text -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, meta-repo, stream-packs, invalid -cookbook/ # optional profiles + patterns -scripts/validate.py -``` - -**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). - ---- +To check maps in CI, see [`cookbook/ci-validation.md`](./cookbook/ci-validation.md). This is optional and the skill does not depend on it. This repository keeps its own map in [`.aap/map.yaml`](./.aap/map.yaml), written by the skill. ## Status -**`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/`. +AAP is at version 0.3.0 and is experimental. The Map v2 schema has not changed since 0.2.0, but the convention has been used on a small number of repositories, mostly by its author, and it has not been measured against alternatives. Expect small changes before 1.0, and treat the tag you pin as the version you are using. The thesis, that a sparse map beats a bigger prompt, is unproven here, and [`cookbook/measuring.md`](./cookbook/measuring.md) describes how to test it on your own work. If a map does not help, shrink it before adding anything. -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`. +Feedback is welcome as issues: map size, how fine layout keys should be, and whether the skill guesses well on repositories unlike the three it was tested on. -Feedback: map size, layout-key granularity, cross-runtime use without preload, whether Core is still too large, whether profiles stay optional in practice. +## License -[`CONTRIBUTING.md`](./CONTRIBUTING.md) · [`CHANGELOG.md`](./CHANGELOG.md) · Issues/PRs welcome; keep L0 small. +MIT. See [`LICENSE`](./LICENSE). diff --git a/SPEC.md b/SPEC.md index 1962208..5b1c81a 100644 --- a/SPEC.md +++ b/SPEC.md @@ -2,8 +2,7 @@ **Name:** Agent Artifact Protocol (AAP) **Kind:** filesystem convention + JSON Schema -**Version:** 0.2.1-prototype -**Status:** experimental Core (Map v2) + prototype docs/cookbook (profiles optional) +**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. @@ -155,3 +154,14 @@ python scripts/validate.py ``` The 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. + +## Conformance labels + +| 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. diff --git a/cookbook/README.md b/cookbook/README.md index 8ebbb7b..d9503c1 100644 --- a/cookbook/README.md +++ b/cookbook/README.md @@ -1,20 +1,16 @@ -# Cookbook profiles — status incubator +# Cookbook -Optional profiles and patterns. **Not Core L0.** Status is author-maintained maturity signal only. +Optional profiles and how-to pages. None of them is part of the mandatory first read (L0), and none is needed to claim Orientation conformance. Start with the map alone and add a page here only when the map has already helped and you want more. -Allowed status values: `used in practice` · `tried once` · `idea only` · empty (pending author) +| Page | What it covers | +|------|----------------| +| [brownfield-init](./brownfield-init.md) | Add a map to an existing repository without touching its docs system | +| [hub-umbrella](./hub-umbrella.md) | A hub map for several repositories, with nodes as navigation hops | +| [schema-pinning](./schema-pinning.md) | Pin the schema by tag or commit instead of following the branch tip | +| [ci-validation](./ci-validation.md) | Check maps against the pinned schema in CI (optional) | +| [measuring](./measuring.md) | How to run an honest A/B of map versus no map | +| [local-bootstrap](./local-bootstrap.md) | A thin orientation card and local index beside the map | +| [stream-packs](./stream-packs.md) | One task-class procedure pack per session | +| [done-bar](./done-bar.md) | A short checklist before an agent calls work done | -| Profile | Status | Based on | Used by | -|---------|--------|----------|---------| -| [schema-pinning](./schema-pinning.md) | used in practice | pin / immutable tag practice | author only | -| [local-bootstrap](./local-bootstrap.md) | used in practice | thin orientation + local index | author only | -| [done-bar](./done-bar.md) | used in practice | accept before done / PR | author only | -| [glass-box-factory](./glass-box-factory.md) | tried once | recent early trial | author only | -| [orchestrator-session](./orchestrator-session.md) | tried once | recent early trial | author only | -| [stream-packs](./stream-packs.md) | — | one task-class pack per session | — | -| [hub-umbrella](./hub-umbrella.md) | — | multi-repo shell map hops | — | -| [brownfield-init](./brownfield-init.md) | — | add map to an existing repo | — | - -`what-not-to-copy` is guidance, not a profile — omitted from this table. - -See also: [root README — optional profiles](../README.md#optional-profiles-not-core-l0). +Templates for the last three are in [`../templates/`](../templates/) and samples in [`../examples/stream-packs/`](../examples/stream-packs/). diff --git a/cookbook/brownfield-init.md b/cookbook/brownfield-init.md index b97d03e..dab03da 100644 --- a/cookbook/brownfield-init.md +++ b/cookbook/brownfield-init.md @@ -1,7 +1,5 @@ # Cookbook: brownfield init -> **Profile status:** pending author - ## Goal Add AAP orientation to an existing repo **without** rewriting its docs system. @@ -16,7 +14,7 @@ Add AAP orientation to an existing repo **without** rewriting its docs system. Record the immutable v2 tag or commit in a one-line note, e.g. `.aap/VERSION`. Do not validate against a floating branch tip. Details: [`schema-pinning.md`](./schema-pinning.md). ```text - v0.2.1-prototype + v0.3.0 https://github.com/gitpash/agent-artifact-protocol ``` diff --git a/cookbook/ci-validation.md b/cookbook/ci-validation.md index cac696f..5e42d3c 100644 --- a/cookbook/ci-validation.md +++ b/cookbook/ci-validation.md @@ -13,7 +13,7 @@ Pin details and dual-source honesty: [`schema-pinning.md`](./schema-pinning.md). | Pin | Effect | |-----|--------| -| **Git tag** (e.g. `v0.2.1-prototype`) | Human-readable; matches release notes | +| **Git tag** (e.g. `v0.3.0`) | Human-readable; matches release notes | | **Commit SHA** | Immutable when tags lag or you need a one-off revision | | Floating `main` / branch tip | **Silent drift** — yesterday’s green job can fail (or worse, pass a map that other clones reject) without any intentional upgrade | | Mutable Gist / `raw/.../main/...` URL | Same problem: remote bytes change under the same URL | @@ -51,7 +51,7 @@ Vendor-neutral shape — map the `run:` body onto GitHub Actions, GitLab CI, Bui # EXAMPLE — illustrative job fragment (any CI product) # Pin MUST be a tag or commit SHA, never a floating branch name alone. env: - AAP_PIN: v0.2.1-prototype # or full commit SHA + AAP_PIN: v0.3.0 # or full commit SHA steps: - name: checkout-consumer run: # your normal workspace checkout @@ -97,7 +97,7 @@ Notes: ## See also -- [`schema-pinning.md`](./schema-pinning.md) — pin styles, contract sidecar, Gist vs in-repo +- [`schema-pinning.md`](./schema-pinning.md) — pin styles, contract sidecar, editor hint vs in-repo schema - [`brownfield-init.md`](./brownfield-init.md) — pin during first map copy - [`README.md`](../README.md) — `scripts/validate.py` one-liner for this seed - [`CONTRIBUTING.md`](../CONTRIBUTING.md) — Core vs profile; keep L0 small diff --git a/cookbook/done-bar.md b/cookbook/done-bar.md index 6287a6f..dcbc64a 100644 --- a/cookbook/done-bar.md +++ b/cookbook/done-bar.md @@ -1,7 +1,5 @@ # Cookbook: done bar (optional profile) -> **Profile status:** used in practice - > **Optional profile — not required for Orientation conformance.** > Core L0 remains: discoverable map only. @@ -90,4 +88,3 @@ Harnesses MAY require walking the bar before “done.” That is **consumer/runt - [`stream-packs.md`](./stream-packs.md) - [`local-bootstrap.md`](./local-bootstrap.md) -- [`what-not-to-copy.md`](./what-not-to-copy.md) diff --git a/cookbook/glass-box-factory.md b/cookbook/glass-box-factory.md deleted file mode 100644 index ef98cc0..0000000 --- a/cookbook/glass-box-factory.md +++ /dev/null @@ -1,62 +0,0 @@ -# Cookbook: glass-box factory (optional pattern) - -> **Profile status:** tried once - -> **Optional pattern — not required for Orientation conformance.** -> Documents a *shape* for visible multi-session work. **No CLI or harness ships in this Core repo.** - -## Problem - -Incubators often grow a “factory”: queues, conductor scripts, session cards, prompt packs. Useful locally — toxic when mistaken for AAP Core or copied as mandatory infrastructure. - -## Pattern (ideas only) - -Keep the factory **glass-box** and **file-first**: - -| Idea | Meaning | -|------|---------| -| **Dumb file conductor** | Orchestration reads/writes ordinary files (queues, status, prompts). Logic stays boring and inspectable. | -| **Visible sessions** | Each worker/session has an on-disk card humans can open without a special UI. | -| **Prompts on disk** | Prompt text lives in the repo or scratch as files — not only inside a proprietary runtime blob. | -| **No hidden brain** | The conductor does not silently own product judgment; agents and humans do. | - -AAP’s job stops at **addresses and disclosure**. A factory is an **incubator/runtime** choice that may *use* maps and packs — it is not a Map v2 feature. - -## What this repo deliberately omits - -- Conductor CLIs / `*.mjs` runners -- Queue schemas and lease protocols -- Session card formats as Core types -- Mandatory multi-agent boards - -See [`what-not-to-copy.md`](./what-not-to-copy.md). - -## How it relates to AAP - -```text -map (L0) → optional stream pack → optional done bar - ↑ - factory may schedule sessions that follow the above - factory is not itself an AAP level -``` - -If you adopt a factory: - -1. Keep Core maps sparse. -2. Put factory state under layout `scratch` / local paths — not new mandatory L0 files. -3. Prefer copying **templates** into the consumer over live-fetching incubator `main`. -4. Document the factory as **runtime**, never as Orientation law. - -## Anti-patterns - -- Shipping a conductor binary “because AAP needs it” -- Preloading every session card and prompt pack at L0 -- Treating queue depth as a protocol conformance metric -- Renaming product factory docs as `SPEC.md` - -## See also - -- [`orchestrator-session.md`](./orchestrator-session.md) — manager/worker shape without harness lock-in -- [`stream-packs.md`](./stream-packs.md) -- [`done-bar.md`](./done-bar.md) -- [`what-not-to-copy.md`](./what-not-to-copy.md) diff --git a/cookbook/hub-umbrella.md b/cookbook/hub-umbrella.md index bd7773e..431d713 100644 --- a/cookbook/hub-umbrella.md +++ b/cookbook/hub-umbrella.md @@ -1,7 +1,5 @@ # Cookbook: hub umbrella (multi-repo shell) -> **Profile status:** pending author - > **Teaching pattern on Core maps.** Core already allows shell maps (`nodes` + child `map.path`). This page scales the idea. Not a new Core requirement. ## Problem diff --git a/cookbook/local-bootstrap.md b/cookbook/local-bootstrap.md index 9f4d91e..b48188b 100644 --- a/cookbook/local-bootstrap.md +++ b/cookbook/local-bootstrap.md @@ -1,7 +1,5 @@ # Cookbook: local bootstrap (optional profile) -> **Profile status:** used in practice - > **Optional profile — not required for Orientation conformance.** > Keeps machine GPS and session procedure out of the committed Core map. @@ -98,6 +96,5 @@ Before claiming done / ship / PR-ready, walk a small checklist (orient, evidence - [`done-bar.md`](./done-bar.md) - [`schema-pinning.md`](./schema-pinning.md) - [`hub-umbrella.md`](./hub-umbrella.md) -- [`what-not-to-copy.md`](./what-not-to-copy.md) - [`brownfield-init.md`](./brownfield-init.md) — still ends at map-only experiment first diff --git a/cookbook/measuring.md b/cookbook/measuring.md index 177b4a6..6b1bd78 100644 --- a/cookbook/measuring.md +++ b/cookbook/measuring.md @@ -1,6 +1,6 @@ # Measuring whether a map helps (method) -**Status:** method profile — documents *how* to measure, not measured results. +This page documents *how* to measure, not measured results. **Do not** paste invented before/after numbers into this file. This is an optional cookbook pattern. It is **not** Core MUST and not required for Orientation conformance. @@ -11,7 +11,7 @@ This is an optional cookbook pattern. It is **not** Core MUST and not required f Check whether a **sparse local map** improves orientation on *your* real work — with an honest A/B, not a slogan. -Related: root README “Experiment before you expand” and [`MOTIVATION.md`](../MOTIVATION.md). +Related: [`docs/motivation.md`](../docs/motivation.md). --- diff --git a/cookbook/orchestrator-session.md b/cookbook/orchestrator-session.md deleted file mode 100644 index 17cc717..0000000 --- a/cookbook/orchestrator-session.md +++ /dev/null @@ -1,88 +0,0 @@ -# Cookbook: orchestrator session (optional profile) - -> **Profile status:** tried once - -> **Optional profile — not required for Orientation conformance.** -> Harness-agnostic **shape** for manager / worker / handoff. Multi-agent “teams” features are **one** possible implementation — not required by AAP. - -## Problem - -Long-running or multi-role work needs: - -- a plan someone can re-open tomorrow -- bounded worker tasks -- an end-of-day or end-of-stream **handoff** - -Teams then either paste huge chat logs into the next session or bind the protocol to one vendor’s teammate API. - -## Shape (runtime-agnostic) - -| Role | Responsibility | -|------|----------------| -| **Manager (orchestrator)** | Owns the plan, spawns or sequences work, integrates results, writes handoff | -| **Worker** | Executes a bounded slice with map + **one** stream pack; returns evidence | -| **Handoff** | Durable note: done / in flight / blockers / next map locus — under layout write-home or scratch | - -```text -plan → assign bounded work → workers orient (map) → optional pack → evidence → - manager integrates → accept bar → handoff file -``` - -Nothing here requires a particular desktop app, teammate RPC, or shared task-board product. - -## Implementation menu (examples, not mandates) - -| Approach | Notes | -|----------|--------| -| Single human + one agent session | Manager is the human; handoff is a Markdown file | -| Sequential agent sessions | Same shape; new session reads handoff first | -| Multi-agent / “agent teams” runtime | **One** way to spawn workers; still optional | -| External ticket system | Tickets carry handoff; map still orients code | - -**AAP does not require multi-agent runtimes.** If your harness has teams/teammates, use them as an adapter — do not encode spawn APIs into Core maps. - -## Handoff sketch (informative) - -```markdown -# Handoff — YYYY-MM-DD - -## Done -- … - -## In flight -- … (owner, path locus) - -## Blockers -- … (evidence links) - -## Next -- Open map → node X → layout Y -- Suggested stream: research | release-check | … -``` - -Prefer layout `artifacts` or `scratch` paths from the map. Do not invent a parallel durable root. - -## Session bootstrap (when using this profile) - -1. Read local map (L0). -2. Read handoff if continuing prior work. -3. Open **exactly one** stream pack for this session’s class of work. -4. Before “done,” walk the [done bar](./done-bar.md). - -Profile bootstrap is **consumer policy** — it does not redefine Core L0. - -## Anti-patterns - -- “AAP compliance = must use agent teams” -- Manager preloads every worker prompt and child map -- Handoff that is only chat memory with no file -- Encoding vendor spawn tool names into shared cookbook examples as required vocabulary -- Growing Map v2 schema with orchestrator fields without multi-consumer evidence - -## See also - -- [`glass-box-factory.md`](./glass-box-factory.md) — visible sessions; no Core CLI -- [`stream-packs.md`](./stream-packs.md) -- [`done-bar.md`](./done-bar.md) -- [`local-bootstrap.md`](./local-bootstrap.md) -- [`what-not-to-copy.md`](./what-not-to-copy.md) diff --git a/cookbook/schema-pinning.md b/cookbook/schema-pinning.md index 815401e..11303e4 100644 --- a/cookbook/schema-pinning.md +++ b/cookbook/schema-pinning.md @@ -1,7 +1,5 @@ # Cookbook: schema pinning -> **Profile status:** used in practice - > **Consumer ops guidance — not a new Core schema feature.** > Keeps validators honest when upstream evolves. @@ -26,7 +24,7 @@ Agents then “pass” maps that other clones reject — or the reverse. | Style | Example | Notes | |-------|---------|--------| -| **Git tag** | `v0.2.1-prototype` | Preferred for humans; matches CHANGELOG language with `v` prefix on tags | +| **Git tag** | `v0.3.0` | Preferred for humans; matches CHANGELOG language with `v` prefix on tags | | **Commit SHA** | full or abbreviated immutable SHA | Best when tags lag | | **Vendored file** | copy `schemas/map.schema.json` into consumer | Offline CI; bump deliberately | | **Contract sidecar** | e.g. `.aap/aap-contract.yaml` with `revision` + `sha256` | Optional; consumer convention | @@ -34,7 +32,7 @@ Agents then “pass” maps that other clones reject — or the reverse. Conceptual pin (no fetch during normal sessions): ```bash -# git clone --depth 1 --branch v0.2.1-prototype \ +# git clone --depth 1 --branch v0.3.0 \ # https://github.com/gitpash/agent-artifact-protocol.git /tmp/aap # cp /tmp/aap/schemas/map.schema.json path/to/consumer-tools/ ``` @@ -43,7 +41,7 @@ One-line consumer note (example): ```text # .aap/VERSION (or equivalent local note) -v0.2.1-prototype +v0.3.0 https://github.com/gitpash/agent-artifact-protocol ``` @@ -53,14 +51,14 @@ https://github.com/gitpash/agent-artifact-protocol # Consumer-local — not required by Map v2 Core schema: name: map.schema.json - pin: v0.2.1-prototype # or commit SHA + pin: v0.3.0 # or commit SHA # sha256: source: https://github.com/gitpash/agent-artifact-protocol ``` Upgrade **schema revision, lock/contract, validator, and compatibility fixtures together**. Partial upgrades are how tip-drift returns. -## Dual gist vs in-repo honesty +## Editor hint vs in-repo schema This seed’s minimal map template may carry a `yaml-language-server: $schema=…` comment pointing at a **revision-pinned** raw URL for editor UX. The **repository** also ships `schemas/map.schema.json`. @@ -70,7 +68,7 @@ This seed’s minimal map template may carry a `yaml-language-server: $schema= | Pinned remote URL in a comment | Editor convenience — **must** name an immutable revision, not tip | | Consumer contract file | Local lock for *their* validators | -**MUST NOT** silently validate against Gist or GitHub **tip**. If Gist and git diverge, say so and pick one pin for automation until they match. +**MUST NOT** silently validate against a mutable URL or GitHub **tip**. If the remote copy and the repository ever diverge, say so and pick one pin for automation until they match. Validation is **never** required for L0 orientation. Schema checks are for editors, CI, and conformance claims — not session start preload. diff --git a/cookbook/stream-packs.md b/cookbook/stream-packs.md index 07c6e07..40bbfac 100644 --- a/cookbook/stream-packs.md +++ b/cookbook/stream-packs.md @@ -1,7 +1,5 @@ # Cookbook: stream packs (optional profile) -> **Profile status:** pending author - > **Optional profile — not required for Orientation conformance.** > Core L0 remains: discoverable map only. diff --git a/cookbook/what-not-to-copy.md b/cookbook/what-not-to-copy.md deleted file mode 100644 index 389bf47..0000000 --- a/cookbook/what-not-to-copy.md +++ /dev/null @@ -1,46 +0,0 @@ -# What not to copy from product incubators - -If you saw AAP grow inside a company monorepo first, **do not** treat that tree as the upstream product. - -## Leave in the product repo - -| Material | Why | -|----------|-----| -| Pilot plans and metrics | Local experiment | -| Adoption guides naming internal systems | Product-specific | -| Partner contracts / mirrors | Confidential or local | -| Runtime adapters (editor packs, desktop skills, MCP wiring) | Swappable; not Core | -| Huge architecture HTML dumps | Derived / unrelated | -| “Read SPEC every session” checklists | Violates L0 | -| Glass-box factory CLI, queue schemas, session cards | Incubator harness tooling | -| Day-manager / multi-agent orchestrator prompts and handoff paths | Runtime orchestration profile | -| Standing chat/TPM status macros | Team process, not orientation | -| Full local dispatcher product-policy dumps | Runtime file; keep thin if used at all | -| Knowledge-graph database files and rebuild scripts | Derived indexes; retrieval adapters | -| DB connection allow-lists and env enable markers | Environment adapters | -| Pilot metrics and tool-effectiveness logs | Local experiment | -| “Read SPEC + all stream packs every session” checklists | Violates progressive disclosure | -| Partner repo names and internal schema locks as if universal SoT | Consumer pin policy | - -## Copy or re-implement from upstream - -| Material | Why | -|----------|-----| -| Minimal map template | L0 | -| Envelope field names + core types | Interop | -| JSON Schemas (optional pin) | Validation | -| Progressive disclosure rules | Protocol law | -| Generic examples | Teaching | -| Hub-umbrella example shape | Teaching multi-node orientation | -| Stream pack **idea** + sample ids | Optional disclosure profile | -| Accept-default / done-bar **idea** | Optional honesty bar | -| Thin orientation card template | Optional local card | -| Schema-pinning **practice** | Consumer validator honesty | -| Glass-box / orchestrator **shape** (not CLI) | Optional runtime stories | - -## Rule - -> Upstream = small pinned seed. -> Consumer = local map + local memory. -> Incubator docs ≠ distribution unit. -> Optional profiles stay optional — they are not a second Core. diff --git a/MOTIVATION.md b/docs/motivation.md similarity index 53% rename from MOTIVATION.md rename to docs/motivation.md index 0e3af36..07c82c5 100644 --- a/MOTIVATION.md +++ b/docs/motivation.md @@ -1,6 +1,6 @@ -# AAP Motivation (outline) +# AAP motivation -**Status:** outline paired with Map v2 SPEC `0.2.1-prototype` (Core lineage `0.2.0-draft`) +Why the map exists and what it deliberately leaves out. The normative text is [`SPEC.md`](../SPEC.md). --- @@ -73,29 +73,6 @@ Expand schemas/profiles only if B wins on time-to-locus and wrong-home rate. --- -## 6b. Experiment metrics sketch (methodology) - -When a pilot runs longer than a single A/B task, prefer **cheap, honest counters** over dashboards. Sketch only — adapt labels locally; do not treat this section as a product analytics spec. - -| Signal | What to count | Pass intuition | -|--------|----------------|----------------| -| **Wrong-home** | Durable writes or “fix” edits outside map write-home / wrong node checkout | B (map) lowers rate vs A | -| **Time-to-locus** | Minutes (or turns) until first correct path/node | B faster on repeat task classes | -| **Graph / index degrade honesty** | Sessions where optional retrieval was empty/stale **and** the agent said so vs silent proceed | Degrade named ≥ silent fiction | -| **Accept-bar catches** | Done-bar steps that failed before a bad “PR ready” (red checks, evidence-free blocker, skipped orient) | Catches > 0 in early weeks is success, not shame | -| **Preload pressure** | Times session opened all packs or recursive child maps | Should trend down after stream-pack profile | - -**Honesty rules for the sketch:** - -- Missing optional index ≠ green “nothing found” without a degrade line. -- Wrong-home includes inventing parallel `docs/` roots the map never named. -- Accept-bar catches are **local process metrics**; they are not Core conformance scores. -- Do not publish internal pilot paths or vendor tool ids as if they were AAP required vocabulary. - -Optional profiles that support the loop: done bar, stream packs, hub umbrella (see cookbook). Still: if plain map-only B does not win, **shrink** — do not add metrics theater. - ---- - ## 7. Closing lines > Conventions over infrastructure. @@ -103,4 +80,4 @@ Optional profiles that support the loop: done bar, stream packs, hub umbrella (s > Progressive disclosure over context dumping. > Files over runtime dependencies. -Normative detail: [`SPEC.md`](./SPEC.md). This document explains motivation and positioning; it is not an evidence-backed white paper or normative specification. +This document explains motivation and positioning. It is not an evidence-backed white paper and not a specification. diff --git a/docs/skill-tests.md b/docs/skill-tests.md new file mode 100644 index 0000000..360d50d --- /dev/null +++ b/docs/skill-tests.md @@ -0,0 +1,38 @@ +# aap-map skill: test notes + +Tested 2026-10-28 on three public projects of different shape, cloned shallow into a scratch directory: chalk (small JS library), requests (Python library, `src/` layout, Sphinx docs) and changesets (pnpm TypeScript monorepo, 21 packages). In each run a fresh agent received only `SKILL.md` and followed it literally. A separate reviewer read the skill looking for assumptions inherited from a private team-side original. + +The skill was first written with a bundled schema and validator, then simplified to a single text file (the validator added install friction and little value at install time). Results below are from both versions. + +## Results + +| Project | Map produced | Notes | +|---|---|---| +| chalk | `code: source/`, `tests: test/`, `nodes: []` | No `read-only` guessed for the vendored folder inside the code root. Passes the JSON Schema. | +| requests | `code: src/requests/`, `tests: tests/`, `nodes: []` | Libraries (urllib3, certifi, ...) correctly not nodes. Passes (first version). | +| changesets | `code: packages/`, `docs` or `site` key, `nodes: []` | Parent folder used instead of 21 paths; tests next to code left out; one REVIEW on competing docs folders. Passes the JSON Schema. | + +No run admitted a node. Third-party libraries, README mentions and a branch of the same repo were all rejected, which is the intended result for standalone repositories. Final maps were checked against `schemas/map.schema.json` by the tester after the fact; the skill itself runs no tool. + +## What broke or was ambiguous, and what changed + +| Finding | Change | +|---|---| +| Flow-style example with a comma in a description split the value and the validator gave a confusing error | Example is block style; descriptions are quoted | +| `src/` versus `src/requests/` for `code` | Pick the folder that holds the code; check with `ls` | +| 21 packages, globs not supported | Use the parent folder | +| Tests next to code, no tests folder | Leave `tests` out | +| Docs website versus durable notes for `artifacts` | `artifacts` is working notes only | +| Vendored folder inside the code root | Keep the root, mention it in the report | +| Two competing docs folders; `scripts/` full of packages | Pick the current one with a REVIEW; key must really be what it says | +| A branch of the same repo in the README | Not a node | +| Case-sensitive file lookup | Case-insensitive | +| Rejected candidates have no id | Not needed in the shorter report | + +Reviewer findings applied: do not assume git; do not guess `locator.repo` or the host; `read-only` needs written evidence; slugify ids without reordering; edit the map as text so comments survive; never overwrite or create a second map. + +## Known limits + +- Tested with Claude subagents on macOS only. Other agents, Windows, and a repo that already has a map were not tried. +- Schema quirk: `pathString` rejects any path containing `..`, even inside a name (`a..b`). Left alone. +- Layout paths are literal, so large monorepos get a coarse parent folder. diff --git a/legacy/v1/examples/invalid/internal-zone-without-path.yaml b/legacy/v1/examples/invalid/internal-zone-without-path.yaml deleted file mode 100644 index 919915e..0000000 --- a/legacy/v1/examples/invalid/internal-zone-without-path.yaml +++ /dev/null @@ -1,5 +0,0 @@ -version: 1 -zones: - app: - kind: mixed - write: [maintainer] diff --git a/legacy/v1/examples/invalid/layout-absolute-path.yaml b/legacy/v1/examples/invalid/layout-absolute-path.yaml deleted file mode 100644 index 7f03d4c..0000000 --- a/legacy/v1/examples/invalid/layout-absolute-path.yaml +++ /dev/null @@ -1,7 +0,0 @@ -version: 1 -zones: - app: - path: . - write: [maintainer] - layout: - code: /abs/src/ diff --git a/legacy/v1/examples/invalid/layout-dotdot.yaml b/legacy/v1/examples/invalid/layout-dotdot.yaml deleted file mode 100644 index 67d4183..0000000 --- a/legacy/v1/examples/invalid/layout-dotdot.yaml +++ /dev/null @@ -1,7 +0,0 @@ -version: 1 -zones: - app: - path: . - write: [maintainer] - layout: - code: ../outside/ diff --git a/legacy/v1/examples/invalid/write-readonly.yaml b/legacy/v1/examples/invalid/write-readonly.yaml deleted file mode 100644 index c62c6cc..0000000 --- a/legacy/v1/examples/invalid/write-readonly.yaml +++ /dev/null @@ -1,5 +0,0 @@ -version: 1 -zones: - app: - path: . - write: [""] diff --git a/legacy/v1/examples/multi-zone/map.yaml b/legacy/v1/examples/multi-zone/map.yaml deleted file mode 100644 index 87e8a8f..0000000 --- a/legacy/v1/examples/multi-zone/map.yaml +++ /dev/null @@ -1,42 +0,0 @@ -# yaml-language-server: $schema=../../schemas/map.schema.json -# Shell / multi-root workspace — keep zone count honest and sparse. -version: 1 - -defaults: - layout: - artifacts: docs/artifacts/ - scratch: docs/scratch/ - -zones: - global: - path: . - kind: root - write: [platform-maintainer] - layout: - artifacts: docs/artifacts/global/ - scratch: docs/scratch/ - - backend: - path: services/backend - kind: backend - write: [service-maintainer] - layout: - code: src/ - tests: tests/ - artifacts: docs/artifacts/ - scratch: docs/scratch/ - - frontend: - path: apps/web - kind: frontend - write: [service-maintainer] - layout: - code: src/ - tests: src/ - artifacts: docs/artifacts/ - scratch: docs/scratch/ - -# Optional machine-local overrides (prefer gitignored map.local.yaml): -# overlays: -# local_paths: -# backend: /home/you/src/backend-standalone diff --git a/legacy/v1/examples/single-repo/map.yaml b/legacy/v1/examples/single-repo/map.yaml deleted file mode 100644 index 58f58a6..0000000 --- a/legacy/v1/examples/single-repo/map.yaml +++ /dev/null @@ -1,20 +0,0 @@ -# yaml-language-server: $schema=../../schemas/map.schema.json -# Single product repository — topology optional; map still helps orientation. -version: 1 - -defaults: - layout: - artifacts: docs/artifacts/ - scratch: docs/scratch/ - -zones: - app: - path: . - kind: mixed - write: [maintainer] - layout: - code: src/ - tests: tests/ - scripts: scripts/ - artifacts: docs/artifacts/ - scratch: docs/scratch/ diff --git a/legacy/v1/schemas/map.schema.json b/legacy/v1/schemas/map.schema.json deleted file mode 100644 index c43f92c..0000000 --- a/legacy/v1/schemas/map.schema.json +++ /dev/null @@ -1,188 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://raw.githubusercontent.com/gitpash/agent-artifact-protocol/v0.1.1-draft/schemas/map.schema.json", - "title": "AAP Map v0.1", - "type": "object", - "additionalProperties": false, - "required": ["version", "zones"], - "properties": { - "version": { - "type": "integer", - "enum": [1], - "description": "Map format version." - }, - "defaults": { - "type": "object", - "additionalProperties": false, - "properties": { - "layout": { "$ref": "#/$defs/layoutObject" } - } - }, - "zones": { - "type": "object", - "minProperties": 1, - "propertyNames": { - "type": "string", - "pattern": "^[a-z][a-z0-9-]*$" - }, - "additionalProperties": { "$ref": "#/$defs/zoneObject" } - }, - "overlays": { - "type": "object", - "additionalProperties": false, - "description": "Prefer map.local.yaml (gitignored) instead of committing absolute paths.", - "properties": { - "local_paths": { - "type": "object", - "propertyNames": { - "type": "string", - "pattern": "^[a-z][a-z0-9-]*$" - }, - "additionalProperties": { - "type": "string", - "minLength": 1, - "description": "Absolute path or workspace-relative path to a checkout root for a zone id." - } - } - } - }, - "profiles": { - "type": "object", - "additionalProperties": false, - "properties": { - "enabled": { - "type": "array", - "items": { "type": "string", "minLength": 1 }, - "description": "Opt-in profile ids. Unknown ids must not break parse." - } - } - } - }, - "$defs": { - "pathOrPaths": { - "oneOf": [ - { - "type": "string", - "minLength": 1, - "pattern": "^(?!.*\\.\\.)(?!/).*$", - "description": "Path relative to resolved zone root; / separators; no .. or absolute." - }, - { - "type": "array", - "minItems": 1, - "items": { - "type": "string", - "minLength": 1, - "pattern": "^(?!.*\\.\\.)(?!/).*$" - } - } - ] - }, - "layoutObject": { - "type": "object", - "description": "Intent → path router. Core keys documented in SPEC; additional keys are extensions.", - "properties": { - "code": { "$ref": "#/$defs/pathOrPaths" }, - "tests": { "$ref": "#/$defs/pathOrPaths" }, - "artifacts": { "$ref": "#/$defs/pathOrPaths" }, - "scratch": { "$ref": "#/$defs/pathOrPaths" }, - "scripts": { "$ref": "#/$defs/pathOrPaths" }, - "infra": { "$ref": "#/$defs/pathOrPaths" }, - "proposals": { "$ref": "#/$defs/pathOrPaths" }, - "architecture": { "$ref": "#/$defs/pathOrPaths" } - }, - "additionalProperties": { "$ref": "#/$defs/pathOrPaths" } - }, - "remoteObject": { - "type": "object", - "additionalProperties": false, - "properties": { - "url": { "type": "string", "minLength": 1 }, - "repo": { - "type": "string", - "description": "owner/name shorthand" - }, - "id": { "type": "string" }, - "default_branch": { "type": "string" } - }, - "anyOf": [ - { "required": ["url"] }, - { "required": ["repo"] }, - { "required": ["id"] } - ] - }, - "aapPointerObject": { - "type": "object", - "additionalProperties": false, - "description": "Paths relative to resolved foreign root.", - "properties": { - "map": { "type": "string", "minLength": 1 }, - "spec": { "type": "string", "minLength": 1 }, - "version": { "type": "string" } - } - }, - "zoneObject": { - "type": "object", - "additionalProperties": false, - "required": [], - "properties": { - "path": { - "type": "string", - "minLength": 1, - "description": "In-workspace root relative to workspace root. Required for internal zones." - }, - "relation": { - "type": "string", - "enum": ["internal", "external"], - "description": "Default internal when omitted." - }, - "remote": { "$ref": "#/$defs/remoteObject" }, - "aap": { "$ref": "#/$defs/aapPointerObject" }, - "mirrors": { - "type": "string", - "minLength": 1, - "description": "Workspace-relative path for mirror artifacts about this zone (esp. external)." - }, - "kind": { - "type": "string", - "description": "Soft hint. Recommended: root|backend|frontend|infra|batch|mixed|external. Unknown allowed." - }, - "access": { - "type": "string", - "enum": ["read-only", "read-write"] - }, - "write": { - "type": "array", - "items": { - "type": "string", - "minLength": 1 - }, - "description": "Deployment-defined mutating mode labels. Empty array = no declared write grant. Core does not define a universal role vocabulary." - }, - "layout": { "$ref": "#/$defs/layoutObject" } - }, - "allOf": [ - { - "if": { - "properties": { "relation": { "const": "external" } }, - "required": ["relation"] - }, - "then": { - "required": ["remote"] - } - }, - { - "if": { - "anyOf": [ - { "properties": { "relation": { "const": "internal" } }, "required": ["relation"] }, - { "not": { "required": ["relation"] } } - ] - }, - "then": { - "required": ["path"] - } - } - ] - } - } -} diff --git a/llms.txt b/llms.txt new file mode 100644 index 0000000..6ce04ce --- /dev/null +++ b/llms.txt @@ -0,0 +1,77 @@ +# Agent Artifact Protocol (AAP) + +> AAP makes repository context addressable without requiring it to be loaded. It is a small filesystem convention: one checked-in map file (`.aap/map.yaml`) that tells an agent where things live and which neighboring repositories exist, validated by a JSON Schema. It is not a context engine, RAG, agent framework, dependency graph or authorization system. + +Version: 0.3.0 (experimental, pre-1.0). Pin the tag `v0.3.0`; do not read the default branch tip as authoritative. + +## If you are an agent working in a repository + +1. Look for the map in this order: `.aap/map.yaml`, `map.yaml`, `docs/map.yaml`. +2. Read that one file. That is the whole orientation step (level L0). Do not open anything else yet. +3. Pick one `layout` key (`code`, `tests`, `artifacts`, `scratch`, ...) or one `nodes` entry for the task, and open only that path (L1). +4. Open a single durable artifact only if the task needs durable memory (L2). Use normal code tools for the rest (L3). +5. A node with a `map` pointer is a hop you may take on purpose. Never open linked maps recursively "to be safe". +6. Do not fetch this upstream repository or read SPEC.md at session start. The local map is the source of truth for the checkout. + +If there is no map and the user wants one, use the `aap-map` skill (see below) or copy `templates/minimal-map.yaml` to `.aap/map.yaml` and edit it. Never overwrite an existing map without explicit confirmation. + +## The map in one screen + +```yaml +version: 2 +workspace: { id: my-app, description: What this checkout is } +self: { id: my-app, kind: repository, path: . } +layout: + code: src/ + tests: tests/ + artifacts: docs/artifacts/ + scratch: docs/scratch/ +nodes: [] +``` + +- `id` values are lowercase kebab-case and start with a letter. +- `layout` maps intent to a path in this checkout. Paths are relative, never absolute, never contain `..`. Paths may be absent on disk; do not invent a directory tree to satisfy the map. +- `nodes` are direct navigation hops to other repositories or products. They are not a dependency graph. Keep them few. +- Machine-local checkout paths go in a gitignored `map.local.yaml` (`overlays`), not in the committed map. + +## The `access` rules (write fence) + +Every layout value is either a path string or `{ path, access?, description? }`. + +- A string means `{ path: , access: read-write }`. A missing `access` means `read-write`. +- `access` is `read-only` or `read-write`. Nothing else. +- `read-only`: you may read it, you must not create or change durable content there. +- When a layout key lists several paths, the durable write home is the first entry whose access is not `read-only`. +- If a key has no writable entry, stop and ask. Do not invent a parallel root and do not write into a read-only one. +- On a node, `access: read-only` means do not modify that repository from this workspace (typical for external products). +- A node's `write: [...]` list is a role hint, not a permission. It never overrides `access`. +- `overlays` only say where a node is checked out on this machine. They never grant write rights. +- All of this is a coordination fence between agents and humans. Real enforcement is Git permissions, CODEOWNERS, protected branches and sandboxes. + +Until the user or runtime explicitly enables writes, prefer reading and orienting only. + +## Where to read next (only when needed) + +- Normative spec, short: https://github.com/gitpash/agent-artifact-protocol/blob/v0.3.0/SPEC.md +- Map JSON Schema (draft-07): https://raw.githubusercontent.com/gitpash/agent-artifact-protocol/v0.3.0/schemas/map.schema.json +- Starter map: https://raw.githubusercontent.com/gitpash/agent-artifact-protocol/v0.3.0/templates/minimal-map.yaml +- Examples (single repo, multi-repo hub, resource refs): `examples/` in the same tag +- Optional profiles (stream packs, done bar, hub umbrella, CI validation): `cookbook/README.md`. These are never part of the mandatory first read. +- Validator for this repo: `pip install pyyaml jsonschema && python scripts/validate.py` + +## Creating or updating a map: the `aap-map` skill + +The folder `skills/aap-map/` is a portable agent skill (one SKILL.md). It looks at a codebase, writes a minimal map, and flags guesses for human review. It does not need any tools installed. Install commands are at the top of the README. + +## Rules of thumb + +- Keep the map sparse. If a map did not help on a real task, shrink it before adding anything. +- Prefer omitting a layout key over pointing it at a path that does not exist. +- A node needs one concrete reason to exist: you would plausibly open that repository during a normal change here. A mention in a README is not enough. +- Schema-valid does not mean useful. A human should review nodes before the map is relied on. + +## Optional + +- Rationale: https://github.com/gitpash/agent-artifact-protocol/blob/v0.3.0/docs/motivation.md +- Changelog: https://github.com/gitpash/agent-artifact-protocol/blob/v0.3.0/CHANGELOG.md +- License: MIT diff --git a/schemas/map.schema.json b/schemas/map.schema.json index 94ddf71..7c13ef2 100644 --- a/schemas/map.schema.json +++ b/schemas/map.schema.json @@ -1,8 +1,8 @@ { "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://gist.githubusercontent.com/gitpash/928c100ebf269acf9db7c09a18ed4a68/raw/map.schema.json", + "$id": "https://raw.githubusercontent.com/gitpash/agent-artifact-protocol/v0.3.0/schemas/map.schema.json", "title": "AAP Map (workspace / self / nodes) — single convention", - "description": "Pilot map schema. Additive evolution preferred while adoption is near-zero. Layout paths use resourceRef (path + optional access) so write fences share the same permission class as nodes.", + "description": "AAP Map v2. Additive evolution preferred. Layout paths use resourceRef (path + optional access) so write fences share the same permission class as nodes.", "type": "object", "additionalProperties": false, "required": ["version", "workspace", "self", "nodes"], diff --git a/scripts/validate.py b/scripts/validate.py index 66591bd..12de0b8 100644 --- a/scripts/validate.py +++ b/scripts/validate.py @@ -59,18 +59,21 @@ def main() -> None: die("PyYAML and jsonschema required: pip install pyyaml jsonschema") map_schema = load_json(ROOT / "schemas" / "map.schema.json") envelope_schema = load_json(ROOT / "schemas" / "artifact-envelope.schema.json") + for manifest in sorted((ROOT / ".claude-plugin").glob("*.json")): + load_json(manifest) + print(f"OK json {manifest.relative_to(ROOT)}") jsonschema.Draft7Validator.check_schema(map_schema) jsonschema.Draft7Validator.check_schema(envelope_schema) print("OK schemas self-validate") map_validator = jsonschema.Draft7Validator(map_schema) envelope_validator = jsonschema.Draft7Validator(envelope_schema) - # templates + every examples/**/map.yaml except under examples/invalid/ + # template, this repo's own map, every examples/**/map.yaml except under examples/invalid/ example_maps = sorted( path for path in (ROOT / "examples").rglob("map.yaml") if "invalid" not in path.relative_to(ROOT / "examples").parts ) - positives = [ROOT / "templates" / "minimal-map.yaml"] + example_maps + positives = [ROOT / "templates" / "minimal-map.yaml", ROOT / ".aap" / "map.yaml"] + example_maps for path in positives: data = yaml.safe_load(path.read_text(encoding="utf-8")) errors = list(map_validator.iter_errors(data)) + [Exception(error) for error in layout_path_errors(data)] diff --git a/skills/aap-map/SKILL.md b/skills/aap-map/SKILL.md new file mode 100644 index 0000000..a48ad91 --- /dev/null +++ b/skills/aap-map/SKILL.md @@ -0,0 +1,101 @@ +--- +name: aap-map +description: Add a minimal AAP (Agent Artifact Protocol) navigation map, .aap/map.yaml, to the current repository. Use when the user asks to add or fix an AAP map, or says "aap-map". Reads the repo, writes a small map, and tells the user what it guessed. Does not ask questions it can answer by looking. +--- + +# aap-map + +Writes a small `.aap/map.yaml` for the repository you are in. AAP in one line: a checked-in map that says where things live and which neighboring repositories exist, so an agent can open the right place without loading everything. + +Default behavior: look, decide, write, report. Do not interview the user. The user can say "yes" to the result, or tell you what to change. + +## Ground rules + +- If a map already exists (`.aap/map.yaml`, `map.yaml` or `docs/map.yaml`), do not overwrite it and do not create a second one. Show what you would change and ask once. +- Work in the project root you were pointed at. In a monorepo subfolder, use the closest sensible root and say which you chose. +- Do not touch other repositories, move folders, or rename docs. The only file you create is the map (plus its `.aap/` folder). +- No absolute or machine-specific paths in the map. +- Keep it small. A map that fits on one screen is the goal. + +## Steps + +1. **Look.** README and any `AGENTS.md` / `CLAUDE.md` if present (file names in any case), the top-level folders, the build manifest (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, ...) for the name and source layout, test folders or config, a folder of durable notes if one exists (`docs/adr/`, `adr/`, `rfcs/`), `.gitmodules` and workspace definitions if present. Stop as soon as you can fill the map. Check that each path exists with `ls`. +2. **Write `.aap/map.yaml`** in this shape. Block style, descriptions in quotes (an unquoted comma or colon breaks flow-style YAML): + + ```yaml + version: 2 + workspace: + id: my-app + description: "What this repository is, one line." + self: + id: my-app + kind: repository + path: . + layout: + code: src/ + tests: tests/ + nodes: [] + ``` + +3. **Report** in a few lines (see the end), then stop. + +## Filling it in + +**ids** (`workspace.id`, `self.id`, node ids): lowercase letters, digits and hyphens, starting with a letter. Slugify the repo name (`My_App` becomes `my-app`, `3d-viewer` becomes `app-3d-viewer`); never reorder words. `workspace.id` and `self.id` may be equal. + +**layout** maps intent to a path in this repo. Add a key only when the folder exists: +- `code` and `tests` usually. Several code roots: a list. Many packages (more than about five): use the parent folder (`packages/`). Paths are literal, no globs. +- Tests next to the code and no tests folder: leave `tests` out. +- `artifacts` only for a folder of working notes (ADRs, decisions, specs) that already exists. A docs website is not `artifacts`. Do not create a new folder for it. +- Other keys (`docs`, `scripts`, `infra`, ...) are allowed, only if the folder really is that (a `scripts/` folder full of workspace packages is not scripts) and an agent would plausibly be sent there. Fewer is better. +- Two folders compete (old docs and a newer site, say): pick the one the repo says is current, and add a REVIEW comment. +- A vendored folder inside the code root: keep the root and mention the folder in the report. +- Paths: relative, no leading `/`, no `..`. + +**access.** Paths are read-write by default; leave `access` out. Use `{ path: ..., access: read-only }` only when the repo itself says the folder is frozen, generated or vendored (README, CODEOWNERS, `.gitattributes`, a header in the folder). A folder name alone is not evidence. + +**nodes** are direct hops to other repositories someone would plausibly open during a normal change here. `nodes: []` is a normal answer for a standalone repository. Admit a node only if you can name a reason and point at evidence in this repo: +- it is called at runtime (client or endpoint config), +- it owns a contract this repo consumes (schema, API definition, generated client), +- it is the named source of truth for design or requirements, +- it is an intentionally shared convention with a maintained sync. + +Not nodes: third-party libraries, README mentions, transitive dependencies, a one-time scaffold source, another branch or fork of this repo, packages inside a monorepo (use `layout.code`). + +For a node: `id`, `kind` (`repository`, or `external` if you only read about it), a one-line `description` of what is consulted there and when. `locator.repo` or `locator.url` only if copied from `.gitmodules`, a git remote, the README or config; never guess an organization or host. `map.path: .aap/map.yaml` only if you saw that file there. `access: read-only` for consume-only hops. Machine paths for neighbors go in a gitignored `map.local.yaml`, not here. + +Leave out `relations`, `overlays`, `profiles`, `mirror`, `write` unless asked. + +## Flag guesses + +Anything you are not sure about gets a `# REVIEW: ` comment on that line, and is listed in the report. Typical cases: a node, a `read-only`, a slugified id, two competing folders, a path you could not confirm. Edit the file as text; do not load it into a YAML library and write it back, which deletes comments. + +## Checking it (optional) + +You do not need to run a validator, and nothing has to be installed. Before you report, read the file once against this list: + +- `version: 2`; `workspace`, `self`, `nodes` present; `nodes` is a list. +- ids match `^[a-z][a-z0-9-]*$`. +- Only known fields: `workspace` {id, description}; `self` {id, kind, path, description, parent}; nodes {id, kind, description, path, locator, map, mirror, access, write}; `access` is `read-only` or `read-write`. +- Layout paths are relative, with no `..`. + +If the user wants machine checking later (for example in CI), the AAP repository has the JSON Schema (`schemas/map.schema.json`), a reference script (`scripts/validate.py`) and a guide (`cookbook/ci-validation.md`). Mention that in one line, only if they ask about validation. + +## Report + +Plain and short: + +```text +Added .aap/map.yaml +- layout: +- nodes: +- guessed (marked REVIEW): +- not checked by a tool: read against the field list by hand +Say "ok", or tell me what to change. +``` + +Do not claim the map is "validated". Do not offer profiles, stream packs or other extras unless asked. + +## What the map must not become + +A list of every folder, a dependency graph, a place for procedures or essays (those go in `AGENTS.md` or README), or a permission system (`access` is a note between humans and agents, not enforcement). diff --git a/templates/minimal-map.yaml b/templates/minimal-map.yaml index f0eb147..f4223c8 100644 --- a/templates/minimal-map.yaml +++ b/templates/minimal-map.yaml @@ -1,4 +1,4 @@ -# yaml-language-server: $schema=https://gist.githubusercontent.com/gitpash/928c100ebf269acf9db7c09a18ed4a68/raw/9bec3c5cb3cc259e6197746a1c753adfe952f8cc/map.schema.json +# yaml-language-server: $schema=https://raw.githubusercontent.com/gitpash/agent-artifact-protocol/v0.3.0/schemas/map.schema.json # AAP v2 L0 orientation map — keep this file small. # Copy to .aap/map.yaml. Do not overwrite an existing map without confirmation. version: 2