Specification Proposal Creation

Follow the specification-driven development approach to generate complete change proposals.

Quick Start

Creating a specification proposal includes three types of outputs:

proposal.md - Summary of why, what, and impact
tasks.json - Numbered implementation checklist
spec-delta.md - Formal requirement changes (ADDED/MODIFIED/REMOVED)

Basic Process: Generate change ID → Scaffold directory → Draft proposal → Write specification delta → Validate structure

Workflow

Copy this checklist to track progress:

Planning Progress:
- [ ] Step 1: Review existing specifications
- [ ] Step 2: Generate unique change ID
- [ ] Step 3: Generate directory structure
- [ ] Step 4: Draft proposal.md (why, what, impact summary)
- [ ] Step 5: Create tasks.json implementation checklist
- [ ] Step 6: Write spec-delta.md specification differences (ADDED/MODIFIED/REMOVED)
- [ ] Step 7: Validate proposal structure
- [ ] Step 8: Present to user and request approval

Step 1: Review Existing Specifications

Understand the current state before creating a proposal:

bash

# List all existing specifications
find spec/specs -name "spec.md" -type f

# List ongoing changes to avoid conflicts
find spec/changes -maxdepth 1 -type d -not -path "*/archive"

# Search related requirements
grep -r "### Requirement:" spec/specs/

Step 2: Generate Unique Change 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>"

Step 3: Generate Directory Structure

Create a change directory following the standard structure:

bash

# Replace {change-id} with the actual ID
mkdir -p spec/changes/{change-id}/specs/{capability-name}

Example:

bash

mkdir -p spec/changes/add-user-auth/specs/authentication

Step 4: Draft proposal.md

Start with templates/proposal.md.

Required Sections:

Why: The problem or opportunity driving the change
What Changes: List of modifications
Impact: Affected specifications, code, APIs, users

Tone: Clear, concise, and decision-oriented. Avoid unnecessary background.

Step 5: Create tasks.json Implementation Checklist

Break down implementation into specific, testable tasks. Use templates/tasks.json.

Format:

markdown

# Implementation Tasks
```json
[
  {
    "number": 1,
    "category": "Phase 1: Infrastructure",
    "task": "Environment setup tasks - database schema, dependencies, etc.",
    "steps": [
      { "step": "Initialize Git repository and configure .gitignore", "completed": false },
      { "step": "Create and activate Python virtual environment", "completed": false },
      { "step": "Create requirements.txt or pyproject.toml and install dependencies (FastAPI, SQLAlchemy, Pydantic, Alembic, etc.)", "completed": false },
      { "step": "Design initial database ER diagram", "completed": false },
      { "step": "Configure database connection string and environment variables (.env)", "completed": false },
      { "step": "Initialize Alembic migration environment", "completed": false }
    ],
    "passes": false
  }
]


**Best Practices**:
- Each task can be completed independently
- Add test tasks for each major component
- Add test tasks for each major component
- Include testing and validation tasks
- Sort by dependency (database before API, etc.)
- Typically 5-15 tasks; split if more
- Process only 1 step at a time

Step 6: Write Specification Delta in EARS Format

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

Complete EARS Guide is available at reference/EARS_FORMAT.md

Delta Operations:

```
## ADDED Requirements
```
- New capabilities added
```
## MODIFIED Requirements
```
- Behavior changes (include full updated text)
```
## REMOVED Requirements
```
- Deprecated features

Basic Requirement Structure:

markdown

## ADDED Requirements

### Requirement: User Login
WHEN the user submits valid credentials,
the system SHALL authenticate the user and create a session.

#### Scenario: Successful Login
GIVEN the user's email is "user@example.com" and password is "correct123"
WHEN the user submits the login form
THEN the system creates an authenticated session
AND redirects to the dashboard

Patterns for Validation are available at reference/VALIDATION_PATTERNS.md

Step 7: Validate Proposal Structure

Run the following checks before presenting to the user:

markdown

Structure Checklist:
- [ ] Directory exists: `spec/changes/{change-id}/`
- [ ] proposal.md includes Why/What/Impact
- [ ] tasks.json contains numbered task list (5-15 items)
- [ ] Specification delta includes operation headers (ADDED/MODIFIED/REMOVED)
- [ ] Requirements follow the `### Requirement: <name>` format
- [ ] Scenarios use the `#### Scenario:` format (four hashes)

Automated Checks:

bash

# Count delta operations (should be > 0)
grep -c "## ADDED\|MODIFIED\|REMOVED" spec/changes/{change-id}/specs/**/*.md

# Validate scenario format (show line numbers)
grep -n "#### Scenario:" spec/changes/{change-id}/specs/**/*.md

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

Step 8: Submit for User Review

Summarize the proposal clearly:

markdown

## Proposal Summary

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

**Files Created**:
- spec/changes/{change-id}/proposal.md
- spec/changes/{change-id}/tasks.json
- spec/changes/{change-id}/specs/{capability}/spec-delta.md

**Next Steps**:
Please review the proposal. If approved or revised, reply with "openspec development" or "complete tasks in order" to start implementation.

Advanced Topics

EARS Format Details: See reference/EARS_FORMAT.md Validation Patterns: See reference/VALIDATION_PATTERNS.md Complete Examples: See reference/EXAMPLES.md

Common Patterns

Pattern 1: New Feature Proposal

When adding new capabilities:

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

Pattern 2: Breaking Change Proposal

When modifying existing behavior:

Use
```
MODIFIED Requirements
```
delta
Include full updated requirement text
Explain what changed and why in proposal.md
Include migration tasks in tasks.json

Pattern 3: Deprecation Proposal

When removing features:

Use
```
REMOVED Requirements
```
delta
Record the reason for removal in proposal.md
Include cleanup tasks in tasks.json
Consider user migration in the impact section

Anti-Patterns to Avoid

Do NOT:

Skip validation checks (be sure to run grep patterns)
Create proposals without first reviewing existing specifications
Use vague task descriptions (e.g., "fix it")
Write requirements without scenarios
Ignore error handling scenarios
Mix multiple unrelated changes in one proposal

DO:

Check for conflicts before creating a change ID
Write specific, testable tasks
Include both positive and negative scenarios
Address only one concern per proposal
Validate structure before presenting

File Templates

All templates are located in the

templates/

directory:

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

Reference Materials

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

Token Budget: This SKILL.md is approximately 250 lines, below the recommended 500-line limit. Reference files are loaded on demand for gradual presentation.

openspec-proposal-creation-cn

NPX Install

Tags

SKILL.md Content (Chinese)

Specification Proposal Creation

Quick Start

Workflow

Step 1: Review Existing Specifications

Step 2: Generate Unique Change ID

Step 3: Generate Directory Structure

Step 4: Draft proposal.md

Step 5: Create tasks.json Implementation Checklist

Step 6: Write Specification Delta in EARS Format

Step 7: Validate Proposal Structure

Step 8: Submit for User Review

Advanced Topics

Common Patterns

Pattern 1: New Feature Proposal

Pattern 2: Breaking Change Proposal

Pattern 3: Deprecation Proposal

Anti-Patterns to Avoid

File Templates

Reference Materials