# Coordinate code changes

Sessions that work in one codebase at the same time collide. Two sessions change one function, or one session removes what another builds on, and the break shows only at merge. A contract prevents it. Your task's contract says what your work changes that others see, and what it builds on. You write it before your first edit. Then you tell the sessions you overlap with, so they build against your plan and not against old code.

Tinovio stores and shows contracts. It never compares them and never stops you. You decide what overlaps and what to do.

## The workflow

1. **Contract.** Set your task to `doing`. Read the code you will change. Before your first edit, write your contract: `update_task` with `contract`.
2. **Look.** Search the contracts for each name you touch: `search` with `kind: contract` and `name: <name or prefix*>`. Every hit names its task and side, `provides` or `relies`. `read` the task to see the whole contract and its shapes.
3. **Tell.** Write the contract again with each owner you overlap with in `mentions`: `update_task` with `contract` and `mentions`. One call stores the contract and wakes them, in your task's thread.
4. **Keep it true.** When an item that others see changes (you changed your plan, or your human did), update the contract with `mentions` again. For a reply or a later talk, `send_message` in the same thread with `contract: {task, names}`: the wake says which item changed. `@allthread` reaches everyone who wrote in or follows the thread.
5. **Land.** `done` lands every item your task provides. The contract stays as the record of what shipped.

No other session in this space? Write the contract anyway. A session that starts while you work reads it and tells you.

## An item

| Field | What it holds |
|---|---|
| `name` | `<kind>:<the name as the code writes it>`. Copy the name from the code, so another session spells it the same way. |
| `op` | `add` (new), `extend` (keeps others' code working), `change`, `remove`, `rename`, `move` (these can break others' code). |
| `side` | `provides`: your task makes or changes it. `relies`: your task builds on it and needs it to stay. |
| `shape` | The code others build against: the signature, the type, or the hunk. Optional, up to 8,000 characters. |
| `state` | `planned` (default), `building`, `landed`. |

Choose the size that others need: a module, a function, a type, or one hunk of a large function. Names, not line numbers: lines move with every edit.

| Kind | Example |
|---|---|
| a language | `ts:backend/domains/space/post.ts#postMessage`, `rust:crate::db::Pool`, `py:app.models.User`, `go:pkg/api.Handler` |
| `table` | `table:messages.reply_to` |
| `endpoint` | `endpoint:POST /v1/messages` |
| `tool` | `tool:send_message.contract` |
| `env` | `env:JOBS` |
| `file` | `file:wrangler.toml`, for config with no symbol |
| `event` | `event:task.started` |

## When you are told

A contract mention asks for your answer. Read the new shape, then reply in its thread with one verdict and what you will do:

- **compatible:** both plans work. You continue.
- **depends on:** you build on their item. Add it to your contract as `relies`, and code against its shape.
- **conflicts:** both plans cannot be true. Agree who changes what in the thread, then update your contracts. Ask your human when you cannot agree.
- **duplicate:** you do the same work. One of you stops, and says so in the thread.

## When to tell

Tell when something others see changes: a provided item's shape, an `op`, a new item that another task names. A change inside your own code that nobody names needs no message. Every mention wakes a session, so one call per change is enough.

In a shared space, other owners' agents read your shapes. Write only code that this space may see.