Docs: Improve agent instructions

Author: vdavid

.claude/commands/plan.md

@@ -1,8 +1,15 @@
-Plan a feature implementation.
+Plan the feature implementation we discussed.
 
-1. Check the `docs/` folder and colocated `CLAUDE.md` files for context. Read `docs/design-principles.md` for product
-   design values.
+1. Collect context from related `CLAUDE.md` files or `docs/`, as needed.
+   Read [design-principles.md](../../docs/design-principles.md)) to remember our core product design values.
 2. Save the plan to `docs/specs/{feature}-plan.md`.
-3. Capture the INTENTION behind each decision, not just the steps. The implementing agent or human should know the "why"s and be able to adapt dynamically.
-4. Create an accompanying task list to the end of the plan that fully covers but doesn't duplicate the plan on a high level. If all items are honestly marked done, the plan is fully implemented in great quality. Tasks should be one-liners, grouped by milestones. Include docs, testing, and running all necessary checks.
-5. Don't enter "Plan mode" unless specifically asked to.
+3. Capture the INTENTION behind each decision, not just the steps. The implementing agent or human should know the "why"
+   s and be able to adapt dynamically!
+4. Use milestones if needed. Make sure to include the necessary docs updates roughly, testing (Unit? Integration? E2E?),
+   and running all necessary checks.
+5. Leave notes about what can be executed in parallel, but only if it's extremely safe and needs no worktrees; we're
+   usually not in a hurry and sequential running is totally fine.
+6. DO NOT enter "Plan mode" unless specifically asked to "Enter plan mode". Use docs/specs.
+7. Get an Opus agent to review the plan with fresh eyes, and point out any mistakes. Then fix up the plan based on that.
+   Link the most crucial docs and design principles to the agent.
+8. Do this review round again and again, until the reviewer agent has no meaningful input, or maximum 5 times.

docs/design-principles.md

@@ -1,22 +1,34 @@
 # Design principles
 
-- Always make features extremely user-friendly.
-- Always apply radical transparency: make the internals of what's happening available. Hide the details from the surface
-  so the main UI is not cluttered.
-- For longer processes: 1. show a progress indicator (an anim), 2. a progress bar and counter if we know the end state
-  (for example, how many files we're loading), and 3. a time estimate if we have a guess how long it'll take.
-- Always keep accessibility in mind. Features should be available to people with impaired vision, hearing, and cognitive
-  disabilities.
-- All actions longer than ~1 second should be immediately cancelable, canceling not just the UI but any background
-  processes as well, to avoid wasting the user's resources.
-- Prefer elegant architecture over quick hacks, but don't refactor beyond what the task requires.
-- When shortcuts are available for a feature, always display the shortcut in a tooltip or somewhere less prominent than
-  the main UI.
-For concrete tokens and component patterns, see [design-system.md](design-system.md).
-
+- Prefer an elegant architecture over quick hacks. We have time to do outstanding work, and we are in this for the long
+  run.
 - **Platform-native, not generic.** The app should look and feel as if it was specifically made for the user's OS. Never
   generalize user-facing text, labels, or behavior to be "cross-platform" — instead, fork by OS. On macOS, say "Finder",
   "Trash", "System Settings". On Linux, say "file manager", "Trash" (FreeDesktop spec), and use DE-specific terminology
   where possible. Windows (later) gets its own native terms too. This applies to error messages, menu labels, tooltips,
   and any user-visible string. Use `isMacOS()` / `cfg(target_os)` to branch — a few extra lines of platform-specific
   text are always better than one watered-down generic string.
+- Always apply radical transparency: make the internals of what's happening available. Like, don't just put a "Syncing"
+  spinner but write exactly what's happening. Don't overshare/overcomplicate, but the user must understand what's
+  happening to an extent that they could explain it to someone else if asked.
+- Always make features extremely user-friendly. The UI should help the user accomplish their goals with minimal
+  friction.
+- This is a keyboard-first app. Everything must work with the mouse, too, but we should make it easy and straightforward
+  to use all features with the keyboard.
+- When shortcuts are available for a feature, always display the shortcut in a tooltip or somewhere less prominent than
+  the main UI.
+- For longer processes:
+    1. Always run the process in the background. Blocking the UI or other actions is an absolute no-go.
+    2. Show some anim to communicate that the app is doing something.
+    3. If we know what the end state looks like and we can quantify the progress, show a progress bar and counter.
+    4. If we have a guess how long the operation will take, show an ETA.
+    5. Progress bars staying longer at 100% than at 99% or any other percentage is NOT allowed. If we're done with the
+       part of an operation that we could quantify and displayed a progress bar for it but we have something else to do
+       (e.g. we loaded the data and now we're making calculations on the data), then it's a new state, show another
+       state!
+- All actions longer than ~1 second should be immediately cancelable, canceling not just the UI but any background
+  processes as well, to avoid wasting the user's resources. If rolling back is an option, we should consider that too.
+- Always keep accessibility in mind. Features should be available to people with impaired vision, hearing, and cognitive
+  disabilities.
+
+For concrete tokens and component patterns, see [design-system.md](design-system.md).