writing-specslisted

# Writing specs The Spec-First protocol: **problem definition → small, safe change → change review → refactor → repeat.** No code is written until a spec exists and the user has reviewed it. This skill is the authority on *how a spec is structured and how specs cite each other*; `AGENTS.md` is the authority on the surrounding workflow. ## 1. Where the spec lives ``` specs/ ├── <topic>/ │ ├── 01-short-description.md │ ├── 02-short-description.md │ └── ... ``` - **Pick the closest existing topic folder or create one.** Current topics: `core`, `providers`, `ui`, `widgets`, `ci`. Only create a new topic folder if the work fits none of them. - **Number sequentially _within that topic folder_.** List the folder's files, take the next number, zero-pad to two digits (`07`, not `7`). - **File name:** `NN-short-description.md` — kebab-case, intention-revealing, no spaces. ### Topic guide | Topic | What belongs here | |--------------|-------------------------------------------------------| | `core` | Provider protocol, hub, registry, Keychain, refresh | | `providers` | Individual provider implementations (z.ai, Claude, …) | | `ui` | Menu bar, popover, settings, app lifecycle | | `widgets` | Desktop widgets, Notification Center integration | | `ci` | GitHub Actions workflows, CI configuration, tooling | ## 2. MLA cross-references (MANDATORY) When a spec mentions another spec, ci