SpecURI

You are reviewing a clickdummy an agent built from your specs. A button in the mockup has a small link beside it: F-1234 — Session Invitations. You click it, and the Feature opens in VS Code, right there in the SPECLAN editor, revealed in the tree with its parents expanded.

That link is a SpecURI. It is how a generated work product points back at the specification that governs it.

This page covers what a SpecURI is, what happens when you click one, how links behave when you have several SPECLAN projects open, and what to do when a link appears to do nothing.

What Is a SpecURI?

A SpecURI is a link that names a SPECLAN entity by its ID and opens it in VS Code:

vscode://DigitalDividend.speclan-vscode-extension/open?id=F-1234

It can name any of four entity types:

Type	ID shape	Example
Goal	`G-###`	`G-002`
Feature	`F-####`	`F-1234`
Requirement	`R-####`	`R-0291`
Change Request	`CR-####`	`CR-8931`

The ID is the durable handle. A SpecURI does not contain a file path. When you click it, SPECLAN looks the ID up in the current project's index and opens whatever file holds it right now. Rename the spec, move it under a different parent, reorganise the whole tree — the link still lands. This is the main reason to link by SpecURI rather than by relative path.

Where the Links Come From

You will mostly encounter SpecURIs rather than write them.

The intended producer is an AI agent generating something from your specs — an interactive clickdummy, a status report, a diagram, a slide deck. As it builds each element, it embeds a back-reference to the Goal, Feature, or Requirement that element realizes. The result is a work product you can audit: every claim in it is one click from the specification it came from.

That is a task an agent does well and a human does badly. An agent already knows which spec it used for each element, and it can read the project's identity out of git. Hand-writing these links is possible — the format is documented at the bottom of this page — but it is not the point of the feature.

Clicking a Link

The first time you follow a SpecURI, VS Code asks:

Allow 'SPECLAN' extension to open this URI?

That prompt comes from VS Code, not from SPECLAN, and it appears once per extension. Tick Do not ask me again for this extension if you follow links regularly.

Then the spec opens:

Goals, Features and Requirements open in the SPECLAN editor and are revealed in the tree, with their parent chain expanded so you can see where the spec sits.
Change Requests open the Change Request's own file.
The tab is persistent, not a preview — it will not be replaced by the next thing you open, because following a link is a deliberate navigation.

Following a link never changes anything. A SpecURI can only navigate. It cannot edit a spec, create one, delete one, or run anything. There is no link you can be sent that modifies your specifications.

Working Across Several Projects

Here is the part worth understanding before it surprises you.

SPECLAN IDs are four random digits, assigned per project. Two different projects can both contain an F-1234, and they will be completely unrelated specs. So a bare ?id=F-1234 link is only unambiguous inside one project.

For that reason a link can carry a workspace key identifying which project it belongs to:

vscode://DigitalDividend.speclan-vscode-extension/open?id=F-1234&ws=github.com%2Facme%2Fspeclan

The key is either the project's git remote reduced to host/owner/repo, or — for a project with no remote — path: followed by its folder path. The git-remote form is the portable one: it is the same for every clone of the repository, on every machine.

Which window answers the link

VS Code hands a vscode:// link to whichever window you used last. Not the window holding the target project — the most recently focused one. If you have SPECLAN open on three projects, the link goes wherever your attention happened to be.

SPECLAN's job is to make sure that never misleads you:

Situation	What happens
The link names your current project (or carries no workspace key) and the spec exists here	The spec opens
The link carries a workspace key for a different project	SPECLAN declines: "This link points at SPECLAN F-1234 in a different project. Open that project, then follow the link again."
The link carries no workspace key and the ID is not in this project	"SPECLAN F-1234 not found in this workspace", with a Go to Spec… button to search what you do have open

The middle row is the one that matters. A workspace-qualified link will never open a same-numbered spec from the wrong project. Being shown the wrong F-1234 with no indication anything went wrong would be far worse than being told to switch projects.

Today, switching is manual. SPECLAN does not open or switch a workspace for you. Focus (or open) the window holding that project, then follow the link again. Automatic routing to the right window is planned but not yet available.

When Nothing Seems to Happen

You clicked a link, VS Code asked permission, you clicked Open — and nothing happened.

Almost always, the window that received the link is running a SPECLAN version from before deep links existed. VS Code decides whether to show the permission prompt by looking at the installed extension, but delivers the link to the running one — and a window that has been open since before the update is still running the old code, which has nothing to receive it.

Fix it with Developer: Reload Window (Cmd/Ctrl+Shift+P) in that window. After any SPECLAN update, windows you already had open keep running the previous version until they are reloaded.

"…is not a valid SPECLAN entity ID." The link is malformed, or names something that is not a Goal, Feature, Requirement, or Change Request. Nothing was opened or changed. If an agent generated it, the ID was likely invented rather than read from the project.

"This link needs a newer version of SPECLAN." The link uses a capability your installed version does not have — for example, a link produced by a newer SPECLAN. Update the extension. Old versions decline politely rather than guessing.

"SPECLAN F-1234 not found in this workspace." The link reached a project that does not contain that ID. Either the wrong window answered — see above — or the spec has been deleted. Use the Go to Spec… button to search the project you are actually in.

Writing a Link Yourself

This section is for agents generating artifacts, and for anyone constructing a link by hand.

vscode://DigitalDividend.speclan-vscode-extension/open?id=<ID>[&ws=<KEY>]

Part	Value
Scheme	`vscode` — use `vscode-insiders` to target VS Code Insiders
Extension identity	`DigitalDividend.speclan-vscode-extension`, always exactly this
Action	`open`
`id`	The entity ID: `G-###`, `F-####`, `R-####`, or `CR-####`. Case is not significant
`ws`	Optional workspace key — see below

To determine the workspace key for a project:

Read its origin remote and reduce it to host/owner/repo, lower-cased and without a .git suffix. git@github.com:Acme/SpecLan.git and https://github.com/acme/speclan both give github.com/acme/speclan.
If the project has no remote, use path: followed by the absolute path of the project folder. This form only works on the machine that folder lives on.

URL-encode every value. A workspace key contains / and often :.

Include ws whenever the artifact might be read alongside another SPECLAN project — which, for anything shared with a colleague, is most of the time. Omit it only for a link that will be followed inside a single known project. Unknown parameters are ignored, so adding your own metadata to a link is harmless.

Artifacts — where generated work products carrying back-reference links usually live
Getting Started — new to SPECLAN and looking for the basics first