From 22c8f144f76df7082e4de450640898aaa0c4bb16 Mon Sep 17 00:00:00 2001 From: Chip Lay Date: Mon, 4 May 2026 16:22:47 -0400 Subject: [PATCH] refactor(skills): rename setup-plugin to verify-setup, drop install branch MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The skill ships *inside* the plugin, so its install instructions are unreachable in practice — if an agent can read the skill, the plugin is already installed. Refocus the skill on what it can actually do: verify connectivity, diagnose MCP / auth failures, check local deps. - Rename `skills/setup-plugin/` → `skills/verify-setup/` and rewrite SKILL.md around verification + diagnosis. Install instructions point at https://subtext.fullstory.com/install/ (already linked from README). - Drop platform-specific install slash commands; diagnostics now describe the failure mode rather than prescribing platform-specific UI. - Drop the misleading `platform: claude-code` frontmatter — the skill is cross-platform now. - Update references in onboard, using-subtext, skills/README.md, authoring.md. - Bump all platform manifests 0.2.x → 0.2.2. Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- .cursor-plugin/plugin.json | 2 +- skills/README.md | 4 +- skills/authoring.md | 2 +- skills/onboard/SKILL.md | 4 +- skills/setup-plugin/SKILL.md | 73 --------------------------------- skills/using-subtext/SKILL.md | 2 +- skills/verify-setup/SKILL.md | 54 ++++++++++++++++++++++++ 10 files changed, 64 insertions(+), 83 deletions(-) delete mode 100644 skills/setup-plugin/SKILL.md create mode 100644 skills/verify-setup/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 0008c9f..27fc37a 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -9,7 +9,7 @@ { "name": "subtext", "source": "./", - "version": "0.2.1", + "version": "0.2.2", "description": "Tools that let coding agents verify and show their work against your running application", "category": "development", "keywords": ["subtext", "automation", "verification", "testing", "session-replay", "debugging", "fullstory"], diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 3786ca7..ead47d7 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "subtext", - "version": "0.2.1", + "version": "0.2.2", "description": "Tools for agents to build with Subtext", "license": "MIT", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index dc86d1f..02b930c 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "subtext", - "version": "0.2.1", + "version": "0.2.2", "description": "Tools that let coding agents verify and show their work against your running application", "author": { "name": "Subtext", diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 4e9db15..2bfadc2 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "subtext", "description": "Tools that let coding agents verify and show their work against your running application", - "version": "0.2.0", + "version": "0.2.2", "license": "MIT", "author": { "name": "Subtext", diff --git a/skills/README.md b/skills/README.md index 4ad0dc4..b9eb82e 100644 --- a/skills/README.md +++ b/skills/README.md @@ -27,14 +27,14 @@ Before creating or modifying any skill, read [`authoring.md`](authoring.md). ## Onboarding — "getting started" - **subtext:onboard** — Three-step first-run flow: connect to the user's local dev server, prove a small change with before/after evidence, bootstrap a starter `.sightmap/` from what was learned. -- **subtext:setup-plugin** — Install the Subtext plugin and configure MCP servers (invoked implicitly by `onboard` if MCP isn't reachable). +- **subtext:verify-setup** — Verify the plugin is connected and diagnose MCP / auth failures (invoked implicitly by `onboard` if MCP isn't reachable). Does not install — see https://subtext.fullstory.com/install/. - **subtext:first-session** — Agent-driven exploration of the user's site via the hosted browser. ## How they compose ``` onboard - ├─ setup-plugin (implicit health check; only runs on failure) + ├─ verify-setup (implicit health check; only runs on failure) ├─ tunnel + live (connect to user's local dev server) ├─ proof (small change → before/after evidence) └─ sightmap (write .sightmap/components.yaml from what was learned) diff --git a/skills/authoring.md b/skills/authoring.md index 5a58bc0..02aa610 100644 --- a/skills/authoring.md +++ b/skills/authoring.md @@ -66,7 +66,7 @@ A workflow earns its length through decision points. If every section is "call t ### Onboarding-shaped workflows -Skills like `onboard`, `setup-plugin`, and `first-session` are workflow-shaped but user-facing — guided setup rather than agent-internal orchestration. They follow the same bare-name rule. Treat them as adjacent to the three buckets, not a fourth tier. +Skills like `onboard`, `verify-setup`, and `first-session` are workflow-shaped but user-facing — guided setup rather than agent-internal orchestration. They follow the same bare-name rule. Treat them as adjacent to the three buckets, not a fourth tier. ## Conventions diff --git a/skills/onboard/SKILL.md b/skills/onboard/SKILL.md index 32b1855..e3ff325 100644 --- a/skills/onboard/SKILL.md +++ b/skills/onboard/SKILL.md @@ -17,7 +17,7 @@ The goal: walk a new user through one real, useful Subtext run end-to-end. They ## Implicit health check -Do **not** announce a "plugin setup" step. Trust that the plugin is installed — the user just ran a slash command from it. If the first MCP call below fails (server unreachable, auth missing), invoke `subtext:setup-plugin`, then retry the call. Otherwise stay silent about plumbing. +Do **not** announce a "plugin setup" step. Trust that the plugin is installed — the user just ran a slash command from it. If the first MCP call below fails (server unreachable, auth missing), invoke `subtext:verify-setup`, then retry the call. Otherwise stay silent about plumbing. ## Greeting @@ -57,7 +57,7 @@ Once you have a `http://localhost:…` (or `http://127.0.0.1:…`) URL, follow t 2. `tunnel-connect({ relayUrl, target: })` → confirm `state: "ready"` 3. `live-view-new({ connection_id, url: })` → returns `trace_url` (and the initial snapshot) -If any of these calls fails because the MCP server is unreachable, invoke `subtext:setup-plugin`, then retry. +If any of these calls fails because the MCP server is unreachable, invoke `subtext:verify-setup`, then retry. **Print the `trace_url` immediately, on its own line, before saying anything else:** diff --git a/skills/setup-plugin/SKILL.md b/skills/setup-plugin/SKILL.md deleted file mode 100644 index 94e662c..0000000 --- a/skills/setup-plugin/SKILL.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -name: setup-plugin -description: Install the Subtext plugin and configure MCP servers. Authenticates via OAuth or API Key. -metadata: - platform: claude-code - requires: - skills: ["subtext:shared"] ---- - -# Setup Plugin - -Install and verify the Subtext plugin for Claude Code. - -## Pre-check - -Verify the plugin is working by testing actual connectivity — do NOT read config files or plugin cache directories. - -**Step 1: Test MCP connectivity** - -Try calling a lightweight MCP tool to verify the server is reachable. For example, list the available tools on the `subtext` MCP server. If the call succeeds, the plugin is installed and connected. - -Check these servers: -- `subtext` — required (for review, live, comments) -- `subtext-tunnel` — optional (local tunnel client) - -If MCP tools are available, the plugin is working. Report which servers connected and move on. - -**Step 2: Verify local dependencies** - -Run in a single command: -```bash -python3 --version 2>&1 && python3 -c "import yaml; print('PyYAML OK')" 2>&1 -``` - -These are required by the sightmap upload script. If missing: -- No Python 3: suggest `brew install python@3.12` (macOS) -- No PyYAML: suggest `python3 -m pip install pyyaml` - -**If all pass:** report "Plugin is set up — MCP servers connected, dependencies OK." and exit. - -## Install Steps - -### Plugin not installed - -If MCP tools are not available, the plugin needs to be installed. - - - -Tell the user to run: - -``` -/plugin marketplace add https://subtext.fullstory.com/repo.git -/plugin install subtext@subtext-marketplace -``` - -Note: Slash commands can't be executed by the agent — the user must run them directly. - -### MCP connectivity failed - -If the MCP connectivity test fails, tell the user: - -1. **MCP connectivity test failed** — the subtext MCP server did not respond. -2. **Double-check authentication settings** for the MCP servers in the tool configuration. -3. **To authenticate**, follow the OAuth flow provided by the tool being used (e.g. Claude Code, Cursor) to connect the MCP servers. Alternatively, manually configure an API key header value for the MCP server as described in the installation instructions. - -After the user has addressed authentication, re-run the MCP connectivity check to confirm everything works. - -## Explain - -After setup, explain what was installed: -- **Skills** — `proof` (before/after evidence for UI changes), `review` (structured summary of any session), `onboard` (first-run walkthrough), plus the underlying tool catalogs (`live`, `session`, `comments`, `tunnel`, `sightmap`) -- **MCP servers** — `subtext` (review, live, comments) and `subtext-tunnel` (local tunnel client) -- **Sightmap** — semantic component mapping, uploaded automatically after each connection. Created naturally as agents work; see `subtext:sightmap`. diff --git a/skills/using-subtext/SKILL.md b/skills/using-subtext/SKILL.md index 834c7ed..11b9947 100644 --- a/skills/using-subtext/SKILL.md +++ b/skills/using-subtext/SKILL.md @@ -64,7 +64,7 @@ These thoughts mean STOP — you're rationalizing: - **Atomics** (`shared`, `session`, `live`, `sightmap`, `tunnel`, `comments`) — tool catalogs. - **Workflows** (`proof`, `review`) — orchestration. `proof` is the inner loop, `review` is the outer loop. - **Recipes** (`recipe-sightmap-setup`) — short step lists. -- **Onboarding** (`onboard`, `setup-plugin`, `first-session`) — first-time user setup. +- **Onboarding** (`onboard`, `verify-setup`, `first-session`) — first-time user setup. ``` proof ──▶ session recorded ──▶ review (optional handoff) diff --git a/skills/verify-setup/SKILL.md b/skills/verify-setup/SKILL.md new file mode 100644 index 0000000..bfe0f81 --- /dev/null +++ b/skills/verify-setup/SKILL.md @@ -0,0 +1,54 @@ +--- +name: verify-setup +description: Verify the Subtext plugin/extension is connected and diagnose MCP connectivity or auth failures. Does not install — see https://subtext.fullstory.com/install/ for first-time setup. +metadata: + requires: + skills: ["subtext:shared"] +--- + +# Verify Setup + +Confirm Subtext is wired up correctly and diagnose failures. This skill assumes the plugin/extension is already installed — you wouldn't be reading it otherwise. For first-time install, point users at https://subtext.fullstory.com/install/. + +## When to use + +- User asks *"is Subtext working?"* or *"is it set up?"* +- A Subtext MCP tool just failed and you need to diagnose why +- Invoked implicitly by `subtext:onboard` when an early MCP call errors out + +## Step 1: Test MCP connectivity + +Try a lightweight MCP call to confirm the server is reachable. Listing tools on the `subtext` server is a good probe — it doesn't require any session or scope beyond auth. + +Servers to consider: +- `subtext` (US) or `subtext-eu1` (EU) — required for review, live, comments. Whichever the user's account region uses. +- `subtext-tunnel` — optional, only needed for hosted-browser flows against a localhost dev server. + +If the call succeeds, the plugin is connected. Report which servers are reachable and move to Step 2. + +If the call fails, classify the failure: + +- **Tool / server not registered** (the MCP server name isn't even available) → the plugin or extension isn't activated in this agent. Tell the user to enable it via their platform's extension/plugin UI. Don't prescribe specific UI flows — different platforms differ; ask the user to check whichever they're on. +- **401 / 403 / "auth required"** → MCP server is reachable but unauthenticated. Tell the user to complete the OAuth flow (typically opens a browser on first tool use), or to configure an API key per their platform's MCP server settings. Detailed install/auth steps live at https://subtext.fullstory.com/install/. +- **Network error / 5xx / timeout** → MCP server is unreachable. Suggest checking network and retrying. If persistent, escalate to subtext@fullstory.com. + +## Step 2: Verify local dependencies + +The sightmap upload script (`skills/shared/collect_and_upload_sightmap.py`) needs Python 3 + PyYAML. Run as a single command: + +```bash +python3 --version 2>&1 && python3 -c "import yaml; print('PyYAML OK')" 2>&1 +``` + +- No Python 3 → suggest the user's OS-appropriate install (e.g. `brew install python@3.12` on macOS). +- No PyYAML → suggest `python3 -m pip install pyyaml`. + +These aren't fatal — Subtext's MCP tools work without sightmap upload — but agents that try to upload sightmap on session start will fail silently if these are missing. + +## Step 3: Report + +If everything passes: + +> "Subtext is connected. MCP servers reachable, deps OK." + +If something failed, report the specific failure and the next step you suggested. Stay terse — the user wants to get unstuck, not read a plumbing essay.