@kennethsolomon/shipkit 3.2.0 → 3.4.0

package/skills/sk:mvp/references/stacks/react-vite.md

@@ -0,0 +1,287 @@
+# React + Vite + Tailwind — Stack Reference
+
+## Scaffold
+
+```bash
+npm create vite@latest {project-name} -- --template react-ts
+cd {project-name}
+npm install
+npm install -D tailwindcss @tailwindcss/vite
+npm install react-router-dom
+```
+
+## Directory Structure
+
+```
+{project-name}/
+├── src/
+│   ├── main.tsx                ← entry point (router setup)
+│   ├── App.tsx                 ← route definitions
+│   ├── index.css               ← Tailwind directives + custom CSS
+│   ├── pages/
+│   │   ├── Landing.tsx         ← landing page
+│   │   ├── Dashboard.tsx       ← dashboard
+│   │   ├── {Feature1}.tsx
+│   │   ├── {Feature2}.tsx
+│   │   └── Settings.tsx
+│   ├── components/
+│   │   ├── landing/
+│   │   │   ├── Navbar.tsx
+│   │   │   ├── Hero.tsx
+│   │   │   ├── Features.tsx
+│   │   │   ├── HowItWorks.tsx
+│   │   │   ├── Pricing.tsx
+│   │   │   ├── Testimonials.tsx
+│   │   │   ├── WaitlistForm.tsx
+│   │   │   └── Footer.tsx
+│   │   ├── app/
+│   │   │   ├── Sidebar.tsx
+│   │   │   ├── AppLayout.tsx
+│   │   │   ├── DashboardCards.tsx
+│   │   │   └── {feature components}
+│   │   └── ui/
+│   │       ├── Button.tsx
+│   │       ├── Input.tsx
+│   │       ├── Card.tsx
+│   │       ├── Modal.tsx
+│   │       └── Toast.tsx
+│   ├── data/
+│   │   └── mock.ts             ← all fake data centralized
+│   └── lib/
+│       └── utils.ts            ← shared helpers (cn, etc.)
+├── public/
+│   └── {static assets}
+├── index.html
+├── vite.config.ts
+├── tailwind.config.ts
+└── package.json
+```
+
+## Vite Config
+
+`vite.config.ts`:
+
+```ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+})
+```
+
+## Tailwind Config
+
+`tailwind.config.ts`:
+
+```ts
+export default {
+  content: ['./index.html', './src/**/*.{ts,tsx}'],
+  theme: {
+    extend: {
+      colors: {
+        bg: 'var(--color-bg)',
+        fg: 'var(--color-fg)',
+        accent: 'var(--color-accent)',
+        muted: 'var(--color-muted)',
+      },
+      fontFamily: {
+        display: ['var(--font-display)', 'serif'],
+        body: ['var(--font-body)', 'sans-serif'],
+      },
+    },
+  },
+}
+```
+
+CSS variables and font imports in `src/index.css`:
+
+```css
+@import url('https://fonts.googleapis.com/css2?family={DisplayFont}:wght@400;600;700;800&family={BodyFont}:wght@400;500;600&display=swap');
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  --color-bg: #xxxxxx;
+  --color-fg: #xxxxxx;
+  --color-accent: #xxxxxx;
+  --color-muted: #xxxxxx;
+  --font-display: '{DisplayFont}', serif;
+  --font-body: '{BodyFont}', sans-serif;
+}
+
+body {
+  font-family: var(--font-body);
+}
+```
+
+## Router Setup
+
+`src/App.tsx`:
+
+```tsx
+import { createBrowserRouter, RouterProvider } from 'react-router-dom'
+import Landing from './pages/Landing'
+import AppLayout from './components/app/AppLayout'
+import Dashboard from './pages/Dashboard'
+import Feature1 from './pages/{Feature1}'
+import Feature2 from './pages/{Feature2}'
+import Settings from './pages/Settings'
+
+const router = createBrowserRouter([
+  { path: '/', element: <Landing /> },
+  {
+    element: <AppLayout />,
+    children: [
+      { path: '/dashboard', element: <Dashboard /> },
+      { path: '/{feature-1}', element: <Feature1 /> },
+      { path: '/{feature-2}', element: <Feature2 /> },
+      { path: '/settings', element: <Settings /> },
+    ],
+  },
+])
+
+export default function App() {
+  return <RouterProvider router={router} />
+}
+```
+
+## App Layout
+
+`src/components/app/AppLayout.tsx`:
+
+```tsx
+import { Outlet } from 'react-router-dom'
+import Sidebar from './Sidebar'
+
+export default function AppLayout() {
+  return (
+    <div className="flex min-h-screen bg-bg text-fg">
+      <Sidebar />
+      <main className="flex-1 p-6 lg:p-8">
+        <Outlet />
+      </main>
+    </div>
+  )
+}
+```
+
+## Waitlist — Formspree Integration
+
+Since React + Vite has no backend, use Formspree for email collection.
+
+`src/components/landing/WaitlistForm.tsx`:
+
+```tsx
+import { useState, FormEvent } from 'react'
+
+// Replace YOUR_FORM_ID with your Formspree form ID
+// Create one free at https://formspree.io
+const FORMSPREE_URL = 'https://formspree.io/f/YOUR_FORM_ID'
+
+export default function WaitlistForm() {
+  const [email, setEmail] = useState('')
+  const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle')
+  const [message, setMessage] = useState('')
+
+  async function handleSubmit(e: FormEvent) {
+    e.preventDefault()
+    setStatus('loading')
+
+    try {
+      const res = await fetch(FORMSPREE_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+        body: JSON.stringify({ email }),
+      })
+
+      if (res.ok) {
+        setStatus('success')
+        setMessage("You're on the list! We'll notify you when we launch.")
+      } else {
+        throw new Error()
+      }
+    } catch {
+      setStatus('error')
+      setMessage('Something went wrong. Please try again.')
+    }
+  }
+
+  if (status === 'success') {
+    return <p className="text-green-600 font-medium text-lg">{message}</p>
+  }
+
+  return (
+    <form onSubmit={handleSubmit} className="flex flex-col sm:flex-row gap-3 max-w-md">
+      <input
+        type="email"
+        value={email}
+        onChange={e => setEmail(e.target.value)}
+        placeholder="you@example.com"
+        required
+        className="flex-1 px-4 py-3 rounded-lg border border-muted/30 bg-bg focus:ring-2 focus:ring-accent focus:outline-none"
+      />
+      <button
+        type="submit"
+        disabled={status === 'loading'}
+        className="px-6 py-3 bg-accent text-white rounded-xl font-medium hover:opacity-90 transition-all disabled:opacity-50"
+      >
+        {status === 'loading' ? 'Joining...' : 'Join Waitlist'}
+      </button>
+      {status === 'error' && <p className="text-red-500 text-sm">{message}</p>}
+    </form>
+  )
+}
+```
+
+## Mock Data
+
+Centralize all fake data in `src/data/mock.ts`:
+
+```ts
+export const features = [
+  { icon: '🎯', title: 'Feature One', description: 'Short benefit-driven description.' },
+  { icon: '⚡', title: 'Feature Two', description: 'Short benefit-driven description.' },
+  { icon: '🔒', title: 'Feature Three', description: 'Short benefit-driven description.' },
+]
+
+export const testimonials = [
+  { quote: 'Realistic testimonial here.', name: 'Jane Smith', role: 'CTO, TechCo' },
+  // ...
+]
+
+export const pricingPlans = [
+  { name: 'Free', price: '$0', features: ['Feature A', 'Feature B'], cta: 'Get Started' },
+  { name: 'Pro', price: '$29/mo', features: ['Everything in Free', 'Feature C'], cta: 'Get Pro', popular: true },
+  { name: 'Enterprise', price: 'Custom', features: ['Everything in Pro', 'Priority support'], cta: 'Contact Us' },
+]
+
+// Dashboard mock data
+export const dashboardStats = [
+  { label: 'Total Users', value: '2,847', change: '+12%' },
+  // ...
+]
+
+export const recentActivity = [
+  { user: 'Jane Smith', action: 'created a new project', time: '2 hours ago' },
+  // ...
+]
+```
+
+## Component Patterns
+
+- Use functional components with TypeScript.
+- Use `useState` for local state, no state management library needed.
+- Navigation: `<Link to="/dashboard">` from react-router-dom.
+- Keep components focused — one file per component.
+- Props typed with interfaces or inline.
+
+## Dev Server
+
+```bash
+npm run dev
+# Runs on http://localhost:5173
+```

package/skills/sk:review/SKILL.md

@@ -58,16 +58,23 @@ If `tasks/security-findings.md` exists, read the most recent audit. Use any unre
 Critical/High findings as additional targeted checks — verify the current diff doesn't
 reintroduce previously flagged vulnerabilities.
 
-### 2. Collect All Changes
+### 2. Collect Changes + Blast Radius
+
+Instead of reading the entire codebase or only the diff, build a **blast radius** — the minimal set of files that could be affected by the changes. This produces focused, high-signal context that leads to better review quality.
+
+**2a — Baseline git info:**
 
 ```bash
 # Determine base branch
-git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main"
+BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main")
+
+# Changed files and stats
+CHANGED_FILES=$(git diff $BASE..HEAD --name-only)
+git diff $BASE..HEAD --stat
+git log $BASE..HEAD --oneline
 
-# All changes on this branch
-git diff main..HEAD
-git diff main..HEAD --stat
-git log main..HEAD --oneline
+# Full diff for reference
+git diff $BASE..HEAD
 
 # Check for uncommitted changes
 git status --short
@@ -76,12 +83,103 @@ git status --short
 If there are uncommitted changes, warn:
 > **Warning:** You have uncommitted changes. These will NOT be included in the review. Commit or stash them first.
 
-Read the full content of every changed file (not just the diff hunks) to understand context around the changes.
+**2b — Extract changed symbols:**
+
+Use **git hunk headers** as the primary extraction method. Git already parses the enclosing function/class name into every `@@` header — this is more reliable than regex or AST tools:
+
+```bash
+# Phase 1: Enclosing scope names from hunk headers (free from git, no parsing needed)
+git diff $BASE..HEAD -U0 | grep '^@@' | sed 's/.*@@\s*//' | \
+  grep -oE '[A-Za-z_][A-Za-z0-9_]*\s*\(' | sed 's/\s*(//' | sort -u
+```
+
+Then supplement with **new/modified definitions** from added lines using language-specific patterns. Only match definition keywords — not `const`, `export`, `type`, or other high-noise terms:
+
+```bash
+# Phase 2: Definitions from added lines (supplement, not replace)
+# JS/TS:   function foo(, class Foo, interface Foo
+# Python:  def foo(, class Foo
+# Go:      func foo(, func (r *T) foo(
+# PHP:     function foo(, class Foo
+# Rust:    fn foo(, struct Foo, impl Foo, trait Foo
+git diff $BASE..HEAD | grep '^+' | grep -v '^+++' | \
+  grep -oE '(function|class|interface|def|fn|func|struct|trait|impl)\s+[A-Za-z_][A-Za-z0-9_]+' | \
+  awk '{print $2}' | sort -u
+```
+
+Combine both phases. Filter out symbols shorter than 3 characters (too generic for blast-radius search).
+
+Classify each symbol:
+- **Modified/removed** — existed before the branch, changed or deleted now. These can break callers. **Run blast radius on these.**
+- **New** — added in this branch, no prior callers exist. **Skip blast radius** (nothing to break).
+
+To classify, check if the symbol appears in the base branch:
+```bash
+# If symbol exists in base branch files, it's modified/removed → needs blast radius
+git show $BASE:$FILE 2>/dev/null | grep -q "\b$SYMBOL\b"
+```
+
+**2c — Find blast radius (modified/removed symbols only):**
+
+For each modified/removed symbol, use **import-chain narrowing** to find dependents with minimal false positives:
+
+```bash
+# Step 1: Find files that import the module containing the changed symbol
+CHANGED_MODULE_PATHS=$(echo "$CHANGED_FILES" | sed 's/\.[^.]*$//' | sed 's/\/index$//')
+for module_path in $CHANGED_MODULE_PATHS; do
+  rg -l "(import|require|from|use)\s.*$(basename $module_path)" \
+    --glob '!node_modules/**' --glob '!vendor/**' --glob '!dist/**' \
+    --glob '!build/**' --glob '!*.lock' --glob '!*.md' \
+    2>/dev/null
+done | sort -u > /tmp/importers.txt
+
+# Step 2: Within importers, find which ones reference the specific changed symbols
+for symbol in $MODIFIED_SYMBOLS; do
+  rg -wl "$symbol" $(cat /tmp/importers.txt) 2>/dev/null
+done | sort -u > /tmp/dependents.txt
+
+# Remove files already in the changed set
+comm -23 /tmp/dependents.txt <(echo "$CHANGED_FILES" | sort) > /tmp/blast_radius.txt
+```
+
+**Noise guard:** If a symbol produces >100 matches, it's too generic for grep-based analysis. Note it in the review as "unable to determine blast radius for `symbol` — manual verification recommended."
+
+Log the blast radius before reading:
+```
+Blast Radius Summary
+──────────────────────────────────
+Changed files:           X
+Blast-radius dependents: Y  (files importing changed symbols)
+Total review scope:      X+Y files
+Symbols analyzed:        N modified, M new (skipped)
+
+Symbol → Dependents:
+  processOrder  → src/checkout/cart.ts, src/api/orders.ts
+  validateInput → src/middleware/auth.ts
+──────────────────────────────────
+```
+
+**2d — Read context (focused, not exhaustive):**
+
+Read in this priority order:
+1. **Changed files in full** — not just the diff. The full file provides surrounding context (imports, related functions, class-level state) needed to judge whether the change is correct. For files >500 lines, read the changed function + 30 lines of surrounding context instead.
+2. **The diff** — for precise change tracking (already collected above).
+3. **Blast-radius dependent files** — read only the call sites that reference changed symbols. Use `rg -B5 -A10 "\bsymbol\b" dependent_file` to get the call site with surrounding context, not the entire file.
+4. **Test files** for changed symbols — verify existing tests still cover the changed behavior.
+
+Do **not** read unchanged files outside the blast radius.
+
+Carry the blast-radius mapping (symbol → dependents) forward into Steps 3-9. When analyzing a changed function, always cross-reference its dependents.
 
 ### 3. Analyze — Correctness & Bugs
 
 The most important dimension. A bug that ships is worse than ugly code that works.
 
+**Blast-radius check (mandatory):** For every modified/removed symbol, verify its dependents (from Step 2c) are still compatible:
+- Do callers pass arguments the changed function still accepts?
+- Do callers depend on return values whose shape/type changed?
+- Do callers rely on side effects the changed code no longer produces?
+
 **Logic errors:**
 - Wrong operator (`&&` vs `||`, `==` vs `===`, `<` vs `<=`)
 - Inverted conditions, missing negation
@@ -114,7 +212,11 @@ The most important dimension. A bug that ships is worse than ugly code that work
 
 ### 4. Analyze — Security
 
-Load `references/security-checklist.md` and apply its grep patterns systematically. Check for:
+Load `references/security-checklist.md` and apply its grep patterns against the **diff and blast-radius files** (not the entire codebase). Only flag patterns **newly introduced** in the diff — pre-existing issues are out of scope unless they interact with the changed code.
+
+**Blast-radius check:** If a validation or auth function was modified, check all its callers (from Step 2c) — a weakened check affects every endpoint that depends on it.
+
+Check for:
 
 **Injection (OWASP A03):**
 - SQL, NoSQL, OS command, LDAP, template injection
@@ -184,6 +286,8 @@ Think about what happens at 10x, 100x current scale. Performance bugs are often
 
 Production code must handle failure gracefully. The question isn't "does it work?" but "what happens when things go wrong?"
 
+**Blast-radius check:** If error handling changed (e.g., function now throws instead of returning null, or error type changed), check all callers from Step 2c — they may not have matching try/catch or null checks.
+
 **Error handling quality:**
 - Swallowed errors (empty catch blocks, `.catch(() => {})`)
 - Generic catch blocks that hide the actual error type
@@ -217,8 +321,9 @@ Think about the next engineer who reads this code. Is the intent clear? Does the
 - Components doing too many things (should be split)
 - Side effects in pure functions or constructors
 
-**API design (if endpoints changed):**
+**API design (if endpoints or function signatures changed):**
 - Breaking changes to existing API contracts without versioning
+- **Blast-radius check:** If a function signature changed, the blast radius from Step 2c is the definitive answer to whether it's a breaking change — every dependent file that calls the old signature will break
 - Inconsistent response format across endpoints
 - Missing or inconsistent HTTP status codes
 - Unclear or missing error response schema
@@ -294,7 +399,8 @@ Format findings with severity levels and review dimensions:
 
 **Changes:** X files changed, +Y/-Z lines
 **Commits:** N commits
-**Review dimensions:** Correctness, Security, Performance, Reliability, Design, Best Practices, Testing
+**Blast radius:** X changed files + Y dependents = Z total review scope
+**Review dimensions:** Correctness, Security, Performance, Reliability, Design, Best Practices, Testing, Blast Radius
 
 ### Critical (must fix before merge)
 - **[Correctness]** [FILE:LINE] Description of critical issue
@@ -323,7 +429,8 @@ Format findings with severity levels and review dimensions:
 
 **Rules:**
 - Maximum 20 items total (prioritize by severity, then by category)
-- Every item must tag its review dimension: `[Correctness]`, `[Security]`, `[Performance]`, `[Reliability]`, `[Design]`, `[Best Practices]`, `[Testing]`
+- Every item must tag its review dimension: `[Correctness]`, `[Security]`, `[Performance]`, `[Reliability]`, `[Design]`, `[Best Practices]`, `[Testing]`, `[Blast Radius]`
+- Use `[Blast Radius]` for issues found in dependent files — callers broken by changed signatures, importers affected by removed exports, tests that no longer cover the changed behavior
 - Every item must reference a specific file and line
 - Every item must explain **why** it matters — the impact, not just the symptom
 - Include a brief "What Looks Good" section (2-3 items) — acknowledge strong patterns so they're reinforced. This isn't cheerleading — it's calibrating signal.

package/skills/sk:write-tests/SKILL.md

@@ -145,16 +145,54 @@ If a frontend stack was detected, generate FE test files:
 
 Skip this step if no FE stack was detected.
 
-### 8b. Playwright-Specific (conditional)
+### 8b. Write E2E Spec Files (conditional)
+
+**Only if `playwright.config.ts` or `playwright.config.js` is detected in the project root:**
+
+Write `e2e/<feature>.spec.ts` files covering the acceptance criteria from `tasks/todo.md`. Follow these rules:
+
+- Use `test.describe` / `test` blocks — not `describe`/`it`
+- Use role-based locators: `getByRole`, `getByLabel`, `getByText`, `getByPlaceholder` — never CSS selectors
+- Use `test.beforeEach` for shared setup (auth, navigation)
+- Use `test.skip(!email, 'ENV_VAR not set — skipping')` guards for credential-dependent tests
+- Auth credentials from env vars via `e2e/helpers/auth.ts` — never hardcode credentials
+- Soft assertions (`expect.soft`) for non-critical checks; hard `expect` for gate conditions
+
+E2E spec example structure:
+```ts
+import { test, expect } from '@playwright/test'
+import { signIn, TEST_USERS } from './helpers/auth'
+
+test.describe('[Feature] — [scenario]', () => {
+  test.beforeEach(async ({ page }) => {
+    const { email, password } = TEST_USERS.regular
+    test.skip(!email, 'E2E_USER_EMAIL not set — skipping')
+    await signIn(page, email, password)
+  })
+
+  test('[behavior description]', async ({ page }) => {
+    await page.goto('/dashboard/feature')
+    await expect(page.getByRole('heading', { name: /title/i })).toBeVisible()
+  })
+})
+```
+
+Create `e2e/helpers/auth.ts` if it doesn't exist (see `/sk:e2e` Playwright Setup Reference).
+
+**Run the E2E spec to confirm tests fail or skip** (they should fail until implementation, or skip if env vars aren't set — both are acceptable for the RED phase):
+```bash
+npx playwright test e2e/<feature>.spec.ts --reporter=list
+```
+
+### 8c. Playwright MCP Inspection (optional)
 
-**Only if `@playwright/sk:test` is detected:**
+**Only if the Playwright MCP plugin is active in the session AND live selectors are needed:**
 
 Use the Playwright MCP plugin to inspect live page state for more accurate selectors:
 
 1. Navigate to target URL
 2. Capture accessibility snapshot for role-based selectors
 3. Screenshot for visual reference
-4. Optionally run inline assertions for complex interactions
 
 ### 9. Verify Tests Fail (Red Phase)
 
@@ -170,6 +208,7 @@ Output:
 ```
 BE tests written: X tests in Y files ([framework])
 FE tests written: X tests in Y files ([framework])  ← omit if no FE stack
+E2E specs written: X tests in Y files (Playwright)  ← omit if no playwright.config.ts
 Existing tests updated: X files
 Status: RED (tests fail as expected — ready for implementation)
 ```