maxrave-dev

maxrave-dev/SimpMusic

Instructions file

Claude Code instructions for maxrave-dev/SimpMusic, covering claude.md - simpmusic project guide for ai agents, 🌐 language rule, 📋 project overview, main purpose and basic information.

maxrave-dev/kotlin-footguns

Plugin Claude Code

Agent skills by maxrave-dev, distilled from shipping SimpMusic in production since 2023.

maxrave-dev/kotlin-footguns

Plugin Claude Code

216 battle-tested agent skills mapping the footguns of Kotlin, Compose Multiplatform and desktop JVM development. Mined from SimpMusic, a production cross-platform app shipping since 2023; traps-first, with verification commands that were executed against the real codebase.

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

A design rule with legitimate exceptions survives only if every exception carries its reason at the call site and the rule itself is greppable — otherwise nothing distinguishes an exception from a violation and the rule silently rots. Covers where the rule statement goes, where the reasons go, scoping the audit to the…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

A reusable top-glow layer that gives pages with no imagery of their own the same tinted ground the image-backed screens get — emitted as the first sibling of a navigation destination's content, with no wrapper, because destinations already stack. Covers why a null tone must collapse the gradient into the page colour…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

Draw a linear gradient at an arbitrary angle across a Compose box so both endpoints land exactly on the box edge — the per-quadrant endpoint formula from the requested angle, why rotating the diagonal overshoots and why clamping to the nearest edge distorts the angle, and the degenerate cases that collapse the ramp to…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

A rotating sweep-gradient ring around a card, chip or button, built from a clipped box, a full-size gradient and an opaque inset surface parked on its middle — where the modifier order is the whole mechanism and no blend mode is involved — plus why the SrcIn-inside-an-offscreen-layer version of this cannot draw a…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

A remote write can answer "ok" and still have discarded what you sent, saying so only in a secondary field riding along with the success. Model accepted-but-discarded as its own outcome, read that field on every write, and log a discard loudly. Reach for it when a submission reports success on every call and the data…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

Back an app up into one zip that lands in the user's own Downloads folder with no storage permission, keeping only the newest N archives. Covers checkpointing the database's write-ahead log before the file is copied, assembling the archive in cache first, inserting through the system media store, and pruning old…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

Audit every native dependency for a slice on a CPU architecture before promising that target in a multiplatform desktop build — one missing native takes the whole target down at first use rather than at build time, so make the audit a repeatable command over the resolved artifacts and re-run it on every dependency…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

Drive a screen's colours from its artwork — which extracted swatch to use for an accent versus for a large page background, luminance-adaptive darkening so overlaid text stays readable on any image, the hex parsing helper this needs, and what to do when extraction returns nothing or there is no artwork at all. Use…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

Derive a complete tonal colour scheme from one artwork-extracted seed and wrap only that subtree in it, so every control inherits contrast-paired roles instead of hand-picked swatches — covers falling back by comparing against the sentinel the seed was initialised with, tweening the seed rather than the scheme, and…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

Implement a programmatic audio fade — a sleep timer, an alarm ramp, a duck — on a gain line of its own instead of the user's volume, and restore that gain from the player's own completion path. Use when a fade drags the volume slider down in the UI, when the app comes back permanently silent with a full slider, when a…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

Hold Android audio focus once at app level when several player instances are alive at the same time — dual-player crossfade, precached players — and keep focus-driven ducking off whatever gain line a fade already owns. Use when background playback dies between tracks, autoplay stalls after the first item, a duck never…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

Derive an automatic crossfade duration and a tempo/key match from how far apart two tracks are, the way a DJ would — halftime normalisation before comparing tempos, beat-quantised durations, a front-loaded ramp and quantised gain/speed steps. Use when an automatic transition length feels arbitrary, when tracks an…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

Wrap an integer flag set handed up from a lower layer in a single-field value class exposing contains and containsAny, so call sites stop writing raw bitwise tests against library constants. Covers keeping the wrapper allocation-free, why the flag constants must travel with it, the difference between "any of these…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

Rules for implementing a protocol someone else defined — no renaming, no reordering, constants the schema omits read off the counterpart implementation rather than guessed, unknown message types decoded to null instead of thrown, and negotiated capabilities narrowed but never widened. Use when your client must…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

Group events by local hour or local day in application code from one raw scan, not in SQL — the engine's local-time modifier answers from the process time zone rather than the user's, and four local-time aggregates mean four scans that can disagree with each other. Covers where the line sits between an aggregate that…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

Wire build-time configuration into a Kotlin Multiplatform app with BuildKonfig — secrets read from an untracked local properties file and injected as generated constants, with the no-secrets branch getting empty strings so the feature disables itself instead of failing the build, plus the task-dependency wiring newer…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

Import thousands of rows from a user-supplied file without the UI going dark or the batch dying halfway — chunk the writes and emit progress per chunk, reject a parse that yields nothing before touching the database, and filter incoming rows down to those whose referenced parents exist. Use when building an…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

A native library you bundle with a desktop app drags its own copy of a general-purpose base library along, that copy claims the shared-object name for the whole process the moment your native loads, and an unrelated platform API then fails with a missing-symbol message naming a third library. Use when a feature that…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

Serve the stored copy immediately, then the fresh one, from a single repository flow — and emit an error only when nothing was served, because an error after a successful emission replaces working content the user is already reading. Use when a screen shows a spinner on every open despite having shown the same data a…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

Sweeping a local cache database down to what the user actually owns — ordering container deletes before leaf deletes, telling "kept by state" columns apart from genuine garbage, re-checking conditions inside the DELETE, and pinning the record currently in use. Reach for it when a "clear cache" or "clear history" pass…

maxrave-dev/kotlin-footguns

Skill Claude CodeCodex

Keep a tracked markdown file of dated entries that record symptom, mechanism, what was ruled out and the condition for removing the workaround — and enforce it with a rule that the entry lands with the change. Use when a fix rests on non-obvious behaviour someone will later "clean up", when the same investigation…