OpenSpec Propose

Create change proposals for new features or behavioral changes.

Announce: "I'm using openspec-propose to create a change proposal for approval."

Iron Law

NO IMPLEMENTATION WITHOUT APPROVED PROPOSAL

Do NOT write implementation code during this phase. Only create:

• proposal.md
• tasks.md
• design.md (if complex)
• Spec deltas

Process

Phase 1: Gather Context

1. Read openspec/project.md for conventions
2. Run openspec list --specs to see current capabilities
3. Run openspec list to check for conflicts
4. Search codebase for related code: rg [keyword]

Phase 2: Choose Change ID

Format: verb-noun in kebab-case

Examples:

• add-leaderboard
• update-scoring-algorithm
• refactor-game-state

Verify uniqueness against openspec list.

Phase 3: Create Proposal

Create openspec/changes/[id]/proposal.md:

# Change: [Brief description]

## Why

[1-2 sentences: What problem does this solve?]

## What Changes

- [Change 1]
- [Change 2]
- **BREAKING**: [If any breaking changes]

## Impact

- Affected specs: [list]
- Affected code: [key files/directories]

Phase 4: Create Spec Deltas

For each affected capability, create openspec/changes/[id]/specs/[capability]/spec.md:

## ADDED Requirements

### Requirement: [Name]

The system SHALL [behavior].

#### Scenario: [Name]

- **WHEN** [condition]
- **THEN** [expected result]

## MODIFIED Requirements

### Requirement: [Existing Name]

[Complete updated requirement text - not just the diff]

#### Scenario: [Name]

- **WHEN** [condition]
- **THEN** [expected result]

Every requirement MUST have at least one scenario.

Phase 5: Create Tasks

Create openspec/changes/[id]/tasks.md:

## 1. [Category]

- [ ] 1.1 [Specific task - 2-5 minutes]
- [ ] 1.2 [Specific task - 2-5 minutes]

## 2. [Category]

- [ ] 2.1 [Specific task - 2-5 minutes]

Phase 6: Validate

openspec validate [id] --strict

Fix ALL issues before presenting to user.

Phase 7: Request Approval

Present summary to user:

## Proposal: [id]

**Goal:** [One sentence]

**Changes:**
- [Key change 1]
- [Key change 2]

**Tasks:** [X] items

**Ready for your review.** Run `openspec show [id]` for full details.

Do you approve this proposal?

WAIT for explicit approval before proceeding.

REQUIRED SUB-SKILL

After approval: → Load task-planning skill if tasks need more detail → Load openspec-apply skill to begin implementation

Red Flags - STOP

If you catch yourself:

• Writing implementation code
• Skipping validation
• Proceeding without user approval
• Creating vague tasks ("implement feature")

STOP. This phase is planning only.

Common Rationalizations