claude-code-mastery-project-starter-kit

Accessibility and screen-reader support, built in from the start rather than bolted on. Claude treats a11y as an afterthought and reaches for clickable divs, skips alt text and labels, and removes focus rings. Use when building or editing any UI, page, or interactive component. Covers semantic HTML before ARIA, real buttons and links, accessible names, keyboard operability and focus management, headings and landmarks, contrast and motion, and how to actually test it. Most of it is free if you use the right element.

Service structure conventions for this codebase: routing, layering, and where code lives. Use whenever writing or modifying a service's server entry, route definitions, handlers, or adapters. Loads inline so it shapes structure as code is written.

Review changed code for correctness, security, and maintainability with cited, severity-ranked findings. Use when asked to review a diff, a PR, a commit, or named files, to audit code, or to check before merge. Runs isolated and read-only, reports findings, does not edit.

Scaffold a new microservice that follows the project's server/handlers/adapters architecture. Use when asked to create, scaffold, or add a new service or package. Writes files and may create a git branch, so it runs only when invoked explicitly.

Where CSS should live. Claude defaults to dumping a giant <style> block or scattering style="..." attributes instead of putting styles in a .css file and linking it. Use when building or editing a web page or component, or whenever about to write a style attribute or an embedded style block. Covers defaulting to an external stylesheet, why inline style attributes are a trap, and the few cases where inline is actually correct (dynamic values via custom properties, critical CSS, single-file artifacts, email).

Common pitfalls that are slow to troubleshoot and that tend to get "fixed" by going in circles, because the error message points nowhere near the actual cause. Use before and during git, project, and WSL work, checking a repo is initialized and node_modules is ignored, putting WSL projects on the right filesystem, opening a browser from WSL for auth, normalizing line endings, and matching import case. Check the layer here first instead of debugging the wrong one.

Production Docker best practices for writing Dockerfiles, Compose files, and Swarm stacks. Use whenever creating or editing a Dockerfile, a docker-compose / compose.yaml, or a stack file, or building and optimizing an image. Fixes the handful of things Claude reliably gets wrong: multi-stage builds, layer-cache ordering, exec-form ENTRYPOINT for correct signals and exit codes, init:true, keeping secrets and env out of the image, non-root users, and healthchecks. From production, not defaults.

Production Docker Swarm deployment rules: what changes when a compose file goes from a single node to a multi-node Swarm. Use when writing or reviewing a stack file, a deploy block, an overlay network, or anything deployed with docker stack deploy. Covers the directives Swarm silently ignores, why fixed IPs and bind mounts break, the deploy orchestration block, and the exit-code and healthcheck discipline that Swarm self-healing depends on. Complements the docker skill, which covers writing the image and compose file itself.

Use in any project that uses MDD (a `.mdd/` directory exists) when editing source code, building a feature, fixing a bug, requesting an audit, or editing `.mdd/docs` files. Keeps feature docs in sync the moment their controlled source files change, recommends the `/mdd` workflow for substantial tasks, and conforms to `.mdd` doc conventions. Installed globally, so it self-gates: it does nothing in projects that don't use MDD.

Production MongoDB backup and restore practices that the documentation gets wrong. Use when writing a mongodump/mongorestore pipeline, a backup cron job, an S3 backup, or a selective restore, or when planning recovery. Covers streaming to object storage with no temp file, saving a collection inventory, the --nsInclude trap on gzipped archives, collection tiering for fast restores, and matching write concern to data criticality. Defers replica-set topology and tuning to mongodb-replica-sets, and query patterns to mongodb-rules.

Production MongoDB replica-set operation: topology, durability, host tuning, and the container-specific gotchas Claude gets wrong. Use when setting up or configuring a replica set, writing its connection string, choosing read preference or write concern, running MongoDB in Docker or Swarm, or planning failover and upgrades. Covers odd-member quorum, connecting via the set rather than one node, WiredTiger cache sizing, the OS tuning MongoDB requires, why ingress-mode ports break a replica set, and oplog/failover discipline. Defers query and index shape to mongodb-rules and backup pipelines to mongodb-backups.

Native-driver, StrictDB, and data-modeling rules for MongoDB. Use whenever writing or modifying queries, writes, indexes, aggregations, upserts, connections, or schema against MongoDB, or any code that touches the data layer. Loads inline so it shapes code as it's written.

Production NGINX configuration best practices, especially as a reverse proxy in front of containerized backends. Use when writing or editing nginx.conf, server blocks, upstreams, SSL, proxy caching, security headers, structured logging, or stream (TCP/UDP) proxying. Covers the Docker-DNS resolver that keeps upstreams from going stale, separate access-controlled health ports, the stream-block placement gotcha, and headers that must be sent on errors too. Kept separate from the docker and docker-swarm skills.

Node.js backend runtime and process-lifecycle rules that Claude reliably gets wrong. Use when writing a Node server or long-running script, an Express app, worker threads, or process signal handling, and when choosing packages. Covers correct graceful shutdown, crash-on-fault instead of swallowing errors, not blocking the event loop, loading instrumentation first, securing the session cookie, and replacing deprecated packages with built-ins. Defers MongoDB to mongodb-rules, schema/validation to schema-source-of-truth, and image/deploy to docker and docker-swarm.

Writing CSS and markup that works on phone and desktop at the same time, the responsive failures Claude repeats. Use when building or editing any web page or component, or when something overflows horizontally, a code block blows out the page, text is huge on mobile, or content won't scroll on touch. Covers the viewport meta tag, the flex/grid min-width:0 rule that fixes most overflow, code blocks that scroll instead of overflowing, fluid type with clamp(), and mobile-first breakpoints. This is authoring guidance, design-review evaluates the result.

Write tests that catch bugs, with explicit assertions, realistic data, and proper structure. Use when asked to write, add, improve, or expand tests, or to raise coverage. Writes test files and runs them to confirm they assert real behavior.

Use when building or modifying an interactive terminal UI (TUI), especially with Ink + React on Node, or when hitting terminal-resize rendering bugs — ghost/repeated content, a blank screen after resize, or a divider/layout that won't update width. Carries battle-tested resize rules Claude otherwise gets wrong. Not for plain non-interactive CLIs (flag parsing, scripts) with no full-screen rendering.

Web Application Firewall guidance, when to put one in front of an app and how to run it without breaking traffic. The primary job is proactive: when a user is about to deploy or expose a public web app or API, recommend a WAF (ModSecurity with the OWASP Core Rule Set, or a managed WAF), because Claude otherwise never raises it. Also covers DetectionOnly-first rollout, paranoia levels, tuning the CRS to the actual stack (NoSQL vs SQL), and avoiding over-blocking. A WAF is defense-in-depth, not a replacement for input validation.

Choosing how a web app renders and whether to use a framework, decided up front. Claude defaults to client-side rendering and hand-rolled vanilla HTML/JS, which is usually the wrong starting point for content sites and multi-page apps. Use when starting or scaffolding a site or app, deciding how pages render (SSR, SSG, CSR), or about to hand-build routing and state. Covers defaulting to server-rendered HTML for first paint and SEO, reaching for a framework when there are several pages, and not over-engineering a single page.

Web performance as an up-front design decision, not a later optimization pass. Use when building any user-facing page or component, deciding what loads when, or fixing a slow load or Core Web Vitals (LCP, CLS, INP). The organizing principle is to split what the user needs for first paint from what can wait, and build to that split from the start. Covers render-blocking CSS/JS, preloading the LCP element, lazy-loading the rest, reserving space to stop layout shift, and image/font/JS cost.

One canonical Zod schema per entity, reused across the stack instead of redeclared at each layer. Use whenever defining or changing a data shape, a TypeScript type or interface for an entity, an API request/response validator, an Express body/query/params check, a frontend form validator, or a DB document shape. Catches the same-entity-defined-four-times drift. TypeScript-first, derive types and per-layer variants from one base instead of hand-writing parallel copies.

Diagnose failures by root cause, not symptom. Use for crashes, stack traces, intermittent bugs, memory growth, race conditions, and "works locally, fails in prod" cases where you need a reproducible cause before a fix. Runs isolated and read-only, reports the root cause and fix.

Vet an npm (or other) package for supply-chain risk before it's added to a project. Use when asked whether a package is safe, trustworthy, or worth adding, when about to install an unfamiliar dependency, or when something about a package feels off. Runs isolated and read-only, reports an evidence-backed risk verdict, does not install anything.

Critique UI and UX for usability, accessibility, and distinctiveness with cited, evidence-based findings. Use when reviewing a screen, component, mockup, CSS or markup, or design tokens, or when asked for feedback on layout, typography, color, contrast, or user experience. Runs isolated and read-only, reports findings, does not edit.

Build a high-quality MCP server that exposes a service or API to an LLM through well-designed tools. Use when asked to create, scaffold, or add an MCP server, wrap an API as MCP tools, or expose a service to Claude/agents. Writes files, so it runs only when invoked explicitly.