@composer-app/mcp 0.0.2 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@composer-app/mcp",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Composer MCP",
   "license": "MIT",
   "author": "Josh Philpott",

package/skill/commenting/SKILL.md

@@ -59,6 +59,98 @@ of your response from this:
 For suggestion craft (anchoring, ripples, multi-span), load
 **`composer:suggesting`**.
 
+## State and the ack-first flow
+
+Every agent-authored reply / comment / suggestion carries a lifecycle
+state the UI animates: **`thinking → working → replying → ready`**.
+The mention loop in `composer:monitor` opens this with an ack-first
+reply (`state: "thinking"`); from there you advance state with
+`composer_agent_status`:
+
+```
+composer_agent_status({
+  roomId,
+  threadId,
+  replyId?,        // identifies which reply you own; omit for thread-head
+  state,           // "thinking" | "working" | "replying" | "ready"
+  text?,           // rewrite the body (only meaningful on "ready")
+  note?,           // short human-readable progress line
+  kind?            // "comment" | "suggestion" — disambiguates head records
+})
+```
+
+- `thinking` — initial ack, set by the `composer_add_*` /
+  `composer_reply_*` call that posted it.
+- `working` — substantive work in flight (reading the doc, computing,
+  drafting). Set this whenever you expect a gap.
+- `replying` — about to write the final text. Optional, brief.
+- `ready` — done. Pass `text: "<final body>"` to rewrite the ack in
+  place atomically; the awareness heartbeat is pruned in the same call.
+
+**Silence is the failure mode.** If you're about to do something slow
+(fetch the full doc, compute a non-trivial diff, call another tool)
+transition to `working` first. The UI collapses transitions faster
+than ~400 ms, so don't worry about being too fast — worry about being
+silent for >2 s without a `working` flip. Use `note` to surface
+progress where it helps: `note: "Reading section 3…"`,
+`note: "Drafting suggestion…"`.
+
+**Rewrite-on-ready replaces a duplicate "done" reply.** When the
+substantive answer is a standalone artifact (a suggestion, a
+cross-span comment, a doc link), DO NOT post a second pointer reply.
+Rewrite the existing ack in place to a thin pointer and mark `ready`
+in the same call:
+
+```
+composer_agent_status({
+  roomId, threadId, replyId,
+  state: "ready",
+  text: "Posted a suggestion below."
+})
+```
+
+When the substantive answer IS the reply text, do the same — rewrite
+the ack to that text and set `ready` in the same call. Do not post a
+separate follow-up reply.
+
+### Worked example — ack-then-suggestion
+
+```
+// 1. Mention arrives via composer_next_event.
+//    { kind: "mention", threadId: "t_abc", invokerUserId: "u_jess",
+//      invokerName: "Jess", reason: "direct_mention", ... }
+
+// 2. Ack first.
+const { replyId } = composer_reply_comment({
+  roomId, threadId: "t_abc",
+  text: "@Jess — on it",
+  mentions: ["u_jess"],
+  state: "thinking",
+});
+
+// 3. Transition to working before any slow step.
+composer_agent_status({
+  roomId, threadId: "t_abc", replyId,
+  state: "working",
+  note: "Reading section 3…",
+});
+
+// 4. Post the substantive artifact.
+composer_add_suggestion({
+  roomId, fromThreadId: "t_abc", replacementText: "…",
+});
+
+// 5. Rewrite the ack and mark ready atomically.
+composer_agent_status({
+  roomId, threadId: "t_abc", replyId,
+  state: "ready",
+  text: "Posted a suggestion below.",
+});
+```
+
+No extra pointer reply. The rewrite + suggestion card together are
+the complete response.
+
 ## Empty acknowledgements: don't
 
 Never post a reply that's just "👍", "got it", or "thanks". If the

package/skill/monitor/SKILL.md

@@ -114,7 +114,9 @@ post in the doc.
   anchoredText?: "...",        // the doc text the thread is anchored to
   headingId?: "...",           // the section's headingId (use with write tools)
   headingText?: "...",
-  sectionMarkdown?: "..."      // full containing section as markdown
+  sectionMarkdown?: "...",     // full containing section as markdown
+  invokerUserId?: "...",       // userId of whoever triggered you (use in mentions[])
+  invokerName?: "..."          // their display name (use in @mention literal)
 }
 ```
 
@@ -123,6 +125,10 @@ Use `headingId` + `anchoredText` directly when calling
 `composer_get_section` is needed in the common case. Reach for
 `sectionMarkdown` to understand surrounding context before replying.
 
+Read `invokerUserId` and `invokerName` directly from the payload — do
+NOT try to reconstruct them from `threadText` or from an awareness
+lookup. They're the authoritative values the server resolved.
+
 **The event only carries the triggering message.** If the thread already
 has replies, call `composer_get_thread({ roomId, threadId })` before
 replying. The return has every reply with author and timestamp —
@@ -148,6 +154,41 @@ essential when the user tagged you mid-conversation.
       they're jotting down).
   When in doubt, reply — the user can always ignore you.
 
+## Ack first, then do the work
+
+Whenever you intend to act on a mention, post a brief ack reply FIRST —
+before reading the full doc, before drafting a suggestion. This is the
+"I heard you, I'm on it" signal; without it the user stares at a silent
+sidebar while you think.
+
+- Call `composer_reply_comment` (or `composer_reply_suggestion`) with
+  `state: "thinking"` and `mentions: [event.invokerUserId]`. For a
+  brand-new thread response use `composer_add_comment` /
+  `composer_add_suggestion` with the same `state` + `mentions` shape.
+- Body: `@<invokerName> — on it` or equivalent terse phrasing
+  (≤ 24 chars). "On it.", "Looking.", "Checking.". No preamble.
+- **Skip the ack** for empty thank-yous or conversational dead-ends you
+  wouldn't reply to at all (see `reason` gates above) — the ack is a
+  signal of intent to act, not a reflex.
+- **Skip the ack** when the mention fired as `active_thread` AND your
+  own prior reply on this thread was a concrete yes/no counter-proposal
+  AND the human's message is a yes-variant. The "I heard you" signal
+  was delivered in the prior ack; drop the suggestion directly via
+  `composer_add_suggestion({ fromThreadId: event.threadId })`. A second
+  ack here is noise.
+
+Once the ack is posted, drive its state with `composer_agent_status`
+as you work. On completion, rewrite the ack to its final form in the
+same call that transitions to `ready` — do not post a duplicate
+pointer reply. See `composer:commenting` for the state machine and the
+ack-then-suggestion flow.
+
+If you decide to skip a mention without replying, call
+`composer_done({ roomId, threadId })` so the thread-head "thinking…"
+heartbeat (auto-published when the mention was dequeued) gets cleared.
+The normal reply-with-`ready` path clears its own placeholder; this is
+only for the skip case.
+
 ## Where to go for richer rules
 
 - About to **reply on a thread** with text? Load **`composer:commenting`**