@popoverinstall/cli 0.8.1 → 0.9.0

package/plugin/scripts/roster.mjs

@@ -1,52 +1,52 @@
-#!/usr/bin/env node
-// Renders the /team menu.
-//
-// Invoked from the command's `!` injection, so its stdout becomes part of the prompt
-// Claude sees. Two consequences shape everything here:
-//   - always exit 0. A non-zero exit aborts the whole slash command.
-//   - always print something useful. If the daemon is down, say so in words the model
-//     can relay, rather than printing an empty section and letting it invent a reason.
-
-import { callerSessionId, request } from "./_ipc.mjs";
-
-// `fromSessionId` is what lets the daemon mark this agent's own line. It comes from the
-// session's environment, so a bare shell run of this script sends nothing and the roster
-// comes back unmarked.
-const reply = await request(
-  {
-    t: "roster",
-    id: "cli",
-    refresh: true,
-    ...(callerSessionId() ? { fromSessionId: callerSessionId() } : {}),
-    // Fallback for the window where the daemon has not yet resolved this session's repo —
-    // the same hint the MCP server sends. Without it an unplaceable caller falls through to
-    // pure recency across every session on the machine, so `/popover:team` run in one repo
-    // could print the roster for another, under a heading claiming it was this one.
-    cwd: process.cwd(),
-  },
-  { timeoutMs: 8000 },
-);
-
-if (!reply) {
-  console.log(
-    "The popover daemon is not running on this machine, so teammate agents are not visible.\n" +
-      "Start it with `popover daemon start`, or check `popover doctor`.",
-  );
-} else if (reply.t === "error") {
-  // The daemon distinguishes "no credentials" from "signed in but cannot connect", so
-  // relay its message rather than assuming the user has not logged in.
-  console.log(
-    reply.code === "not_authenticated"
-      ? reply.message
-      : `Could not load the team roster: ${reply.message}`,
-  );
-} else if (reply.t === "roster.ok") {
-  console.log(reply.rendered);
-  if (reply.stale) {
-    console.log("\n(Showing cached data — the backend was unreachable.)");
-  }
-} else {
-  console.log("The popover daemon returned an unexpected response.");
-}
-
-process.exit(0);
+#!/usr/bin/env node
+// Renders the /team menu.
+//
+// Invoked from the command's `!` injection, so its stdout becomes part of the prompt
+// Claude sees. Two consequences shape everything here:
+//   - always exit 0. A non-zero exit aborts the whole slash command.
+//   - always print something useful. If the daemon is down, say so in words the model
+//     can relay, rather than printing an empty section and letting it invent a reason.
+
+import { callerSessionId, request } from "./_ipc.mjs";
+
+// `fromSessionId` is what lets the daemon mark this agent's own line. It comes from the
+// session's environment, so a bare shell run of this script sends nothing and the roster
+// comes back unmarked.
+const reply = await request(
+  {
+    t: "roster",
+    id: "cli",
+    refresh: true,
+    ...(callerSessionId() ? { fromSessionId: callerSessionId() } : {}),
+    // Fallback for the window where the daemon has not yet resolved this session's repo —
+    // the same hint the MCP server sends. Without it an unplaceable caller falls through to
+    // pure recency across every session on the machine, so `/popover:team` run in one repo
+    // could print the roster for another, under a heading claiming it was this one.
+    cwd: process.cwd(),
+  },
+  { timeoutMs: 8000 },
+);
+
+if (!reply) {
+  console.log(
+    "The popover daemon is not running on this machine, so teammate agents are not visible.\n" +
+      "Start it with `popover daemon start`, or check `popover doctor`.",
+  );
+} else if (reply.t === "error") {
+  // The daemon distinguishes "no credentials" from "signed in but cannot connect", so
+  // relay its message rather than assuming the user has not logged in.
+  console.log(
+    reply.code === "not_authenticated"
+      ? reply.message
+      : `Could not load the team roster: ${reply.message}`,
+  );
+} else if (reply.t === "roster.ok") {
+  console.log(reply.rendered);
+  if (reply.stale) {
+    console.log("\n(Showing cached data — the backend was unreachable.)");
+  }
+} else {
+  console.log("The popover daemon returned an unexpected response.");
+}
+
+process.exit(0);

package/plugin/skills/popover/SKILL.md

@@ -1,168 +1,175 @@
----
-name: popover
-description: "Judgment for reaching a teammate's Claude Code agent *without being asked to* — when it is worth spending their tokens, and which of /popover:team, /popover:ask, /popover:tell and /popover:fork fits. Nothing to invoke by hand: use it when a question turns on what a colleague decided, ruled out, or is changing right now — why the code is the way it is when the repo does not say, whether work about to start is already in flight, or why something nobody touched is broken."
----
-
-# popover
-
-Your teammates are running their own Claude Code sessions in this repo. Each one has
-accumulated context you do not have: the alternatives they rejected, the constraint that
-forced an awkward shape, what they changed twenty minutes ago and have not pushed. popover
-lets you reach those agents.
-
-**This skill is not a command, and there is nothing here for a user to invoke.** The four
-commands are the things a user types:
-
-| | |
-| --- | --- |
-| `/popover:team` | who is working in this repo right now |
-| `/popover:ask` | one question to one agent, and you wait for the answer |
-| `/popover:tell` | a heads-up into a teammate's live session; nothing comes back |
-| `/popover:fork` | hand this whole conversation to a teammate |
-
-This file is the judgment around them: when reaching for one is worth it, which one fits, and
-what each one spends. It exists because the moment to use popover rarely announces itself. The
-user asks why something is the way it is, and the honest answer is that the repo does not
-record it — but a colleague's agent worked it out this morning. Nobody will type `/popover:ask`
-for you. Noticing is your job.
-
-## The three tools
-
-They arrive as deferred MCP tools, so you have their names but not their schemas. Load them
-before use:
-
-```
-ToolSearch("select:mcp__plugin_popover_popover__team_list,mcp__plugin_popover_popover__team_ask,mcp__plugin_popover_popover__team_tell")
-```
-
-Their own descriptions are detailed and authoritative on arguments and limits — read them
-once loaded rather than guessing. In short:
-
-- **`team_list`** — who is active in this repo, what they are doing, and each one's short
-  handle (`B1`). Takes nothing. Read-only and cheap.
-- **`team_ask`** — one question to one agent, and you wait for the answer. A read-only copy
-  of their session answers from its full context. Their live session is not interrupted and
-  cannot be changed by it. Takes up to ~90s by default.
-- **`team_tell`** — a one- or two-sentence heads-up delivered into a teammate's live session
-  before its next prompt. Nothing comes back, and their user is notified that you sent it.
-
-## When to reach for it on your own
-
-Check the roster and consider an ask when:
-
-- **The user asks *why*** — why a library was chosen, why a function is shaped oddly, why an
-  obvious approach was not taken — **and the repo does not answer it.** Read the code, the
-  comments, `git log`, `git blame`, and `CLAUDE.md` first. If the reasoning is not written
-  down anywhere, that is precisely the case popover was built for: it exists only in
-  somebody's session.
-- **You are about to start something that may already be underway** — a rename spanning many
-  files, a dependency bump, a refactor of a shared module. One `team_list` costs almost
-  nothing and can save the user an afternoon of conflicted work.
-- **You are blocked by something you did not break** — a migration that appears unapplied, a
-  failing build on untouched code, an endpoint that disagrees with its own types. Ask the
-  person whose agent is in that area before you debug their in-flight change as if it were a
-  bug.
-- **You are about to edit a file a teammate's agent is working in right now.** The roster
-  often says what each agent is doing. Prefer a `tell` here — it is a collision, not a
-  question.
-- **The user names a colleague.** "Did Bob get the webhook working?", "what is Sarah doing to
-  globals.css" — that is a direct signal, and you do not need to be asked twice.
-
-Say what you are doing and why before you ask, in a line. The user should never be surprised
-that you spent a teammate's tokens.
-
-## When not to
-
-- **When the repo can answer.** Reading is free and instant; an ask runs on someone else's
-  machine at their expense. Exhaust local evidence first, always.
-- **For curiosity or completeness.** Do not ask because a second opinion would be tidy. Ask
-  because you are stuck and they are not.
-- **More than one agent per question.** Never fan out across the roster to see who answers
-  best. Pick the one that fits; if none obviously does, show the user the roster instead.
-- **To hand off work.** A `tell` is information, not a directive — the receiving agent is
-  explicitly told to treat it that way — and an ask talks to a read-only copy that cannot act.
-  Neither one delegates. If the user wants a colleague to *do* something, say plainly that
-  popover does not do that, and let them message the human.
-- **For anything outside this repo.** Only agents in the same repository are visible or
-  reachable. An empty roster means nobody else is working *here* — not that the team is idle.
-  Phrase it that way, or you will imply something false about your user's colleagues.
-
-## The cost asymmetry, which governs consent
-
-Three tools, three different things being spent:
-
-| | Costs | Ask the user first? |
-| --- | --- | --- |
-| `team_list` | Nothing meaningful | No — just do it |
-| `team_ask` | The teammate's tokens and compute, on their machine. Interrupts nobody. | No, but say you are doing it |
-| `team_tell` | A colleague's **attention**. It lands in their live session and notifies them. | **Yes, every time** |
-
-`team_tell` is the only thing in popover that reaches a running agent. Treat it as something
-the user should have deliberately meant to do, and confirm before sending. It is also rate
-limited to 10 messages an hour to any one agent, which is a hint about its intended frequency.
-
-If it is genuinely ambiguous whether to ask or tell, ask. It interrupts nobody.
-
-## Writing an ask worth the money
-
-The answering agent has none of your conversation. It cannot see the file you are looking at
-or the error you just read. So make the question stand alone:
-
-- Expand every pronoun and vague reference. "that bug" → "the token refresh bug in the auth
-  service".
-- Name files by path, and say what you are trying to do, not only what you want to know.
-- Ask one well-formed question, not three exploratory ones. You get one round trip for the
-  price.
-
-A poor ask — *"why is it done this way?"* — comes back useless and you have spent a
-colleague's tokens to learn nothing. A good one — *"`apps/web/src/lib/auth-redirect.ts`
-derives the origin from the request Host header, with a comment saying
-`NEXT_PUBLIC_APP_URL` still points at the old Vercel domain. Is that variable going to be
-corrected, or is reading Host the intended long-term approach?"* — comes back with the
-reasoning, because that is knowledge about shared state that lives in a person's head rather
-than in the repo.
-
-Never invent a handle. Use only what `team_list` returned, and note that a handle from
-earlier in this conversation may have gone out of scope since. If the tool says it does not
-match, relay that instead of trying a different agent.
-
-## Forks are a different thing
-
-A fork hands over **this entire conversation**, frozen, and the recipient continues it in
-their own session. Nothing comes back. That includes the contents of every file read into the
-context, so it is a far larger disclosure than an ask.
-
-**Creating one is the user's alone.** It happens when they ask for it in as many words, never
-on their behalf — and "that would be useful" is not a yes.
-
-Saying that a fork would fit is a different act from making one, and it is worth doing once.
-The moment for a fork is one the user is usually too deep in the work to notice: they are going
-off shift, or about to re-explain an hour of debugging to a colleague by hand, or trading asks
-back and forth on what was never really one question. Say so plainly, say what the fork would
-include, and leave it there. If they pass, do not raise it again.
-
-When the user wants an *answer* rather than to hand over the whole conversation, an ask is the
-cheaper and more private thing. Offer that instead.
-
-## When it does not work
-
-The tools return errors as text; relay them rather than retrying with different arguments.
-
-- **"the popover daemon is not running"** — teammate agents are unreachable from this machine.
-  `popover daemon start`, or `popover doctor` to diagnose. Do not treat it as an empty roster.
-- **Empty roster** — print what the tool returned verbatim; it knows whether the answer is
-  "nobody is working here" or something else. Do not paraphrase it into "your team is idle".
-- **Handle does not match** — relay it. Do not guess at another agent.
-- **Ask times out** — say so. Their machine may be busy or the session may have ended. Do not
-  silently re-ask.
-
-## The user-facing commands
-
-The four commands carry the full flows for when the user drives this explicitly — how to
-present a roster, how to word an ask, how to take delivery of a fork. Do not restate their
-steps here or work around them: **when the user invokes a command, follow that command.** This
-skill is for the other case, where nobody invoked anything and you noticed the moment yourself.
-
-When you act on your own, prefer naming the command you are standing in for — "I'll run the
-equivalent of `/popover:ask B1`" — so the user learns the surface they can drive directly next
-time.
+---
+name: popover
+description: "Judgment for reaching a teammate's Claude Code agent *without being asked to* — when it is worth spending their tokens, and which of /popover:team, /popover:ask, /popover:tell and /popover:fork fits. Nothing to invoke by hand: use it when a question turns on what a colleague decided, ruled out, or is changing right now — why the code is the way it is when the repo does not say, whether work about to start is already in flight, or why something nobody touched is broken."
+---
+
+# popover
+
+Your teammates are running their own Claude Code sessions in this repo. Each one has
+accumulated context you do not have: the alternatives they rejected, the constraint that
+forced an awkward shape, what they changed twenty minutes ago and have not pushed. popover
+lets you reach those agents.
+
+**This skill is not a command, and there is nothing here for a user to invoke.** The five
+commands are the things a user types:
+
+| | |
+| --- | --- |
+| `/popover:team` | who is working in this repo right now |
+| `/popover:ask` | one question to one agent, and you wait for the answer |
+| `/popover:tell` | a heads-up into a teammate's live session; nothing comes back |
+| `/popover:fork` | hand this whole conversation to a teammate |
+| `/popover:vault` | publish this conversation to the team's archive, or ask one already there |
+
+This file is the judgment around them: when reaching for one is worth it, which one fits, and
+what each one spends. It exists because the moment to use popover rarely announces itself. The
+user asks why something is the way it is, and the honest answer is that the repo does not
+record it — but a colleague's agent worked it out this morning. Nobody will type `/popover:ask`
+for you. Noticing is your job.
+
+## The five tools
+
+They arrive as deferred MCP tools, so you have their names but not their schemas. Load them
+before use:
+
+```
+ToolSearch("select:mcp__plugin_popover_popover__team_list,mcp__plugin_popover_popover__team_ask,mcp__plugin_popover_popover__team_tell,mcp__plugin_popover_popover__vault_search,mcp__plugin_popover_popover__vault_ask")
+```
+
+Their own descriptions are detailed and authoritative on arguments and limits — read them
+once loaded rather than guessing. In short:
+
+- **`team_list`** — who is active in this repo, what they are doing, and each one's short
+  handle (`B1`). Takes nothing. Read-only and cheap.
+- **`team_ask`** — one question to one agent, and you wait for the answer. A read-only copy
+  of their session answers from its full context. Their live session is not interrupted and
+  cannot be changed by it. Takes up to ~90s by default.
+- **`team_tell`** — a one- or two-sentence heads-up delivered into a teammate's live session
+  before its next prompt. Nothing comes back, and their user is notified that you sent it.
+- **`vault_search`** — search the conversations your team has frozen and published. Free, no
+  model, nothing resumed. Not limited to this repo, and not limited to people who are working
+  right now. Always the first of the two.
+- **`vault_ask`** — one question to one vault, answered from its frozen context on *this*
+  machine at your user's expense. Roughly $0.50 and up to 90 seconds. Never call it on a
+  vault you have not seen in a search result.
+
+## When to reach for it on your own
+
+Check the roster and consider an ask when:
+
+- **The user asks *why*** — why a library was chosen, why a function is shaped oddly, why an
+  obvious approach was not taken — **and the repo does not answer it.** Read the code, the
+  comments, `git log`, `git blame`, and `CLAUDE.md` first. If the reasoning is not written
+  down anywhere, that is precisely the case popover was built for: it exists only in
+  somebody's session.
+- **You are about to start something that may already be underway** — a rename spanning many
+  files, a dependency bump, a refactor of a shared module. One `team_list` costs almost
+  nothing and can save the user an afternoon of conflicted work.
+- **You are blocked by something you did not break** — a migration that appears unapplied, a
+  failing build on untouched code, an endpoint that disagrees with its own types. Ask the
+  person whose agent is in that area before you debug their in-flight change as if it were a
+  bug.
+- **You are about to edit a file a teammate's agent is working in right now.** The roster
+  often says what each agent is doing. Prefer a `tell` here — it is a collision, not a
+  question.
+- **The user names a colleague.** "Did Bob get the webhook working?", "what is Sarah doing to
+  globals.css" — that is a direct signal, and you do not need to be asked twice.
+
+Say what you are doing and why before you ask, in a line. The user should never be surprised
+that you spent a teammate's tokens.
+
+## When not to
+
+- **When the repo can answer.** Reading is free and instant; an ask runs on someone else's
+  machine at their expense. Exhaust local evidence first, always.
+- **For curiosity or completeness.** Do not ask because a second opinion would be tidy. Ask
+  because you are stuck and they are not.
+- **More than one agent per question.** Never fan out across the roster to see who answers
+  best. Pick the one that fits; if none obviously does, show the user the roster instead.
+- **To hand off work.** A `tell` is information, not a directive — the receiving agent is
+  explicitly told to treat it that way — and an ask talks to a read-only copy that cannot act.
+  Neither one delegates. If the user wants a colleague to *do* something, say plainly that
+  popover does not do that, and let them message the human.
+- **For anything outside this repo.** Only agents in the same repository are visible or
+  reachable. An empty roster means nobody else is working *here* — not that the team is idle.
+  Phrase it that way, or you will imply something false about your user's colleagues.
+
+## The cost asymmetry, which governs consent
+
+Three tools, three different things being spent:
+
+| | Costs | Ask the user first? |
+| --- | --- | --- |
+| `team_list` | Nothing meaningful | No — just do it |
+| `team_ask` | The teammate's tokens and compute, on their machine. Interrupts nobody. | No, but say you are doing it |
+| `team_tell` | A colleague's **attention**. It lands in their live session and notifies them. | **Yes, every time** |
+
+`team_tell` is the only thing in popover that reaches a running agent. Treat it as something
+the user should have deliberately meant to do, and confirm before sending. It is also rate
+limited to 10 messages an hour to any one agent, which is a hint about its intended frequency.
+
+If it is genuinely ambiguous whether to ask or tell, ask. It interrupts nobody.
+
+## Writing an ask worth the money
+
+The answering agent has none of your conversation. It cannot see the file you are looking at
+or the error you just read. So make the question stand alone:
+
+- Expand every pronoun and vague reference. "that bug" → "the token refresh bug in the auth
+  service".
+- Name files by path, and say what you are trying to do, not only what you want to know.
+- Ask one well-formed question, not three exploratory ones. You get one round trip for the
+  price.
+
+A poor ask — *"why is it done this way?"* — comes back useless and you have spent a
+colleague's tokens to learn nothing. A good one — *"`apps/web/src/lib/auth-redirect.ts`
+derives the origin from the request Host header, with a comment saying
+`NEXT_PUBLIC_APP_URL` still points at the old Vercel domain. Is that variable going to be
+corrected, or is reading Host the intended long-term approach?"* — comes back with the
+reasoning, because that is knowledge about shared state that lives in a person's head rather
+than in the repo.
+
+Never invent a handle. Use only what `team_list` returned, and note that a handle from
+earlier in this conversation may have gone out of scope since. If the tool says it does not
+match, relay that instead of trying a different agent.
+
+## Forks are a different thing
+
+A fork hands over **this entire conversation**, frozen, and the recipient continues it in
+their own session. Nothing comes back. That includes the contents of every file read into the
+context, so it is a far larger disclosure than an ask.
+
+**Creating one is the user's alone.** It happens when they ask for it in as many words, never
+on their behalf — and "that would be useful" is not a yes.
+
+Saying that a fork would fit is a different act from making one, and it is worth doing once.
+The moment for a fork is one the user is usually too deep in the work to notice: they are going
+off shift, or about to re-explain an hour of debugging to a colleague by hand, or trading asks
+back and forth on what was never really one question. Say so plainly, say what the fork would
+include, and leave it there. If they pass, do not raise it again.
+
+When the user wants an *answer* rather than to hand over the whole conversation, an ask is the
+cheaper and more private thing. Offer that instead.
+
+## When it does not work
+
+The tools return errors as text; relay them rather than retrying with different arguments.
+
+- **"the popover daemon is not running"** — teammate agents are unreachable from this machine.
+  `popover daemon start`, or `popover doctor` to diagnose. Do not treat it as an empty roster.
+- **Empty roster** — print what the tool returned verbatim; it knows whether the answer is
+  "nobody is working here" or something else. Do not paraphrase it into "your team is idle".
+- **Handle does not match** — relay it. Do not guess at another agent.
+- **Ask times out** — say so. Their machine may be busy or the session may have ended. Do not
+  silently re-ask.
+
+## The user-facing commands
+
+The four commands carry the full flows for when the user drives this explicitly — how to
+present a roster, how to word an ask, how to take delivery of a fork. Do not restate their
+steps here or work around them: **when the user invokes a command, follow that command.** This
+skill is for the other case, where nobody invoked anything and you noticed the moment yourself.
+
+When you act on your own, prefer naming the command you are standing in for — "I'll run the
+equivalent of `/popover:ask B1`" — so the user learns the surface they can drive directly next
+time.