Clipboard Dev

Clipboard Desktop Development

Start every task

1. Read references/maintenance-workflow.md completely before changing the repository.
2. Inspect git status --short --branch, recent commits, TODO.md, and the exact source and tests in scope. Preserve unrelated user changes.
3. Select the relevant references from the routing table below and read each selected file completely before editing its subsystem.
4. Treat current source, tests, configuration, and rendered/runtime behavior as authoritative. References are navigation aids and must be corrected when evidence disagrees.
5. Define one independently verifiable feature, fix, audit, style pass, or documentation update for the next commit.

Non-negotiable principles

• Check a TODO only when direct implementation evidence and proportionate verification cover its full wording. A stub, setting, UI shell, similarly named symbol, or untested platform file is not completion.
• Preserve the approved main-page visual language. Do not redesign it unless the task explicitly requests a main-page redesign.
• Apply the settings style gate before any settings CSS or markup change. Reuse project-wide semantic variables and shared settings primitives.
• Protect local data first. Be conservative around migrations, cleanup, custom resource roots, self-trigger suppression, favorites, recycle-bin records, OCR, and derived search data.
• Keep parallel ownership non-overlapping. The primary agent owns shared integration files and final verification.
• Commit one verified minimal unit at a time; never mix unrelated cleanup into the same commit.

Mandatory documentation currency gate — every commit

Before every commit, inspect the staged diff and decide whether SKILL.md or any file under references/ must change. This gate is required even when the answer is “no documentation update needed.”

Update the matching reference in the same commit when the change affects any of these:

• routes, components, services, utilities, backend modules, or ownership boundaries;
• Tauri commands/events, TypeScript/Rust types, database/config schemas, defaults, or serialization;
• lifecycle, data-safety, search-cache, OCR, platform, or verification invariants;
• theme variables, project-wide styles, settings primitives, layout hierarchy, or an approved pattern;
• a recurring pitfall, workflow rule, or stable project preference.

Keep stable workflow and routing rules in SKILL.md. Put module-specific facts, signatures, examples, and style details in the relevant reference. Do not edit documentation merely to create churn, but never commit a known-stale skill or reference.

Reference router

Also read the focused project document when relevant: docs/PITFALLS.md, docs/SEARCH.md, docs/OCR.md, or docs/DEFAULTS_AND_PRIVACY.md.

Cross-cutting change gates

• Tauri contract: keep command name, Rust arguments/result, frontend invoke, serde casing, error handling, and tests aligned.
• Settings contract: update TypeScript type, defaults, normalization/ranges, Rust config serde/defaults, UI, persistence, cross-window application, i18n, tests, and references as applicable.
• Async settings contract: a control bound to backend-loaded state must hydrate before it renders — a shared module-level store (generalSettings, windowConfig) or a load gate — never a placeholder default that the fetch later overwrites. Lazy settings panels are destroyed and recreated on every section switch, so a per-mount fetch makes the wrong value (and any toggle animation) flash on each visit. See settings-panels.md.
• Database contract: update schema/migration, row mapping, repository behavior, derived search/OCR cleanup, recovery expectations, and tests.
• i18n contract: update src/lib/i18n/locales/en.ts, zh-CN.ts, and src/lib/i18n/types.ts together unless the string is intentionally non-localized and documented.
• Worker/listener contract: retain stop signals, join handles, unlisten functions, and the unified shutdown path.
• Platform contract: separate shared behavior from per-platform implementation and degradation. Do not infer macOS/Linux completion from a compiled adapter or documentation scaffold.
• Visual contract: type/build checks do not prove appearance. Use structural comparison and, when available, rendered/runtime inspection at the target window size and theme.

Verification commands

npm run check
npm run build
npm run test:rust
npm run lint:rust
npm run format:check
npm run verify

The Rust format, test, and Clippy scripts cover every Cargo workspace member, including the Tauri-independent sync crate. Run the narrowest relevant checks during implementation. Run npm run verify at integration milestones or before a commit whose scope crosses frontend and backend. If an environment prevents a required runtime, visual, platform, packaging, or performance check, report the missing evidence and leave the corresponding TODO unverified.

The pre-release gate runs format + check + lint:rust and does not build locally (see skills/version-release/SKILL.md); building happens remotely in the GitHub Actions release.yml workflow on tag push, so the local build profile stays fast.