OpenSpec Extension

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.
• 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, and archive 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

• From marketplace: Install OpenSpec from the VS Code Marketplace or Open VSX (e.g. in Cursor).
• 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. Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P).
3. Run OpenSpec: Open Dashboard.
4. Select a change to inspect Proposal, Specs, Design, Tasks, and Verify & Archive tabs.
5. Use the action bar or change-card actions to copy/fill /opsx:continue, /opsx:ff, and /opsx:apply commands.
6. Use the Verify & Archive tab to open an interactive VS Code terminal for /opsx-verify or /opsx-archive, so Agent follow-up questions remain interactive.

Review & Archive is the primary Detail action and starts the interactive /opsx-archive <change> session. Archive Now is a secondary, confirmation-protected direct CLI action enabled only when the bound resolver reports all required artifacts and tasks complete. Dashboard Verify/Archive actions open this Detail surface; they never archive directly.

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	Workflow button behavior: clipboard copies the generated command; adapter routes through the selected adapter
openspec.preferredAgentAdapter	clipboard	Preferred agent executor adapter id used when workflowLaunchMode=adapter: clipboard, cursor, vscode-copilot, claude-code, or opencode
openspec.cursorLaunchMode	clipboard	Cursor adapter launch behavior for non-interactive workflow actions: clipboard copies only; deeplink opens Cursor prompt with fallback copy; chatCommand tries Cursor Chat query with fallback copy; agentCli runs Cursor Agent CLI in headless mode
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 auto or a specific model name
openspec.agentModel	auto	Legacy Cursor Agent CLI model setting; prefer openspec.cursorAgentModel
openspec.debug	false	Enable debug: Verify tab and full prompt in Output when executing tasks

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.

---

🏗️ Architecture

Extension Host (Node.js)          Webview (Browser)
├── DataManager                   ├── HTML (current)
│   ├── OpenSpecCliService        └── React App (Phase 7-9)
│   ├── FileManagerService            ├── Dashboard
│   └── FileWatcherService            ├── TaskList
├── CommandManager                    └── ArtifactViewer
└── DashboardProvider

Design Decisions:

• Data Source: Hybrid (CLI + FileWatcher + Direct reads)
• Backend: OpenSpec CLI via child_process
• Frontend: React + Tailwind CSS + Radix UI (planned)
• Build: esbuild + Vite
• Package Manager: pnpm

See 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

To package and publish the extension to VS Code Marketplace and Open VSX (e.g. for Cursor), 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 (coming)
├── 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 once
pnpm run watch         # Watch extension changes
pnpm run build         # Build everything (future)

Tech Stack

Layer	Technology
Backend	TypeScript, Node.js, VSCode API
Frontend	React 19, Tailwind CSS, Radix UI (planned)
Build	esbuild (extension), Vite (webview)
Tools	pnpm, ESLint, Prettier

---

📊 Progress

Current: MVP complete (Phases 1–12). Post-MVP: Sidebar tree, Spec diff, Archive browser.

✅ Completed Phases

• ✅ Phase 1–6: Setup, CLI, File system, Cache, Commands, Dashboard provider
• ✅ Phase 7–10: React webview, Dashboard & Change detail UI, UI component library
• ✅ Phase 11: Testing & polish (manual checklist, edge cases, performance, docs)
• ✅ Phase 12: Documentation, package config, release prep

Detailed progress: tasks.md

---

🐛 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
ARCHITECTURE.md	High-level architecture
PROGRESS.md	Development log
proposal.md	Project proposal
design.md	Technical design
tasks.md	Task breakdown

---

🤝 Contributing

Currently in active development. Contributions welcome after MVP release.

To contribute:

1. Review ARCHITECTURE.md
2. Check tasks.md
3. Follow code style (ESLint + Prettier)

---

📄 License

MIT (TBD)

---

🙏 Acknowledgments

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

---

Version: 0.1.0
Last Updated: 2026-02
Status: 🟢 MVP complete