sauron-cli 1.1.3 → 1.3.0

package/OpenSpec-main/openspec/changes/archive/2026-02-17-schema-management-cli/specs/schema-validate-command/spec.md

@@ -0,0 +1,86 @@
+## ADDED Requirements
+
+### Requirement: Schema validate checks schema structure
+The CLI SHALL provide an `openspec schema validate [name]` command that validates schema configuration and reports errors.
+
+#### Scenario: Validate specific schema
+- **WHEN** user runs `openspec schema validate my-workflow`
+- **THEN** system locates schema using resolution order
+- **AND** validates `schema.yaml` against the schema Zod type
+- **AND** displays validation result (valid or list of errors)
+
+#### Scenario: Validate all project schemas
+- **WHEN** user runs `openspec schema validate` without a name
+- **THEN** system validates all schemas in `openspec/schemas/`
+- **AND** displays results for each schema
+- **AND** exits with non-zero code if any schema is invalid
+
+#### Scenario: Schema not found
+- **WHEN** user runs `openspec schema validate nonexistent`
+- **THEN** system displays error that schema was not found
+- **AND** exits with non-zero code
+
+### Requirement: Schema validate checks YAML syntax
+The CLI SHALL report YAML parsing errors with line numbers when possible.
+
+#### Scenario: Invalid YAML syntax
+- **WHEN** user runs `openspec schema validate my-workflow` and `schema.yaml` has syntax errors
+- **THEN** system displays YAML parse error with line number
+- **AND** exits with non-zero code
+
+#### Scenario: Valid YAML but missing required fields
+- **WHEN** `schema.yaml` is valid YAML but missing `name` field
+- **THEN** system displays Zod validation error for missing required field
+- **AND** identifies the specific missing field
+
+### Requirement: Schema validate checks template existence
+The CLI SHALL verify that all template files referenced by artifacts exist.
+
+#### Scenario: Missing template file
+- **WHEN** artifact references `template: proposal.md` but file doesn't exist in schema directory
+- **THEN** system reports error: "Template file 'proposal.md' not found for artifact 'proposal'"
+- **AND** exits with non-zero code
+
+#### Scenario: All templates exist
+- **WHEN** all artifact templates exist
+- **THEN** system reports that templates are valid
+- **AND** template existence is included in validation summary
+
+### Requirement: Schema validate checks dependency graph
+The CLI SHALL verify that artifact dependencies form a valid directed acyclic graph.
+
+#### Scenario: Valid dependency graph
+- **WHEN** artifact dependencies form a valid DAG (e.g., tasks → specs → proposal)
+- **THEN** system reports dependency graph is valid
+
+#### Scenario: Circular dependency detected
+- **WHEN** artifact A requires B and artifact B requires A
+- **THEN** system reports circular dependency error
+- **AND** identifies the artifacts involved in the cycle
+- **AND** exits with non-zero code
+
+#### Scenario: Unknown dependency reference
+- **WHEN** artifact requires `nonexistent-artifact`
+- **THEN** system reports error: "Artifact 'x' requires unknown artifact 'nonexistent-artifact'"
+- **AND** exits with non-zero code
+
+### Requirement: Schema validate outputs JSON format
+The CLI SHALL support `--json` flag for machine-readable validation results.
+
+#### Scenario: JSON output for valid schema
+- **WHEN** user runs `openspec schema validate my-workflow --json` and schema is valid
+- **THEN** system outputs JSON with `valid: true`, `name`, and `path` fields
+
+#### Scenario: JSON output for invalid schema
+- **WHEN** user runs `openspec schema validate my-workflow --json` and schema has errors
+- **THEN** system outputs JSON with `valid: false` and `issues` array
+- **AND** each issue includes `level`, `path`, and `message` fields
+- **AND** format matches existing `openspec validate` output structure
+
+### Requirement: Schema validate supports verbose mode
+The CLI SHALL support `--verbose` flag for detailed validation information.
+
+#### Scenario: Verbose output shows all checks
+- **WHEN** user runs `openspec schema validate my-workflow --verbose`
+- **THEN** system displays each validation check as it runs
+- **AND** shows pass/fail status for: YAML parsing, Zod validation, template existence, dependency graph

package/OpenSpec-main/openspec/changes/archive/2026-02-17-schema-management-cli/specs/schema-which-command/spec.md

@@ -0,0 +1,65 @@
+## ADDED Requirements
+
+### Requirement: Schema which shows resolution result
+The CLI SHALL provide an `openspec schema which <name>` command that displays where a schema resolves from.
+
+#### Scenario: Schema resolves from project
+- **WHEN** user runs `openspec schema which my-workflow` and schema exists in `openspec/schemas/my-workflow/`
+- **THEN** system displays source as "project"
+- **AND** displays full path to schema directory
+
+#### Scenario: Schema resolves from user directory
+- **WHEN** user runs `openspec schema which my-workflow` and schema exists only in user data directory
+- **THEN** system displays source as "user"
+- **AND** displays full path including XDG data directory
+
+#### Scenario: Schema resolves from package
+- **WHEN** user runs `openspec schema which spec-driven` and no override exists
+- **THEN** system displays source as "package"
+- **AND** displays full path to package's schemas directory
+
+#### Scenario: Schema not found
+- **WHEN** user runs `openspec schema which nonexistent`
+- **THEN** system displays error that schema was not found
+- **AND** lists available schemas
+- **AND** exits with non-zero code
+
+### Requirement: Schema which shows shadowing information
+The CLI SHALL indicate when a schema shadows another schema at a lower priority level.
+
+#### Scenario: Project schema shadows package
+- **WHEN** user runs `openspec schema which spec-driven` and both project and package have `spec-driven`
+- **THEN** system displays that project schema is active
+- **AND** indicates it shadows the package version
+- **AND** shows path to shadowed package schema
+
+#### Scenario: No shadowing
+- **WHEN** schema exists only in one location
+- **THEN** system does not display shadowing information
+
+#### Scenario: Multiple shadows
+- **WHEN** project schema shadows both user and package schemas
+- **THEN** system lists all shadowed locations in priority order
+
+### Requirement: Schema which outputs JSON format
+The CLI SHALL support `--json` flag for machine-readable output.
+
+#### Scenario: JSON output basic
+- **WHEN** user runs `openspec schema which spec-driven --json`
+- **THEN** system outputs JSON with `name`, `source`, and `path` fields
+
+#### Scenario: JSON output with shadows
+- **WHEN** user runs `openspec schema which spec-driven --json` and schema has shadows
+- **THEN** JSON includes `shadows` array with `source` and `path` for each shadowed schema
+
+### Requirement: Schema which supports list mode
+The CLI SHALL support listing all schemas with their resolution sources.
+
+#### Scenario: List all schemas
+- **WHEN** user runs `openspec schema which --all`
+- **THEN** system displays all available schemas grouped by source
+- **AND** indicates which schemas shadow others
+
+#### Scenario: List in JSON format
+- **WHEN** user runs `openspec schema which --all --json`
+- **THEN** system outputs JSON array with resolution info for each schema

package/OpenSpec-main/openspec/changes/archive/2026-02-17-schema-management-cli/tasks.md

@@ -0,0 +1,67 @@
+## 1. Setup and Command Structure
+
+- [x] 1.1 Create `src/commands/schema.ts` with `registerSchemaCommand(program: Command)` function
+- [x] 1.2 Register schema command in `src/cli/index.ts` (import and call `registerSchemaCommand`)
+- [x] 1.3 Add schema command group with description: "Manage workflow schemas"
+
+## 2. Schema Which Command
+
+- [x] 2.1 Add `schema which <name>` subcommand with `--json` and `--all` options
+- [x] 2.2 Implement resolution lookup using `getSchemaDir()` with project root
+- [x] 2.3 Implement shadow detection by checking all three locations (project, user, package)
+- [x] 2.4 Add text output: show source, path, and shadowing info
+- [x] 2.5 Add JSON output: `{ name, source, path, shadows: [] }`
+- [x] 2.6 Add `--all` mode to list all schemas with their resolution sources
+
+## 3. Schema Validate Command
+
+- [x] 3.1 Add `schema validate [name]` subcommand with `--json` and `--verbose` options
+- [x] 3.2 Implement single-schema validation using existing `parseSchema()` from `schema.ts`
+- [x] 3.3 Add template existence check for each artifact's template file
+- [x] 3.4 Add dependency graph cycle detection (reuse topological sort logic)
+- [x] 3.5 Add validate-all mode when no name provided (scan `openspec/schemas/`)
+- [x] 3.6 Add text output with pass/fail indicators and error messages
+- [x] 3.7 Add JSON output matching existing `openspec validate` format: `{ valid, issues: [] }`
+- [x] 3.8 Add verbose mode showing each validation step
+
+## 4. Schema Fork Command
+
+- [x] 4.1 Add `schema fork <source> [name]` subcommand with `--json` and `--force` options
+- [x] 4.2 Implement source resolution using `getSchemaDir()` with project root
+- [x] 4.3 Implement default destination naming: `<source>-custom`
+- [x] 4.4 Implement directory copy with recursive file copy
+- [x] 4.5 Update `name` field in copied `schema.yaml`
+- [x] 4.6 Add overwrite protection: check destination exists, require `--force` or confirmation
+- [x] 4.7 Add text output with source/destination paths
+- [x] 4.8 Add JSON output: `{ forked, source, destination, sourceLocation }`
+
+## 5. Schema Init Command
+
+- [x] 5.1 Add `schema init <name>` subcommand with `--json`, `--description`, `--artifacts`, `--default`, `--no-default`, `--force` options
+- [x] 5.2 Implement schema name validation (kebab-case, no spaces)
+- [x] 5.3 Implement interactive prompts for description using `@inquirer/prompts`
+- [x] 5.4 Implement interactive artifact selection with descriptions (multi-select)
+- [x] 5.5 Create schema directory and `schema.yaml` with selected configuration
+- [x] 5.6 Create default template files for selected artifacts
+- [x] 5.7 Add `--default` flag to update `openspec/config.yaml` with new schema as default
+- [x] 5.8 Add overwrite protection: check if schema exists, require `--force`
+- [x] 5.9 Add text output with created path and next steps
+- [x] 5.10 Add JSON output: `{ created, path, schema }`
+- [x] 5.11 Add non-interactive mode with `--description` and `--artifacts` flags
+
+## 6. Testing
+
+- [x] 6.1 Add unit tests for `schema which` command in `test/commands/schema.test.ts`
+- [x] 6.2 Add unit tests for `schema validate` command
+- [x] 6.3 Add unit tests for `schema fork` command
+- [x] 6.4 Add unit tests for `schema init` command
+- [x] 6.5 Test interactive mode mocking with `@inquirer/prompts`
+- [x] 6.6 Test JSON output format for all commands
+- [x] 6.7 Test error cases: invalid name, not found, already exists, cycle detection
+
+## 7. Documentation and Polish
+
+- [x] 7.1 Add CLI help text for all schema subcommands
+- [x] 7.2 Update shell completion to include schema commands
+- [x] 7.3 Run linting and fix any issues (`npm run lint`)
+- [x] 7.4 Run full test suite (`npm test`)

package/OpenSpec-main/openspec/changes/archive/2026-04-23-add-kimi-cli-skills-only-support/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-23

package/OpenSpec-main/openspec/changes/archive/2026-04-23-add-kimi-cli-skills-only-support/README.md

@@ -0,0 +1,3 @@
+# add-kimi-cli-skills-only-support
+
+Add Kimi CLI as a supported skills-only tool without a command adapter

package/OpenSpec-main/openspec/changes/archive/2026-04-23-add-kimi-cli-skills-only-support/design.md

@@ -0,0 +1,85 @@
+## Context
+
+Kimi CLI is not another Claude/Codex-style adapter target. Its extension model is built around discovered skills, not external command files:
+
+- skills are discovered from `.kimi/skills/`
+- skills are exposed as `/skill:<name>`
+- no stable `.kimi/commands/` or prompt-file loading mechanism was found in the Kimi CLI codebase
+
+OpenSpec's existing architecture can already represent that shape:
+
+- `AI_TOOLS` can advertise a `skillsDir`
+- `init` can install skills for any selected tool with `skillsDir`
+- when command generation is attempted for a tool without an adapter, OpenSpec already records `commandsSkipped`
+
+## Goals
+
+- Add Kimi CLI using the same narrow `skills-only` pattern already used by Trae
+- Keep the implementation small: metadata, docs, and a focused regression test
+- Make the spec text match the current code path for adapterless tools
+
+## Non-Goals
+
+- designing a Kimi-specific command adapter without upstream support
+- changing tool capability modeling across the whole generation pipeline
+- reworking `delivery=commands` behavior for all adapterless tools
+
+## Decisions
+
+### 1. Represent Kimi CLI as an adapterless tool with `.kimi`
+
+Add a new `AI_TOOLS` entry:
+
+```ts
+{ name: 'Kimi CLI', value: 'kimi', available: true, successLabel: 'Kimi CLI', skillsDir: '.kimi' }
+```
+
+This matches Kimi CLI's project-local skills root and lets existing init/update detection paths treat it as a supported tool.
+
+### 2. Do not add a Kimi command adapter
+
+No `src/core/command-generation/adapters/kimi.ts` file will be added, and the command adapter registry will remain unchanged.
+
+Rationale:
+
+- Kimi CLI exposes skills dynamically as `/skill:<name>`
+- the previous upstream PR stalled specifically because no legitimate adapter target was available
+- adding a fake `.kimi/commands/...` path would create behavior OpenSpec cannot justify against upstream Kimi CLI behavior
+
+### 3. Document Kimi by its real invocation surface
+
+Kimi documentation in OpenSpec must use Kimi's actual skill invocation form:
+
+- supported-tools: no generated command files, use `/skill:openspec-*`
+- commands doc: examples such as `/skill:openspec-propose`
+
+The docs must not claim generated `opsx-*` files or `/openspec-*` direct invocations for Kimi.
+
+### 4. Keep the change compatible with existing Trae-style behavior
+
+This change intentionally follows the current adapterless-tool behavior already present in the codebase:
+
+- skills are created whenever delivery includes skills
+- command generation is skipped when no adapter exists
+- init output reports `Commands skipped for: kimi (no adapter)`
+
+This keeps the Kimi change small and avoids overlapping implementation work already captured in `add-tool-command-surface-capabilities`.
+
+## Test Strategy
+
+Add one focused regression test in `test/core/init.test.ts`:
+
+- configure `delivery=both`
+- run init with `--tools kimi`
+- verify Kimi skills are created under `.kimi/skills/...`
+- verify init reports the skipped command generation path for `kimi`
+
+That test is enough for this narrow change because:
+
+- adapterless update behavior already has generic coverage
+- CLI tool-id rendering is derived from `AI_TOOLS`
+- no command adapter or path formatting logic is being introduced
+
+## Risks / Trade-offs
+
+The main trade-off is scope: Kimi will inherit the current adapterless-tool behavior, including the broader limitation that `delivery=commands` is not yet capability-aware for skills-invocable tools. That is acceptable for this change because it matches the existing Trae/ForgeCode model and keeps the implementation aligned with verified Kimi CLI behavior.

package/OpenSpec-main/openspec/changes/archive/2026-04-23-add-kimi-cli-skills-only-support/proposal.md

@@ -0,0 +1,38 @@
+## Why
+
+OpenSpec already has user demand for Kimi CLI support, but the previous upstream attempt stalled because it assumed Kimi needed a command adapter. Local review of the Kimi CLI codebase shows a different integration surface: Kimi discovers `SKILL.md` files from `.kimi/skills/` and exposes them through `/skill:<name>`, but it does not provide a stable, file-based custom command directory like Claude Code or Codex.
+
+OpenSpec already supports tools that install skills without a command adapter. Trae and ForgeCode are the existing examples. Kimi should follow the same pattern instead of introducing undocumented `.kimi/commands/...` behavior.
+
+## What Changes
+
+- Add Kimi CLI as a supported tool in `AI_TOOLS` with `skillsDir: '.kimi'`
+- Document Kimi CLI as a skills-only integration in supported tools and command usage docs
+- Align change specs so `cli-init` explicitly allows selected tools with `skillsDir` but no registered command adapter
+
+## Capabilities
+
+### New Capabilities
+
+_None._
+
+### Modified Capabilities
+
+- `ai-tool-paths`: define the `.kimi` skills root for Kimi CLI
+- `cli-init`: clarify that adapterless tools remain valid selections and skip command-file generation with an informational message
+
+## Impact
+
+- `src/core/config.ts` - add Kimi CLI tool metadata
+- `docs/supported-tools.md` - add Kimi CLI row and tool id
+- `docs/commands.md` - document `/skill:openspec-*` usage for Kimi CLI
+- `docs/cli.md` - include `kimi` in the supported `--tools` list
+- `test/core/init.test.ts` - cover Kimi CLI as an adapterless tool during init
+
+## Non-Goals
+
+- Adding `src/core/command-generation/adapters/kimi.ts`
+- Defining a `.kimi/commands/...` output path
+- Changing the broader delivery model for adapterless tools under `delivery=commands`
+
+That broader capability-aware delivery work is already being explored separately in `add-tool-command-surface-capabilities`. This change stays narrow and follows the existing Trae/ForgeCode pattern.

package/OpenSpec-main/openspec/changes/archive/2026-04-23-add-kimi-cli-skills-only-support/specs/ai-tool-paths/spec.md

@@ -0,0 +1,12 @@
+# ai-tool-paths Delta Specification
+
+## MODIFIED Requirements
+
+### Requirement: Path configuration for supported tools
+
+The `AI_TOOLS` array SHALL include `skillsDir` for tools that support the Agent Skills specification.
+
+#### Scenario: Kimi CLI paths defined
+
+- **WHEN** looking up the `kimi` tool
+- **THEN** `skillsDir` SHALL be `.kimi`

package/OpenSpec-main/openspec/changes/archive/2026-04-23-add-kimi-cli-skills-only-support/specs/cli-init/spec.md

@@ -0,0 +1,37 @@
+# cli-init Delta Specification
+
+## MODIFIED Requirements
+
+### Requirement: Slash Command Generation
+
+The command SHALL generate opsx slash commands only for selected tools that have a registered command adapter, while keeping adapterless tools valid for skill generation.
+
+#### Scenario: Generating slash commands for a tool with a registered adapter
+
+- **WHEN** a tool with a registered command adapter is selected during initialization
+- **THEN** create 9 slash command files using the tool's command adapter:
+  - `/opsx:explore`
+  - `/opsx:new`
+  - `/opsx:continue`
+  - `/opsx:apply`
+  - `/opsx:ff`
+  - `/opsx:verify`
+  - `/opsx:sync`
+  - `/opsx:archive`
+  - `/opsx:bulk-archive`
+- **AND** use tool-specific path conventions (e.g., `.claude/commands/opsx/` for Claude)
+- **AND** include tool-specific frontmatter format
+
+#### Scenario: Selected tool has no command adapter
+
+- **GIVEN** a selected tool has `skillsDir` configured but no registered command adapter
+- **WHEN** initialization includes command generation
+- **THEN** skill generation for that tool SHALL still remain valid
+- **AND** command-file generation SHALL be skipped for that tool
+- **AND** the command output SHALL include `Commands skipped for: <tool-id> (no adapter)`
+
+#### Scenario: Kimi CLI skips command-file generation
+
+- **WHEN** the user selects Kimi CLI during initialization
+- **THEN** OpenSpec SHALL treat it as a supported tool with `skillsDir: '.kimi'`
+- **AND** command-file generation SHALL be skipped because no Kimi adapter is registered

package/OpenSpec-main/openspec/changes/archive/2026-04-23-add-kimi-cli-skills-only-support/tasks.md

@@ -0,0 +1,22 @@
+## 1. Change Artifacts
+
+- [x] 1.1 Write proposal, design, and spec deltas for Kimi CLI skills-only support
+
+## 2. Tool Metadata
+
+- [x] 2.1 Add `Kimi CLI` to `src/core/config.ts` with `value: 'kimi'` and `skillsDir: '.kimi'`
+
+## 3. Documentation
+
+- [x] 3.1 Update `docs/supported-tools.md` with a Kimi CLI row that clearly states there is no command adapter
+- [x] 3.2 Update `docs/commands.md` to document Kimi CLI usage via `/skill:openspec-*`
+- [x] 3.3 Update `docs/cli.md` so the supported `--tools` list includes `kimi`
+
+## 4. Tests
+
+- [x] 4.1 Add a targeted init regression test for `--tools kimi` under adapterless command generation
+
+## 5. Validation
+
+- [x] 5.1 Validate the change artifacts with `openspec validate`
+- [x] 5.2 Run targeted tests and fix any regressions

package/OpenSpec-main/openspec/changes/archive/2026-05-04-workspace-foundation/design.md

@@ -0,0 +1,208 @@
+## Product Model
+
+An OpenSpec workspace is the durable planning home for work that spans multiple repos or folders.
+
+It should feel like this:
+
+```text
+workspace = where related changes live
+link      = a named repo or folder the workspace can plan against
+change    = one feature, fix, project, or other planned piece of work
+```
+
+The foundation intentionally avoids the rest of the workflow. It only defines how OpenSpec recognizes a workspace, where managed workspaces live, how linked paths are represented, and how shared state differs from local state.
+
+A workspace is not a feature. It can hold many changes over time. The linked repos or folders provide planning context, while the code stays where it is.
+
+## Workspace Shape
+
+OpenSpec workspaces use this shape:
+
+```text
+workspace-root/
+  changes/                       # workspace-level proposals, tasks, specs
+  .openspec-workspace/
+    workspace.yaml               # shared workspace information
+    local.yaml                   # this machine's paths and preferences
+```
+
+The user-facing planning surface is `changes/`. The identity file that makes the directory a workspace is `.openspec-workspace/workspace.yaml`.
+
+Repo-local projects keep the existing shape:
+
+```text
+repo-root/
+  openspec/
+    specs/
+    changes/
+```
+
+That distinction lets a user or agent tell which surface they are working in:
+
+```text
+coordination workspace -> shared cross-repo planning
+repo-local project     -> repo-owned specs and implementation planning
+```
+
+Users should not run repo-local `openspec init` inside the workspace root. A workspace is already an OpenSpec coordination surface; it is not a product repo adopting repo-local OpenSpec.
+
+## Workspace Names
+
+A workspace name is a simple folder-style identifier, not a display name.
+
+The name must be usable as a folder name in the current runtime. It must not be empty, must not be `.` or `..`, and must not contain path separators.
+
+OpenSpec should not maintain a cross-platform reserved-name list in this slice. Setup/create flows should let filesystem creation surface OS-specific invalid folder names, then report that failure clearly.
+
+The same workspace name is stored in `.openspec-workspace/workspace.yaml`, used as the default managed workspace folder name, and used as the local registry name.
+
+## Shared And Local State
+
+Workspace state follows a simple sharing rule:
+
+```text
+share stable link names and planning
+keep local checkout paths local
+```
+
+Expected shared state:
+
+```yaml
+version: 1
+name: platform
+links:
+  api: {}
+  web: {}
+```
+
+Expected local state:
+
+```yaml
+version: 1
+paths:
+  api: /repos/api
+  web: /repos/web
+```
+
+Later slices can expand these shapes, but the product rule should stay stable: a shared workspace should not commit one user's absolute checkout paths.
+
+OpenSpec-created workspaces should include an ignore rule for `.openspec-workspace/local.yaml` so local checkout paths are not accidentally shared. `.openspec-workspace/workspace.yaml` remains the portable workspace identity and link-name state.
+
+## Workspace Location
+
+OpenSpec should create managed workspaces in one standard place:
+
+```text
+getGlobalDataDir()/workspaces
+```
+
+That reuses existing OpenSpec data-directory behavior:
+
+- `$XDG_DATA_HOME/openspec/workspaces` when `XDG_DATA_HOME` is set
+- `~/.local/share/openspec/workspaces` on Unix/macOS fallback
+- `%LOCALAPPDATA%\openspec\workspaces` on native Windows fallback
+
+This slice intentionally does not define a workspace-specific environment-variable, command, or configuration override for managed workspace storage. Tests should rely on existing global data-directory controls and test helpers instead of a separate workspace-home override.
+
+This is deliberately quiet. The product should not ask most users where workspaces should live.
+
+OpenSpec should show the resolved workspace path after setup. Quiet defaults should avoid a prompt, not hide where planning files were created.
+
+## Local Workspace Registry
+
+OpenSpec should keep a lightweight local registry of known workspaces:
+
+```text
+getGlobalDataDir()/workspaces/registry.yaml
+```
+
+Expected registry state:
+
+```yaml
+version: 1
+workspaces:
+  platform: /Users/tabish/.local/share/openspec/workspaces/platform
+  checkout: /Users/tabish/.local/share/openspec/workspaces/checkout
+```
+
+The registry is a local index, not the source of truth. It exists so workspace commands can work from anywhere, show a picker when multiple workspaces exist, and list known workspaces without scanning arbitrary folders.
+
+Each workspace folder remains authoritative for its own `.openspec-workspace/workspace.yaml` and `.openspec-workspace/local.yaml`. If a registry entry points at a missing or invalid workspace, later check/list flows can report that and suggest a repair.
+
+## Windows And WSL2
+
+Path behavior is runtime-local:
+
+- PowerShell/native Windows uses Windows paths and Windows data-directory fallback.
+- WSL2 uses Linux paths and Linux/XDG fallback inside WSL.
+- Local repo paths are stored as the user supplied them for the current runtime.
+
+Examples:
+
+```text
+PowerShell:
+  default base -> %LOCALAPPDATA%\openspec\workspaces
+
+WSL2:
+  default base -> ~/.local/share/openspec/workspaces
+```
+
+This slice should not translate between `D:\repo`, `/mnt/d/repo`, and `\\wsl$` paths. Cross-runtime translation can be reconsidered later if an agent-launch workflow requires it.
+
+## Link Names
+
+A link name is the stable way to refer to a repo or folder inside workspace planning.
+
+The local path can vary by machine:
+
+```text
+shared link name: landing
+Tabish path:      /Users/tabish/repos/landing
+Windows path:     D:\repos\landing
+WSL2 path:        /mnt/d/repos/landing
+```
+
+Later workflows should refer to `landing` in workspace planning, status, and apply context. The local path is only how the current machine finds that repo or folder.
+
+Link names are intentionally minimal: they must be non-empty, must not be `.` or `..`, must not contain path separators, and must be unique within the workspace.
+
+The owning repo or folder remains the home of canonical specs and implementation work. The workspace makes the cross-boundary plan legible; it does not take ownership away from the linked repos or folders.
+
+Link names are normally inferred from the folder basename in guided flows. Direct flows can allow an explicit name when the default would conflict or be unclear.
+
+## Linked Repos And Folders
+
+Workspace planning visibility should not require repo-local OpenSpec state.
+
+That matters for two common cases:
+
+- a repo has not adopted OpenSpec yet, but still needs to be considered in planning
+- a large monorepo has folders such as packages, services, or apps that should be planned like separate areas, without each folder having its own `openspec/`
+
+Foundation should allow the link model to describe both:
+
+```text
+multi-repo:
+  api      -> /repos/api
+  web      -> /repos/web
+
+large monorepo:
+  billing  -> /repos/platform/services/billing
+  checkout -> /repos/platform/apps/checkout
+```
+
+Later apply/verify/archive workflows can decide what extra readiness is needed for implementation. Planning should be able to start before that.
+
+Linking only records the relationship between a workspace link name and a local path. It must not create, copy, move, initialize, or edit files inside the linked repo or folder.
+
+Repo-local spec availability is computed when needed. For example, `repo_specs_path` can be reported by a later doctor command when a linked path contains `openspec/specs`, but that path should not be treated as required workspace state.
+
+## Later Slices
+
+This foundation stops before user-facing workspace workflows:
+
+- `workspace-create-and-register-repos` owns setup, link, relink, list, and doctor behavior.
+- `workspace-open-agent-context` owns agent launch context.
+- `workspace-change-planning` owns workspace proposals and repo scope.
+- `workspace-apply-repo-slice` owns implementation of one repo slice.
+- `workspace-verify-and-archive` owns completion and archive behavior.