OpenSpec Workflow
Project-first OpenSpec workbench for VS Code and Cursor: see the next step, hand Verify/Apply to the IDE Agent, and archive safely.
English | 简体中文
Overview
OpenSpec Workflow is a project-first workbench for the OpenSpec change lifecycle—not a CodeLens companion that only stuffs context into Chat.
- See what needs attention across Changes, Specs, Stores, and Worksets
- One click hands Verify / Apply to the IDE Agent panel (Cursor) or prefills Chat (VS Code)
- Safe defaults: confirm before Archive; CLI stays the source of truth behind the UI
Requires OpenSpec CLI. Published registry versions may trail the in-repo release until publish completes; see CHANGELOG.md for the latest version.
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: Workflow buttons open the IDE Agent panel with
/opsx-* commands; 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
- Open a workspace that contains
openspec/config.yaml.
- Run OpenSpec: Open Dashboard.
- Check the active Root, then select New Change.
- In Cursor, select Open Cursor · Continue planning or Open Cursor · FF to launch the workflow in Chat (or choose Copy command only (safe) in settings). In VS Code, buttons copy commands by default.
- Review Proposal, Specs, Design, and Tasks, then select Open Cursor · Apply (or Copy Apply in copy-only mode) and continue in your Agent.
- In Verify & Archive, run Run Verify first, then use Review & Archive as needed.
In Cursor, workflow buttons default to Launch with adapter (recommended) — they open Chat or Cursor with the /opsx:* command prefilled. Choose Copy command only (safe) in openspec.workflowLaunchMode when you only want clipboard copy. In VS Code, copy-only remains the default unless you explicitly choose adapter mode.
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
Commands
Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P):
| Command | Description |
|---|
| OpenSpec: Open Dashboard | Open visual dashboard (sidebar or editor) |
| OpenSpec: Refresh Data | Manually refresh from CLI |
| OpenSpec: Create New Change | Create new change (with validation) |
| OpenSpec: Archive Change | Archive completed change |
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
| Setting | Default | Description |
|---|
openspec.focusSidebarViewWhenOpeningChangeDetail | false | Focus OpenSpec sidebar when opening change detail |
openspec.focusSidebarViewWhenOpeningDashboard | false | Focus OpenSpec sidebar when opening dashboard |
openspec.cliPath | "" | Optional absolute path to OpenSpec CLI; empty = auto-detect from PATH and login shell |
openspec.taskExecutionMode | fillChat | When clicking task execute: auto = run via adapter; fillChat = fill chat or copy to clipboard |
openspec.workflowLaunchMode | clipboard (VS Code) / smart launch in Cursor | Launch with adapter (recommended) or Copy command only (safe). In Cursor with unset settings, defaults to launch mode. |
openspec.preferredAgentAdapter | clipboard (VS Code) / cursor in Cursor launch mode | Preferred agent executor when launch mode is adapter: clipboard, cursor, vscode-copilot, claude-code, or opencode |
openspec.agentAutoSubmit | readOnly | Auto-send in Cursor Agent panel: never, readOnly (explore/verify only), or always (composer layer only) |
openspec.cursorLaunchMode | clipboard (stored default) / agentPanel in Cursor launch mode | agentPanel (IDE Agent with fallback), clipboard, or explicit agentCli (may modify workspace files) |
openspec.taskDependencyPolicy | block | When preceding tasks are incomplete: block = prevent execution; warn = show warning and allow proceed |
openspec.cursorAgentModel | auto | Cursor Agent CLI model for explicit Agent CLI execution. Use or a specific model name |
Task execution & Adapters
- Clipboard (
clipboard): Always available. Select Copy command only (safe) when you only want /opsx:* commands copied.
- Cursor (
cursor): In Cursor, defaults to the Agent panel (agentPanel) with runtime fallback (composer → chat → deeplink → clipboard). agentCli is opt-in and may modify workspace files.
- OpenCode (
opencode): Uses /opsx-<action> command format when routed through the adapter.
- In Cursor, unset workflow settings smart-default to launch mode with the Cursor adapter. Choose Copy command only (safe) in settings to restore copy-only behavior. If launch fails, the extension falls back to clipboard with a visible notice.
- Verify and Archive use the same Agent panel launch path as Apply and Continue. The Verify & Archive tab also offers Archive Now (direct filesystem archive) when the 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
- Open Output panel:
View > Output or Cmd+Shift+U
- Select "OpenSpec" from dropdown
- 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.
🏗️ Architecture
Extension Host (Node.js) Webview (React)
├── DataManager ├── Dashboard
│ ├── OpenSpecCliService ├── Change detail
│ ├── FileManagerService └── Shared UI components
│ └── FileWatcherService
├── CommandManager
└── DashboardProvider
Design Decisions:
- Data Source: Hybrid (CLI + FileWatcher + Direct reads)
- Backend: OpenSpec CLI via
child_process
- Frontend: React + Tailwind CSS + Radix UI
- Build: esbuild + Vite
- Package Manager: pnpm
See docs/ARCHITECTURE.md for details.
🛠️ Development
Prerequisites
- Node.js 18.0.0+
- pnpm 8.0.0+ (
npm install -g pnpm)
- VSCode 1.85.0+
- OpenSpec CLI 1.1.0+ (installation)
Development Setup
# Clone and install
git clone <repo-url>
cd openspce-ui
pnpm install
# Build
pnpm run compile # One-time build
pnpm run watch # Watch mode
# Debug
# Press F5 in VSCode to launch Extension Development Host
Publishing
0.2.5 is prepared in-repo (A+B track); 0.2.4 was the prior formal release. Registry publish (Open VSX / VS Code Marketplace) follows merge and tag — see docs/PUBLISHING.md for publisher setup, tokens, and release steps.
Project Structure
openspce-ui/
├── src/
│ ├── extension/ # Extension host (Node.js)
│ │ ├── services/ # CLI, FileManager, DataManager
│ │ ├── commands/ # Command handlers
│ │ ├── providers/ # Webview providers
│ │ └── utils/ # Logger, helpers
│ └── webview/ # React app
├── openspec/ # OpenSpec workspace
│ ├── changes/
│ │ └── vscode-extension-mvp/ # This project
│ ├── specs/
│ └── config.yaml
├── .vscode/
│ ├── launch.json # Debug config
│ └── tasks.json # Build tasks
├── esbuild.js # Extension bundler
├── vite.config.ts # Webview bundler
└── package.json
Scripts
pnpm run compile # Build extension + webview once
pnpm run watch # Watch extension changes
pnpm run build # Same as compile (extension + webview)
pnpm test # Run unit tests (Vitest)
Tech Stack
| Layer | Technology |
|---|
| Backend | TypeScript, Node.js, VSCode API |
| Frontend | React 19, Tailwind CSS, Radix UI |
| Build | esbuild (extension), Vite (webview) |
| Tools | pnpm, ESLint, Prettier |
📊 Progress
Current: v0.2.3 — P0 usability release (CLI recovery, smart launch defaults, task Next/Copy actions).
See CHANGELOG.md for release history. Historical MVP planning artifacts live under openspec/changes/archive/2026-02-11-vscode-extension-mvp/.
🐛 Known Issues & Troubleshooting
Troubleshooting
-
Extension doesn’t activate
Ensure the workspace root contains openspec/config.yaml. Check Output → Extension Host.
-
Dashboard or webview blank
Run pnpm run build and ensure dist/webview/ exists. In Extension Development Host, use "Developer: Toggle Developer Tools" and check the webview iframe console.
-
OpenSpec CLI not found
Install OpenSpec CLI and ensure openspec is on PATH in the environment where VSCode is launched.
-
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.
-
Tasks don’t update on disk
Ensure the workspace has write access to openspec/changes/<name>/tasks.md. Check Output → OpenSpec for errors.
-
Build or test failures
rm -rf dist node_modules && pnpm install && pnpm run build && pnpm test
Fixed
- ✅ JSON parse error with "No specs found" (v0.1.0)
📚 Documentation
🤝 Contributing
Contributions welcome. Open an issue or pull request on GitHub.
To contribute:
- Review docs/ARCHITECTURE.md
- Run
pnpm install, pnpm run build, and pnpm test before submitting
- Follow code style (ESLint + Prettier)
📄 License
MIT — see LICENSE
🙏 Acknowledgments
Version: 0.2.5
Last Updated: 2026-10
Status: 🟡 0.2.5 prepared in-repo; tag and registry publish are follow-up after merge
