tallydocs
gromit 0.2.0
Docs menu
Docs / Agents / For agents · llms.txt

For agents

Point your coding agent here before it touches Tally. Every page of these docs is also plain Markdown, and /llms.txt is the index: what Tally is, the rules a safe adapter follows, and where each page lives.

Give this to your agent

Paste this into Claude Code, or your agent's instructions:

Before writing or changing anything that talks to Tally, read
https://tallyprotocol.dev/llms.txt and follow its rules. Fetch the .md pages it links to
as you need them. Test only in a sandbox grouping (docs/sandbox.sh).

Every page as Markdown

Swap a page's address for .md: /concepts.md, /sidecar-api.md. Same content, no layout. llms.txt lists them all and is short on purpose: an agent reads it first, then follows the links it needs.

The MCP tools are already there

gromit local install registered them in Claude Code as <you>/claude, under the default mandate: tally_status, tally_state, tally_inbox and tally_do. See Get started.

The rules, and why

  1. Talk only to your person's sidecar. It holds the key and judges every event. Nothing else on the machine can publish, and nothing needs to.
  2. Read outcome on every POST /do. The sidecar answers 200 even when it rejects. A rejected event is never stored or sent, and sending it again gets the same answer.
  3. Compare with /state every pass. It's the fold of everything everyone did. Your own memory of what you sent isn't, so trusting it publishes things twice.
  4. Put your tool's id on created. One ext.<tool> key on the creating event means a crash can never leave an item you won't recognise next pass.
  5. Move state with its own verb. edited with a state is rejected. Use state_changed, and claim an item before marking it done.
  6. Leave change sets to the bridge. The GitLab bridge opens one per MR, so one from an adapter would be a duplicate. Link your planning to the bridge's with change-set@0 linked.
  7. Never test on the team's grouping. Events can't be deleted. A sandbox grouping takes one command and is gone with another.
  8. Assume the whole team reads it. Every event goes to everyone in the grouping. Publish only what the tool marks as shared.

When the docs and the code disagree

The code wins. Say so in your answer, name the file and line, and carry on with what the code does. Then tell your person, so the page gets fixed.

For people: checking your agent's adapter

See Writing an adapter for the whole procedure.