docs(buzz-acp): rewrite Communication Patterns for mention accuracy and threading clarity#982
Merged
Merged
Conversation
…nd threading clarity Agents were using partial display names (@will instead of @will Pfleger), causing silent mention failures. Threading rules were ambiguous about when to reply at thread root vs nest, leading to buried messages humans couldn't find. Agents also forgot to callback-mention delegators after completing work, stalling orchestration. Restructures the section into Mentions, Callback Mentions, Threading, and General subsections with explicit rules for human-facing vs agent-to-agent reply targeting. Co-authored-by: Will Pfleger <wpfleger@block.xyz> Signed-off-by: Will Pfleger <wpfleger@block.xyz>
Same semantic rules, ~40% fewer tokens. Reduces context window cost for every agent session without losing any behavioral guidance. Co-authored-by: Will Pfleger <wpfleger@block.xyz> Signed-off-by: Will Pfleger <wpfleger@block.xyz>
wesbillman
approved these changes
Jun 11, 2026
tlongwell-block
pushed a commit
that referenced
this pull request
Jun 12, 2026
Co-authored-by: npub1mprnacetjua2xx3p5eddmhxyk6wv929ymm5py8kd2xfxurxahspqqlgyta <d8473ee32b973aa31a21a65adddcc4b69cc2a8a4dee8121ecd51926e0cddbc02@sprout-oss.stage.blox.sqprod.co> Signed-off-by: npub1mprnacetjua2xx3p5eddmhxyk6wv929ymm5py8kd2xfxurxahspqqlgyta <d8473ee32b973aa31a21a65adddcc4b69cc2a8a4dee8121ecd51926e0cddbc02@sprout-oss.stage.blox.sqprod.co> * origin/main: (35 commits) feat(huddle): sentence-at-a-time voice-mode guidelines for lower TTS latency (#996) Shard desktop Playwright CI jobs (#992) chore(release): release version 0.3.18 (#995) Video Player Improvements (#993) Improve first-run welcome setup (#970) fix(release): use legacy updater key secret (#991) Replace built-in personas with Fizz (#987) docs(buzz-acp): rewrite Communication Patterns for mention accuracy and threading clarity (#982) chore(justfile): build git-credential-nostr in dev and staging recipes (#980) Fix Buzz command migration for saved agents (#979) fix(desktop): resolve effective model and prompt from persona in display path (#972) docs: clean up remaining Buzz references (#977) chore(release): release version 0.3.17 (#976) fix(onboarding): skip onboarding when relay already has a profile (#973) docs: finish Buzz rename cleanup (#974) fix(desktop): let channel members bypass mention agent gate (#965) Rename desktop app to Buzz (#960) feat(desktop): open profile panel from MembersSidebar rows (#962) feat(desktop): per-event notification sounds and alert controls (#968) fix(desktop): make header chrome zoom-correct and tidy split-pane (#941) ... # Conflicts: # crates/buzz-agent/README.md # crates/buzz-agent/src/config.rs
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rewrites the Communication Patterns section of the base agent system prompt (
crates/buzz-acp/src/base_prompt.md) to fix three problems:Partial mention failures — agents were writing
@Willinstead of@Will Pfleger, causing silent notification failures. New rules require the exact full display name.Stalled orchestration from missing callback mentions — agents completing delegated work forgot to
@mentionthe delegator, leaving them with no notification that work was done. New "Callback Mentions" subsection makes this mandatory.Buried human-facing messages in nested threads — agents replied at arbitrary thread depths, making it hard for humans to follow. New threading rules: reply to thread root when addressing a human (with mandatory
@mention), nest freely when talking to other agents.The section is restructured into four subsections: Mentions, Callback Mentions, Threading, and General.