From cf7730bac21fdf20b54f7c1154600f2627a22e35 Mon Sep 17 00:00:00 2001 From: Pavel Luzanov Date: Wed, 28 Oct 2026 19:19:20 +0900 Subject: [PATCH 01/10] Add llms.txt, aap-map skill, plugin manifests and README agent section Co-Authored-By: Claude Sonnet 5.5 --- .claude-plugin/marketplace.json | 12 ++ .claude-plugin/plugin.json | 9 + CHANGELOG.md | 5 +- README.md | 28 ++- llms.txt | 77 +++++++++ scripts/validate.py | 6 + skills/aap-map/SKILL.md | 168 ++++++++++++++++++ skills/aap-map/TEST-NOTES.md | 38 +++++ skills/aap-map/schema/map.schema.json | 225 +++++++++++++++++++++++++ skills/aap-map/scripts/validate_map.py | 117 +++++++++++++ 10 files changed, 683 insertions(+), 2 deletions(-) create mode 100644 .claude-plugin/marketplace.json create mode 100644 .claude-plugin/plugin.json create mode 100644 llms.txt create mode 100644 skills/aap-map/SKILL.md create mode 100644 skills/aap-map/TEST-NOTES.md create mode 100644 skills/aap-map/schema/map.schema.json create mode 100644 skills/aap-map/scripts/validate_map.py diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..78363b5 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,12 @@ +{ + "name": "agent-artifact-protocol", + "description": "Skills for the Agent Artifact Protocol (AAP)", + "owner": { "name": "gitpash" }, + "plugins": [ + { + "name": "aap", + "source": "./", + "description": "aap-map: draft and validate 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..6deb31a --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "aap", + "version": "0.2.1", + "description": "Agent Artifact Protocol tooling: the aap-map skill drafts and validates a minimal .aap/map.yaml for any repository.", + "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..ba28543 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,10 @@ ## Unreleased -(nothing yet) +- `llms.txt`: agent-readable entry point (what AAP is, what to open first, `access` rules, links). +- `skills/aap-map/`: portable agent skill that drafts and validates a minimal map, with `scripts/validate_map.py` and a bundled copy of the Map v2 schema. +- `.claude-plugin/` manifests and a README section "Use with your agent". Nothing is published to any registry. +- `scripts/validate.py` checks that the bundled schema copy matches `schemas/map.schema.json` and that plugin manifests parse. ## 0.2.1-prototype — 2026-10-16 diff --git a/README.md b/README.md index 650e06b..2c9e016 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,30 @@ The map is checked against **JSON Schema by a validator in CI**, so structure dr --- +## Use with your agent + +**Give your LLM one link.** [`llms.txt`](./llms.txt) is written for an agent to read: what AAP is, what to open first, and the `access` rules. + +```text +https://raw.githubusercontent.com/gitpash/agent-artifact-protocol/main/llms.txt +``` + +Paste that into any chat or agent session and ask it to explain AAP or to work in a repo that has an `.aap/map.yaml`. It points to the spec and schema only for when they are needed. + +**Add a map to your own project with the `aap-map` skill.** The skill in [`skills/aap-map/`](./skills/aap-map/SKILL.md) drafts a minimal `.aap/map.yaml` for any codebase, validates it against the bundled schema, and marks anything it could not verify with `# REVIEW:` comments for you to check. It never overwrites an existing map. Install it as a plain skill folder: + +```bash +# Claude Code, user-level +git clone --depth 1 https://github.com/gitpash/agent-artifact-protocol.git /tmp/aap +cp -R /tmp/aap/skills/aap-map ~/.claude/skills/aap-map +``` + +Then ask your agent: *"use the aap-map skill to add an AAP map to this repo"*. Validation needs `pip install pyyaml jsonschema` (or `uv run --with pyyaml --with jsonschema`). + +Package layouts for skill installers and the Claude Code plugin marketplace (`.claude-plugin/`) are included in the repo, but the skill is not listed in any registry yet. + +--- + ## What problem is this for? Coding agents often fail on **orientation** and **context pollution**, not on “missing a wiki page.” @@ -286,7 +310,9 @@ This is a **convention + schemas**, not a complete cross-file protocol suite. ## What’s in this repository ```text -README.md SPEC.md MOTIVATION.md CONTRIBUTING.md CHANGELOG.md +README.md SPEC.md MOTIVATION.md CONTRIBUTING.md CHANGELOG.md llms.txt +skills/aap-map/ # portable agent skill + validator + bundled schema copy +.claude-plugin/ # plugin + marketplace manifests (not published) schemas/ # Map v2 JSON Schema legacy/v1/ # historical zones map templates/ # minimal-map, orientation, stream-pack, artifacts diff --git a/llms.txt b/llms.txt new file mode 100644 index 0000000..1c100de --- /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.2.1-prototype (experimental). Pin the tag `v0.2.1-prototype`; 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.2.1-prototype/SPEC.md +- Map JSON Schema (draft-07): https://raw.githubusercontent.com/gitpash/agent-artifact-protocol/v0.2.1-prototype/schemas/map.schema.json +- Starter map: https://raw.githubusercontent.com/gitpash/agent-artifact-protocol/v0.2.1-prototype/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 (SKILL.md plus a validator and a bundled copy of the schema). It drafts a minimal map for any codebase, validates it against the schema, and marks uncertain nodes for human review. Install paths are described in the README section "Use with your agent". + +## 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.2.1-prototype/MOTIVATION.md +- Changelog: https://github.com/gitpash/agent-artifact-protocol/blob/v0.2.1-prototype/CHANGELOG.md +- License: MIT diff --git a/scripts/validate.py b/scripts/validate.py index 66591bd..7136322 100644 --- a/scripts/validate.py +++ b/scripts/validate.py @@ -59,6 +59,12 @@ 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") + bundled = ROOT / "skills" / "aap-map" / "schema" / "map.schema.json" + if bundled.exists() and load_json(bundled) != map_schema: + die("skills/aap-map/schema/map.schema.json differs from schemas/map.schema.json (re-copy it)") + 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") diff --git a/skills/aap-map/SKILL.md b/skills/aap-map/SKILL.md new file mode 100644 index 0000000..fb3259a --- /dev/null +++ b/skills/aap-map/SKILL.md @@ -0,0 +1,168 @@ +--- +name: aap-map +description: Draft, validate and review a minimal AAP (Agent Artifact Protocol) navigation map, .aap/map.yaml, for any repository. Use when the user asks to add an AAP map, create or fix .aap/map.yaml, check a map against the schema, or says "aap-map". Produces a schema-valid candidate and marks uncertain parts for human review. Not for general documentation work. +--- + +# aap-map + +Creates a small `.aap/map.yaml` (AAP Map v2) for the repository you are in, checks it against the bundled JSON Schema, and leaves anything it could not establish from evidence marked for a human. + +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. It is not a dependency graph, a search index or a permission system. + +Schema validity proves shape only. It does not prove that the paths are right or the nodes are useful. That is why this skill ends with a review step, not with "done". + +## Files in this skill + +- `schema/map.schema.json`: byte-identical copy of `schemas/map.schema.json` from the AAP repo at tag `v0.2.1-prototype`. If the two ever differ, the repo copy wins. +- `scripts/validate_map.py`: validator. Needs PyYAML and jsonschema. + +Resolve these paths relative to this SKILL.md, not to the project you are mapping. Use the absolute path when you run the validator. + +## Rules before you write anything + +1. If `.aap/map.yaml` (or `map.yaml`, `docs/map.yaml`) already exists, do not overwrite it and do not create a second map next to it. Validate it, report, and propose a diff. Write only after the user says yes. +2. Work in the project root you were pointed at (the git top-level, if it is a git repo). If it is a subfolder of a monorepo, ask which folder is the workspace. +3. Do not edit other repositories. For a neighbor that should list this repo, give a YAML snippet and stop. +4. Do not move, rename or "tidy" any existing docs or folders to make the map look better. +5. Never put absolute or machine-specific paths into the committed map. Those belong in a gitignored `map.local.yaml`. + +## Procedure + +### 1. Discover (short, evidence only) + +Read, in this order, and stop as soon as you can fill the map: + +- README and any agent guidance file (`AGENTS.md`, `CLAUDE.md`, CONTRIBUTING), if present. Match file names case-insensitively. +- Top-level directory listing (one level, then one more level only for `src`-like roots). +- Build manifest (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle*`, etc.) for the project name and the source layout. +- Test config or test directories. +- Where durable notes live, if anywhere: `docs/`, `doc/`, `adr/`, `docs/adr/`, `rfcs/`. +- `.gitmodules`, and workspace definitions (`pnpm-workspace.yaml`, `workspaces` in `package.json`, `[tool.uv.workspace]`, `go.work`, Cargo `[workspace]`), if present. +- Endpoints, client config or generated clients that point at other repositories, when the README mentions them. + +Record what you saw as evidence for each key you add. If you cannot point at evidence, do not add the key. + +### 2. Draft the map + +Shape (Map v2). Use block style and quote every description (a bare comma, colon or `#` inside a flow-style value splits it and the validator then reports a confusing "additional properties" error): + +```yaml +version: 2 +workspace: + id: + description: "" +self: + id: + kind: repository + path: . +layout: + code: + tests: +nodes: [] +``` + +Rules for each part: + +- **ids** (`workspace.id`, `self.id`, node ids): lowercase letters, digits and hyphens, must start with a letter. Slugify the repository name: lowercase, replace `_`, `.` and spaces with `-`, and add a short letter prefix only if it starts with a digit (`My_App` becomes `my-app`, `3d-viewer` becomes `app-3d-viewer`). Never reorder words. Mention every change in the report. `workspace.id` and `self.id` may be the same. +- **layout**: include only keys with evidence. `code` and `tests` usually, after confirming with `ls` that the folders exist; `artifacts` only for a folder of durable working notes (ADRs, decisions, specs), not for published user documentation such as a docs website, and only if it already exists or the user wants one (then list the path, say in the report that you did not create it, and expect a validator WARN); `scratch` only if the project already has one. A monorepo with a few code roots uses a list: `code: [packages/a/src/, packages/b/src/]`. With many packages (roughly more than five) use the parent folder (`packages/`) and add a REVIEW comment; do not use globs, the schema treats paths literally. If tests sit next to the code and there is no tests folder, omit `tests`; do not pick the nearest folder that merely looks like tests. If a vendored or generated subfolder sits inside a code root, keep the root and add a REVIEW comment; splitting it needs a separate `read-only` entry and is the human's call. Extension keys such as `scripts` or `infra` are optional; add one only if the folder is something an agent would plausibly be sent to, and prefer fewer keys. Omit a key rather than point it at a path that does not exist. +- **access**: default is `read-write`, so leave it out. Add `{ path, access: read-only }` only when the repo says so: a README or contributing note, CODEOWNERS, a `.gitattributes` generated/vendored entry, or a header comment in the folder. A folder name alone is not evidence. If you are guessing, do not mark it; put a REVIEW comment instead. Never invent other fields on paths. +- **description**: one line each for the workspace and for every node. Descriptions are for humans. +- **nodes**: see admission below. An empty `nodes: []` is a normal, valid answer for a standalone repository. +- Skip `relations`, `overlays`, `profiles`, `mirror`, `write` unless the user asks for them. They are optional and make the L0 file bigger. + +### 3. Node admission + +A node is a direct navigation hop: another repository or product someone is likely to open during a normal change here. Admit a candidate only if you can state one reason and point at local evidence: + +| Reason | Evidence in this repo | +|---|---| +| calls it at runtime | client, endpoint or env/config naming the other service | +| owns a contract this repo consumes | schema, API definition, generated client, shared types sourced from it | +| current reference | design source, requirements or spec repo that the README names as the source of truth | +| intentionally shared convention | maintained import or sync workflow, not a one-time copy | + +Do not admit something because it is mentioned in a README, is a transitive dependency, is a package manager dependency (third-party libraries are not nodes), was a one-time scaffold source, or is only conceptually related. Put such context in the README instead. + +For a node you do admit: + +- `kind`: `repository` for another repo you could check out, `external` for something you only read about. `kind` is free text; use these two unless the project has its own word. +- `locator.repo` or `locator.url` only with a value copied verbatim from `.gitmodules`, a git remote, the README or client config. If the repo does not state it, omit `locator` and add a REVIEW comment. Never guess an organization or host. A different branch or fork of this same repository is not a node. `path` only if it is checked out inside this tree (submodule, vendored folder). +- `map.path: .aap/map.yaml` only if you saw that file in that repository. Otherwise omit `map`. +- For `external` or consume-only hops add `access: read-only`. +- `description`: what is consulted there and when. + +Workspace roots made of several packages in one repository: do not create one node per package by default. Use `layout.code` as a list. Add nodes for packages only if the user wants per-package maps. + +### 4. Mark uncertainty + +You cannot ask the schema about uncertainty, and the schema forbids unknown fields, so use YAML comments. Put `# REVIEW:` directly above or beside every line you are not sure about, with the reason: + +```yaml +layout: + code: src/ + # REVIEW: tests live in both tests/ and src/**/__tests__; only tests/ listed + tests: tests/ +nodes: + # REVIEW: only a README mention, no client config found. Remove if not a normal-change hop. + - id: billing-service + kind: external + access: read-only +``` + +Edit the file textually. Do not load it into a YAML library and dump it back, which deletes comments. Keep REVIEW comments for uncertainty only; put plain notes in your report. Mark for review at minimum: every node, every `read-only` you chose, any layout path you could not verify exists, any slugified id, any key where two folders competed. + +### 5. Validate + +```bash +python3 /absolute/path/to/aap-map/scripts/validate_map.py .aap/map.yaml +``` + +(On Windows use `py -3` instead of `python3`.) + +If PyYAML or jsonschema are missing, either `pip install pyyaml jsonschema` (inside a virtualenv, not system-wide) or run `uv run --with pyyaml --with jsonschema python3 /absolute/path/to/aap-map/scripts/validate_map.py .aap/map.yaml`. Do not install packages into the project's own environment without asking. + +Output contract: + +```text +VALIDATION_SUCCESS +WARN ... (zero or more; informational) +REVIEW_MARKERS N (lines ...) +# or +VALIDATION_FAILED +- path: /nodes/0/id | message: ... +``` + +On failure, patch the file from the path and message and run again. Stop after 5 rounds and report what is still failing. Do not weaken the schema or edit the bundled copy to make a map pass. + +If Python is not available at all, report "validation NOT RUN" and never call the map valid. Self-check the rules above (id pattern, no absolute paths, no `..`, quoted descriptions) and show the user the one command to run later. + +### 6. Hand over for review + +Do not claim the map is done. End with this report, plainly: + +```text +## aap-map result +- file: .aap/map.yaml (new | unchanged | proposed diff) +- validation: PASS | FAIL | NOT RUN (why) +- layout keys: (each with the evidence you used) +- nodes accepted: N (id, reason) / candidates rejected: N (name as seen in the repo, why; list only candidates you actually saw) +- REVIEW markers: N (list the lines) +- ids changed by slugifying: +- needs a human decision: +``` + +If the user asked for machine-local overlays, put them in a sibling `map.local.yaml` next to the map and add it to `.gitignore` (if the project uses git). Otherwise leave `.gitignore` alone. + +## What the map must not become + +- A list of every folder. If the tree is self-explanatory, `code` and `tests` are enough. +- A dependency graph. Libraries and transitive services stay out. +- A place for procedures, conventions or essays. Those go in `AGENTS.md`, README or docs. +- A permission system. `access` is a note between humans and agents, not enforcement. +- A speculative structure. If the project has no durable notes folder, say so and leave `artifacts` out unless the user asks to create one. + +## Reading an existing map (for reference) + +- Write home for a layout key is the first entry whose access is not `read-only`. If there is none, fail closed and ask. +- `overlays` and `map.local.yaml` say where a node is checked out on this machine. They never grant write rights. +- A node `write: [...]` list is a role hint, not a permission. diff --git a/skills/aap-map/TEST-NOTES.md b/skills/aap-map/TEST-NOTES.md new file mode 100644 index 0000000..a6e1739 --- /dev/null +++ b/skills/aap-map/TEST-NOTES.md @@ -0,0 +1,38 @@ +# aap-map test notes + +Tested 2026-10-28 on three public projects of different shape, cloned shallow into a scratch directory. In each run a fresh agent received only `SKILL.md` and followed it literally, with the validator and bundled schema. A separate reviewer then read the files looking for assumptions inherited from the private convention the skill grew out of. + +| Project | Shape | Result map | Validator | REVIEW markers | Tool calls | +|---|---|---|---|---|---| +| chalk | small JS library, flat | `code: source/`, `tests: test/`, `nodes: []` | pass (after one fix) | 2 | ~12 | +| requests | Python library, `src/` layout, Sphinx docs | `code: src/requests/`, `tests: tests/`, `nodes: []` | pass (after one fix) | 0 | 5 | +| changesets | pnpm TypeScript monorepo, 21 packages | `code: packages/`, `artifacts: docs/`, extension key `site`, `nodes: []` | pass | 4 | ~7 | + +No run admitted a node. Third-party libraries and README mentions were rejected, which is the intended outcome for standalone repositories. + +## What broke or was ambiguous, and what changed + +| Finding | Seen in | Change | +|---|---|---| +| The shape example used flow style. A description containing a comma split the value and the validator reported "additional properties", naming the stray key, not the cause. | chalk, requests | Example is now block style; descriptions must be quoted. | +| `src/` versus `src/requests/` for `code` unspecified | requests | Rule: confirm with `ls`, pick the folder that holds the code. | +| 21 packages: a list of 21 paths is absurd, globs are not supported | changesets | Use the parent folder plus a REVIEW comment; no globs. | +| Tests colocated with code, no tests folder; agent guessed a nearby folder | changesets | Omit `tests` rather than guess. | +| Published docs site versus durable notes for `artifacts` | requests, changesets | `artifacts` means working notes (ADRs, decisions, specs), not a docs website. | +| Vendored folder inside the code root; unclear how to mark read-only | chalk | Keep the root, add a REVIEW comment; splitting is the human's call. | +| Branch of the same repository mentioned in the README | changesets | Not a node. | +| File lookup was case sensitive (`readme.md`) | chalk | Case-insensitive. | +| Informational notes inflated the REVIEW count | chalk | REVIEW comments are for uncertainty only; notes go in the report. | +| Rejected candidates have no id | chalk, changesets | Report them by name as seen in the repo. | +| Validator printed line numbers not in the output contract | chalk, changesets | Contract updated. | +| Extension keys (`site`, `examples`) tempt the agent to list every folder | chalk, changesets | Optional, fewer is better. | + +Reviewer findings applied: do not assume a git repo; do not guess `locator.repo` or the host; `read-only` needs written evidence, a folder name is not enough; slugify ids without reordering words; edit the map textually so comments survive; validator warns on absolute, `~`, backslash and `..` paths in `self.path`, `node.path` and `map.path` (the schema only checks layout paths); validator sort no longer crashes on mixed index and key error paths; REVIEW marker count matches only YAML comments; `python3` / `py -3` and absolute script path; honest "validation NOT RUN" fallback; do not create a second map next to an existing one. + +## Known limits + +- Tested with Claude subagents only. Other agents were not tried. +- The schema's `pathString` pattern rejects any path containing `..` even as part of a name (`a..b`). That is the schema's behavior and was left alone. +- `layout` paths are literal. There are no globs, so large monorepos get a coarse parent folder. +- The bundled schema keeps its original `$id`. A CI check in `scripts/validate.py` keeps it identical to `schemas/map.schema.json`. +- Not tested: Windows, a machine with no network and no Python, and a repository that already has a map. diff --git a/skills/aap-map/schema/map.schema.json b/skills/aap-map/schema/map.schema.json new file mode 100644 index 0000000..94ddf71 --- /dev/null +++ b/skills/aap-map/schema/map.schema.json @@ -0,0 +1,225 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://gist.githubusercontent.com/gitpash/928c100ebf269acf9db7c09a18ed4a68/raw/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.", + "type": "object", + "additionalProperties": false, + "required": ["version", "workspace", "self", "nodes"], + "properties": { + "version": { + "type": "integer", + "enum": [2], + "description": "Map format version 2 — semantic surface router. Still 2: resourceRef is additive (string paths remain valid)." + }, + "workspace": { + "type": "object", + "additionalProperties": false, + "required": ["id"], + "properties": { + "id": { "$ref": "#/$defs/id" }, + "description": { "type": "string" } + } + }, + "self": { + "type": "object", + "additionalProperties": false, + "required": ["id", "kind"], + "properties": { + "id": { "$ref": "#/$defs/id" }, + "kind": { "type": "string", "minLength": 1 }, + "path": { "type": "string", "minLength": 1 }, + "description": { "type": "string" }, + "parent": { "$ref": "#/$defs/parentObject" } + } + }, + "layout": { "$ref": "#/$defs/layoutObject" }, + "nodes": { + "type": "array", + "items": { "$ref": "#/$defs/nodeObject" } + }, + "relations": { + "type": "array", + "description": "Optional local topology hints — not a global dependency graph.", + "items": { "$ref": "#/$defs/relationObject" } + }, + "overlays": { + "type": "object", + "additionalProperties": false, + "description": "Prefer map.local.yaml (gitignored) for absolute checkout paths.", + "properties": { + "nodes": { + "type": "object", + "propertyNames": { "$ref": "#/$defs/id" }, + "additionalProperties": { + "type": "object", + "additionalProperties": false, + "properties": { + "path": { "type": "string", "minLength": 1 } + } + } + }, + "local_paths": { + "type": "object", + "propertyNames": { "$ref": "#/$defs/id" }, + "additionalProperties": { "type": "string", "minLength": 1 } + } + } + }, + "profiles": { + "type": "object", + "additionalProperties": false, + "properties": { + "enabled": { + "type": "array", + "items": { "type": "string", "minLength": 1 } + } + } + } + }, + "$defs": { + "id": { + "type": "string", + "pattern": "^[a-z][a-z0-9-]*$", + "minLength": 1 + }, + "pathString": { + "type": "string", + "minLength": 1, + "pattern": "^(?!.*\\.\\.)(?!/).*$", + "description": "Path relative to workspace root; / separators; no .. or absolute." + }, + "access": { + "type": "string", + "enum": ["read-only", "read-write"], + "description": "Shared permission class. read-only = agents MUST NOT write/create durable content here; read still allowed. Default when omitted: read-write. Human lifecycle words (legacy/deprecated) belong in description, not a separate enum." + }, + "resourceRef": { + "oneOf": [ + { "$ref": "#/$defs/pathString" }, + { + "type": "object", + "additionalProperties": false, + "required": ["path"], + "properties": { + "path": { "$ref": "#/$defs/pathString" }, + "access": { "$ref": "#/$defs/access" }, + "description": { + "type": "string", + "description": "Optional human note only. Agents gate on access, not on this text." + } + } + } + ], + "description": "Addressable path resource. String shorthand ≡ { path: , access: read-write }. Object form adds optional access (same enum as nodes)." + }, + "pathOrPaths": { + "oneOf": [ + { "$ref": "#/$defs/resourceRef" }, + { + "type": "array", + "minItems": 1, + "items": { "$ref": "#/$defs/resourceRef" } + } + ], + "description": "One resourceRef or a list. Write home = first entry whose access is not read-only (after normalize)." + }, + "layoutObject": { + "type": "object", + "description": "Intent → path router. Values are resourceRef(s). Known keys are hints; additionalProperties allowed for 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" }, + "devops": { "$ref": "#/$defs/pathOrPaths" } + }, + "additionalProperties": { "$ref": "#/$defs/pathOrPaths" } + }, + "mapPointerObject": { + "type": "object", + "additionalProperties": false, + "properties": { + "path": { "type": "string", "minLength": 1 }, + "url": { "type": "string", "minLength": 1 }, + "ref": { "type": "string", "minLength": 1 } + }, + "anyOf": [ + { "required": ["path"] }, + { "required": ["url"] } + ] + }, + "locatorObject": { + "type": "object", + "additionalProperties": false, + "properties": { + "repo": { "type": "string", "minLength": 1 }, + "url": { "type": "string", "minLength": 1 }, + "id": { "type": "string", "minLength": 1 }, + "default_branch": { "type": "string" } + }, + "anyOf": [ + { "required": ["repo"] }, + { "required": ["url"] }, + { "required": ["id"] } + ] + }, + "parentObject": { + "type": "object", + "additionalProperties": false, + "required": ["id"], + "description": "Optional immediate navigation parent. Groups the current repository for orientation; does not imply ownership, authorization, inherited policy, or recursive traversal.", + "properties": { + "id": { "$ref": "#/$defs/id" }, + "locator": { "$ref": "#/$defs/locatorObject" }, + "map": { "$ref": "#/$defs/mapPointerObject" } + } + }, + "mirrorObject": { + "type": "object", + "additionalProperties": false, + "properties": { + "path": { "type": "string", "minLength": 1 } + }, + "required": ["path"] + }, + "nodeObject": { + "type": "object", + "additionalProperties": false, + "required": ["id", "kind"], + "properties": { + "id": { "$ref": "#/$defs/id" }, + "kind": { "type": "string", "minLength": 1 }, + "description": { "type": "string" }, + "path": { "type": "string", "minLength": 1 }, + "locator": { "$ref": "#/$defs/locatorObject" }, + "map": { "$ref": "#/$defs/mapPointerObject" }, + "mirror": { "$ref": "#/$defs/mirrorObject" }, + "access": { + "$ref": "#/$defs/access", + "description": "Same permission class as resourceRef.access. External consume-only hops use read-only." + }, + "write": { + "type": "array", + "items": { "type": "string", "minLength": 1 }, + "description": "Optional role hints (e.g. domain, architect). NOT a filesystem ACL — use access for write fence. Empty/absent is not a grant by itself." + } + } + }, + "relationObject": { + "type": "object", + "additionalProperties": false, + "required": ["from", "to", "type"], + "properties": { + "from": { "$ref": "#/$defs/id" }, + "to": { "$ref": "#/$defs/id" }, + "type": { "type": "string", "minLength": 1 }, + "description": { "type": "string" } + } + } + } +} diff --git a/skills/aap-map/scripts/validate_map.py b/skills/aap-map/scripts/validate_map.py new file mode 100644 index 0000000..766c2de --- /dev/null +++ b/skills/aap-map/scripts/validate_map.py @@ -0,0 +1,117 @@ +#!/usr/bin/env python3 +"""Validate an AAP Map v2 file against the bundled JSON Schema. + +Usage: python validate_map.py [MAP] [--root DIR] [--schema FILE] + +MAP defaults to .aap/map.yaml. Exit codes: 0 valid, 1 invalid, 2 setup problem. +Needs PyYAML and jsonschema (pip install pyyaml jsonschema, or +uv run --with pyyaml --with jsonschema python validate_map.py ...). +Warnings never change the exit code; they point at things a human should check. +""" +from __future__ import annotations + +import argparse +import json +import re +import sys +from pathlib import Path + +HERE = Path(__file__).resolve().parent + + +def setup_error(message: str) -> None: + print(f"SETUP_ERROR: {message}", file=sys.stderr) + raise SystemExit(2) + + +def refs(value: object) -> list[tuple[str, bool]]: + """Return (path, writable) for a layout value.""" + items = value if isinstance(value, list) else [value] + out = [] + for item in items: + if isinstance(item, str): + out.append((item, True)) + elif isinstance(item, dict) and isinstance(item.get("path"), str): + out.append((item["path"], item.get("access", "read-write") != "read-only")) + return out + + +def main() -> None: + parser = argparse.ArgumentParser() + parser.add_argument("map", nargs="?", default=".aap/map.yaml") + parser.add_argument("--root", help="workspace root for path checks (default: parent of .aap/, else map dir)") + parser.add_argument("--schema", default=str(HERE.parent / "schema" / "map.schema.json")) + args = parser.parse_args() + + try: + import yaml + import jsonschema + except ImportError: + setup_error("PyYAML and jsonschema are required: pip install pyyaml jsonschema") + + map_path = Path(args.map) + if not map_path.is_file(): + setup_error(f"map not found: {map_path}") + schema_path = Path(args.schema) + if not schema_path.is_file(): + setup_error(f"schema not found: {schema_path}") + + text = map_path.read_text(encoding="utf-8") + try: + data = yaml.safe_load(text) + except yaml.YAMLError as error: + print("VALIDATION_FAILED") + print(f"- path: / | message: YAML does not parse: {error}") + raise SystemExit(1) + schema = json.loads(schema_path.read_text(encoding="utf-8")) + validator = jsonschema.Draft7Validator(schema) + errors = sorted(validator.iter_errors(data), key=lambda e: [str(p) for p in e.absolute_path]) + if errors: + print("VALIDATION_FAILED") + for error in errors: + pointer = "/" + "/".join(str(p) for p in error.absolute_path) + print(f"- path: {pointer} | message: {error.message[:200]}") + raise SystemExit(1) + + root = Path(args.root) if args.root else ( + map_path.resolve().parent.parent if map_path.resolve().parent.name == ".aap" else map_path.resolve().parent + ) + warnings: list[str] = [] + for key, value in (data.get("layout") or {}).items(): + entries = refs(value) + for path, _ in entries: + if not (root / path).exists(): + warnings.append(f"layout.{key}: '{path}' does not exist on disk (fine if intended, otherwise fix or drop)") + if entries and not any(writable for _, writable in entries): + warnings.append(f"layout.{key}: no writable entry, agents will fail closed on durable writes") + seen: set[str] = set() + for index, node in enumerate(data.get("nodes") or []): + if node["id"] in seen: + warnings.append(f"nodes[{index}]: duplicate id '{node['id']}'") + seen.add(node["id"]) + if "path" in node and not (root / node["path"]).exists(): + warnings.append(f"nodes[{index}] ({node['id']}): path '{node['path']}' does not exist on disk") + if "description" not in node: + warnings.append(f"nodes[{index}] ({node['id']}): no description; say what is consulted there and when") + def bad_path(value: object) -> bool: + return isinstance(value, str) and ( + value.startswith(("/", "~", "\\")) or re.match(r"^[A-Za-z]:", value) is not None + or "\\" in value or ".." in value.split("/") + ) + + candidates = [("self.path", (data.get("self") or {}).get("path"))] + for index, node in enumerate(data.get("nodes") or []): + candidates.append((f"nodes[{index}].path", node.get("path"))) + candidates.append((f"nodes[{index}].map.path", (node.get("map") or {}).get("path"))) + for name, value in candidates: + if bad_path(value): + warnings.append(f"{name}: '{value}' must be workspace-relative (no absolute, '~', backslash or '..'); machine paths belong in map.local.yaml") + review = [n + 1 for n, line in enumerate(text.splitlines()) if re.search(r"#\s*REVIEW:", line)] + print("VALIDATION_SUCCESS") + for warning in warnings: + print(f"WARN {warning}") + print(f"REVIEW_MARKERS {len(review)}" + (f" (lines {', '.join(map(str, review))})" if review else "")) + + +if __name__ == "__main__": + main() From f6e2c16c4974b03d1b9daa1aeee8e10d34711a1c Mon Sep 17 00:00:00 2001 From: Pavel Luzanov Date: Wed, 28 Oct 2026 22:23:14 +0900 Subject: [PATCH 02/10] aap-map: dependency-free validation (manual checklist, stdlib validator, jsonschema in CI) Co-Authored-By: Claude Sonnet 5.5 --- CHANGELOG.md | 4 +- README.md | 2 +- scripts/validate.py | 51 +++ skills/aap-map/SKILL.md | 33 +- skills/aap-map/TEST-NOTES.md | 9 + skills/aap-map/scripts/validate_map.py | 527 +++++++++++++++++++++---- 6 files changed, 544 insertions(+), 82 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ba28543..3767c4e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,9 +3,9 @@ ## Unreleased - `llms.txt`: agent-readable entry point (what AAP is, what to open first, `access` rules, links). -- `skills/aap-map/`: portable agent skill that drafts and validates a minimal map, with `scripts/validate_map.py` and a bundled copy of the Map v2 schema. +- `skills/aap-map/`: portable agent skill that drafts and validates a minimal map. Validation has three levels (manual checklist, dependency-free `scripts/validate_map.py`, full jsonschema) and a bundled copy of the Map v2 schema. - `.claude-plugin/` manifests and a README section "Use with your agent". Nothing is published to any registry. -- `scripts/validate.py` checks that the bundled schema copy matches `schemas/map.schema.json` and that plugin manifests parse. +- `scripts/validate.py` checks that the bundled schema copy matches `schemas/map.schema.json`, that plugin manifests parse, and that the dependency-free validator agrees with jsonschema on all fixtures and mutated maps. ## 0.2.1-prototype — 2026-10-16 diff --git a/README.md b/README.md index 2c9e016..a6d5a4d 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ git clone --depth 1 https://github.com/gitpash/agent-artifact-protocol.git /tmp/ cp -R /tmp/aap/skills/aap-map ~/.claude/skills/aap-map ``` -Then ask your agent: *"use the aap-map skill to add an AAP map to this repo"*. Validation needs `pip install pyyaml jsonschema` (or `uv run --with pyyaml --with jsonschema`). +Then ask your agent: *"use the aap-map skill to add an AAP map to this repo"*. Nothing to install: the skill checks the map by hand against a short checklist, and uses a standard-library `python3` script for a machine check when Python is available. Package layouts for skill installers and the Claude Code plugin marketplace (`.claude-plugin/`) are included in the repo, but the skill is not listed in any registry yet. diff --git a/scripts/validate.py b/scripts/validate.py index 7136322..d7c0d66 100644 --- a/scripts/validate.py +++ b/scripts/validate.py @@ -51,6 +51,56 @@ def parse_envelope(path: Path, yaml: object) -> dict: meta["updated"] = meta["updated"].isoformat() return meta +def _normalize(value: object) -> object: + if isinstance(value, str): + return value.strip() + if isinstance(value, list): + return [_normalize(v) for v in value] + if isinstance(value, dict): + return {k: _normalize(v) for k, v in value.items()} + return value + +def check_stdlib_validator(yaml: object, map_validator: object, positives: list[Path]) -> None: + """The skill ships a stdlib-only validator; it must agree with the jsonschema reference.""" + sys.path.insert(0, str(ROOT / "skills" / "aap-map" / "scripts")) + import validate_map # type: ignore + base = yaml.safe_load((ROOT / "templates" / "minimal-map.yaml").read_text(encoding="utf-8")) + mutants = { + "bad-version": {**base, "version": 1}, + "extra-top-key": {**base, "zones": {}}, + "bad-id": {**base, "workspace": {"id": "3d-app"}}, + "uppercase-id": {**base, "self": {**base["self"], "id": "My_App"}}, + "node-missing-kind": {**base, "nodes": [{"id": "a"}]}, + "node-bad-access": {**base, "nodes": [{"id": "a", "kind": "x", "access": "rw"}]}, + "node-extra-key": {**base, "nodes": [{"id": "a", "kind": "x", "role": "y"}]}, + "node-locator-empty": {**base, "nodes": [{"id": "a", "kind": "x", "locator": {}}]}, + "node-map-ref-only": {**base, "nodes": [{"id": "a", "kind": "x", "map": {"ref": "main"}}]}, + "layout-dotdot": {**base, "layout": {"code": "../x/"}}, + "layout-empty-list": {**base, "layout": {"code": []}}, + "layout-ext-ok": {**base, "layout": {"surfaces": [{"path": "a/", "access": "read-only"}]}}, + "relation-ok": {**base, "relations": [{"from": "a", "to": "b", "type": "consumes"}]}, + "relation-missing-type": {**base, "relations": [{"from": "a", "to": "b"}]}, + "profiles-ok": {**base, "profiles": {"enabled": ["x"]}}, + "profiles-bad": {**base, "profiles": {"enabled": "x"}}, + "overlay-ok": {**base, "overlays": {"nodes": {"a": {"path": "/x"}}, "local_paths": {"b": "/y"}}}, + "overlay-bad-id": {**base, "overlays": {"nodes": {"A": {"path": "/x"}}}}, + "parent-ok": {**base, "self": {**base["self"], "parent": {"id": "hub", "locator": {"repo": "o/r"}, "map": {"path": ".aap/map.yaml"}}}}, + "parent-no-id": {**base, "self": {**base["self"], "parent": {"locator": {"repo": "o/r"}}}}, + "nodes-not-list": {**base, "nodes": {}}, + } + cases: list[tuple[str, str]] = [(str(p.relative_to(ROOT)), p.read_text(encoding="utf-8")) for p in positives] + cases += [(str(p.relative_to(ROOT)), p.read_text(encoding="utf-8")) for p in sorted((ROOT / "examples" / "invalid").glob("*.yaml"))] + cases += [(f"mutant:{name}", yaml.safe_dump(doc)) for name, doc in mutants.items()] + for name, text in cases: + errors, parsed = validate_map.validate_text(text) + reference = yaml.safe_load(text) + ref_ok = not list(map_validator.iter_errors(reference)) and not layout_path_errors(reference) + if (not errors) != ref_ok: + die(f"stdlib validator disagrees with jsonschema on {name}: stdlib={errors[:2]} reference_ok={ref_ok}") + if parsed is not None and _normalize(parsed) != _normalize(reference): + die(f"stdlib YAML reader parsed {name} differently from PyYAML") + print(f"OK stdlib validator agrees with jsonschema on {len(cases)} cases") + def main() -> None: try: import yaml # type: ignore @@ -92,5 +142,6 @@ def main() -> None: for path in sorted((ROOT / "templates").glob("artifact-*.md")): if list(envelope_validator.iter_errors(parse_envelope(path, yaml))): die(f"envelope invalid {path}") print(f"OK envelope {path.relative_to(ROOT)}") + check_stdlib_validator(yaml, map_validator, positives) print("All checks passed.") if __name__ == "__main__": main() diff --git a/skills/aap-map/SKILL.md b/skills/aap-map/SKILL.md index fb3259a..2d7a852 100644 --- a/skills/aap-map/SKILL.md +++ b/skills/aap-map/SKILL.md @@ -14,7 +14,7 @@ Schema validity proves shape only. It does not prove that the paths are right or ## Files in this skill - `schema/map.schema.json`: byte-identical copy of `schemas/map.schema.json` from the AAP repo at tag `v0.2.1-prototype`. If the two ever differ, the repo copy wins. -- `scripts/validate_map.py`: validator. Needs PyYAML and jsonschema. +- `scripts/validate_map.py`: optional validator, standard-library Python 3 only, no packages to install. Resolve these paths relative to this SKILL.md, not to the project you are mapping. Use the absolute path when you run the validator. @@ -113,15 +113,26 @@ Edit the file textually. Do not load it into a YAML library and dump it back, wh ### 5. Validate +Nothing here needs an install. Use the highest level that works on this machine and say which one you used. + +**Level 1, always: manual checklist.** Check the file yourself against these rules (they are the whole schema): + +- `version: 2`, and `workspace`, `self` and `nodes` all present. `nodes` is a list (`[]` is fine). +- `workspace` has only `id` and `description`. `self` has `id`, `kind` and optionally `path`, `description`, `parent`. +- Every id (`workspace.id`, `self.id`, node ids, `parent.id`) matches `^[a-z][a-z0-9-]*$`. +- Every layout value is a path string, or `{ path, access?, description? }`, or a non-empty list of those. `access` is `read-only` or `read-write` and nothing else. +- Paths are relative: no leading `/`, no `..`, no `~`, no backslashes, no Windows drive letters. +- A node has `id` and `kind`, and only these other fields: `description`, `path`, `locator`, `map`, `mirror`, `access`, `write`. `locator` needs `repo`, `url` or `id`. `map` needs `path` or `url`. +- No unknown fields anywhere, except extra keys under `layout`. Descriptions are quoted strings. +- Every path in the map exists on disk (check with `ls`), or is flagged with a REVIEW comment. + +**Level 2, if `python3` is on the machine: bundled script.** It uses only the Python standard library. + ```bash python3 /absolute/path/to/aap-map/scripts/validate_map.py .aap/map.yaml ``` -(On Windows use `py -3` instead of `python3`.) - -If PyYAML or jsonschema are missing, either `pip install pyyaml jsonschema` (inside a virtualenv, not system-wide) or run `uv run --with pyyaml --with jsonschema python3 /absolute/path/to/aap-map/scripts/validate_map.py .aap/map.yaml`. Do not install packages into the project's own environment without asking. - -Output contract: +(On Windows use `py -3`.) Output contract: ```text VALIDATION_SUCCESS @@ -132,9 +143,13 @@ VALIDATION_FAILED - path: /nodes/0/id | message: ... ``` -On failure, patch the file from the path and message and run again. Stop after 5 rounds and report what is still failing. Do not weaken the schema or edit the bundled copy to make a map pass. +The script reads a deliberately small YAML subset. If it answers "unsupported YAML", rewrite the map in plain block style (indented `key: value` lines, quoted strings) and run it again; that is not a schema error. + +**Level 3, optional, for AAP maintainers: full JSON Schema.** The AAP repository's `scripts/validate.py` uses `jsonschema` against `schemas/map.schema.json`. Do not install anything to reach this level unless the user asks. `uv run --with pyyaml --with jsonschema python3 scripts/validate.py` runs it without touching the project's environment. + +On failure at level 2, patch the file from the path and message and run again. Stop after 5 rounds and report what is still failing. Do not weaken the schema or edit the bundled copy to make a map pass. -If Python is not available at all, report "validation NOT RUN" and never call the map valid. Self-check the rules above (id pattern, no absolute paths, no `..`, quoted descriptions) and show the user the one command to run later. +If you could only do level 1, the map is "checked by hand, not by a machine": say that, never call it validated, and give the user the level 2 command to run later. ### 6. Hand over for review @@ -143,7 +158,7 @@ Do not claim the map is done. End with this report, plainly: ```text ## aap-map result - file: .aap/map.yaml (new | unchanged | proposed diff) -- validation: PASS | FAIL | NOT RUN (why) +- validation level actually run: 1 manual checklist | 2 bundled script (PASS or FAIL) | 3 full JSON Schema (PASS or FAIL). If 2 or 3 could not run, say why. Only 2 or 3 may be called "validated". - layout keys: (each with the evidence you used) - nodes accepted: N (id, reason) / candidates rejected: N (name as seen in the repo, why; list only candidates you actually saw) - REVIEW markers: N (list the lines) diff --git a/skills/aap-map/TEST-NOTES.md b/skills/aap-map/TEST-NOTES.md index a6e1739..7104d17 100644 --- a/skills/aap-map/TEST-NOTES.md +++ b/skills/aap-map/TEST-NOTES.md @@ -29,10 +29,19 @@ No run admitted a node. Third-party libraries and README mentions were rejected, Reviewer findings applied: do not assume a git repo; do not guess `locator.repo` or the host; `read-only` needs written evidence, a folder name is not enough; slugify ids without reordering words; edit the map textually so comments survive; validator warns on absolute, `~`, backslash and `..` paths in `self.path`, `node.path` and `map.path` (the schema only checks layout paths); validator sort no longer crashes on mixed index and key error paths; REVIEW marker count matches only YAML comments; `python3` / `py -3` and absolute script path; honest "validation NOT RUN" fallback; do not create a second map next to an existing one. +## Validator without dependencies (second pass) + +The first version of the skill required PyYAML and jsonschema, which is a poor ask for a skill that should work on any machine. The skill now has three levels: a manual checklist (always possible), a standard-library `python3` script with its own small YAML reader (no installs), and the full `jsonschema` check kept for the AAP repository itself. The report states which level actually ran, and only levels 2 and 3 may be called "validated". + +Safety net: `scripts/validate.py` runs the standard-library validator and PyYAML plus jsonschema over every valid example, every invalid fixture and 20 mutated maps. It fails if they disagree on accept or reject, or if the standard-library reader parses a file differently from PyYAML. The three maps produced in the tests above were rechecked with the new script and give the same results. + +Unsupported YAML (anchors, tags, multi-line plain scalars, tabs, multi-line flow collections) is rejected with a message asking for block style, not guessed at. + ## Known limits - Tested with Claude subagents only. Other agents were not tried. - The schema's `pathString` pattern rejects any path containing `..` even as part of a name (`a..b`). That is the schema's behavior and was left alone. - `layout` paths are literal. There are no globs, so large monorepos get a coarse parent folder. - The bundled schema keeps its original `$id`. A CI check in `scripts/validate.py` keeps it identical to `schemas/map.schema.json`. +- The standard-library validator was tested on macOS with Python 3.15 only. Older Python 3 versions and Windows were not tried. - Not tested: Windows, a machine with no network and no Python, and a repository that already has a map. diff --git a/skills/aap-map/scripts/validate_map.py b/skills/aap-map/scripts/validate_map.py index 766c2de..462d0c0 100644 --- a/skills/aap-map/scripts/validate_map.py +++ b/skills/aap-map/scripts/validate_map.py @@ -1,115 +1,502 @@ #!/usr/bin/env python3 -"""Validate an AAP Map v2 file against the bundled JSON Schema. +"""Validate an AAP Map v2 file with nothing but the Python 3 standard library. -Usage: python validate_map.py [MAP] [--root DIR] [--schema FILE] +Usage: python3 validate_map.py [MAP] [--root DIR] MAP defaults to .aap/map.yaml. Exit codes: 0 valid, 1 invalid, 2 setup problem. -Needs PyYAML and jsonschema (pip install pyyaml jsonschema, or -uv run --with pyyaml --with jsonschema python validate_map.py ...). -Warnings never change the exit code; they point at things a human should check. + +This is a hand-written check of the Map v2 schema plus a small YAML reader for +the subset a map needs: block mappings and sequences, flow {} and [] values, +quoted and plain scalars, comments, and | or > block scalars. Anything else +(anchors, tags, multi-line plain scalars, tabs) is rejected on purpose with +"unsupported YAML"; rewrite the map in block style. The full JSON Schema check +(scripts/validate.py in the AAP repo) is the reference; CI runs both on the +same fixtures so they cannot drift apart. """ from __future__ import annotations import argparse -import json import re import sys from pathlib import Path -HERE = Path(__file__).resolve().parent +ID = re.compile(r"^[a-z][a-z0-9-]*$") +KEY_RE = ( + r'^("(?:[^"\\]|\\.)*"' # double-quoted key + r"|'[^']*'" # single-quoted key + r"|[^\s:#\"'\[{][^:#]*?)" # plain key + r"\s*:(?:\s+(.*)|$)" +) + + +class YamlError(Exception): + pass + + +# ---------------------------------------------------------------- YAML subset + +def strip_comment(line: str) -> str: + quote = "" + for i, ch in enumerate(line): + if quote: + if ch == quote: + quote = "" + elif ch in "\"'" and (i == 0 or line[i - 1] in " \t:[{,-"): + quote = ch + elif ch == "#" and (i == 0 or line[i - 1] in " \t"): + return line[:i] + return line.rstrip() + + +def scalar(text: str): + t = text.strip() + if t == "": + return None + if t[0] == '"': + if len(t) < 2 or t[-1] != '"': + raise YamlError(f"unterminated double quote: {t[:40]}") + return re.sub(r'\\(["\\/])', r"\1", t[1:-1]).replace("\\n", "\n").replace("\\t", "\t") + if t[0] == "'": + if len(t) < 2 or t[-1] != "'": + raise YamlError(f"unterminated single quote: {t[:40]}") + return t[1:-1].replace("''", "'") + if t[0] in "&*!@`%": + raise YamlError(f"unsupported YAML (anchors, tags, aliases): {t[:40]}") + if t in ("null", "~", "Null", "NULL"): + return None + if t in ("true", "True", "TRUE"): + return True + if t in ("false", "False", "FALSE"): + return False + if re.fullmatch(r"-?\d+", t): + return int(t) + if t[0] in "{[": + return flow(t) + return t + + +def flow(text: str): + pos = 0 + + def skip() -> None: + nonlocal pos + while pos < len(text) and text[pos] in " \t": + pos += 1 + + def value(stop: str): + nonlocal pos + skip() + if pos >= len(text): + raise YamlError("unterminated flow collection") + ch = text[pos] + if ch == "{": + pos += 1 + out: dict = {} + skip() + if text[pos:pos + 1] == "}": + pos += 1 + return out + while True: + key = value(":") + skip() + if text[pos:pos + 1] != ":": + raise YamlError("flow mapping key without ':' (quote values that contain commas, colons or #, or use block style)") + pos += 1 + out[key] = value(",}") + skip() + if text[pos:pos + 1] == ",": + pos += 1 + continue + if text[pos:pos + 1] == "}": + pos += 1 + return out + raise YamlError("bad flow mapping") + if ch == "[": + pos += 1 + items: list = [] + skip() + if text[pos:pos + 1] == "]": + pos += 1 + return items + while True: + items.append(value(",]")) + skip() + if text[pos:pos + 1] == ",": + pos += 1 + continue + if text[pos:pos + 1] == "]": + pos += 1 + return items + raise YamlError("bad flow sequence") + if ch in "\"'": + end = pos + 1 + while end < len(text) and text[end] != ch: + end += 1 + if end >= len(text): + raise YamlError("unterminated quote in flow collection") + raw = text[pos:end + 1] + pos = end + 1 + return scalar(raw) + start = pos + while pos < len(text) and text[pos] not in stop: + pos += 1 + return scalar(text[start:pos]) + + result = value("") + skip() + if pos != len(text): + raise YamlError(f"unexpected text after flow value: {text[pos:pos + 30]}") + return result + + +def parse_yaml(source: str): + if "\t" in source: + raise YamlError("unsupported YAML: tab characters (use spaces)") + raw = source.splitlines() + lines: list[tuple[int, str, int]] = [] # (indent, text, original index) + for n, line in enumerate(raw): + stripped = strip_comment(line) + if stripped.strip() == "" or stripped.strip() in ("---", "..."): + continue + lines.append((len(stripped) - len(stripped.lstrip(" ")), stripped.strip(), n)) + if not lines: + raise YamlError("empty document") + pos = 0 + + def block_scalar(indent: int, style: str, header_line: int) -> str: + nonlocal pos + body = [] + n = header_line + 1 + while n < len(raw) and (raw[n].strip() == "" or len(raw[n]) - len(raw[n].lstrip(" ")) > indent): + body.append(raw[n].strip()) + n += 1 + while pos < len(lines) and lines[pos][2] < n: + pos += 1 + joined = ("\n" if style.startswith("|") else " ").join(body).strip() + return joined + + def split_key(text: str): + m = re.match(KEY_RE, text) + if not m: + return None + key = scalar(m.group(1)) + return key, (m.group(2) or "") + + def value_of(rest: str, indent: int, line_no: int): + nonlocal pos + if rest in ("|", ">", "|-", ">-", "|+", ">+"): + return block_scalar(indent, rest, line_no) + if rest == "": + if pos < len(lines) and (lines[pos][0] > indent or (lines[pos][0] == indent and lines[pos][1].startswith("- "))): + return parse_block(lines[pos][0]) + return None + if rest[0] in "{[" and not (rest.endswith("}") or rest.endswith("]")): + raise YamlError(f"unsupported YAML: multi-line flow collection at line {line_no + 1}") + val = scalar(rest) + if pos < len(lines) and lines[pos][0] > indent and not isinstance(val, (dict, list)): + raise YamlError(f"unsupported YAML: multi-line plain scalar near line {lines[pos][2] + 1}; quote it on one line") + return val + + def parse_block(indent: int): + nonlocal pos + indent_now, text, _ = lines[pos] + if text.startswith("- ") or text == "-": + seq: list = [] + while pos < len(lines) and lines[pos][0] == indent and (lines[pos][1].startswith("- ") or lines[pos][1] == "-"): + _, t, ln = lines[pos] + rest = t[1:].strip() + pos += 1 + kv = split_key(rest) if rest and rest[0] not in "{[" else None + if kv is not None: + # "- key: value": re-inject as a mapping indented past the dash + offset = len(t) - len(rest) + lines.insert(pos, (indent + offset, rest, ln)) + seq.append(parse_block(indent + offset)) + elif rest == "": + seq.append(parse_block(lines[pos][0]) if pos < len(lines) and lines[pos][0] > indent else None) + else: + seq.append(value_of(rest, indent, ln)) + return seq + out: dict = {} + while pos < len(lines) and lines[pos][0] == indent: + _, t, ln = lines[pos] + if t.startswith("- "): + break + kv = split_key(t) + if kv is None: + raise YamlError(f"unsupported YAML or not a mapping at line {ln + 1}: {t[:50]}") + key, rest = kv + pos += 1 + if key in out: + raise YamlError(f"duplicate key '{key}' at line {ln + 1}") + out[key] = value_of(rest, indent, ln) + if pos < len(lines) and lines[pos][0] > indent: + raise YamlError(f"unexpected indentation at line {lines[pos][2] + 1}") + return out + + doc = parse_block(lines[0][0]) + if pos < len(lines): + raise YamlError(f"unexpected content at line {lines[pos][2] + 1}: {lines[pos][1][:50]}") + return doc + + +# --------------------------------------------------------------- schema rules + +def is_str(v) -> bool: + return isinstance(v, str) and v != "" + +def check_path(v, where, errs, allow_empty=False): + if not isinstance(v, str) or (v == "" and not allow_empty): + errs.append((where, "must be a non-empty string")) + elif v.startswith("/") or ".." in v: + errs.append((where, f"must be workspace-relative with no '..' (got {v!r})")) -def setup_error(message: str) -> None: - print(f"SETUP_ERROR: {message}", file=sys.stderr) - raise SystemExit(2) +def check_id(v, where, errs): + if not (isinstance(v, str) and ID.match(v)): + errs.append((where, f"id must match ^[a-z][a-z0-9-]*$ (got {v!r})")) -def refs(value: object) -> list[tuple[str, bool]]: - """Return (path, writable) for a layout value.""" - items = value if isinstance(value, list) else [value] - out = [] - for item in items: + +def check_keys(obj, where, allowed, required, errs): + if not isinstance(obj, dict): + errs.append((where, "must be a mapping")) + return False + for k in obj: + if k not in allowed: + errs.append((f"{where}/{k}", "additional property not allowed")) + for k in required: + if k not in obj: + errs.append((where, f"missing required property '{k}'")) + return True + + +def check_access(v, where, errs): + if v not in ("read-only", "read-write"): + errs.append((where, "access must be 'read-only' or 'read-write'")) + + +def check_resource(v, where, errs): + if isinstance(v, str): + check_path(v, where, errs) + elif isinstance(v, dict): + if check_keys(v, where, {"path", "access", "description"}, ["path"], errs): + if "path" in v: + check_path(v["path"], f"{where}/path", errs) + if "access" in v: + check_access(v["access"], f"{where}/access", errs) + if "description" in v and not isinstance(v["description"], str): + errs.append((f"{where}/description", "must be a string")) + else: + errs.append((where, "must be a path string or {path, access?, description?}")) + + +def check_locator(v, where, errs): + if check_keys(v, where, {"repo", "url", "id", "default_branch"}, [], errs): + for k in ("repo", "url", "id"): + if k in v and not is_str(v[k]): + errs.append((f"{where}/{k}", "must be a non-empty string")) + if not any(k in v for k in ("repo", "url", "id")): + errs.append((where, "needs at least one of repo, url, id")) + + +def check_mappointer(v, where, errs): + if check_keys(v, where, {"path", "url", "ref"}, [], errs): + for k in ("path", "url", "ref"): + if k in v and not is_str(v[k]): + errs.append((f"{where}/{k}", "must be a non-empty string")) + if not ("path" in v or "url" in v): + errs.append((where, "needs path or url")) + + +def schema_errors(d) -> list[tuple[str, str]]: + errs: list[tuple[str, str]] = [] + top = {"version", "workspace", "self", "layout", "nodes", "relations", "overlays", "profiles"} + if not check_keys(d, "", top, ["version", "workspace", "self", "nodes"], errs): + return errs + if d.get("version") != 2 or isinstance(d.get("version"), bool): + errs.append(("/version", "must be the integer 2")) + ws = d.get("workspace") + if check_keys(ws, "/workspace", {"id", "description"}, ["id"], errs): + if "id" in ws: + check_id(ws["id"], "/workspace/id", errs) + if "description" in ws and not isinstance(ws["description"], str): + errs.append(("/workspace/description", "must be a string")) + me = d.get("self") + if check_keys(me, "/self", {"id", "kind", "path", "description", "parent"}, ["id", "kind"], errs): + if "id" in me: + check_id(me["id"], "/self/id", errs) + for k in ("kind", "path"): + if k in me and not is_str(me[k]): + errs.append((f"/self/{k}", "must be a non-empty string")) + if "description" in me and not isinstance(me["description"], str): + errs.append(("/self/description", "must be a string")) + if "parent" in me: + p = me["parent"] + if check_keys(p, "/self/parent", {"id", "locator", "map"}, ["id"], errs): + if "id" in p: + check_id(p["id"], "/self/parent/id", errs) + if "locator" in p: + check_locator(p["locator"], "/self/parent/locator", errs) + if "map" in p: + check_mappointer(p["map"], "/self/parent/map", errs) + layout = d.get("layout") + if "layout" in d: + if not isinstance(layout, dict): + errs.append(("/layout", "must be a mapping")) + else: + for k, v in layout.items(): + if isinstance(v, list): + if not v: + errs.append((f"/layout/{k}", "list must not be empty")) + for i, item in enumerate(v): + check_resource(item, f"/layout/{k}/{i}", errs) + else: + check_resource(v, f"/layout/{k}", errs) + nodes = d.get("nodes") + if not isinstance(nodes, list): + errs.append(("/nodes", "must be a list (use 'nodes: []' for none)")) + else: + allowed = {"id", "kind", "description", "path", "locator", "map", "mirror", "access", "write"} + for i, n in enumerate(nodes): + w = f"/nodes/{i}" + if not check_keys(n, w, allowed, ["id", "kind"], errs): + continue + if "id" in n: + check_id(n["id"], f"{w}/id", errs) + for k in ("kind", "path"): + if k in n and not is_str(n[k]): + errs.append((f"{w}/{k}", "must be a non-empty string")) + if "description" in n and not isinstance(n["description"], str): + errs.append((f"{w}/description", "must be a string")) + if "locator" in n: + check_locator(n["locator"], f"{w}/locator", errs) + if "map" in n: + check_mappointer(n["map"], f"{w}/map", errs) + if "mirror" in n: + m = n["mirror"] + if check_keys(m, f"{w}/mirror", {"path"}, ["path"], errs) and "path" in m and not is_str(m["path"]): + errs.append((f"{w}/mirror/path", "must be a non-empty string")) + if "access" in n: + check_access(n["access"], f"{w}/access", errs) + if "write" in n: + wr = n["write"] + if not isinstance(wr, list) or not all(is_str(x) for x in wr): + errs.append((f"{w}/write", "must be a list of non-empty strings")) + if "relations" in d: + rel = d["relations"] + if not isinstance(rel, list): + errs.append(("/relations", "must be a list")) + else: + for i, r in enumerate(rel): + w = f"/relations/{i}" + if check_keys(r, w, {"from", "to", "type", "description"}, ["from", "to", "type"], errs): + for k in ("from", "to"): + if k in r: + check_id(r[k], f"{w}/{k}", errs) + if "type" in r and not is_str(r["type"]): + errs.append((f"{w}/type", "must be a non-empty string")) + if "description" in r and not isinstance(r["description"], str): + errs.append((f"{w}/description", "must be a string")) + if "overlays" in d: + o = d["overlays"] + if check_keys(o, "/overlays", {"nodes", "local_paths"}, [], errs): + if "nodes" in o: + on = o["nodes"] + if not isinstance(on, dict): + errs.append(("/overlays/nodes", "must be a mapping")) + else: + for k, v in on.items(): + check_id(k, f"/overlays/nodes/{k}", errs) + if check_keys(v, f"/overlays/nodes/{k}", {"path"}, [], errs) and "path" in v and not is_str(v["path"]): + errs.append((f"/overlays/nodes/{k}/path", "must be a non-empty string")) + if "local_paths" in o: + lp = o["local_paths"] + if not isinstance(lp, dict): + errs.append(("/overlays/local_paths", "must be a mapping")) + else: + for k, v in lp.items(): + check_id(k, f"/overlays/local_paths/{k}", errs) + if not is_str(v): + errs.append((f"/overlays/local_paths/{k}", "must be a non-empty string")) + if "profiles" in d: + p = d["profiles"] + if check_keys(p, "/profiles", {"enabled"}, [], errs) and "enabled" in p: + if not isinstance(p["enabled"], list) or not all(is_str(x) for x in p["enabled"]): + errs.append(("/profiles/enabled", "must be a list of non-empty strings")) + return errs + + +# ----------------------------------------------------------------------- main + +def layout_refs(value): + for item in value if isinstance(value, list) else [value]: if isinstance(item, str): - out.append((item, True)) + yield item, True elif isinstance(item, dict) and isinstance(item.get("path"), str): - out.append((item["path"], item.get("access", "read-write") != "read-only")) - return out - + yield item["path"], item.get("access", "read-write") != "read-only" -def main() -> None: - parser = argparse.ArgumentParser() - parser.add_argument("map", nargs="?", default=".aap/map.yaml") - parser.add_argument("--root", help="workspace root for path checks (default: parent of .aap/, else map dir)") - parser.add_argument("--schema", default=str(HERE.parent / "schema" / "map.schema.json")) - args = parser.parse_args() +def validate_text(text: str) -> tuple[list[tuple[str, str]], object]: + """Return (errors, parsed document). Used by the AAP repo's CI as well.""" try: - import yaml - import jsonschema - except ImportError: - setup_error("PyYAML and jsonschema are required: pip install pyyaml jsonschema") + data = parse_yaml(text) + except YamlError as error: + return [("/", f"{error}")], None + return schema_errors(data), data + +def main() -> None: + ap = argparse.ArgumentParser() + ap.add_argument("map", nargs="?", default=".aap/map.yaml") + ap.add_argument("--root", help="workspace root for path checks (default: parent of .aap/, else map dir)") + args = ap.parse_args() map_path = Path(args.map) if not map_path.is_file(): - setup_error(f"map not found: {map_path}") - schema_path = Path(args.schema) - if not schema_path.is_file(): - setup_error(f"schema not found: {schema_path}") - + print(f"SETUP_ERROR: map not found: {map_path}", file=sys.stderr) + raise SystemExit(2) text = map_path.read_text(encoding="utf-8") - try: - data = yaml.safe_load(text) - except yaml.YAMLError as error: - print("VALIDATION_FAILED") - print(f"- path: / | message: YAML does not parse: {error}") - raise SystemExit(1) - schema = json.loads(schema_path.read_text(encoding="utf-8")) - validator = jsonschema.Draft7Validator(schema) - errors = sorted(validator.iter_errors(data), key=lambda e: [str(p) for p in e.absolute_path]) + errors, data = validate_text(text) if errors: print("VALIDATION_FAILED") - for error in errors: - pointer = "/" + "/".join(str(p) for p in error.absolute_path) - print(f"- path: {pointer} | message: {error.message[:200]}") + for pointer, message in errors: + print(f"- path: {pointer or '/'} | message: {message[:200]}") raise SystemExit(1) - root = Path(args.root) if args.root else ( - map_path.resolve().parent.parent if map_path.resolve().parent.name == ".aap" else map_path.resolve().parent - ) + here = map_path.resolve().parent + root = Path(args.root) if args.root else (here.parent if here.name == ".aap" else here) warnings: list[str] = [] for key, value in (data.get("layout") or {}).items(): - entries = refs(value) + entries = list(layout_refs(value)) for path, _ in entries: if not (root / path).exists(): warnings.append(f"layout.{key}: '{path}' does not exist on disk (fine if intended, otherwise fix or drop)") - if entries and not any(writable for _, writable in entries): + if entries and not any(w for _, w in entries): warnings.append(f"layout.{key}: no writable entry, agents will fail closed on durable writes") seen: set[str] = set() - for index, node in enumerate(data.get("nodes") or []): + for i, node in enumerate(data.get("nodes") or []): if node["id"] in seen: - warnings.append(f"nodes[{index}]: duplicate id '{node['id']}'") + warnings.append(f"nodes[{i}]: duplicate id '{node['id']}'") seen.add(node["id"]) if "path" in node and not (root / node["path"]).exists(): - warnings.append(f"nodes[{index}] ({node['id']}): path '{node['path']}' does not exist on disk") + warnings.append(f"nodes[{i}] ({node['id']}): path '{node['path']}' does not exist on disk") if "description" not in node: - warnings.append(f"nodes[{index}] ({node['id']}): no description; say what is consulted there and when") - def bad_path(value: object) -> bool: - return isinstance(value, str) and ( - value.startswith(("/", "~", "\\")) or re.match(r"^[A-Za-z]:", value) is not None - or "\\" in value or ".." in value.split("/") - ) - - candidates = [("self.path", (data.get("self") or {}).get("path"))] - for index, node in enumerate(data.get("nodes") or []): - candidates.append((f"nodes[{index}].path", node.get("path"))) - candidates.append((f"nodes[{index}].map.path", (node.get("map") or {}).get("path"))) - for name, value in candidates: - if bad_path(value): - warnings.append(f"{name}: '{value}' must be workspace-relative (no absolute, '~', backslash or '..'); machine paths belong in map.local.yaml") + warnings.append(f"nodes[{i}] ({node['id']}): no description; say what is consulted there and when") + + def bad(v) -> bool: + return isinstance(v, str) and (v.startswith(("/", "~", "\\")) or re.match(r"^[A-Za-z]:", v) is not None + or "\\" in v or ".." in v.split("/")) + + cands = [("self.path", (data.get("self") or {}).get("path"))] + for i, node in enumerate(data.get("nodes") or []): + cands += [(f"nodes[{i}].path", node.get("path")), (f"nodes[{i}].map.path", (node.get("map") or {}).get("path"))] + for name, v in cands: + if bad(v): + warnings.append(f"{name}: '{v}' must be workspace-relative (no absolute, '~', backslash or '..'); machine paths belong in map.local.yaml") review = [n + 1 for n, line in enumerate(text.splitlines()) if re.search(r"#\s*REVIEW:", line)] print("VALIDATION_SUCCESS") - for warning in warnings: - print(f"WARN {warning}") + for w in warnings: + print(f"WARN {w}") print(f"REVIEW_MARKERS {len(review)}" + (f" (lines {', '.join(map(str, review))})" if review else "")) From 07ae1f94d96ba983188f50fbeb29744c5fc98318 Mon Sep 17 00:00:00 2001 From: Pavel Luzanov Date: Wed, 28 Oct 2026 22:25:00 +0900 Subject: [PATCH 03/10] aap-map: simplify to a single text file, drop bundled validator and schema copy Validation stays an optional CI choice. Test notes moved to cookbook. Co-Authored-By: Claude Sonnet 5.5 --- CHANGELOG.md | 4 +- README.md | 6 +- cookbook/aap-map-skill-tests.md | 38 ++ llms.txt | 2 +- scripts/validate.py | 54 --- skills/aap-map/SKILL.md | 212 ++++------- skills/aap-map/TEST-NOTES.md | 47 --- skills/aap-map/schema/map.schema.json | 225 ----------- skills/aap-map/scripts/validate_map.py | 504 ------------------------- 9 files changed, 109 insertions(+), 983 deletions(-) create mode 100644 cookbook/aap-map-skill-tests.md delete mode 100644 skills/aap-map/TEST-NOTES.md delete mode 100644 skills/aap-map/schema/map.schema.json delete mode 100644 skills/aap-map/scripts/validate_map.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 3767c4e..2fabe32 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,9 +3,9 @@ ## Unreleased - `llms.txt`: agent-readable entry point (what AAP is, what to open first, `access` rules, links). -- `skills/aap-map/`: portable agent skill that drafts and validates a minimal map. Validation has three levels (manual checklist, dependency-free `scripts/validate_map.py`, full jsonschema) and a bundled copy of the Map v2 schema. +- `skills/aap-map/`: portable agent skill (one SKILL.md) that writes a minimal map and flags guesses for review. No scripts or dependencies; machine validation stays a CI choice (`cookbook/ci-validation.md`). - `.claude-plugin/` manifests and a README section "Use with your agent". Nothing is published to any registry. -- `scripts/validate.py` checks that the bundled schema copy matches `schemas/map.schema.json`, that plugin manifests parse, and that the dependency-free validator agrees with jsonschema on all fixtures and mutated maps. +- `scripts/validate.py` also checks that the plugin manifests parse. ## 0.2.1-prototype — 2026-10-16 diff --git a/README.md b/README.md index a6d5a4d..ed33110 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ https://raw.githubusercontent.com/gitpash/agent-artifact-protocol/main/llms.txt Paste that into any chat or agent session and ask it to explain AAP or to work in a repo that has an `.aap/map.yaml`. It points to the spec and schema only for when they are needed. -**Add a map to your own project with the `aap-map` skill.** The skill in [`skills/aap-map/`](./skills/aap-map/SKILL.md) drafts a minimal `.aap/map.yaml` for any codebase, validates it against the bundled schema, and marks anything it could not verify with `# REVIEW:` comments for you to check. It never overwrites an existing map. Install it as a plain skill folder: +**Add a map to your own project with the `aap-map` skill.** The skill in [`skills/aap-map/`](./skills/aap-map/SKILL.md) is a single text file. It tells your agent how to look at a repository, write a minimal `.aap/map.yaml`, and say which parts it guessed (`# REVIEW:` comments). It does not interview you and it never overwrites an existing map. Say "ok" or ask for changes. Install it as a plain skill folder: ```bash # Claude Code, user-level @@ -46,7 +46,7 @@ git clone --depth 1 https://github.com/gitpash/agent-artifact-protocol.git /tmp/ cp -R /tmp/aap/skills/aap-map ~/.claude/skills/aap-map ``` -Then ask your agent: *"use the aap-map skill to add an AAP map to this repo"*. Nothing to install: the skill checks the map by hand against a short checklist, and uses a standard-library `python3` script for a machine check when Python is available. +Then ask your agent: *"use the aap-map skill to add an AAP map to this repo"*. Nothing to install and nothing is validated by a tool at this point. If you want machine checking later, for example in CI, see [`cookbook/ci-validation.md`](./cookbook/ci-validation.md). Package layouts for skill installers and the Claude Code plugin marketplace (`.claude-plugin/`) are included in the repo, but the skill is not listed in any registry yet. @@ -311,7 +311,7 @@ This is a **convention + schemas**, not a complete cross-file protocol suite. ```text README.md SPEC.md MOTIVATION.md CONTRIBUTING.md CHANGELOG.md llms.txt -skills/aap-map/ # portable agent skill + validator + bundled schema copy +skills/aap-map/ # portable agent skill (one SKILL.md) .claude-plugin/ # plugin + marketplace manifests (not published) schemas/ # Map v2 JSON Schema legacy/v1/ # historical zones map diff --git a/cookbook/aap-map-skill-tests.md b/cookbook/aap-map-skill-tests.md new file mode 100644 index 0000000..360d50d --- /dev/null +++ b/cookbook/aap-map-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/llms.txt b/llms.txt index 1c100de..82d2f86 100644 --- a/llms.txt +++ b/llms.txt @@ -61,7 +61,7 @@ Until the user or runtime explicitly enables writes, prefer reading and orientin ## Creating or updating a map: the `aap-map` skill -The folder `skills/aap-map/` is a portable agent skill (SKILL.md plus a validator and a bundled copy of the schema). It drafts a minimal map for any codebase, validates it against the schema, and marks uncertain nodes for human review. Install paths are described in the README section "Use with your agent". +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 paths are in the README section "Use with your agent". ## Rules of thumb diff --git a/scripts/validate.py b/scripts/validate.py index d7c0d66..8cc0010 100644 --- a/scripts/validate.py +++ b/scripts/validate.py @@ -51,56 +51,6 @@ def parse_envelope(path: Path, yaml: object) -> dict: meta["updated"] = meta["updated"].isoformat() return meta -def _normalize(value: object) -> object: - if isinstance(value, str): - return value.strip() - if isinstance(value, list): - return [_normalize(v) for v in value] - if isinstance(value, dict): - return {k: _normalize(v) for k, v in value.items()} - return value - -def check_stdlib_validator(yaml: object, map_validator: object, positives: list[Path]) -> None: - """The skill ships a stdlib-only validator; it must agree with the jsonschema reference.""" - sys.path.insert(0, str(ROOT / "skills" / "aap-map" / "scripts")) - import validate_map # type: ignore - base = yaml.safe_load((ROOT / "templates" / "minimal-map.yaml").read_text(encoding="utf-8")) - mutants = { - "bad-version": {**base, "version": 1}, - "extra-top-key": {**base, "zones": {}}, - "bad-id": {**base, "workspace": {"id": "3d-app"}}, - "uppercase-id": {**base, "self": {**base["self"], "id": "My_App"}}, - "node-missing-kind": {**base, "nodes": [{"id": "a"}]}, - "node-bad-access": {**base, "nodes": [{"id": "a", "kind": "x", "access": "rw"}]}, - "node-extra-key": {**base, "nodes": [{"id": "a", "kind": "x", "role": "y"}]}, - "node-locator-empty": {**base, "nodes": [{"id": "a", "kind": "x", "locator": {}}]}, - "node-map-ref-only": {**base, "nodes": [{"id": "a", "kind": "x", "map": {"ref": "main"}}]}, - "layout-dotdot": {**base, "layout": {"code": "../x/"}}, - "layout-empty-list": {**base, "layout": {"code": []}}, - "layout-ext-ok": {**base, "layout": {"surfaces": [{"path": "a/", "access": "read-only"}]}}, - "relation-ok": {**base, "relations": [{"from": "a", "to": "b", "type": "consumes"}]}, - "relation-missing-type": {**base, "relations": [{"from": "a", "to": "b"}]}, - "profiles-ok": {**base, "profiles": {"enabled": ["x"]}}, - "profiles-bad": {**base, "profiles": {"enabled": "x"}}, - "overlay-ok": {**base, "overlays": {"nodes": {"a": {"path": "/x"}}, "local_paths": {"b": "/y"}}}, - "overlay-bad-id": {**base, "overlays": {"nodes": {"A": {"path": "/x"}}}}, - "parent-ok": {**base, "self": {**base["self"], "parent": {"id": "hub", "locator": {"repo": "o/r"}, "map": {"path": ".aap/map.yaml"}}}}, - "parent-no-id": {**base, "self": {**base["self"], "parent": {"locator": {"repo": "o/r"}}}}, - "nodes-not-list": {**base, "nodes": {}}, - } - cases: list[tuple[str, str]] = [(str(p.relative_to(ROOT)), p.read_text(encoding="utf-8")) for p in positives] - cases += [(str(p.relative_to(ROOT)), p.read_text(encoding="utf-8")) for p in sorted((ROOT / "examples" / "invalid").glob("*.yaml"))] - cases += [(f"mutant:{name}", yaml.safe_dump(doc)) for name, doc in mutants.items()] - for name, text in cases: - errors, parsed = validate_map.validate_text(text) - reference = yaml.safe_load(text) - ref_ok = not list(map_validator.iter_errors(reference)) and not layout_path_errors(reference) - if (not errors) != ref_ok: - die(f"stdlib validator disagrees with jsonschema on {name}: stdlib={errors[:2]} reference_ok={ref_ok}") - if parsed is not None and _normalize(parsed) != _normalize(reference): - die(f"stdlib YAML reader parsed {name} differently from PyYAML") - print(f"OK stdlib validator agrees with jsonschema on {len(cases)} cases") - def main() -> None: try: import yaml # type: ignore @@ -109,9 +59,6 @@ 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") - bundled = ROOT / "skills" / "aap-map" / "schema" / "map.schema.json" - if bundled.exists() and load_json(bundled) != map_schema: - die("skills/aap-map/schema/map.schema.json differs from schemas/map.schema.json (re-copy it)") for manifest in sorted((ROOT / ".claude-plugin").glob("*.json")): load_json(manifest) print(f"OK json {manifest.relative_to(ROOT)}") @@ -142,6 +89,5 @@ def main() -> None: for path in sorted((ROOT / "templates").glob("artifact-*.md")): if list(envelope_validator.iter_errors(parse_envelope(path, yaml))): die(f"envelope invalid {path}") print(f"OK envelope {path.relative_to(ROOT)}") - check_stdlib_validator(yaml, map_validator, positives) print("All checks passed.") if __name__ == "__main__": main() diff --git a/skills/aap-map/SKILL.md b/skills/aap-map/SKILL.md index 2d7a852..a48ad91 100644 --- a/skills/aap-map/SKILL.md +++ b/skills/aap-map/SKILL.md @@ -1,183 +1,101 @@ --- name: aap-map -description: Draft, validate and review a minimal AAP (Agent Artifact Protocol) navigation map, .aap/map.yaml, for any repository. Use when the user asks to add an AAP map, create or fix .aap/map.yaml, check a map against the schema, or says "aap-map". Produces a schema-valid candidate and marks uncertain parts for human review. Not for general documentation work. +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 -Creates a small `.aap/map.yaml` (AAP Map v2) for the repository you are in, checks it against the bundled JSON Schema, and leaves anything it could not establish from evidence marked for a human. +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. -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. It is not a dependency graph, a search index or a permission system. +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. -Schema validity proves shape only. It does not prove that the paths are right or the nodes are useful. That is why this skill ends with a review step, not with "done". +## Ground rules -## Files in this skill +- 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. -- `schema/map.schema.json`: byte-identical copy of `schemas/map.schema.json` from the AAP repo at tag `v0.2.1-prototype`. If the two ever differ, the repo copy wins. -- `scripts/validate_map.py`: optional validator, standard-library Python 3 only, no packages to install. +## Steps -Resolve these paths relative to this SKILL.md, not to the project you are mapping. Use the absolute path when you run the validator. +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): -## Rules before you write anything + ```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: [] + ``` -1. If `.aap/map.yaml` (or `map.yaml`, `docs/map.yaml`) already exists, do not overwrite it and do not create a second map next to it. Validate it, report, and propose a diff. Write only after the user says yes. -2. Work in the project root you were pointed at (the git top-level, if it is a git repo). If it is a subfolder of a monorepo, ask which folder is the workspace. -3. Do not edit other repositories. For a neighbor that should list this repo, give a YAML snippet and stop. -4. Do not move, rename or "tidy" any existing docs or folders to make the map look better. -5. Never put absolute or machine-specific paths into the committed map. Those belong in a gitignored `map.local.yaml`. +3. **Report** in a few lines (see the end), then stop. -## Procedure +## Filling it in -### 1. Discover (short, evidence only) +**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. -Read, in this order, and stop as soon as you can fill the map: +**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 `..`. -- README and any agent guidance file (`AGENTS.md`, `CLAUDE.md`, CONTRIBUTING), if present. Match file names case-insensitively. -- Top-level directory listing (one level, then one more level only for `src`-like roots). -- Build manifest (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle*`, etc.) for the project name and the source layout. -- Test config or test directories. -- Where durable notes live, if anywhere: `docs/`, `doc/`, `adr/`, `docs/adr/`, `rfcs/`. -- `.gitmodules`, and workspace definitions (`pnpm-workspace.yaml`, `workspaces` in `package.json`, `[tool.uv.workspace]`, `go.work`, Cargo `[workspace]`), if present. -- Endpoints, client config or generated clients that point at other repositories, when the README mentions them. +**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. -Record what you saw as evidence for each key you add. If you cannot point at evidence, do not add the key. +**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. -### 2. Draft the map +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`). -Shape (Map v2). Use block style and quote every description (a bare comma, colon or `#` inside a flow-style value splits it and the validator then reports a confusing "additional properties" error): +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. -```yaml -version: 2 -workspace: - id: - description: "" -self: - id: - kind: repository - path: . -layout: - code: - tests: -nodes: [] -``` - -Rules for each part: - -- **ids** (`workspace.id`, `self.id`, node ids): lowercase letters, digits and hyphens, must start with a letter. Slugify the repository name: lowercase, replace `_`, `.` and spaces with `-`, and add a short letter prefix only if it starts with a digit (`My_App` becomes `my-app`, `3d-viewer` becomes `app-3d-viewer`). Never reorder words. Mention every change in the report. `workspace.id` and `self.id` may be the same. -- **layout**: include only keys with evidence. `code` and `tests` usually, after confirming with `ls` that the folders exist; `artifacts` only for a folder of durable working notes (ADRs, decisions, specs), not for published user documentation such as a docs website, and only if it already exists or the user wants one (then list the path, say in the report that you did not create it, and expect a validator WARN); `scratch` only if the project already has one. A monorepo with a few code roots uses a list: `code: [packages/a/src/, packages/b/src/]`. With many packages (roughly more than five) use the parent folder (`packages/`) and add a REVIEW comment; do not use globs, the schema treats paths literally. If tests sit next to the code and there is no tests folder, omit `tests`; do not pick the nearest folder that merely looks like tests. If a vendored or generated subfolder sits inside a code root, keep the root and add a REVIEW comment; splitting it needs a separate `read-only` entry and is the human's call. Extension keys such as `scripts` or `infra` are optional; add one only if the folder is something an agent would plausibly be sent to, and prefer fewer keys. Omit a key rather than point it at a path that does not exist. -- **access**: default is `read-write`, so leave it out. Add `{ path, access: read-only }` only when the repo says so: a README or contributing note, CODEOWNERS, a `.gitattributes` generated/vendored entry, or a header comment in the folder. A folder name alone is not evidence. If you are guessing, do not mark it; put a REVIEW comment instead. Never invent other fields on paths. -- **description**: one line each for the workspace and for every node. Descriptions are for humans. -- **nodes**: see admission below. An empty `nodes: []` is a normal, valid answer for a standalone repository. -- Skip `relations`, `overlays`, `profiles`, `mirror`, `write` unless the user asks for them. They are optional and make the L0 file bigger. - -### 3. Node admission - -A node is a direct navigation hop: another repository or product someone is likely to open during a normal change here. Admit a candidate only if you can state one reason and point at local evidence: - -| Reason | Evidence in this repo | -|---|---| -| calls it at runtime | client, endpoint or env/config naming the other service | -| owns a contract this repo consumes | schema, API definition, generated client, shared types sourced from it | -| current reference | design source, requirements or spec repo that the README names as the source of truth | -| intentionally shared convention | maintained import or sync workflow, not a one-time copy | - -Do not admit something because it is mentioned in a README, is a transitive dependency, is a package manager dependency (third-party libraries are not nodes), was a one-time scaffold source, or is only conceptually related. Put such context in the README instead. - -For a node you do admit: - -- `kind`: `repository` for another repo you could check out, `external` for something you only read about. `kind` is free text; use these two unless the project has its own word. -- `locator.repo` or `locator.url` only with a value copied verbatim from `.gitmodules`, a git remote, the README or client config. If the repo does not state it, omit `locator` and add a REVIEW comment. Never guess an organization or host. A different branch or fork of this same repository is not a node. `path` only if it is checked out inside this tree (submodule, vendored folder). -- `map.path: .aap/map.yaml` only if you saw that file in that repository. Otherwise omit `map`. -- For `external` or consume-only hops add `access: read-only`. -- `description`: what is consulted there and when. - -Workspace roots made of several packages in one repository: do not create one node per package by default. Use `layout.code` as a list. Add nodes for packages only if the user wants per-package maps. - -### 4. Mark uncertainty - -You cannot ask the schema about uncertainty, and the schema forbids unknown fields, so use YAML comments. Put `# REVIEW:` directly above or beside every line you are not sure about, with the reason: - -```yaml -layout: - code: src/ - # REVIEW: tests live in both tests/ and src/**/__tests__; only tests/ listed - tests: tests/ -nodes: - # REVIEW: only a README mention, no client config found. Remove if not a normal-change hop. - - id: billing-service - kind: external - access: read-only -``` +Leave out `relations`, `overlays`, `profiles`, `mirror`, `write` unless asked. -Edit the file textually. Do not load it into a YAML library and dump it back, which deletes comments. Keep REVIEW comments for uncertainty only; put plain notes in your report. Mark for review at minimum: every node, every `read-only` you chose, any layout path you could not verify exists, any slugified id, any key where two folders competed. +## Flag guesses -### 5. Validate +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. -Nothing here needs an install. Use the highest level that works on this machine and say which one you used. +## Checking it (optional) -**Level 1, always: manual checklist.** Check the file yourself against these rules (they are the whole schema): +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`, and `workspace`, `self` and `nodes` all present. `nodes` is a list (`[]` is fine). -- `workspace` has only `id` and `description`. `self` has `id`, `kind` and optionally `path`, `description`, `parent`. -- Every id (`workspace.id`, `self.id`, node ids, `parent.id`) matches `^[a-z][a-z0-9-]*$`. -- Every layout value is a path string, or `{ path, access?, description? }`, or a non-empty list of those. `access` is `read-only` or `read-write` and nothing else. -- Paths are relative: no leading `/`, no `..`, no `~`, no backslashes, no Windows drive letters. -- A node has `id` and `kind`, and only these other fields: `description`, `path`, `locator`, `map`, `mirror`, `access`, `write`. `locator` needs `repo`, `url` or `id`. `map` needs `path` or `url`. -- No unknown fields anywhere, except extra keys under `layout`. Descriptions are quoted strings. -- Every path in the map exists on disk (check with `ls`), or is flagged with a REVIEW comment. +- `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 `..`. -**Level 2, if `python3` is on the machine: bundled script.** It uses only the Python standard library. +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. -```bash -python3 /absolute/path/to/aap-map/scripts/validate_map.py .aap/map.yaml -``` +## Report -(On Windows use `py -3`.) Output contract: +Plain and short: ```text -VALIDATION_SUCCESS -WARN ... (zero or more; informational) -REVIEW_MARKERS N (lines ...) -# or -VALIDATION_FAILED -- path: /nodes/0/id | message: ... +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. ``` -The script reads a deliberately small YAML subset. If it answers "unsupported YAML", rewrite the map in plain block style (indented `key: value` lines, quoted strings) and run it again; that is not a schema error. - -**Level 3, optional, for AAP maintainers: full JSON Schema.** The AAP repository's `scripts/validate.py` uses `jsonschema` against `schemas/map.schema.json`. Do not install anything to reach this level unless the user asks. `uv run --with pyyaml --with jsonschema python3 scripts/validate.py` runs it without touching the project's environment. - -On failure at level 2, patch the file from the path and message and run again. Stop after 5 rounds and report what is still failing. Do not weaken the schema or edit the bundled copy to make a map pass. - -If you could only do level 1, the map is "checked by hand, not by a machine": say that, never call it validated, and give the user the level 2 command to run later. - -### 6. Hand over for review - -Do not claim the map is done. End with this report, plainly: - -```text -## aap-map result -- file: .aap/map.yaml (new | unchanged | proposed diff) -- validation level actually run: 1 manual checklist | 2 bundled script (PASS or FAIL) | 3 full JSON Schema (PASS or FAIL). If 2 or 3 could not run, say why. Only 2 or 3 may be called "validated". -- layout keys: (each with the evidence you used) -- nodes accepted: N (id, reason) / candidates rejected: N (name as seen in the repo, why; list only candidates you actually saw) -- REVIEW markers: N (list the lines) -- ids changed by slugifying: -- needs a human decision: -``` - -If the user asked for machine-local overlays, put them in a sibling `map.local.yaml` next to the map and add it to `.gitignore` (if the project uses git). Otherwise leave `.gitignore` alone. +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. If the tree is self-explanatory, `code` and `tests` are enough. -- A dependency graph. Libraries and transitive services stay out. -- A place for procedures, conventions or essays. Those go in `AGENTS.md`, README or docs. -- A permission system. `access` is a note between humans and agents, not enforcement. -- A speculative structure. If the project has no durable notes folder, say so and leave `artifacts` out unless the user asks to create one. - -## Reading an existing map (for reference) - -- Write home for a layout key is the first entry whose access is not `read-only`. If there is none, fail closed and ask. -- `overlays` and `map.local.yaml` say where a node is checked out on this machine. They never grant write rights. -- A node `write: [...]` list is a role hint, not a permission. +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/skills/aap-map/TEST-NOTES.md b/skills/aap-map/TEST-NOTES.md deleted file mode 100644 index 7104d17..0000000 --- a/skills/aap-map/TEST-NOTES.md +++ /dev/null @@ -1,47 +0,0 @@ -# aap-map test notes - -Tested 2026-10-28 on three public projects of different shape, cloned shallow into a scratch directory. In each run a fresh agent received only `SKILL.md` and followed it literally, with the validator and bundled schema. A separate reviewer then read the files looking for assumptions inherited from the private convention the skill grew out of. - -| Project | Shape | Result map | Validator | REVIEW markers | Tool calls | -|---|---|---|---|---|---| -| chalk | small JS library, flat | `code: source/`, `tests: test/`, `nodes: []` | pass (after one fix) | 2 | ~12 | -| requests | Python library, `src/` layout, Sphinx docs | `code: src/requests/`, `tests: tests/`, `nodes: []` | pass (after one fix) | 0 | 5 | -| changesets | pnpm TypeScript monorepo, 21 packages | `code: packages/`, `artifacts: docs/`, extension key `site`, `nodes: []` | pass | 4 | ~7 | - -No run admitted a node. Third-party libraries and README mentions were rejected, which is the intended outcome for standalone repositories. - -## What broke or was ambiguous, and what changed - -| Finding | Seen in | Change | -|---|---|---| -| The shape example used flow style. A description containing a comma split the value and the validator reported "additional properties", naming the stray key, not the cause. | chalk, requests | Example is now block style; descriptions must be quoted. | -| `src/` versus `src/requests/` for `code` unspecified | requests | Rule: confirm with `ls`, pick the folder that holds the code. | -| 21 packages: a list of 21 paths is absurd, globs are not supported | changesets | Use the parent folder plus a REVIEW comment; no globs. | -| Tests colocated with code, no tests folder; agent guessed a nearby folder | changesets | Omit `tests` rather than guess. | -| Published docs site versus durable notes for `artifacts` | requests, changesets | `artifacts` means working notes (ADRs, decisions, specs), not a docs website. | -| Vendored folder inside the code root; unclear how to mark read-only | chalk | Keep the root, add a REVIEW comment; splitting is the human's call. | -| Branch of the same repository mentioned in the README | changesets | Not a node. | -| File lookup was case sensitive (`readme.md`) | chalk | Case-insensitive. | -| Informational notes inflated the REVIEW count | chalk | REVIEW comments are for uncertainty only; notes go in the report. | -| Rejected candidates have no id | chalk, changesets | Report them by name as seen in the repo. | -| Validator printed line numbers not in the output contract | chalk, changesets | Contract updated. | -| Extension keys (`site`, `examples`) tempt the agent to list every folder | chalk, changesets | Optional, fewer is better. | - -Reviewer findings applied: do not assume a git repo; do not guess `locator.repo` or the host; `read-only` needs written evidence, a folder name is not enough; slugify ids without reordering words; edit the map textually so comments survive; validator warns on absolute, `~`, backslash and `..` paths in `self.path`, `node.path` and `map.path` (the schema only checks layout paths); validator sort no longer crashes on mixed index and key error paths; REVIEW marker count matches only YAML comments; `python3` / `py -3` and absolute script path; honest "validation NOT RUN" fallback; do not create a second map next to an existing one. - -## Validator without dependencies (second pass) - -The first version of the skill required PyYAML and jsonschema, which is a poor ask for a skill that should work on any machine. The skill now has three levels: a manual checklist (always possible), a standard-library `python3` script with its own small YAML reader (no installs), and the full `jsonschema` check kept for the AAP repository itself. The report states which level actually ran, and only levels 2 and 3 may be called "validated". - -Safety net: `scripts/validate.py` runs the standard-library validator and PyYAML plus jsonschema over every valid example, every invalid fixture and 20 mutated maps. It fails if they disagree on accept or reject, or if the standard-library reader parses a file differently from PyYAML. The three maps produced in the tests above were rechecked with the new script and give the same results. - -Unsupported YAML (anchors, tags, multi-line plain scalars, tabs, multi-line flow collections) is rejected with a message asking for block style, not guessed at. - -## Known limits - -- Tested with Claude subagents only. Other agents were not tried. -- The schema's `pathString` pattern rejects any path containing `..` even as part of a name (`a..b`). That is the schema's behavior and was left alone. -- `layout` paths are literal. There are no globs, so large monorepos get a coarse parent folder. -- The bundled schema keeps its original `$id`. A CI check in `scripts/validate.py` keeps it identical to `schemas/map.schema.json`. -- The standard-library validator was tested on macOS with Python 3.15 only. Older Python 3 versions and Windows were not tried. -- Not tested: Windows, a machine with no network and no Python, and a repository that already has a map. diff --git a/skills/aap-map/schema/map.schema.json b/skills/aap-map/schema/map.schema.json deleted file mode 100644 index 94ddf71..0000000 --- a/skills/aap-map/schema/map.schema.json +++ /dev/null @@ -1,225 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://gist.githubusercontent.com/gitpash/928c100ebf269acf9db7c09a18ed4a68/raw/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.", - "type": "object", - "additionalProperties": false, - "required": ["version", "workspace", "self", "nodes"], - "properties": { - "version": { - "type": "integer", - "enum": [2], - "description": "Map format version 2 — semantic surface router. Still 2: resourceRef is additive (string paths remain valid)." - }, - "workspace": { - "type": "object", - "additionalProperties": false, - "required": ["id"], - "properties": { - "id": { "$ref": "#/$defs/id" }, - "description": { "type": "string" } - } - }, - "self": { - "type": "object", - "additionalProperties": false, - "required": ["id", "kind"], - "properties": { - "id": { "$ref": "#/$defs/id" }, - "kind": { "type": "string", "minLength": 1 }, - "path": { "type": "string", "minLength": 1 }, - "description": { "type": "string" }, - "parent": { "$ref": "#/$defs/parentObject" } - } - }, - "layout": { "$ref": "#/$defs/layoutObject" }, - "nodes": { - "type": "array", - "items": { "$ref": "#/$defs/nodeObject" } - }, - "relations": { - "type": "array", - "description": "Optional local topology hints — not a global dependency graph.", - "items": { "$ref": "#/$defs/relationObject" } - }, - "overlays": { - "type": "object", - "additionalProperties": false, - "description": "Prefer map.local.yaml (gitignored) for absolute checkout paths.", - "properties": { - "nodes": { - "type": "object", - "propertyNames": { "$ref": "#/$defs/id" }, - "additionalProperties": { - "type": "object", - "additionalProperties": false, - "properties": { - "path": { "type": "string", "minLength": 1 } - } - } - }, - "local_paths": { - "type": "object", - "propertyNames": { "$ref": "#/$defs/id" }, - "additionalProperties": { "type": "string", "minLength": 1 } - } - } - }, - "profiles": { - "type": "object", - "additionalProperties": false, - "properties": { - "enabled": { - "type": "array", - "items": { "type": "string", "minLength": 1 } - } - } - } - }, - "$defs": { - "id": { - "type": "string", - "pattern": "^[a-z][a-z0-9-]*$", - "minLength": 1 - }, - "pathString": { - "type": "string", - "minLength": 1, - "pattern": "^(?!.*\\.\\.)(?!/).*$", - "description": "Path relative to workspace root; / separators; no .. or absolute." - }, - "access": { - "type": "string", - "enum": ["read-only", "read-write"], - "description": "Shared permission class. read-only = agents MUST NOT write/create durable content here; read still allowed. Default when omitted: read-write. Human lifecycle words (legacy/deprecated) belong in description, not a separate enum." - }, - "resourceRef": { - "oneOf": [ - { "$ref": "#/$defs/pathString" }, - { - "type": "object", - "additionalProperties": false, - "required": ["path"], - "properties": { - "path": { "$ref": "#/$defs/pathString" }, - "access": { "$ref": "#/$defs/access" }, - "description": { - "type": "string", - "description": "Optional human note only. Agents gate on access, not on this text." - } - } - } - ], - "description": "Addressable path resource. String shorthand ≡ { path: , access: read-write }. Object form adds optional access (same enum as nodes)." - }, - "pathOrPaths": { - "oneOf": [ - { "$ref": "#/$defs/resourceRef" }, - { - "type": "array", - "minItems": 1, - "items": { "$ref": "#/$defs/resourceRef" } - } - ], - "description": "One resourceRef or a list. Write home = first entry whose access is not read-only (after normalize)." - }, - "layoutObject": { - "type": "object", - "description": "Intent → path router. Values are resourceRef(s). Known keys are hints; additionalProperties allowed for 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" }, - "devops": { "$ref": "#/$defs/pathOrPaths" } - }, - "additionalProperties": { "$ref": "#/$defs/pathOrPaths" } - }, - "mapPointerObject": { - "type": "object", - "additionalProperties": false, - "properties": { - "path": { "type": "string", "minLength": 1 }, - "url": { "type": "string", "minLength": 1 }, - "ref": { "type": "string", "minLength": 1 } - }, - "anyOf": [ - { "required": ["path"] }, - { "required": ["url"] } - ] - }, - "locatorObject": { - "type": "object", - "additionalProperties": false, - "properties": { - "repo": { "type": "string", "minLength": 1 }, - "url": { "type": "string", "minLength": 1 }, - "id": { "type": "string", "minLength": 1 }, - "default_branch": { "type": "string" } - }, - "anyOf": [ - { "required": ["repo"] }, - { "required": ["url"] }, - { "required": ["id"] } - ] - }, - "parentObject": { - "type": "object", - "additionalProperties": false, - "required": ["id"], - "description": "Optional immediate navigation parent. Groups the current repository for orientation; does not imply ownership, authorization, inherited policy, or recursive traversal.", - "properties": { - "id": { "$ref": "#/$defs/id" }, - "locator": { "$ref": "#/$defs/locatorObject" }, - "map": { "$ref": "#/$defs/mapPointerObject" } - } - }, - "mirrorObject": { - "type": "object", - "additionalProperties": false, - "properties": { - "path": { "type": "string", "minLength": 1 } - }, - "required": ["path"] - }, - "nodeObject": { - "type": "object", - "additionalProperties": false, - "required": ["id", "kind"], - "properties": { - "id": { "$ref": "#/$defs/id" }, - "kind": { "type": "string", "minLength": 1 }, - "description": { "type": "string" }, - "path": { "type": "string", "minLength": 1 }, - "locator": { "$ref": "#/$defs/locatorObject" }, - "map": { "$ref": "#/$defs/mapPointerObject" }, - "mirror": { "$ref": "#/$defs/mirrorObject" }, - "access": { - "$ref": "#/$defs/access", - "description": "Same permission class as resourceRef.access. External consume-only hops use read-only." - }, - "write": { - "type": "array", - "items": { "type": "string", "minLength": 1 }, - "description": "Optional role hints (e.g. domain, architect). NOT a filesystem ACL — use access for write fence. Empty/absent is not a grant by itself." - } - } - }, - "relationObject": { - "type": "object", - "additionalProperties": false, - "required": ["from", "to", "type"], - "properties": { - "from": { "$ref": "#/$defs/id" }, - "to": { "$ref": "#/$defs/id" }, - "type": { "type": "string", "minLength": 1 }, - "description": { "type": "string" } - } - } - } -} diff --git a/skills/aap-map/scripts/validate_map.py b/skills/aap-map/scripts/validate_map.py deleted file mode 100644 index 462d0c0..0000000 --- a/skills/aap-map/scripts/validate_map.py +++ /dev/null @@ -1,504 +0,0 @@ -#!/usr/bin/env python3 -"""Validate an AAP Map v2 file with nothing but the Python 3 standard library. - -Usage: python3 validate_map.py [MAP] [--root DIR] - -MAP defaults to .aap/map.yaml. Exit codes: 0 valid, 1 invalid, 2 setup problem. - -This is a hand-written check of the Map v2 schema plus a small YAML reader for -the subset a map needs: block mappings and sequences, flow {} and [] values, -quoted and plain scalars, comments, and | or > block scalars. Anything else -(anchors, tags, multi-line plain scalars, tabs) is rejected on purpose with -"unsupported YAML"; rewrite the map in block style. The full JSON Schema check -(scripts/validate.py in the AAP repo) is the reference; CI runs both on the -same fixtures so they cannot drift apart. -""" -from __future__ import annotations - -import argparse -import re -import sys -from pathlib import Path - -ID = re.compile(r"^[a-z][a-z0-9-]*$") -KEY_RE = ( - r'^("(?:[^"\\]|\\.)*"' # double-quoted key - r"|'[^']*'" # single-quoted key - r"|[^\s:#\"'\[{][^:#]*?)" # plain key - r"\s*:(?:\s+(.*)|$)" -) - - -class YamlError(Exception): - pass - - -# ---------------------------------------------------------------- YAML subset - -def strip_comment(line: str) -> str: - quote = "" - for i, ch in enumerate(line): - if quote: - if ch == quote: - quote = "" - elif ch in "\"'" and (i == 0 or line[i - 1] in " \t:[{,-"): - quote = ch - elif ch == "#" and (i == 0 or line[i - 1] in " \t"): - return line[:i] - return line.rstrip() - - -def scalar(text: str): - t = text.strip() - if t == "": - return None - if t[0] == '"': - if len(t) < 2 or t[-1] != '"': - raise YamlError(f"unterminated double quote: {t[:40]}") - return re.sub(r'\\(["\\/])', r"\1", t[1:-1]).replace("\\n", "\n").replace("\\t", "\t") - if t[0] == "'": - if len(t) < 2 or t[-1] != "'": - raise YamlError(f"unterminated single quote: {t[:40]}") - return t[1:-1].replace("''", "'") - if t[0] in "&*!@`%": - raise YamlError(f"unsupported YAML (anchors, tags, aliases): {t[:40]}") - if t in ("null", "~", "Null", "NULL"): - return None - if t in ("true", "True", "TRUE"): - return True - if t in ("false", "False", "FALSE"): - return False - if re.fullmatch(r"-?\d+", t): - return int(t) - if t[0] in "{[": - return flow(t) - return t - - -def flow(text: str): - pos = 0 - - def skip() -> None: - nonlocal pos - while pos < len(text) and text[pos] in " \t": - pos += 1 - - def value(stop: str): - nonlocal pos - skip() - if pos >= len(text): - raise YamlError("unterminated flow collection") - ch = text[pos] - if ch == "{": - pos += 1 - out: dict = {} - skip() - if text[pos:pos + 1] == "}": - pos += 1 - return out - while True: - key = value(":") - skip() - if text[pos:pos + 1] != ":": - raise YamlError("flow mapping key without ':' (quote values that contain commas, colons or #, or use block style)") - pos += 1 - out[key] = value(",}") - skip() - if text[pos:pos + 1] == ",": - pos += 1 - continue - if text[pos:pos + 1] == "}": - pos += 1 - return out - raise YamlError("bad flow mapping") - if ch == "[": - pos += 1 - items: list = [] - skip() - if text[pos:pos + 1] == "]": - pos += 1 - return items - while True: - items.append(value(",]")) - skip() - if text[pos:pos + 1] == ",": - pos += 1 - continue - if text[pos:pos + 1] == "]": - pos += 1 - return items - raise YamlError("bad flow sequence") - if ch in "\"'": - end = pos + 1 - while end < len(text) and text[end] != ch: - end += 1 - if end >= len(text): - raise YamlError("unterminated quote in flow collection") - raw = text[pos:end + 1] - pos = end + 1 - return scalar(raw) - start = pos - while pos < len(text) and text[pos] not in stop: - pos += 1 - return scalar(text[start:pos]) - - result = value("") - skip() - if pos != len(text): - raise YamlError(f"unexpected text after flow value: {text[pos:pos + 30]}") - return result - - -def parse_yaml(source: str): - if "\t" in source: - raise YamlError("unsupported YAML: tab characters (use spaces)") - raw = source.splitlines() - lines: list[tuple[int, str, int]] = [] # (indent, text, original index) - for n, line in enumerate(raw): - stripped = strip_comment(line) - if stripped.strip() == "" or stripped.strip() in ("---", "..."): - continue - lines.append((len(stripped) - len(stripped.lstrip(" ")), stripped.strip(), n)) - if not lines: - raise YamlError("empty document") - pos = 0 - - def block_scalar(indent: int, style: str, header_line: int) -> str: - nonlocal pos - body = [] - n = header_line + 1 - while n < len(raw) and (raw[n].strip() == "" or len(raw[n]) - len(raw[n].lstrip(" ")) > indent): - body.append(raw[n].strip()) - n += 1 - while pos < len(lines) and lines[pos][2] < n: - pos += 1 - joined = ("\n" if style.startswith("|") else " ").join(body).strip() - return joined - - def split_key(text: str): - m = re.match(KEY_RE, text) - if not m: - return None - key = scalar(m.group(1)) - return key, (m.group(2) or "") - - def value_of(rest: str, indent: int, line_no: int): - nonlocal pos - if rest in ("|", ">", "|-", ">-", "|+", ">+"): - return block_scalar(indent, rest, line_no) - if rest == "": - if pos < len(lines) and (lines[pos][0] > indent or (lines[pos][0] == indent and lines[pos][1].startswith("- "))): - return parse_block(lines[pos][0]) - return None - if rest[0] in "{[" and not (rest.endswith("}") or rest.endswith("]")): - raise YamlError(f"unsupported YAML: multi-line flow collection at line {line_no + 1}") - val = scalar(rest) - if pos < len(lines) and lines[pos][0] > indent and not isinstance(val, (dict, list)): - raise YamlError(f"unsupported YAML: multi-line plain scalar near line {lines[pos][2] + 1}; quote it on one line") - return val - - def parse_block(indent: int): - nonlocal pos - indent_now, text, _ = lines[pos] - if text.startswith("- ") or text == "-": - seq: list = [] - while pos < len(lines) and lines[pos][0] == indent and (lines[pos][1].startswith("- ") or lines[pos][1] == "-"): - _, t, ln = lines[pos] - rest = t[1:].strip() - pos += 1 - kv = split_key(rest) if rest and rest[0] not in "{[" else None - if kv is not None: - # "- key: value": re-inject as a mapping indented past the dash - offset = len(t) - len(rest) - lines.insert(pos, (indent + offset, rest, ln)) - seq.append(parse_block(indent + offset)) - elif rest == "": - seq.append(parse_block(lines[pos][0]) if pos < len(lines) and lines[pos][0] > indent else None) - else: - seq.append(value_of(rest, indent, ln)) - return seq - out: dict = {} - while pos < len(lines) and lines[pos][0] == indent: - _, t, ln = lines[pos] - if t.startswith("- "): - break - kv = split_key(t) - if kv is None: - raise YamlError(f"unsupported YAML or not a mapping at line {ln + 1}: {t[:50]}") - key, rest = kv - pos += 1 - if key in out: - raise YamlError(f"duplicate key '{key}' at line {ln + 1}") - out[key] = value_of(rest, indent, ln) - if pos < len(lines) and lines[pos][0] > indent: - raise YamlError(f"unexpected indentation at line {lines[pos][2] + 1}") - return out - - doc = parse_block(lines[0][0]) - if pos < len(lines): - raise YamlError(f"unexpected content at line {lines[pos][2] + 1}: {lines[pos][1][:50]}") - return doc - - -# --------------------------------------------------------------- schema rules - -def is_str(v) -> bool: - return isinstance(v, str) and v != "" - - -def check_path(v, where, errs, allow_empty=False): - if not isinstance(v, str) or (v == "" and not allow_empty): - errs.append((where, "must be a non-empty string")) - elif v.startswith("/") or ".." in v: - errs.append((where, f"must be workspace-relative with no '..' (got {v!r})")) - - -def check_id(v, where, errs): - if not (isinstance(v, str) and ID.match(v)): - errs.append((where, f"id must match ^[a-z][a-z0-9-]*$ (got {v!r})")) - - -def check_keys(obj, where, allowed, required, errs): - if not isinstance(obj, dict): - errs.append((where, "must be a mapping")) - return False - for k in obj: - if k not in allowed: - errs.append((f"{where}/{k}", "additional property not allowed")) - for k in required: - if k not in obj: - errs.append((where, f"missing required property '{k}'")) - return True - - -def check_access(v, where, errs): - if v not in ("read-only", "read-write"): - errs.append((where, "access must be 'read-only' or 'read-write'")) - - -def check_resource(v, where, errs): - if isinstance(v, str): - check_path(v, where, errs) - elif isinstance(v, dict): - if check_keys(v, where, {"path", "access", "description"}, ["path"], errs): - if "path" in v: - check_path(v["path"], f"{where}/path", errs) - if "access" in v: - check_access(v["access"], f"{where}/access", errs) - if "description" in v and not isinstance(v["description"], str): - errs.append((f"{where}/description", "must be a string")) - else: - errs.append((where, "must be a path string or {path, access?, description?}")) - - -def check_locator(v, where, errs): - if check_keys(v, where, {"repo", "url", "id", "default_branch"}, [], errs): - for k in ("repo", "url", "id"): - if k in v and not is_str(v[k]): - errs.append((f"{where}/{k}", "must be a non-empty string")) - if not any(k in v for k in ("repo", "url", "id")): - errs.append((where, "needs at least one of repo, url, id")) - - -def check_mappointer(v, where, errs): - if check_keys(v, where, {"path", "url", "ref"}, [], errs): - for k in ("path", "url", "ref"): - if k in v and not is_str(v[k]): - errs.append((f"{where}/{k}", "must be a non-empty string")) - if not ("path" in v or "url" in v): - errs.append((where, "needs path or url")) - - -def schema_errors(d) -> list[tuple[str, str]]: - errs: list[tuple[str, str]] = [] - top = {"version", "workspace", "self", "layout", "nodes", "relations", "overlays", "profiles"} - if not check_keys(d, "", top, ["version", "workspace", "self", "nodes"], errs): - return errs - if d.get("version") != 2 or isinstance(d.get("version"), bool): - errs.append(("/version", "must be the integer 2")) - ws = d.get("workspace") - if check_keys(ws, "/workspace", {"id", "description"}, ["id"], errs): - if "id" in ws: - check_id(ws["id"], "/workspace/id", errs) - if "description" in ws and not isinstance(ws["description"], str): - errs.append(("/workspace/description", "must be a string")) - me = d.get("self") - if check_keys(me, "/self", {"id", "kind", "path", "description", "parent"}, ["id", "kind"], errs): - if "id" in me: - check_id(me["id"], "/self/id", errs) - for k in ("kind", "path"): - if k in me and not is_str(me[k]): - errs.append((f"/self/{k}", "must be a non-empty string")) - if "description" in me and not isinstance(me["description"], str): - errs.append(("/self/description", "must be a string")) - if "parent" in me: - p = me["parent"] - if check_keys(p, "/self/parent", {"id", "locator", "map"}, ["id"], errs): - if "id" in p: - check_id(p["id"], "/self/parent/id", errs) - if "locator" in p: - check_locator(p["locator"], "/self/parent/locator", errs) - if "map" in p: - check_mappointer(p["map"], "/self/parent/map", errs) - layout = d.get("layout") - if "layout" in d: - if not isinstance(layout, dict): - errs.append(("/layout", "must be a mapping")) - else: - for k, v in layout.items(): - if isinstance(v, list): - if not v: - errs.append((f"/layout/{k}", "list must not be empty")) - for i, item in enumerate(v): - check_resource(item, f"/layout/{k}/{i}", errs) - else: - check_resource(v, f"/layout/{k}", errs) - nodes = d.get("nodes") - if not isinstance(nodes, list): - errs.append(("/nodes", "must be a list (use 'nodes: []' for none)")) - else: - allowed = {"id", "kind", "description", "path", "locator", "map", "mirror", "access", "write"} - for i, n in enumerate(nodes): - w = f"/nodes/{i}" - if not check_keys(n, w, allowed, ["id", "kind"], errs): - continue - if "id" in n: - check_id(n["id"], f"{w}/id", errs) - for k in ("kind", "path"): - if k in n and not is_str(n[k]): - errs.append((f"{w}/{k}", "must be a non-empty string")) - if "description" in n and not isinstance(n["description"], str): - errs.append((f"{w}/description", "must be a string")) - if "locator" in n: - check_locator(n["locator"], f"{w}/locator", errs) - if "map" in n: - check_mappointer(n["map"], f"{w}/map", errs) - if "mirror" in n: - m = n["mirror"] - if check_keys(m, f"{w}/mirror", {"path"}, ["path"], errs) and "path" in m and not is_str(m["path"]): - errs.append((f"{w}/mirror/path", "must be a non-empty string")) - if "access" in n: - check_access(n["access"], f"{w}/access", errs) - if "write" in n: - wr = n["write"] - if not isinstance(wr, list) or not all(is_str(x) for x in wr): - errs.append((f"{w}/write", "must be a list of non-empty strings")) - if "relations" in d: - rel = d["relations"] - if not isinstance(rel, list): - errs.append(("/relations", "must be a list")) - else: - for i, r in enumerate(rel): - w = f"/relations/{i}" - if check_keys(r, w, {"from", "to", "type", "description"}, ["from", "to", "type"], errs): - for k in ("from", "to"): - if k in r: - check_id(r[k], f"{w}/{k}", errs) - if "type" in r and not is_str(r["type"]): - errs.append((f"{w}/type", "must be a non-empty string")) - if "description" in r and not isinstance(r["description"], str): - errs.append((f"{w}/description", "must be a string")) - if "overlays" in d: - o = d["overlays"] - if check_keys(o, "/overlays", {"nodes", "local_paths"}, [], errs): - if "nodes" in o: - on = o["nodes"] - if not isinstance(on, dict): - errs.append(("/overlays/nodes", "must be a mapping")) - else: - for k, v in on.items(): - check_id(k, f"/overlays/nodes/{k}", errs) - if check_keys(v, f"/overlays/nodes/{k}", {"path"}, [], errs) and "path" in v and not is_str(v["path"]): - errs.append((f"/overlays/nodes/{k}/path", "must be a non-empty string")) - if "local_paths" in o: - lp = o["local_paths"] - if not isinstance(lp, dict): - errs.append(("/overlays/local_paths", "must be a mapping")) - else: - for k, v in lp.items(): - check_id(k, f"/overlays/local_paths/{k}", errs) - if not is_str(v): - errs.append((f"/overlays/local_paths/{k}", "must be a non-empty string")) - if "profiles" in d: - p = d["profiles"] - if check_keys(p, "/profiles", {"enabled"}, [], errs) and "enabled" in p: - if not isinstance(p["enabled"], list) or not all(is_str(x) for x in p["enabled"]): - errs.append(("/profiles/enabled", "must be a list of non-empty strings")) - return errs - - -# ----------------------------------------------------------------------- main - -def layout_refs(value): - for item in value if isinstance(value, list) else [value]: - if isinstance(item, str): - yield item, True - elif isinstance(item, dict) and isinstance(item.get("path"), str): - yield item["path"], item.get("access", "read-write") != "read-only" - - -def validate_text(text: str) -> tuple[list[tuple[str, str]], object]: - """Return (errors, parsed document). Used by the AAP repo's CI as well.""" - try: - data = parse_yaml(text) - except YamlError as error: - return [("/", f"{error}")], None - return schema_errors(data), data - - -def main() -> None: - ap = argparse.ArgumentParser() - ap.add_argument("map", nargs="?", default=".aap/map.yaml") - ap.add_argument("--root", help="workspace root for path checks (default: parent of .aap/, else map dir)") - args = ap.parse_args() - map_path = Path(args.map) - if not map_path.is_file(): - print(f"SETUP_ERROR: map not found: {map_path}", file=sys.stderr) - raise SystemExit(2) - text = map_path.read_text(encoding="utf-8") - errors, data = validate_text(text) - if errors: - print("VALIDATION_FAILED") - for pointer, message in errors: - print(f"- path: {pointer or '/'} | message: {message[:200]}") - raise SystemExit(1) - - here = map_path.resolve().parent - root = Path(args.root) if args.root else (here.parent if here.name == ".aap" else here) - warnings: list[str] = [] - for key, value in (data.get("layout") or {}).items(): - entries = list(layout_refs(value)) - for path, _ in entries: - if not (root / path).exists(): - warnings.append(f"layout.{key}: '{path}' does not exist on disk (fine if intended, otherwise fix or drop)") - if entries and not any(w for _, w in entries): - warnings.append(f"layout.{key}: no writable entry, agents will fail closed on durable writes") - seen: set[str] = set() - for i, node in enumerate(data.get("nodes") or []): - if node["id"] in seen: - warnings.append(f"nodes[{i}]: duplicate id '{node['id']}'") - seen.add(node["id"]) - if "path" in node and not (root / node["path"]).exists(): - warnings.append(f"nodes[{i}] ({node['id']}): path '{node['path']}' does not exist on disk") - if "description" not in node: - warnings.append(f"nodes[{i}] ({node['id']}): no description; say what is consulted there and when") - - def bad(v) -> bool: - return isinstance(v, str) and (v.startswith(("/", "~", "\\")) or re.match(r"^[A-Za-z]:", v) is not None - or "\\" in v or ".." in v.split("/")) - - cands = [("self.path", (data.get("self") or {}).get("path"))] - for i, node in enumerate(data.get("nodes") or []): - cands += [(f"nodes[{i}].path", node.get("path")), (f"nodes[{i}].map.path", (node.get("map") or {}).get("path"))] - for name, v in cands: - if bad(v): - warnings.append(f"{name}: '{v}' must be workspace-relative (no absolute, '~', backslash or '..'); machine paths belong in map.local.yaml") - review = [n + 1 for n, line in enumerate(text.splitlines()) if re.search(r"#\s*REVIEW:", line)] - print("VALIDATION_SUCCESS") - for w in warnings: - print(f"WARN {w}") - print(f"REVIEW_MARKERS {len(review)}" + (f" (lines {', '.join(map(str, review))})" if review else "")) - - -if __name__ == "__main__": - main() From 95b16db7f00904ddb8c7cc1efd91e570b088ca51 Mon Sep 17 00:00:00 2001 From: Pavel Luzanov Date: Wed, 28 Oct 2026 22:27:11 +0900 Subject: [PATCH 04/10] Remove v1 legacy material and incubator-only cookbook pages Deleted: legacy/v1 (history stays in git and the v0.1.1-draft tag), glass-box-factory, orchestrator-session (patterns not shipped here), what-not-to-copy (incubator provenance). Co-Authored-By: Claude Sonnet 5.5 --- CONTRIBUTING.md | 3 +- cookbook/done-bar.md | 1 - cookbook/glass-box-factory.md | 62 ------ cookbook/local-bootstrap.md | 1 - cookbook/orchestrator-session.md | 88 -------- cookbook/what-not-to-copy.md | 46 ----- .../invalid/internal-zone-without-path.yaml | 5 - .../invalid/layout-absolute-path.yaml | 7 - legacy/v1/examples/invalid/layout-dotdot.yaml | 7 - .../v1/examples/invalid/write-readonly.yaml | 5 - legacy/v1/examples/multi-zone/map.yaml | 42 ---- legacy/v1/examples/single-repo/map.yaml | 20 -- legacy/v1/schemas/map.schema.json | 188 ------------------ 13 files changed, 1 insertion(+), 474 deletions(-) delete mode 100644 cookbook/glass-box-factory.md delete mode 100644 cookbook/orchestrator-session.md delete mode 100644 cookbook/what-not-to-copy.md delete mode 100644 legacy/v1/examples/invalid/internal-zone-without-path.yaml delete mode 100644 legacy/v1/examples/invalid/layout-absolute-path.yaml delete mode 100644 legacy/v1/examples/invalid/layout-dotdot.yaml delete mode 100644 legacy/v1/examples/invalid/write-readonly.yaml delete mode 100644 legacy/v1/examples/multi-zone/map.yaml delete mode 100644 legacy/v1/examples/single-repo/map.yaml delete mode 100644 legacy/v1/schemas/map.schema.json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 298f180..e42bfed 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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/cookbook/done-bar.md b/cookbook/done-bar.md index 6287a6f..6697ada 100644 --- a/cookbook/done-bar.md +++ b/cookbook/done-bar.md @@ -90,4 +90,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/local-bootstrap.md b/cookbook/local-bootstrap.md index 9f4d91e..9e5dbb6 100644 --- a/cookbook/local-bootstrap.md +++ b/cookbook/local-bootstrap.md @@ -98,6 +98,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/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/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/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"] - } - } - ] - } - } -} From d4733be4797a66823880849669ea3c53c008f52b Mon Sep 17 00:00:00 2001 From: Pavel Luzanov Date: Wed, 28 Oct 2026 22:28:09 +0900 Subject: [PATCH 05/10] Restructure docs and drop status clutter Move MOTIVATION.md and the skill test notes under docs/, trim the pilot metrics sketch, replace the cookbook status table with a plain index, remove per-page 'Profile status' lines, update version strings to 0.3.0 and neutralise the schema description. No change to schema semantics. Co-Authored-By: Claude Sonnet 5.5 --- CONTRIBUTING.md | 6 ++-- README.md | 2 +- SPEC.md | 3 +- cookbook/README.md | 30 ++++++++----------- cookbook/brownfield-init.md | 4 +-- cookbook/ci-validation.md | 4 +-- cookbook/done-bar.md | 2 -- cookbook/hub-umbrella.md | 2 -- cookbook/local-bootstrap.md | 2 -- cookbook/measuring.md | 4 +-- cookbook/schema-pinning.md | 10 +++---- cookbook/stream-packs.md | 2 -- MOTIVATION.md => docs/motivation.md | 29 ++---------------- .../skill-tests.md | 0 schemas/map.schema.json | 2 +- 15 files changed, 31 insertions(+), 71 deletions(-) rename MOTIVATION.md => docs/motivation.md (53%) rename cookbook/aap-map-skill-tests.md => docs/skill-tests.md (100%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e42bfed..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 diff --git a/README.md b/README.md index ed33110..480415f 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ Coding agents often fail on **orientation** and **context pollution**, not on | No GPS | Multi-repo: path ≠ GitHub name; no clear hop | **Core** (nodes) | | Fake confidence | “PR ready” with red CI / invented blockers | ***Profile*** ([done-bar](./cookbook/done-bar.md)) | -**AAP’s bet** (thesis, not a measured claim here): a sparse map + disclosure beats a bigger prompt. See [`MOTIVATION.md`](./MOTIVATION.md). How to run an honest local A/B: [`cookbook/measuring.md`](./cookbook/measuring.md). +**AAP’s bet** (thesis, not a measured claim here): a sparse map + disclosure beats a bigger prompt. See [`docs/motivation.md`](./docs/motivation.md). How to run an honest local A/B: [`cookbook/measuring.md`](./cookbook/measuring.md). ```mermaid flowchart LR diff --git a/SPEC.md b/SPEC.md index 1962208..b11a2be 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. 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..186192d 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 diff --git a/cookbook/done-bar.md b/cookbook/done-bar.md index 6697ada..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. 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 9e5dbb6..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. 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/schema-pinning.md b/cookbook/schema-pinning.md index 815401e..868eb37 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,7 +51,7 @@ 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 ``` 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/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/cookbook/aap-map-skill-tests.md b/docs/skill-tests.md similarity index 100% rename from cookbook/aap-map-skill-tests.md rename to docs/skill-tests.md diff --git a/schemas/map.schema.json b/schemas/map.schema.json index 94ddf71..68bfda8 100644 --- a/schemas/map.schema.json +++ b/schemas/map.schema.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://gist.githubusercontent.com/gitpash/928c100ebf269acf9db7c09a18ed4a68/raw/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"], From 787af23a59e72d58ce1723fde73038b047a77d03 Mon Sep 17 00:00:00 2001 From: Pavel Luzanov Date: Wed, 28 Oct 2026 22:28:27 +0900 Subject: [PATCH 06/10] Packaging: align plugin manifests and llms.txt with the simplified skill The manifests still described the skill as validating maps. Bump plugin version to 0.3.0 and point llms.txt at the 0.3.0 tag and docs/motivation.md. Passes 'claude plugin validate . --strict'. Co-Authored-By: Claude Sonnet 5.5 --- .claude-plugin/marketplace.json | 4 ++-- .claude-plugin/plugin.json | 4 ++-- llms.txt | 14 +++++++------- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 78363b5..4cbf866 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,12 +1,12 @@ { "name": "agent-artifact-protocol", - "description": "Skills for the Agent Artifact Protocol (AAP)", + "description": "Skills for the Agent Artifact Protocol (AAP), a repository map for coding agents", "owner": { "name": "gitpash" }, "plugins": [ { "name": "aap", "source": "./", - "description": "aap-map: draft and validate a minimal .aap/map.yaml for any repository, with uncertain parts marked for human review." + "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 index 6deb31a..516c9c6 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "aap", - "version": "0.2.1", - "description": "Agent Artifact Protocol tooling: the aap-map skill drafts and validates a minimal .aap/map.yaml for any repository.", + "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", diff --git a/llms.txt b/llms.txt index 82d2f86..6ce04ce 100644 --- a/llms.txt +++ b/llms.txt @@ -2,7 +2,7 @@ > 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.2.1-prototype (experimental). Pin the tag `v0.2.1-prototype`; do not read the default branch tip as authoritative. +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 @@ -52,16 +52,16 @@ Until the user or runtime explicitly enables writes, prefer reading and orientin ## Where to read next (only when needed) -- Normative spec, short: https://github.com/gitpash/agent-artifact-protocol/blob/v0.2.1-prototype/SPEC.md -- Map JSON Schema (draft-07): https://raw.githubusercontent.com/gitpash/agent-artifact-protocol/v0.2.1-prototype/schemas/map.schema.json -- Starter map: https://raw.githubusercontent.com/gitpash/agent-artifact-protocol/v0.2.1-prototype/templates/minimal-map.yaml +- 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 paths are in the README section "Use with your agent". +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 @@ -72,6 +72,6 @@ The folder `skills/aap-map/` is a portable agent skill (one SKILL.md). It looks ## Optional -- Rationale: https://github.com/gitpash/agent-artifact-protocol/blob/v0.2.1-prototype/MOTIVATION.md -- Changelog: https://github.com/gitpash/agent-artifact-protocol/blob/v0.2.1-prototype/CHANGELOG.md +- 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 From 4b9928938632b06e8702763d6c46fe7a0cedc5e6 Mon Sep 17 00:00:00 2001 From: Pavel Luzanov Date: Wed, 28 Oct 2026 22:28:37 +0900 Subject: [PATCH 07/10] Dogfood: add .aap/map.yaml for this repository Written by following skills/aap-map/SKILL.md; validated against schemas/map.schema.json by scripts/validate.py, which now includes the map. Co-Authored-By: Claude Sonnet 5.5 --- .aap/map.yaml | 16 ++++++++++++++++ scripts/validate.py | 4 ++-- 2 files changed, 18 insertions(+), 2 deletions(-) create mode 100644 .aap/map.yaml 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/scripts/validate.py b/scripts/validate.py index 8cc0010..12de0b8 100644 --- a/scripts/validate.py +++ b/scripts/validate.py @@ -67,13 +67,13 @@ def main() -> None: 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)] From 0cbff154fb93b21141b21eeb6e1b2e119778ba6a Mon Sep 17 00:00:00 2001 From: Pavel Luzanov Date: Wed, 28 Oct 2026 22:29:24 +0900 Subject: [PATCH 08/10] Rewrite README for newcomers: one-click install first, honest status in one place Moves the conformance labels into SPEC.md so nothing normative lives only in the README. Co-Authored-By: Claude Sonnet 5.5 --- README.md | 342 ++++++++++-------------------------------------------- SPEC.md | 11 ++ 2 files changed, 70 insertions(+), 283 deletions(-) diff --git a/README.md b/README.md index 480415f..692c805 100644 --- a/README.md +++ b/README.md @@ -1,339 +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 | - -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. - ---- - -## Use with your agent - -**Give your LLM one link.** [`llms.txt`](./llms.txt) is written for an agent to read: what AAP is, what to open first, and the `access` rules. - -```text -https://raw.githubusercontent.com/gitpash/agent-artifact-protocol/main/llms.txt -``` - -Paste that into any chat or agent session and ask it to explain AAP or to work in a repo that has an `.aap/map.yaml`. It points to the spec and schema only for when they are needed. - -**Add a map to your own project with the `aap-map` skill.** The skill in [`skills/aap-map/`](./skills/aap-map/SKILL.md) is a single text file. It tells your agent how to look at a repository, write a minimal `.aap/map.yaml`, and say which parts it guessed (`# REVIEW:` comments). It does not interview you and it never overwrites an existing map. Say "ok" or ask for changes. Install it as a plain skill folder: +With the [`skills`](https://skills.sh) installer, which works for Claude Code, Codex, Cursor and many other agents: ```bash -# Claude Code, user-level -git clone --depth 1 https://github.com/gitpash/agent-artifact-protocol.git /tmp/aap -cp -R /tmp/aap/skills/aap-map ~/.claude/skills/aap-map +npx skills add gitpash/agent-artifact-protocol ``` -Then ask your agent: *"use the aap-map skill to add an AAP map to this repo"*. Nothing to install and nothing is validated by a tool at this point. If you want machine checking later, for example in CI, see [`cookbook/ci-validation.md`](./cookbook/ci-validation.md). - -Package layouts for skill installers and the Claude Code plugin marketplace (`.claude-plugin/`) are included in the repo, but the skill is not listed in any registry yet. - ---- +In Claude Code, from the plugin marketplace: -## What problem is this for? - -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 [`docs/motivation.md`](./docs/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 + access: read-only ``` -| 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. +- `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 `..`. -Full rules: [`SPEC.md`](./SPEC.md). +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). ---- +## How an agent uses it -## 60-second start (brownfield) +AAP asks for progressive disclosure in four levels, and only the first is required. -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). +| 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 | -**Pin** = which tag your copied templates came from. Nothing is fetched at agent runtime. Keep the pin visible in the map file: +Linked maps are hops taken on purpose and are never preloaded recursively. Until you enable writes, an agent should prefer reading and orienting only. -```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 -``` +## Beyond the basics -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). +- [`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). ---- - -## 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"] -``` - -| 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). - ---- - -## Vocabulary and conformance - -| Term | Meaning | -|------|---------| -| **Map** | Sparse description of the opened workspace | -| **Node** | Direct hop to a related repo/product | -| **self.parent** | Optional single navigation/container pointer ([SPEC](./SPEC.md)) | -| **Layout key** | `code`, `tests`, `artifacts`, `scratch`, … → resourceRef(s) | -| **resourceRef**, **`access`**, **`write`** | See [How it works §1](#1-one-small-map-in-your-repo) (canonical) | -| **Artifact** | Optional durable note (envelope when claiming addressability) | -| **Profile** | Optional cookbook elaboration — never mandatory L0 | - -| Conformance label | Means | -|-------------------|--------| -| **Orientation** | Discoverable sparse map; layout-based discovery possible | -| **Artifact** | Envelope field set when claiming addressability | -| **Topology** | Nodes are direct hops; listed paths are meant to resolve in the checkout | -| **Disclosure profile** *(optional)* | Streams / accept / thin orientation — not required for Orientation | - -```bash -pip install pyyaml jsonschema -python scripts/validate.py -``` - -This is a **convention + schemas**, not a complete cross-file protocol suite. - ---- - -## What’s in this repository - -```text -README.md SPEC.md MOTIVATION.md CONTRIBUTING.md CHANGELOG.md llms.txt -skills/aap-map/ # portable agent skill (one SKILL.md) -.claude-plugin/ # plugin + marketplace manifests (not published) -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 b11a2be..5b1c81a 100644 --- a/SPEC.md +++ b/SPEC.md @@ -154,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. From 281ea8145cee3b6200a87a6b3c52fde5614b172b Mon Sep 17 00:00:00 2001 From: Pavel Luzanov Date: Wed, 28 Oct 2026 22:29:35 +0900 Subject: [PATCH 09/10] CHANGELOG: 0.3.0 Co-Authored-By: Claude Sonnet 5.5 --- CHANGELOG.md | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2fabe32..ff92bc2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,11 +1,29 @@ # Changelog -## Unreleased +## 0.3.0 — 2026-10-28 -- `llms.txt`: agent-readable entry point (what AAP is, what to open first, `access` rules, links). -- `skills/aap-map/`: portable agent skill (one SKILL.md) that writes a minimal map and flags guesses for review. No scripts or dependencies; machine validation stays a CI choice (`cookbook/ci-validation.md`). -- `.claude-plugin/` manifests and a README section "Use with your agent". Nothing is published to any registry. -- `scripts/validate.py` also checks that the plugin manifests parse. +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`: the top-level `description` no longer says "Pilot". No change to validation. + +### 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 From e1c646fb44ea24e48486467eefb42ebadbf2feb8 Mon Sep 17 00:00:00 2001 From: Pavel Luzanov Date: Thu, 29 Oct 2026 18:15:15 +0900 Subject: [PATCH 10/10] Schema $id and editor hint: use the tagged raw URL instead of a gist Co-Authored-By: Claude Sonnet 5.5 --- CHANGELOG.md | 2 +- cookbook/ci-validation.md | 2 +- cookbook/schema-pinning.md | 4 ++-- schemas/map.schema.json | 2 +- templates/minimal-map.yaml | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ff92bc2..046c8c9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,7 +18,7 @@ First release with an agent entry point and an installable skill. The Map v2 sch - `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`: the top-level `description` no longer says "Pilot". No change to validation. +- `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 diff --git a/cookbook/ci-validation.md b/cookbook/ci-validation.md index 186192d..5e42d3c 100644 --- a/cookbook/ci-validation.md +++ b/cookbook/ci-validation.md @@ -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/schema-pinning.md b/cookbook/schema-pinning.md index 868eb37..11303e4 100644 --- a/cookbook/schema-pinning.md +++ b/cookbook/schema-pinning.md @@ -58,7 +58,7 @@ 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`. @@ -68,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/schemas/map.schema.json b/schemas/map.schema.json index 68bfda8..7c13ef2 100644 --- a/schemas/map.schema.json +++ b/schemas/map.schema.json @@ -1,6 +1,6 @@ { "$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": "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", 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