User entry path to gatekeeper: enforce the routing + shorten the mention handle (@bro)

[ZaxShen]

Two coupled concerns

Concern 1 — The gatekeeper isn't actually enforced as the entry point

Today's plugin CLAUDE.md describes gatekeeper as "single Human entry point" but that's descriptive, not prescriptive. There's no rule that forces main Claude to spawn the gatekeeper subagent on every Human message. So in practice:

• User types "implement feature X" → main Claude reads CLAUDE.md → may-or-may-not spawn gatekeeper. Model judgment call.
• User types @architect ... → bypasses gatekeeper entirely.
• User types @swe ... → bypasses architect AND gatekeeper.

The flow we drew in docs/architecture/FLOWS.md (Human → Gatekeeper → architect → swe → pr-reviewer) is the intent, not what's mechanically enforced.

Fix options:

Option	Mechanism	Pros	Cons
A — Prescriptive CLAUDE.md rule	Add a top-of-file rule: "On every Human message, immediately spawn gatekeeper via Task tool. Never answer directly. Never spawn other agents directly except via gatekeeper's routing."	Cheap, no CC changes	Soft enforcement — model still decides
B — UserPromptSubmit hook	Hook intercepts every user prompt, prepends "use the gatekeeper agent" instruction	Hard enforcement at prompt layer	Can still be bypassed by explicit @-mention
C — Plugin manifest defaultAgent	If plugin.json schema supports declaring an entry-point agent that intercepts all messages	Clean, declarative	Need to verify CC supports this — currently unknown

Concern 2 — @gatekeeper is too verbose; user wants @bro

@gatekeeper is 11 characters after the @. The plugin's default identity.gatekeeper_name is bro (3 characters), and that's the persona the agent uses in conversation. Asymmetry: persona = bro, mention = @gatekeeper. User prefers a single short handle they can hammer on the keyboard.

Wrinkle: the user can rename the persona via identity_set(gatekeeper_name='alex'). CC's @-mention syntax addresses agents by filename, not by runtime-derived persona name. So the mention handle has to be a fixed file name, decoupled from the per-project persona.

Fix options for the handle:

Option	Approach	Tradeoff
A — Rename file agents/gatekeeper.md → agents/bro.md	Mention becomes @bro. Persona stays runtime-controlled via identity.gatekeeper_name.	"bro" is a colloquial handle; "gatekeeper" is the canonical role. Have to update all internal refs.
B — Add agents/bro.md as a redirect / duplicate	Both @gatekeeper and @bro work.	Two files, drift risk; CC may complain about duplicate role names.
C — Pick a different short canonical handle (e.g. agents/tmb.md)	Plugin-branded, short, persona-agnostic.	New name to teach users; less intuitive.

Recommendation pending dogfood: probably A (rename file). Persona is mutable; mention handle is just a keyboard shortcut.

What needs dogfooding to decide

I genuinely don't know which of these matter most until the plugin is exercised in a fresh project. Specifically:

1. Does main Claude actually spawn gatekeeper without explicit @-mention? Test by installing the plugin in a fresh project and just typing "add a hello-world endpoint". Watch what happens.
2. What does @gatekeeper feel like to type 50 times in a session? vs. @bro?
3. Can @-mentions even be used as primary invocation, or do users default to bare prompts?
4. What happens if user types @architect? Does the architect honor the bypass, or refuse and route back?

Acceptance criteria

• Dogfood test report (above 4 questions answered with observed behavior)
• Decision on enforcement mechanism (A / B / C from concern 1)
• Decision on handle (A / B / C from concern 2)
• CLAUDE.md updated with the chosen enforcement rule
• If file rename — agents/gatekeeper.md → agents/bro.md (or whatever) and every cross-reference updated (CLAUDE.md, README.md, FLOWS.md, ERD.md, agent prompts citing gatekeeper, the KNOWN_ROLES set in middleware/agent-scope.ts)
• PR-reviewer overlay still works (it queries tasks by branch_id; not coupled to gatekeeper file name)
• FLOWS.md "How does the Human reach gatekeeper?" answer added explicitly

Why both concerns at once

If we rename to @bro AND keep the soft enforcement, the user types @bro → mention works. If we enforce hard but keep @gatekeeper, the user never types the handle so verbosity doesn't matter (main Claude handles routing). The two fixes interact — solving them together gives the cleanest UX. Dogfood will reveal which combination feels right.

[ZaxShen]

Superseded by #58 + the earlier rename: gatekeeper became bro, and bro is now both router and planner. The user-entry-path enforcement is the trigger rule at the top of CLAUDE.md.