From 4bff972fd49cf50099d92954bb3cb411a199bdf6 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 30 Sep 2026 10:48:59 +0000 Subject: [PATCH 1/2] docs: point AgentSwarm at Agent Substrate as its platform MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a thin mirror cross-link recording that Agent Substrate is the shared platform AgentSwarm runs on, and maps its vocabulary onto the existing spec: events over substrate-mcp -> message bus, governed memory -> memory plane, leases/handoffs -> offer/claim and single-writer ownership, Graph ID -> correlation_id. - docs/substrate-integration.md: the mirror pointer + vocabulary map, referencing 01 §2.2, 02 and 04 §2 rather than restating them - 04-integration-plan.md: new §2.1 "Platform substrate" (the §2 table stays authoritative) - README.md: document-map row 9 and a short "Platform" section The integration decision itself is an ADR in agent-substrate (docs/adr/*-swarm-substrate-integration.md), tracked as SPE-5050/SPE-5051. Docs only: no runtime behaviour changes, and build_agents.py --check is still up-to-date. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01BRBehxvVTgfHY4VEaXT89U --- 04-integration-plan.md | 4 +++ README.md | 13 ++++++++++ docs/substrate-integration.md | 48 +++++++++++++++++++++++++++++++++++ 3 files changed, 65 insertions(+) create mode 100644 docs/substrate-integration.md diff --git a/04-integration-plan.md b/04-integration-plan.md index a34a735..6527f00 100644 --- a/04-integration-plan.md +++ b/04-integration-plan.md @@ -40,6 +40,10 @@ This plan defines how the 15 agents interact, share data, and resolve conflicts **Correlation invariant:** one business request = one `correlation_id`; every artifact, message, PR, run, and release carries it. This is what makes the whole system auditable end-to-end. +### 2.1 Platform substrate + +These substrates are provided by **[Agent Substrate](https://github.com/swcstudiospace/agent-substrate)**, the shared platform AgentSwarm runs on: events over substrate-mcp (message bus), governed memory (the memory plane), leases and handoffs (offer/claim and single-writer ownership), and Graph ID = `correlation_id`. The table above stays authoritative for what flows where; the integration decision itself is an ADR in that repo (`docs/adr/*-swarm-substrate-integration.md`), tracked as Linear [SPE-5050](https://linear.app/swcstudio/issue/SPE-5050) / [SPE-5051](https://linear.app/swcstudio/issue/SPE-5051). See [docs/substrate-integration.md](docs/substrate-integration.md) for the vocabulary map. No swarm runtime behaviour depends on it today. + ## 3. Reference event flows ### 3.1 Greenfield feature (happy path) diff --git a/README.md b/README.md index 65c6b18..ba3ec4a 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,19 @@ A complete design specification for a distributed swarm of 15 specialized AI age | 6 | [06-testing-protocols.md](06-testing-protocols.md) | 7-level validation: golden tasks → contracts → integration flows → chaos → E2E benchmark → security red-team → prod invariants | | 7 | [07-scalability.md](07-scalability.md) | Manifest schema, new-agent onboarding (shadow→probation→full), traffic shaping, contract evolution, multi-swarm | | 8 | [CLAUDE.md](CLAUDE.md) · [prompts/](prompts/) · [scripts/](scripts/) · [swarm/](swarm/) | Runnable implementation: subagent prompts, per-agent Python tools, orchestration runtime | +| 9 | [docs/substrate-integration.md](docs/substrate-integration.md) | Platform pointer: how the spec's substrates map onto [Agent Substrate](https://github.com/swcstudiospace/agent-substrate) | + +## Platform + +AgentSwarm runs on **[Agent Substrate](https://github.com/swcstudiospace/agent-substrate)**, the shared +platform providing the infrastructure services this spec assumes ([01 §2.2](01-architecture.md), +[04 §2](04-integration-plan.md)): events over substrate-mcp, governed memory, leases and handoffs, and +Graph ID = `correlation_id`. The integration ADR lives in that repo +(`docs/adr/*-swarm-substrate-integration.md`), tracked as Linear +[SPE-5050](https://linear.app/swcstudio/issue/SPE-5050) / +[SPE-5051](https://linear.app/swcstudio/issue/SPE-5051); +[docs/substrate-integration.md](docs/substrate-integration.md) is the mirror pointer here. No swarm +runtime behaviour depends on it today. ## The 15 agents diff --git a/docs/substrate-integration.md b/docs/substrate-integration.md new file mode 100644 index 0000000..946137d --- /dev/null +++ b/docs/substrate-integration.md @@ -0,0 +1,48 @@ +# AgentSwarm on Agent Substrate — platform pointer + +**Status:** pointer / cross-link only. This document records *where* the swarm's shared platform lives +and how its vocabulary maps onto the existing AgentSwarm spec. It changes no runtime behaviour: nothing +in `swarm/`, `scripts/`, `omp/` or `hooks/` reads or depends on it. + +- **Platform repo:** [swcstudiospace/agent-substrate](https://github.com/swcstudiospace/agent-substrate) +- **Primary ADR** (lands in that repo, not here): `docs/adr/*-swarm-substrate-integration.md` +- **Tracking:** Linear [SPE-5050](https://linear.app/swcstudio/issue/SPE-5050) (platform) · + [SPE-5051](https://linear.app/swcstudio/issue/SPE-5051) (swarm ↔ substrate integration) + +## Why this exists + +[01-architecture.md §2.2](../01-architecture.md) lists the swarm's infrastructure services (message bus, +Task Store, artifact registry, memory, secrets, observability) as *shared, not agents*, and +[04-integration-plan.md §2](../04-integration-plan.md) lists the substrates those services expose. +**Agent Substrate is the platform that provides them.** AgentSwarm is one tenant of it, not its owner: +the swarm keeps its agent roster, gates and task DAG; the substrate supplies the transport, the governed +memory and the coordination primitives underneath. + +The local `.swarm/` store (SQLite Task Store, `events.jsonl`, signed verdicts) remains the offline, +single-host implementation of the same contracts — see +[05-deployment-guide.md](../05-deployment-guide.md). Substrate is the hosted form of the same seams, +not a replacement for them. + +## Vocabulary map + +| Substrate capability | AgentSwarm concept | Where it is already specified | +|---|---|---| +| Events over **substrate-mcp** | Message bus, `swarm.v1` envelope, `evt./req./offer./ctl./esc.` subjects | [02-message-protocol.md](../02-message-protocol.md) · [04 §2](../04-integration-plan.md) | +| **Governed memory** | Memory plane (vector + KV): decisions, patterns, retrospectives, estimates, written via `memory.write` | [01 §2.2](../01-architecture.md) · [04 §2](../04-integration-plan.md) | +| **Leases / handoffs** | `task.offer` → claim → `task.assign`, single-writer artifact ownership, A01-only state transitions | [01 §3](../01-architecture.md) · [02 lifecycle](../02-message-protocol.md) | +| **Graph ID** | `correlation_id` — one business request, one id, carried by every artifact, message, PR, run and release | [04 §2 correlation invariant](../04-integration-plan.md) | + +The Graph ID equivalence is the load-bearing one: because the swarm already guarantees a single +`correlation_id` per business request (invariant 4 in the [README](../README.md)), a swarm run maps onto +exactly one substrate graph, and substrate-side audit joins the swarm's own run log without a translation +table. + +## What this doc is not + +- Not an integration design. The ADR in `agent-substrate` owns the decision, the interfaces and the + migration sequencing; this page only points at it. +- Not a change to [04-integration-plan.md](../04-integration-plan.md). That document's substrate table + stays authoritative for what flows where; §2.1 there links back here. +- Not a dependency. Governance of gates, verdicts and autonomy ceilings stays with the swarm + ([02-message-protocol.md](../02-message-protocol.md) autonomy levels L0–L4); substrate never raises a + ceiling. From 6dfc4de42536f30e25b1bd8f83d8d4d4cd79f6f2 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 30 Sep 2026 10:57:55 +0000 Subject: [PATCH 2/2] docs: narrow substrate scope claims and fix pointer accuracy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses three Greptile review findings on the substrate pointer, all over-claims in the new doc rather than the spec it references: - Platform scope (P2): "provides them" attributed all six 01 §2.2 services to Agent Substrate. Narrowed to the four capabilities actually in the map, and stated that the artifact registry and secrets stay externally provisioned. Adds a telemetry row covering the OTel plane, marked as not claimed by substrate here, so the map is explicit rather than silent about it. - Graph ID (P1): claimed substrate-side audit joins the run log "without a translation table". The swarm mints correlation_id as str(uuid.uuid4()) (scripts/orch_plan.py, swarm/envelope.py), so a differently shaped Graph ID cannot be string-equal. Restated as a correspondence needing an explicit mapping, which the ADR and its adapter stage own. - Deployment link (P2): pointed readers at 05-deployment-guide.md for the local .swarm/ store, but that document covers the containerized NATS/Postgres/etcd/Vault model and never mentions SQLite or events.jsonl. Repointed at the runnable-swarm sections of CLAUDE.md and the README. The first fix applied to the 04 §2.1 subsection and the README Platform section too, which carried the same over-attribution. Still docs only. Links verified, build_agents.py --check and build_trae_agents.py --check up-to-date, root TS suite green. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01BRBehxvVTgfHY4VEaXT89U --- 04-integration-plan.md | 2 +- README.md | 7 ++++--- docs/substrate-integration.md | 36 ++++++++++++++++++++++++----------- 3 files changed, 30 insertions(+), 15 deletions(-) diff --git a/04-integration-plan.md b/04-integration-plan.md index 6527f00..f8e6eaf 100644 --- a/04-integration-plan.md +++ b/04-integration-plan.md @@ -42,7 +42,7 @@ This plan defines how the 15 agents interact, share data, and resolve conflicts ### 2.1 Platform substrate -These substrates are provided by **[Agent Substrate](https://github.com/swcstudiospace/agent-substrate)**, the shared platform AgentSwarm runs on: events over substrate-mcp (message bus), governed memory (the memory plane), leases and handoffs (offer/claim and single-writer ownership), and Graph ID = `correlation_id`. The table above stays authoritative for what flows where; the integration decision itself is an ADR in that repo (`docs/adr/*-swarm-substrate-integration.md`), tracked as Linear [SPE-5050](https://linear.app/swcstudio/issue/SPE-5050) / [SPE-5051](https://linear.app/swcstudio/issue/SPE-5051). See [docs/substrate-integration.md](docs/substrate-integration.md) for the vocabulary map. No swarm runtime behaviour depends on it today. +**[Agent Substrate](https://github.com/swcstudiospace/agent-substrate)** is the shared platform AgentSwarm runs on. It provides four of the substrates above: events over substrate-mcp (message bus), governed memory (the memory plane), leases and handoffs (offer/claim and single-writer ownership), and the Graph ID that a `correlation_id` maps onto. The artifact registry and secrets stay externally provisioned, and the telemetry plane stays OTel. The table above stays authoritative for what flows where; the integration decision itself — including the id mapping and cross-platform trace correlation — is an ADR in that repo (`docs/adr/*-swarm-substrate-integration.md`), tracked as Linear [SPE-5050](https://linear.app/swcstudio/issue/SPE-5050) / [SPE-5051](https://linear.app/swcstudio/issue/SPE-5051). See [docs/substrate-integration.md](docs/substrate-integration.md) for the vocabulary map. No swarm runtime behaviour depends on it today. ## 3. Reference event flows diff --git a/README.md b/README.md index ba3ec4a..ca882c8 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,10 @@ A complete design specification for a distributed swarm of 15 specialized AI age ## Platform AgentSwarm runs on **[Agent Substrate](https://github.com/swcstudiospace/agent-substrate)**, the shared -platform providing the infrastructure services this spec assumes ([01 §2.2](01-architecture.md), -[04 §2](04-integration-plan.md)): events over substrate-mcp, governed memory, leases and handoffs, and -Graph ID = `correlation_id`. The integration ADR lives in that repo +platform providing four of the infrastructure substrates this spec assumes ([01 §2.2](01-architecture.md), +[04 §2](04-integration-plan.md)): events over substrate-mcp, governed memory, leases and handoffs, and the +Graph ID a `correlation_id` maps onto. The artifact registry, secrets and the OTel telemetry plane are not +in that set. The integration ADR lives in that repo (`docs/adr/*-swarm-substrate-integration.md`), tracked as Linear [SPE-5050](https://linear.app/swcstudio/issue/SPE-5050) / [SPE-5051](https://linear.app/swcstudio/issue/SPE-5051); diff --git a/docs/substrate-integration.md b/docs/substrate-integration.md index 946137d..c4422f3 100644 --- a/docs/substrate-integration.md +++ b/docs/substrate-integration.md @@ -14,14 +14,23 @@ in `swarm/`, `scripts/`, `omp/` or `hooks/` reads or depends on it. [01-architecture.md §2.2](../01-architecture.md) lists the swarm's infrastructure services (message bus, Task Store, artifact registry, memory, secrets, observability) as *shared, not agents*, and [04-integration-plan.md §2](../04-integration-plan.md) lists the substrates those services expose. -**Agent Substrate is the platform that provides them.** AgentSwarm is one tenant of it, not its owner: -the swarm keeps its agent roster, gates and task DAG; the substrate supplies the transport, the governed -memory and the coordination primitives underneath. +**Agent Substrate is the platform providing the four capabilities in the map below** — events, +governed memory, leases/handoffs and the Graph ID. AgentSwarm is one tenant of it, not its owner: the +swarm keeps its agent roster, gates and task DAG; the substrate supplies that transport, that governed +memory and those coordination primitives underneath. + +It does not follow that substrate provides every service in §2.2. The artifact registry (Git + OCI) and +secrets (Vault/KMS) stay externally provisioned and are out of scope for this pointer, and the OTel +telemetry plane stays OTel — see the map's last row. Which side provisions what, and the trace-to-graph +correlation across the two platforms, is for the ADR to settle; do not read this page as a provisioning +list. The local `.swarm/` store (SQLite Task Store, `events.jsonl`, signed verdicts) remains the offline, -single-host implementation of the same contracts — see -[05-deployment-guide.md](../05-deployment-guide.md). Substrate is the hosted form of the same seams, -not a replacement for them. +single-host implementation of the same contracts — see the runnable-swarm sections of +[CLAUDE.md](../CLAUDE.md) and the [README](../README.md), not +[05-deployment-guide.md](../05-deployment-guide.md), which covers the containerized +NATS/Postgres/etcd/Vault deployment instead. Substrate is the hosted form of the same seams, not a +replacement for them. ## Vocabulary map @@ -31,11 +40,16 @@ not a replacement for them. | **Governed memory** | Memory plane (vector + KV): decisions, patterns, retrospectives, estimates, written via `memory.write` | [01 §2.2](../01-architecture.md) · [04 §2](../04-integration-plan.md) | | **Leases / handoffs** | `task.offer` → claim → `task.assign`, single-writer artifact ownership, A01-only state transitions | [01 §3](../01-architecture.md) · [02 lifecycle](../02-message-protocol.md) | | **Graph ID** | `correlation_id` — one business request, one id, carried by every artifact, message, PR, run and release | [04 §2 correlation invariant](../04-integration-plan.md) | - -The Graph ID equivalence is the load-bearing one: because the swarm already guarantees a single -`correlation_id` per business request (invariant 4 in the [README](../README.md)), a swarm run maps onto -exactly one substrate graph, and substrate-side audit joins the swarm's own run log without a translation -table. +| Telemetry (*not claimed by substrate here*) | OTel telemetry plane: traces/metrics/logs correlated by `trace_id`, A13 operates, all agents emit | [01 §2.2](../01-architecture.md) · [04 §2](../04-integration-plan.md) | + +The Graph ID row is the load-bearing one, and it is a **correspondence, not string equality**: because the +swarm already guarantees a single `correlation_id` per business request (invariant 4 in the +[README](../README.md)), one swarm run corresponds to exactly one substrate graph. The identifiers +themselves are shaped differently — the swarm mints a UUID (`str(uuid.uuid4())`, see +[`scripts/orch_plan.py`](../scripts/orch_plan.py) and [`swarm/envelope.py`](../swarm/envelope.py)) — so +joining substrate-side audit to the swarm's own run log needs an explicit `correlation_id` ↔ Graph ID +mapping. Defining it (and how `trace_id` correlation crosses the two platforms) belongs to the ADR and +its adapter stage, not to this page. ## What this doc is not