Spectrum

VS Code extension for Spectrum spec-driven development - maintain bidirectional traceability between specifications and code with IntelliSense, navigation, and validation.

What is Spectrum? A specification management system that maintains bidirectional links between spec.yaml specifications and code annotations (@specs/path), enabling instant navigation between requirements and implementation. Perfect for AI-native development workflows where maintaining project context is critical.

Features

🔍 Go to Definition

Click on any @specs/ reference (or press F12) to jump to the exact location in spec.yaml. Works on individual path segments too - click on cli in @specs/cli/show to navigate to the cli spec.

💡 IntelliSense / Autocomplete

Type @specs/ and get intelligent autocomplete suggestions with spec titles, descriptions, and metadata. Navigate through the spec tree hierarchically.

🎯 Hover Information

Hover over any spec reference to see its title, description, priority, status, and a link to open it in spec.yaml.

⚠️ Validation

Real-time diagnostics show warnings for invalid spec references that don't exist in your spec.yaml.

🎨 Syntax Highlighting

Spec references are highlighted in Spectrum brand colors for easy visual identification.

Installation

Option 1: From Marketplace (Private)

This extension is published as unlisted. You'll need the direct link to install it.

1. Go to the extension page
2. Click "Install"

Option 2: Manual Installation (.vsix)

1. Download the latest .vsix file from Releases
2. In VS Code: Extensions → ... menu → Install from VSIX...
3. Select the downloaded .vsix file

Usage

The extension automatically activates when it detects a spec.yaml or spec.yml file in your workspace.

Go to Definition

• Press F12 on any @specs/ reference
• Or Ctrl+Click (Windows/Linux) / Cmd+Click (Mac)
• Click on any segment: cli in @specs/cli/show/depth-control jumps to cli spec

Autocomplete

• Type @specs/ to trigger suggestions
• Use arrow keys to navigate, Enter to select
• Manually type / to navigate deeper into the spec tree

View Hover Information

• Hover over any spec reference to see its details
• Shows title, description, priority, status
• Includes link to open in spec.yaml

Example

// @specs/cli/show: Show Command Implementation
// Autocomplete will suggest 'show' after typing '@specs/cli/'
// Hover to see: "Show Command Implementation"
// F12 to jump to spec.yaml:123
function showCommand() {
  // ...
}

Development

Prerequisites

• Node.js and Yarn
• VS Code

Local Testing

IMPORTANT: To debug the extension, you must open the packages/vscode folder directly in VS Code, NOT the root Spectrum folder.

1. Install dependencies from the Spectrum monorepo root:

   yarn install
   

2. Open the extension directory in a NEW VS Code window:

   cd packages/vscode
   code .
   

   Or: File > New Window, then open the packages/vscode folder

3. Press F5 to launch the Extension Development Host

   • The extension will automatically compile
   • A new window opens with the Spectrum root folder loaded
   • The extension is now active in that window

4. Test the "Go to Definition" functionality:

   • Open any file with @specs/ references (e.g., packages/cli/src/commands/show.ts)
   • Place cursor on a spec reference like @specs/cli/show
   • Press F12 or Ctrl+Click to jump to the definition in spec.yaml

5. To verify the extension is loaded:

   • Press Ctrl+Shift+P → "Developer: Show Running Extensions"
   • Look for "Spectrum" in the list

Building

yarn compile

The compiled extension will be in the out/ directory.

Technical Details

• Uses @spectrum/core for spec.yaml parsing
• Leverages VS Code's DefinitionProvider API
• Matches spec references using regex: /@specs\/([a-zA-Z0-9_.-]+(?:\/[a-zA-Z0-9_.-]+)*)/g

License

Same as Spectrum project