← All templates

Activate lazily, never block the editor, every setting documented.

Constitution — VS Code extension

Version 1.0.0 · Ratified 2026-11-10

These principles hold for every spec, plan and task of the extension. A spec may add rules; it never weakens these.

  1. Activate lazily. The extension declares narrow activation events (a language, a command, a workspace file) and never * or onStartupFinished without a reason in the plan. Activation takes under 100 ms as measured by Developer: Show Running Extensions.

  2. Never block the editor. Heavy work runs asynchronously, in a language server or a worker, with cancellation tokens honoured. No synchronous file system or network call runs on the extension host's main path.

  3. Every setting documented. Every setting in contributes.configuration has a type, a default and a markdownDescription, and changes are picked up without reloading the window. A setting missing from the README fails the review.

  4. Clean up what you register. Every command, listener, provider and watcher is added to context.subscriptions or disposed explicitly. Deactivating the extension leaves no running timers or processes.

  5. Small and fast to install. The extension is bundled with esbuild or webpack into one file, and the packaged .vsix has a size budget in the plan. Unused dependencies are not shipped.

  6. Tested in the editor. Integration tests run with @vscode/test-electron or @vscode/test-cli against the minimum supported VS Code version in engines and the latest stable, in CI. A red test blocks the release.