openspec-generate-specs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Generate OpenSpec main specifications by analyzing the current project's code, documentation, issues, and pull requests.

Unlike

openspec-propose

(which creates a change with proposal/design/tasks artifacts for future work), this skill writes finished specs directly to

openspec/specs/

based on what already exists in the project.

Input: Optionally specify which capabilities or areas to generate specs for. If omitted, analyze the full project and determine capabilities automatically.

Steps

Gather project context

Collect information from all available sources. Prioritize breadth over depth — skim first, then deep-dive into relevant areas.

a. Project documentation:
- Read
```
AGENTS.md
```
  (or
```
CONTRIBUTING.md
```
  ,
```
README.md
```
  ) for architecture overview, conventions, and design decisions
- Read
```
docs/
```
  directory for feature specs, design docs, BDD features (
```
.feature
```
  files)
- Read
```
openspec/config.yaml
```
  for project context and rules
b. Codebase structure:
- Scan
```
src/
```
  directory tree to understand module organization
- Read key files (entry points, type definitions, core modules) to understand capabilities
- Identify the main functional areas / capabilities the system provides
c. GitHub issues and PRs (if available):
- Use GitHub MCP tools to fetch recent open/closed issues for requirements context
- Use GitHub MCP tools to fetch recent merged PRs for implemented features
- Extract requirement-like information (feature requests, bug fixes, design decisions)
d. Existing specs (if any):
- Read
```
openspec/specs/
```
  to understand what's already documented
- Identify gaps between existing specs and actual implementation
Identify capabilities
Based on the gathered context, determine the project's main capability areas. Each capability becomes a spec file at
```
openspec/specs/<capability>/spec.md
```
.
Use the AskUserQuestion tool to confirm the identified capabilities before proceeding:

"I've identified these capabilities from the project. Which should I generate specs for?"

Present the list with brief descriptions. Let the user select all or a subset.
Naming convention: Use kebab-case for capability names (e.g.,
```
memory-system
```
,
```
platform-abstraction
```
,
```
acp-integration
```
).
Check existing specs

For each selected capability:
- If
```
openspec/specs/<capability>/spec.md
```
  already exists, read it
- Use AskUserQuestion tool to ask: "Spec for
```
<capability>
```
  already exists. Overwrite, merge, or skip?"
  - Overwrite: Replace entirely with newly generated spec
  - Merge: Add missing requirements/scenarios to existing spec, preserve existing content
  - Skip: Leave as-is
Generate specs

For each capability, create a spec file following the OpenSpec spec format.

Use the TodoWrite tool to track progress through capabilities.
Spec file structure (
```
openspec/specs/<capability>/spec.md
```
):
markdown
```
# <Capability Name>

## Purpose

<Brief description of what this capability does and why it exists.>

## Requirements

### Requirement: <Requirement Name>

<The system SHALL/SHOULD/MAY description using RFC 2119 language.>

#### Scenario: <Scenario Name>
- **GIVEN** <precondition>
- **WHEN** <action>
- **THEN** <expected outcome>

#### Scenario: <Another Scenario>
- **GIVEN** <precondition>
- **WHEN** <action>
- **THEN** <expected outcome>
```
Writing guidelines:
- Use RFC 2119 keywords (SHALL, SHOULD, MAY) for requirement strength
- Derive requirements from actual code behavior, not aspirational features
- Include scenarios that reflect real code paths (check tests for scenario ideas)
- Reference source files in requirement descriptions when helpful (e.g., "Implemented in
```
src/core/workspace-manager.ts
```
  ")
- Keep requirements atomic — one concern per requirement
- Group related scenarios under their parent requirement
Write spec files

For each capability:
bash
```
mkdir -p openspec/specs/<capability>
```
Write the spec content to
```
openspec/specs/<capability>/spec.md
```
.
After writing each file, verify it exists and show brief progress.
Validate output

Run validation if available:
bash
```
openspec validate --specs --json
```
If validation fails, fix issues and re-validate.

Show summary

Display what was generated:

## Specs Generated

| Capability | Requirements | Scenarios | Status |
|------------|-------------|-----------|--------|
| <name>     | N           | M         | New/Merged/Overwritten |

Total: X capabilities, Y requirements, Z scenarios

Files written to `openspec/specs/`.

Source Priority

When information conflicts across sources, prefer in this order:

Actual code behavior (ground truth)
Test assertions (verified behavior)
BDD feature files / design docs (intended behavior)
GitHub issues/PRs (discussed behavior)
README / AGENTS.md (described behavior)

Guardrails

Always confirm capability list with user before generating
Never fabricate requirements not supported by code or documentation
If a capability area is ambiguous, ask for clarification
Preserve existing spec content when merging (only add, don't remove unless user confirms)
Each spec file must have at least a Purpose section and one requirement
Use consistent formatting across all generated spec files

通过分析当前项目的代码、文档、议题和拉取请求生成OpenSpec主规范。

与

openspec-propose

（为未来工作创建包含提案/设计/任务工件的变更）不同，此技能会根据项目中已有的内容直接将完成的规范写入

openspec/specs/

目录。

输入：可选择性指定要为哪些功能或领域生成规范。若省略此参数，则分析整个项目并自动识别功能领域。

步骤

收集项目上下文

从所有可用来源收集信息。优先保证广度而非深度——先快速浏览，再深入相关领域。

a. 项目文档：
- 阅读
```
AGENTS.md
```
  （或
```
CONTRIBUTING.md
```
  、
```
README.md
```
  ）了解架构概述、约定和设计决策
- 阅读
```
docs/
```
  目录下的功能规范、设计文档、BDD特性文件（
```
.feature
```
  文件）
- 阅读
```
openspec/config.yaml
```
  获取项目上下文和规则
b. 代码库结构：
- 扫描
```
src/
```
  目录树，理解模块组织方式
- 阅读关键文件（入口文件、类型定义、核心模块），了解系统功能
- 识别系统提供的主要功能领域/能力
c. GitHub议题和拉取请求（若可用）：
- 使用GitHub MCP工具获取近期的开放/已关闭议题，了解需求背景
- 使用GitHub MCP工具获取近期合并的拉取请求，了解已实现的功能
- 提取类需求信息（功能请求、Bug修复、设计决策）
d. 现有规范（若存在）：
- 阅读
```
openspec/specs/
```
  目录，了解已有的文档内容
- 识别现有规范与实际实现之间的差距
识别功能领域
根据收集到的上下文，确定项目的主要功能领域。每个功能领域对应一个规范文件，路径为
```
openspec/specs/<capability>/spec.md
```
。
在继续之前，使用AskUserQuestion工具确认识别出的功能领域：

"我已从项目中识别出以下功能领域，请问需要为哪些生成规范？"

列出功能领域并附上简要描述，让用户选择全部或部分。
命名规范：功能名称使用kebab-case（短横线分隔）格式（例如：
```
memory-system
```
、
```
platform-abstraction
```
、
```
acp-integration
```
）。
检查现有规范

针对每个选中的功能领域：
- 若
```
openspec/specs/<capability>/spec.md
```
  已存在，则阅读该文件
- 使用AskUserQuestion工具询问："
```
<capability>
```
  的规范已存在。是否覆盖、合并或跳过？"
  - 覆盖：用新生成的规范完全替换原有内容
  - 合并：将缺失的需求/场景添加到现有规范中，保留原有内容
  - 跳过：保持原有内容不变
生成规范

针对每个功能领域，按照OpenSpec规范格式创建规范文件。

使用TodoWrite工具跟踪各功能领域的进度。
规范文件结构（
```
openspec/specs/<capability>/spec.md
```
）：
markdown
```
# <功能名称>

## 用途

<简要描述该功能的作用及存在意义。>

## 需求

### 需求：<需求名称>

<使用RFC 2119规定的表述（SHALL/SHOULD/MAY）描述系统要求。>

#### 场景：<场景名称>
- **GIVEN** <前置条件>
- **WHEN** <操作>
- **THEN** <预期结果>

#### 场景：<另一个场景>
- **GIVEN** <前置条件>
- **WHEN** <操作>
- **THEN** <预期结果>
```
编写指南：
- 使用RFC 2119关键字（SHALL、SHOULD、MAY）明确需求强度
- 从实际代码行为推导需求，而非基于理想功能
- 包含能反映真实代码路径的场景（可参考测试用例获取场景思路）
- 必要时在需求描述中引用源文件（例如："实现于
```
src/core/workspace-manager.ts
```
  "）
- 保持需求原子性——每个需求只关注一个关注点
- 将相关场景归到对应的父需求下
写入规范文件

针对每个功能领域：
bash
```
mkdir -p openspec/specs/<capability>
```
将规范内容写入
```
openspec/specs/<capability>/spec.md
```
。
每个文件写入完成后，验证其存在并展示简要进度。
验证输出

若有验证工具则运行验证：
bash
```
openspec validate --specs --json
```
若验证失败，修复问题后重新验证。

展示总结

展示生成结果：

## 生成的规范

| 功能领域 | 需求数量 | 场景数量 | 状态 |
|------------|-------------|-----------|--------|
| <名称>     | N           | M         | 新建/合并/覆盖 |

总计：X个功能领域，Y条需求，Z个场景

文件已写入`openspec/specs/`目录。

来源优先级

当不同来源的信息冲突时，按以下优先级选择：

实际代码行为（基准事实）
测试断言（已验证的行为）
BDD特性文件/设计文档（预期行为）
GitHub议题/拉取请求（讨论中的行为）
README / AGENTS.md（描述的行为）

约束规则

生成前必须与用户确认功能领域列表
不得编造代码或文档未支持的需求
若功能领域存在歧义，需向用户请求澄清
合并时保留现有规范内容（仅添加，除非用户确认否则不删除）
每个规范文件必须至少包含“用途”章节和一条需求
所有生成的规范文件使用统一格式