From e17cdd9d5c7e2b836b4670ae88bb87a79f94337a Mon Sep 17 00:00:00 2001 From: Salman Mohammed Date: Fri, 11 Sep 2026 14:07:12 -0400 Subject: [PATCH] refactor(buzz-acp): point agents at buzz --help instead of a command table (#7586) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 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 Co-authored-by: Claude Opus 5 --- crates/buzz-acp/src/base_prompt.md | 25 ++++++------------------- 1 file changed, 6 insertions(+), 19 deletions(-) diff --git a/crates/buzz-acp/src/base_prompt.md b/crates/buzz-acp/src/base_prompt.md index 305d5b8880..1a5e69cdcf 100644 --- a/crates/buzz-acp/src/base_prompt.md +++ b/crates/buzz-acp/src/base_prompt.md @@ -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 --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 --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.