atcli
A fully featured CLI used as an alternative to AppView applications (Bsky.app/mu.social)
Star 1
Fork 0
Watch

docs: mark every writing command as writing (README, skill, generated reference) #13

Merged pipobscure.com
targeting main from feature/mark-writing-commands
Merged opened by and assigned to pipobscure.com
targeting main from feature/mark-writing-commands

What #

Every runnable command now declares whether it writes:

  • writes: 'network' — changes state on the network: your account, or something other people can see (post, reply, quote, delete, like/unlike, repost/unrepost, bookmark add/remove, gate, profile update/pin/unpin, follow/unfollow, block/unblock, mute/unmute, the list commands, feed save/unsave/pin/unpin, notifications seen, every chat mutation, record create/put/delete, upload, report).
  • writes: 'local' — writes only this machine's state: sessions, config, the shell's startup file (login, logout, account remove/default/refresh, config set/unset/forget, skill install, completion --install/--uninstall).
  • writes: false — reads only.

xrpc is classified as a network write with an extra line in every document: whether it writes depends on the method — queries (GET) read, procedures (POST) write.

Why #

An agent that cannot tell reading from writing will eventually publish by accident. This came out of a real one: an agent ran atcli post <at-uri> believing post was a read ("show this post") and created a junk post; the same session had been silently mis-classifying actions all morning. Every document an agent might read should answer "does this write?" without guessing from the summary line.

How #

  • CommandSpec gains writes?: false | 'network' | 'local', set on every runnable command (91 of them, including the helper-generated families: toggle → like/unlike/repost/unrepost, relationCommand → follow/unfollow/block/unblock, saveCommand → feed save/unsave/pin/unpin, convoAction, reaction, interactions, actorList).
  • src/reference.ts renders a marker line under each writing command's summary, and a "Which commands write" section up top of the generated reference. It refuses to generate while any runnable command lacks the declaration, so a future command cannot silently skip classification — the generation step (and npm test's currency check) fails until it is classified.
  • skills/atcli/SKILL.md gains a Which commands write section: a table of every network write with what it does, a table of the local writes, and the xrpc caveat. Ground rule 4 (ask before acting in public) now points at it.
  • README.md gains a What writes section with the same three kinds.

Tests #

  • npm run typecheck clean.
  • npm test: 67/67 pass (includes the reference-currency check against the regenerated skills/atcli/reference.md).
Commits 0