stash: Instructions file for Claude Code

Write extremely easy to consume code. Optimize for readability: skimmable, no cleverness, early returns.

This file is the single source of truth for agent rules in this repo. AGENTS.md is a symlink to this file so Codex, OpenCode, and any other AGENTS.md-style tool get the same instructions as Claude Code. Edit this file; never edit AGENTS.md directly.

Write simple code

We are a startup. Therefore, code simplicity is our most important concern. Please NEVER

• Add backwards compatibility support of any kind. This includes compatibility shims, aliases, legacy format support, and fallback code paths.
• Attempt to preserve backwards compatibility when making an edit.
• Use fallbacks of ANY kind, ANYWHERE, under ANY circumstance. There are no exceptions. This includes UX-saving fallbacks when a primary path fails, default values papered over a missing input (x or DEFAULT, x or stored_value()), try/except that swallows an error and continues, and "if the real source is empty, use this other source" chains. When a required input is absent or a path fails, FAIL LOUD (raise/exit with a clear message) — never silently substitute. A single source of truth with one codepath, always.
• Support old formats. If a format changes, change it everywhere in one shot.

Data migrations are allowed (updated 2026-07: we have real users now). When a schema or format changes, you may — and should — write a one-time migration that carries existing user data forward to the new format, so nobody loses data. This is not a license for backwards compatibility: migrate the data forward in one shot, then delete the old path. The end state is still a single format and one codepath — the migration is just how you get there without stranding what users already have. Everything else above stands: no compatibility shims, no fallbacks, no dual code paths.

Here are some common code patterns that we need you to avoid:

• Excessive try/catch: only use try/catch when there's a reasonable expectation that the code within might fail during normal usage. Every try/catch that we add adds another codepath that we need to maintain (the catch) and balloons complexity. In general, we follow the concept of "parse, don't validate" from TDD whenever possible. That is, we validate inputs at module boundaries, and within a module, we don't randomly add try/catch everywhere.

• Unhelpful comments that reiterate what the code does: The point of a comment is to explain information that is not obvious from reading the code. A good rule of thumb: if your comment is an action (eg: sets the diff viewer open state), it is probably a bad comment. If it is a description (eg: the diff viewer state must be synced to our ui interaction server) it is likely a good comment.