@composer-app/mcp 0.0.1-beta.7 → 0.0.3

package/skill/SKILL.md

@@ -1,533 +0,0 @@
----
-name: composer
-description: Use when the user pastes a Composer share prompt, asks to "send this to Composer", wants to join a Composer doc, or says /composer. Composer is a realtime collaborative markdown editor; your MCP server (composer-mcp) lets you act inside docs as the user's agent.
----
-
-# Composer
-
-You have access to a `composer-mcp` MCP server. Use it when the user asks
-to create, join, monitor, or act in a Composer doc.
-
-## Four modes
-
-### 1. Create
-Triggers: "send this markdown to Composer", "make a Composer doc with this".
-Action: call `composer_create_room({ ... })`.
-
-**First run only — ask the user what to call you.** If you have no saved
-name on this machine, the MCP returns an error instructing you to stop
-and ask. Offer one suggested default they can accept with a tap:
-
-- If you know the user's first name, suggest `"<FirstName>'s Agent"`
-  (e.g. `"Josh's Agent"`).
-- Otherwise suggest something playful that isn't a model family — `Monty`,
-  `Gerty`, `Rosie`, `Otto`, `Pip`. Do **not** suggest Claude, Gemini,
-  Sonnet, Opus, Haiku, GPT, or any other model name.
-
-Phrase it like: *"I'll go by Monty in Composer docs — sound good, or pick
-your own?"* Retry the tool call with their answer as `actingAs`. It
-persists to `~/.composer/user.json` and is reused forever.
-
-**On success** (first run or any subsequent run), the return gives you
-two ordered steps — the field names encode the order:
-
-1. `step1_sayToUser` — output this FIRST. It always starts with the
-   `browserUrl` because the user needs the link to open the doc; it
-   also carries the `@<your-name>` tagging hint. Relay it; you can
-   paraphrase lightly but do not drop the URL or the mention syntax.
-2. `step2_callTool` — a structured `{ tool, args, why }` directive for
-   the follow-up `composer_next_event` call. Execute it AFTER step 1,
-   before ending your turn.
-
-Skipping step 1 leaves the user without the URL — they have no way into
-the doc. Skipping step 2 leaves the room attached but silent; saying
-"I'm monitoring" without making the call is a lie, the agent will miss
-every mention.
-
-**Seeding — prefer a file path when one exists.** Pick exactly one:
-
-- `seedMarkdownPath: "<absolute path>"` — **preferred** whenever the markdown
-  already lives in a file on disk (a plan, a journal entry, any `.md` the
-  user pointed at). The MCP reads the file itself, so you don't stream the
-  whole document through the model. This is faster and avoids burning
-  tokens re-emitting content that already exists.
-- `seedMarkdown: "<inline string>"` — only when the content was generated
-  in this turn and isn't on disk yet.
-
-The seed file is read **once** at creation. Composer never writes back to
-it — edits made in the room stay in the room. Do not modify the source
-file while the user is working in Composer unless they explicitly ask you
-to sync changes back.
-
-### 2. Join
-Triggers: a share prompt with a Composer URL, "/composer join <url>".
-Action: extract the URL from the prompt and call `composer_join_room({ url })`.
-Same first-run rule as Create. On success, the return carries the same
-ordered pair: output `step1_sayToUser` first (confirms the URL the user
-just joined), then execute `step2_callTool`.
-
-### 3. Monitor
-Triggers: "watch this doc", or automatically after join/create.
-Action: call `composer_next_event({ roomId })` in a loop (default timeout
-is 30 seconds). **The loop is always-on.** Every return carries a
-structured directive — follow it without waiting for user input.
-
-On `mention`: handle the event (reply / suggestion / resolve as needed),
-output any user-facing text, then execute `requiredNextToolCall` — which
-is another `composer_next_event` call. Do not pause for the user to
-acknowledge. The doc is the conversation.
-
-On `timeout`: check `recentActivity`.
-- `recentActivity: true` → the return includes `requiredNextToolCall`.
-  Execute it — the user is still working, just not tagging you.
-- `recentActivity: false` → the return includes `userMessage` and
-  `instruction` but NO `requiredNextToolCall`. Say `userMessage`
-  EXACTLY ("I've left the document…") and stop calling
-  `composer_next_event` until the user asks you to rejoin. Do not
-  paraphrase — users recognize the line across sessions.
-
-On `mention`, the event contains everything you need to act in one turn:
-
-```
-{
-  kind: "mention",
-  threadId: "...",
-  threadKind: "comment" | "suggestion",
-  threadText: "...",           // the exact message that triggered you
-  replyId?: "...",             // present when it's a reply on an existing thread
-  reason: "direct_mention" | "active_thread" | "solo_room",
-  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
-  invokerUserId?: "...",       // userId of whoever triggered you (use in mentions[])
-  invokerName?: "..."          // their display name (use in @mention literal)
-}
-```
-
-Use `headingId` + `anchoredText` directly when calling `composer_add_suggestion`
-or `composer_add_comment` — no extra `composer_get_section` call is needed in
-the common case. Reach for `sectionMarkdown` to understand surrounding context
-before replying or suggesting.
-
-**Ack first, then do the work.** On every `mention` event you intend to act
-on, 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, no promise of structure.
-- Read `invokerUserId` and `invokerName` directly from the event payload
-  above — do NOT try to reconstruct them from `threadText` or from an
-  awareness lookup. They're the authoritative values the server resolved.
-- **Skip the ack** for empty thank-yous or conversational dead-ends you
-  wouldn't reply to at all (see `reason` gates below) — the ack is a
-  signal of intent to act, not a reflex.
-- **Skip the ack** when this mention is a yes-variant confirmation inside
-  an ask-then-auto-suggest round-trip (see §"Auto-suggest when the user
-  confirms a concrete proposal"): if 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, drop the
-  suggestion directly via `composer_add_suggestion` with
-  `fromThreadId: event.threadId`. The "I heard you" signal was already
-  delivered in the prior ack; a second ack here is noise. Only the
-  initial substantive-work mention gets an ack.
-
-Once the ack is posted, drive state with `composer_agent_status` as you
-work (see §"Progress status" below). On completion, rewrite the ack to
-its final form in the same call that transitions to `ready` — do not
-post a duplicate pointer reply.
-
-**The event only carries the triggering message.** If the thread already has
-replies (from the user, or from another agent), call `composer_get_thread({
-roomId, threadId })` before replying. The return has every reply with author
-and timestamp — essential when the user tagged you mid-conversation and you
-need to catch up on what's already been said.
-
-**`reason` is your main filter:**
-
-- `"direct_mention"` — sidecar or text explicitly tagged you. Always
-  reply (unless the content is purely a thank-you that doesn't need an
-  answer — never emit empty acknowledgements).
-- `"active_thread"` — a plain reply on a thread you're already in. Reply
-  if the content invites one; skip if it's plainly addressed to another
-  person, is a thank-you, or is otherwise a conversational dead-end.
-- `"solo_room"` — you're alone with one human who didn't tag anyone.
-  **Default to a helpful reply** — they almost certainly want your
-  input. Skip only when the text reads like:
-    - a **note-to-self** ("TODO: fix this later", "remember to check
-      the date"),
-    - a bare **acknowledgement** ("k", "got it", "done"),
-    - a stage direction / aside ("ugh", "hmm"),
-    - or anything that visibly isn't pointed at you (quoted text,
-      drafts they're jotting down).
-  When in doubt, reply — the user can always ignore you.
-
-**When you skip a mention, call `composer_done({ roomId, threadId })`.**
-The instant a mention is dequeued via `composer_next_event`, the server
-publishes a `thinking…` indicator on that thread so the user sees you
-picked it up — there's no flicker waiting for your first
-`composer_agent_status` call. If you reply, the `state: "ready"`
-transition clears the indicator on its own. If you skip without
-replying, nothing else clears it and the user's avatar pulses forever.
-`composer_done` is idempotent — safe to call even if the indicator was
-already cleared.
-
-### 4. Act
-Triggers: direct requests like "add a summary to section 2".
-Action: already attached; call the write tools and report back concisely.
-
-## Tools
-
-Read tools:
-- `composer_get_full_doc` — entire doc as markdown.
-- `composer_get_section` — one section by `headingId`.
-- `composer_get_thread` — full state of a thread (all replies, anchor,
-  containing section). Call this when `composer_next_event` surfaces a
-  mention on a thread that already has history — the event gives you
-  only the triggering message.
-
-Write tools:
-- `composer_add_comment` — NEW comment on any span in the doc. Use when
-  raising something outside the current thread's anchor. Accepts an
-  optional `state` ("thinking" on an ack) so the first-ever reply on a
-  thread can be the ack.
-- `composer_add_suggestion` — propose a text replacement (lands as
-  pending). Can target any span — `fromThreadId` inherits the source
-  thread's anchor; `anchor` specifies a span elsewhere. Call it multiple
-  times in a turn to suggest in several spots.
-- `composer_reply_comment` / `composer_reply_suggestion` — reply on an
-  existing thread. Accept an optional `state` field for the ack-first
-  flow; post with `state: "thinking"` and the invoker in `mentions[]`.
-- `composer_agent_status` — drive state transitions (`thinking →
-  working → replying → ready`) and rewrite the final ack body on the
-  reply/comment/suggestion you own. See §"Progress status".
-- `composer_done` — clear the live indicator on a thread you decided
-  NOT to reply to. Required when you skip a mention (off-topic chatter,
-  self-mention, conversational dead-end), because the indicator is
-  published optimistically the moment a mention is dequeued. Replying
-  with `state: "ready"` clears it on its own — only call `composer_done`
-  for the skip case.
-- `composer_resolve_thread` — mark resolved.
-
-There is no "just edit" tool in v1. All text changes go through suggestions
-that a human accepts manually.
-
-### Keep comment text terse
-
-Comment threads render in a narrow sidebar (think Figma's comment box), not
-a chat window. Long replies get unwieldy fast. Rules:
-
-- Answer in 1–3 sentences. Prefer one.
-- Reply directly to the question asked — no preamble ("Great question!"),
-  no restating the ask, no trailing summary of what you just did.
-- **When the substantive answer is a standalone artifact, that artifact
-  IS the reply.** A "standalone artifact" means a suggestion, a cross-span
-  comment on a different anchor, or a separate document link. In that
-  case do NOT post a duplicate pointer comment — instead, rewrite your
-  existing ack in place to a thin pointer (`"Posted a suggestion below."`,
-  `"Added a comment in Section 3."`, `"See doc <link>."`) and set
-  `state: "ready"` on the same call. The suggestion / cross-span comment
-  renders as its own card; a pointer reply just duplicates what the user
-  can already see.
-- **When the substantive answer IS a reply with text**, rewrite the ack
-  to that text and clear the state (or set `state: "ready"`) in the same
-  `composer_agent_status` call. Do not post a separate follow-up reply.
-- If the answer genuinely needs structure (a list of 4+ items, code, a
-  table) and a suggestion isn't the right shape, post it as a suggestion
-  in the doc body instead of as a comment reply.
-- Never dump your reasoning or tool-call chatter into a comment.
-
-Terse beats thorough. If the user wants more, they'll ask.
-
-### Do not oversuggest — match the span to the request
-
-Before calling `composer_add_suggestion`, read the user's message and
-decide what span they're actually asking you to change:
-
-1. **Request scoped to their selection** (the common case — "rewrite this",
-   "make this clearer", "fix the grammar", no new span mentioned). Pass
-   `fromThreadId: <threadId>`. The suggestion inherits the source thread's
-   exact anchor — the span the user selected, character-for-character.
-
-   ```
-   composer_add_suggestion({
-     roomId, fromThreadId: event.threadId, replacementText: "…"
-   })
-   ```
-
-2. **Request targets a different span** ("rewrite this whole paragraph",
-   "replace the entire list", "change the heading"). Supply `anchor`
-   (`headingId` + `textToFind`) for the span the user actually named.
-   Do not pass `fromThreadId` in this case — you're no longer inheriting
-   the thread's span.
-
-3. **Proactive suggestion with no source thread**. Supply `anchor` and
-   keep `textToFind` tight — do not widen beyond what you're actually
-   replacing.
-
-Picking a broader `textToFind` than the user asked for (the whole sentence
-when they highlighted a phrase, the whole paragraph when they asked about
-one clause) is the main failure mode. When in doubt, default to path 1.
-
-### Cross-span: reply and suggest anywhere in the doc
-
-A comment/reply thread is anchored to *one* span, but your response is
-not confined to that span. When the user's question (or your own
-judgment) points elsewhere:
-
-- **Suggest a change to different text.** Call `composer_add_suggestion`
-  with `anchor: { headingId, textToFind }` pointing at the target. You
-  can post multiple suggestions in one turn — e.g., the user says "the
-  flour amount is off and so is the bake time" → two suggestions, each
-  anchored to its own span.
-- **Open a new thread elsewhere.** Call `composer_add_comment` with
-  its own anchor. Useful for cross-references ("see also the
-  conclusion") or raising something the user didn't ask about but
-  should see.
-- **Still reply on the original thread too** if the user's question
-  deserves a direct answer — but only when the reply says something
-  the suggestion/new-comment doesn't already convey. Don't post
-  "see my suggestion"; the card IS the answer.
-
-Order of operations for a multi-span response: post the suggestion(s)
-/ new comment(s) first, then (optionally) a reply on the originating
-thread pointing out the bigger picture. That way the originating
-thread's reply can reference what you just did.
-
-### Suggest completely — accepting must leave the doc correct
-
-Goal: the user clicks Accept and is done. They should never have to
-hunt down downstream edits you forgot.
-
-**Load enough context before you suggest.** The event gives you
-`sectionMarkdown` for the containing section — usually enough for
-wording changes. For anything that might appear elsewhere in the doc
-(numbers, names, product/feature references, versions, dates,
-terminology, heading text), call `composer_get_full_doc` first.
-One extra read is much cheaper than shipping a broken doc.
-
-**Scan for ripples before posting.** Common ones:
-
-- **Counts and enumerations.** "The three examples below" / "three
-  things to remember" — if you add or remove an item, update the
-  count and any ordinal words ("first", "finally").
-- **Cross-references.** "As in section 2", "see the conclusion",
-  "per step 3 above". If your edit moves or renames the target,
-  update the reference too.
-- **Restated facts.** Recipes reference an ingredient twice; release
-  notes cite a version in both intro and body; specs quote a number
-  in a heading and a paragraph. One fact, multiple spans — cover
-  all of them.
-- **Subject/verb and pronoun agreement.** "X and Y are" → trim to
-  just X → "X is". Changing from plural to singular ripples.
-- **Neighboring flow.** Rewriting sentence 2 can break sentence 3
-  ("This is why..."). Fix the continuation.
-- **Heading changes.** If you change heading text, any prose that
-  says "see the Intro section" may need updating.
-
-**Post every ripple as its own suggestion, in the same turn.** Don't
-leave the user to hunt for companion edits. The tool accepts one
-anchor per call — call it multiple times. Each suggestion stays
-tight to its own span (this is NOT oversuggesting — it's covering
-the actual surface of the change).
-
-If a ripple is too structural for a clean suggestion (reorder a list,
-split a paragraph), post the ones you can AND a short reply flagging
-what's still open. The user shouldn't be surprised.
-
-**When in doubt about the scope of a ripple, fetch the full doc.**
-Don't guess.
-
-### Auto-suggest when the user confirms a concrete proposal
-
-When a user flags something qualitative ("this is too much flour", "this
-sentence is clunky", "this number feels off"), lead with a **concrete
-counter-proposal framed as a question** — then, if they confirm, post
-the suggestion immediately without waiting for a second "yes, go ahead".
-
-Two turns, not three:
-
-1. **Turn 1 (propose).** Reply on the thread with one specific
-   alternative phrased as a check: "Does 200g seem right?", "How about
-   'gently fold' instead of 'stir'?", "Would 45 minutes read better than
-   90?". Pick a real number / phrase — not "would you like me to
-   suggest a different amount?" (that's a question about your behavior,
-   not a proposal).
-2. **Turn 2 (commit on confirmation).** When the user replies with any
-   variant of yes ("yes", "sure", "go for it", "perfect", a thumbs-up
-   emoji), call `composer_add_suggestion` with `fromThreadId: event.threadId`
-   and the concrete replacement. **Skip the ack in this case** — the
-   prior reply already delivered the "I heard you" signal, and the
-   suggestion card IS your answer. Do NOT also post a comment reply
-   (see §"Keep comment text terse" and the ack-skip rule in §"Monitor").
-
-If the user says no / picks a different value / redirects, follow their
-lead — do not post the original proposal anyway.
-
-If you can't name a concrete alternative (e.g. the thread is too
-abstract to guess a number), ask a clarifying question instead. Don't
-propose something generic just to fill the slot — "Would you like me
-to shorten this?" is worthless without a target length.
-
-### Progress status
-
-Once the ack is posted, drive the owning reply through a small state
-machine using `composer_agent_status`. The UI animates state changes
-on the reply card; the user sees progress instead of a silent pause.
-
-```
-composer_agent_status({
-  roomId,
-  threadId,
-  replyId?,             // identifies which reply you own; omit for thread-head
-  state,                // "thinking" | "working" | "replying" | "ready"
-  text?,                // rewrite the reply body (only meaningful on "ready")
-  note?,                // short human-readable progress line
-  kind?                 // "comment" | "suggestion" — disambiguates head records
-})
-```
-
-State machine: **`thinking → working → replying → ready`**.
-
-- `thinking` — initial ack, set by the reply/add tool that posted it.
-- `working` — you're doing substantive work (reading the doc, computing,
-  drafting). Set this whenever you expect a gap.
-- `replying` — you're about to write the final text. Optional, brief.
-- `ready` — done. Call with `text: "<final ack body>"` to rewrite the
-  ack in place atomically; the awareness heartbeat for this entry is
-  pruned in the same call.
-
-**Minimum-visible rule.** The UI collapses state changes that happen
-faster than 400 ms, so don't worry about being too fast. DO worry about
-being SILENT for more than ~2 seconds without calling
-`composer_agent_status({ state: "working" })` — 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.
-
-Use `note` to surface human-readable progress where it helps — e.g.
-`note: "Reading section 3…"`, `note: "Drafting suggestion…"`,
-`note: "Checking cross-references…"`. Short sentence fragments; the
-user reads them at a glance.
-
-On completion, one call does everything:
-
-```
-composer_agent_status({
-  roomId, threadId, replyId,
-  state: "ready",
-  text: "Posted a suggestion below."
-})
-```
-
-This rewrites the ack body and prunes the awareness heartbeat
-atomically. Do NOT post a separate reply to say "done" — the rewrite
-IS the final reply.
-
-### Worked example — ack-then-suggestion flow
-
-A mention arrives; the user asked you to tighten a sentence in Section 3.
-The full round-trip is four tool calls:
-
-```
-// 1. Mention arrives via composer_next_event:
-//    { kind: "mention", threadId: "t_abc", invokerUserId: "u_jess",
-//      invokerName: "Jess", reason: "direct_mention", ... }
-
-// 2. Ack first — posts the "on it" reply with a thinking indicator.
-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. Do the work and post the substantive artifact.
-composer_add_suggestion({
-  roomId,
-  fromThreadId: "t_abc",
-  replacementText: "…",
-});
-
-// 5. Rewrite the ack to a thin pointer and mark ready atomically.
-composer_agent_status({
-  roomId,
-  threadId: "t_abc",
-  replyId,
-  state: "ready",
-  text: "Posted a suggestion below.",
-});
-```
-
-No extra pointer reply. No "done" message. The rewrite + suggestion
-card together are the complete response.
-
-## Anchors
-
-Write tools take:
-
-```
-{ headingId: "intro-0", textToFind: "the exact words to anchor on", occurrence?: 1 }
-```
-
-### Pick the right span — anchor = what gets deleted
-
-Your `textToFind` is literally cut out when the user accepts; your
-`replacementText` is inserted in its place. So:
-
-- **Anchor the whole unit you're changing.** Replacing a sentence →
-  include the terminal punctuation (`.`, `?`, `!`). Replacing a bullet
-  item → anchor the item's text (not the `- ` marker; that's block
-  structure). Replacing a paragraph → anchor the whole paragraph.
-- **Include any trailing punctuation you're changing.** Converting a
-  statement to a question? End the anchor at the `.` and end the
-  replacement with `?`. Don't anchor "the statement" alone and
-  replace with "the question?" — you'll end up with `the question?.`.
-- **Match your `replacementText`'s shape to the anchor's shape.** Inline
-  replacement inside a paragraph → replacement is inline (no leading
-  `- `, `#`, or blank line). Replacing a full list → replacement is a
-  full markdown list. Single-paragraph markdown is unwrapped to inline
-  on accept; multi-block markdown is inserted as blocks.
-- **Formatting is part of your replacement, not the anchor.** If the
-  original had `**bold**` or a link, the anchor's formatting is gone
-  on accept — your replacement must include the markdown syntax for
-  any formatting you want preserved.
-- **Anchor at token boundaries, not mid-word.** `textToFind: "istrat"`
-  to hit the middle of "administration" is fragile. Use whole words
-  or sentence boundaries. Use `occurrence` when the same phrase
-  appears multiple times.
-- **Mind the whitespace.** By default, do not include leading or
-  trailing whitespace in the anchor, and end `replacementText` at the
-  same boundary. If you include a trailing space in the anchor,
-  include one in the replacement too; otherwise words smash together.
-
-If you get `text_not_found`, the error message includes the current
-section text. Re-plan against the fresh text and retry. Never retry
-with stale content.
-
-## Discoverability
-
-On first Composer-related message in a session, tell the user:
-"You can say 'send this markdown to Composer' and I'll create a seeded doc
-with a link to open."
-
-## Failure handling
-
-- Setup not done → run `npx @composer-app/mcp@latest setup`, restart your CLI.
-- Anchor text not found → retry against the fresh section text returned in
-  the error.
-- Doc edited mid-turn → anchors re-resolve natively; just retry.