OpenSpec for Copilot

OpenSpec for Copilot is a VS Code extension that brings Spec-Driven Development (SDD) to your workflow, leveraging OpenSpec prompts and chat agents like GitHub Copilot Chat.

It allows you to visually manage Specs, Steering documents (AGENTS.md), and custom prompts, seamlessly integrating with GitHub Copilot Chat by default, with optional Codex Chat support.

Features

📝 Spec Management

• Create Specs: Run OpenSpec for Copilot: Create New Spec (openspec-for-copilot.spec.create) to open the creation dialog. Define your summary, product context, and constraints.
• Generate with Chat: The extension compiles your input into an optimized OpenSpec prompt and sends it to the configured chat agent (GitHub Copilot Chat by default) to generate the full specification (Requirements, Design, Tasks).
• Manage Specs: Browse generated specs in the Specs view.
• Detailed Design: Generate a detailed design document from a change, and update specs based on it.
• Create GitHub Issue: Generate a GitHub issue from a spec change, including references to proposal, design, and tasks.
• Execute Tasks: Open tasks.md and use the "Start Task" CodeLens to send task context to the configured chat agent for implementation.

🧩 Prompt Management

• Custom Prompts: Manage Markdown prompts under .github/prompts (configurable) alongside instructions and agents to keep all project guidance in one place.
• Project Instructions & Agents: The Prompts explorer now shows Project Instructions and Project Agents groups, surfacing .github/instructions and .github/agents files (in that order) so you can reference reusable instructions and agent definitions without leaving VS Code.
• Run Prompts: Execute prompts directly from the tree view, passing the context to the configured chat agent.
• Rename or Delete: Use the item context menu to rename or delete prompts, instructions, and agents without leaving the explorer. Rename always appears above Delete for quick edits.

Installation

Prerequisites

• Visual Studio Code 1.84.0 or newer.
• GitHub Copilot Chat extension must be installed (default).
• For Codex mode, a VS Code extension that provides the chatgpt.addToThread command must be installed.
• OpenSpec must be globally installed and initialized.

OpenSpec Global Installation and Initialization:

Step 1: Install the CLI globally

npm install -g @fission-ai/openspec@latest

Verify installation:

openspec --version

Step 2: Initialize OpenSpec in your project

Navigate to your project directory:

cd my-project

Run the initialization:

openspec init

Migrating to OpenSpec v1

OpenSpec for Copilot v1.0.0+ requires OpenSpec CLI v1. If you're upgrading from an earlier version:

Prerequisites

• Node.js 18 or higher
• npm or yarn

Migration Steps

1. Install OpenSpec CLI v1:

   npm install -g openspec@latest

2. Initialize OpenSpec v1 in your workspace:

   cd /path/to/your/workspace
   openspec init

3. Verify prompt files were created: Check that .github/prompts/ contains:

   • opsx-new.prompt.md
   • opsx-apply.prompt.md
   • opsx-archive.prompt.md
   • opsx-continue.prompt.md
   • opsx-ff.prompt.md
   • opsx-explore.prompt.md
   • opsx-verify.prompt.md
   • opsx-sync.prompt.md
   • opsx-bulk-archive.prompt.md
   • opsx-onboard.prompt.md

Legacy File Support

The extension will temporarily use legacy v0.x prompt files if v1 files are not found, but will display deprecation warnings. Legacy support will be removed in a future release.

Troubleshooting

"OpenSpec v1 prompt files not found" error:

• Ensure you've run openspec init in your workspace root
• Verify .github/prompts/ directory exists
• Check that OpenSpec CLI is v1.0.0 or higher: openspec --version

"Using legacy OpenSpec v0.x prompt file" warning:

• Run openspec init to generate v1 files
• The extension will continue working with legacy files but will show warnings

Marketplace

Search for "OpenSpec for Copilot" in the VS Code Marketplace and install the extension.

From Local VSIX

1. Build the package with npm run package (produces openspec-for-copilot-<version>.vsix).
2. Install via code --install-extension openspec-for-copilot-<version>.vsix.

Usage

1. Create a Spec

1. Open the Specs view in the Activity Bar.

2. Click Create New Spec.

3. Fill in the details (Product Context is required).

4. Click Create Spec. This will open chat with a generated prompt.

5. Follow the chat instructions to generate the spec files.

   

2. Detailed Design Workflow (Optional)

1. Right-click on a Change ID in the Specs view.
2. Select Create Detailed Design. Chat will generate a detailed design document.
3. Once the design is finalized, right-click the change again and select Update Specs from Detailed Design to synchronize other documents.

3. Implement Tasks

1. Open a generated tasks.md file.

2. Click Start All Tasks above a checklist item.

3. Chat will open with the task context. Interact with it to implement the code.

   

4. Create GitHub Issue

1. Right-click on a Change ID in the Specs view.
2. Select Create GitHub Issue from the context menu.
3. Chat will open with a prompt to create a GitHub issue based on the spec documents.
4. Review the generated issue title and body, then create the issue.

5. Archive Change

1. Right-click on a Change ID in the Specs view.

2. Select Archive Change from the context menu.

3. The change will be moved to the archive.

   

Configuration

All settings live under the openspec-for-copilot namespace.

Setting	Type	Default	Purpose
aiAgent	string	github-copilot	Select which chat agent to use for sending prompts (github-copilot or codex).
chatLanguage	string	English	The language GitHub Copilot should use for responses.
copilot.specsPath	string	openspec	Workspace-relative path for generated specs.
copilot.promptsPath	string	.github/prompts	Workspace-relative path for Markdown prompts.
views.specs.visible	boolean	true	Show or hide the Specs explorer.
views.prompts.visible	boolean	true	Toggle the Prompts explorer.
views.steering.visible	boolean	true	Toggle the Steering explorer.
views.settings.visible	boolean	true	Toggle the Settings overview.
customInstructions.global	string	""	Global custom instructions appended to all prompts.
customInstructions.createSpec	string	""	Custom instructions for "Create Spec".
customInstructions.startAllTask	string	""	Custom instructions for "Start All Tasks".
customInstructions.archiveChange	string	""	Custom instructions for "Archive Change".
customInstructions.runPrompt	string	""	Custom instructions for "Run Prompt".

Note: In Codex mode, prompts are written to temporary Markdown files under ~/.codex/.tmp/ and sent via chatgpt.addToThread.

Paths accept custom locations inside the workspace; the extension mirrors watchers to match custom directories.

Workspace Layout

.github/
├── prompts/                # Markdown prompts
├── agents/                 # Project agent definitions surfaced in the Prompts view
openspec/
├── AGENTS.md               # Project-specific steering rules
├── project.md              # Project specification
├── <spec>/
│   ├── requirements.md
│   ├── design.md
│   └── tasks.md
LICENSE
src/
├── extension.ts            # Activation, command registration, tree providers
├── features/               # Spec and steering managers
├── providers/              # TreeDataProviders, CodeLens, webviews
├── services/               # Prompt loader (Handlebars templates)
├── utils/                  # Config manager, Copilot chat helpers
└── prompts/                # Prompt source markdown and generated TypeScript
webview-ui/                 # React + Vite webview bundle
scripts/
└── build-prompts.js        # Markdown → TypeScript prompt compiler

Development

1. Install dependencies for both the extension and webview UI:
   • npm run install:all
2. Build prompts and bundle the extension:
   • npm run build (runs prompt compilation, extension bundle, and webview build)
3. Launch the development host:
   • Press F5 inside VS Code or run the Extension launch configuration.
4. Live development:
   • npm run watch (TypeScript watch + webview dev server)
   • npm --prefix webview-ui run dev (webview in isolation)
5. Generate prompt modules when editing markdown under src/prompts:
   • npm run build-prompts

Testing and Quality

• Unit tests: npm test, npm run test:watch, or npm run test:coverage (Vitest).
• Linting, formatting, and static checks: npm run lint, npm run format, npm run check (Ultracite toolchain).

Packaging

• Produce a VSIX with npm run package (requires vsce).
• The output bundle lives in dist/extension.js; webview assets emit to dist/webview/app/.

License

MIT License. See LICENSE.

Credits

Based on OpenSpec by Fission AI. Originally forked from kiro-for-codex-ide.