Spec Lens
VSCode extension for spec-driven development on any repo (brownfield-first):
- Reverse Spec — generate specs from existing code
- Draft Spec — author new specs with LLM assist
- App Map — interactive screens → navigation → API-call map
- Drift Check — verify specs against the actual codebase
See SPEC.md in the repository for the full implementation plan. Work is phased;
current status is tracked in CHANGELOG.md. docs/FAQ.md answers the common
questions — when the LLM is called, what lives in .speclens/, how the cache and
the drift statuses work.
Supported frameworks
The analyzer picks the first matching framework adapter (all analysis is
static and local — zero LLM calls):
| Framework |
Detected by |
Graph contents |
| Flutter/Dart |
pubspec.yaml with flutter: |
screens (GoRouter/Navigator), navigations, Dio/Retrofit/http calls, models, state deps |
| Angular |
angular.json or @angular/core dep |
routed @Components, routerLink/router.navigate edges, HttpClient calls |
| React / Next.js |
react/next in package.json |
App & Pages Router pages, React Router routes, <Link>/router.push/navigate edges, fetch/axios calls, Next API routes as server endpoints |
| Go |
go.mod |
server endpoints (net/http incl. 1.22 patterns, gin, echo, chi, gorilla/mux, fiber) with request/response structs, outgoing HTTP calls |
| Java |
pom.xml / build.gradle |
Spring MVC & JAX-RS endpoints with @RequestBody/return-type models, RestTemplate/WebClient/Feign outgoing calls |
Backend workspaces (Go, Java) have no screens — the App Map is empty but the
API list, API specs and drift check work on the endpoint surface.
Monorepos: detection scans subdirectories (two levels deep) too, so a repo
with web/ (React) + server/ (Go) analyzes both and merges them into one
graph. A frontend call and the backend endpoint that implements it become one
node — and the drift report lists every client call that no server
endpoint in the workspace implements (renamed, deleted, or external).
LLM providers
Configured via specLens.llm.provider:
| Provider |
Setup |
vscode-lm (default) |
None — uses your Copilot models via the VSCode Language Model API |
anthropic |
Run Spec Lens: Set API Key |
ollama |
Local Ollama; set specLens.ollama.baseUrl if not on :11434 |
custom |
Any OpenAI-compatible endpoint: specLens.custom.baseUrl (+ headers / API key) |
Pick the model with Spec Lens: Select LLM Model — it lists what is
actually available on this machine (live Copilot models for vscode-lm,
installed Ollama tags) rather than the static dropdown in Settings, and writes
the choice to user settings.
Semantic search embeddings (specLens.embeddings.provider) support ollama
and custom only; with none search is lexical-only.
All LLM responses are cached by content hash under .speclens/cache/ in the
target repo — identical inputs never call the LLM twice.
Using it
Run Spec Lens: Get Started — it initializes .speclens/, analyzes the
workspace and opens the App Map in one go. (Opening a supported repo that has
never been initialized offers this automatically, and a 5-step walkthrough
lives on VSCode's Welcome page.) After that you mostly do not touch the
command palette — the extension comes to the code you have open:
- CodeLens on screen classes — each screen shows its linked spec and that
spec's last drift result, with
Check Drift / Show in Map next to it, or
Generate spec when the screen has none. Badges are read from the last stored
check, so scrolling never costs an LLM call.
- Problems panel — drift lands on the spec file as diagnostics: structural
misses are errors, drifted behavior lines warnings, unverifiable information.
- Status bar —
N drifted / N specs aligned; click to re-check.
Checks run from any of these update all of them, and a per-screen check merges
into the whole-repo report rather than replacing it.
Commands
- Spec Lens: Get Started — initialize + analyze + open the App Map, in one command
- Spec Lens: Initialize — create
.speclens/ (specs/, cache/, README) in the workspace
- Spec Lens: Analyze Workspace — build the app graph (screens, navigation, API calls)
- Spec Lens: Open App Map — the interactive map
- Spec Lens: Search — QuickPick over screens, endpoints, specs, files
- Spec Lens: New Spec — author a spec for code that does not exist yet
- Spec Lens: Generate Specs for All Screens — bulk reverse-spec (confirms the call count first)
- Spec Lens: Check Drift — whole-repo drift report webview
- Spec Lens: Approve Spec — mark the open spec approved
- Spec Lens: Set API Key — store the key in VSCode SecretStorage
- Spec Lens: Select LLM Model — pick
specLens.llm.model from the models this machine actually has
- Spec Lens: Test LLM Provider — one-shot round-trip against the configured provider
A semantic drift check that finds behavior the spec never documents writes it
into the spec by default (version bump + changelog, status back to draft for
review). Turn off with specLens.drift.autoDocument: false.
Development
npm install
npm run typecheck
npm test # vitest: cache + provider tests against mock servers
npm run build # esbuild bundle → dist/extension.js
Launch with F5 (Extension Development Host) after npm run build.
