sauron-cli 1.1.3 → 1.3.0

package/OpenSpec-main/openspec/changes/archive/2026-05-06-workspace-open-agent-context/design.md

@@ -0,0 +1,266 @@
+## Product Shape
+
+`workspace open` should feel like opening a multi-root working set.
+
+The user model is:
+
+```text
+workspace setup = create the planning home and choose the default opener
+workspace links = the repos or folders OpenSpec can plan across
+workspace open = open that linked working set
+--agent = use a different agent for this one session
+--editor = open the working set as an editor workspace
+```
+
+Repo or folder visibility supports exploration and planning. Opening a workspace gives the agent or editor access to linked paths, and implementation starts through an explicit later workflow.
+
+## Command Surface
+
+Supported v1 forms:
+
+```bash
+openspec workspace open
+openspec workspace open platform
+openspec workspace open --agent codex
+openspec workspace open platform --agent github-copilot
+openspec workspace open --editor
+```
+
+The positional workspace name is the primary explicit selection surface for `open`. User-facing docs should prefer the positional form because a flag such as `--workspace <name>` repeats the noun.
+
+For consistency with other workspace commands and scripts, `workspace open` may also support `--workspace <name>` as an alias for the positional name:
+
+```bash
+openspec workspace open platform
+openspec workspace open --workspace platform
+```
+
+User-facing docs should prefer the positional form. If both are provided and they differ, OpenSpec should fail with a clear conflict error.
+
+`--prepare-only` should not be included. The POC used it to build and print launch surfaces without starting the external tool, but that does not map cleanly to a user-facing intent.
+
+`--json` should not be included in this slice. If a future integration needs a machine-readable resolved-open context, design that as a separate context/query surface instead of overloading the launching command.
+
+`--change` should be deferred. Change-scoped open depends on workspace change planning and target semantics that this slice should not invent.
+
+## Workspace Selection
+
+Selection should follow this order:
+
+1. If a positional workspace name is provided, open that known workspace.
+2. Otherwise, if the command runs from inside a workspace, open the current workspace.
+3. Otherwise, if exactly one workspace is known locally, open it.
+4. Otherwise, if multiple workspaces are known and the terminal is interactive, present a picker.
+5. Otherwise, fail with a clear message that names the known workspaces and asks the user to pass the workspace name.
+
+This keeps the common cases direct while still supporting global use.
+
+## Preferred Opener
+
+Workspace setup should ask which opener the user wants by default. The answer is machine-local state because different machines may have different installed agents or editors.
+
+`workspace open` uses the saved opener when no override is passed.
+
+`--agent <tool>` is a one-session override that leaves the saved preference unchanged. Persisting a changed default should require an explicit preference/config action in a later slice if users need it.
+
+This slice should not add global workspace opener config. OpenSpec already has a global config system, and workspace-level defaults can be added there later if repeated setup makes the local prompt feel noisy.
+
+The local preference should be shaped so a future global default can fit underneath it with smooth migration. The intended precedence is:
+
+```text
+command override
+  -> workspace-local preferred opener
+  -> future global workspace default opener
+  -> interactive prompt or built-in fallback
+```
+
+In future config terms, that global default might look like `workspace.defaultOpener`; this slice documents the precedence for later implementation.
+
+Store the preferred opener as a structured object in `.openspec-workspace/local.yaml`:
+
+```yaml
+preferred_opener:
+  kind: agent
+  id: codex
+```
+
+```yaml
+preferred_opener:
+  kind: editor
+  id: vscode
+```
+
+Allowed initial values:
+
+```text
+kind: agent, id: codex
+kind: agent, id: claude
+kind: agent, id: github-copilot
+kind: editor, id: vscode
+```
+
+The structure keeps the agent/editor distinction clear and leaves room for future opener variants without changing the local-state shape.
+
+Interactive setup should show all supported opener choices, but it should order detected/available openers first. Unavailable choices should still be visible with a note such as `not found on PATH`.
+
+Setup should prefer the plain editor option over an agent when a fallback default is needed for an interactive picker.
+
+Non-interactive setup stores a preferred opener when the caller explicitly passes an opener option. Otherwise, it leaves opener selection for a later interactive `workspace open` prompt or a non-interactive error that explains how to choose an opener.
+
+The setup-time flag should be:
+
+```bash
+openspec workspace setup --no-interactive --name platform --link /repo --opener codex
+openspec workspace setup --no-interactive --name platform --link /repo --opener editor
+```
+
+`--opener <id>` sets the stored preference. It is different from `workspace open --agent <id>` and `workspace open --editor`, which are one-session runtime overrides.
+
+Initial opener detection should stay simple and executable-based:
+
+```text
+VS Code editor: code
+Codex: codex
+Claude: claude
+GitHub Copilot in VS Code: code
+```
+
+Keep initial detection scoped to executable availability in this slice.
+
+Supported agent values for the initial open surface should be limited to tools with a real launch or attachment mechanism:
+
+```text
+claude
+codex
+github-copilot
+```
+
+Plain editor open should be represented by `--editor` with an explicit editor kind.
+
+For this slice, `--editor` means VS Code editor. The `.code-workspace` format is VS Code-specific, so prompts and errors should call this `VS Code editor` rather than implying generic editor support.
+
+`github-copilot` means the VS Code Copilot experience. It should open the maintained `.code-workspace` in VS Code because that is the product surface where this Copilot mode is available.
+
+If OpenSpec later supports a Copilot CLI agent, it should use a distinct value such as `github-copilot-cli` and launch the CLI agent directly. VS Code Copilot and a CLI agent have different opener mechanics, so they should remain distinct opener values.
+
+## Opener Availability
+
+`workspace open` should fail with a clear error when the selected opener is unavailable on the current machine.
+
+The selected opener remains required because it represents user intent, whether it came from local preference or a command-line override.
+
+Errors should name the missing executable or unavailable opener and suggest a concrete next step. For editor-based open, the error should include the `.code-workspace` path so the user can open it manually if needed.
+
+When no preferred opener is stored and no command-line override is provided, `workspace open` should prompt in interactive mode. In non-interactive mode, it should fail and tell the user to pass either an agent override or the editor option.
+
+## Editor Open
+
+`--editor` opens the workspace root plus every linked repo or folder with a valid local path.
+
+For VS Code-style editor support, OpenSpec should create and maintain a `.code-workspace` file as part of the workspace setup/link/relink lifecycle. `workspace open` should launch against existing workspace state.
+
+Expected local workspace shape:
+
+```text
+workspace-root/
+  changes/
+  <workspace-name>.code-workspace
+  .openspec-workspace/
+    workspace.yaml
+    local.yaml
+```
+
+The `.code-workspace` file should include the workspace root and each linked repo or folder with a valid local path. Because linked paths come from machine-local workspace state, OpenSpec-created workspaces should ignore the maintained `.code-workspace` file by default.
+
+The ignore rule should target the specific maintained file and leave other `*.code-workspace` files available for user-authored tracking:
+
+```text
+<workspace-name>.code-workspace
+```
+
+This lets teams add a separate user-authored portable `.code-workspace` later if they have a shared relative-path layout.
+
+`workspace setup`, `workspace link`, and `workspace relink` should all run the same open-surface sync after mutating workspace state. That sync owns:
+
+- `AGENTS.md`
+- `<workspace-name>.code-workspace`
+- workspace ignore rules for machine-local files
+
+Even when a command only changes local state, such as `workspace relink`, it should refresh the full openable workspace surface so user-facing files do not drift.
+
+`--agent github-copilot` may use the same editor workspace mechanics, but it also needs Copilot prompt context. Plain `--editor` keeps a normal editor-workspace intent.
+
+`--agent github-copilot` should still open VS Code. The distinction from `--editor` is intent: `--editor` opens the workspace as a normal editor workspace, while `--agent github-copilot` opens the same editor workspace for the user to work with the VS Code Copilot agent experience.
+
+## Workspace Guidance
+
+Workspace setup should install stable guidance in the workspace root, preferably `AGENTS.md`.
+
+The guidance should explain durable workspace rules:
+
+- the workspace root is the planning home
+- `changes/` contains workspace-level planning
+- linked repos and folders are available for exploration and planning
+- visibility supports exploration and planning
+- implementation edits start after the user explicitly asks for implementation work
+
+The managed `AGENTS.md` text should stay short and durable, covering stable workspace guidance while runtime details remain discoverable from workspace state. A starting shape:
+
+```markdown
+# OpenSpec Workspace Guidance
+
+This directory is an OpenSpec workspace for planning across linked repos or folders.
+
+- Use `changes/` for workspace-level planning.
+- Linked repos and folders are available for exploration and planning.
+- Repo or folder visibility supports exploration and planning.
+- Make implementation edits after the user explicitly asks for implementation work.
+- Treat linked repos and folders as the implementation homes for their owned code.
+- Use OpenSpec workspace commands instead of hand-editing `.openspec-workspace/*.yaml`.
+```
+
+`workspace open` is a launching feature. It should launch the selected opener against existing workspace files.
+
+For Claude and Codex, `workspace open` may still need to pass workspace and linked directory arguments to the agent process at launch because those tools do not consume `.code-workspace` directly. If an opener requires an initial prompt argument, it should be minimal, such as `Open this OpenSpec workspace.`
+
+Dynamic workspace facts should normally be discoverable from existing files:
+
+- linked paths: `.openspec-workspace/local.yaml`
+- stable link names: `.openspec-workspace/workspace.yaml`
+- active workspace changes: `changes/`
+- editor working set: `<workspace-name>.code-workspace`
+
+Report a command file or prompt file path only when the file is actually written and used.
+
+OpenSpec should own a marked workspace-guidance block inside `AGENTS.md`:
+
+```markdown
+<!-- OPENSPEC:WORKSPACE-GUIDANCE:START -->
+# OpenSpec Workspace Guidance
+
+...
+<!-- OPENSPEC:WORKSPACE-GUIDANCE:END -->
+```
+
+`workspace setup`, `workspace link`, and `workspace relink` may rewrite that marked block during open-surface sync. Content outside the marked block should be preserved so users can keep their own workspace notes in the same file.
+
+If `AGENTS.md` is missing, OpenSpec should recreate it. If `AGENTS.md` exists and the markers are absent, OpenSpec should append the managed block while preserving existing content.
+
+## Linked Paths
+
+Root workspace open should attach every linked repo or folder with a valid local path.
+
+Broken links are skipped during workspace open. OpenSpec should surface clear status in human output, with `openspec workspace doctor` as the repair path.
+
+Links with repo-local `openspec/` state absent remain valid for workspace open. Missing repo-local OpenSpec state can matter later for implementation readiness while still allowing visibility for exploration and planning.
+
+## Safety Boundary
+
+The opening prompt or editor guidance should say:
+
+```text
+Linked repos and folders are visible for exploration and planning.
+Make implementation edits after the user explicitly asks for implementation work.
+```
+
+Prompt guidance is acceptable for this slice because apply/verify/archive sit outside the open surface. Later implementation workflows should enforce mode and scope through explicit context providers as well as prompt wording.

package/OpenSpec-main/openspec/changes/archive/2026-05-06-workspace-open-agent-context/proposal.md

@@ -0,0 +1,65 @@
+## Why
+
+After a user creates a workspace and links repos or folders, they need to open that workspace with their preferred agent or editor and have the working set available immediately.
+
+The workspace should provide repo and folder locations, link names, and the context that distinguishes planning from implementation.
+
+## What Changes
+
+Add the workspace-open experience:
+
+```text
+Open this workspace.
+Use my preferred opener by default and honor explicit opener overrides.
+The opener sees the workspace location, linked repos or folders, current changes, and relevant instructions.
+```
+
+Links are the planning context. The local registry serves as a workspace-discovery index for finding known workspaces on the current machine.
+
+Expected user surface:
+
+```bash
+openspec workspace open
+openspec workspace open platform
+openspec workspace open --agent codex
+openspec workspace open platform --agent github-copilot
+openspec workspace open --editor
+```
+
+`workspace open` should open the current workspace when run from inside one, auto-select the only known workspace when run outside a workspace, and present an interactive picker when multiple known workspaces are available. Users can pass a workspace name as the positional argument when they want to choose explicitly.
+
+Workspace setup should ask for and store a preferred opener in machine-local workspace state. `workspace open` uses that preference by default. `--agent <tool>` is a one-session override that leaves the saved preference unchanged.
+
+`--editor` opens the workspace as an editor workspace. This is related to, but distinct from, `--agent github-copilot`: GitHub Copilot needs editor workspace support plus agent prompt context, while plain editor open should focus on opening the linked working set.
+
+Workspace guidance should live in durable workspace files where possible:
+
+- stable behavior belongs in workspace-level `AGENTS.md`
+- opener-specific launch prompts stay minimal when required
+- linked repos or folders are visible for exploration and planning before a change exists
+
+This slice supports root workspace launching through the documented opener forms. Public preview (`--prepare-only`) and machine-readable context (`--json`) surfaces belong in a future context/query design if a clear user need appears.
+
+This slice focuses on root workspace open behavior. Change-scoped sessions need the target model from workspace change planning before they can be specified cleanly.
+
+Planning dependency:
+
+- Depends on `workspace-create-and-register-repos`.
+
+## Capabilities
+
+### New Capabilities
+
+- `workspace-open`: Opens a workspace through a preferred agent or VS Code editor with linked repos or folders available for exploration and planning.
+
+### Modified Capabilities
+
+- `workspace-foundation`: Extends machine-local workspace state and setup/link/relink behavior with a preferred opener and maintained openable workspace surface.
+
+## Impact
+
+- `openspec workspace open`
+- Workspace setup preferred opener prompt and local preference storage.
+- Workspace prompt, editor workspace, and agent-launch context.
+- Generated or committed agent guidance for workspace mode.
+- Tests for opening inside a workspace, auto-selecting one known workspace, picking among multiple known workspaces, opening by workspace name, one-session agent overrides, and editor open.

package/OpenSpec-main/openspec/changes/archive/2026-05-06-workspace-open-agent-context/specs/workspace-foundation/spec.md

@@ -0,0 +1,76 @@
+## ADDED Requirements
+
+### Requirement: Workspace Preferred Opener State
+OpenSpec SHALL store a workspace's preferred opener in machine-local workspace state when the user explicitly chooses one.
+
+#### Scenario: Recording an interactive setup opener choice
+- **WHEN** an interactive user chooses a preferred opener during `openspec workspace setup`
+- **THEN** OpenSpec SHALL record the opener in `.openspec-workspace/local.yaml`
+- **AND** the stored value SHALL use a structured `preferred_opener` object with `kind` and `id`
+
+#### Scenario: Recording a non-interactive setup opener choice
+- **WHEN** a non-interactive user runs `openspec workspace setup --no-interactive --opener codex`
+- **THEN** OpenSpec SHALL record `preferred_opener.kind` as `agent`
+- **AND** it SHALL record `preferred_opener.id` as `codex`
+
+#### Scenario: Leaving opener unset during non-interactive setup
+- **WHEN** a non-interactive user runs `openspec workspace setup --no-interactive` with opener selection omitted
+- **THEN** OpenSpec SHALL leave the workspace preferred opener unset
+- **AND** the unset state SHALL allow `workspace open` to prompt later
+
+#### Scenario: Supported preferred opener values
+- **WHEN** OpenSpec accepts a preferred opener value
+- **THEN** it SHALL accept `codex`, `claude`, `github-copilot`, and `editor`
+- **AND** it SHALL map `editor` to `kind: editor` and `id: vscode`
+- **AND** it SHALL map agent values to `kind: agent` and the matching agent `id`
+
+#### Scenario: Ordering setup opener choices
+- **WHEN** interactive setup displays opener choices
+- **THEN** OpenSpec SHALL show all supported openers
+- **AND** it SHALL order openers with detected executables before unavailable openers
+- **AND** unavailable openers SHALL remain visible with an availability note
+
+### Requirement: Maintained Workspace Open Surface
+OpenSpec SHALL maintain files that make a workspace directly openable after setup and link changes.
+
+#### Scenario: Creating the open surface during setup
+- **WHEN** `openspec workspace setup` creates a workspace
+- **THEN** OpenSpec SHALL create or refresh `AGENTS.md`
+- **AND** it SHALL create or refresh `<workspace-name>.code-workspace`
+- **AND** it SHALL create or refresh workspace ignore rules for machine-local open files
+
+#### Scenario: Refreshing the open surface after linking
+- **WHEN** `openspec workspace link` succeeds
+- **THEN** OpenSpec SHALL refresh `AGENTS.md`
+- **AND** it SHALL refresh `<workspace-name>.code-workspace`
+- **AND** it SHALL refresh workspace ignore rules for machine-local open files
+
+#### Scenario: Refreshing the open surface after relinking
+- **WHEN** `openspec workspace relink` succeeds
+- **THEN** OpenSpec SHALL refresh `AGENTS.md`
+- **AND** it SHALL refresh `<workspace-name>.code-workspace`
+- **AND** it SHALL refresh workspace ignore rules for machine-local open files
+
+#### Scenario: Building the VS Code workspace file
+- **WHEN** OpenSpec refreshes `<workspace-name>.code-workspace`
+- **THEN** the file SHALL include the workspace root
+- **AND** the workspace root folder entry SHALL use the root path without a synthetic display name
+- **AND** it SHALL include every linked repo or folder with a valid local path
+- **AND** it SHALL omit linked repos or folders whose local paths are missing or invalid
+
+#### Scenario: Ignoring the maintained VS Code workspace file
+- **WHEN** OpenSpec refreshes workspace ignore rules
+- **THEN** it SHALL ignore the specific maintained `<workspace-name>.code-workspace` file
+- **AND** user-authored `*.code-workspace` files SHALL remain eligible for tracking
+
+#### Scenario: Preserving user-authored AGENTS content
+- **GIVEN** `AGENTS.md` contains content outside the OpenSpec workspace guidance markers
+- **WHEN** OpenSpec refreshes workspace guidance
+- **THEN** it SHALL replace only the marked OpenSpec workspace guidance block
+- **AND** it SHALL preserve content outside the markers
+
+#### Scenario: Appending AGENTS guidance when markers are missing
+- **GIVEN** `AGENTS.md` exists and OpenSpec workspace guidance markers are absent
+- **WHEN** OpenSpec refreshes workspace guidance
+- **THEN** it SHALL append the marked OpenSpec workspace guidance block
+- **AND** it SHALL preserve the existing file content

package/OpenSpec-main/openspec/changes/archive/2026-05-06-workspace-open-agent-context/specs/workspace-open/spec.md

@@ -0,0 +1,199 @@
+## ADDED Requirements
+
+### Requirement: Workspace Open Command
+OpenSpec SHALL provide a `workspace open` command that opens an OpenSpec workspace working set through an agent or VS Code editor.
+
+#### Scenario: Opening the current workspace
+- **GIVEN** the command runs from inside an OpenSpec workspace
+- **WHEN** the user runs `openspec workspace open`
+- **THEN** OpenSpec SHALL open that current workspace
+- **AND** it SHALL use the selected opener for that workspace
+
+#### Scenario: Opening a named workspace
+- **GIVEN** a workspace named `platform` is known locally
+- **WHEN** the user runs `openspec workspace open platform`
+- **THEN** OpenSpec SHALL open the `platform` workspace
+
+#### Scenario: Opening a named workspace with the selection flag
+- **GIVEN** a workspace named `platform` is known locally
+- **WHEN** the user runs `openspec workspace open --workspace platform`
+- **THEN** OpenSpec SHALL open the `platform` workspace
+
+#### Scenario: Conflicting workspace selectors
+- **GIVEN** workspaces named `platform` and `checkout` are known locally
+- **WHEN** the user runs `openspec workspace open platform --workspace checkout`
+- **THEN** OpenSpec SHALL fail with a clear conflict error
+- **AND** the error SHALL name both conflicting selectors
+
+#### Scenario: Handling unsupported preview and JSON flags
+- **WHEN** the user runs `openspec workspace open` with `--prepare-only` or `--json`
+- **THEN** OpenSpec SHALL fail with a clear error that the root workspace open surface supports launching through a selected opener
+- **AND** the error SHALL direct preview or machine-readable context needs to a future context/query surface
+
+#### Scenario: Handling change-scoped open before workspace planning
+- **WHEN** the user runs `openspec workspace open --change <id>`
+- **THEN** OpenSpec SHALL fail with a clear error that this slice supports root workspace open
+- **AND** the error SHALL direct change-scoped open behavior to future workspace change planning
+
+### Requirement: Workspace Selection For Open
+OpenSpec SHALL resolve the workspace to open using current workspace context, local registry state, and interactive selection.
+
+#### Scenario: Current workspace wins
+- **GIVEN** the command runs from a workspace folder or one of its subdirectories
+- **AND** no workspace name is provided
+- **WHEN** the user runs `openspec workspace open`
+- **THEN** OpenSpec SHALL open the current workspace
+
+#### Scenario: Auto-selecting the only known workspace
+- **GIVEN** the command runs outside a workspace
+- **AND** exactly one workspace is known locally
+- **WHEN** the user runs `openspec workspace open`
+- **THEN** OpenSpec SHALL open that known workspace directly
+
+#### Scenario: Picking from multiple workspaces
+- **GIVEN** the command runs outside a workspace
+- **AND** multiple workspaces are known locally
+- **AND** the terminal is interactive
+- **WHEN** the user runs `openspec workspace open`
+- **THEN** OpenSpec SHALL present a picker with workspace names and locations
+- **AND** it SHALL open the workspace the user selects
+
+#### Scenario: Non-interactive ambiguous selection
+- **GIVEN** the command runs outside a workspace
+- **AND** multiple workspaces are known locally
+- **AND** the terminal is non-interactive
+- **WHEN** the user runs `openspec workspace open`
+- **THEN** OpenSpec SHALL fail with a clear message listing the known workspace names
+- **AND** it SHALL ask the user to pass a workspace name
+
+#### Scenario: No known workspace
+- **GIVEN** the command runs outside a workspace
+- **AND** no workspaces are known locally
+- **WHEN** the user runs `openspec workspace open`
+- **THEN** OpenSpec SHALL fail with a clear message
+- **AND** it SHALL suggest running `openspec workspace setup`
+
+### Requirement: Opener Resolution
+OpenSpec SHALL resolve the opener from command overrides, workspace-local preference, or an interactive prompt.
+
+#### Scenario: Conflicting opener overrides
+- **WHEN** the user runs `openspec workspace open --agent codex --editor`
+- **THEN** OpenSpec SHALL fail with a clear conflict error naming `--agent` and `--editor`
+- **AND** it SHALL avoid launching any opener
+- **AND** it SHALL leave the stored preferred opener unchanged
+
+#### Scenario: Using the stored preferred opener
+- **GIVEN** the workspace has a machine-local preferred opener
+- **WHEN** the user runs `openspec workspace open` using default opener resolution
+- **THEN** OpenSpec SHALL use the stored preferred opener
+
+#### Scenario: Overriding with an agent for one session
+- **GIVEN** the workspace has a stored preferred opener
+- **WHEN** the user runs `openspec workspace open --agent codex`
+- **THEN** OpenSpec SHALL use Codex for that open command
+- **AND** it SHALL leave the stored preferred opener unchanged
+
+#### Scenario: Overriding with VS Code editor for one session
+- **GIVEN** the workspace has a stored preferred opener
+- **WHEN** the user runs `openspec workspace open --editor`
+- **THEN** OpenSpec SHALL open the workspace in VS Code editor mode
+- **AND** it SHALL leave the stored preferred opener unchanged
+
+#### Scenario: Prompting when no opener is stored
+- **GIVEN** the workspace has no stored preferred opener
+- **AND** the terminal is interactive
+- **WHEN** the user runs `openspec workspace open` using default opener resolution
+- **THEN** OpenSpec SHALL prompt the user to choose an opener
+- **AND** it SHALL only offer openers with detected executables
+
+#### Scenario: Failing when no opener can be prompted
+- **GIVEN** the workspace has no stored preferred opener
+- **AND** the terminal is interactive
+- **AND** no supported opener executable is available on `PATH`
+- **WHEN** the user runs `openspec workspace open` using default opener resolution
+- **THEN** OpenSpec SHALL fail with a clear message that no supported opener is available
+- **AND** it SHALL avoid prompting with unlaunchable choices
+
+#### Scenario: Failing when no opener is stored in non-interactive mode
+- **GIVEN** the workspace has no stored preferred opener
+- **AND** the terminal is non-interactive
+- **WHEN** the user runs `openspec workspace open` using default opener resolution
+- **THEN** OpenSpec SHALL fail with a clear message
+- **AND** it SHALL ask the user to pass `--agent <tool>` or `--editor`
+
+### Requirement: Opener Launch Behavior
+OpenSpec SHALL launch the selected opener using existing workspace files and linked path state.
+
+#### Scenario: Opening VS Code editor
+- **GIVEN** the user selected the VS Code editor opener
+- **WHEN** `code` is available on `PATH`
+- **THEN** OpenSpec SHALL open the workspace's maintained `.code-workspace` file with VS Code
+
+#### Scenario: Opening GitHub Copilot in VS Code
+- **GIVEN** the user selected `--agent github-copilot`
+- **WHEN** `code` is available on `PATH`
+- **THEN** OpenSpec SHALL open the workspace's maintained `.code-workspace` file with VS Code
+- **AND** it SHALL treat this as the VS Code Copilot experience
+
+#### Scenario: Opening Codex
+- **GIVEN** the user selected `--agent codex`
+- **WHEN** `codex` is available on `PATH`
+- **THEN** OpenSpec SHALL launch Codex from the workspace root
+- **AND** it SHALL attach every linked repo or folder with a valid local path using Codex's supported directory attachment mechanism
+
+#### Scenario: Opening Claude
+- **GIVEN** the user selected `--agent claude`
+- **WHEN** `claude` is available on `PATH`
+- **THEN** OpenSpec SHALL launch Claude from the workspace root
+- **AND** it SHALL attach every linked repo or folder with a valid local path using Claude's supported directory attachment mechanism
+
+#### Scenario: Missing opener executable
+- **GIVEN** the selected opener requires an executable that is not available on `PATH`
+- **WHEN** the user runs `openspec workspace open`
+- **THEN** OpenSpec SHALL fail with a clear error naming the missing executable
+- **AND** it SHALL keep the selected opener as the required opener
+
+#### Scenario: Missing VS Code executable
+- **GIVEN** the selected opener is VS Code editor or GitHub Copilot in VS Code
+- **AND** `code` is not available on `PATH`
+- **WHEN** the user runs `openspec workspace open`
+- **THEN** OpenSpec SHALL fail with a clear error naming `code`
+- **AND** it SHALL include the maintained `.code-workspace` path so the user can open it manually
+
+### Requirement: Linked Working Set Visibility
+OpenSpec SHALL make linked repos and folders visible for workspace exploration and planning before change creation.
+
+#### Scenario: Attaching valid linked paths
+- **GIVEN** a workspace has linked repos or folders with valid local paths
+- **WHEN** the user opens the workspace through an opener that supports linked directory attachment
+- **THEN** OpenSpec SHALL include every valid linked path in the opened working set
+- **AND** it SHALL support opening before a workspace change exists
+
+#### Scenario: Skipping broken linked paths
+- **GIVEN** a workspace has at least one linked path that is missing or not recorded locally
+- **WHEN** the user opens the workspace
+- **THEN** OpenSpec SHALL skip the broken linked path
+- **AND** it SHALL report that the path was skipped with `openspec workspace doctor` as the repair path
+- **AND** it SHALL continue opening the workspace when the selected opener itself is available
+
+#### Scenario: Opening links with repo-local OpenSpec state absent
+- **GIVEN** a linked repo or folder has a valid local path and repo-local `openspec/` state is absent
+- **WHEN** the user opens the workspace
+- **THEN** OpenSpec SHALL include that link when its local path is valid
+- **AND** it SHALL treat missing repo-local OpenSpec state as an implementation-readiness concern for later workflows while continuing open
+
+### Requirement: Workspace Open Guidance
+OpenSpec SHALL use durable workspace guidance as the primary context source for root workspace open.
+
+#### Scenario: Launching with existing workspace guidance
+- **GIVEN** the workspace has OpenSpec-managed guidance in `AGENTS.md`
+- **WHEN** the user opens the workspace
+- **THEN** OpenSpec SHALL refresh the maintained `.code-workspace` from current linked path state
+- **AND** it SHALL launch the selected opener against refreshed workspace files
+- **AND** it SHALL use durable workspace files as the primary workspace-open artifact
+
+#### Scenario: Minimal required launch prompt
+- **GIVEN** an opener requires an initial prompt argument
+- **WHEN** OpenSpec launches that opener
+- **THEN** OpenSpec SHALL use a minimal prompt such as `Open this OpenSpec workspace.`
+- **AND** durable workspace rules SHALL remain in workspace files