@claude-code-mastery/starter-kit 1.2.1 → 1.3.1

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, 11 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/                   <- 11 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,17 +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
-- `schema-source-of-truth` - one canonical Zod schema per entity, derived across all layers; catches the same shape defined four times drift
+- `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, 11 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/                   <- 11 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,17 +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
-- `schema-source-of-truth` - one canonical Zod schema per entity, derived across all layers; catches the same shape defined four times drift
+- `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/bin/cli.js

@@ -3,6 +3,7 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import https from 'https';
+import { execSync } from 'child_process';
 import { fileURLToPath } from 'url';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -160,6 +161,17 @@ export function mergeSettings(homeDir = os.homedir()) {
   fs.writeFileSync(glPath, JSON.stringify(gl, null, 2), 'utf8');
 }
 
+// ── MDD integration ───────────────────────────────────────────────────────────
+
+function runMddInstall() {
+  try {
+    execSync('npm install -g @thedecipherist/mdd', { stdio: 'inherit' });
+    execSync('mdd install', { stdio: 'inherit' });
+  } catch {
+    console.log('  ⚠  MDD install skipped — run manually: npm install -g @thedecipherist/mdd && mdd install');
+  }
+}
+
 // ── main commands ─────────────────────────────────────────────────────────────
 
 export async function init(homeDir = os.homedir()) {
@@ -176,6 +188,8 @@ export async function init(homeDir = os.homedir()) {
     console.log(`  Copied claude-mastery-project.conf → ${claudeDir}`);
   }
   fs.writeFileSync(path.join(claudeDir, 'starter-kit-source-path'), starterKitDir, 'utf8');
+  console.log('\nInstalling MDD workflow...');
+  runMddInstall();
   const version = readInstalledVersion(homeDir);
   console.log(`\n✅ Installed v${version} to ${starterKitDir}`);
   console.log('   Run /starter-kit update inside Claude Code to update in future.\n');
@@ -191,6 +205,8 @@ export async function update(homeDir = os.homedir()) {
   copyPackageFiles(homeDir);
   symlinkAll(homeDir);
   mergeSettings(homeDir);
+  console.log('\nUpdating MDD workflow...');
+  runMddInstall();
   console.log(`\n✅ Updated to v${readInstalledVersion(homeDir)}`);
 }
 

package/package.json

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