Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion .agents/skills/add-aaif-link/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ A link on the map is a claim that one project's documentation states a relations

```json
{
"id": "e-<from>-<to>",
"id": "e-<a>-<b>",
"from": "<project id>",
"to": "<project id>",
"kind": "documented",
Expand All @@ -28,6 +28,10 @@ A link on the map is a claim that one project's documentation states a relations

Use `"kind": "example"` when the source only names the other project as an example. Project ids are in `data/projects.json`.

`from` and `to` are the line's two ends, in any order (the page draws no arrow). The id is `e-` plus two short names for the ends; it only has to be unique. `source` may add a `label`, shown next to the file name.

Adding a link can change counts and dates stated on the page and in the README. CONTRIBUTING lists those sentences; update any your link makes wrong.

4. **Check the drawing.** Open the page (`bunx serve .`) and confirm the new line does not pass through another project's box. If it does, add `"bend"` (a vertical offset in map units, positive bends down) or ask before moving a node.
5. **Add it to a flow** only if it extends a flow's story. Each step in `data/flows.json` names a link id and gives a one-sentence caption.
6. **Verify.** Run `bun scripts/verify.ts`. Every test must pass. Report the full output.
Expand Down
9 changes: 5 additions & 4 deletions .github/ISSUE_TEMPLATE/propose-a-link.yml
Original file line number Diff line number Diff line change
@@ -1,19 +1,20 @@
name: Propose a link
description: A project's own documentation states a relationship to another AAIF project.
title: "Link: <from> → <to>"
title: "Link: <project> ↔ <project>"
labels: ["link"]
body:
- type: input
id: from
attributes:
label: From (the project whose docs state the link)
label: One project
description: The two ends of the line, in any order. The page draws no arrow.
placeholder: goose
validations:
required: true
- type: input
id: to
attributes:
label: To
label: The other project
placeholder: MCP
validations:
required: true
Expand All @@ -28,7 +29,7 @@ body:
id: source
attributes:
label: Source file URL
description: A file in the project's own repository, on its default branch.
description: The file the quote comes from, in that project's own repository, on its default branch.
placeholder: https://github.com/owner/repo/blob/main/docs/page.md
validations:
required: true
Expand Down
1 change: 1 addition & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,4 +14,5 @@
```

- [ ] `bun scripts/verify.ts` passes
- [ ] `bun.lock` is unchanged, unless you changed a dependency (Bun 1.3 rewrites it: `git checkout bun.lock`)
- [ ] `bunx tsc --noEmit` passes
7 changes: 4 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,9 @@ bunx tsc --noEmit # typecheck the verify script
- `data/projects.json`: the ten projects (stage, docs, repository, technical committee name) plus the two outside nodes, "Your app" and "Models".
- `data/links.json`: every line on the map. `kind` is `documented`, `example` or `seam`.
- `data/flows.json`: the guided flows. Each step names a link id.
- `index.html`: the page. It reads the three data files and holds no data of its own.
- `index.html`: the page. It reads the three data files. A few sentences on it state counts and dates; CONTRIBUTING lists them.
- `scripts/verify.ts`: checks every claim against the source repositories.
- `project.faf`: the repository's facts (stack, commands, data files) as structured YAML, for agents that read it.
- `project.faf`: the repository's facts (what it is, who it's for, stack, hosting, how it works) as structured YAML, for agents that read it.

## Rules

Expand All @@ -33,7 +33,8 @@ bunx tsc --noEmit # typecheck the verify script
3. Stages come only from the project table in `aaif/technical-committee`. Do not infer a stage from a blog post or announcement.
4. The project list comes only from aaif.io/projects. Do not add a project that page does not list.
5. Mark new links with `"added": "YYYY-MM-DD"`, the date you verified them.
6. Do not change `index.html` to change data. Change the data files.
6. Do not change `index.html` to change data. Change the data files. If a change makes a count or date on the page or in the README wrong, update that sentence too (CONTRIBUTING lists them).
7. A project's `origin` and `joined` appear only when a cited source states them (the AAIF or Linux Foundation announcement, aaif.io). Otherwise leave them out.

## Leave alone

Expand Down
15 changes: 13 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,22 @@ To add a path yourself, add a flow to `data/flows.json`. Each step names a link

- **A quote** from the source project's docs, copied as a reader sees it.
- **A source file** in that project's own repository, on its default branch. Docs pages and READMEs are preferred over blog posts, issues and release notes.
- **A kind:** `documented` when the docs state the link, `example` when they only name the other project as an example.
- **A kind:** `documented` when the docs state the link, `example` when they only name the other project as an example. (`seam` marks an overlap no document settles; its quote is the map's own wording and it needs no source.)
- **Two ends:** `from` and `to` are the two projects the line connects. The page draws no arrow, so their order doesn't matter. The source is whichever project's docs the quote comes from.
- **Optionally a `label`** in `source`, shown next to the file name (for example `README, Key Features`).

The [add-aaif-link skill](.agents/skills/add-aaif-link/SKILL.md) walks through the steps.

## Confirm your project

If you work on one of the projects, open its "Check your details" issue. Its confirm link opens `confirmed/<project id>.md` with the project's details as the map shows them; if they're right, add your GitHub handle after `Verified by: @` and press "Propose new file". If something's wrong, say so in the issue or fix it in a pull request. [confirmed/README.md](confirmed/README.md) has more.
If you work on one of the projects, open its "Check your details" issue. Its confirm link opens `confirmed/<project id>.md` with the project's details as the map shows them; if they're right, add your GitHub handle after `Verified by: @`, press "Propose new file", then "Create pull request". If something's wrong, say so in the issue or fix it in a pull request. [confirmed/README.md](confirmed/README.md) has more.

## Sentences that state counts and dates

A few sentences hold numbers the data can change. When your change makes one wrong, update it in the same pull request:

- README, "What it shows": the counts of projects, links, examples, seams and flows.
- `index.html`: the line under the title (project count and month), "MCP is the hub" and "MCP sits in the middle" (how many projects link to MCP), the stage lists and the committee table's date, and the overview's sentence about links added in a check.

## What the map does not take

Expand All @@ -36,6 +45,8 @@ bun scripts/verify.ts
bunx tsc --noEmit
```

CI uses Bun 1.4.4. Bun 1.3 can't read `bun.lock` and rewrites it on `bun install`; if `bun.lock` shows as changed, run `git checkout bun.lock` before you commit.

Every test must pass. Paste the full verify output in the pull request.

## Commits
Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# AAIF Stack Map

An interactive map of the ten [Agentic AI Foundation](https://aaif.io/projects) projects and the links between them. Every line on the map is a link that one project's own documentation states, with the quote and the file it comes from.
An interactive map of the ten [Agentic AI Foundation](https://aaif.io/projects) projects and the links between them. Every documented line on the map is a link one project's own documentation states, with the quote and the file it comes from; examples and open seams are labelled as such.

A community map by James Wolfe, AAIF Ambassador, built from each project's own documentation.

Expand Down Expand Up @@ -36,7 +36,7 @@ The script clones each source repository (shallow, into `.cache/repos`) and runs
| 2 · Stages | Every stage matches the technical committee table, and the map has exactly the projects the table lists. |
| 3 · Data | The data files are consistent: unique ids, links between real nodes, flow steps that name real links, complete project records. |

It prints every test and exits non-zero if any fails. CI runs it on every push and pull request and once a week; when the weekly run finds drift, it opens an issue labelled `drift`.
It prints every test and exits non-zero if any fails. CI runs it on pushes to `main`, on pull requests and once a week; when the weekly run finds drift, it opens an issue labelled `drift`.

## Contribute

Expand All @@ -61,7 +61,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).

| File | Holds |
| --- | --- |
| `data/projects.json` | Projects: stage, docs, repository, contributor, date joined, and map position |
| `data/projects.json` | Projects: stage, docs, repository, origin and date joined (only where a cited source states them), and map position |
| `data/links.json` | Links: ends, kind, quote, source repository and path |
| `data/flows.json` | Flows: ordered link ids with one caption each |

Expand Down
2 changes: 1 addition & 1 deletion confirmed/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,6 @@

One file per project: the project's details as the map showed them when someone from that project confirmed them. Git records who confirmed and when.

A file is named after the project's id in [`data/projects.json`](../data/projects.json) (`goose.md`, `mcp.md`, `agw.md`, …). Each project's "Check your details" issue has a link that opens its file already filled in, ending with `Verified by: @`. Add your GitHub handle after the `@` and press "Propose new file"; once it's merged, you're listed as a contributor.
A file is named after the project's id in [`data/projects.json`](../data/projects.json) (`goose.md`, `mcp.md`, `agw.md`, …). Each project's "Check your details" issue has a link that opens its file already filled in, ending with `Verified by: @`. Add your GitHub handle after the `@`, press "Propose new file", then "Create pull request"; once it's merged, you're listed as a contributor.

A file is kept as it was confirmed. If the map's data changes later, the file still shows what was agreed then. The verify script checks only that each file is named after a project.
2 changes: 1 addition & 1 deletion data/flows.json
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
},
{
"link": "e-goose-mcp",
"caption": "Its tools arrive as extensions, and every extension is an MCP server."
"caption": "Its tools arrive as extensions, which are based on MCP."
},
{
"link": "e-sandbox-mcp",
Expand Down
4 changes: 2 additions & 2 deletions data/links.json
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@
"from": "goose",
"to": "mcp",
"kind": "documented",
"title": "goose extensions are MCP servers",
"title": "goose extensions are based on MCP",
"quote": "Extensions are based on the Model Context Protocol (MCP)",
"source": {
"repo": "aaif-goose/goose",
Expand Down Expand Up @@ -173,7 +173,7 @@
"from": "sandbox",
"to": "skills",
"kind": "documented",
"title": "OpenSandbox ships skills as SKILL.md",
"title": "OpenSandbox's CLI installs its skills, as SKILL.md for opencode",
"quote": "The CLI ships with built-in OpenSandbox skills for coding agents and agent-oriented tools. … `./.agents/skills/<name>/SKILL.md`",
"source": {
"repo": "opensandbox-group/OpenSandbox",
Expand Down
6 changes: 1 addition & 5 deletions data/projects.json
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,6 @@
"layer": "Context",
"x": 600,
"y": 60,
"origin": "OpenAI, with others",
"joined": "Dec 2025 (launch project)",
"stage": "Impact",
"role": "A predictable place for the instructions and context that help coding agents work on a project.",
Expand Down Expand Up @@ -107,7 +106,6 @@
"x": 760,
"y": 250,
"origin": "Google",
"joined": "Aug 17, 2026",
"stage": "Growth",
"role": "An open standard for communication and interoperability between AI agents. Its Agent Card lists an agent’s “skills”, a separate idea from the Agent Skills format.",
"repo": "a2aproject/A2A",
Expand All @@ -122,7 +120,6 @@
"x": 260,
"y": 355,
"origin": "Envoy AI Gateway, renamed",
"joined": "Sep 9, 2026",
"stage": "Growth",
"role": "The control plane for agent traffic: one OpenAI-compatible API for models and MCP servers, with a preview guide for A2A traffic.",
"repo": "theagentrouter/agent-router",
Expand All @@ -137,7 +134,6 @@
"x": 740,
"y": 355,
"origin": "Solo.io",
"joined": "Jun 4, 2026",
"stage": "Growth",
"role": "One high-performance gateway for service, LLM and MCP traffic, with A2A support.",
"repo": "agentgateway/agentgateway",
Expand Down Expand Up @@ -166,7 +162,7 @@
"layer": "Run & train",
"x": 590,
"y": 450,
"origin": "Hugging Face, with Meta-PyTorch",
"origin": "Hugging Face",
"joined": "Oct 22, 2026",
"stage": "Growth",
"role": "Environments for training and evaluating agents with reinforcement learning, shared through a hub. Its /mcp route uses MCP’s message format over its own HTTP transport; RFC 003 (still in review) plans standard Streamable HTTP.",
Expand Down
2 changes: 1 addition & 1 deletion index.html
Original file line number Diff line number Diff line change
Expand Up @@ -282,7 +282,7 @@ <h3>Sources</h3>
const es = EDGES.filter(e => (e.a === id || e.b === id) && (!e.seam || seamsBox.checked));
highlight([id, ...es.map(e => e.a === id ? e.b : e.a)], es.map(e => e.id));
panel.innerHTML = `<p class="sub">${esc(n.layer)} · ${esc(n.kind)}</p><h2>${esc(n.name)}</h2><div>${stageChip(n)}</div><p>${esc(n.role)}</p>` +
(n.ext ? '' : `<dl class="facts"><dt>Contributed by</dt><dd>${esc(n.origin)}</dd><dt>Joined AAIF</dt><dd>${esc(n.joined)}</dd><dt>Docs</dt><dd><a href="${DOCS[n.id]}" target="_blank" rel="noopener">${esc(DOCS[n.id].replace(/^https:\/\/(www\.)?/, ''))}</a></dd><dt>Repository</dt><dd><a href="${n.repo}" target="_blank" rel="noopener">${esc(n.repo.replace('https://github.com/', ''))}</a></dd></dl>`) +
(n.ext ? '' : `<dl class="facts">${n.origin ? `<dt>Origin</dt><dd>${esc(n.origin)}</dd>` : ''}${n.joined ? `<dt>Joined AAIF</dt><dd>${esc(n.joined)}</dd>` : ''}<dt>Docs</dt><dd><a href="${DOCS[n.id]}" target="_blank" rel="noopener">${esc(DOCS[n.id].replace(/^https:\/\/(www\.)?/, ''))}</a></dd><dt>Repository</dt><dd><a href="${n.repo}" target="_blank" rel="noopener">${esc(n.repo.replace('https://github.com/', ''))}</a></dd></dl>`) +
`<p class="sub">${es.length} ${es.length === 1 ? 'link' : 'links'} on the map</p><ul class="links">${es.map(edgeItem).join('')}</ul>`;
}
function showEdge(eid) {
Expand Down
4 changes: 2 additions & 2 deletions project.faf
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
faf_version: "3.0"
project:
name: aaif-stack-map
goal: An interactive map of the ten [Agentic AI Foundation](https://aaif.io/projects) projects and the links between them. Every line on the map is a link that one project's own documentation states, with the quote and the file it comes from.
goal: "An interactive map of the ten [Agentic AI Foundation](https://aaif.io/projects) projects and the links between them. Every documented line on the map is a link one project's own documentation states, with the quote and the file it comes from; examples and open seams are labelled as such."
main_language: TypeScript
type: html # found: index.html (vanilla, no frontend framework)
stack:
Expand All @@ -26,7 +26,7 @@ stack:
storage: slotignored
human_context:
who: "Developers, newcomers and AAIF ambassadors working out how the AAIF projects fit together, and the projects' maintainers, who can confirm their details."
what: An interactive map of the ten [Agentic AI Foundation](https://aaif.io/projects) projects and the links between them. Every line on the map is a link that one project's own documentation states, with the quote and the file it comes from.
what: "An interactive map of the ten [Agentic AI Foundation](https://aaif.io/projects) projects and the links between them. Every documented line on the map is a link one project's own documentation states, with the quote and the file it comes from; examples and open seams are labelled as such."
why: "One page for how the AAIF projects connect, every line backed by a project's own docs."
where: "https://wolfe-jam.github.io/aaif-stack-map/ (source: github.com/Wolfe-Jam/aaif-stack-map)"
when: "Built November 2026 against aaif.io/projects and the technical committee table; re-verified weekly in CI."
Expand Down
8 changes: 7 additions & 1 deletion recipes/recheck.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,15 @@ prompt: |
1. Run `bun install` if node_modules is missing, then run `bun scripts/verify.ts --json report.json`.
2. If every test passes, report the full test output, every line, not a summary, and stop.
3. For each failing test:
- Quote not found: search the same repository (cached under .cache/repos) for the current wording.
- Quote not found: search the same repository for the current wording. The cache under .cache/repos
holds only git data, no working files: use `git -C .cache/repos/<owner>_<name> grep -n "<words>" HEAD`
and `git -C .cache/repos/<owner>_<name> show HEAD:<path>`.
If the project still states the link, update the quote and path in data/links.json.
If it no longer does, remove the link and any flow step in data/flows.json that uses it.
- Source file not found: the file may have moved. Find the quote with `git grep` in the same repository
and update the path in data/links.json.
- Repository not reachable: it may have been renamed or moved. If GitHub redirects the old name,
update the repo in data/links.json (and data/projects.json); if it is gone, report it.
- Stage mismatch: update the stage in data/projects.json to the committee table's value.
- Project missing from the map, or count mismatch: do not add the project yourself. Report it.
4. Run `bun scripts/verify.ts` again and report the full output.
Expand Down
7 changes: 5 additions & 2 deletions scripts/verify.ts
Original file line number Diff line number Diff line change
Expand Up @@ -50,8 +50,10 @@ const dirFor = (repo: string): string => join(reposDir, repo.replace("/", "_"));
function ensureRepo(repo: string): boolean {
const dir = dirFor(repo);
if (existsSync(join(dir, ".git"))) {
// A failed fetch must not pass on an old cached copy: the quotes would not be current.
const fetched = run(["git", "fetch", "-q", "--depth", "1", "origin", "HEAD"], dir);
if (fetched.ok) run(["git", "update-ref", "HEAD", "FETCH_HEAD"], dir);
if (!fetched.ok) return false;
run(["git", "update-ref", "HEAD", "FETCH_HEAD"], dir);
return run(["git", "rev-parse", "HEAD"], dir).ok;
}
mkdirSync(reposDir, { recursive: true });
Expand Down Expand Up @@ -95,7 +97,8 @@ for (const [key, f] of Object.entries(flows)) {
record(3, `flow ${key}: every step names a link`, missing.length === 0, missing.length ? `unknown: ${missing.join(", ")}` : `${f.steps.length} steps`);
}
for (const p of projects) {
const gaps = (["repo", "docs", "stage", "committeeName", "origin", "joined"] as const).filter(k => !p[k]);
// origin and joined are optional: shown only where a cited source states them (AGENTS.md rule 7).
const gaps = (["repo", "docs", "stage", "committeeName"] as const).filter(k => !p[k]);
record(3, `project ${p.id}: required fields present`, gaps.length === 0, gaps.length ? `missing: ${gaps.join(", ")}` : "repo, docs, stage, committee name");
if (p.docs) record(3, `project ${p.id}: docs link is https`, p.docs.startsWith("https://"), p.docs);
if (p.stage) record(3, `project ${p.id}: stage is a known stage`, (STAGES as readonly string[]).includes(p.stage), p.stage);
Expand Down
Loading