propose

Propose a Change

You are creating a new change using the OpenSpec OPSX workflow. This command is the fastest path — it creates the change directory and generates all planning artifacts in one step.

Upstream source: Fission-AI/OpenSpec — run /openspec:check-updates to check for updates.

About OpenSpec

OpenSpec uses a fluid, iterative workflow built around "changes" — folders in openspec/changes/<change-name>/ that contain planning artifacts. The default schema (spec-driven) produces four artifacts:

openspec/changes/<change-name>/
├── proposal.md    — why we're doing this, what's changing
├── specs/         — requirements and scenarios per capability
├── design.md      — technical approach
└── tasks.md       — implementation checklist

Workflow

Step 1: Determine Change Name

If the user provided a change name or description, derive a kebab-case name from it (2-4 words, descriptive):

• "add dark mode" → add-dark-mode
• "fix payment timeout bug" → fix-payment-timeout
• "implement JWT authentication for mobile API" → jwt-mobile-auth

If no description was provided, ask: "What would you like to build or change?"

Step 2: Set Up Change Directory

Create the change directory structure:

openspec/changes/<change-name>/

Also create openspec/changes/<change-name>/.openspec.yaml:

schema: spec-driven
created: [TODAY'S DATE ISO FORMAT]

Read the project configuration if it exists (openspec/config.yaml):

• context field: inject into all artifact instructions
• schema field: use as the schema (default: spec-driven)
• rules field: per-artifact rules to inject

Step 3: Generate All Planning Artifacts

For each artifact in the spec-driven schema (in dependency order):

3a. Create proposal.md

Purpose: Establish WHY this change is needed.

# Proposal: [CHANGE NAME]

## Why

[1-2 sentences: what problem does this solve? Why now?]

## What Changes

[Bullet list of changes — be specific about new capabilities, modifications, or removals]
[Mark breaking changes with **BREAKING**]

## Capabilities

### New Capabilities
[List capabilities being introduced. Each becomes a new `openspec/specs/<name>/spec.md`]
[Use kebab-case names, e.g., `user-auth`, `data-export`]

### Modified Capabilities
[List existing capabilities whose REQUIREMENTS are changing]
[Leave empty if no requirement changes]

## Impact

[Affected code, APIs, dependencies, or systems]

Check openspec/specs/ for existing spec names to avoid duplicates in Modified Capabilities.

3b. Create specs/<capability>/spec.md (one per capability in proposal)

Purpose: Define WHAT the system should do.

For each capability listed in the proposal's Capabilities section, create openspec/changes/<change-name>/specs/<capability>/spec.md:

## [ADDED/MODIFIED/REMOVED] Requirements

### Requirement: [Requirement Name]
[Description — the system SHALL/MUST do X]

#### Scenario: [Scenario Name]
- **WHEN** [action or event]
- **THEN** [expected outcome]

Critical formatting rules:

• Each requirement: ### Requirement: <name> followed by description
• Use SHALL/MUST for normative requirements
• Each scenario: #### Scenario: <name> with WHEN/THEN format (4 hashtags exactly)
• Every requirement MUST have at least one scenario
• CRITICAL: Scenarios MUST use exactly 4 hashtags (####). Using 3 hashtags will fail silently.

For MODIFIED requirements: Copy the ENTIRE existing requirement block from openspec/specs/<capability>/spec.md and modify it in full. Never use partial content.

3c. Create design.md (if needed)

Purpose: Explain HOW to implement the change.

Create only if any of these apply:

• Cross-cutting change (multiple services/modules) or new architectural pattern
• New external dependency or significant data model changes
• Security, performance, or migration complexity
• Ambiguity that benefits from technical decisions before coding

If not needed, skip this file.

# Design: [CHANGE NAME]

## Context
[Background, current state, constraints, stakeholders]

## Goals / Non-Goals
**Goals**:
- [What this design achieves]

**Non-Goals**:
- [What this explicitly excludes]

## Decisions
[Key technical choices with rationale — why X over Y?]
[For each decision: **Decision**: [choice] — **Rationale**: [why]; **Alternatives**: [what else was considered]]

## Risks / Trade-offs
- [Risk] → Mitigation: [how to address]

## Migration Plan
[Steps to deploy, rollback strategy if applicable]

## Open Questions
[Outstanding decisions or unknowns]

3d. Create tasks.md

Purpose: Break down the work into trackable implementation tasks.

# Tasks: [CHANGE NAME]

## 1. Setup

- [ ] 1.1 [First setup task — project structure, dependencies]
- [ ] 1.2 [Second setup task]

## 2. Core Implementation

- [ ] 2.1 [First core task — specific file/component]
- [ ] 2.2 [Second core task — specific file/component]
- [ ] 2.3 [Third core task]

## 3. Integration & Testing

- [ ] 3.1 [Integration or test task]
- [ ] 3.2 [Another integration task]

## 4. Polish

- [ ] 4.1 [Documentation, cleanup, final review]

Task rules:

• Each task uses - [ ] X.Y Description format
• Group tasks under ## N. [Phase] headings
• Tasks should be small enough to complete in one session
• Order tasks by dependency (what must be done first?)
• Reference specific files/components in descriptions

Step 4: Inject Project Context (if config exists)

If openspec/config.yaml has:

• context: prepend this context to each artifact's generation instructions (helps AI understand conventions)
• rules.<artifact-id>: inject these rules into the specific artifact's generation

Step 5: Output Summary

Change Created: openspec/changes/[change-name]/

  Artifacts Generated:
    ✓ proposal.md          — change rationale and scope
    ✓ specs/[cap]/spec.md  — requirements and scenarios
    ✓ design.md            — technical approach (if needed)
    ✓ tasks.md             — implementation checklist

  [count] tasks ready for implementation

Next step: Run /openspec:apply to start implementing tasks.
Or run /openspec:explore if you need to think through the approach first.

Important Rules

• Focus proposal on WHY and WHAT, not HOW — save technical details for design.md
• Specs should be testable — each scenario is a potential test case
• Tasks should be small and concrete — verifiable when done
• Check openspec/specs/ for existing capabilities before creating new ones
• If the change description is very vague, ask one focused clarifying question before proceeding
• The openspec/changes/ directory is the source of truth for in-progress work