OpenSpec Workflow

A focused, project-first dashboard for OpenSpec changes, specs, and safe workflow actions in VS Code and Cursor.

English | 简体中文

Overview

OpenSpec brings change planning and execution into the editor. Review what needs attention, inspect specs and artifacts, and take the next workflow step without losing context.

Highlights

• Project-first sidebar: Fixed Changes, Specs, Worksets, and Dashboard entry points, with clear active, focus, and unavailable states.
• Stores and Worksets: Use registered Stores as planning roots, then browse, inspect, create, and open trusted multi-folder Worksets without leaving the sidebar.
• Recommended actions: A compact, resolver-backed action rail surfaces up to three next steps by priority: Needs Attention, Ready to Verify, then Recommended.
• Change detail: Proposal, Specs, Design, Tasks, and Verify & Archive tabs with markdown rendering, task progress, and workflow controls.
• Safe workflow routing: Review and verify actions open the appropriate detail or interactive terminal flow; high-impact archive actions stay confirmation-protected.
• CLI integration: OpenSpec CLI list, status, new, archive, Store, and Workset flows with retry, timeout, and openspec.cliPath fallback.
• Editor-native: Uses VS Code theme tokens, Codicons, keyboard-accessible controls, and narrow-sidebar-friendly layouts.

Screenshots

Project dashboard sidebar

The sidebar keeps project navigation and the next recommended workflow actions in one compact surface. The screenshot uses a public demo workspace and contains no private paths, credentials, or runtime logs.

Change detail and task actions

The detail view keeps artifacts, task progress, and workflow actions together. Verify and Archive remain separate from ordinary task execution so the safe route is explicit.

Installation

• Open VSX (available now): Install OpenSpec Workflow from Open VSX — works in Cursor, VSCodium, and other Open VSX–compatible editors.
• VS Code Marketplace (publishing in progress): The listing for publisher randysss / OpenSpec Workflow is being prepared; it is not live on marketplace.visualstudio.com yet. Until then, use Open VSX or install from a packaged .vsix (see docs/PUBLISHING.md).
• Requirements: OpenSpec CLI; a workspace that contains (or will contain) openspec/config.yaml. The extension activates when it finds an OpenSpec workspace.

If Cursor or VS Code cannot see the CLI that works in your terminal, set openspec.cliPath to the absolute executable path, for example /opt/homebrew/bin/openspec or /usr/local/bin/openspec.

Usage

Quick start

1. Open a workspace that contains openspec/config.yaml.
2. Run OpenSpec: Open Dashboard.
3. Check the active Root, then select New Change.
4. By default, select Copy Continue planning or Copy FF, then paste the copied command into your Agent to generate the planning artifacts.
5. Review Proposal, Specs, Design, and Tasks, then select Copy Apply and paste the copied command into your Agent.
6. In Verify & Archive, run Run Verify first, then use Review & Archive as needed.

The default clipboard launch mode only copies workflow commands. Set openspec.workflowLaunchMode to adapter when you want actions to open, launch, or run through the configured adapter.

Review & Archive is the recommended Agent-assisted path. Archive Now is a direct CLI path that requires explicit confirmation and is available only when the workflow is complete.

Stores and Worksets

Stores and Worksets require OpenSpec CLI 1.5.0 or newer.

A Store is a writable planning Root for Changes and Specs. Use the Root controls to select or create one; the extension switches the binding only after CLI validation. Store Git operations remain your responsibility.

A Workset is a machine-local named group of folders. From Worksets, you can view Projects and Stores, switch the sidebar Project or planning Root, open every member as a complete workspace, and create a group.

A row opens only its detail view, not a new editor window. A Project member switches the sidebar, a Store member becomes the planning Root, and Open all opens the complete workspace.

Create Workset starts with the current Project and adds folders through the native folder picker. A one-time opener override does not change the saved opener.

Complete user guide

• English user guide
• Plugin interface
• 简体中文使用指南

Commands

Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P):

Keyboard shortcuts

• Cmd+Shift+P (Mac) / Ctrl+Shift+P (Windows/Linux): Command Palette — then type "OpenSpec" to run any command.
• No default keybindings; you can assign them in Keyboard Shortcuts (e.g. for "OpenSpec: Open Dashboard").

Configuration

Task execution & Adapters

• Clipboard (clipboard): Always available. This is the default workflow launch behavior and only copies the generated /opsx:* command.
• Cursor (cursor): In Cursor, the adapter can copy the command and open the official prompt deeplink, try a Chat query, copy only, or explicitly run the headless Agent CLI depending on openspec.cursorLaunchMode.
• OpenCode (opencode): Uses /opsx-<action> command format when routed through the adapter.
• Workflow actions default to workflowLaunchMode=clipboard. Set openspec.workflowLaunchMode=adapter and choose openspec.preferredAgentAdapter when you want buttons to open the selected adapter. In Cursor, explicitly setting openspec.cursorLaunchMode to deeplink, chatCommand, or agentCli also routes non-interactive workflow buttons through Cursor.
• Verify and Archive are intentionally different: they open the dedicated Verify & Archive tab and run inside a real VS Code terminal editor instead of the headless agentCli path.
• Within that tab, Review & Archive keeps Agent review interactive, while Archive Now is the explicit direct-archive escape path and is disabled until the bound workflow is complete.

Dashboard

• Filter by Host-derived lifecycle status: All, Planning, Ready to Apply, Applying, Ready to Verify, and Archived.
• Needs Attention is an orthogonal filter (not a lifecycle value) for changes that need review.
• Pipeline order is always filter → search → sort → paginate; status filters apply before pagination.
• Archived is a first-class, read-only lifecycle status (no write workflow actions).
• View state (filters, search, sort, page size) is scoped per OpenSpec Root (Local / Store).
• Search changes by name, status, artifact, or Proposal Why text.
• Review progress, lifecycle badges, artifact badges, and Proposal Why summaries.
• Open change details with Proposal / Specs / Design / Tasks / Verify & Archive tabs.
• Execute tasks through the selected adapter, or fill/copy workflow commands into chat.
• Toggle task completion only after confirming in the webview dialog.

Viewing Logs

1. Open Output panel: View > Output or Cmd+Shift+U
2. Select "OpenSpec" from dropdown
3. View timestamped logs (INFO, WARN, ERROR, DEBUG)

Troubleshooting

• Extension doesn’t activate: Open a folder that contains (or will contain) an OpenSpec workspace (openspec/config.yaml). The extension only activates in OpenSpec workspaces.
• "OpenSpec CLI not found": Install OpenSpec CLI and ensure it’s on your PATH.
• Dashboard empty: Run OpenSpec: Refresh Data; check the OpenSpec output channel for errors.
• CLI diagnostic card shown in Dashboard: When the OpenSpec CLI cannot be launched from the VS Code/Cursor Extension Host, the Dashboard shows a diagnostic card with safe details and recovery actions. Use Retry after fixing PATH or openspec.cliPath, Open Settings to set the CLI path, and Copy Diagnostics when reporting an issue. The copied diagnostic omits full PATH values, home directory paths, and secrets.
• Windows .cmd or shim launch failures: If the diagnostic mentions spawn-failed or ENOENT, set openspec.cliPath to the absolute OpenSpec executable or shim path, then click Retry.
• Retry does not modify your configuration: The Retry button only re-runs CLI detection. It does not install the CLI, modify your shell configuration, or change openspec.cliPath.