OpenSpec Standards

The OpenSpec v0.1 standard defines the protocol and data structures used by ContextSubstrate to ensure AI agent executions are interoperable, verifiable, and content-addressed. By adhering to this specification, ctx creates a "substrate" where agent logs are transformed into immutable artifacts called Context Packs.

The Context Pack Manifest

At the core of the OpenSpec standard is the Manifest. A Context Pack is a JSON document that follows a strict schema to ensure portability across different execution environments. To maintain integrity, all manifests must be serialized using Canonical JSON (deterministic key ordering) before hashing.

Manifest Schema (v0.1)

| Field | Type | Description | | :--- | :--- | :--- | | version | string | The OpenSpec version (currently 0.1). | | hash | string | The content-addressed identity of the pack. | | created | datetime | ISO 8601 timestamp of pack finalization. | | model | object | Metadata about the LLM used (ID and hyperparameters). | | system_prompt | string | A blob reference (hash) to the system instructions. | | prompts | array | List of user/assistant prompt objects with content references. | | inputs | array | Files or data provided to the agent before execution. | | steps | array | Sequential log of tool calls, reasoning, and intermediate outputs. | | outputs | array | Final artifacts produced by the agent. | | environment | object | OS, runtime, and tool versioning metadata. |

Content Addressing and URIs

OpenSpec utilizes a flat-file, content-addressed storage model. Every piece of data—from a 10MB input file to a single system prompt—is stored as a "blob" named by its SHA-256 hash.

The ctx:// URI Scheme

The protocol defines a standard URI format for referencing context packs and their internal blobs:

ctx://<hash>

These URIs are used within the CLI and manifest to point to specific execution states. When a pack is "forked," the new pack maintains a parent reference to the original hash, creating a directed acyclic graph (DAG) of agent iterations.

Execution Steps and Tool Calls

To support reproducibility, OpenSpec captures every "Step" an agent takes. Each step must record whether it was deterministic.

{
  "index": 0,
  "type": "tool_call",
  "tool": "filesystem_read",
  "parameters": {
    "path": "config.json"
  },
  "output_ref": "sha256:e3b0c442...",
  "deterministic": true,
  "timestamp": "2023-10-27T10:00:00Z"
}

Drift Classification Standards

A primary goal of OpenSpec is to make agent behavior "contestable." The standard defines specific types of Drift used when comparing two execution packs (ctx diff). These classifications help developers pinpoint exactly where an agent's logic diverged:

| Drift Type | Description | | :--- | :--- | | prompt_drift | Differences in system instructions or user-provided prompts. | | tool_drift | A change in which tool was selected for a specific step. | | param_drift | The same tool was called but with different arguments. | | reasoning_drift | The tool and parameters matched, but the agent produced a different output. | | output_drift | Differences in the final artifacts or files generated. |

Environment Provenance

For an execution to be truly reproducible, the environment must be documented. OpenSpec v0.1 requires the following metadata:

• OS/Arch: The operating system and architecture (e.g., darwin/arm64).
• Runtime: The language version (e.g., go1.22).
• Tool Versions: A map of specific versions for every tool available to the agent.

This ensures that if an agent fails during ctx replay, the developer can verify if the failure was due to logic drift or environment mismatch.