SLOP.md specification

Version 1.0 · Status: public draft · Steward: Caplifi Build

Sequenced Local-first Orchestration Protocol. The open standard for AI agent handoff channels. Transport-agnostic envelopes with one non-negotiable invariant: fuzzy layers inform; deterministic code gates anything irreversible.

1.What this is

Most multi-agent setups fail the same way: two models on two surfaces (a phone app, a desktop terminal, a background daemon) end up needing to hand work to each other, and every team invents its own ad hoc convention - a shared folder, a Slack channel, a magic filename - that only the person who built it understands, and that quietly breaks the moment someone adds a third agent.

SLOP.md is a small, file-based (or HTTP-based) envelope format for handing work between AI agents and human operators across any surface, with one non-negotiable invariant:

Fuzzy layers inform. Deterministic code gates anything irreversible.

Agents can read, summarize, and propose freely. Nothing that spends money, deletes data, signs a transaction, or otherwise can't be undone happens because a model decided it should - it happens because a human-authorized, code-enforced gate let it through. Agents never hold the keys to that gate.

Everything else in this spec exists to make that one rule easy to honor and hard to accidentally violate.

2.Design principles

1. Transport-agnostic. The envelope is the contract, not the pipe. HTTP POST, a shared cloud folder, a local filesystem watcher - all valid, all interchangeable, all reading the same schema.
2. One seat per drop. Every message declares exactly which agent/surface produced it (grok-mobile is not grok-build is not claude-code), so provenance survives even when the same human is behind all of them.
3. Execute is opt-in, discuss is default. A message either asks to be acted on or thought about - that distinction is explicit in the envelope, never inferred from tone.
4. Idempotent by construction. Never overwrite a prior drop. Revise by sending a new envelope that references the old one. Retries are safe by default.
5. Replies are classified, not dumped. A push notification and a deliverable are different things. Don't make a human read a 2,000-word result on a lock screen.
6. The channel gets smarter, not just busier. A lightweight note type lets any agent leave a breadcrumb for the next one - what worked, what didn't, what to try differently.

3.Canonical lanes

Agents never write to authorized/. That's the whole point of the gate.

4.The envelope

Markdown payloads use YAML front-matter. Pure control messages (handshakes, acks) may be plain JSON.

---
protocol: slop.v1
id: 20260704T071553Z-short-slug        # sortable UTC timestamp + slug, globally unique
type: instigate | handoff | ack | result | error | query | handshake | note
from: <agent-id>                        # e.g. grok-mobile, claude-code, watcher:odysseus, human
to: <recipient>                         # e.g. watcher, remote, human, a named orchestrator
in_reply_to: <id> | null
created_at: 2026-07-04T07:15:53Z        # ISO 8601 UTC
auth: none | signed:<sidecar-ref>
---

# Body (Markdown)

File naming (when using a file transport): YYYYMMDDThhmmssZ-slug.ext. Never overwrite. Revise with a new id and in_reply_to pointing at the original.

ID rules: [a-z0-9._:-] only, no slashes, no leading dot. IDs are sortable slugs, not proof of delivery time - a server-stamped receipt (over HTTP) is the actual delivery timestamp when it matters.

5.Type vs. mode - execute or discuss

This is the single most important distinction in the protocol, because it's the difference between "an agent left me a note" and "an agent just did something."

An implementation MUST let the sender force discuss even on a type: instigate message. An implementation MUST NOT let a discuss-mode message trigger anything irreversible.

6.Transport priority

A conforming implementation supports at least one of these; supporting all three is recommended for resilience.

7.Idempotency and retries

• Never overwrite an existing drop. A correction is a new envelope with in_reply_to set to the original.
• If unsure whether a message was delivered, check for an ack/result keyed to your id before resending.
• Recommended retry backoff for transient transport failures: 2s → 4s → 8s, then stop and surface the failure instead of looping.
• A receiving watcher MUST treat a duplicate id as a no-op, not a re-execution.

8.Reply delivery classes

Not every reply deserves the same amount of a human's attention. SLOP.md separates the notification from the payload:

This is what keeps a phone-based agent from ever having a 3,000-word result dumped on a lock screen.

9.Cross-agent learning (type: note)

Any agent may leave a structured note for the next one, after a complex handoff:

---
protocol: slop.v1
id: 20260704T071553Z-note-example
type: note
from: grok-mobile
to: watcher
in_reply_to: <prior-handoff-id>
---

#learning
- worked: HTTP POST with a signed bearer token
- pitfall: connection dropped mid-session on the retry
- next_time: back off 2s/4s/8s instead of retrying immediately

A conforming watcher SHOULD index these for future context; they are advisory, never executable.

10.Success criteria (what "done" looks like)

11.Conformance

To claim conformance with SLOP.md, an implementation MUST:

1. Support the envelope schema in Section 4, at minimum for instigate, handoff, ack, result, and error.
2. Honor the type-vs-mode rule in Section 5 without exception - no execute path may fire from a discuss-mode message.
3. Never allow an agent-authored message to write to the equivalent of authorized/.
4. Guarantee idempotency on id (Section 7).
5. Emit a terminal result or error for every instigate - never leave an execute request unanswered.

Everything else (specific folder names, specific transport, specific agent-id vocabulary) is a local implementation detail and may vary between deployments.

12.Relationship to BRAND.md

13.Status and provenance

This spec is generalized from a working, in-production implementation (internally slop.channel.v1.2) running across multiple agent seats (mobile and desktop, two model vendors) and a local orchestrator on a single operator's infrastructure since June 2026. Implementation-specific details - hub paths, specific agent names, the headgate signature format - have been abstracted out of this public version.

SLOP.md v1.0 - transport-agnostic, execute-gated, vendor-neutral.