tool notes & conventions

package managers

in general, stick to bun. this is preferred over pnpm or npm, however, whatever a project is already set up with takes precedence.

git

don't assume it's okay to commit or push or perform git operations. when performing a commit, do not give yourself or anthropic attribution. we like you, we don't like anthropic.

commit messages:

subject line: 50 chars max
body: 72 chars max width
format: type(scope): subject
types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
use imperative mood ("add feature" not "added feature")

arch packages

use pacman for official repos, yay for AUR. don't use paru.

coding standards

follow the universal coding standards documented in ~/universal-coding-standards.md

key principles:

max 3 levels of indentation (if you need more, refactor)
comments explain why, not what or how
test things in the browser, don't be lazy

line width

soft limit: 80-100 chars (forces clear thinking, works on split screens)
hard limit: 120 chars max
exceptions: user-visible strings, URLs, long literals

ui design

when building UI, follow the design principles documented in ~/.claude/UI-DESIGN-PRINCIPLES.md

grepai

use grepai as the primary tool for code exploration and search.

use grepai search instead of grep/glob/find for:

understanding what code does or where functionality lives
finding implementations by intent
exploring unfamiliar parts of the codebase

use standard grep/glob only for exact text matching or file path patterns. if grepai fails, fall back to standard tools.

grepai search "query here" --json --compact
grepai trace callers "Symbol" --json
grepai trace callees "Symbol" --json
grepai trace graph "Symbol" --depth 3 --json

open source contributions

even if a PR gets rebuilt/refactored by maintainers, it still matters
be transparent about ai assistance in PRs
check how similar features are structured before contributing
prefer shared helpers over custom one-off implementations
keep core lean - features belong at the edges (plugins/extensions)
dynamic config > hardcoded catalog entries
when unsure about architecture fit, ask in an issue first

other tools

imsg

send an iMessage/SMS: describe who/what, confirm before sending
prefer short messages; avoid sending secrets

sag

text-to-speech: specify voice, target speaker/room, and whether to stream

2.5 KiB Raw Blame History