refactor(buzz-acp): point agents at buzz --help instead of a command table (#7586)

## Summary

The ACP base prompt carried a `Group | Key commands` table for the
`buzz` CLI — a second copy of a surface that already documents itself,
with nothing tying it to the parser. It had already drifted: 16 of the
CLI's 23 groups (missing `emoji`, `gifs`, `notes`, `patches`, `media`,
`moderation`, `pack`) and 50 of the 91 subcommands under the groups it
did list. The adjacent exit-code line stopped at 4; the CLI has a 5th (5
= write conflict, NIP-33 LWW).

#7584 was the prerequisite: `buzz --help` now renders the full command
tree — every group, its subcommands, and their descriptions — in one
invocation (199 lines, 13 KB), generated from clap's own command
definition, so it cannot drift. `buzz -h` still prints the group-level
summary. Pointing the prompt at `--help` was not viable before that,
because discovering `buzz messages send` cost a second call and
discovering `buzz canvas set` exists cost a third.

So this replaces the table with a pointer to `buzz --help`, fixes the
exit codes, and adds the one CLI ergonomic that `--help` does not make
obvious (`--format compact` is a global flag that goes before the
subcommand). Everything after the table is kept verbatim — it is the
non-discoverable semantics `--help` cannot express: multiline content
through stdin, the `BUZZ_AUTH_TAG` requirement for agent drafts,
`--channel` on `pr open`, the `link` field, mention and assignment
rules.

Signed-off-by: Salman Mohammed <smohammed@squareup.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Salman Mohammed
2026-09-11 14:07:12 -04:00
committed by GitHub
parent 44c1cc7df8
commit e17cdd9d5c

View File

@@ -3,26 +3,13 @@ Buzz is a desktop and mobile collaboration app organized around channels, conver
## Buzz CLI
The `buzz` CLI is your primary interface. Auth env vars: `BUZZ_RELAY_URL`, `BUZZ_PRIVATE_KEY`, `BUZZ_AUTH_TAG`. Exit codes: 0 ok, 1 user error, 2 network, 3 auth, 4 other. Output is structured JSON.
The `buzz` CLI is your primary interface. Run `buzz --help` once for the full
command tree, and `buzz <group> <sub> --help` for flags and examples. Before
assuming a capability doesn't exist, check `buzz --help`.
| Group | Key commands |
|-------|-------------|
| `buzz agents` | `draft-create`, `draft-update` |
| `buzz messages` | `send`, `get`, `thread`, `search` |
| `buzz channels` | `list`, `get`, `create`, `join`, `members` |
| `buzz canvas` | `get`, `set` |
| `buzz reactions` | `add`, `remove` |
| `buzz dms` | `list`, `open` |
| `buzz users` | `get`, `set-profile`, `presence` |
| `buzz workflows` | `list`, `trigger`, `runs` |
| `buzz feed` | `get` |
| `buzz social` | `publish`, `notes` |
| `buzz repos` | `create`, `get`, `list` |
| `buzz projects` | `create`, `get`, `list`, `add-repo`, `add-channel` |
| `buzz issues` | `create`, `get`, `list`, `status`, `assign` |
| `buzz pr` | `open`, `update`, `get`, `list`, `status` |
| `buzz upload` | `file` |
| `buzz mem` | `set`, `get`, `ls`, `patch`, `rm` |
Auth env vars: `BUZZ_RELAY_URL`, `BUZZ_PRIVATE_KEY`, `BUZZ_AUTH_TAG`. Exit codes:
0 ok, 1 user error, 2 network, 3 auth, 4 other, 5 write conflict. Output is
structured JSON. `--format compact` is global — it goes before the subcommand.
Run `buzz --help` or `buzz <group> --help` for full usage. For multiline message content, pass real newline bytes through stdin: `printf 'first\n\nsecond\n' | buzz messages send ... --content -`. Do not write `--content 'first\n\nsecond'`: single-quoted shell strings preserve `\n` literally, so recipients will see the backslash characters. `buzz agents draft-create` and `buzz agents draft-update` require `BUZZ_AUTH_TAG`; if it is missing, explain that this managed agent cannot open owner-reviewed agent drafts from chat.