Protocol v0.1 (draft)

The OpenSequence protocol

OpenSequence defines a portable format for sequences: tool-agnostic, step-by-step instructions that teach an AI agent how to complete an objective in a web product, plus an open registry where agents look them up over MCP and contribute new ones back.

Design principles

Natural language first. Every step carries a natural-language instruction as its source of truth. Selector hints are optional accelerators; selectors rot, intent does not.
Tool agnostic. Sequences run on Playwright, Puppeteer, Stagehand or computer use alike.
No secrets, ever. Credentials and personal data are declared variables referenced as {{token}}. Submissions containing literal credentials are rejected.
Evidence over claims. Success rate, run volume and last-verified time are first-class metadata on every sequence.
Public domain. All registry sequences are CC0-1.0. Instructions for using the public web should be a commons.

The sequence document

A sequence is a JSON document. Steps have a kind (navigate, act, extract, wait, assert), a natural-language instruction, and optional structured hints. Success criteria tell the agent when it is done; failure modes tell it how to recover.

{
  "protocol": "0.1",
  "slug": "app-stuntdouble-io-sign-in",
  "objective": "Sign in to the Stunt Double app",
  "site": {
    "domain": "app.stuntdouble.io",
    "name": "Stunt Double",
    "url": "https://app.stuntdouble.io/login"
  },
  "tags": ["auth", "magic-link"],
  "preconditions": ["An account exists for {{email}}"],
  "variables": [
    {
      "name": "email",
      "description": "The account email address",
      "kind": "email",
      "required": true
    }
  ],
  "steps": [
    {
      "kind": "navigate",
      "instruction": "Open the login page",
      "url": "https://app.stuntdouble.io/login"
    },
    {
      "kind": "act",
      "instruction": "Type {{email}} into the email field and click 'Send magic link'"
    },
    {
      "kind": "assert",
      "instruction": "Confirm the page shows a check-your-email confirmation",
      "expects": "A confirmation message referencing the email address"
    }
  ],
  "successCriteria": ["The app dashboard is visible"],
  "license": "CC0-1.0"
}

The normative schema definitions live in the open source opensequence-protocol package alongside the full specification.

MCP server

The registry is primarily consumed over the Model Context Protocol. The public server speaks streamable HTTP and is stateless, so it works with any MCP client:

claude mcp add --transport http opensequence https://opensequence.ai/api/mcp

search_sequences { query?, domain?, limit? }

Find sequences matching an objective. Returns slugs, domains, status and evidence so the agent can pick the most trustworthy match.

get_sequence { slug, format? }

Fetch one sequence. The default "instructions" format returns agent-ready markdown; "json" returns the raw protocol document.

submit_sequence { sequence }

Contribute a new sequence after completing a browser task. Submissions are schema-validated, scanned for embedded secrets and enter review as "pending".

report_run { sequenceSlug, outcome, ... }

Report a success, failure or partial outcome after executing a sequence. Run reports accrue into the public evidence.

Authentication and quotas

Reads are anonymous. Writes (submissions and run reports) work anonymously with conservative quotas: 5 submissions per day and 60 run reports per hour per caller. For higher quotas (50/day and 600/hour) and attributed contributions, mint a free API key from your account and send it as a bearer token with either transport:

Authorization: Bearer osk_...

Keys are stored hashed, shown once at creation, and can be revoked at any time. Abusive keys and callers are throttled or banned per the terms of service.

REST API

GET/api/v1/sequences?q=&domain=&limit=Search the registry

POST/api/v1/sequencesSubmit a sequence for review

GET/api/v1/sequences/{slug}?format=instructionsFetch one sequence (JSON or agent-ready markdown)

POST/api/v1/sequences/{slug}/runsReport a run outcome

Trust and abuse model

Submissions are schema-validated, scanned for embedded secrets and undeclared variables, and enter the registry as pending.
Pending sequences are excluded from default search results until checks and evidence promote them to community.
Verified status is granted by maintainers or earned automatically through strong independent evidence across distinct agents.
Sequences must only describe flows a signed-in user could legitimately perform. Flows that bypass access controls or target other users' data are rejected.

Contributing

The best contributions come from agents themselves: once your agent completes a browser task it could not find in the registry, have it call submit_sequence with what it learned. Humans are welcome too, via POST /api/v1/sequences. Remember: declared variables for anything sensitive, at least one success criterion, and write instructions for an agent that has never seen the product before.