Workspace cheat sheet

The three scopes
Settings
Folder pick
SDD placement
Run history
Tasks tree
Unsaved workspaces

The three scopes

Scope	Path	Exists when
Folder	`<repo>/.local-workflows/`	always
Workspace	`<workspaceRoot>/.local-workflows/`	a `.code-workspace` is open
Profile	`~/.local-workflows/`	always

Precedence: folder > workspace > profile. A wider copy of the same id / name: / id@version is hidden, not reported.

All three contribute tasks.yml, workflows/*.yml, templates/*/template.yml and plugins/.

Settings

Both live in the settings block of the .code-workspace file. Both are ignored when a plain folder is open. Empty string means unset.

Key	Type	Default
`localWorkflows.workspaceRoot`	string	folder holding the `.code-workspace`
`localWorkflows.specRoot`	string	`<workspaceRoot>/.local-workflows/specs`

Relative values resolve against the folder holding the .code-workspace. Absolute values are used as-is.

{
  "folders": [
    { "path": "../repos/api" },
    { "path": "../repos/web" }
  ],
  "settings": {
    "localWorkflows.workspaceRoot": "D:\\Work\\team-workspace",
    "localWorkflows.specRoot": "D:\\Work\\team-specs"
  }
}

Folder pick


Asked for	workspace- and profile-level tasks and workflows
Not asked for	folder-level anything; any plain-folder window
Trigger	the play icon on the row, and Run inside the panel
Frequency	every run, including with one candidate
Stored	nowhere
Candidates	the `.code-workspace` folders, minus `workspaceRoot`
Sets	`${{ root }}` for that run
Dismissed	nothing runs

Asked again on every run from an already-open panel: a session left open is not aimed at anything by the time it is used again.

SDD placement

`localWorkflows.specRoot`	Behaviour
Set	used
Unset, `.code-workspace` open	`.local-workflows/specs` beside the `.code-workspace` file
Plain folder	setting ignored; `config.yml` decides

Never asked, never written back.

With a .code-workspace open, specRoot: in a repository’s config.yml is ignored, and custom styles are read from the workspace’s .local-workflows/styles/ rather than from each repository. style:, source:, checkpoints: and ai: still apply, read from the workspace.

Run history

Window	`~/.local-workflows/db/<key>/run.db` keyed on
Plain folder	that folder’s path
`.code-workspace`	the `.code-workspace` file’s path

Reordering folders: does not move history. Renaming or moving the workspace does.

Tasks tree

Scopes with tasks	Layout
One	flat rows
Two or three	Folder / Workspace / Profile headings, narrowest first

Unsaved workspaces

A multi-root workspace assembled in the window but never saved has no file on disk. It is treated as a plain folder — no workspace scope, no folder pick, no settings — until you save it.