From 2fef55b0edb77c02897571f9df569a1a7a02dcfc Mon Sep 17 00:00:00 2001 From: Pavel Luzanov Date: Fri, 16 Oct 2026 18:25:43 +0900 Subject: [PATCH 1/4] docs(readme): problem/how-it-works diagrams for 0.2.1-prototype Refresh top-of-README for graspability: failure modes, Core flow, progressive disclosure, hub hops, optional profiles, pin story. Mermaid diagrams; keep Core vs profile fence explicit. --- README.md | 336 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 197 insertions(+), 139 deletions(-) diff --git a/README.md b/README.md index 84d7a4d..a9c6f17 100644 --- a/README.md +++ b/README.md @@ -3,155 +3,207 @@ **Version:** 0.2.1-prototype **Status:** experimental Map v2 Core + dogfood-informed **optional** profiles (working-prototype **docs**) **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** for: - -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 is a **runtime-agnostic filesystem convention**: a tiny map in the repo so agents (and humans) can **find the right place** without dumping CLAUDE/SPEC/wiki into the prompt. 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. - -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 +## What problem is this for? + +Coding agents waste turns on **orientation failure** and **context pollution**: + +| Failure | What happens | +|---------|----------------| +| Wrong home | Edits land in the wrong package, service, or “docs that look related” | +| Preload bloat | Session starts by reading constitutions, full catalogs, every submodule map | +| No GPS | Multi-repo / monorepo: path ≠ GitHub name; nobody knows the hop | +| Fake confidence | “PR ready” with red CI or blockers invented without evidence | + +AAP’s bet: **a sparse map + progressive disclosure** beats a bigger prompt. + +```mermaid +flowchart LR + subgraph before [Without AAP] + A[Agent starts] --> B[Dump CLAUDE / wiki / all maps] + B --> C[Guess locus] + C --> D[Wrong home or token blow-up] + 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 +``` --- -## Progressive disclosure +## How it works (Core) -| 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 | +### 1. One small map in *your* repo -**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.” +Prefer `.aap/map.yaml` (also `map.yaml` or `docs/map.yaml`). -**MUST NOT:** force agents to load this whole repository, the full SPEC, or an artifact corpus into the model context to begin work. +```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/ # optional durable notes + scratch: docs/scratch/ # optional throwaway notes +nodes: [] # or direct hops to related repos +``` ---- +| Piece | Role | +|-------|------| +| **workspace / self** | What you opened | +| **layout** | Vocabulary keys (`code`, `tests`, `artifacts`, `scratch`, …) → directories | +| **nodes** | Direct **navigation hops** (related repos/products) — not a dependency graph | +| **resourceRef** | Path string or `{ path, access?, description? }` (`access: read-only` = coordination fence, not ACL) | -## 60-second start (brownfield) +### 2. Progressive disclosure (do not load the universe) -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). +```mermaid +flowchart TD + L0["L0 — Map only
Orientation conformance"] + L1["L1 — One layout path or node hop"] + L2["L2 — One durable artifact if needed"] + L3["L3 — Code + grep / LSP / indexes
outside AAP"] -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. + L0 --> L1 --> L2 --> L3 -```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 + P["Optional profile bootstrap
thin orientation + exactly one stream pack"] + L0 -.-> P + P -.-> L1 ``` -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. +| Level | What | When | +|-------|------|------| +| **L0** | Map only | Session start | +| **L1** | Targeted path / layout index | After choosing a key or node | +| **L2** | One artifact | Durable memory needed | +| **L3** | Normal engineering tools | Implementation | + +**MUST NOT:** force-load this upstream repo, the full SPEC, or an artifact corpus just to begin work. + +### 3. 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
self.parent → hub"] + N2 --> C2["Child map optional"] +``` ---- +Nodes are **doors**, not “git clone everything into context.” +See [`cookbook/hub-umbrella.md`](./cookbook/hub-umbrella.md) and [`examples/hub-umbrella/`](./examples/hub-umbrella/). -## Repository layout (this seed) +### 4. Optional profiles (not Core L0) -```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 +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 --> D[done-bar at exit] + M --> W[work] + D --> W ``` -**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. +| 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 here) | [`glass-box-factory.md`](./cookbook/glass-box-factory.md) | + +Templates: [`templates/orientation.md`](./templates/orientation.md), [`templates/stream-pack.yaml`](./templates/stream-pack.yaml). --- -## Core vs profile +## 60-second start (brownfield) -| 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) | +1. Copy [`templates/minimal-map.yaml`](./templates/minimal-map.yaml) → `.aap/map.yaml` (or `map.yaml` / `docs/map.yaml`). +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: **no map** vs **map only**. If map doesn’t help → **shrink**, don’t add profiles. +5. Only then optional profiles (hub / streams / done-bar). -**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. +Pin this protocol by **tag or commit** (never floating `main` as a live fetch): ---- +```bash +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 +# edit .aap/map.yaml — then work from YOUR repo, not /tmp/aap +``` -## Core ideas (short) +Details: [`cookbook/schema-pinning.md`](./cookbook/schema-pinning.md), [`cookbook/brownfield-init.md`](./cookbook/brownfield-init.md). -| 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 | +Init tooling (if you add any) MUST be explicit, additive, dry-run capable, human-reviewed — **never** silent overwrite of existing files. -### `write` is not security +--- -```yaml -# Coordination hint only — NOT access control / sandboxing. -write: [maintainer] +## Core vs profile (don’t mix them up) + +```mermaid +flowchart TB + subgraph core [CORE — required for Orientation] + C1[Map v2: workspace / self / nodes / layout] + C2[Disclosure law L0 → L3] + C3[Artifact envelope only if you claim Artifact addressability] + end + subgraph prof [PROFILES — optional cookbook] + P1[Stream packs · orientation · done-bar] + P2[Hub-umbrella teaching · schema-pinning] + P3[Orchestrator / glass-box patterns — no harness required] + end + core -.->|do not promote into L0| prof ``` -AAP **cannot** prevent a human or agent from writing outside these paths. Real enforcement requires Git permissions, CODEOWNERS, host policy, or a runtime sandbox. +| Layer | Required for Orientation? | +|-------|---------------------------| +| Map v2 + disclosure law | **Yes** | +| Artifact envelope | Only if claiming Artifact addressability | +| Stream packs / accept bars / orientation cards | **No** | +| Thin runtime dispatcher (`AGENTS.md`-style) | **No** | +| Multi-agent “teams” runtimes | **No** (one way to implement orchestrator shape) | + +**`write` / `access` are coordination hints, not security.** Real enforcement = Git permissions, CODEOWNERS, host policy, sandbox. + +--- -If no active mutating mode is **explicitly** provided by the user/runtime, the default is **no write grant** (read/orient only). +## Core vocabulary (short) -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). +| Term | Meaning | +|------|---------| +| **Map** | Sparse description of the opened workspace | +| **Node** | Direct hop to a related repo/product | +| **Layout key** | `code`, `tests`, `artifacts`, `scratch`, … → path(s); extensions allowed | +| **resourceRef** | Path string or `{ path, access?, description? }` (default access `read-write`) | +| **Artifact** | Optional durable note (historical envelope separately versioned) | +| **Profile** | Optional named elaboration — never mandatory L0 | -External / cross-repo nodes are schema-compatible direct navigation hops; their write policy is deployment-specific. +Layout keys are **not** a natural-language task classifier. “Modernize the API” is chosen by the human/agent; AAP only says where `code` / `tests` live. Full rules: [`SPEC.md`](./SPEC.md). @@ -161,12 +213,10 @@ Full rules: [`SPEC.md`](./SPEC.md). | 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 | - -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. +| **Orientation** | Discoverable sparse map; layout-based discovery possible | +| **Artifact** | Durable notes use the envelope field set when claiming addressability | +| **Topology** | Honest direct nodes and paths | +| **Disclosure profile** *(optional)* | Streams / accept / thin orientation — **not** required for Orientation | ```bash pip install pyyaml jsonschema @@ -175,42 +225,50 @@ python scripts/validate.py --- -## Relationship to consumer repos +## What’s in this repository -| 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) | +```text +README.md ← you are here +SPEC.md # Map v2 Core (on demand — not L0) +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 +``` -Pin by **tag or commit**. Do not treat `main` as a live runtime dependency. +**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). --- -## Experiment before you expand - -```text -A) agent without map -B) agent with map only (no SPEC dump) -``` +## Upstream vs your product repo -If B does not improve time-to-locus / wrong-home rate, **shrink** the map — do not add schemas and profiles first. +| This repo | Your repo | +|-----------|-----------| +| Spec + templates + examples | **Pinned** tag/commit (e.g. `v0.2.1-prototype`) | +| Evolves via tags | Local map + optional local profiles | +| Not fetched every agent turn | L0 = **local** map only | -Only after B helps, try optional profiles (one stream pack, hub umbrella, accept bar). +```mermaid +flowchart LR + U[gitpash/agent-artifact-protocol
pin v0.2.1-prototype] -.->|copy templates once| Y[Your repo
.aap/map.yaml] + Y --> AG[Agent session] + AG --> Y +``` --- ## 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 **plus** a dogfood-informed **cookbook prototype**. Useful in multi-repo pilots. **Not** production infrastructure or a finished interoperability standard. Profiles do not make Core “stable.” -Feedback is especially welcome on: +Map v2 landed in the `0.2.0-draft` lineage; this tag documents optional profiles on **that same Core** (schema required fields unchanged). v1 lives under `legacy/v1/`. -- 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 welcome: 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; prefer changes that keep L0 small. From 570e05324b9ca3c5befddd1410eb63d59bb9a0dc Mon Sep 17 00:00:00 2001 From: Pavel Luzanov Date: Fri, 16 Oct 2026 18:33:23 +0900 Subject: [PATCH 2/4] =?UTF-8?q?docs(readme):=20apply=20review=20=E2=80=94?= =?UTF-8?q?=20diagram=20honesty=20+=20section=20order?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Honest without-map path (AGENTS/wiki/grep); AAP vs AGENTS one-liner - L0–L3: optional L2; profile side branch not between L0/L1 - Profiles: work then done-bar at exit - Core vs profile: envelope conditional; no ambiguous promote arrow - Problem table: fake confidence = done-bar profile - self.parent in map sample + vocabulary (schema-backed) - Reorder: Core → 60s start → hub → profiles; drop pin diagram - Soften bet; link MOTIVATION; slim status/header --- README.md | 257 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 133 insertions(+), 124 deletions(-) diff --git a/README.md b/README.md index a9c6f17..2765dcf 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,45 @@ # Agent Artifact Protocol (AAP) **Version:** 0.2.1-prototype -**Status:** experimental Map v2 Core + dogfood-informed **optional** profiles (working-prototype **docs**) +**Status:** experimental · docs-only prototype **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`). +(Documents omit the `v` prefix: `0.2.1-prototype`.) > **AAP makes repository context addressable without requiring repository context to be loaded.** -AAP is a **runtime-agnostic filesystem convention**: a tiny map in the repo so agents (and humans) can **find the right place** without dumping CLAUDE/SPEC/wiki into the prompt. +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. -It is **not** a context engine, RAG stack, agent harness, security sandbox, or mandatory preload pack. +| AAP is | AAP is not | +|--------|------------| +| Sparse **map** + progressive disclosure | Context engine / RAG | +| Optional **profiles** in the cookbook | Agent harness or multi-agent runtime | +| Coordination hints (`write` / `access`) | Security sandbox or ACL | +| Pinned templates you copy once | Something fetched every agent turn | + +**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. --- ## What problem is this for? -Coding agents waste turns on **orientation failure** and **context pollution**: +Coding agents often fail on **orientation** and **context pollution**, not on “missing a wiki page.” -| Failure | What happens | -|---------|----------------| -| Wrong home | Edits land in the wrong package, service, or “docs that look related” | -| Preload bloat | Session starts by reading constitutions, full catalogs, every submodule map | -| No GPS | Multi-repo / monorepo: path ≠ GitHub name; nobody knows the hop | -| Fake confidence | “PR ready” with red CI or blockers invented without evidence | +| 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: **a sparse map + progressive disclosure** beats a bigger prompt. +**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 AAP] - A[Agent starts] --> B[Dump CLAUDE / wiki / all maps] + subgraph before [Without a map] + A[Agent starts] --> B["Read AGENTS.md / wiki,
grep around"] B --> C[Guess locus] - C --> D[Wrong home or token blow-up] + C --> D[Wrong home or wasted turns] end subgraph after [With AAP] @@ -60,47 +67,81 @@ self: id: my-app kind: repository path: . + # parent: # optional — see vocabulary + # id: my-hub + # path: ../.. # or map.path hop; navigation only layout: code: src/ tests: tests/ - artifacts: docs/artifacts/ # optional durable notes - scratch: docs/scratch/ # optional throwaway notes -nodes: [] # or direct hops to related repos + artifacts: docs/artifacts/ # optional durable notes + scratch: docs/scratch/ # optional throwaway notes +nodes: [] # or direct hops to related repos ``` | Piece | Role | |-------|------| | **workspace / self** | What you opened | -| **layout** | Vocabulary keys (`code`, `tests`, `artifacts`, `scratch`, …) → directories | -| **nodes** | Direct **navigation hops** (related repos/products) — not a dependency graph | -| **resourceRef** | Path string or `{ path, access?, description? }` (`access: read-only` = coordination fence, not ACL) | +| **self.parent** | Optional **one** navigation/container pointer (no ownership, auth, or recursive preload) | +| **layout** | Keys (`code`, `tests`, `artifacts`, `scratch`, …) → directories | +| **nodes** | Direct **navigation hops** — not a dependency graph | +| **resourceRef** | Path string or `{ path, access?, description? }` (`access: read-only` = coordination fence, **not** ACL) | + +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 (do not load the universe) +### 2. Progressive disclosure ```mermaid flowchart TD - L0["L0 — Map only
Orientation conformance"] + L0["L0 — Map only
(Orientation conformance)"] L1["L1 — One layout path or node hop"] - L2["L2 — One durable artifact if needed"] - L3["L3 — Code + grep / LSP / indexes
outside AAP"] + L2["L2 — One durable artifact"] + L3["L3 — Code + grep / LSP / indexes
(outside AAP)"] - L0 --> L1 --> L2 --> L3 + L0 --> L1 + L1 --> L3 + L1 -.->|only if durable memory is needed| L2 + L2 -.-> L3 - P["Optional profile bootstrap
thin orientation + exactly one stream pack"] - L0 -.-> P - P -.-> L1 + subgraph side [Optional profile — never part of L0] + P["Local orientation card +
exactly one stream pack"] + end ``` | Level | What | When | |-------|------|------| -| **L0** | Map only | Session start | -| **L1** | Targeted path / layout index | After choosing a key or node | -| **L2** | One artifact | Durable memory needed | +| **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. -### 3. Multi-repo: hop, don’t preload +Full rules: [`SPEC.md`](./SPEC.md). + +--- + +## 60-second start (brownfield) + +1. Copy [`templates/minimal-map.yaml`](./templates/minimal-map.yaml) → `.aap/map.yaml`. +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: **no map** vs **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. + +```bash +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 +# edit .aap/map.yaml — work from YOUR repo, not /tmp/aap +``` + +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 @@ -111,20 +152,21 @@ flowchart TB N2 --> C2["Child map optional"] ``` -Nodes are **doors**, not “git clone everything into context.” -See [`cookbook/hub-umbrella.md`](./cookbook/hub-umbrella.md) and [`examples/hub-umbrella/`](./examples/hub-umbrella/). +Nodes are **doors**, not “load every submodule into context.” +[`cookbook/hub-umbrella.md`](./cookbook/hub-umbrella.md) · [`examples/hub-umbrella/`](./examples/hub-umbrella/). -### 4. Optional profiles (not Core L0) +--- + +## Optional profiles (not Core L0) 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 --> D[done-bar at exit] - M --> W[work] - D --> W + M["Map (L0)"] --> O["orientation.md
thin card"] + O --> S["One stream pack
research / feature / …"] + S --> W[Work] + W --> D["Done-bar
at exit"] ``` | Profile | Cookbook | @@ -134,115 +176,89 @@ flowchart LR | 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 here) | [`glass-box-factory.md`](./cookbook/glass-box-factory.md) | +| Glass-box factory *pattern* (no CLI in this repo) | [`glass-box-factory.md`](./cookbook/glass-box-factory.md) | -Templates: [`templates/orientation.md`](./templates/orientation.md), [`templates/stream-pack.yaml`](./templates/stream-pack.yaml). +Stubs: [`templates/orientation.md`](./templates/orientation.md), [`templates/stream-pack.yaml`](./templates/stream-pack.yaml). --- -## 60-second start (brownfield) - -1. Copy [`templates/minimal-map.yaml`](./templates/minimal-map.yaml) → `.aap/map.yaml` (or `map.yaml` / `docs/map.yaml`). -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: **no map** vs **map only**. If map doesn’t help → **shrink**, don’t add profiles. -5. Only then optional profiles (hub / streams / done-bar). - -Pin this protocol by **tag or commit** (never floating `main` as a live fetch): - -```bash -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 -# edit .aap/map.yaml — then work from YOUR repo, not /tmp/aap -``` - -Details: [`cookbook/schema-pinning.md`](./cookbook/schema-pinning.md), [`cookbook/brownfield-init.md`](./cookbook/brownfield-init.md). - -Init tooling (if you add any) MUST be explicit, additive, dry-run capable, human-reviewed — **never** silent overwrite of existing files. - ---- - -## Core vs profile (don’t mix them up) +## Core vs profile ```mermaid flowchart TB - subgraph core [CORE — required for Orientation] - C1[Map v2: workspace / self / nodes / layout] - C2[Disclosure law L0 → L3] - C3[Artifact envelope only if you claim Artifact addressability] + subgraph core ["CORE — required for Orientation"] + C1["Map v2: workspace / self / nodes / layout"] + C2["Disclosure law L0 → L3"] end - subgraph prof [PROFILES — optional cookbook] - P1[Stream packs · orientation · done-bar] - P2[Hub-umbrella teaching · schema-pinning] - P3[Orchestrator / glass-box patterns — no harness required] + + 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 - core -.->|do not promote into L0| prof + + core ~~~ cond + cond ~~~ prof ``` -| Layer | Required for Orientation? | -|-------|---------------------------| -| Map v2 + disclosure law | **Yes** | -| Artifact envelope | Only if claiming Artifact addressability | -| Stream packs / accept bars / orientation cards | **No** | -| Thin runtime dispatcher (`AGENTS.md`-style) | **No** | -| Multi-agent “teams” runtimes | **No** (one way to implement orchestrator shape) | +| Also remember | | +|---------------|--| +| **`write` / `access`** | Coordination hints, **not** security. Enforcement = Git / CODEOWNERS / host / sandbox. | +| **Thin dispatcher** (`AGENTS.md`-style bootstrap) | Profile / runtime policy — not Core MUST. | +| **Multi-agent “teams”** | One possible impl of orchestrator shape — not required. | -**`write` / `access` are coordination hints, not security.** Real enforcement = Git permissions, CODEOWNERS, host policy, sandbox. +Default with no explicit mutating mode: **read/orient only** (no write grant). --- -## Core vocabulary (short) +## Vocabulary and conformance | Term | Meaning | |------|---------| | **Map** | Sparse description of the opened workspace | | **Node** | Direct hop to a related repo/product | -| **Layout key** | `code`, `tests`, `artifacts`, `scratch`, … → path(s); extensions allowed | -| **resourceRef** | Path string or `{ path, access?, description? }` (default access `read-write`) | -| **Artifact** | Optional durable note (historical envelope separately versioned) | -| **Profile** | Optional named elaboration — never mandatory L0 | - -Layout keys are **not** a natural-language task classifier. “Modernize the API” is chosen by the human/agent; AAP only says where `code` / `tests` live. - -Full rules: [`SPEC.md`](./SPEC.md). - ---- - -## Conformance (lightweight) - -| Label | Means | -|-------|--------| +| **self.parent** | Optional single navigation/container pointer (see SPEC) | +| **Layout key** | `code`, `tests`, `artifacts`, `scratch`, … → path(s) | +| **resourceRef** | Path string or `{ path, access?, description? }` | +| **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** | Durable notes use the envelope field set when claiming addressability | +| **Artifact** | Envelope field set when claiming addressability | | **Topology** | Honest direct nodes and paths | -| **Disclosure profile** *(optional)* | Streams / accept / thin orientation — **not** required for Orientation | +| **Disclosure profile** *(optional)* | Streams / accept / thin orientation — not required for Orientation | ```bash pip install pyyaml jsonschema python scripts/validate.py ``` +This is a **convention + schemas**, not a complete cross-file protocol suite. + --- ## What’s in this repository ```text -README.md ← you are here -SPEC.md # Map v2 Core (on demand — not L0) -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 +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 ``` **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). +[`cookbook/what-not-to-copy.md`](./cookbook/what-not-to-copy.md). + +Init tooling, if you add any elsewhere, MUST be explicit, additive, dry-run capable, and human-reviewed — never silent overwrite ([`CONTRIBUTING.md`](./CONTRIBUTING.md), [`SPEC.md`](./SPEC.md)). --- @@ -254,21 +270,14 @@ See [`cookbook/what-not-to-copy.md`](./cookbook/what-not-to-copy.md). | Evolves via tags | Local map + optional local profiles | | Not fetched every agent turn | L0 = **local** map only | -```mermaid -flowchart LR - U[gitpash/agent-artifact-protocol
pin v0.2.1-prototype] -.->|copy templates once| Y[Your repo
.aap/map.yaml] - Y --> AG[Agent session] - AG --> Y -``` - --- ## Status -**`0.2.1-prototype`** = experimental Map v2 Core **plus** a dogfood-informed **cookbook prototype**. Useful in multi-repo pilots. **Not** production infrastructure or a finished interoperability standard. Profiles do not make Core “stable.” +**`0.2.1-prototype`** = experimental Map v2 Core **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 landed in the `0.2.0-draft` lineage; this tag documents optional profiles on **that same Core** (schema required fields unchanged). v1 lives under `legacy/v1/`. +Map v2 rules come from the `0.2.0-draft` lineage; this tag adds prototype **docs** on that Core (required schema fields unchanged). v1: `legacy/v1/`. -Feedback welcome: map size, layout-key granularity, cross-runtime use without preload, whether Core is still too large, whether profiles stay 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. -[`CONTRIBUTING.md`](./CONTRIBUTING.md) · [`CHANGELOG.md`](./CHANGELOG.md) · Issues/PRs welcome; prefer changes that keep L0 small. +[`CONTRIBUTING.md`](./CONTRIBUTING.md) · [`CHANGELOG.md`](./CHANGELOG.md) · Issues/PRs welcome; keep L0 small. From bdd67f3bdbe300d27c47320e13282e8398559e99 Mon Sep 17 00:00:00 2001 From: Pavel Luzanov Date: Fri, 16 Oct 2026 18:36:46 +0900 Subject: [PATCH 3/4] =?UTF-8?q?docs(readme):=20finish=20review=20nits=20?= =?UTF-8?q?=E2=80=94=20access/write,=20diagrams,=20pin,=20scope?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Define access (path fence) vs write (node role hints) from schema/SPEC - Status: docs + schema + validator; drop orphan mutating-mode line - L0–L3: L0 -.-> optional profile; hub: child -.->|self.parent| hub - Core vs profile: node ~~~ links (C2/C3/P1) - A/B labels; pin comment in map copy snippet - Topology wording; drop duplicate upstream table; init → CONTRIBUTING link --- README.md | 97 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 51 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 2765dcf..db79c06 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Agent Artifact Protocol (AAP) **Version:** 0.2.1-prototype -**Status:** experimental · docs-only 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`.) @@ -14,7 +14,7 @@ AAP is a **runtime-agnostic filesystem convention**: a tiny map in the repo so a |--------|------------| | Sparse **map** + progressive disclosure | Context engine / RAG | | Optional **profiles** in the cookbook | Agent harness or multi-agent runtime | -| Coordination hints (`write` / `access`) | Security sandbox or ACL | +| Path **`access`** fences + optional node **`write`** role hints (coordination only) | Security sandbox or ACL | | Pinned templates you copy once | Something fetched every agent turn | **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. @@ -69,22 +69,30 @@ self: path: . # parent: # optional — see vocabulary # id: my-hub - # path: ../.. # or map.path hop; navigation only + # path: ../.. # navigation only layout: code: src/ tests: tests/ - artifacts: docs/artifacts/ # optional durable notes - scratch: docs/scratch/ # optional throwaway notes -nodes: [] # or direct hops to related repos + artifacts: + - path: docs/artifacts/ + access: read-write # path fence (default if omitted) + scratch: docs/scratch/ +nodes: + - id: orders-api + kind: repository + path: services/orders + # access: read-only # path fence on the hop + # write: [domain] # optional role hint — 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`, …) → directories | +| **self.parent** | Optional **one** navigation/container pointer (no ownership, auth, or recursive preload). Already in Map v2 schema/SPEC. | +| **layout** | Keys (`code`, `tests`, `artifacts`, `scratch`, …) → `resourceRef`(s) | | **nodes** | Direct **navigation hops** — not a dependency graph | -| **resourceRef** | Path string or `{ path, access?, description? }` (`access: read-only` = coordination fence, **not** ACL) | +| **resourceRef.`access`** | `read-only` \| `read-write` on a **path** (string shorthand ≡ `read-write`). Coordination fence, **not** OS/Git/IAM. Write-home for a layout key = first ref whose access is not `read-only`. | +| **node.`write`** | Optional 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. @@ -96,15 +104,13 @@ flowchart TD 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 - - subgraph side [Optional profile — never part of L0] - P["Local orientation card +
exactly one stream pack"] - end + L0 -.->|optional — never part of L0| P ``` | Level | What | When | @@ -122,22 +128,27 @@ Full rules: [`SPEC.md`](./SPEC.md). ## 60-second start (brownfield) -1. Copy [`templates/minimal-map.yaml`](./templates/minimal-map.yaml) → `.aap/map.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: **no map** vs **map only**. If B does not help → **shrink the map**, do not add profiles. +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. +**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 && cp /tmp/aap/templates/minimal-map.yaml .aap/map.yaml +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 ``` -More detail: [`cookbook/schema-pinning.md`](./cookbook/schema-pinning.md), [`cookbook/brownfield-init.md`](./cookbook/brownfield-init.md). +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). --- @@ -148,8 +159,10 @@ 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
self.parent → hub"] + 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.” @@ -201,17 +214,17 @@ flowchart TB P3["Orchestrator / glass-box patterns"] end - core ~~~ cond - cond ~~~ prof + C2 ~~~ C3 + C3 ~~~ P1 ``` -| Also remember | | -|---------------|--| -| **`write` / `access`** | Coordination hints, **not** security. Enforcement = Git / CODEOWNERS / host / sandbox. | -| **Thin dispatcher** (`AGENTS.md`-style bootstrap) | Profile / runtime policy — not Core MUST. | -| **Multi-agent “teams”** | One possible impl of orchestrator shape — not required. | - -Default with no explicit mutating mode: **read/orient only** (no write grant). +| Field / policy | Meaning | +|----------------|---------| +| **`access`** (on `resourceRef` / node path) | Path coordination fence: `read-only` \| `read-write` | +| **`write`** (on node) | Optional role **hints** only — not a filesystem grant ([SPEC](./SPEC.md)) | +| **Thin dispatcher** (`AGENTS.md`-style bootstrap) | Profile / runtime policy — not Core MUST | +| **Multi-agent “teams”** | One possible impl of orchestrator shape — not required | +| **Default agent posture** | Until the user/runtime **explicitly** enables a mutating mode, treat the session as **read/orient only** (no write grant). See [SPEC — `write` is not security](./SPEC.md). | --- @@ -221,9 +234,11 @@ Default with no explicit mutating mode: **read/orient only** (no write grant). |------|---------| | **Map** | Sparse description of the opened workspace | | **Node** | Direct hop to a related repo/product | -| **self.parent** | Optional single navigation/container pointer (see SPEC) | -| **Layout key** | `code`, `tests`, `artifacts`, `scratch`, … → path(s) | +| **self.parent** | Optional single navigation/container pointer ([SPEC](./SPEC.md) / schema) | +| **Layout key** | `code`, `tests`, `artifacts`, `scratch`, … → `resourceRef`(s) | | **resourceRef** | Path string or `{ path, access?, description? }` | +| **access** | Path fence on a ref or hop | +| **write** | Optional node role hints (not ACL) | | **Artifact** | Optional durable note (envelope when claiming addressability) | | **Profile** | Optional cookbook elaboration — never mandatory L0 | @@ -231,7 +246,7 @@ Default with no explicit mutating mode: **read/orient only** (no write grant). |-------------------|--------| | **Orientation** | Discoverable sparse map; layout-based discovery possible | | **Artifact** | Envelope field set when claiming addressability | -| **Topology** | Honest direct nodes and paths | +| **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 @@ -256,27 +271,17 @@ scripts/validate.py ``` **Intentionally absent:** product adoption guides, pilot dashboards, runtime adapters, factory/conductor CLI, mandatory multi-agent harnesses. -[`cookbook/what-not-to-copy.md`](./cookbook/what-not-to-copy.md). - -Init tooling, if you add any elsewhere, MUST be explicit, additive, dry-run capable, and human-reviewed — never silent overwrite ([`CONTRIBUTING.md`](./CONTRIBUTING.md), [`SPEC.md`](./SPEC.md)). - ---- - -## Upstream vs your product repo - -| This repo | Your repo | -|-----------|-----------| -| Spec + templates + examples | **Pinned** tag/commit (e.g. `v0.2.1-prototype`) | -| Evolves via tags | Local map + optional local profiles | -| Not fetched every agent turn | L0 = **local** map only | +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. Aimed at multi-repo pilots; **not** production infrastructure or a finished interoperability standard. Profiles do not make Core stable. +**`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 (required schema fields unchanged — including existing `self.parent`, `access`, and node `write`). v1: `legacy/v1/`. -Map v2 rules come from the `0.2.0-draft` lineage; this tag adds prototype **docs** on that Core (required schema fields unchanged). v1: `legacy/v1/`. +Upstream is pinned by **tag/commit** into your repo; L0 stays the **local** map only (see 60-second start). Feedback: map size, layout-key granularity, cross-runtime use without preload, whether Core is still too large, whether profiles stay optional in practice. From edc7b2714bc121306b9d6c671f36e55657f3f269 Mon Sep 17 00:00:00 2001 From: Pavel Luzanov Date: Fri, 16 Oct 2026 18:42:18 +0900 Subject: [PATCH 4/4] =?UTF-8?q?docs(readme):=20final=20nits=20=E2=80=94=20?= =?UTF-8?q?single=20access/write=20locus,=20posture,=20labels?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Sample map validated against map.schema.json (string+list+write[]) - Status: optional fields pre-exist; not “required fields unchanged” - access/write defined once in §1; vocab + Core-vs-profile link back - write-home one line + SPEC pointer - Default posture: runtime recommendation, not Core MUST - L0 diagram label: optional profile only - Confirm v0.2.1-prototype has minimal-map template --- README.md | 41 ++++++++++++++++++++--------------------- 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index db79c06..b2e0e5b 100644 --- a/README.md +++ b/README.md @@ -71,28 +71,29 @@ self: # id: my-hub # path: ../.. # navigation only layout: - code: src/ + code: src/ # string ≡ { path: src/, access: read-write } tests: tests/ artifacts: - path: docs/artifacts/ - access: read-write # path fence (default if omitted) + access: read-write # same resourceRef shape; list allowed scratch: docs/scratch/ nodes: - id: orders-api kind: repository path: services/orders - # access: read-only # path fence on the hop - # write: [domain] # optional role hint — not an ACL + # 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). Already in Map v2 schema/SPEC. | -| **layout** | Keys (`code`, `tests`, `artifacts`, `scratch`, …) → `resourceRef`(s) | +| **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.`access`** | `read-only` \| `read-write` on a **path** (string shorthand ≡ `read-write`). Coordination fence, **not** OS/Git/IAM. Write-home for a layout key = first ref whose access is not `read-only`. | -| **node.`write`** | Optional deployment-defined **role hints** (e.g. `domain`). Separate from `access`; does **not** grant filesystem permission ([SPEC](./SPEC.md)). | +| **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. @@ -110,7 +111,7 @@ flowchart TD L1 --> L3 L1 -.->|only if durable memory is needed| L2 L2 -.-> L3 - L0 -.->|optional — never part of L0| P + L0 -.->|optional profile| P ``` | Level | What | When | @@ -218,13 +219,13 @@ flowchart TB C3 ~~~ P1 ``` -| Field / policy | Meaning | -|----------------|---------| -| **`access`** (on `resourceRef` / node path) | Path coordination fence: `read-only` \| `read-write` | -| **`write`** (on node) | Optional role **hints** only — not a filesystem grant ([SPEC](./SPEC.md)) | +| 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 agent posture** | Until the user/runtime **explicitly** enables a mutating mode, treat the session as **read/orient only** (no write grant). See [SPEC — `write` is not security](./SPEC.md). | +| **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). --- @@ -234,11 +235,9 @@ flowchart TB |------|---------| | **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) / schema) | -| **Layout key** | `code`, `tests`, `artifacts`, `scratch`, … → `resourceRef`(s) | -| **resourceRef** | Path string or `{ path, access?, description? }` | -| **access** | Path fence on a ref or hop | -| **write** | Optional node role hints (not ACL) | +| **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 | @@ -279,9 +278,9 @@ See [`cookbook/what-not-to-copy.md`](./cookbook/what-not-to-copy.md). For init-t **`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 (required schema fields unchanged — including existing `self.parent`, `access`, and node `write`). v1: `legacy/v1/`. +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/`. -Upstream is pinned by **tag/commit** into your repo; L0 stays the **local** map only (see 60-second start). +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: map size, layout-key granularity, cross-runtime use without preload, whether Core is still too large, whether profiles stay optional in practice.