Creates structured change proposals with specification deltas for new features, breaking changes, or architecture updates. Use when planning features, creating proposals, speccing changes, introducing new capabilities, or starting development workflows. Triggers include "openspec proposal", "create

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: Step 1: Review existing specifications Before creating a proposal, understand the current state: 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: Step 3: Scaffold directory structure Create the change folder with standard structure: Example : Step 4: Draft proposal.md Use the template at [templates/proposal.md](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. Step 5: Create tasks.md implementation checklist Break implementation into concrete, testable tasks. Use the template at [templates/tasks.md](templates/tasks.md). Format : 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](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 : For validation patterns , see [reference/VALIDATION PATTERNS.md](reference/VALIDATION PATTERNS.md) Step 7: Validate proposal structure Run these checks before presenting to user: Automated checks : Step 8: Present for user approval Summarize the proposal clearly: Advanced Topics EARS format details : See [reference/EARS FORMAT.md](reference/EARS FORMAT.md) Validation patterns : See [reference/VALIDATION PATTERNS.md](reference/VALIDATION PATTERNS.md) Complete examples : See [reference/EXAMPLES.md](reference/EXAMPLES.md) 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](templates/proposal.md) Proposal structure [tasks.md](templates/tasks.md) Task checklist format [spec delta.md](templates/spec delta.md) Spec delta template Reference Materials [EARS FORMAT.md](reference/EARS FORMAT.md) Complete EARS syntax guide [VALIDATION PATTERNS.md](reference/VALIDATION PATTERNS.md) Grep/bash validation [EXAMPLES.md](reference/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.

openspec-proposal-creation