Spectra

A VS Code extension for visualizing and managing Spec-Driven Development (SDD) workspaces.

Spectra reads your specs/ and .ai/ directories and gives you a structured view of every specification — its status, task progress, and health — without leaving the editor.

Features

Tree View

Spectra adds an activity bar panel that organizes all specs by status in real time.

• Status groups — In Progress, Approved, Draft, Done, Abandoned
• Task progress — [3/8] badge next to each spec that has a tasks.md
• Health indicators — ⚠ icon on specs with open [NEEDS CLARIFICATION] items or missing required files
• Blocked count — status groups show how many specs are blocked (e.g. 2 bloqueadas)
• Auto-refresh — tree updates automatically when any spec file changes on disk

Commands

All commands are available from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and, where applicable, from the tree view's context menu.

Kanban Board

Opens a full-width webview with all specs organized in status columns. Each card shows the spec title, task progress bar, and a warning badge for specs that need attention. Clicking a card opens the spec.md in the editor.

The board syncs automatically whenever specs change — no manual refresh needed.

Status Bar

When you open any file inside a spec folder, the status bar shows the active spec:

[001] autenticacao — in-progress

A ⚠ icon appears when the spec has open clarifications or missing files. Click the item to open the spec search.

Spec Reference Hover

Hover over a spec slug or reference in any TypeScript, JavaScript, or Markdown file to see a summary popup:

// TODO: implements spec/003-autenticacao

Supported patterns:

• spec/003-autenticacao
• spec: 003-autenticacao
• 003-autenticacao (bare slug anywhere in the file)

The popup shows the spec's title, status, creation date, and any pending clarifications.

CodeLens in tasks.md

A live progress indicator appears at the top of every tasks.md file:

✓ 5/12 tasks concluídas (41%)

Updates as you type. Click it to jump to the parent spec.md.

Activation

Spectra activates automatically when the opened workspace contains a specs/ or .ai/ directory.

SDD Conventions

Spectra is built around the following file structure. If your project follows a different layout, the extension will not activate.

specs/
├── INDEX.md              # Auto-generated index by status
├── NNN-slug/             # One folder per spec (e.g. 001-authentication)
│   ├── spec.md           # Required — specification (what & why)
│   ├── plan.md           # Optional — implementation plan (how)
│   └── tasks.md          # Optional — task checklist (steps)
└── archive/
    └── YYYY-Qn/          # Quarterly archive

.ai/
├── rules/                # Domain-specific AI guidance files
└── templates/            # Code templates with placeholders

spec.md format

# Title of the Feature

**Status:** draft
**Created:** 2026-01-15
**ID:** 001

## Overview
...

## Requirements
...

Status values: draft · approved · in-progress · done · abandoned

Spec health rules

Spectra flags specs that are in an inconsistent state:

A spec is also flagged if its spec.md contains any [NEEDS CLARIFICATION: ...] markers.

Resolving clarifications

The Spectra: Resolve Clarification command lets you pick an open item and type a resolution. Spectra rewrites the marker in place:

<!-- Before -->
[NEEDS CLARIFICATION: Should this support multi-tenancy?]

<!-- After -->
[RESOLVED: Should this support multi-tenancy? → Yes, via workspace scoping — see ADR-007]

Creating the next phase

The Spectra: Next Phase command (context menu on a spec node) creates the next missing file in the SDD sequence:

1. No plan.md → creates plan.md and opens it for editing
2. Has plan.md, no tasks.md → creates tasks.md and opens it
3. Both exist → shows an info message

If your workspace has .ai/templates/plan.template.md or .ai/templates/tasks.template.md, those templates are used (with {{title}}, {{slug}}, {{date}} replaced). Otherwise, a built-in template is used.

Requirements

• VS Code 1.90.0 or later
• A workspace with a specs/ or .ai/ directory

Extension Settings

Spectra has no user-configurable settings.

Known Limitations

• Only the first workspace folder is scanned. Multi-root workspaces are not yet supported.
• The specs/archive/ directory is not shown in the tree view.