vixen-rs

Bump the patch version in server/Cargo.toml or website/package.json after completing a major change. Use when the user asks to bump/release a version, or when CLAUDE.md's rule about version bumps after major changes applies.

Before a non-trivial change, list affected systems — DB schema, API contract, Telegram handlers, jobs, TS types, docs. Catch ripple effects upfront, not after CI fails. Use when planning a feature, migration, refactor, or any cross-module touch.

Self-review before push — read the diff as a reader, scan for vixen footguns (token leaks, PII, idempotency, captcha asset overwrites), run validation pipeline, no surprise files. Use before "git push", before opening a PR, or when the user says "ready to commit".

Write a git commit message for vixen-rs following the project's Conventional Commits convention. Use when the user asks to commit, create a commit, or write a commit message.

Reproduce → bisect → root cause → fix → verify. Don't speculate, don't "add more error handling" as a guess. Use when something is broken, when a test fails intermittently, when the user says "this isn't working" or "investigate why".

Write small, fast, reproducible Dockerfiles for the vixen-rs server (Rust) and website (bun) using multi-stage builds, cache mounts, distroless/alpine runtime images, and non-root users. Use when editing server/Dockerfile, website/Dockerfile, docker-compose.yml, or when the user asks to shrink an image or speed up a Docker build.

Evaluate a 3rd-party Claude skill before importing — source trust, duplicate check, rule extraction, vixen-fit. Reject vague triggers and off-scope content. Use when the user shares a skill URL, asks "should we adopt this skill", or proposes importing from a marketplace.

Write or modify .github/workflows/*.yml — server-ci, website-ci, build-server, build-website. Concurrency, caching, sqlx offline mode, secrets via secrets.* refs. Use when adding/editing CI workflows or when the user asks about GH Actions.

Before non-trivial code — challenge approach, ask unknowns, propose alternatives, list edge cases, get explicit sign-off. Skip only for trivial fixes (typos, renames). Use when the user asks for a feature, refactor, schema change, or anything touching public surface.

Write the PR body — Why / What / Risk / Test plan. Skip pleasantries. Link issue. Tag CHANGELOG entry. Use 'gh pr create --body' with HEREDOC. Use when the user asks to open a PR, create a pull request, or write a PR description.

Review a pull request (or uncommitted diff) against vixen-rs conventions — server rules in server/docs/rules/ and website rules in website/docs/rules/. Use when the user asks to review a PR, review changes, or asks "what do you think of this diff".

Add a new Axum HTTP route to the vixen-rs server following project conventions for auth, validation, error mapping, and OpenAPI docs. Use when the user asks to add an endpoint, add a route, expose a new API, or extend an existing handler.

Create a new SQLx migration for the vixen-rs Postgres schema, including .up.sql and .down.sql, then apply it and refresh the offline query cache. Use when the user asks to add a migration, change the DB schema, create a new table, alter columns, or add an index.

Register a /slash_command (BotCommands derive) with permission check, dispatcher wiring, and i18n help text. Use for /verify, /ban, /unban, /stats, /help and similar.

Add a new teloxide update handler (Message, EditedMessage, CallbackQuery, ChatMemberUpdated, MyChatMember) routed through the dispatcher tree. Use when adding bot reactions to a Telegram event.

Add a periodic background job (interval-driven or wall-clock scheduled) — tokio::spawn + CancellationToken + idempotency + tracing span. Use for daily reports, captcha expiry, cleanup.

Add or modify a captcha mode (digits, picture-pick, etc.) — atomic image render + DB row + sendPhoto + restrictChatMember; deterministic per challenge_id.

Tune sqlx PgPool size, idle_timeout, max_lifetime, acquire_timeout. Diagnose pool exhaustion and 'pool timed out' errors.

Add a per-chat configurable knob (spam_threshold, report_hour, captcha_difficulty) — migration → ChatConfig struct → API DTO → transactional update endpoint.

Tune Postgres queries and schema in the vixen-rs server — read EXPLAIN (ANALYZE, BUFFERS), add the right indexes, spot N+1, batch writes, use partial/covering/expression indexes, avoid row locks on hot paths. Use when a query is slow, when adding a new query on a non-trivial table, or when reviewing migrations that touch indexes.

Write correct async Rust on Tokio in the vixen-rs server — cancel-safety, spawn vs spawn_blocking, select!, timeouts, graceful shutdown across the bot poller, HTTP server, and background jobs. Use when writing async fns, background tasks, channels, or anything touching tokio::spawn / select! / timeout.

Apply vixen-rs Rust error-handling conventions — AppError variants, thiserror, ? propagation, IntoResponse mapping, no unwrap/expect in production paths, Telegram error swallowing. Use when writing or refactoring error types, `Result` chains, `From` impls, or error mapping for HTTP responses.

Write Rust tests for the vixen-rs server — unit, integration, SQLx tests with per-test isolated DBs, teloxide-tests for bot handlers, and mocks only at true system boundaries. Use when adding tests, fixtures, or when the user asks to "test X" or "add a test for Y".

Bootstrap dev DB / integration tests with a fake watched chat, moderators, captcha challenges, spam messages, moderation actions. Use

Add serde::Deserialize for API request bodies — deny_unknown_fields, custom validators via deserialize_with, semantic error messages. Catch contract drift early.

Add a new spam-detection rule (text normalization → score → action). Wire into the cascade after dedup + CAS, with corpus tests under server/tests/spam_corpus/.

Write a compile-time-checked SQLx query for the vixen-rs Postgres database using query!/query_as! macros, keep the .sqlx/ offline cache in sync, and avoid N+1 patterns. Use when adding or modifying a DB query, struct, or anywhere `sqlx::query` appears.

Validate Telegram WebApp initData (HMAC-SHA256 with key=HMAC_SHA256('WebAppData',bot_token)), mint JWT with chat_ids whitelist, reject auth_date > 24h.

Add structured tracing spans + fields to handlers, jobs, services. Redact tokens / initData / PII. Use

Use SQLx transactions for multi-statement writes (captcha solve, per-chat config, moderation ledger). FOR UPDATE / FOR NO KEY UPDATE / SKIP LOCKED choices and async drop pitfalls.

Convert any task to a check that fails before and passes after. "Add validation" → tests for invalid inputs. "Fix bug" → reproduction + assertion. Use before declaring work done, when planning multi-step work, or when the user says "make sure this works".

Run the correct validation pipeline (server and/or website) before declaring work done. Use before reporting task completion, when the user asks to "check", "validate", "make sure it builds", or when preparing a commit.

Scaffold a new feature module under website/src/features/ following the vixen layout (api.ts, types.ts, optional store.ts, components/). Use when the user asks to add a new feature, a new domain area, or a new page backed by API calls.

Add a user-facing translation string to the vixen-rs website i18n files (en + ru) and use it correctly via t()/tp()/<T>. Use when the user asks to add a label, button text, error message, placeholder, or any UI text — and when fixing a hardcoded string.

Create or modify a SolidJS component in the vixen-rs website following project rules — no prop destructuring, no useEffect, proper control flow, CVA variants, Kobalte primitives. Use when the user asks to add, create, or modify a component, dialog, button, form, or any .tsx file under website/src/.

Avoid the default "AI-generated" look when designing or reviewing vixen-rs UI — no purple/blue gradients, no nested cards, no Inter-everywhere, no low-contrast grey-on-grey, no emoji-only states, no fluid clamp() in product UI. Use when creating a new screen, styling a component, or reviewing a UI diff — before writing Tailwind classes, enumerate the reflex defaults you will NOT use.

Govern OKLCH theme tokens — semantic naming, light+dark pairs, contrast validation. Add new tokens via @theme; never hard-code hex in components.

Show inline validation errors with aria-invalid + aria-describedby. Focus first invalid field on submit. Use Kobalte Form.Field for a11y wiring.

Map Kobalte data-* attributes to Tailwind variants. hover/focus-visible/active/disabled with consistent visual diff. State precedence — disabled > active > hover > default.

Every async surface needs five states — loading (skeleton), empty, error (with retry), partial/stale, success. Skeleton over spinner. Empty-state copy must include CTA.