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

1. Open a workspace that contains openspec/config.yaml.
2. Run OpenSpec: Open Dashboard.
3. Check the active Root, then select New Change.
4. 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.
5. Review Proposal, Specs, Design, and Tasks, then select Open Cursor · Apply (or Copy Apply in copy-only mode) and continue in your Agent.
6. 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

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

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

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.

---

🏗️ 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

Document	Description
docs/ARCHITECTURE.md	High-level architecture
CHANGELOG.md	Release history
docs/PUBLISHING.md	Package and publish to Open VSX / VS Marketplace
docs/USER_GUIDE.md	End-user guide

---

🤝 Contributing

Contributions welcome. Open an issue or pull request on GitHub.

To contribute:

1. Review docs/ARCHITECTURE.md
2. Run pnpm install, pnpm run build, and pnpm test before submitting
3. Follow code style (ESLint + Prettier)

---

📄 License

MIT — see LICENSE

---

🙏 Acknowledgments

• OpenSpec - Spec-driven workflow tool
• VSCode Extension Samples

---

Version: 0.2.5
Last Updated: 2026-10
Status: 🟡 0.2.5 prepared in-repo; tag and registry publish are follow-up after merge