/role

name: role
description: Set this Claude session's agent-bus role so other sessions can address it (e.g. /role frontend, /role backend, /role tester)
args: "<role-name>"

Set this session's agent-bus role so peers can send it directed messages with `claudectl bus send <role> …`. The binding is **PID-keyed** — it follows this exact Claude Code process, so re-runs in the same project don't get confused by other sessions sharing the cwd.

Common role names: `spec`, `frontend`, `backend`, `data-analyst`, `tester`, `infra`, `reviewer`, `planner`. Pick whatever maps to what this session will actually own.

What to do

1. The user supplied a role name as `{{args}}`. If it's empty, run `claudectl bus role suggest --json --top 3` to fetch transcript-derived candidates and propose them; if even that comes back empty, ask the user what to name the role and stop until they reply.

2. Run:

   claudectl bus role bind --self {{args}}

The `--self` flag tells the CLI to walk the ancestor process chain, find this Claude Code process, and bind the role to that pid + the current working directory. No need to look up the pid yourself.

3. On success the command prints `bound role <name> -> <cwd> (pid=<pid>)`. Echo that confirmation back to the user.

4. If the command errors with "could not find a Claude Code process in the ancestor chain", the plugin was invoked outside the normal `claude` execution context. Tell the user to try again from inside a Claude session, or pass an explicit pid via `claudectl bus role bind <name> <cwd> --pid <pid>`.

5. If the user wants to verify the binding, suggest `claudectl bus role list` or `claudectl bus whoami --json`.

Why pid-binding

Cwd-only bindings get ambiguous when two Claude sessions run in the same folder (e.g. worktrees, or one session in `/repo` and another in `/repo/sub`). The pid binding picks the specific session you ran `/role` from, so directed messages land where you expect.

See issues #307 (pid binding) and #310 (this slash command).