pbakaus_impeccable/docs/VSCODE-EXTENSION.md

VS Code skill distribution

The VS Code extension is a declarative delivery channel for the GitHub Copilot skill. bun run build stages dist/vscode/ from the GitHub provider output; bun run package:vscode builds and packages a VSIX with pinned @vscode/vsce tooling. Nothing is published by either command.

Install Impeccable from the Visual Studio Marketplace, published by Renaissance Geek, or run code --install-extension renaissance-geek.impeccable. Requires VS Code 1.109.3+, Copilot Chat access, and a trusted local workspace. Use Chat in Agent mode, for example /impeccable polish. Avoid duplicate Impeccable skill installations in the same workspace/profile.

The package version follows .claude-plugin/plugin.json. Do not independently bump it for feature work. Publication and updates are separate maintainer steps; building or packaging does not publish.

Scope

• Register skills/impeccable/SKILL.md through contributes.chatSkills.
• Include its references, inline role fallbacks, launchers, and pinned engine version. Do not bundle engine binaries.
• Resolve launcher paths from the loaded skill, not .github/skills in the workspace. Preserve the project's working directory.
• No extension entrypoint, activation events, automatic hooks, custom-agent registrations, settings mutations, or workspace copying.
• Marketplace updates own the bundled files. No separate extension update command.

VS Code 1.109 introduced the contribution point; 1.109.3 added skill slash commands. The manifest therefore requires ^1.109.3. Register the SKILL.md file, not the containing folder; early release-note examples used the folder form. Supporting files remain adjacent and are referenced by relative Markdown links.

Sources: release notes, contribution-point reference, supporting-file clarification.

Validation

node --test tests/vscode-extension.test.mjs checks the generated manifest, linked resources, launcher relocation (including spaces and project cwd), lack of repo-install sidecars, and deterministic rebuilding. The core suite includes these checks. CI also runs vsce package on the staged directory.

Before publishing, install the VSIX into a separate VS Code profile and extensions directory:

code --user-data-dir /absolute/path/to/test-profile \
  --extensions-dir /absolute/path/to/test-extensions \
  --install-extension dist/vscode/impeccable-<version>.vsix
code --user-data-dir /absolute/path/to/test-profile \
  --extensions-dir /absolute/path/to/test-extensions \
  /absolute/path/to/synthetic-project

Use an otherwise skill-free fixture with PRODUCT.md, DESIGN.md, and a small HTML file. Disable discovery of user-level Impeccable copies in that test profile to avoid testing the wrong installation. Sign into Copilot without enabling Settings Sync.

Check that /impeccable is discoverable, the loaded SKILL.md is inside the installed extension, a command-specific reference resolves there, and the launcher runs with cwd at the fixture. Record any requested command approvals. Also check that installation itself created no .github/ directory or instructions file in the fixture. A launcher subprocess test alone is not a Copilot behavior test.

Test the oldest supported editor as well as current stable before publication. Windows and remote workspaces need separate smoke checks; do not infer them from a macOS local run. Plain browser-only VS Code cannot run the native launcher.

Initial macOS packaging checks: the VSIX installs in VS Code 1.109.3 (which resolves Copilot Chat 0.37.9) and 1.136.1. Both editor versions also passed the read-only Copilot behavior smoke below.

Recorded Copilot smoke (September 7, 2026)

VS Code 1.136.1, Copilot Chat 0.64.1, Auto routed to GPT-5.6 Luna. A single read-only /impeccable polish index.html compatibility request passed:

• /impeccable appeared in the slash picker after reloading the window following initial folder trust. Before that reload, the extension was installed but absent from the skill list.
• Copilot invoked the quoted absolute skills/impeccable/scripts/impeccable path inside the installed extension, with context --target index.html. One command approval was granted; default permission settings remained unchanged.
• The loader resolved the synthetic project root and its PRODUCT.md and DESIGN.md. Copilot then read reference/polish.md from the same extension, followed by the three fixture files.
• The completed report correctly described the fixture. The project still contained only its original three files, with unchanged contents. No workspace skill copy, server, or image-generation call was created.

The final renaissance-geek.impeccable 4.2.2 VSIX also passed the same read-only smoke in VS Code 1.109.3 / Copilot Chat 0.37.9 (Auto selected GPT-5.3-Codex): slash discovery, the installed launcher, project context, and the polish reference all resolved correctly. One scoped command approval was granted, and all three fixture files remained unchanged.

After publication, code --install-extension renaissance-geek.impeccable installed 4.2.2 into fresh isolated profile/extensions directories in VS Code 1.136.1. All 55 extension payload files matched the tested VSIX (ignoring VS Code's added package.json installation metadata). Its installed launcher loaded the same fixture context successfully; fixture hashes and file inventory stayed unchanged. This Marketplace check verified download/install and payload identity, not an additional Copilot conversation.

These are packaging/path-resolution smokes, not activation-reliability or design-quality evaluations. They do not establish Windows or remote-host behavior.