Merge pull request #84 from Automattic/vscode-extension-scaffold

Add VS Code Studio connector scaffold

Author: chubes4

README.md

@@ -43,6 +43,7 @@ Generated outputs are available for:
 - Qodo
 - Roo Code
 - Devin Desktop
+- VS Code Marketplace extension scaffold
 - Zed
 
 The shared WordPress workflow:
@@ -95,9 +96,10 @@ Each build packages the shared `skills/` directory into the surfaces that can co
 | Qodo | `plugins/qodo/` | `AGENTS.md`, `skills/`, MCP setup documented for Qodo Agentic Tools |
 | Roo Code | `plugins/roo-code/` | `.roo/mcp.json`, `.roo/rules/`, `.roo/rules-code/`, `skills/` |
 | Devin Desktop | `plugins/devin-desktop/` | `.devin/rules/`, `mcp_config.json`, `skills/` |
+| VS Code Marketplace extension scaffold | `plugins/vscode/` | `package.json`, `extension.js`, `mcp.json`, `skills/` |
 | Zed | `plugins/zed/` | `AGENTS.md`, `.agents/skills/`, `.zed/settings.json` |
 
-Some outputs intentionally stop at workspace files or setup guidance because that is what the official agent surface supports today. For example, Pi does not expose built-in MCP configuration, Qodo documents MCP through Agentic Tools or enterprise allow-lists, and Conductor keeps MCP setup in app/provider settings rather than a repository-local MCP file. Devin Desktop output lives under `plugins/devin-desktop/`; Cascade's official MCP config destination still uses `~/.codeium/windsurf/mcp_config.json`.
+Some outputs intentionally stop at workspace files or setup guidance because that is what the official agent surface supports today. For example, Pi does not expose built-in MCP configuration, Qodo documents MCP through Agentic Tools or enterprise allow-lists, and Conductor keeps MCP setup in app/provider settings rather than a repository-local MCP file. Devin Desktop output lives under `plugins/devin-desktop/`; Cascade's official MCP config destination still uses `~/.codeium/windsurf/mcp_config.json`. The VS Code output is a generated extension scaffold with the Automattic Marketplace publisher and no Marketplace publishing automation.
 
 ## Testing
 

docs/architecture.md

@@ -66,6 +66,7 @@ Repository-native names used across the source and generated outputs:
     ├── qodo/
     ├── roo-code/
     ├── devin-desktop/
+    ├── vscode/
     └── zed/
 ```
 
@@ -151,6 +152,8 @@ Build with WordPress does not own WordPress site storage, Studio authentication,
 
 Generated output packages are repository-local files. Some agents consume package metadata or marketplace manifests, while other agents consume workspace instructions, MCP config files, or setup notes. The verification script documents which boundary each surface currently supports.
 
+The VS Code output is a repository-generated extension scaffold. It uses the Automattic Marketplace publisher and lightweight local commands, but publishing credentials and Marketplace release automation remain outside this repository until maintainers explicitly add that workflow.
+
 ## Failure modes and invariants
 
 | Area | Failure mode | Invariant or recovery path |

docs/generated-outputs.md

@@ -50,10 +50,13 @@ pnpm build:telemetry-mcp
 | Qodo | `plugins/qodo/` | `AGENTS.md`, `skills/`, and MCP setup guidance for Qodo Agentic Tools. |
 | Roo Code | `plugins/roo-code/` | `.roo/mcp.json`, `.roo/rules/`, `.roo/rules-code/`, `skills/`. |
 | Devin Desktop | `plugins/devin-desktop/` | `.devin/rules/`, `mcp_config.json`, `skills/`. The generated output uses the Devin Desktop name; Cascade's official MCP config destination still uses `~/.codeium/windsurf/mcp_config.json`. |
+| VS Code Marketplace extension scaffold | `plugins/vscode/` | `package.json`, `extension.js`, `mcp.json`, `skills/`. Publisher is `automattic`. |
 | Zed | `plugins/zed/` | `AGENTS.md`, `.agents/skills/`, `.zed/settings.json`. |
 
 Some surfaces support a complete plugin/marketplace package. Others only support workspace instructions, local settings, or user-facing setup notes. The generator should use the best supported native integration point for each surface.
 
+The VS Code output is intentionally a scaffold, not a publishing workflow. It includes Marketplace-shaped extension metadata, the Automattic publisher, command contributions, a thin JavaScript runtime, the bundled MCP config, and shared skills. Add packaging credentials and release automation outside this generated output before attempting Marketplace publication.
+
 ## Shared generated contracts
 
 ### Skill packaging
@@ -110,6 +113,7 @@ Several surfaces require package metadata. Verification checks representative fi
 - MCP config path such as `./.mcp.json`
 - marketplace entries pointing to the generated plugin path
 - schema URLs and package metadata required by a surface
+- publishing identity and release credentials for Marketplace surfaces
 
 Keep these values stable unless the corresponding agent surface changes its contract.
 

docs/skills-and-integrations.md

@@ -62,7 +62,7 @@ The current generated surfaces are listed in the top-level README and [Generated
 
 | Group | Examples | Integration style |
 | --- | --- | --- |
-| Plugin or marketplace packages | Codex, Claude Code, Cursor, Factory, Hermes, OpenClaw, Pi | Generated manifests, package metadata, marketplace entries, and skills. |
+| Plugin or marketplace packages | Codex, Claude Code, Cursor, Factory, Hermes, OpenClaw, Pi, VS Code | Generated manifests, package metadata, marketplace entries or extension scaffolds, and skills. |
 | Workspace instruction surfaces | Aider, Gemini, Qodo, Zed | Generated agent instructions plus skills or setup notes. |
 | MCP-configurable workspaces | Amp, Cline, Continue, Copilot, Devin, Junie, Kilo Code, OpenCode, Roo Code, Windsurf | Generated MCP config in the agent's native location plus skills/instructions. |
 | App/provider configured surfaces | Conductor and some Qodo use cases | Generated setup notes or settings where repository-local MCP config is not the supported path. |
@@ -130,6 +130,8 @@ The shared WordPress workflow can produce three design preview directions before
 5. Add verification for the generated files users or marketplaces will consume.
 6. Document the new surface in `README.md` and [Generated outputs](generated-outputs.md).
 
+For VS Code Marketplace work, keep the generated scaffold separate from publishing. The generated manifest uses the Automattic Marketplace publisher, and this repository should not store Marketplace credentials.
+
 ## Safe extension boundaries
 
 - Add reusable WordPress behavior in `skills/`.

plugins/vscode/README.md

@@ -0,0 +1,31 @@
+# WordPress Studio for VS Code
+
+This is the smallest useful VS Code extension scaffold generated by Build with WordPress. It does not publish anything to the Marketplace from this repository.
+
+## What it includes
+
+- `package.json` with VS Code extension metadata and command contributions.
+- `extension.js` with thin commands to check whether `studio` is available and to show or copy the bundled MCP config.
+- `mcp.json` with `wordpress-studio` and `wordpress-telemetry` server entries.
+- `skills/` as reference Build with WordPress playbooks for editor users and future extension behavior.
+
+## Marketplace placeholder
+
+The manifest uses the Visual Studio Marketplace publisher `automattic`. This repo intentionally does not include publish automation or Marketplace credentials.
+
+## Commands
+
+- `WordPress Studio: Check Studio CLI` runs `studio --version` and reports whether the CLI is on `PATH`.
+- `WordPress Studio: Show MCP Config` opens the bundled `mcp.json` in an untitled JSON editor.
+- `WordPress Studio: Copy MCP Config` copies the bundled `mcp.json` to the clipboard.
+
+## Included skills
+
+- `auditing`
+- `block-creator`
+- `design-previews-creator`
+- `plugin-creator`
+- `site-creator`
+- `studio`
+- `theme-creator`
+- `wordpress-creator`

plugins/vscode/extension.js

@@ -0,0 +1,63 @@
+const vscode = require("vscode");
+const { execFile } = require("child_process");
+const { readFile } = require("fs/promises");
+const path = require("path");
+
+function runStudioVersion() {
+  return new Promise((resolve, reject) => {
+    execFile("studio", ["--version"], { timeout: 10000 }, (error, stdout, stderr) => {
+      if (error) {
+        reject(new Error(stderr || error.message));
+        return;
+      }
+      resolve((stdout || stderr).trim());
+    });
+  });
+}
+
+async function readMcpConfig(context) {
+  return readFile(path.join(context.extensionPath, "mcp.json"), "utf8");
+}
+
+async function checkStudio() {
+  try {
+    const version = await runStudioVersion();
+    vscode.window.showInformationMessage(
+      version ? "Studio CLI is available: " + version : "Studio CLI is available."
+    );
+  } catch (error) {
+    vscode.window.showErrorMessage(
+      "Studio CLI was not found. Install WordPress Studio and ensure the studio command is on PATH. " + error.message
+    );
+  }
+}
+
+async function showMcpConfig(context) {
+  const config = await readMcpConfig(context);
+  const document = await vscode.workspace.openTextDocument({
+    content: config,
+    language: "json",
+  });
+  await vscode.window.showTextDocument(document, { preview: true });
+}
+
+async function copyMcpConfig(context) {
+  const config = await readMcpConfig(context);
+  await vscode.env.clipboard.writeText(config);
+  vscode.window.showInformationMessage("Copied WordPress Studio MCP config to the clipboard.");
+}
+
+function activate(context) {
+  context.subscriptions.push(
+    vscode.commands.registerCommand("wordpressStudio.checkStudio", checkStudio),
+    vscode.commands.registerCommand("wordpressStudio.showMcpConfig", () => showMcpConfig(context)),
+    vscode.commands.registerCommand("wordpressStudio.copyMcpConfig", () => copyMcpConfig(context))
+  );
+}
+
+function deactivate() {}
+
+module.exports = {
+  activate,
+  deactivate,
+};

plugins/vscode/mcp.json

@@ -0,0 +1,50 @@
+{
+  "name": "wordpress-studio-vscode",
+  "displayName": "WordPress Studio",
+  "publisher": "automattic",
+  "version": "0.1.0",
+  "description": "Use WordPress Studio MCP from VS Code and copy the Build with WordPress MCP configuration.",
+  "author": {
+    "name": "Automattic"
+  },
+  "homepage": "https://developer.wordpress.com/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Automattic/build-with-wordpress.git"
+  },
+  "license": "GPL-2.0-or-later",
+  "engines": {
+    "vscode": "^1.95.0"
+  },
+  "categories": [
+    "Other"
+  ],
+  "keywords": [
+    "wordpress",
+    "studio",
+    "mcp",
+    "wp-cli"
+  ],
+  "activationEvents": [
+    "onCommand:wordpressStudio.checkStudio",
+    "onCommand:wordpressStudio.showMcpConfig",
+    "onCommand:wordpressStudio.copyMcpConfig"
+  ],
+  "main": "./extension.js",
+  "contributes": {
+    "commands": [
+      {
+        "command": "wordpressStudio.checkStudio",
+        "title": "WordPress Studio: Check Studio CLI"
+      },
+      {
+        "command": "wordpressStudio.showMcpConfig",
+        "title": "WordPress Studio: Show MCP Config"
+      },
+      {
+        "command": "wordpressStudio.copyMcpConfig",
+        "title": "WordPress Studio: Copy MCP Config"
+      }
+    ]
+  }
+}

plugins/vscode/package.json

@@ -0,0 +1,148 @@
+---
+name: auditing
+description: Audit a Studio-backed WordPress site for performance, accessibility, and visible frontend quality issues, then recommend or validate improvements.
+---
+
+# Auditing
+
+Use this skill when the user wants to review, optimize, or verify an existing WordPress site rather than primarily build new functionality.
+
+## Ownership
+
+This skill owns:
+
+- performance audits using Studio MCP tools
+- accessibility-focused review of color, contrast, motion, and readability
+- visible frontend quality review when the user asks for QA or polish
+- before-and-after audit comparison after fixes
+
+Use `studio` for site resolution, screenshots, and MCP tool usage details.
+
+## Principle
+
+Start with the smallest audit that answers the user's request.
+
+- If the user asks about speed, Core Web Vitals, or performance, prioritize the performance workflow.
+- If the user asks about accessibility, contrast, readability, or color usage, prioritize the accessibility workflow.
+- If the user asks for a general review, combine the relevant sections and keep the report practical.
+
+Do not invent automated checks that the available tools do not provide. When a conclusion comes from visual inspection or code reading rather than a dedicated tool, say so.
+
+## Workflow
+
+### 1. Resolve the target site
+
+Use `studio` to:
+
+- identify the site
+- ensure it is running
+- confirm the page or URL path to review
+
+If the user did not specify a page, default to `/`.
+
+### 2. Pick the audit scope
+
+Choose one or more of:
+
+- Performance Audit
+- Accessibility Review
+- Visual QA
+
+Tell the user which scope you are using when it is not obvious from the request.
+
+Once you begin the actual audit workflow, call `record_workflow_event` with `workflow: "auditing"` and `stage: "started"`.
+
+### 3. Performance Audit
+
+Use `need_for_speed` for the requested path.
+
+Interpret at least:
+
+- TTFB
+- FCP
+- LCP
+- CLS
+- total page weight
+- request count
+- DOM size
+- JS, CSS, image, and font breakdown
+
+Use these baseline thresholds:
+
+| Metric | Good | Needs Improvement | Poor |
+|-------|------|-------------------|------|
+| TTFB | < 800 ms | 800-1800 ms | > 1800 ms |
+| FCP | < 1800 ms | 1800-3000 ms | > 3000 ms |
+| LCP | < 2500 ms | 2500-4000 ms | > 4000 ms |
+| CLS | < 0.1 | 0.1-0.25 | > 0.25 |
+
+Use these page-composition warning signs:
+
+- DOM elements above 1500
+- total page weight above 3 MB
+- total requests above 80
+- scripts above 20 files or 500 KB total
+- stylesheets above 10 files or 200 KB total
+
+Translate findings into WordPress-specific actions where possible, such as:
+
+- reducing or replacing heavy plugins
+- deferring or removing non-critical JS
+- reducing oversized images
+- trimming unused theme CSS
+- checking duplicate font loads
+- simplifying wrapper-heavy block layouts
+
+### 4. Accessibility Review
+
+Use `take_screenshot` plus theme or plugin code inspection as needed.
+
+Focus on issues this repo can realistically help with:
+
+- low text/background contrast
+- weak CTA contrast or ambiguous button states
+- missing or unclear hover and focus states
+- motion that should respect `prefers-reduced-motion`
+- readability issues caused by font size, line height, or dense layouts
+- color choices that make important information hard to distinguish
+
+When the issue is visual, prefer `take_screenshot`-backed observations. Use `inspect_design` when the rendered DOM or computed styles would identify the root cause faster than code inspection.
+
+When the issue appears structural, inspect the relevant theme or plugin files before recommending a fix.
+
+### 5. Visual QA
+
+When the user wants a broader quality pass, use `take_screenshot` to check:
+
+- spacing and alignment
+- responsive layout issues
+- broken visual hierarchy
+- inconsistent component styling
+- awkward cropping or media balance
+
+Keep this section focused on visible problems that materially affect the site.
+
+### 6. Report clearly
+
+Summarize:
+
+- what you audited
+- the most important findings
+- the likely causes
+- the highest-value next fixes
+
+Prefer a short prioritized report over a long exhaustive list.
+
+### 7. Re-test after changes
+
+If fixes are made during the same task, re-run the relevant audit steps and compare before versus after.
+
+Call out what improved, what did not, and any remaining tradeoffs.
+
+When the audit workflow is complete, call `record_workflow_event` with `workflow: "auditing"` and `stage: "completed"`.
+
+## Important notes
+
+- `need_for_speed` results are synthetic measurements from a local Studio environment. Use them primarily for diagnosis and before-versus-after comparison, not as production truth.
+- Accessibility observations in this workflow are often based on visual review and code inspection rather than a dedicated automated accessibility scanner.
+- When performance, accessibility, and design issues conflict, explain the tradeoff instead of over-optimizing one dimension silently.