tallydocs
gromit 0.2.0
Docs menu
Docs / Build / Example: todo adapter

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:

Run it against a sandbox

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

shell
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.