# Example: a todo-list adapter

A complete adapter in about 150 lines of standard-library Python. The tool is
a JSON file of todos, so the adapter logic is the only thing to read.
Replace `load_tool` and `save_tool` with your own tool's API and keep the rest.

| File | What it is |
|---|---|
| `todo_adapter.py` | the adapter: one pass out, one pass in, a loop |
| `todo.adapter.yaml` | its manifest, for `gromit conformance` |

What it does:

- **Out.** Each todo with a `repo` becomes a `work-item@1` that you hold, with
  the todo's id in `ext.todo`. Ticking it locally marks the work item `done`.
- **In.** A work item you hold that this tool didn't make (a board ticket, an
  offer you accepted) is added to the list once.

## Run it against a sandbox

Never against the team's grouping while you're trying things.

```sh
PERSON=sam docs/sandbox.sh start          # then paste the export line it prints
cd docs/examples/todo-adapter
cat > todos.json <<'EOF'
[{"id": "t1", "title": "Rotate the Snowflake key", "done": false, "repo": "git:platform"},
 {"id": "t2", "title": "Buy milk", "done": false}]
EOF
```

The output below is from a real run on 18 Nov 2026 with gromit 0.2.0.

```
$ python3 todo_adapter.py --todos todos.json --dry-run
would {"contract": "work-item@1", "verb": "created", "entity": null, "payload": {"title": "Rotate the Snowflake key", "repo": "git:platform", "ext.todo": "t1"}}
published 0

$ python3 todo_adapter.py --todos todos.json --once
created        applied                1220847fffa73e  Rotate the Snowflake key
claimed        applied                1220847fffa73e
published 2

$ python3 todo_adapter.py --todos todos.json --once            # nothing new: publishes nothing
published 0

$ gromit do work-item@1 created -s title="Review the relay alarms" -s repo=git:platform
fd05d713e5 applied
$ gromit do work-item@1 claimed --entity fd05d713e5
e038d5ad7e applied

$ python3 todo_adapter.py --todos todos.json --once            # after ticking t1 in todos.json
state_changed  applied                1220847fffa73e
seeded         from the bus           1220fd05d713e5  Review the relay alarms
published 1

$ gromit conformance todo.adapter.yaml --in sandbox     # from this directory
pass fold tests
     16 of 16 passed
pass order
     0 shuffled-order failures
pass round trip
     probe survived on 1 entities
pass no lossy write-back
     first pass published 0, second 0
pass produces only its verbs
skip enforcer tests
     no enforcers in v0

compliant (enforcer tests aside)
```

`Buy milk` has no `repo`, so it stays private to the tool.

`docs/sandbox.sh clean` removes the sandbox.

## On your real grouping

Change `person:` in the manifest to your name. Run the adapter without
`--socket`: it finds `~/.local/share/gromit/<grouping>/sidecar.sock`. Run
`--dry-run` first and read what it would publish. Everything goes to the
whole team.
