OpenSpec best practices
These habits separate smooth spec-driven workflows from messy ones—especially when multiple people or models touch the same change.
Start with a narrow change name
Use /opsx:new short-descriptive-slug so the folder name reads clearly in code review and git status. Prefer add-oauth-refresh over stuff.
Make proposals readable in two minutes
Your proposal should answer: problem, proposed solution, scope (in and out), and risks. If a reviewer cannot skim it quickly, split the change or trim scope.
Write scenarios, not vibes
In specs/, prefer concrete scenarios (“Given … when … then …”) over vague adjectives. Scenarios become the contract your assistant implements against.
Keep tasks small and ordered
Large monolithic tasks lead to huge diffs. Break work into numbered steps that can be verified independently. Order matters when later steps depend on earlier files or migrations.
Review before /opsx:apply
Fast-forward (/opsx:ff) is powerful; treat its output like a human-authored design review. Adjust specs or tasks before asking the model to touch production paths.
Reset context between planning and coding
Long threads accumulate noise. After planning is stable, starting a fresh session with the spec files attached often yields cleaner implementations. See also OpenSpec + Cursor for editor-specific tips.
Archive when truly done
Use /opsx:archive when the change is merged or abandoned so your openspec/changes/ directory stays a queue of active work, not a graveyard.