@popoverinstall/cli 0.9.1 → 0.10.1

package/plugin/skills/popover/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: popover
-description: "Judgment for reaching a teammate's Claude Code agent *without being asked to*, and for keeping this conversation where the team can ask it later — when it is worth spending their tokens, and which of /popover:team, /popover:ask, /popover:tell, /popover:fork and /popover:vault 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; or when this session has worked something out that the team will want and the repo will not record, which is the moment to vault it rather than let it be deleted."
+description: "Judgment for reaching a teammate's Claude Code agent *without being asked to*, and for keeping this conversation where the team can ask it later — when it is worth spending their tokens, and which of /popover:team, /popover:message, /popover:fork and /popover:vault fits. Nothing to invoke by hand. **Standing rule: when you finish a task, vault this conversation before you report completion.** That is the moment and it does not come back — you have just built the thing, your grasp of it is as good as it is ever going to get, the user is about to move on to something else, and a conversation nobody vaults is deleted when the session ends. Vault a decision and the reasons behind it, an approach tried and rejected, an investigation that ended in an answer. Do not vault a session that only did what its diff says, one that concluded nothing, or one carrying secrets or a customer's data — an index full of everything is one nobody trusts, and fails the same way as vaulting nothing. Read this skill too 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
@@ -10,30 +10,38 @@ accumulated context you do not have: the alternatives they rejected, the constra
 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:
+**This skill is not a command, and there is nothing here for a user to invoke.** The 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:message` | say something to one agent, and carry on the thread they reply on |
 | `/popover:fork` | hand this whole conversation to a teammate |
 | `/popover:vault` | publish this conversation to the team's archive, or ask one already there |
+| `/popover:ask` | deprecated — `/popover:message` does this |
+| `/popover:tell` | deprecated — `/popover:message` does this |
+
+The last two still work and are still carried out when a user types them; they are deprecated
+because the difference between them was never a user's to decide. Whether a message is
+answered by a live session or by a read-only copy turns on what that agent is doing at this
+second, which the daemon knows and the sender does not — so the system picks, and no argument
+lets a caller override it (`docs/messages.md` §1).
 
 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.
+record it — but a colleague's agent worked it out this morning. Nobody will type
+`/popover:message` for you. Noticing is your job.
 
-## The six tools
+## The eight tools
 
 They arrive as deferred MCP tools, so you have their names but not their schemas. Load them
-before use:
+before use — a name that is missing from this line is a tool you cannot call, so it lists
+every one that exists, deprecated ones included:
 
 ```
-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,mcp__plugin_popover_popover__vault_create")
+ToolSearch("select:mcp__plugin_popover_popover__team_list,mcp__plugin_popover_popover__team_message,mcp__plugin_popover_popover__team_ask,mcp__plugin_popover_popover__team_tell,mcp__plugin_popover_popover__vault_search,mcp__plugin_popover_popover__vault_ask,mcp__plugin_popover_popover__vault_create,mcp__plugin_popover_popover__team_receipts")
 ```
 
 Their own descriptions are detailed and authoritative on arguments and limits — read them
@@ -41,11 +49,26 @@ 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.
+- **`team_message`** — the one verb for reaching an agent. You give it a target and a body;
+  it decides on its own whether that lands in the teammate's live session or is answered by
+  a read-only copy of it, and tells you which afterwards. An answer may come back on the
+  call, or later, or not at all — none of the three means it failed. Replies run on a thread
+  in both directions, so pass the `thread_id` it returned to carry on rather than opening
+  something new.
+- **`team_ask`** — deprecated; `team_message` covers it. Still works, unchanged: one question
+  to one agent, answered by a read-only copy of their session from its full context, ~90s.
+- **`team_tell`** — deprecated; `team_message` covers it. Still works, unchanged: a short
+  heads-up into a teammate's live session, with nothing coming back.
+- **`team_receipts`** — everything that came in for *this* session while nobody was watching.
+  Read-only and cheap, and it now carries two kinds, so read the `kind` on each. `asks` is a
+  finished exchange: a copy of this conversation answered and whoever asked already has the
+  answer, so nobody is waiting on you. `thread` is a teammate's reply on an open thread, and
+  that one may be a live turn with a person waiting — answer it with `team_message` on the
+  same `thread_id`, which needs no fresh consent because the thread is already open. You
+  learn something is waiting from a line your own daemon prints, which carries a count and a
+  kind and never any of the text; this is how you read the text itself. Worth calling when
+  you finish a task — being asked about something is the clearest evidence the team wants it,
+  which makes it the best reason to vault.
 - **`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.
@@ -53,14 +76,14 @@ once loaded rather than guessing. In short:
   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.
 - **`vault_create`** — publish *this* conversation into the archive the other two read.
-  The only one of the six that writes something permanent: the whole conversation goes to
+  The only one here that writes something permanent: the whole conversation goes to
   everyone on the team, it does not expire, and it cannot be edited afterwards. You may call
   it on your own judgement — see *Vaults are a different thing again* below — but say plainly
   that a vault is **readable by the popover service**, which a fork is not.
 
 ## When to reach for it on your own
 
-Check the roster and consider an ask when:
+Check the roster and consider messaging someone 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
@@ -75,74 +98,116 @@ Check the roster and consider an ask when:
   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.
+  often says what each agent is doing. This is a collision rather than a question, and it is
+  still one `team_message` — you no longer have to decide that it is a "tell", and you never
+  had the information to decide it well.
 - **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.
+Say what you are doing and why before you send, in a line. The user should never be surprised
+that you spent a teammate's tokens or their attention.
 
 ## 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.
+- **When the repo can answer.** Reading is free and instant; a message spends either someone
+  else's machine or someone else's attention. Exhaust local evidence first, always.
+- **For curiosity or completeness.** Do not reach for someone because a second opinion would
+  be tidy. Message them 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.
+- **To hand off work.** A message is information, not a directive: the receiving agent is
+  explicitly told to treat it that way, and the copy that may answer it has no tools at all.
+  Threads do not change this, and being able to reply is not being able to delegate. 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:
+| `team_message`, **opening** a thread | A teammate's tokens or their attention, and you do not learn which until after | **Yes, once** |
+| `team_message`, **continuing** one | The same, on a channel their human already agreed to | No — say what you sent |
+
+**Consent is per thread, not per message** (`docs/messages.md` §2). Opening a channel into a
+colleague's work is the deliberate act worth your user's say-so; each sentence inside a
+conversation they already agreed to is not, and humans do not re-consent to a conversation
+per utterance. So confirm at the open, and then stop asking. Re-confirming every reply is the
+old habit wearing a thread as a hat, and it makes the surface unusable for the exchange it
+exists to support.
+
+There is no longer a numeric cap, and its removal was the point rather than an oversight. A
+count is a proxy for consent: it guesses a number on the recipient's behalf and then severs,
+mid-sentence and at an arbitrary total, a conversation their human already agreed to. What
+replaces it is a human with a kill switch — either party can close a thread with `popover
+thread close <id>`, which is landing alongside this. Nothing else throttles you, so the bar
+you carry at the open *is* the protection. If the tool refuses a message, relay the refusal
+rather than retrying it.
+
+### The number you can see is the wrong half of the bill
+
+`team_message` may report a cost. Read it, and read what it leaves out, because the omission
+runs the opposite way to intuition (§8):
+
+> The transport we can bill looks expensive, and the one we cannot bill looks free. Routing
+> prefers the unbillable one exactly when the target is busiest.
+
+A read-only copy runs headless on the recipient's machine and reports a dollar figure — and
+it is chosen when they are **idle**, which is the cheapest moment to interrupt anybody. Live
+injection reports nothing, because it spends the teammate's own session inside their own
+Claude usage where popover cannot see it — and it is chosen when they are **working**, which
+is the most disruptive moment there is. So a thread showing a low number may have been the
+expensive one. Never tell a user a thread was cheap for the person on the other end; say
+what the figure covers, which is the copies and not the interruptions.
+
+## Writing a message worth the money
+
+First, the thing most often got wrong: an agent that believes it has one shot writes a
+paragraph it did not need. You are not spending your only round trip, and that is now
+literally true rather than encouragement — the reply is repliable. Send the smallest thing
+that unblocks you and follow up if what comes back opens something. Two exchanges beat one
+padded one, and they beat one padded one that timed out.
+
+No length is prescribed, in either direction, and none will be. The verbosity this replaced
+was compliance, not bad judgement: doctrine said you got one round trip, so agents wrote as
+if they did. A word count would be the same instruction in cruder form, making a short
+message pad out to look thorough and a long one stop mid-reasoning. Write at whatever length
+the thing takes; six words is a good message when six words are the message.
+
+The first message on a thread has none of your conversation behind it. The recipient cannot
+see the file you are looking at or the error you just read. So make it 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.
+- One question. Not three, and not one question with three others hanging off it.
 
 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.
+colleague's tokens to learn nothing. A good one is barely longer: *"Is `NEXT_PUBLIC_APP_URL`
+going to be corrected, or is reading the Host header in `apps/web/src/lib/auth-redirect.ts`
+the intended long-term approach?"* Two lines, self-contained, and it comes back with the
+reasoning — because that is knowledge about shared state which lives in a person's head
+rather than in the repo.
+
+Later messages on the same thread are a different matter: they arrive with the thread's own
+history behind them, so a reply can be as short as a reply naturally is. Pass the `thread_id`
+the tool returned. Restating context the thread already carries is the padding habit finding
+somewhere new to live, and it is also expensive — the thread is replayed to whatever answers
+it, under a budget that drops the oldest turns first.
+
+Never invent a handle, and never invent a thread id. Use only what `team_list` returned and
+what a previous call handed back; a handle from earlier in this conversation may have gone
+out of scope since, and an id you did not receive is not a thread you are on. 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.
+context, so it is a far larger disclosure than a message.
 
 **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.
@@ -153,8 +218,8 @@ off shift, or about to re-explain an hour of debugging to a colleague by hand, o
 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 the user wants an *answer* rather than to hand over the whole conversation, a message is
+the cheaper and more private thing. Offer that instead.
 
 ## Vaults are a different thing again
 
@@ -165,9 +230,19 @@ the person asking pays rather than the person who wrote it.
 **Unlike a fork, creating one is yours to decide.** Not to offer and wait on — to decide. The
 rule differs from the fork rule deliberately: a fork discloses one conversation to one named
 individual, while a vault goes to a team that already shares the repository and the work, so
-the disclosure is smaller and the cost of missing the moment is higher. The moment for a vault
-is one the user is usually too deep in the work to notice, and a conversation nobody vaults is
-deleted when the session ends.
+the disclosure is smaller and the cost of missing the moment is higher.
+
+And the moment is not vague. It is **the completion of a task**: you have just finished
+building something, your grasp of the work is as good as it is ever going to get, and the user
+is about to move on to something else. So the default runs the other way from every other
+proactive act in popover — when you finish, vault before you report completion, rather than
+finishing and waiting to see whether it occurs to anybody. `docs/vaults.md` §3 fixes that
+as the trigger and says why it beat the obvious alternative of vaulting on compaction:
+compaction fires on the longest sessions, and a session is usually long because it wandered
+rather than because it concluded anything worth asking later.
+
+Which leaves the exception carrying all the weight, so hold it honestly rather than as a
+formality. It is stated in full at the end of this section.
 
 It is still a real disclosure, and two things must be said plainly when you make one:
 
@@ -178,8 +253,12 @@ It is still a real disclosure, and two things must be said plainly when you make
 
 Vault a conversation that worked something out the team will want and the repo will not
 record — a decision and its reasons, an approach tried and rejected, an investigation into why
-something is the way it is. Do not vault routine work: an index full of everything is one
-nobody trusts, which fails in the same way as vaulting nothing.
+something is the way it is. Do not vault a session that only did what its diff says, one that
+concluded nothing, or one carrying secrets or a customer's data. Both failure modes here are
+real and you should be watching for both in yourself: vaulting everything produces an index
+nobody trusts, and vaulting nothing is the older ask-first habit wearing a different hat.
+Reversing the default is what makes the archive exist at all; the exception is what keeps it
+worth asking.
 
 ## When it does not work
 
@@ -190,16 +269,26 @@ The tools return errors as text; relay them rather than retrying with different
 - **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.
+- **It times out** — say so. Their machine may be busy. A timeout does not end a thread and
+  does not mean the target is gone, so do not silently re-send and do not report the thread
+  as dead.
+- **The target is offline** — their session has ended, and this is also what a thread returns
+  once its peer has gone and something is still undelivered. Say it could not be sent now.
+  **Do not say the thread is closed**, because it is not: it goes live again by itself when
+  that session resumes (§7.1). Refusing is deliberate — the alternative is a pile of messages
+  landing at once on a person returning from lunch.
+- **The thread is closed** — a human used the kill switch. Closing bars new sends; it does
+  not retract anything already filed, so a reply produced before the close still reaches the
+  other side when they resume. Do not describe a close as having undone something, and do not
+  reopen by dropping the `thread_id` — that opens a new thread, which needs consent again.
 
 ## The user-facing commands
 
-The five 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
+The commands carry the full flows for when the user drives this explicitly — how to present
+a roster, how to word a message, 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.
+equivalent of `/popover:message B1`" — so the user learns the surface they can drive
+directly next time.