OpenSpec Workflow

OpenPencil uses OpenSpec for spec-driven development. Specifications are the source of truth for what the system does.

Structure

openspec/
├── specs/              # Source of truth: how the system works now
│   ├── scene-graph/
│   │   └── spec.md
│   ├── canvas-rendering/
│   │   └── spec.md
│   ├── auto-layout/
│   │   └── spec.md
│   └── ...             # 19 capability specs total
├── changes/            # Proposed changes (one directory per change)
│   └── archive/        # Completed changes
└── config.yaml         # Optional configuration

Current Specs

Capability	Description
scene-graph	Flat Map storage, CRUD, hit testing
canvas-rendering	CanvasKit WASM rendering pipeline
canvas-navigation	Pan, zoom, hand tool
selection-manipulation	Click/marquee select, move, resize, rotate
undo-redo	Inverse-command pattern
text-editing	Text tool, Paragraph API, font loading
pen-tool	Vector network model, bezier curves
auto-layout	Yoga WASM flexbox, Shift+A toggle
figma-clipboard	Bidirectional fig-kiwi clipboard
fig-import	.fig file import pipeline
kiwi-codec	Kiwi binary codec, sparse field IDs
editor-ui	Vue 3 panels, toolbar, color picker
snap-guides	Edge/center snapping, rotation-aware
rulers	Canvas rulers, selection highlight
group-ungroup	⌘G/⇧⌘G, position-based sort
desktop-app	Tauri v2, macOS menu bar
testing	Playwright E2E, bun:test unit
scrub-input	Drag-to-scrub numeric inputs
tooling	Vite 7, oxlint, oxfmt, tsgo, VitePress

Workflow

1. Propose a Change

/opsx:propose add-dark-mode

Creates openspec/changes/add-dark-mode/ with:

• proposal.md — why and what changes
• design.md — technical approach
• specs/ — delta specifications (ADDED/MODIFIED/REMOVED requirements)
• tasks.md — implementation checklist

2. Implement

/opsx:apply

Execute tasks from tasks.md, checking off items as they're completed.

3. Archive

/opsx:archive

• Merges delta specs into openspec/specs/ (the baseline)
• Moves the change to openspec/changes/archive/

Spec Format

Each spec file follows a consistent structure:

# capability-name Specification

## Purpose
One-line description of what this capability does.

## Requirements

### Requirement: Name
Description using SHALL/MUST for normative requirements.

#### Scenario: Name
- **WHEN** condition
- **THEN** expected outcome

Every requirement has at least one scenario. Scenarios are potential test cases.

CLI Commands

openspec list                    # List active changes
openspec show <name>             # Show change details
openspec status --change <name>  # Artifact status
openspec archive <name>          # Archive completed change
openspec update                  # Regenerate skills/prompts