Openspec Proposal Creation

Specification Proposal Creation

Creates comprehensive change proposals following spec-driven development methodology.

Quick Start

Creating a spec proposal involves three main outputs:

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

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

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

Step 1: Review existing specifications

Before creating a proposal, understand the current state:

# List all existing specsfind spec/specs -name "spec.md" -type f
# List active changes to avoid conflictsfind spec/changes -maxdepth 1 -type d -not -path "*/archive"
# Search for related requirementsgrep -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:

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

Step 3: Scaffold directory structure

Create the change folder with standard structure:

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

Example:

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

Step 4: Draft proposal.md

Use the template at templates/proposal.md [blocked] 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.

Step 5: Create tasks.md implementation checklist

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

Format:

# Implementation Tasks
1. [First concrete task]2. [Second concrete task]3. [Test task]4. [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

Step 6: Write spec deltas with EARS format

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 [blocked]

Delta operations:

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

Basic requirement structure:

## ADDED Requirements
### Requirement: User LoginWHEN a user submits valid credentials,the system SHALL authenticate the user and create a session.
#### Scenario: Successful LoginGIVEN a user with email "[email protected]" and password "correct123"WHEN the user submits the login formTHEN the system creates an authenticated sessionAND redirects to the dashboard

For validation patterns, see reference/VALIDATION_PATTERNS.md [blocked]

Step 7: Validate proposal structure

Run these checks before presenting to user:

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:

# 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 headersgrep -n "### Requirement:" spec/changes/{change-id}/specs/**/*.md

Step 8: Present for user approval

Summarize the proposal clearly:

## 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.

Advanced Topics

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

Common Patterns

Pattern 1: New feature proposal

When adding net-new capability:

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

Pattern 2: Breaking change proposal

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

Pattern 3: Deprecation proposal

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

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

File Templates

All templates are in the templates/ directory:

• proposal.md [blocked] - Proposal structure
• tasks.md [blocked] - Task checklist format
• spec-delta.md [blocked] - Spec delta template

Reference Materials

• EARS_FORMAT.md [blocked] - Complete EARS syntax guide
• VALIDATION_PATTERNS.md [blocked] - Grep/bash validation
• EXAMPLES.md [blocked] - 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.