From 1395531aa933f099a7f92bdbe1d869cd3c29112a Mon Sep 17 00:00:00 2001 From: oon arfiandwi Date: Mon, 22 Jun 2026 22:56:07 +0700 Subject: [PATCH] chore: archive sync-upstream-v1-4-1; merge deltas into main specs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ran `openspec archive sync-upstream-v1-4-1`: moved the change to openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/ and merged its delta specs into openspec/specs/ (+15 requirements, ~4 modified across 7 capabilities; new main specs: context-store, initiatives, workspace). The v0.2.0 archive re-validation guard ran clean — all merged specs are valid. validate --all: 10 passed, 0 failed. --- .../.openspec.yaml | 0 .../design.md | 0 .../proposal.md | 0 .../specs/ai-tool-integration/spec.md | 0 .../specs/cli-commands/spec.md | 0 .../specs/config-management/spec.md | 0 .../specs/context-store/spec.md | 0 .../specs/initiatives/spec.md | 0 .../specs/shell-completion/spec.md | 0 .../specs/spec-parser/spec.md | 0 .../specs/telemetry/spec.md | 0 .../specs/workspace/spec.md | 0 .../2026-06-22-sync-upstream-v1-4-1}/tasks.md | 0 openspec/specs/ai-tool-integration/spec.md | 16 ++++-- openspec/specs/cli-commands/spec.md | 39 ++++++++++++- openspec/specs/config-management/spec.md | 31 +++++++++- openspec/specs/context-store/spec.md | 37 ++++++++++++ openspec/specs/initiatives/spec.md | 30 ++++++++++ openspec/specs/shell-completion/spec.md | 16 ++++-- openspec/specs/spec-parser/spec.md | 15 +++-- openspec/specs/telemetry/spec.md | 15 ++++- openspec/specs/workspace/spec.md | 57 +++++++++++++++++++ 22 files changed, 237 insertions(+), 19 deletions(-) rename openspec/changes/{sync-upstream-v1-4-1 => archive/2026-06-22-sync-upstream-v1-4-1}/.openspec.yaml (100%) rename openspec/changes/{sync-upstream-v1-4-1 => archive/2026-06-22-sync-upstream-v1-4-1}/design.md (100%) rename openspec/changes/{sync-upstream-v1-4-1 => archive/2026-06-22-sync-upstream-v1-4-1}/proposal.md (100%) rename openspec/changes/{sync-upstream-v1-4-1 => archive/2026-06-22-sync-upstream-v1-4-1}/specs/ai-tool-integration/spec.md (100%) rename openspec/changes/{sync-upstream-v1-4-1 => archive/2026-06-22-sync-upstream-v1-4-1}/specs/cli-commands/spec.md (100%) rename openspec/changes/{sync-upstream-v1-4-1 => archive/2026-06-22-sync-upstream-v1-4-1}/specs/config-management/spec.md (100%) rename openspec/changes/{sync-upstream-v1-4-1 => archive/2026-06-22-sync-upstream-v1-4-1}/specs/context-store/spec.md (100%) rename openspec/changes/{sync-upstream-v1-4-1 => archive/2026-06-22-sync-upstream-v1-4-1}/specs/initiatives/spec.md (100%) rename openspec/changes/{sync-upstream-v1-4-1 => archive/2026-06-22-sync-upstream-v1-4-1}/specs/shell-completion/spec.md (100%) rename openspec/changes/{sync-upstream-v1-4-1 => archive/2026-06-22-sync-upstream-v1-4-1}/specs/spec-parser/spec.md (100%) rename openspec/changes/{sync-upstream-v1-4-1 => archive/2026-06-22-sync-upstream-v1-4-1}/specs/telemetry/spec.md (100%) rename openspec/changes/{sync-upstream-v1-4-1 => archive/2026-06-22-sync-upstream-v1-4-1}/specs/workspace/spec.md (100%) rename openspec/changes/{sync-upstream-v1-4-1 => archive/2026-06-22-sync-upstream-v1-4-1}/tasks.md (100%) create mode 100644 openspec/specs/context-store/spec.md create mode 100644 openspec/specs/initiatives/spec.md create mode 100644 openspec/specs/workspace/spec.md diff --git a/openspec/changes/sync-upstream-v1-4-1/.openspec.yaml b/openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/.openspec.yaml similarity index 100% rename from openspec/changes/sync-upstream-v1-4-1/.openspec.yaml rename to openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/.openspec.yaml diff --git a/openspec/changes/sync-upstream-v1-4-1/design.md b/openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/design.md similarity index 100% rename from openspec/changes/sync-upstream-v1-4-1/design.md rename to openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/design.md diff --git a/openspec/changes/sync-upstream-v1-4-1/proposal.md b/openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/proposal.md similarity index 100% rename from openspec/changes/sync-upstream-v1-4-1/proposal.md rename to openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/proposal.md diff --git a/openspec/changes/sync-upstream-v1-4-1/specs/ai-tool-integration/spec.md b/openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/specs/ai-tool-integration/spec.md similarity index 100% rename from openspec/changes/sync-upstream-v1-4-1/specs/ai-tool-integration/spec.md rename to openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/specs/ai-tool-integration/spec.md diff --git a/openspec/changes/sync-upstream-v1-4-1/specs/cli-commands/spec.md b/openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/specs/cli-commands/spec.md similarity index 100% rename from openspec/changes/sync-upstream-v1-4-1/specs/cli-commands/spec.md rename to openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/specs/cli-commands/spec.md diff --git a/openspec/changes/sync-upstream-v1-4-1/specs/config-management/spec.md b/openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/specs/config-management/spec.md similarity index 100% rename from openspec/changes/sync-upstream-v1-4-1/specs/config-management/spec.md rename to openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/specs/config-management/spec.md diff --git a/openspec/changes/sync-upstream-v1-4-1/specs/context-store/spec.md b/openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/specs/context-store/spec.md similarity index 100% rename from openspec/changes/sync-upstream-v1-4-1/specs/context-store/spec.md rename to openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/specs/context-store/spec.md diff --git a/openspec/changes/sync-upstream-v1-4-1/specs/initiatives/spec.md b/openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/specs/initiatives/spec.md similarity index 100% rename from openspec/changes/sync-upstream-v1-4-1/specs/initiatives/spec.md rename to openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/specs/initiatives/spec.md diff --git a/openspec/changes/sync-upstream-v1-4-1/specs/shell-completion/spec.md b/openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/specs/shell-completion/spec.md similarity index 100% rename from openspec/changes/sync-upstream-v1-4-1/specs/shell-completion/spec.md rename to openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/specs/shell-completion/spec.md diff --git a/openspec/changes/sync-upstream-v1-4-1/specs/spec-parser/spec.md b/openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/specs/spec-parser/spec.md similarity index 100% rename from openspec/changes/sync-upstream-v1-4-1/specs/spec-parser/spec.md rename to openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/specs/spec-parser/spec.md diff --git a/openspec/changes/sync-upstream-v1-4-1/specs/telemetry/spec.md b/openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/specs/telemetry/spec.md similarity index 100% rename from openspec/changes/sync-upstream-v1-4-1/specs/telemetry/spec.md rename to openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/specs/telemetry/spec.md diff --git a/openspec/changes/sync-upstream-v1-4-1/specs/workspace/spec.md b/openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/specs/workspace/spec.md similarity index 100% rename from openspec/changes/sync-upstream-v1-4-1/specs/workspace/spec.md rename to openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/specs/workspace/spec.md diff --git a/openspec/changes/sync-upstream-v1-4-1/tasks.md b/openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/tasks.md similarity index 100% rename from openspec/changes/sync-upstream-v1-4-1/tasks.md rename to openspec/changes/archive/2026-06-22-sync-upstream-v1-4-1/tasks.md diff --git a/openspec/specs/ai-tool-integration/spec.md b/openspec/specs/ai-tool-integration/spec.md index ed7a3b2..a91e8e1 100644 --- a/openspec/specs/ai-tool-integration/spec.md +++ b/openspec/specs/ai-tool-integration/spec.md @@ -1,16 +1,24 @@ ## Purpose AI tool integration for OpenSpec. Generates skill files and slash commands for AI coding assistants. - ## Requirements - ### Requirement: AI Tool Detection -The system SHALL support configuration for multiple AI coding tools. +The system SHALL support configuration for multiple AI coding tools, and SHALL auto-detect tools present in a project. Detection MAY use explicit detection paths (files or directories) instead of the tool's default skills directory. #### Scenario: List supported tools - **WHEN** system initializes - **THEN** system supports at minimum: opencode, claude, cursor, windsurf, cline, continue, amazon-q +- **AND** system supports the additional tools: bob, forgecode, junie, kimi, lingma, vibe + +#### Scenario: Detect tool by skills directory +- **WHEN** a project contains a tool's skills directory (e.g. `.claude/`) +- **THEN** system marks that tool as detected + +#### Scenario: Detect GitHub Copilot via specific paths +- **WHEN** a project contains only a bare `.github/` directory with none of Copilot's detection paths (e.g. `.github/copilot-instructions.md`, `.github/prompts`, `.github/agents`) +- **THEN** system does NOT falsely detect GitHub Copilot +- **AND** system detects GitHub Copilot only when at least one configured detection path exists ### Requirement: Skill Generation @@ -42,4 +50,4 @@ The system SHALL generate files in tool-specific directories. #### Scenario: Generate for multiple tools - **WHEN** user initializes with `--tools claude,cursor` - **THEN** system creates `.claude/` and `.cursor/` directories -- **AND** each contains tool-appropriate configuration files +- **AND** each contains tool-appropriate configuration files \ No newline at end of file diff --git a/openspec/specs/cli-commands/spec.md b/openspec/specs/cli-commands/spec.md index cccc5d8..7097390 100644 --- a/openspec/specs/cli-commands/spec.md +++ b/openspec/specs/cli-commands/spec.md @@ -1,9 +1,7 @@ ## Purpose CLI commands for the OpenSpec Rust binary. Provides all commands for initializing projects, managing changes, viewing status, and archiving completed work. - ## Requirements - ### Requirement: CLI Init Command The system SHALL provide an `openspec init [path]` command that initializes OpenSpec in a project directory. @@ -83,13 +81,18 @@ The system SHALL provide an `openspec show [item-name]` command that displays ch ### Requirement: CLI Validate Command -The system SHALL provide an `openspec validate [item-name]` command that validates changes and specs. +The system SHALL provide an `openspec validate [item-name]` command that validates changes and specs, and SHALL emit actionable hints for common authoring mistakes. #### Scenario: Validate all changes - **WHEN** user runs `openspec validate --all` - **THEN** system validates all changes and specs - **AND** system reports validation errors if any +#### Scenario: Hint when SHALL/MUST only in header +- **WHEN** a requirement has SHALL/MUST only in its `### Requirement:` header line and not in the requirement body +- **THEN** system reports a hint to move the keyword onto the requirement body line +- **AND** the hint is more specific than the generic missing-normative-keyword error + ### Requirement: CLI Archive Command The system SHALL provide an `openspec archive [change-name]` command that archives a completed change. @@ -134,3 +137,33 @@ The system SHALL provide `--version` and `--help` flags for all commands. #### Scenario: Show help - **WHEN** user runs `openspec --help` - **THEN** system displays available commands and options + +### Requirement: JSON Output Stream Separation + +The system SHALL keep `--json` output parseable by AI agents that combine stdout and stderr. + +#### Scenario: No spinner leakage with --json +- **WHEN** a command is run with `--json` +- **THEN** spinner/progress text is suppressed and does not leak into stderr +- **AND** the JSON payload remains the only structured output + +### Requirement: CLI Initiative Command + +The system SHALL provide an `openspec initiative` command group for managing initiatives that group related changes. + +#### Scenario: Initiative command available +- **WHEN** user runs `openspec initiative --help` +- **THEN** system lists initiative subcommands + +### Requirement: CLI Workspace Command + +The system SHALL provide an `openspec workspace` command group for beta multi-project workspace planning. + +#### Scenario: Workspace command available +- **WHEN** user runs `openspec workspace --help` +- **THEN** system lists workspace subcommands (e.g. register, open, view) + +#### Scenario: Update does not route into workspace +- **WHEN** user runs top-level `openspec update` in a project that is not a workspace root +- **THEN** system performs a normal project update and does NOT route into workspace updates +- **AND** a foreign root `workspace.yaml` (e.g. from another tool) does not block normal updates \ No newline at end of file diff --git a/openspec/specs/config-management/spec.md b/openspec/specs/config-management/spec.md index e882b26..55c93dc 100644 --- a/openspec/specs/config-management/spec.md +++ b/openspec/specs/config-management/spec.md @@ -1,9 +1,7 @@ ## Purpose Configuration management for OpenSpec. Handles project-level and global configuration with XDG compliance. - ## Requirements - ### Requirement: Project Configuration The system SHALL support project-level configuration via `openspec/config.yaml`. @@ -44,3 +42,32 @@ The system SHALL support environment variable overrides for configuration. #### Scenario: Override telemetry via env - **WHEN** `OPENSPEC_TELEMETRY=0` is set - **THEN** system disables telemetry regardless of config file + +### Requirement: Global Directory Resolution Parity + +The system SHALL resolve the global config and data directories to the same locations as the upstream TypeScript CLI, so a context store / global config is shared between the two implementations. + +#### Scenario: XDG override honored on all platforms +- **WHEN** `XDG_CONFIG_HOME` or `XDG_DATA_HOME` is set +- **THEN** the global config/data dir is `$XDG_*_HOME/openspec` regardless of platform + +#### Scenario: macOS uses dotfile paths, not Library +- **WHEN** no XDG override is set on macOS +- **THEN** the global config dir is `~/.config/openspec` and the data dir is `~/.local/share/openspec` (matching upstream, not `~/Library/Application Support`) +- **AND** an existing legacy macOS global config is migrated to the new location on a best-effort basis + +### Requirement: Foreign Workspace File Isolation + +The system SHALL ignore foreign root `workspace.yaml` files that do not belong to OpenSpec, so unrelated projects continue updating normally. + +#### Scenario: Ignore non-OpenSpec workspace.yaml +- **WHEN** a project root contains a `workspace.yaml` written by another tool +- **THEN** `openspec update` treats the project as a normal project and ignores that file + +### Requirement: Default Core Profile Sync Workflow + +The system SHALL include the `sync` workflow in the default `core` profile so new installations generate `/opsx:sync` skills and commands by default. + +#### Scenario: Core profile includes sync +- **WHEN** user initializes a project with the default `core` profile +- **THEN** system generates the `sync` workflow skill and command alongside the other core workflows \ No newline at end of file diff --git a/openspec/specs/context-store/spec.md b/openspec/specs/context-store/spec.md new file mode 100644 index 0000000..b8f5e79 --- /dev/null +++ b/openspec/specs/context-store/spec.md @@ -0,0 +1,37 @@ +# context-store Specification + +## Purpose +TBD - created by archiving change sync-upstream-v1-4-1. Update Purpose after archive. +## Requirements +### Requirement: Context Store Setup and Registration + +The system SHALL provide an `openspec context-store` command group to set up and register local context stores that back workspace and initiative data. + +#### Scenario: Set up a context store +- **WHEN** user runs `openspec context-store setup [id]` +- **THEN** system creates and registers a local context store +- **AND** system supports `--path ` (defaults to OpenSpec-managed local data) and optional `--init-git` + +#### Scenario: Register an existing store +- **WHEN** user runs `openspec context-store register [path] --id ` +- **THEN** system registers the existing local context store, defaulting the id from metadata or folder name + +### Requirement: Context Store Lifecycle + +The system SHALL allow listing, diagnosing, and removing context-store registrations. + +#### Scenario: List registered stores +- **WHEN** user runs `openspec context-store list` +- **THEN** system lists locally registered context stores (with `--json` support) + +#### Scenario: Diagnose a store +- **WHEN** user runs `openspec context-store doctor [id]` +- **THEN** system checks the registration and metadata of the store + +#### Scenario: Unregister without deleting +- **WHEN** user runs `openspec context-store unregister ` +- **THEN** system forgets the registration without deleting files + +#### Scenario: Remove and delete +- **WHEN** user runs `openspec context-store remove --yes` +- **THEN** system forgets the registration and deletes its local folder \ No newline at end of file diff --git a/openspec/specs/initiatives/spec.md b/openspec/specs/initiatives/spec.md new file mode 100644 index 0000000..f898dc5 --- /dev/null +++ b/openspec/specs/initiatives/spec.md @@ -0,0 +1,30 @@ +# initiatives Specification + +## Purpose +TBD - created by archiving change sync-upstream-v1-4-1. Update Purpose after archive. +## Requirements +### Requirement: Initiative Change Linking + +The system SHALL allow linking a repo-local change to an initiative. + +#### Scenario: Link a change to an initiative +- **WHEN** a change is created with `--initiative ` (optionally `--store ` or `--store-path `) +- **THEN** system records the link between the repo-local change and the initiative + +### Requirement: Initiative Management + +The system SHALL provide an `openspec initiative` command group to create and list coordinated initiatives that live inside a context store and group related changes. + +#### Scenario: Create an initiative +- **WHEN** user runs `openspec initiative create [id] --title --summary <summary>` +- **THEN** system creates an initiative in the resolved context store +- **AND** system supports selecting the store via `--store <id>` or `--store-path <path>` + +#### Scenario: Show an initiative +- **WHEN** user runs `openspec initiative show <id>` +- **THEN** system reports where the initiative lives and how to read it + +#### Scenario: List initiatives +- **WHEN** user runs `openspec initiative list` +- **THEN** system lists initiatives across registered context stores +- **AND** system supports `--json` output \ No newline at end of file diff --git a/openspec/specs/shell-completion/spec.md b/openspec/specs/shell-completion/spec.md index bb34fa3..47730f7 100644 --- a/openspec/specs/shell-completion/spec.md +++ b/openspec/specs/shell-completion/spec.md @@ -1,9 +1,7 @@ ## Purpose Shell completion support for OpenSpec. Generates and installs completion scripts for Bash, Zsh, and Fish shells. - ## Requirements - ### Requirement: Shell Completion Generation The system SHALL generate shell completion scripts for Bash, Zsh, and Fish. @@ -22,7 +20,7 @@ The system SHALL generate shell completion scripts for Bash, Zsh, and Fish. ### Requirement: Shell Completion Installation -The system SHALL install completion scripts to appropriate shell directories. +The system SHALL install completion scripts to appropriate shell directories. Installation SHALL be opt-in (explicitly requested), and SHALL write scripts using encodings/setup compatible with each target shell. #### Scenario: Install bash completion - **WHEN** user runs `openspec completion install bash` @@ -31,6 +29,16 @@ The system SHALL install completion scripts to appropriate shell directories. #### Scenario: Install zsh completion - **WHEN** user runs `openspec completion install zsh` - **THEN** system installs completion to zsh fpath directory +- **AND** the installed script works under oh-my-zsh's `compinit` + +#### Scenario: Completion install is opt-in +- **WHEN** user runs `openspec init` or `openspec update` +- **THEN** system does NOT install shell completion automatically +- **AND** completion is installed only when the user runs `openspec completion install <shell>` + +#### Scenario: PowerShell completion encoding +- **WHEN** user installs PowerShell completion +- **THEN** the generated profile content is written without encoding corruption ### Requirement: Shell Completion Uninstallation @@ -46,4 +54,4 @@ The system SHALL provide completion data for changes and specs. #### Scenario: Complete change names - **WHEN** shell requests completion for change names -- **THEN** system outputs list of available changes +- **THEN** system outputs list of available changes \ No newline at end of file diff --git a/openspec/specs/spec-parser/spec.md b/openspec/specs/spec-parser/spec.md index 6409965..4bb0044 100644 --- a/openspec/specs/spec-parser/spec.md +++ b/openspec/specs/spec-parser/spec.md @@ -1,9 +1,7 @@ ## Purpose Markdown spec parser for OpenSpec. Parses delta specs with ADDED/MODIFIED/REMOVED/RENAMED sections and merges them into main specs. - ## Requirements - ### Requirement: Delta Spec Parsing The system SHALL parse markdown spec files with ADDED, MODIFIED, REMOVED, and RENAMED sections. @@ -27,7 +25,7 @@ The system SHALL parse markdown spec files with ADDED, MODIFIED, REMOVED, and RE ### Requirement: Requirement Extraction -The system SHALL extract requirements with their scenarios from markdown. +The system SHALL extract requirements with their scenarios from markdown. Requirement headers SHALL be matched case-insensitively, and header-looking lines nested inside fenced code blocks SHALL NOT be parsed as requirements or scenarios. #### Scenario: Extract requirement with scenarios - **WHEN** system parses `### Requirement: <name>` followed by `#### Scenario: <name>` blocks @@ -39,6 +37,15 @@ The system SHALL extract requirements with their scenarios from markdown. - **THEN** system still extracts the requirement - **AND** system may warn about missing scenarios +#### Scenario: Case-insensitive requirement header +- **WHEN** a spec uses a header such as `### requirement: <name>` or `### REQUIREMENT: <name>` +- **THEN** system parses it as a requirement regardless of capitalization + +#### Scenario: Ignore requirement inside a fenced code block +- **WHEN** a spec contains a `### Requirement:` or `#### Scenario:` line inside a fenced code block (```` ``` ```` or `~~~`) +- **THEN** system does NOT parse the fenced line as a requirement or scenario +- **AND** only real, non-fenced requirements are counted + ### Requirement: Spec Merging The system SHALL merge delta specs into main specs during archive. @@ -65,4 +72,4 @@ The system SHALL discover spec files matching glob patterns. #### Scenario: Discover main specs - **WHEN** system looks for specs in `openspec/specs/` -- **THEN** system finds all `spec.md` files organized by capability +- **THEN** system finds all `spec.md` files organized by capability \ No newline at end of file diff --git a/openspec/specs/telemetry/spec.md b/openspec/specs/telemetry/spec.md index a13f9ab..07c57bd 100644 --- a/openspec/specs/telemetry/spec.md +++ b/openspec/specs/telemetry/spec.md @@ -1,9 +1,7 @@ ## Purpose Optional anonymous telemetry for OpenSpec. Collects usage statistics to improve the tool with user consent and easy opt-out. - ## Requirements - ### Requirement: Anonymous Usage Tracking The system MAY collect anonymous usage statistics when telemetry is enabled, and SHALL NOT collect any data when telemetry is disabled. @@ -46,3 +44,16 @@ The system SHALL send telemetry asynchronously to avoid blocking CLI operations. - **WHEN** system sends telemetry - **THEN** command execution is not delayed - **AND** telemetry failures do not affect command results + +### Requirement: Resilient Telemetry Delivery + +The system SHALL fail silently when telemetry delivery is blocked, so that firewalled or offline environments never surface network errors to the user. + +#### Scenario: Network blocked by firewall +- **WHEN** telemetry is enabled but the analytics endpoint is unreachable or blocked +- **THEN** system swallows the network error without printing it +- **AND** system does not retry indefinitely (delivery uses a short ~1s timeout with retries and remote config disabled) + +#### Scenario: No impact on command exit +- **WHEN** a telemetry send fails +- **THEN** the command still completes and exits normally \ No newline at end of file diff --git a/openspec/specs/workspace/spec.md b/openspec/specs/workspace/spec.md new file mode 100644 index 0000000..3bbb028 --- /dev/null +++ b/openspec/specs/workspace/spec.md @@ -0,0 +1,57 @@ +# workspace Specification + +## Purpose +TBD - created by archiving change sync-upstream-v1-4-1. Update Purpose after archive. +## Requirements +### Requirement: Workspace Setup and Linking + +The system SHALL provide a beta `openspec workspace` command group that sets up coordination workspaces and links existing repos or folders to them. + +#### Scenario: Set up a workspace +- **WHEN** user runs `openspec workspace setup` +- **THEN** system creates a workspace and records its configuration +- **AND** system can link existing repos or folders during setup + +#### Scenario: Link an existing repo +- **WHEN** user runs `openspec workspace link [nameOrPath] [path]` +- **THEN** system links the repo or folder to the workspace under a link name + +#### Scenario: Relink a moved repo +- **WHEN** user runs `openspec workspace relink <name> <path>` +- **THEN** system updates the local path for the existing workspace link + +### Requirement: Workspace Inspection + +The system SHALL allow listing and diagnosing workspaces. + +#### Scenario: List workspaces +- **WHEN** user runs `openspec workspace list` (or `ls`) +- **THEN** system lists known OpenSpec workspaces + +#### Scenario: Diagnose workspace resolution +- **WHEN** user runs `openspec workspace doctor` +- **THEN** system reports what the workspace can resolve on this machine + +### Requirement: Workspace Open and View State + +The system SHALL open a workspace in an agent or editor, and SHALL persist beta workspace view state under `.openspec-workspace/view.yaml`. + +#### Scenario: Open a workspace +- **WHEN** user runs `openspec workspace open [name]` +- **THEN** system opens the workspace in a selected agent or VS Code editor + +#### Scenario: Persist view state +- **WHEN** workspace view state changes +- **THEN** system stores it under `.openspec-workspace/view.yaml` + +### Requirement: Workspace Update Isolation + +The system SHALL keep workspace updates separate from project updates. + +#### Scenario: Refresh workspace guidance +- **WHEN** user runs `openspec workspace update [name]` +- **THEN** system refreshes workspace-local OpenSpec guidance and agent skills + +#### Scenario: Top-level update stays project-scoped +- **WHEN** user runs top-level `openspec update` outside a workspace root +- **THEN** system does not route into workspace updates \ No newline at end of file