Change Proposal Structure

Directory structure

openspec/changes/
├── add-barcode-scanning/          # Active change
│   ├── proposal.md                # Description and rationale
│   ├── tasks.md                   # Implementation tasks
│   ├── design.md                  # Technical design (optional)
│   └── specs/                     # Delta specifications
│       ├── warehouse/
│       │   └── spec.md
│       └── product/
│           └── spec.md
│
├── fix-invoice-validation/        # Another active change
│   ├── proposal.md
│   ├── tasks.md
│   └── specs/
│       └── invoicing/
│           └── spec.md
│
└── archive/                       # Completed changes
    ├── 2025-01-15-add-mobile-app/
    ├── 2025-01-22-fix-login-bug/
    └── 2025-02-01-upgrade-workflow/

---

Required files

File	Required	Description
proposal.md	✅ Yes	Description and rationale of the change
tasks.md	✅ Yes	List of implementation tasks
design.md	❌ No	Technical design (for complex changes)
specs/*/spec.md	✅ Yes	Delta specification for affected modules

---

Naming conventions

# Change IDs (verb-led, kebab-case)
good:
  - "add-barcode-scanning"
  - "fix-invoice-validation"
  - "update-workflow-triggers"
  - "remove-deprecated-fields"
  - "refactor-auth-module"

bad:
  - "barcode"           # Missing verb
  - "new_feature"       # Underscore instead of kebab
  - "FixBug123"         # PascalCase
  - "misc-changes"      # Too vague

---

Scope management

# ✅ Good: one coherent change
change: "add-barcode-scanning"
affects:
  - Warehouse module
  - Product lookup (related)

# ❌ Bad: too many unrelated changes
change: "q1-updates"
affects:
  - Barcode scanning
  - Dark mode
  - New reports
  - Bug fixes

---

➡️ Continue to Proposal.md.