Skip to content

Commit 2f50011

Browse files
authored
docs(sprout-acp): add communication discipline rules to base prompt + deprecate --mention flag (#883)
1 parent 5c2476a commit 2f50011

6 files changed

Lines changed: 16 additions & 34 deletions

File tree

‎TESTING.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -241,8 +241,7 @@ from step 4 and @mention the agent:
241241
```bash
242242
export SPROUT_PRIVATE_KEY=$SENDER_SK # the key from step 4
243243
sprout messages send --channel "$CHANNEL" \
244-
--content "Hey agent, reply PONG only." \
245-
--mention "$AGENT_PUBKEY"
244+
--content "Hey agent, reply PONG only."
246245

247246
# Wait 10–90s, then read the channel — the agent's reply is a kind:9 from
248247
# AGENT_PUBKEY. The current ACP build is quiet on stdout during a turn, so

‎crates/sprout-acp/src/base_prompt.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,13 @@ Run `sprout --help` or `sprout <group> --help` for full usage.
2323
## Communication Patterns
2424

2525
- Address agents and humans with plain `@name` — do NOT bold or italicize mention text (formatting prevents alert delivery).
26+
- Writing `@name` in message content triggers a notification to that person. Only include `@name` when you intend to notify them and need their attention or response. Do not use `@name` in narrative or status updates (e.g., "let me coordinate with @Duncan on this") — save it for the message where you actually need their response.
27+
- Respond promptly to @mentions.
28+
- Be direct. State what you did, what you found, or what you need. No preamble.
2629
- Message content supports GitHub-flavored Markdown. Use fenced code blocks with a language tag (` ```python `, ` ```typescript `, etc.) for syntax-highlighted rendering on desktop and mobile. Omitting the language tag renders monochrome.
27-
- Use `sprout messages thread` when responding in-thread; post new messages for new topics.
30+
- When responding in-thread, use `sprout messages send --reply-to <thread-root-event-id>` to keep replies scoped to the thread. Post new top-level messages for new topics.
31+
- When you are mentioned in multiple threads, prioritize the most recent one chronologically. If someone steers or redirects you in a newer thread while you are working from an older dispatch, reply in the newer thread to acknowledge — do not bury your response in the original thread where it may go unseen.
32+
- When you complete a task (e.g., PR created, implementation finished, research delivered), post a top-level channel message with the result — do not only reply in-thread. Thread notifications are easy to miss; a broadcast message ensures the requester sees the outcome promptly.
2833
- No push notifications — poll with `sprout messages get --channel <UUID> --since <ts>`. When `since` is set without `before`, results are oldest-first (chronological).
2934

3035
## Startup Recovery

‎crates/sprout-cli/TESTING.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -201,9 +201,8 @@ REPLY=$(sprout messages send --channel "$CHANNEL_ID" --content "Reply" \
201201
echo "$REPLY"
202202
REPLY_ID=$(echo "$REPLY" | jq -r '.event_id')
203203

204-
# messages send with mentions
205-
sprout messages send --channel "$CHANNEL_ID" --content "Hey @someone" \
206-
--mention "0000000000000000000000000000000000000000000000000000000000000001" | jq .
204+
# messages send with mentions — @name in content is auto-resolved, no flag needed
205+
sprout messages send --channel "$CHANNEL_ID" --content "Hey @someone" | jq .
207206

208207
# messages send from stdin — safe path for content with shell metacharacters
209208
# (backticks, $vars, code blocks) that would otherwise be expanded by the shell.

‎crates/sprout-cli/src/commands/messages.rs‎

Lines changed: 3 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,7 @@ use crate::validate::{
88
infer_language, parse_event_id, parse_uuid, read_or_stdin, truncate_diff,
99
validate_content_size, validate_hex64, validate_uuid, MAX_DIFF_BYTES,
1010
};
11-
use sprout_sdk::mentions::{
12-
extract_at_names, match_names_to_profiles, merge_mentions, normalize_mention_pubkeys,
13-
MentionProfile, MENTION_CAP,
14-
};
11+
use sprout_sdk::mentions::{extract_at_names, match_names_to_profiles, MentionProfile};
1512

1613
// ---------------------------------------------------------------------------
1714
// Helpers
@@ -348,7 +345,6 @@ pub struct SendMessageParams {
348345
pub kind: Option<u16>,
349346
pub reply_to: Option<String>,
350347
pub broadcast: bool,
351-
pub mentions: Vec<String>,
352348
pub files: Vec<String>,
353349
}
354350

@@ -365,10 +361,6 @@ pub async fn cmd_send_message(
365361
if let Some(ref r) = p.reply_to {
366362
validate_hex64(r)?;
367363
}
368-
for m in &p.mentions {
369-
validate_hex64(m)?;
370-
}
371-
372364
let channel_uuid = parse_uuid(&p.channel_id)?;
373365

374366
// Upload files and build imeta tags
@@ -402,13 +394,10 @@ pub async fn cmd_send_message(
402394
None
403395
};
404396

405-
// Normalize explicit mentions, then merge auto-resolved up to the SDK mention cap.
406-
// Auto-resolution scans the author-written body only — not the media markdown we
397+
// Resolve @name mentions in the author-written body only — not the media markdown we
407398
// append above, which is derived from upload metadata and can't carry `@names`.
408-
let mut merged: Vec<String> = normalize_mention_pubkeys(&p.mentions, None);
409399
let auto_resolved = resolve_content_mentions(client, &p.channel_id, &p.content).await;
410-
merge_mentions(&mut merged, &auto_resolved, MENTION_CAP);
411-
let mention_refs: Vec<&str> = merged.iter().map(|s| s.as_str()).collect();
400+
let mention_refs: Vec<&str> = auto_resolved.iter().map(|s| s.as_str()).collect();
412401

413402
let builder = match p.kind {
414403
Some(45001) => {
@@ -630,7 +619,6 @@ pub async fn dispatch(
630619
kind,
631620
reply_to,
632621
broadcast,
633-
mentions,
634622
files,
635623
} => {
636624
cmd_send_message(
@@ -641,7 +629,6 @@ pub async fn dispatch(
641629
kind,
642630
reply_to,
643631
broadcast,
644-
mentions,
645632
files,
646633
},
647634
)

‎crates/sprout-cli/src/lib.rs‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -248,9 +248,6 @@ pub enum MessagesCmd {
248248
/// Also publish to the Nostr network
249249
#[arg(long, default_value_t = false)]
250250
broadcast: bool,
251-
/// Explicit mention pubkeys (64-char hex)
252-
#[arg(long = "mention")]
253-
mentions: Vec<String>,
254251
/// Attach file(s) — uploads and includes as imeta tags
255252
#[arg(long = "file")]
256253
files: Vec<String>,

‎desktop/src-tauri/src/managed_agents/nest_skill.md‎

Lines changed: 4 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -55,19 +55,14 @@ Write commands are unaffected. `--format json` (default) returns full fields.
5555

5656
## Communication Patterns
5757

58-
**Mentions that notify:** Always include `--mention <hex_pubkey>` for each person you `@`-mention in content. The `@Name` text is display-only — without the corresponding `--mention` flag, no notification fires. Look up pubkeys with `sprout users get --name <display_name>`.
58+
**Mentions that notify:** Use `@Name` directly in message content — the CLI auto-resolves channel members by name and adds the required p-tags. No `--mention` flag exists or is needed.
5959

6060
```bash
61-
# ✅ Correct — notification delivered
62-
sprout messages send --channel <UUID> --content "@Alice check this" \
63-
--mention deadbeef1234...
64-
65-
# ❌ Wrong — mention is cosmetic only, no notification
61+
# ✅ Correct — notification delivered automatically
6662
sprout messages send --channel <UUID> --content "@Alice check this"
6763

68-
# Multiple mentions
69-
sprout messages send --channel <UUID> --content "@Alice @Bob review please" \
70-
--mention <alice_hex> --mention <bob_hex>
64+
# Multiple mentions — same pattern
65+
sprout messages send --channel <UUID> --content "@Alice @Bob review please"
7166
```
7267

7368
## DM Management

0 commit comments

Comments
 (0)