openspec-proposal-creation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Specification Proposal Creation

规范提案创建

Creates comprehensive change proposals following spec-driven development methodology.

遵循规范驱动开发方法论创建全面的变更提案。

Quick Start

快速开始

Creating a spec proposal involves three main outputs:

proposal.md - Why, what, and impact summary
tasks.md - Numbered implementation checklist
spec-delta.md - Formal requirement changes (ADDED/MODIFIED/REMOVED)

Basic workflow: Generate change ID → scaffold directories → draft proposal → create spec deltas → validate structure

创建规范提案包含三个主要输出：

proposal.md - 原因、内容及影响摘要
tasks.md - 编号的实施检查清单
spec-delta.md - 正式的需求变更（新增/修改/移除）

基础工作流：生成变更ID → 搭建目录结构 → 起草提案 → 创建规范差异 → 验证结构

Workflow

工作流

Copy this checklist and track progress:

Proposal Progress:
- [ ] Step 1: Review existing specifications
- [ ] Step 2: Generate unique change ID
- [ ] Step 3: Scaffold directory structure
- [ ] Step 4: Draft proposal.md (Why/What/Impact)
- [ ] Step 5: Create tasks.md implementation checklist
- [ ] Step 6: Write spec deltas with EARS format
- [ ] Step 7: Validate proposal structure
- [ ] Step 8: Present for user approval

复制以下检查清单并跟踪进度：

Proposal Progress:
- [ ] Step 1: Review existing specifications
- [ ] Step 2: Generate unique change ID
- [ ] Step 3: Scaffold directories
- [ ] Step 4: Draft proposal.md (Why/What/Impact)
- [ ] Step 5: Create tasks.md implementation checklist
- [ ] Step 6: Write spec deltas with EARS format
- [ ] Step 7: Validate proposal structure
- [ ] Step 8: Present for user approval

Step 1: Review existing specifications

步骤1：审阅现有规范

Before creating a proposal, understand the current state:

bash

undefined

创建提案前，先了解当前状态：

bash

undefined

List all existing specs

find spec/specs -name "spec.md" -type f

List active changes to avoid conflicts

find spec/changes -maxdepth 1 -type d -not -path "*/archive"

Search for related requirements

grep -r "### Requirement:" spec/specs/

undefined

grep -r "### Requirement:" spec/specs/

undefined

Step 2: Generate unique change ID

步骤2：生成唯一变更ID

Choose a descriptive, URL-safe identifier:

Format:

add-<feature>

fix-<issue>

update-<component>

remove-<feature>

Examples:

```
add-user-authentication
```
```
fix-payment-validation
```
```
update-api-rate-limits
```
```
remove-legacy-endpoints
```

Validation: Check for conflicts:

bash

ls spec/changes/ | grep -i "<proposed-id>"

选择一个描述性的、符合URL安全规则的标识符：

格式：

add-<feature>

fix-<issue>

update-<component>

remove-<feature>

示例：

```
add-user-authentication
```
```
fix-payment-validation
```
```
update-api-rate-limits
```
```
remove-legacy-endpoints
```

验证：检查是否存在冲突：

bash

ls spec/changes/ | grep -i "<proposed-id>"

Step 3: Scaffold directory structure

步骤3：搭建目录结构

Create the change folder with standard structure:

bash

undefined

创建带有标准结构的变更文件夹：

bash

undefined

Replace {change-id} with actual ID

mkdir -p spec/changes/{change-id}/specs/{capability-name}


**Example**:
```bash
mkdir -p spec/changes/add-user-auth/specs/authentication

mkdir -p spec/changes/{change-id}/specs/{capability-name}


**示例**：
```bash
mkdir -p spec/changes/add-user-auth/specs/authentication

Step 4: Draft proposal.md

步骤4：起草proposal.md

Use the template at templates/proposal.md as starting point.

Required sections:

Why: Problem or opportunity driving this change
What Changes: Bullet list of modifications
Impact: Affected specs, code, APIs, users

Tone: Clear, concise, decision-focused. Avoid unnecessary background.

以templates/proposal.md中的模板为起点。

必填章节：

原因：驱动此变更的问题或机遇
变更内容：修改项的项目符号列表
影响：受影响的规范、代码、API、用户

语气：清晰、简洁、聚焦决策。避免不必要的背景信息。

Step 5: Create tasks.md implementation checklist

步骤5：创建tasks.md实施检查清单

Break implementation into concrete, testable tasks. Use the template at templates/tasks.md.

Format:

markdown

undefined

将实施工作拆分为具体的、可测试的任务。使用templates/tasks.md中的模板。

格式：

markdown

undefined

Implementation Tasks

[First concrete task]
[Second concrete task]
[Test task]
[Documentation task]


**Best practices**:
- Each task is independently completable
- Include testing and validation tasks
- Order by dependencies (database before API, etc.)
- 5-15 tasks is typical; split if more needed

[First concrete task]
[Second concrete task]
[Test task]
[Documentation task]


**最佳实践**：
- 每个任务可独立完成
- 包含测试和验证任务
- 按依赖关系排序（如先数据库后API等）
- 通常5-15个任务；若超过则拆分

Step 6: Write spec deltas with EARS format

步骤6：使用EARS格式编写规范差异

This is the most critical step. Spec deltas use EARS format (Easy Approach to Requirements Syntax).

For complete EARS guidelines, see reference/EARS_FORMAT.md

Delta operations:

```
## ADDED Requirements
```
- New capabilities
```
## MODIFIED Requirements
```
- Changed behavior (include full updated text)
```
## REMOVED Requirements
```
- Deprecated features

Basic requirement structure:

markdown

undefined

这是最关键的步骤。规范差异采用EARS格式（Easy Approach to Requirements Syntax，简易需求语法方法）。

完整EARS指南，请参阅reference/EARS_FORMAT.md

差异操作：

```
## ADDED Requirements
```
- 新能力
```
## MODIFIED Requirements
```
- 变更的行为（包含完整的更新文本）
```
## REMOVED Requirements
```
- 已弃用的功能

基础需求结构：

markdown

undefined

ADDED Requirements

Requirement: User Login

WHEN a user submits valid credentials, the system SHALL authenticate the user and create a session.

Scenario: Successful Login

GIVEN a user with email "user@example.com" and password "correct123" WHEN the user submits the login form THEN the system creates an authenticated session AND redirects to the dashboard


**For validation patterns**, see [reference/VALIDATION_PATTERNS.md](reference/VALIDATION_PATTERNS.md)

GIVEN a user with email "user@example.com" and password "correct123" WHEN the user submits the login form THEN the system creates an authenticated session AND redirects to the dashboard


**验证模式**，请参阅[reference/VALIDATION_PATTERNS.md](reference/VALIDATION_PATTERNS.md)

Step 7: Validate proposal structure

步骤7：验证提案结构

Run these checks before presenting to user:

markdown

Structure Checklist:
- [ ] Directory exists: `spec/changes/{change-id}/`
- [ ] proposal.md has Why/What/Impact sections
- [ ] tasks.md has numbered task list (5-15 items)
- [ ] Spec deltas have operation headers (ADDED/MODIFIED/REMOVED)
- [ ] Requirements follow `### Requirement: <name>` format
- [ ] Scenarios use `#### Scenario:` format (4 hashtags)

Automated checks:

bash

undefined

提交给用户前运行以下检查：

markdown

Structure Checklist:
- [ ] Directory exists: `spec/changes/{change-id}/`
- [ ] proposal.md has Why/What/Impact sections
- [ ] tasks.md has numbered task list (5-15 items)
- [ ] Spec deltas have operation headers (ADDED/MODIFIED/REMOVED)
- [ ] Requirements follow `### Requirement: <name>` format
- [ ] Scenarios use `#### Scenario:` format (4 hashtags)

自动化检查：

bash

undefined

Count delta operations (should be > 0)

grep -c "## ADDED|MODIFIED|REMOVED" spec/changes/{change-id}/specs/**/*.md

Verify scenario format (should show line numbers)

grep -n "#### Scenario:" spec/changes/{change-id}/specs/**/*.md

Check requirement headers

grep -n "### Requirement:" spec/changes/{change-id}/specs/**/*.md

undefined

grep -n "### Requirement:" spec/changes/{change-id}/specs/**/*.md

undefined

Step 8: Present for user approval

步骤8：提交给用户审批

Summarize the proposal clearly:

markdown

undefined

清晰总结提案：

markdown

undefined

Proposal Summary

Change ID: {change-id} Scope: {brief description}

Files created:

spec/changes/{change-id}/proposal.md
spec/changes/{change-id}/tasks.md
spec/changes/{change-id}/specs/{capability}/spec-delta.md

Next steps: Review the proposal. If approved, say "openspec implement" or "apply the change" to begin implementation.

undefined

Change ID: {change-id} Scope: {brief description}

Files created:

spec/changes/{change-id}/proposal.md
spec/changes/{change-id}/tasks.md
spec/changes/{change-id}/specs/{capability}/spec-delta.md

Next steps: Review the proposal. If approved, say "openspec implement" or "apply the change" to begin implementation.

undefined

Advanced Topics

进阶主题

EARS format details: See reference/EARS_FORMAT.md Validation patterns: See reference/VALIDATION_PATTERNS.md Complete examples: See reference/EXAMPLES.md

EARS格式细节：请参阅reference/EARS_FORMAT.md 验证模式：请参阅reference/VALIDATION_PATTERNS.md 完整示例：请参阅reference/EXAMPLES.md

Common Patterns

常见模式

Pattern 1: New feature proposal

模式1：新功能提案

When adding net-new capability:

Use
```
ADDED Requirements
```
delta
Include positive scenarios AND error handling
Consider edge cases in scenarios

添加全新能力时：

使用
```
ADDED Requirements
```
差异
包含正向场景和错误处理
考虑场景中的边缘情况

Pattern 2: Breaking change proposal

模式2：破坏性变更提案

When changing existing behavior:

Use
```
MODIFIED Requirements
```
delta
Include complete updated requirement text
Document what changes and why in proposal.md
Consider migration tasks in tasks.md

变更现有行为时：

使用
```
MODIFIED Requirements
```
差异
包含完整的更新后需求文本
在proposal.md中记录变更内容及原因
在tasks.md中考虑迁移任务

Pattern 3: Deprecation proposal

模式3：弃用提案

When removing features:

Use
```
REMOVED Requirements
```
delta
Document removal rationale in proposal.md
Include cleanup tasks in tasks.md
Consider user migration in impact section

移除功能时：

使用
```
REMOVED Requirements
```
差异
在proposal.md中记录移除理由
在tasks.md中包含清理任务
在影响部分考虑用户迁移

Anti-Patterns to Avoid

需避免的反模式

Don't:

Skip validation checks (always run grep patterns)
Create proposals without reviewing existing specs first
Use vague task descriptions ("Fix the thing")
Write requirements without scenarios
Forget error handling scenarios
Mix multiple unrelated changes in one proposal

Do:

Check for conflicts before creating change ID
Write concrete, testable tasks
Include positive AND negative scenarios
Keep one concern per proposal
Validate structure before presenting

请勿：

跳过验证检查（务必运行grep命令）
未审阅现有规范就创建提案
使用模糊的任务描述（如“修复问题”）
编写无场景的需求
遗漏错误处理场景
在一个提案中混合多个不相关的变更

请：

创建变更ID前检查冲突
编写具体的、可测试的任务
包含正向和负向场景
每个提案仅关注一个核心事项
提交前验证结构

File Templates

文件模板

All templates are in the

templates/

directory:

proposal.md - Proposal structure
tasks.md - Task checklist format
spec-delta.md - Spec delta template

所有模板均位于

templates/

目录下：

proposal.md - 提案结构
tasks.md - 任务检查清单格式
spec-delta.md - 规范差异模板

Reference Materials

参考资料

EARS_FORMAT.md - Complete EARS syntax guide
VALIDATION_PATTERNS.md - Grep/bash validation
EXAMPLES.md - Real-world proposal examples

Token budget: This SKILL.md is approximately 450 lines, under the 500-line recommended limit. Reference files load only when needed for progressive disclosure.

EARS_FORMAT.md - 完整EARS语法指南
VALIDATION_PATTERNS.md - Grep/bash验证方法
EXAMPLES.md - 真实提案示例

Token预算：本SKILL.md约450行，低于推荐的500行限制。参考文件仅在需要时加载，以实现渐进式披露。