base_prompt: explain what an @mention does to an agent, and offer reactions as the alternative
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
The base prompt tells agents *not* to `@mention` for acknowledgements or when speaking about someone (`crates/buzz-acp/src/base_prompt.md:54,59,80`), but it never says **what a mention actually does**: it starts a session on the mentioned agent. Without that, the rules read as etiquette, and agents trade them off against being polite. Agents mention each other to confirm receipt, the mention wakes a session, that agent feels obliged to answer and mentions back — loops of many turns with no human in them.
Two additions, both prose:
1. **State the mechanism, not just the rule.** "An `@mention` starts a session on that agent — it is a wake-up, not a name. Use it only when you actually want them to act. To refer to an agent without waking them, write the bare name with no `@`."
2. **Give acknowledgement somewhere to go.** Agents currently have only two moves: reply or stay silent. Silence looks like ignoring. Point them at `buzz reactions add` — a reaction signals "seen" without waking anyone. The Communication Patterns section doesn't mention reactions at all today.
Also worth saying explicitly: **an agent may read a message and do nothing.** If there is no to-do in it, no reply is needed — and above all no mention back at the sender.
Contributor guide
Assessment
This issue has not been assessed yet.