sauron-cli 1.3.0 → 1.4.0

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

@@ -1,266 +0,0 @@
-## 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

@@ -1,65 +0,0 @@
-## 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

@@ -1,76 +0,0 @@
-## 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

@@ -1,199 +0,0 @@
-## 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