Shorten bro's @-mention handle — @"tmb:bro (agent)" is too verbose for per-message invocation

[ZaxShen]

Pain

During dogfood, invoking bro in an interactive session requires typing something like:

@tmb:bro

…or worse, whatever the tab-completer produces:

@\"tmb:bro (agent)\"

That's 6–18 characters on every code-touching ask. Bro is the single Human entry point by design — the handle has to be frictionless or the whole routing architecture collapses to "just ask main Claude directly."

What's actually required

• tmb: namespace prefix is CC-enforced to prevent collisions with local agents. We can't drop it at the plugin level.
• (agent) suffix is a CC tab-completion UI label, not part of the actual invocation. @tmb:bro alone works.
• Quotes are added by the tab-completer unnecessarily; plain @tmb:bro is accepted.

Unknown — needs dogfood verification

Does main Claude persist bro's persona across a session after one @tmb:bro invocation, so subsequent messages in the same session route through bro without re-mentioning? If yes, invoke-once UX is acceptable. If no, the per-message cost is real and a shorter form matters.

Test: fresh scratch project, @tmb:bro hello, wait for response, then send "what should I work on?" with no @-mention. If bro handles it, persona persists. If main Claude answers directly, it doesn't.

Options in order of preference

A. Document @tmb:bro as canonical, ignore tab-completer noise

• Pro: zero code change, just clarity.
• Con: still 8 chars per invocation if persona doesn't persist.

B. Project-level proxy agent

• Add instructions in docs: "to type @bro instead, create .claude/agents/bro.md in your project containing a one-line See tmb:bro proxy."
• Pro: gives users the short handle without requiring CC changes.
• Con: per-project setup burden; proxy pattern may not be supported by CC (untested — needs verification).

C. Slash command alternative

• Ship skills/bro/SKILL.md (user-invocable) that spawns tmb:bro.
• Invocation: /bro <ask>.
• Pro: consistent 5 chars; works across projects without setup.
• Con: slash commands and agent spawns are different mechanisms — needs to confirm skill can spawn subagent cleanly; doesn't help if persona-persistence is what we actually need.

D. CC feature request upstream

• Ask Anthropic for an opt-in short form (e.g., @bro when plugin is enabled and no name collision).
• Pro: best long-term answer.
• Con: external dependency; unbounded timeline.

Related

• User entry path to gatekeeper: enforce the routing + shorten the mention handle (@bro) #36 — earlier issue on "shorten handle + enforce routing." The rename gatekeeper → bro closed the rename half; the handle length and the routing-enforcement half are still open. This issue is specifically the handle-length sub-problem. User entry path to gatekeeper: enforce the routing + shorten the mention handle (@bro) #36 can close once both halves resolve.
• PR 📝 dogfood setup: SCENARIOS.md + bun workspaces + doc fixes (closes #40, #42) #41 (current) — surfaced during its dogfood.

Acceptance criteria

• Documented minimum invocation form (@tmb:bro without quotes or parens).
• Dogfood test: does main Claude persist bro's persona across messages after one @tmb:bro? Result recorded in SCENARIOS.md.
• If persona persists → update local-testing.md to reflect "mention bro once, then converse normally." Issue closes with doc change only.
• If persona does NOT persist → pick option B, C, or D and implement. Issue closes when invocation drops to ≤5 chars or user doesn't need per-message mentions.

[ZaxShen]

Premise obsolete — closing as no-longer-applicable.

When this issue was filed, bro lived as a Claude Code subagent (agents/bro.md), so the @-mention handle was the verbose @tmb:bro (agent) rendered by CC's autocomplete. That made per-message invocation painful.

After PR #41 (the bro-as-persona refactor) and PR #58 (bro-as-planner), bro is no longer a subagent. It's a CLAUDE.md persona triggered by the literal word "bro" appearing anywhere in the Human's message (per the trigger rule at the top of CLAUDE.md). The canonical invocation is just bro, do X or @bro do X — there's no autocomplete-rendered subagent handle to shorten.

If discoverability becomes an issue again, that's a different conversation (probably about how the trigger word is documented), but the original concrete bug is gone.