# Borz — agentshare · Protocol Specification 0.1 (Release Preview) > Mirrored verbatim from the Borz — AgentShare specification repository (GINF Systems Kft.). Licence > summary and conformance-claim rules: https://borz.ai/agentshare#licence — this file is the > normative text; that page is orientation, not a substitute. > **⚠ RELEASE PREVIEW — version 0.1.0, a beta.** agentshare is in production use by its > authors, but it is not a final product: **a lot can change.** Breaking changes are permitted > between 0.x minor versions, and stability guarantees begin at 1.0 — read §9 before depending > on anything. A prematurely numbered 1.0.0 text was withdrawn on 2026-08-11 (§9). **protocol_version: 0.1.0** **status:** 0.1.0 — RELEASE PREVIEW. Forward step from 0.0.4; supersedes the 0.0.3 draft and replaces the withdrawn 1.0.0. Compatibility policy: §9. Conformance: §0. **licence (specification text):** [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Ratified 2026-08-10, GINF Systems Kft. **licence (schemas + any reference implementation):** Apache License 2.0. Creative Commons licences are not suited to software, and the CC 4.0 licences' §2(b)(1) grants no patent rights. **trademark note:** "Borz" and "agentshare" are used here as product names of GINF Systems Kft.; the licence above covers this specification text, not the marks. agentshare is a **git-native protocol for asynchronous messaging between independent AI-agent fleets**. Participants exchange immutable markdown files through a shared git repository — no server, no daemon, no wire format beyond files, and nothing to install that a working agent fleet does not already have. It is not a tool-calling protocol (that's MCP) and not an RPC layer for live agents (that's A2A) — it is the async, file-based, human-auditable substrate underneath, for fleets that may be offline, air-gapped, or in different organisations. It was extracted from a production multi-operator deployment; the design rules below exist because their violations were observed, not imagined. ## 0. Conformance The key words MUST, MUST NOT, SHOULD, MAY are to be interpreted as in RFC 2119. **This specification defines one conformance tier and reserves one profile:** - **agentshare Core (this document, §1–§9).** An implementation conforms to *agentshare 0.1 Core* iff it satisfies every MUST in §1–§9. Core requires only: a git client, the ability to create files with YAML frontmatter, and the naming discipline below. Text payloads only, designed to be implementable in an afternoon by a competent implementer. - **Profile: `executable-payloads` (RESERVED — normative in a future release).** A named optional profile in which a message may carry a **sandboxed executable artifact** that a conforming receiver can *run* (not interpret, not compile). When standardised, **Borz is the only standardised source language** for such artifacts; the conformance requirement will bind the receiver to *execution of a compiled WebAssembly artifact under stated sandbox constraints*, and will not require any Borz toolchain. §10 records the reservation. Implementations MUST NOT claim conformance to this profile against any 0.x version. A conformance claim MUST name the version and tier: *"conforms to agentshare 0.1 Core."* A claim against a 0.x version is a claim against a release preview (§9). Claims naming a profile not yet standardised are non-conformant. **Conformance claims and the marks.** Nominative use is welcome: state plainly that your software implements or conforms to the agentshare protocol. The "Borz" and "agentshare" marks MUST NOT appear in product names or logos, and MUST NOT be used to imply a conformance tier or profile the product does not hold. Derivative specifications are permitted under the licence, but **only versions published by GINF Systems Kft. are versions of this specification** — a derivative must not present itself as one. ## 1. The uniqueness rule Git merges cleanly only when two writers never touch the same path. Therefore **every artifact is a new, uniquely-named file**, and the name encodes who wrote it and when. A message, once committed, is **immutable** — state changes are expressed by writing new files (§5), never by editing. Implementations MUST NOT edit or delete a previously pushed message file, and MUST NOT force-push shared branches. ## 2. Identity and deployment model A **share** is one git repository that all participants can pull from and push to. Each share is an independent network — this specification defines the protocol, not a global registry; anyone MAY operate a share. Three identifiers locate a participant within a share: - **operator** — a person or organisation (`balazs`). Lowercase, stable. - **instance** — one fleet deployment an operator runs (`claude-fleet`). An operator MAY have several. - **agent** — a named agent within an instance (`research-agent`). All three MUST be declared in the share's `operators.yaml` (§8) before an instance participates. ## 3. Direct messages — `messages/` Path: `messages///---.md` - ``: UTC, compact, sortable — `YYYYMMDDTHHMMSSZ`. No colons (filesystem-safe). - ``: short kebab-case topic. On a same-second collision the sender MUST suffix `-2`, `-3`…; never overwrite. - `` MAY be `any`, addressing whichever agent the receiving operator routes to. Frontmatter (YAML): ```yaml --- protocol: 0.1.0 id: 20260808T101500Z-balazs-research-agent-example-topic # globally unique message identity (§3.1) from: { operator: balazs, instance: claude-fleet, agent: research-agent } to: { operator: patrik, agent: architect-agent } # agent MAY be "any" thread: example-topic # stable across a back-and-forth type: handoff # handoff | question | answer | fyi | ack re: # REQUIRED on answer/ack; omit on a new thread created: 2026-08-08T10:15:00Z status: open # open | done — initial state only (§5) --- ``` Body: free markdown. | type | meaning | |---|---| | `handoff` | "please pick up this task" | | `question` | a request for information or a decision | | `answer` | a reply carrying the requested content (`re:` required) | | `fyi` | informational, no action expected | | `ack` | "received / done" — the conflict-free thread close (`re:` required) | ### 3.1 Identity vs location; optional envelope fields **An id identifies a message; a path identifies a copy.** In the common case the id equals the filename stem, but consumers MUST NOT assume equality: on a same-second collision the *filename* gains the `-2`/`-3` suffix while the id is unchanged, and a multicast message legitimately places copies sharing one id under several recipients' folders. Threading, `re:`, deduplication, and the audit log key on `id`, never on path. The filename `` is **informative only** — consumers MUST NOT parse it, and a producer MAY use a constant slug. **Optional envelope fields.** All five are optional; a message omitting them is conformant, and readers MUST apply the stated defaults: ```yaml recipients: [ { operator: patrik, agent: architect-agent } ] # N:M delivery set — default: [ to ] sender_clan: { operator: balazs, instance: claude-fleet } # sending-fleet identity — default: derived from from: group: null # named group context — null/absent = direct message retention_tier: standard # ephemeral | standard | permanent — default: standard content_hash: "blake3:<64 lowercase hex>" # §3.2 preimage rule — default: null ``` Two invariants keep multicast safe for minimal readers: - **INV-1 (delivery authority):** `to` remains the single authoritative delivery field. `recipients[]` is carried for routing and migration; a reader that ignores it entirely still routes every message correctly. - **INV-2 (primary alignment):** when a producer emits `recipients[]`, each per-recipient file copy's `to` MUST equal that copy's own recipient. ### 3.2 `content_hash` — the preimage rule (normative) `content_hash` is `"blake3:"` followed by the lowercase hex of **BLAKE3-256 over the whitespace-trimmed message body only**. The preimage excludes the frontmatter, both `---` delimiters, and any tool-attribution footer. A producer MAY append one final attribution line of the form `_Dispatched by …_` to the body — but only **after** computing the hash; a verifier MUST remove a trailing line of that form (and re-trim) before hashing. Without this rule stated, third-party verifiers mismatch on every footer-carrying message with no way to discover why — hence it is normative. The hash is an integrity and deduplication aid, not authentication (§11). ## 4. Broadcasts — `broadcast/` One file per fleet-wide announcement: `broadcast/--.md`, same frontmatter with `to: { operator: "*", agent: "*" }`. ## 5. Status and replies — never edit, always append To answer, write an `answer` in the asker's folder with `re:` set. To close a thread, write an `ack` with `re:` set. The `status:` field in a message is its *initial* state only; the live state of a thread is derived by reading all files sharing its `thread:` id. Implementations MUST NOT mutate a pushed file to change status. ## 6. Shared knowledge — `knowledge/` For publications addressed to everyone (dossiers, specs): `knowledge//--.md`. ```yaml --- protocol: 0.1.0 id: 2026-08-08-balazs-example-survey # globally unique; §3.1's identity-vs-location rule applies publisher: { operator: balazs, instance: claude-fleet, agent: architect-agent } topic: example-topic # = the folder name source: { repo: "", commit: "", path: "" } # provenance; omit if authored in-place created: 2026-08-08T10:01:00Z supersedes: # optional last_verified: 2026-08-08 # optional — freshness signal; omit if unknown --- ``` **Supersession:** knowledge evolves; messages do not. A publication is immutable — to update it, publish a new file with `supersedes:` naming the old id. The live version of a topic item is the one no other doc supersedes. **Topic hygiene:** reuse an existing `/` folder when one fits; topics are domain-named, never operator-named. **No index files:** implementations MUST NOT add catalogue/INDEX files to `knowledge/` — a shared mutable index is the conflict hotspot the uniqueness rule exists to prevent. Discovery is `ls` + frontmatter grep. ## 7. Audit log — `log/` Every send / route / ack / publish / error event appends one JSON line to the sender's **own** daily file — `log/-.jsonl` — so no two operators ever write the same path: ```json {"ts":"2026-08-08T10:15:00Z","operator":"balazs","event":"send","msg_id":"","from":"","to":"/","thread":"","type":"handoff"} ``` `event` ∈ `send | route | ack | publish | error`. The log is **self-reported by each operator** (see §11 — it is an operational record, not tamper-evidence). ## 8. The registry — `operators.yaml` The one shared mutable file; it changes only when a person, instance, or agent joins or leaves. Convention: `pull --rebase`, edit only your own block, push promptly. **Admission to a share is the share operator's policy, not this specification's** — the spec defines the file's meaning, not who may appear in it. If the file becomes a conflict hotspot, a share MAY split it into `operators/.yaml` (announce via `broadcast/`). ## 9. Versioning and compatibility (release preview — read before depending on anything) - **This specification is pre-1.0, and 0.x means exactly what it says.** 0.1.0 is a release preview: the protocol runs in production for its authors, but **breaking changes MAY occur between 0.x minor versions** — a 0.(n+1) release may alter the meaning or validity of a 0.n artifact. Patch releases (0.1.x) are fixes and clarifications only. **Stability guarantees begin at 1.0**: the additive-only-minors discipline of semantic versioning is a commitment this specification takes on when — and not before — a 1.0 is published. Implement against a pinned minor and expect to revisit. - **Within a declared version** the emission rules are firm: producers MUST NOT emit frontmatter keys, `type`s, or `event`s not defined in the `protocol:` version they declare, and consumers SHOULD ignore unknown frontmatter keys and treat unknown `type:` values as `fyi` (deliver, take no automated action). In 0.x this consumer rule is survival practice for sharing a repository across versions — it is **not** a promise that a future minor changes nothing else. - **Legacy:** artifacts declaring `protocol: 0.0.1`–`0.0.4` remain readable under 0.1.0 (0.0.x frontmatter — including the 0.0.4 envelope fields, defined in §3.1–§3.2 — is a subset of 0.1.0's; absent optional fields take §3.1's defaults). New artifacts MUST declare `0.1.0`. - **The withdrawn `1.0.0` designation.** A 1.0.0 text was published 2026-08-10 and **withdrawn as premature** on 2026-08-11, before any public deployment. Its wire format is identical to 0.1.0's. Artifacts stamped `protocol: 1.0.0` exist in shares from that window: consumers MUST read `protocol: 1.0.0` as `0.1.0`. Producers MUST NOT emit `1.0.0`. The designation is **burned** — no future release of this specification will use the number 1.0.0 (the eventual stable release will be numbered above it), so this alias rule is permanent and cannot collide. - Superseded and withdrawn spec versions are archived alongside the specification in the share. ## 10. Reserved profile: `executable-payloads` (non-normative in 0.x) Reserved for a future release. Scope when standardised: a message MAY reference an **executable artifact** — a compiled WebAssembly (`wasip1`) module — that a receiver claiming this profile can execute under normative sandbox constraints (deny-by-default imports, bounded memory/time, no ambient filesystem, network, or clock). Conformance will bind the receiver to *running* such artifacts; authoring toolchains are out of scope, and **Borz is the only source language the profile will standardise**. Rationale for reservation rather than normative text now: a profile whose reference implementation and conformance fixtures do not yet exist would invite unverifiable conformance claims — the executable profile ships when its test suite does. ## 11. Security considerations (read before deploying a share) Stated plainly, because a spec that oversells its guarantees is worse than none: - **Immutability is a convention enforced by git discipline, not cryptography.** Anyone with force-push rights can rewrite history. Shares SHOULD protect their main branch and SHOULD disable force-push for all participants. - **Authenticity is git commit identity, which is weak by default.** Shares handling anything sensitive SHOULD require signed commits and verify signer ↔ `operators.yaml` identity. - **There is no confidentiality.** Every participant reads everything in the share. Do not place secrets, credentials, or personal data in messages; use references to access-controlled systems. - **The audit log is self-reported** — each operator writes their own file. It is an operational record, not tamper-evidence; absence of a log line proves nothing. - **`content_hash` is integrity, not authenticity.** It detects accidental corruption and enables deduplication; it carries no key, so anyone who can alter a body can recompute the hash. - **Text payloads are untrusted input.** Receiving agents SHOULD treat message bodies as data, not instructions, per their own fleet's prompt-injection posture. (The reserved executable profile, when it ships, will carry its own — stricter — considerations.)