@napster-corp/webmcp-toolkit 1.0.0

package/skills/plan-capabilities-and-state/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: plan-capabilities-and-state
+description: Analyze an existing web app and propose a curated plan for what an AI agent should be able to DO (capabilities) and SEE (live-state resources), with deliberate withholds. Use when the developer asks "what should I expose to the agent?", "help me figure out which capabilities to add", "what can my app do that an agent should know about?", or before running setup-edge-mcp on a new app. Produces a conversational plan that the developer reviews, edits, and approves — no file output. The setup-edge-mcp skill invokes this skill automatically if no plan has been agreed yet.
+---
+
+# plan-capabilities-and-state
+
+Read the developer's existing web app and propose a starter plan for a WebMCP integration: which operations should be exposed as **capabilities** the agent can invoke, which state slices should be exposed as **live-state resources** the agent can observe, and what should be deliberately **withheld**.
+
+The output is a conversation, not a file. The developer reviews each item, edits or rejects freely, and approves the final list. That approved plan flows directly into the `setup-edge-mcp` skill, which turns it into code.
+
+**Why this skill exists.** Without it, a developer setting up WebMCP starts from a blank canvas — they have to invent the capability list while also reasoning about side-effect tiers, the live-state resource gate, and what to deliberately withhold. That's high cognitive load. This skill does the inventory work first, so the developer reviews a structured proposal instead of brainstorming from scratch.
+
+## 0. Confirm you're reading the real target app
+
+Before any analysis: skim the actual source — components, the store, the service calls the UI makes, the route structure. Don't trust ambient context files (`CLAUDE.md`, READMEs, project docs) if they describe a different project or contradict the code; the running code is the source of truth, and a stale context file has sent past runs down the wrong path.
+
+If the codebase doesn't match the developer's description, stop and verify before proceeding.
+
+## 1. Identify the domain and the high-value workflows
+
+Before listing individual capabilities, frame the bigger picture:
+
+- **What is this app?** One sentence summarizing the domain. Apps that WebMCP fits include, but are not limited to:
+  - Commerce: *"Electronics e-commerce for logged-in customers"*
+  - Documentation / developer relations: *"API docs site with search, code samples, and a live-agent escape hatch"*
+  - Content / marketing: *"Marketing site with product pages, a blog, and a contact form"*
+  - Healthcare: *"Patient portal for appointment management"*
+  - Internal tools: *"CRM for sales reps"*, *"Read-mostly admin dashboard with a few destructive actions"*
+  - Productivity: *"Project management tool with tasks, comments, and a sidebar"*
+  
+  Any of these is a valid target. Don't assume WebMCP only fits transactional apps — a docs site whose only "operations" are search, page-open, and copy-to-clipboard is just as legitimate as an e-commerce checkout.
+
+- **Who is the user the agent will act on behalf of?** Often the signed-in user; for public or content-heavy sites it's the anonymous visitor. The agent runs scoped to that user's existing rights either way.
+
+- **What are the two or three high-value workflows the agent should be good at?** Workflows look different per domain — match the *actual* shape of the app, not a transactional template:
+  - Commerce: *find and compare products, reorder a past purchase, start a return*
+  - Docs / dev rel: *find the right docs page, walk the user through API setup, copy snippets to clipboard, hand off to a live agent when needed*
+  - Content / marketing: *find a relevant article, jump to a specific section, submit a contact form*
+  - Healthcare: *schedule a follow-up, show upcoming visits*
+  - Internal tools: *look up a record, trigger a known recovery flow*
+  
+  The capability list flows from these. A docs site with three workflows and five capabilities is a perfectly normal output of this skill — not a small or "weak" plan.
+
+If you can't answer these from the codebase alone, ask the developer in plain language before going further.
+
+## 2. Propose candidate capabilities
+
+For each high-value workflow, identify the real operations in the codebase that fulfill it. For each candidate, propose:
+
+- **Name** — in the app's own domain terms, as `domain.verb`. Make cardinality obvious (`products.viewDetails` for one, `products.search` for many).
+- **One-line purpose** — what the agent uses it for.
+- **Arguments** — the input shape, in plain language drawn from the real function signature. List each argument with its type and whether it's required, or write "(no arguments)" if there are none. Example: "query (string, required), maxPrice (number, optional)". You are not writing JSON Schema yet — that's `setup-edge-mcp`'s job — but every capability's arguments must surface here, because the agent cannot use a capability whose input shape is unknown.
+- **Side-effect tier** — using the table below.
+- **Idempotency** — only relevant for `irreversible` tier; mark `true` only if the underlying operation tolerates safe retry (e.g. via an idempotency key).
+- **Evidence** — the file and function in the codebase that backs it (e.g. `src/api/products.ts:searchProducts`). The developer should be able to grep-verify in seconds.
+- **Confidence** — high / medium / low. Reserve low for cases where you're unsure the operation is technically exposable or appropriate.
+
+### Side-effect tiers
+
+| Tier | Returns | Examples | Default when ambiguous |
+|---|---|---|---|
+| `read` | Information; changes no durable state | search, look up, compare | — |
+| `reversible` | A change that's easy to undo | add to cart, save draft, apply filter | escalate from `read` to here if any doubt |
+| `irreversible` | A change that can't be cleanly undone | place order, charge card, cancel, send email | escalate from `reversible` to here if any doubt |
+
+**Default to the safer tier when ambiguous.** Irreversible tier triggers explicit verbal confirmation at runtime; classifying down loses that protection.
+
+### Rules for the capability list
+
+- **One real operation = one capability.** No invented operations, no wrappers around capabilities that don't reflect real app behavior.
+- **Composition is fine.** A `checkout.placeOrder` capability may chain several of the app's real operations (`startCheckout → updateCheckout → placeOrder → refresh`). That's orchestrating the app's own calls. Re-deriving business logic (recomputing prices, re-validating rules the app already owns) is what's forbidden.
+- **Named navigation IS a capability.** `docs.openPage({ slug })`, `account.openSettings()`, `cart.viewDrawer()` are legitimate first-class capabilities — especially for docs sites, content-heavy apps, and anything where "take me to X" is a real user intent. The pattern to **strongly avoid** is a *generic* `navigate({ url })` or `goto({ path })` tool that hands raw routes to the agent. The bridge won't reject it, but it forces the agent to reason in routes instead of domain terms — the agent invents URLs that don't exist, calls break when you refactor a route, and the curation that's the whole point of WebMCP gets sidestepped. The distinguishing test: does the capability require the agent to know the *route system*, or just the *domain*? If domain (a page slug, a product id, a section name), it's fine — that's still a named intent with a parameter. If route system (a raw URL), prefer a named alternative. Routes stay an implementation detail of `execute`.
+- **"Read-only" surfaces still have capabilities.** Even an app that doesn't mutate data has things the agent can DO: search, open a specific page, copy a snippet, open a modal, start a session, submit a form. If you find yourself thinking "this app has no real operations," look again — the operations are everything the user can trigger via a click.
+- **Start small. The plan can also be very small, or zero.** Default to a high-value subset, not an inventory of everything. The plan should be the smallest set that supports the workflows from §1. Three to five capabilities is a normal-sized plan for a focused app. One or two is fine. **Zero is also a valid outcome:** if, after honestly reading the codebase, the app has no real operations worth exposing to the agent (a pure marketing page with one contact form, a static doc browser whose only "operation" is the user reading), say so. Recommend that the developer keep their existing MCP server (if any), use a non-Edge agent (a chatbot reading the docs), or skip the bridge entirely. Padding the plan with speculative capabilities (`copyPrompt` for a single hardcoded prompt, `openSomething` wrapping a button click that the user can already perform) is a worse outcome than an honest "WebMCP isn't the right fit here."
+
+## 3. Propose candidate live-state resources
+
+For each candidate live-state resource, propose:
+
+- **Name** — a noun identifying the slice (`cart`, `currentOrder`, `orderStatus`).
+- **Why it cleared the gate** — see below.
+- **Evidence** — where the underlying state lives (store, signal, query-cache key).
+- **Confidence** — high / medium / low.
+
+### The gate (mechanical test)
+
+Add a live-state resource **only for state that changes out-of-band** — state the agent needs to see that changes *without the agent acting*:
+
+- The **user** changes it by hand (edits a cart quantity, toggles a filter, navigates somewhere), or
+- It changes **server-side over time** (an order moves from `processing` to `shipped` while the conversation is open).
+
+That's the whole test. **If a capability already returns the answer, do NOT add a resource that mirrors it.** A search that returns its results inline needs no `searchResults` resource; a `products.viewDetails` that returns the product needs no `currentProduct` resource. Resources are for the state the return *can't* give you, not a shadow copy of the state it can.
+
+Common cases:
+- `cart` → usually a good resource (user can edit it directly in the UI)
+- `orderStatus` → usually a good resource (moves server-side)
+- `searchResults` → usually NOT a resource (the search capability returns the results)
+- `currentProduct` → usually NOT a resource (the `viewDetails` capability returns the product)
+
+Apply the gate to each candidate and drop anything that fails it. The live-state resource list is the **exception, not the rule** — most apps need only a handful, and **many apps need zero**. Content sites, docs sites, marketing pages, and read-mostly admin tools often have no state that changes out-of-band: the user reads, the agent searches and navigates, nothing mutates behind anyone's back. An empty resources list is the correct outcome for those apps, not a sign that something is wrong.
+
+## 4. List the deliberate withholds
+
+The negative space matters as much as the positive list. Identify and call out:
+
+- **Capabilities deliberately withheld.** Destructive admin actions, billing internals, anything sensitive or rarely needed. Name them and explain why each is excluded. Common examples: `admin.deleteUser`, `account.changePassword`, raw payment-method management, refund disputes.
+- **State the agent should NOT see.** Other users' data, sensitive auth state, private payment information, transient UI state that would confuse rather than help.
+- **Deflections** — workflows the agent should redirect the user to handle themselves rather than attempt programmatically. Common examples: multi-factor confirmation flows, support disputes, anything requiring human review.
+
+The framing here is important: **exposing a capability is an approval, not an inventory.** The agent runs as the signed-in user, but that doesn't mean every operation the user can do should flow through the agent. Curation is the point.
+
+## 5. Present the plan to the developer
+
+Walk through the plan in conversation. Use a clear structure:
+
+1. **Domain summary + high-value workflows** — confirm framing.
+2. **Candidate capabilities, grouped by tier**, with arguments and confidence levels noted. Flag low-confidence items for closer review.
+3. **Candidate live-state resources**, each with one-line why-it-cleared-the-gate.
+4. **Deliberate withholds and deflections**, with reasoning.
+
+Force an explicit per-item review for high-confidence items rather than passive accept-by-default. The developer should *approve* each capability, not silently accept the whole list.
+
+For each item, the developer can:
+- **Approve** as proposed.
+- **Edit** name, tier, or scope.
+- **Reject** with a reason (which adds it to the withhold list with a justification).
+- **Add** a capability or resource you missed.
+
+End the review with an open prompt: "Anything missing?" — the developer almost always thinks of one or two workflows the analysis didn't surface.
+
+## 6. Iterate until approved
+
+The first pass is a draft. Be prepared to revise:
+- Re-classify tiers if the developer pushes back ("`cancelOrder` is actually idempotent — we have an idempotency-key server-side").
+- Drop resources that turn out to mirror returns once the capability shape is clear.
+- Add capabilities you missed.
+- Move items between the expose list and the withhold list as the conversation refines them.
+
+Don't move on until the developer explicitly says the plan is good to go. The whole point is that they own the decision; rushing approval defeats the purpose.
+
+## 7. Hand off
+
+Once the plan is approved, summarize the final state:
+
+- N capabilities approved (M read, K reversible, J irreversible, with idempotency flags)
+- P live-state resources approved
+- Q items deliberately withheld
+- R deflections noted
+
+Then prompt to continue with `setup-edge-mcp` (or remind the developer that's the natural next step if they invoked this skill directly). The setup skill picks up the approved plan and turns it into registered code.
+
+### If the plan came out at zero
+
+If the honest answer was "this app has no real operations worth exposing," don't run `setup-edge-mcp`. Tell the developer plainly:
+
+> Based on the codebase, WebMCP isn't the right fit for this app right now. The agent has nothing real to DO here — only what the user is already doing by reading the page. Options: (a) keep using your existing chatbot / MCP server / docs-aware assistant if you have one; (b) revisit this if you add interactive features later (forms, dynamic content, multi-step flows). WebMCP earns its weight when the agent can act on the user's behalf; without that, it's scaffolding for no payoff.
+
+Skip the setup. A zero-plan is a sign that this skill did its job — not a failure to find capabilities.
+
+## What you will NOT do in this skill
+
+- Write any code. This skill is conversational. Code happens in `setup-edge-mcp`.
+- Produce a JSON or markdown file. The plan lives in the conversation; the code is the record.
+- Skip the gate for live-state resources. Every resource must have a one-line justification that maps to user-edit or server-side change.
+- Approve items the developer hasn't reviewed. "Looks good?" with no explicit approval doesn't count.
+- Suggest capabilities the codebase doesn't actually support. Every candidate must have evidence; if you can't cite a file and function, don't propose it.
+- Plan vendor-specific integration (the Napster Web SDK auto-attach, Function configuration, voice/avatar persona). That's downstream of WebMCP and belongs to the agent vendor's skills.