handover: Instructions file for Codex

For the agent reading this

This is the entry point, and it is written to be enough on its own for the two things an agent does here: install Soil Handover for somebody, or work on this repository. Rationale and depth live in docs/ and spec/. What you have to DO is here.

What this project is

Soil Handover is an open JSON format for a project's working state, so work saved in one AI tool can be continued in another. A handover carries the decisions with their reasons, the constraints and why they bind, the approaches already rejected, the task in flight and the next step, in a document a person can read and any conformant implementation can parse.

What it solves is a boundary. A session fills up, compacts or ends. The work moves to another agent, another tool, another model provider, or to a colleague. A transcript preserves what was said, but not which decisions are current, which approaches were already abandoned, or what should happen next. A summary is smaller, and compression usually takes the reasons with it. "Use X" survives. "Use X because Y failed under load, and do not reopen Z" often does not, and a decision without its reason is a decision waiting to be relitigated.

This repository holds the whole thing: the specification (1.0.0), five independent implementations of it (TypeScript, Python, Go, JVM and .NET), a soil command line tool, a local MCP server over stdio, a self-hostable server preview, and a conformance suite that every implementation is held to. Apache 2.0, copyright Mastodont AB.

The local round trip needs no account, no network and no telemetry. Handovers are plain JSON files under ~/.soil (or $SOIL_HOME), one file per handover, readable with cat. Nothing in this repository calls a hosted service, needs one, or degrades without one.

Nothing here is published to a package registry yet, so every install today builds from a checkout.

The boundary that is easy to get wrong

A memory system helps an agent remember inside one system. Soil Handover moves the current working state between systems. If you catch yourself explaining this as "so your assistant remembers things", you have described something else.