openspec

OpenSpec - Spec-Driven Development

Overview

OpenSpec is a Spec-Driven Development (SDD) framework that lets you write specifications before writing code, ensuring the development direction is correct and reducing rework.

When to Use

When planning new features
When feature specifications need to be documented
Change proposal management
Team collaborative development
When the user mentions "spec", "specification", or "SDD"

Quick Reference

CLI commands (dash spec)

Command	Function
`dash spec init .`	Initialize OpenSpec
`dash spec list .`	List active changes
`dash spec view .`	Interactive dashboard
`dash spec show . <name>`	Show change details
`dash spec validate . <name>`	Validate specification format
`dash spec archive . <name>`	Archive completed changes
`dash spec status .`	Quick status overview

OpenSpec native commands

Command	Function
`openspec init`	Initialize
`openspec list`	List changes
`openspec view`	Interactive dashboard
`openspec show <name>`	Show details
`openspec validate <name>`	Validate format
`openspec archive <name>`	Archive changes

SDD Workflow (five-step cycle)

1. SPEC (規格化)
   └── 定義功能規格 → openspec/specs/feature-name.md

2. PROPOSE (提案)
   └── 建立變更提案 → openspec/changes/change-name.md

3. IMPLEMENT (實作)
   └── 根據規格實作程式碼

4. VERIFY (驗證)
   └── 確認實作符合規格

5. ARCHIVE (歸檔)
   └── 完成後歸檔變更 → dash spec archive . change-name

File Structure

project/
└── openspec/
    ├── specs/           # 功能規格
    │   ├── auth.md
    │   └── dashboard.md
    ├── changes/         # 活動變更提案
    │   └── add-login-feature.md
    └── archive/         # 已歸檔的變更
        └── 2026-01-setup-project.md

Spec File Format

---
title: 使用者認證
status: active
created: 2026-01-17
---

# 使用者認證

## 概述
實作使用者登入/登出功能。

## 功能需求
1. 支援 Email + 密碼登入
2. 支援 Google OAuth
3. 記住登入狀態

## API 規格
- POST /api/auth/login
- POST /api/auth/logout
- GET /api/auth/me

## 相關變更
- [[add-login-feature]]

Change File Format

---
title: 新增登入功能
type: feature
status: in-progress
spec: auth
created: 2026-01-17
---

# 新增登入功能

## 變更內容
實作 Email + 密碼登入功能。

## 影響範圍
- `src/auth/` 目錄
- `src/api/routes/auth.ts`

## 測試計畫
1. 單元測試: 登入邏輯
2. 整合測試: API 端點
3. E2E 測試: 登入流程

## Checklist
- [ ] 實作登入表單
- [ ] 實作 API 端點
- [ ] 撰寫測試
- [ ] 更新文件

Best Practices

1. Write specifications before code

Specifications are the blueprint for development
Reduce rework and misunderstandings
Facilitate team communication

2. Keep specifications up to date

Update specifications after implementation
Record change history
Regularly review outdated specifications

3. Make good use of change proposals

One change per feature
Clearly define the scope
Archive promptly after completion

4. Use dash-devtools integration

dash validate . Automatically validate specifications
dash health . Show specification health
dash spec status . Quick overview

Integration with dash-devtools

Validation integration

# 自動偵測 openspec/ 並驗證
dash validate .

# 檢查項目:
# - 目錄結構完整性
# - 規格檔案格式
# - 過期變更提醒

Health score

# 顯示規格健康度
dash health .

# 評分項目:
# - 規格覆蓋率
# - 變更處理率
# - 格式正確性

Installation

# 安裝 OpenSpec CLI
npm install -g @fission-ai/openspec@latest

# 驗證安裝
openspec --version

# 在專案中初始化
cd your-project
dash spec init .

Troubleshooting

openspec is not installed

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

Specification format error

Ensure every .md file has YAML frontmatter:

---
title: 規格標題
status: active
---

# 內容...

Outdated change warning

Use dash spec archive . <name> to archive completed changes.

About this skill