core

# Skill Usage - MANDATORY

YOU MUST evaluate and invoke ALL relevant skills before starting ANY task. You have 150+ skills installed covering design, copywriting, psychology, animation, CRO, SEO, and more. Using 1-2 skills when 10+ are relevant produces inferior output. Compose skills aggressively.

See @~/.claude/instructions/skill-composition.md for skill groups and composition rules.

When doing frontend work: invoke EVERY design skill + EVERY copy skill + CRO + animation skills.
When writing copy: invoke copywriting + psychology + humanizer + headline skills.
When building pages: invoke design + copy + CRO + animation + polish skills.

If you think there is even a 1% chance a skill applies, invoke it. Never rationalize skipping skills.

# Critical Rules

- Never write comments in code
- Always use pnpm for JS/TS projects
- Always use Radix UI + shadcn/ui for components
- Always use Tailwind CSS for styling
- Always use Docker for deployment via Coolify
- Sentry for all observability
- REST only, no GraphQL
- Validate all user inputs, parameterized queries, never commit secrets

# Imported Instructions

@~/.claude/instructions/git-workflow.md
@~/.claude/instructions/tech-stack.md
@~/.claude/instructions/code-style.md
@~/.claude/instructions/security.md
@~/.claude/instructions/honcho-memory.md

# Screenshots from Zach

When Zach sends a link of the form `https://cdn.zach.best/i/<code>` (e.g. `https://cdn.zach.best/i/s6tphc1t`), that's him sharing a screenshot with you. The link is a viewer URL; the raw image lives at the same code plus `.webp` — e.g. `https://cdn.zach.bes…

# Code Style

## General
- Readability over cleverness, descriptive names
- Explicit error handling, never silently fail
- Comments explain WHY not WHAT
- TODOs: `// TODO(zach): reason`

## TypeScript/JavaScript
- const > let, never var
- async/await over raw promises
- Functional array methods, optional chaining, nullish coalescing
- Explicit return types

## Python
- PEP 8, type hints, f-strings, comprehensions when readable

## Rust
- Idiomatic Rust, Result<T,E>, ownership over cloning

## Files: NEVER touch .env, node_modules, .git, dist/build, *.key/*.pem, secrets/

# Git Commit Standards

ALL commits MUST use conventional commits: `<type>(<scope>): <description>`

Types: feat, fix, docs, chore, refactor, style, test, perf, ci, build
- Lowercase type, imperative mood, under 72 chars, no full stop
- NEVER: "WIP", "fix", "update", past tense, uppercase types

## Branch Naming
- `feature/<ticket-id>-<short-description>`
- `fix/<ticket-id>-<short-description>`
- `hotfix/<description>`, `refactor/<description>`, `chore/<description>`

## Pull Requests
- Title follows conventional commit format
- Include description of changes and why
- Ensure CI passes before merging, delete branch after

# Security

- Never commit API keys, tokens, passwords, private keys, credentials
- Validate and sanitize all user inputs
- Parameterized queries (prevent SQL injection)
- Rate limiting on APIs, HTTPS only in production
- Keep dependencies updated, follow OWASP Top 10

# Skill Composition Rules

IMPORTANT: You have 150+ skills installed. Before starting ANY task, you MUST evaluate which skills are relevant and invoke ALL of them. Never use just 1-2 skills when multiple apply. The more skills you compose together, the better the output.

## Skill Groups - Invoke ALL skills in a matching group

### Frontend Design (building/editing UI)
Invoke: impeccable, human-grade-frontend-design, frontend-design, design-taste-frontend, high-end-visual-design, ui-ux-pro-max, senior-ui-ux, web-designer, refinery-ux, brand-skill, shadcn, tailwind-v4-shadcn
Also consider: typeset, layout, colorize, adapt, polish, critique, audit, bolder

### Animation & Motion (any animation work)
Invoke: gsap-core, gsap-react, gsap-scrolltrigger, gsap-timeline, gsap-plugins, gsap-performance, motion-dev-animations, design-motion-principles, emil-design-eng, animate, delight, overdrive

### Copywriting (writing/editing marketing copy)
Invoke: copywriting, copy-editing, copywriting-psychologist, headline-psychologist, landing-page-copywriter, humanizer, emotional-arc-designer, awareness-stage-mapper, objection-preemptor
Also for ads: ad-creative, social-content, cold-email, email-sequence

### Marketing Psychology (positioning, persuasion, pricing)
Invoke: marketing-psychology, brand-perception-psychologist, price-psychology-strategist, awareness-stage-mapper, emotional-arc-designer, objection-preemptor, marketing-ideas

### CRO (conversion optimization on any page/flow)
Invoke: page-cro, conversion-audit, signup-flow-cro, onboarding-cro, form-cro, popup-cro, paywall-upgrade…

# Tech Stack & Architecture

## Frontend: Next.js (default, App Router) + Tailwind CSS + Radix/shadcn
- React + Vite only when backend is Python/separate service
- Always start with shadcn/ui, build custom on top
- Always use pnpm
- Turbopack for Next.js, Vite for React+Python

## Backend: Flask or FastAPI (Python)
- Express.js only for dead simple APIs
- Rust ONLY for performance-critical workers, never web servers
- REST APIs only, no GraphQL
- Always use OpenAPI/Swagger docs
- **Always use `uv` for Python package management — NEVER `pip`, `pip3`, `pip-tools`, `pipenv`, or `poetry`.**
  - Install: `uv pip install <pkg>` (or `uv add <pkg>` in a uv-managed project)
  - Sync from lockfile: `uv sync`
  - Run a script: `uv run <script>`
  - Create venv: `uv venv`
  - New project: `uv init`
  - If a project still uses pip/poetry/pipenv, propose migrating to uv first — don't fall back to the legacy tool

## Database
- PostgreSQL (production), MySQL (client pref), SQLite (prototypes)
- MongoDB for document-model Python apps, Redis for caching/queues
- Default to raw SQL, use Alembic for migrations

## Auth: JWT (stateless), Session (SSR), OAuth2 (social) - project-specific

## Deployment
- Always Docker + Docker Compose
- Deploy via Coolify (Traefik reverse proxy)
- No Kubernetes, no CI/CD pipelines

## Observability: Sentry for everything
- Structured JSON logging, never log secrets

## Architecture
- Small focused components (<300 lines), functions (<50 lines)
- Separate business logic from UI/routes
- React hooks + Context for state, avoid Redux
- React Query/SWR for server st…