openquack

Specs

Every meaningful change in OpenQuack cites a SPEC. This directory is the source of truth for what we build and why.

Conventions:

• File names: SPEC-<NNN>-<kebab-name>.md.
• IDs are global, monotonic, and stable. Renumbering is forbidden once a spec is referenced by a PR.
• New spec? File the Spec proposal issue first; merging the spec is a separate PR from any implementation.
• Every spec must include an ## Acceptance criteria section that states the clear goal and how to validate it — a user-visible behaviour (“pastes within 200 ms of hotkey release”), a measurable metric (“WER ≤ 6.5 % on bench/corpus/noisy”), or explicit manual steps a reviewer can follow. If neither the goal nor the validation method can be written down, the spec is still a proposal, not a contract.

Index

Every spec listed here has been ratified (the spec PR merged). The Status column tracks implementation state, which is what the roadmap drives against:

• shipped — implemented and merged to main
• partial — partly implemented; remaining work noted in the spec
• draft — accepted spec, not yet built
• parked — superseded or on hold

ID	Title	Status	Milestone
SPEC-001	Voice capture	shipped	M2
SPEC-002	Transcription	shipped	M1
SPEC-003	Global hotkey	shipped	M2
SPEC-003a	fn / Globe key as a bindable hotkey	shipped	M2
SPEC-004	Recording overlay	shipped	M2
SPEC-005	Paste at cursor	shipped	M2
SPEC-006	Agent dispatch (closed-loop sessions)	draft	M2
SPEC-007	LLM transcript polish	draft	M2.5
SPEC-007a	Gemma 4 polish bench addendum	draft	M2.5
SPEC-007b	Intelligent rewrite UX	draft	M2.5
SPEC-008	In-context transcript rewrite	draft	M3
SPEC-010	App shell	shipped	M2
SPEC-011	Update flow: notification + one-click upgrade	shipped	M2
SPEC-012	Streaming transcription (perf-only chunking)	shipped	M3
SPEC-013	Usage stats pane	shipped	M3
SPEC-014	Local audio + transcript history	shipped	M3
SPEC-015	Release channels (alpha / beta / stable)	partial	M3
SPEC-016	Distilled polish model (1B from Gemma 4)	parked	M2.5
SPEC-018	Send-feedback menu item	shipped	M3
SPEC-019	App localisation (i18n)	draft	M3
SPEC-020	One-click “Copy” button for the last transcript	shipped	M3
SPEC-021	Mandarin auto-detect failure: bench coverage + fix	draft	M1/M2
SPEC-022	Custom dictionary auto-learn from user corrections	draft	M3
SPEC-023	Launch at login	shipped	M2
SPEC-024	Per-app tone profiles	draft	M3
SPEC-025	Code signing + notarisation	partial	M2
SPEC-026	Sparkle auto-update	partial	M2
SPEC-027	README demo gif + landing-page polish	draft	M2
SPEC-028	Dictation distribution + personal performance stats	shipped	M3
SPEC-029	ANE-cache-only model footprint (investigation)	draft	M3
SPEC-030	ANE cache footprint: volunteer measurement campaign	draft	M3
SPEC-031	Agent kickoff (one-shot voice-to-action)	shipped	M2
SPEC-031a	Voice reply to live agent sessions	draft	M2
SPEC-032	Engine prompt-token cache (offline path parity)	draft	M1
SPEC-035	Auto-normalise Chinese script + mixed-language streaming detection	shipped	M3

Next free spec ID: SPEC-036. SPEC-033 / SPEC-034 stay reserved for the two open docs PRs (#41 Pages analytics → 033, #42 install-count → 034, pending renumber). IDs are global and monotonic — never reuse 028/029/031/032/035.

Spec lifecycle

proposal issue ──► draft PR adds spec ──► ratified (PR merged)
                                              │
                          ┌───────────────────┴──────────────────┐
                          │                                       │
                  superseded by SPEC-NNN              archived (no longer relevant)

A spec at ratified may still be amended; small edits are fine within an implementation PR if they don’t change semantics. Material changes are their own PR.

This site is open source. Improve this page.