SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsopenspec

openspec

Coding & development

View repository

Updated 10-16 06:49

About this skill

OpenSpec Spec-Driven Development Assistant

OpenSpec is a spec-driven AI programming framework. Core philosophy:Align on requirements with AI before writing code。

  • Fluid, not rigid - Handle any artifact at any time, with no phase gating
  • Iterative, not waterfall - Refine understanding while building
  • Simple, not complex - Minimize setup and ceremony
  • Brownfield first - Modify existing systems in a Delta way

Slash Commands

Command Function
/opsx:explore Explore ideas, investigate problems, clarify requirements
/opsx:new Start a new change
/opsx:continue Create the next ready artifact
/opsx:ff Fast-forward - create all planning artifacts at once
/opsx:apply Implement tasks, update artifacts as needed
/opsx:verify Verify implementation completeness, correctness, and consistency
/opsx:sync Sync delta specs to the main specs (optional)
/opsx:archive Archive completed changes
/opsx:bulk-archive Archive multiple changes in batch
/opsx:onboard Interactive tutorial

Workflow Patterns

Quick Feature Flow(when requirements are clear):

/opsx:new → /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive

Exploratory Flow(when requirements are unclear):

/opsx:explore → /opsx:new → /opsx:continue → ... → /opsx:apply

Incremental Flow(when more control is needed):

/opsx:new → /opsx:continue (重复) → /opsx:apply → /opsx:archive

Artifact System (Default Schema: spec-driven)

Artifact dependency chain:

proposal → specs → design → tasks → implement

Artifact types:

  1. proposal.md - Change proposal (Why/What/Impact)
  2. specs/ - Delta specs (ADDED/MODIFIED/REMOVED) → see references/delta-specs-format.md
  3. design.md - Technical design
  4. tasks.md - Task list (with checkboxes) → for authoring specs, see references/tasks-writing-guide.md

Artifact status:BLOCKED(missing dependency) → READY(dependencies complete) → DONE(file exists)

Directory Structure

openspec/
├── config.yaml           # 项目配置（可选）
├── specs/                # 当前系统行为（事实来源）
├── changes/              # 活跃变更
│   └── add-feature/
│       ├── .openspec.yaml
│       ├── proposal.md
│       ├── specs/
│       ├── design.md
│       └── tasks.md
├── archive/              # 已归档变更
└── schemas/              # 自定义工作流（可选）

Core Requirements for tasks.md

For detailed specifications, read references/tasks-writing-guide.md

The two most important principles:

  1. File-level granularity: Each task entry must include [操作类型] 文件路径 - 具体改动描述, and vague tasks that cannot locate files are prohibited
  2. Pilot layering: When the total number of tasks is ≥ 5, you must first divide a "Pilot Batch" to validate the direction, then proceed with the "main tasks"
  3. Dynamic completion during execution：/opsx:apply、/opsx:verify or when manual review discovers missing tasks, first write back to the current change's tasks.md, then continue implementation or acceptance

Format quick reference:

- [ ] [修改] `packages/foo/src/bar.ts` - 增加 processItem() 方法，实现单条数据处理

Dynamic completion during execution

When /opsx:apply、/opsx:verify or manual review discovers missing tasks in the current change, you must first write the missing items back to openspec/changes/<change>/tasks.md, then continue implementation or acceptance.tasks.md is the only executable task source; missing items must not be written only in chat checklists, progress reports, or sub-agent feedback.

Completed tasks must preserve the OpenSpec checkbox format:

- [ ] [操作类型] 路径 - 具体动作与验收标准

A gap was found but not written back to tasks.md you must not declare the related implementation, acceptance, or change as complete. After the task is completed, you must run:

openspec validate <change-name> --strict

Update and Iteration Decisions

相同意图？  → YES: 更新现有变更 / NO: 启动新变更
>50% 重叠？ → YES: 更新现有变更 / NO: 启动新变更
原始能完成？→ NO: 更新现有变更 / YES: 启动新变更

Verification

/opsx:verify Check three dimensions:

  • Completeness - All tasks are complete and requirements are implemented
  • Correctness - Matches the specification intent and handles edge cases
  • Coherence - Design decisions are reflected in the code

Precautions for Executing Long Tasks

  1. File-level granular execution - Modify only one file at a time and mark it complete immediately
  2. Pilot first, then proceed - Complete the "pilot batch" first, and continue with the "main task" after verification passes
  3. Update task files promptly - Immediately update after completing a task tasks.md checkboxes; when missing tasks are found, first add tasks.md and strict validate
  4. Parallel subagents - Launch multiple subagents to complete tasks by module
  5. Reply in Chinese - Always reply to the user in Chinese
  6. Reread task requirements - Reread the specification after context merging
  7. Continuous execution - Complete all at once tasks.md all tasks
  8. Batch scripts prohibited - Use specific file edits, not scripts for batch modifications
  9. Master-subagent scheduling: The master agent reads all tasks, assigns subagents, and monitors feedback; subagents complete tasks strictly as required

Common CLI Commands

openspec init                              # 初始化项目
openspec list                              # 列出活跃变更
openspec status --change <name>            # 查看工件状态
openspec validate <name> --strict          # 严格格式校验
openspec archive <name> --yes              # 归档变更

For configuration, custom Schema, and troubleshooting, see references/configuration.md

Reference Files

File Content
references/tasks-writing-guide.md tasks.md writing specification (file-level granularity + pilot layering details)
references/delta-specs-format.md Delta Specs complete format specification
references/configuration.md config.yaml configuration, custom Schema, troubleshooting

External Reference Resources