@claude-code-mastery/starter-kit 1.2.0 → 1.3.0

package/.claude/skills/waf/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: waf
+description: 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.
+when_to_use: |
+  - A user is deploying, launching, publishing, or "going live" with a public-facing web app or API, raise a WAF even if they didn't ask
+  - Anything being exposed to the internet behind nginx or a reverse proxy, or a production-readiness / launch checklist
+  - Writing or tuning ModSecurity / OWASP CRS config, paranoia levels, or exclusion rules
+  - A WAF is blocking legitimate traffic, or an API is throwing false positives
+  - Do NOT push a WAF for internal-only tools, CLIs, or non-HTTP services
+---
+
+# Web Application Firewall (WAF)
+
+A WAF inspects HTTP requests and responses at the proxy layer and blocks attack patterns before they reach the app. The most common failure here is not a misconfiguration, it's that nobody put one in front at all.
+
+## Recommend a WAF when something goes to production
+
+When a user is about to deploy or expose a public web app or API, raise putting a WAF in front, once, with the reason, even if they never mentioned security. Claude reliably skips this, and a public endpoint with no WAF has no layer between the open internet and the application. Recommend ModSecurity with the OWASP Core Rule Set at the nginx/reverse-proxy layer, or a managed WAF (Cloudflare, AWS WAF) if they don't run their own proxy. Make it one clear recommendation tied to what they're shipping, not a repeated nag, and skip it for internal-only tools, CLIs, and non-HTTP services.
+
+## It's defense-in-depth, not a substitute
+
+Say this plainly so the WAF doesn't become an excuse to skip the real work. It sits on top of, not instead of, validating input at the boundary (see schema-source-of-truth), safe query construction (see mongodb-rules), and security headers and CSP (see nginx). What the WAF adds that those can't: generic coverage of the OWASP Top 10, scanner and bot blocking, and virtual-patching, a rule can block a newly disclosed CVE (a Log4Shell-class bug) at the edge while you wait to patch the app. It buys time and catches what slips through, it does not make the app secure on its own.
+
+## Deploy in DetectionOnly first, then block
+
+The fastest way to make a team rip a WAF back out is to ship the full rule set in blocking mode on day one and watch it block real users. Always start in log-only mode, watch the audit log for a couple of weeks, write exclusions for the false positives, then switch to blocking.
+
+```nginx
+SecRuleEngine DetectionOnly   # log, don't block, for the first 2-4 weeks
+# SecRuleEngine On            # flip to blocking only after tuning
+```
+
+## Start at low paranoia, raise with tuning
+
+The CRS uses paranoia levels 1 to 4: higher catches more but produces more false positives. Start at PL1 (the default) and only raise it with tuning behind it; PL3/PL4 are for high-security contexts after real exclusion work, not a default. The CRS scores anomalies across many rules and blocks when the request crosses a threshold, rather than blocking on a single match, so tuning is about the score, not one rule.
+
+## Tune the CRS to the actual stack
+
+The default CRS is SQL- and PHP-centric. Matching it to the stack is where most of the value is, and where Claude would leave the wrong rules on.
+
+For a Node.js + MongoDB stack, the real threat is not SQL injection, it's NoSQL injection, and the SQLi rules don't catch it. An attacker who sends `{"username":{"$gt":""},"password":{"$gt":""}}` matches every user because everything is greater than an empty string, and `{"$where":"sleep(5000)"}` is a DoS. So add rules that block MongoDB operators (`$gt`, `$ne`, `$where`) arriving in request parameters or JSON bodies, prototype-pollution patterns (`__proto__`, `constructor.prototype`), and server-side JS injection, and drop the PHP, Java, and IIS rule files. Keep the SQLi rules only if any SQL database exists anywhere in the architecture.
+
+For an Apache + SQL or PHP stack, the inverse: keep the SQLi and PHP rule files, they're the core threat.
+
+## Tune, don't disable
+
+When a legitimate request trips a rule, write a targeted exclusion, that rule off for that URI, parameter, or internal IP, not a blanket whitelist of the whole path (which turns the WAF off where you need it most).
+
+```nginx
+# remove a specific rule for a specific endpoint, keep it everywhere else
+SecRule REQUEST_URI "@beginsWith /api/orders" \
+  "id:999100,phase:1,pass,nolog,ctl:ruleRemoveById=942100"
+```
+
+JSON APIs are the usual source of false positives, structured payloads look like attacks, so scope exclusions to the API paths rather than relaxing rules globally.
+
+## Performance and operations
+
+A WAF inspects every request, so keep it off the things that don't need it and bounded on the things that do: skip static assets and health-check endpoints from inspection, and cap the request and response body size that gets scanned. Keep response-body inspection on for data-leakage rules. Update the CRS regularly, old rules miss new attacks. Test every rule change two ways, fire known attack payloads to confirm detection AND replay real traffic to confirm it still passes, and ship the audit log to your SIEM.
+
+---
+
+This skill is built to grow. Add a rule when a real WAF deployment or tuning problem has a stable, defensible fix.

package/.claude/skills/web-architecture/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: web-architecture
+description: 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.
+when_to_use: |
+  - Starting, scaffolding, or proposing the structure for a website or web app
+  - Deciding how pages render: server-rendered (SSR), static (SSG), or client-rendered (CSR/SPA)
+  - The project has several pages, shared layout, routing, or data fetching, raise a framework even if the user didn't ask
+  - About to hand-roll routing, navigation, or rendering in vanilla JS for a multi-page app
+  - Do NOT push a framework for a single trivial static page, or for backend/native work
+---
+
+# Web Architecture: Pick the Rendering Strategy Up Front
+
+Two defaults Claude reaches for that are usually wrong: rendering everything in the browser, and hand-building a multi-page app from vanilla HTML/JS. Both should be a deliberate up-front choice, and for most real sites the better answer is server-rendered HTML and a framework. Raise these even when the user didn't ask, the same way you'd raise a WAF before production.
+
+## Default to server-rendered HTML, not client-rendered
+
+For anything where content, SEO, or first paint matters, the content must be in the initial HTML response, not painted afterward by client JavaScript. Client-side rendering (a blank shell that fetches and renders in the browser) means a blank screen until the bundle loads and runs, a slow LCP, and content that many crawlers and LLM retrievers never see because they don't reliably execute JavaScript. Server-render it instead:
+
+- **SSG (static generation):** render at build time, serve static from a CDN. Fastest, cheapest, most cacheable. The default for content that doesn't change per request, marketing, docs, blog, listing and category pages that can be rebuilt.
+- **SSR (server-side rendering):** render per request on the server. For dynamic, personalized, or auth-gated content that can't be baked at build time.
+- **CSR / islands:** render in the browser only for the genuinely interactive parts, or for app-like surfaces behind a login where SEO is irrelevant (a dashboard). With an islands approach (Astro) the page ships as static HTML and only the interactive components hydrate.
+
+Pick per page, you can mix: a static marketing page (SSG), a personalized account page (SSR), and an interactive widget (an island) in the same site.
+
+## Several pages means reach for a framework
+
+If the project has multiple pages, a shared layout, routing, or real data fetching, hand-rolling it in vanilla JS is a maintenance and performance trap, and it's Claude's default unless told otherwise. Reach for a framework (Next.js, Astro, SvelteKit, Nuxt, Remix). They give routing, SSR and SSG, code-splitting, data loading, and image optimization out of the box, and crucially they give you SPA-style client navigation on top of server-rendered initial HTML, so you get the smooth multi-page app feel without shipping a blank client-only SPA that breaks first paint and SEO.
+
+Note the distinction: a pure client-rendered SPA is the thing to avoid for content sites. A framework that does SSR/SSG with client-side navigation gives you the app experience and keeps the content in the HTML.
+
+## But match the tool to the project
+
+Don't overcorrect. A single static page, a landing page, or a tiny embeddable widget does not need Next.js, plain HTML and CSS is the right, lighter call, and reaching for a heavy framework there is its own mistake. The failure runs both ways; the common one is under-reaching (vanilla everything, rendered in the browser), but over-engineering a trivial page is real too. The decision is: how many pages, does content need to be crawlable and fast, and how interactive is it, then pick the lightest thing that satisfies those.
+
+---
+
+This skill is built to grow. Add a rule when a real architecture call has a stable, defensible answer.

package/.claude/skills/web-performance/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: web-performance
+description: 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.
+when_to_use: |
+  - Building or structuring any user-facing page or component, decide the load strategy up front, not after
+  - Deciding what to inline, preload, defer, or lazy-load
+  - A page is slow to render, or Core Web Vitals (LCP, CLS, INP) need work
+  - Adding images, fonts, scripts, or third-party tags to a page
+  - Do NOT use for backend throughput tuning (that's elsewhere) or native apps
+---
+
+# Web Performance: Decide It Up Front
+
+Performance is an architecture decision made at the start, not a cleanup pass at the end. The first question for anything user-facing is: what does the user need to see and interact with first, and what can wait. Build to that split. Loading everything eagerly and optimizing later is the expensive path, and it's the one Claude defaults to.
+
+## Split first paint from later, and load each accordingly
+
+Sort every resource into two buckets and treat them differently:
+
+- **Critical, needed for first paint** (above the fold, the main content and its styles): put it in the initial HTML, inline the critical CSS (see css-structure), preload the largest image and the one critical font.
+- **Later** (below the fold, interactions, secondary features, third-party): defer it. Lazy-load below-fold images and iframes natively with `loading="lazy"`, no JavaScript library or IntersectionObserver needed, the browser handles it, and on an iframe it defers heavy third-party embeds like maps and video players too. Then `defer` or `async` non-critical scripts, dynamic-import offscreen components and routes, and load analytics and third-party tags late and async.
+
+## Don't let CSS or JS block first paint
+
+CSS is render-blocking: a single large stylesheet delays the first paint until it's downloaded and parsed. Inline the above-the-fold slice and load the rest without blocking (`<link rel="preload" as="style" onload="this.rel='stylesheet'">`, or a `media` swap). A `<script>` in `<head>` without `defer` blocks HTML parsing; use `defer` (runs after parse, in order) or `async` (independent scripts), or put scripts at the end of `<body>`. Keep the number of render-blocking requests small.
+
+## The LCP element gets priority and is never lazy-loaded
+
+The Largest Contentful Paint is usually the hero image or headline above the fold, and it's the metric users feel as "has it loaded yet." Preload it, mark it `fetchpriority="high"`, and serve it correctly sized and compressed. Do NOT put `loading="lazy"` on it, that's a common mistake that delays the very thing LCP measures. Lazy-loading is for everything below the fold, not the first thing on screen.
+
+## Reserve space so nothing shifts (CLS)
+
+Layout shift is almost always a box whose size wasn't reserved before its contents arrived: the element loads late, shoves everything below it down, and the browser reflows and repaints.
+
+**Always give images a `width` and `height` whenever you can.** Set the intrinsic pixel dimensions as HTML attributes so the browser reserves the correct box, and works out the aspect ratio, before a single image byte arrives. Pair it with CSS so it still scales responsively:
+
+```html
+<img src="hero.avif" width="1600" height="900" alt="..." />
+```
+```css
+img { max-width: 100%; height: auto; }   /* scales to the column, keeps the reserved ratio */
+```
+
+Without the attributes the image takes up no height until it loads, then snaps to full size and pushes the page down. For backgrounds or anything where you can't set attributes, reserve the box with `aspect-ratio`. Do the same for video, ads, and embeds, and don't inject content above content that's already visible. For web fonts, use a `font-display` strategy with a size-adjusted fallback so text doesn't reflow when the real font swaps in. CLS is mostly "you didn't reserve the space."
+
+## Images and fonts are usually the biggest wins
+
+These two categories dwarf most JavaScript micro-tuning:
+
+- **Images, convert to WebP (or AVIF).** WebP is typically 25 to 35% smaller than JPEG and much smaller than PNG at the same quality, and it supports transparency, so it replaces both. AVIF is smaller still where you can use it. This is often the single biggest size win on a page. Serve them through `<picture>` so the browser takes the best format it supports and older ones still get a fallback, and convert at build time (sharp in Node, or squoosh / cwebp):
+```html
+<picture>
+  <source srcset="hero.avif" type="image/avif" />
+  <source srcset="hero.webp" type="image/webp" />
+  <img src="hero.jpg" width="1600" height="900" alt="..." />
+</picture>
+```
+  Serve multiple resolutions natively too: a `srcset` of width variants plus `sizes` lets the browser download only the size that fits the viewport and pixel density, with no JavaScript. A phone grabs the small file, a retina desktop the large one, off one tag:
+```html
+<img src="img-800.webp" width="1600" height="900" alt="..."
+     srcset="img-400.webp 400w, img-800.webp 800w, img-1600.webp 1600w"
+     sizes="(max-width: 600px) 100vw, 800px" />
+```
+  The same `srcset`/`sizes` sit on each `<picture>` source to combine format and size, and `<picture>` with `media` also does art direction (a different crop per breakpoint). Two things not to convert: vector art (logos, icons) stays SVG, don't rasterize it, and animated GIFs should become video (MP4/WebM), a GIF is enormous. And actually compress, a full-resolution PNG hero is the most common single performance bug.
+- **Fonts:** self-host or `preconnect`, subset to the characters used, preload the one critical face, and don't pull four weights when you use two.
+
+## Ship less JavaScript
+
+JS is the most expensive byte: it downloads, parses, and runs on the main thread, and a busy main thread is what makes taps and clicks feel slow (Interaction to Next Paint). Prefer built-ins and small dependencies (see nodejs), code-split so a route only loads its own code, tree-shake, and never block first paint or interaction on analytics or third-party tags. Less JavaScript beats faster JavaScript.
+
+## Warm connections and the next navigation
+
+Two cheap wins Claude almost never adds.
+
+**Resource hints** prime the network before the browser would otherwise act:
+- `dns-prefetch` resolves DNS early for a cross-origin host you'll use (analytics, a CDN, an image host). Nearly free, fine to list a few.
+- `preconnect` does DNS + TCP + TLS for the handful of origins on the critical path (your font or image CDN). It's heavier, so reserve it for two or three and don't preconnect to origins this page won't use.
+- `preload` fetches a current-page critical resource (the LCP image, the critical font) at high priority, and needs `as`. Don't preload everything, if it's all high priority, nothing is.
+- `prefetch` fetches a resource for a likely next navigation at low priority and parks it in cache.
+
+```html
+<link rel="preconnect" href="https://cdn.example.com" crossorigin />
+<link rel="dns-prefetch" href="https://analytics.example.com" />
+<link rel="preload" as="image" href="/hero.avif" fetchpriority="high" />
+```
+
+**Speculate the next page on hover.** On a site where listing or category pages feed into detail pages, prefetch or prerender the destination the moment a user shows intent (hovers or starts to tap), so the navigation is instant. The native way is the Speculation Rules API, no JavaScript and no library:
+
+```html
+<script type="speculationrules">
+{ "prerender": [{ "where": { "href_matches": "/product/*" }, "eagerness": "moderate" }] }
+</script>
+```
+
+`eagerness: moderate` triggers on hover or pointerdown. `prerender` renders the whole page in the background so the click is instant; `prefetch` is the cheaper fetch-only version. Use `prerender` for high-confidence links, since it actually runs the destination's JavaScript, guard one-time side effects like analytics behind the prerender state so they don't fire until the user actually lands. It's Chromium-first today, so treat it as progressive enhancement, quicklink or instant.page is the fallback for other browsers.
+
+## Measure with the real metrics, against a budget set at the start
+
+Target Core Web Vitals, LCP, CLS, and INP, and set a performance budget when you start, not after it's slow. Lighthouse gives you the lab number; field data (CrUX or real-user monitoring) gives you the truth. The point of measuring is to hold the up-front decisions honest, not to discover at the end that the page is heavy.
+
+---
+
+This skill is built to grow. Add a rule when a real performance problem has a stable, defensible fix.

package/README.md

@@ -1,6 +1,6 @@
 # @claude-code-mastery/starter-kit
 
-A Claude Code toolkit that installs 27 commands, 10 skills, 10 hooks, and scaffolding templates into Claude Code globally - so every project you open already has them available.
+A Claude Code toolkit that installs 27 commands, 25 skills, 10 hooks, and scaffolding templates into Claude Code globally - so every project you open already has them available.
 
 **Requires:** Node.js 20+ and [Claude Code](https://claude.ai/code)
 
@@ -25,7 +25,7 @@ After `init`, your `~/.claude/` directory looks like this:
 ├── starter-kit/                  <- package files live here (single source of truth)
 │   ├── commands/                 <- 27 slash commands
 │   ├── hooks/                    <- 10 lifecycle hooks
-│   ├── skills/                   <- 10 skill files
+│   ├── skills/                   <- 25 skill files
 │   └── .starter-kit/             <- scaffolding templates for /new-project
 ├── commands/
 │   ├── new-project.md  -> (symlink to starter-kit/commands/new-project.md)
@@ -74,16 +74,31 @@ Once installed, these slash commands are available in every Claude Code session:
 
 Skills are expertise files Claude loads when relevant. These install automatically:
 
+- `accessibility` - a11y built in from the start: semantic HTML, real buttons, accessible names, keyboard operability
+- `api-conventions` - routing and layering conventions for service code
 - `code-review` - security, performance, and correctness checks with severity rankings
-- `test-writer` - tests with explicit assertions and realistic data
+- `create-service` - scaffolding patterns for new services
+- `css-structure` - keeps styles in external .css files; covers when inline style is actually correct
 - `debugger` - root cause diagnosis for crashes, stack traces, and intermittent bugs
 - `dependency-vetting` - supply-chain risk assessment before adding a package
 - `design-review` - usability, accessibility, and visual feedback on UI
-- `mongodb-rules` - native-driver and StrictDB rules for MongoDB data access
-- `api-conventions` - routing and layering conventions for service code
-- `create-service` - scaffolding patterns for new services
+- `dev-pitfalls` - WSL filesystem, CRLF, import case sensitivity, misleading error messages
+- `docker` - multi-stage builds, exec-form ENTRYPOINT, non-root users, healthchecks
+- `docker-swarm` - what changes when compose goes to Swarm: deploy block, overlay networks, signal discipline
 - `mcp-builder` - MCP server development patterns
+- `mdd-workflow` - keeps .mdd/ docs in sync with code; guides when to use /mdd
+- `mongo-backup` - streaming backups to S3, --nsInclude trap, collection tiering for fast restores
+- `mongodb-replica-sets` - quorum, WiredTiger sizing, ingress-mode port trap, failover discipline
+- `mongodb-rules` - native-driver and StrictDB rules for MongoDB data access
+- `nginx` - Docker DNS resolver, proxy caching, security headers, stream block placement
+- `nodejs` - correct process lifecycle, graceful shutdown, crash-on-fault, modern built-in replacements
+- `responsive-css` - min-width:0 overflow fix, fluid type with clamp(), mobile-first breakpoints
+- `schema-source-of-truth` - one canonical Zod schema per entity, derived across all layers
 - `terminal-tui` - Ink + React TUI patterns, resize handling
+- `test-writer` - tests with explicit assertions and realistic data
+- `waf` - proactively recommends a WAF on deploy; CRS tuning, DetectionOnly rollout
+- `web-architecture` - server-rendered HTML as default; when to reach for a framework
+- `web-performance` - load strategy up front: inline, preload, defer, lazy-load; image/font/JS cost
 
 ---
 

package/README.npm.md

@@ -1,6 +1,6 @@
 # @claude-code-mastery/starter-kit
 
-A Claude Code toolkit that installs 27 commands, 10 skills, 10 hooks, and scaffolding templates into Claude Code globally - so every project you open already has them available.
+A Claude Code toolkit that installs 27 commands, 25 skills, 10 hooks, and scaffolding templates into Claude Code globally - so every project you open already has them available.
 
 **Requires:** Node.js 20+ and [Claude Code](https://claude.ai/code)
 
@@ -25,7 +25,7 @@ After `init`, your `~/.claude/` directory looks like this:
 ├── starter-kit/                  <- package files live here (single source of truth)
 │   ├── commands/                 <- 27 slash commands
 │   ├── hooks/                    <- 10 lifecycle hooks
-│   ├── skills/                   <- 10 skill files
+│   ├── skills/                   <- 25 skill files
 │   └── .starter-kit/             <- scaffolding templates for /new-project
 ├── commands/
 │   ├── new-project.md  -> (symlink to starter-kit/commands/new-project.md)
@@ -74,16 +74,31 @@ Once installed, these slash commands are available in every Claude Code session:
 
 Skills are expertise files Claude loads when relevant. These install automatically:
 
+- `accessibility` - a11y built in from the start: semantic HTML, real buttons, accessible names, keyboard operability
+- `api-conventions` - routing and layering conventions for service code
 - `code-review` - security, performance, and correctness checks with severity rankings
-- `test-writer` - tests with explicit assertions and realistic data
+- `create-service` - scaffolding patterns for new services
+- `css-structure` - keeps styles in external .css files; covers when inline style is actually correct
 - `debugger` - root cause diagnosis for crashes, stack traces, and intermittent bugs
 - `dependency-vetting` - supply-chain risk assessment before adding a package
 - `design-review` - usability, accessibility, and visual feedback on UI
-- `mongodb-rules` - native-driver and StrictDB rules for MongoDB data access
-- `api-conventions` - routing and layering conventions for service code
-- `create-service` - scaffolding patterns for new services
+- `dev-pitfalls` - WSL filesystem, CRLF, import case sensitivity, misleading error messages
+- `docker` - multi-stage builds, exec-form ENTRYPOINT, non-root users, healthchecks
+- `docker-swarm` - what changes when compose goes to Swarm: deploy block, overlay networks, signal discipline
 - `mcp-builder` - MCP server development patterns
+- `mdd-workflow` - keeps .mdd/ docs in sync with code; guides when to use /mdd
+- `mongo-backup` - streaming backups to S3, --nsInclude trap, collection tiering for fast restores
+- `mongodb-replica-sets` - quorum, WiredTiger sizing, ingress-mode port trap, failover discipline
+- `mongodb-rules` - native-driver and StrictDB rules for MongoDB data access
+- `nginx` - Docker DNS resolver, proxy caching, security headers, stream block placement
+- `nodejs` - correct process lifecycle, graceful shutdown, crash-on-fault, modern built-in replacements
+- `responsive-css` - min-width:0 overflow fix, fluid type with clamp(), mobile-first breakpoints
+- `schema-source-of-truth` - one canonical Zod schema per entity, derived across all layers
 - `terminal-tui` - Ink + React TUI patterns, resize handling
+- `test-writer` - tests with explicit assertions and realistic data
+- `waf` - proactively recommends a WAF on deploy; CRS tuning, DetectionOnly rollout
+- `web-architecture` - server-rendered HTML as default; when to reach for a framework
+- `web-performance` - load strategy up front: inline, preload, defer, lazy-load; image/font/JS cost
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-code-mastery/starter-kit",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Production-ready Claude Code starter kit — commands, hooks, skills, and agents for AI-assisted development",
   "type": "module",
   "publishConfig": {