# Quickstart

> Write a first OCP document, validate it, and read a finding.

**1. Write the smallest document**

Save this as `run.ocp.json`. It records one unit of work and nothing else.

```json run.ocp.json
{
  "ocp": "0.3",
  "producer": { "name": "my-orchestrator", "version": "1.0.0" },
  "privacy": { "profile": "metadata_only" },
  "run": { "id": "run_01", "started_at": "2026-09-23T10:00:00-07:00" },
  "nodes": [{ "id": "implement", "kind": "impl" }]
}
```

**2. Install the checker**

The reference checker ships with loopmath, which needs Python 3.11 or newer.

```bash
pipx install loopmath    # or: uv tool install loopmath
```

**3. Validate it**

```bash
loopmath ocp validate run.ocp.json
```

```text Output
PASS  run.ocp.json  (ocp 0.3; 0 errors, 1 warning)
  warning W180 $['producer']: producer.capabilities is absent; consumers cannot distinguish unsupported elements
```

The document conforms. The warning says the producer has not declared what it can record, so a reader cannot tell "this tool does not record cost" from "this run cost nothing". [W180](https://orchestrationcontextprotocol.io/specification/0.3/conformance#w180) explains it.

**4. Add an attempt, its cost and its outcome**

An attempt is one try at a node. Give it the harness, the model as your tool knows it, the reasoning effort, the tokens it used and how it ended. Declare the capabilities you fill.

```json run.ocp.json
{
  "ocp": "0.3",
  "producer": {
    "name": "my-orchestrator",
    "version": "1.0.0",
    "capabilities": { "cost_tokens": true, "outcome_evidence": true }
  },
  "privacy": { "profile": "metadata_only" },
  "run": { "id": "run_01", "started_at": "2026-09-23T10:00:00-07:00" },
  "nodes": [{ "id": "implement", "kind": "impl" }],
  "attempts": [
    {
      "id": "implement.a1",
      "node": "implement",
      "harness": "claude-code",
      "model": { "raw": "claude-opus-5-5" },
      "effort": "high",
      "status": "done",
      "started_at": "2026-09-23T10:00:05-07:00",
      "ended_at": "2026-09-23T10:21:40-07:00",
      "cost": {
        "input_tokens": 12000,
        "cached_input_tokens": 410000,
        "output_tokens": 18500,
        "basis": "measured"
      },
      "outcome": { "result": "done", "evidence": "verified", "receipt": "tests pass 42/42" }
    }
  ]
}
```

```text Output
PASS  run.ocp.json  (ocp 0.3; 0 errors, 0 warnings)
```

**5. Break it on purpose**

Change the attempt's `node` to `implemnt` and validate again:

```text Output
FAIL  run.ocp.json  (ocp 0.3; 1 error, 0 warnings)
  error E112 $['attempts'][0]['node']: attempt 'implement.a1' names unknown node 'implemnt'
```

Every finding names a rule code, a JSON path and what is wrong. The exit code is 1. Look the code up in [Conformance](https://orchestrationcontextprotocol.io/specification/0.3/conformance#e112).

## Next

- [Write OCP from your tool](https://orchestrationcontextprotocol.io/docs/develop/producers): Where to hook in, and the choices every producer makes.
- [Examples](https://orchestrationcontextprotocol.io/examples): Full documents for six workflow shapes.