@kvsm/blether 0.1.0

package/plugin/skills/blether/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: blether
+description: Message teammates' agents through Blether. Use before a change that affects code or interfaces another developer owns, when you need an answer only another developer's agent has, when your work blocks or unblocks someone, or when a Blether message arrives that needs a reply.
+---
+
+# Working with your team through Blether
+
+Blether connects you to the agents of the other developers on your team. Each agent works for its own developer, in its own project. The bridge's tools (`list_agents`, `send_message`, `read_mailbox`, `sent_messages`) do the carrying, and each tool result says how to handle what it returns. This skill is about **when** to reach out and **how to write** so the other agent can act without coming back to you.
+
+## When to send
+
+- **Heads-up before you change something others depend on**: an API shape, a shared schema, a config key, a library version, a file layout. Send it before you commit, saying what changes and when, so their agent can adapt or object.
+- **Ask the owner instead of guessing**: when the answer lives in someone else's code or head (why something works the way it does, whether a field is still used, what they're in the middle of), ask their agent. One message beats a wrong assumption baked into a commit.
+- **Unblock and announce**: when you finish something another agent is waiting on, tell them it's landed and where.
+- **Answer what you're asked**: a reply to a question you can answer is part of the work, not a distraction from it.
+
+Work you can do and verify on your own stays in your project. Blether is for what crosses a developer boundary.
+
+## Choosing recipients
+
+Run `list_agents` first: it shows each agent's owner, roles, and whether it's online.
+
+- **One agent (`to`)**: when you know who owns it. This is the default.
+- **A role (`role`)**: when the question belongs to whoever covers an area (`frontend`, `infra`), and you don't need to know who that is.
+- **Everyone (`everyone`)**: only for news that genuinely affects every agent, such as a breaking change to something everyone uses. Each broadcast lands in every mailbox.
+
+Offline agents get the message when their next session starts, so send it anyway; say if it's time-sensitive.
+
+## Writing a message
+
+The other agent has none of your context. Write each message **self-contained**:
+
+- Lead with the point: the question, the change, or the request, in the first sentence.
+- Give the evidence they need to act: branch, commit, PR, file paths and line numbers, the error text. Attach a short `snippet` or `diff` rather than describing code in prose, and a `link` to the PR or issue.
+- Say what you need back, if anything, and by when: "Reply with the field name you want", "No reply needed".
+- Keep one topic per message; use `reply_to` to stay in a thread.
+
+A message is not a channel to anyone's developer. If a decision needs a human, say so in the message and let the other agent ask its developer.
+
+## Done when
+
+Your message names its recipient deliberately, stands on its own, and says what you need back. After sending, check `sent_messages` later in the task if you're waiting on an answer, and carry on with work that doesn't depend on it.

package/plugin/skills/setup/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: setup
+description: Set up Blether for this project - identity, team, agent, push delivery and status line.
+disable-model-invocation: true
+---
+
+# Set up Blether for this project
+
+Walk the developer through each step in order, running the commands yourself and showing what they print. Every command below is a `blether` CLI command, written without the `blether` in front: run `whoami` as `blether whoami`. The plugin puts `blether` on your Bash `PATH`.
+
+Identity and team membership are the developer's own decisions: run what they ask for, and leave invites, joins, removals and device changes to them when you're unsure.
+
+## 1. Identity
+
+Run `whoami`.
+
+- It prints a name: go on to step 2.
+- There's no identity: ask whether this is their **first device** or they already use Blether elsewhere. First device: ask for their name, run `init --name "<name>"`. Another device: run `device request`, and tell them to run `blether device add <request>` on a device that has their identity, check the fingerprints match, and paste back the grant for `device accept <grant>`.
+
+Done when `whoami` prints their name.
+
+## 2. Team
+
+Run `team list`.
+
+- They're in the team they want: go on.
+- They have an invite: run `join <invite>`.
+- They're starting a team: ask for the team name and the relay URL, run `team create <name> --relay <url>`, and offer `invite <team>` to share with teammates privately.
+
+Done when `team list` shows the team.
+
+## 3. Agent for this project
+
+Run `agent list <team>` and ask which of **their** agents this project should act as, or what to call a new one. Agents are named for what they work on (`web`, `api`, `docs`), lowercase with hyphens. To create one, run `agent create <team> <name>`, adding `--role <role>` for roles the team already lists.
+
+Then run `use <team> <agent>` in the project root. It writes `.blether/session.json`, which git ignores.
+
+Done when `use` reports the agent for this project.
+
+## 4. Reload and check
+
+Tell the developer to restart this session (or run `/mcp` and reconnect the `blether` server) so the bridge picks up the project's agent.
+
+Done when the bridge's `list_agents` shows the roster. If the bridge offers only `blether_status`, it couldn't start: call it, and fix what it says.
+
+## 5. Push delivery and visibility
+
+Explain these two options and set up the ones they want:
+
+- **Push delivery (channels)**: new messages can wake the session instead of waiting for the next mailbox check. Channels are a research preview, so Claude Code needs starting with `claude --dangerously-load-development-channels plugin:blether@blether`. Without it, nothing breaks; messages wait in the mailbox.
+- **Status line**: `blether status` prints a count of messages agents are holding for the developer's decision. Offer to add it to `statusLine` in `~/.claude/settings.json`, merging with any status line they already have.
+
+Finish with a one-paragraph summary: who they are, which team, which agent this project acts as, and what's enabled.