@kennethsolomon/shipkit 3.1.0 → 3.3.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:perf/SKILL.md

@@ -120,24 +120,25 @@ Write findings to `tasks/perf-findings.md`:
 
 ## Critical
 
-- **[FILE:LINE]** Description
+- [ ] **[FILE:LINE]** Description
   **Impact:** What happens at scale
   **Recommendation:** How to fix
+- [x] **[FILE:LINE]** Description *(resolved)*
 
 ## High
 
-- **[FILE:LINE]** Description
+- [ ] **[FILE:LINE]** Description
   **Impact:** ...
   **Recommendation:** ...
 
 ## Medium
 
-- **[FILE:LINE]** Description
+- [ ] **[FILE:LINE]** Description
   **Recommendation:** ...
 
 ## Low
 
-- **[FILE:LINE]** Description
+- [ ] **[FILE:LINE]** Description
   **Recommendation:** ...
 
 ## Passed Checks
@@ -146,13 +147,13 @@ Write findings to `tasks/perf-findings.md`:
 
 ## Summary
 
-| Severity | Count |
-|----------|-------|
-| Critical | N |
-| High     | N |
-| Medium   | N |
-| Low      | N |
-| **Total** | **N** |
+| Severity | Open | Resolved this run |
+|----------|------|-------------------|
+| Critical | N    | N                 |
+| High     | N    | N                 |
+| Medium   | N    | N                 |
+| Low      | N    | N                 |
+| **Total** | **N** | **N**            |
 ```
 
 **Never overwrite** `tasks/perf-findings.md` — append new audits with a date header.

package/skills/sk:seo-audit/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: sk:seo-audit
+description: "SEO audit for web projects. Dual-mode: scans source templates + optionally fetches from running dev server. Ask-before-fix for mechanical issues. Outputs checklist findings to tasks/seo-findings.md."
+license: Complete terms in LICENSE.txt
+---
+
+# /sk:seo-audit
+
+## Purpose
+
+Standalone optional command — audits any web project for SEO issues regardless of framework (Laravel, Next.js, Nuxt, plain HTML, etc.). Run at any point after implementation is complete. NOT a numbered workflow step — invoke it independently like `/sk:debug`.
+
+Two modes:
+- **Source mode** (always runs): scans template files directly for SEO signals
+- **Server mode** (optional): fetches from a running dev server to validate rendered output
+
+Run when: before shipping a client site, after adding new pages, or any time you want to check SEO health.
+
+## Hard Rules
+
+- **Never auto-apply fixes without explicit user confirmation.**
+- **Every finding must cite a specific `file:line`.**
+- **Every finding is a checkbox:** `- [ ]` (open) or `- [x]` (auto-fixed this run)
+- **Append to `tasks/seo-findings.md`** — never overwrite (use date header per run)
+- **Degrade gracefully** if no server is running — skip Phase 2, note it in report
+- **Structured data validation requires external tools** (Google Rich Results Test) — flag it, don't skip silently
+
+## Before You Start
+
+1. Read `tasks/findings.md` if it exists — look for site context, target audience, business type (helps tailor content strategy recommendations)
+2. Read `tasks/lessons.md` if it exists — apply any SEO-related lessons
+3. Check if `tasks/seo-findings.md` exists — if yes, read the last dated section to identify previously flagged items (used to populate "Passed Checks" in the new report)
+
+## Mode Detection
+
+### Source Mode — Always Active
+
+Scan the project for template files:
+
+| Extension | Framework |
+|-----------|-----------|
+| `.blade.php` | Laravel |
+| `.jsx`, `.tsx` | React / Next.js |
+| `.vue` | Vue / Nuxt |
+| `.html` | Plain HTML / static |
+| `.ejs` | Express / Node |
+| `.njk` | Nunjucks |
+| `.twig` | Twig / Symfony |
+| `.erb` | Ruby on Rails |
+| `.astro` | Astro |
+
+Print: `"Source mode: found N template files ([extensions detected])"`
+
+### Server Mode — Optional
+
+Probe ports in parallel (background curl processes) to avoid 14-second worst-case serial timeout:
+- Ports: 3000, 5173, 8000, 8080, 4321, 4000, 8888
+- Command: `curl -s -I --max-time 2 http://localhost:PORT` (HEAD request to capture both status code and headers)
+- Use the first port that returns HTTP 200 **and** has a `Content-Type: text/html` response header
+
+If a port returns 200 but no `Content-Type: text/html` header, skip it — it is likely a non-HTTP service (e.g., a database, gRPC server) and not a web app. Try the next port.
+
+If any port qualifies: `"Server mode: detected running dev server at http://localhost:PORT"`
+
+If none respond or qualify: `"Server mode: no dev server detected — skipping Phase 2. Start your dev server and re-run for full audit."`
+
+> Note: confirm the detected URL looks correct before trusting Phase 2 results.
+
+## Phase 1 — Source Audit
+
+### Technical SEO
+
+- `robots.txt` — exists in project root or `public/`; does NOT contain `Disallow: /` blocking all crawlers
+- `sitemap.xml` — exists in project root or `public/`; referenced in `robots.txt` via `Sitemap:` directive
+- `<html lang="">` — present on all layout/root templates (not empty)
+- Canonical tags — `<link rel="canonical">` present on key page templates
+- No accidental `<meta name="robots" content="noindex">` on public-facing pages
+- No hardcoded `http://` asset URLs in templates (mixed content risk)
+
+### On-Page SEO
+
+- `<title>` — present in `<head>`, unique across pages, 50–60 characters
+- `<meta name="description">` — present in `<head>`, unique across pages, 150–160 characters
+- Exactly one `<h1>` per page template (not zero, not two+)
+- Heading hierarchy not skipped (no jumping from `<h2>` to `<h4>`)
+- All `<img>` tags have `alt` attribute (even if empty for decorative — but flag empty alt on non-decorative images)
+- Internal `<a>` link text is descriptive — flag anchors with text: "click here", "here", "read more", "link", "this"
+- Image filenames are descriptive — flag patterns like `img001`, `IMG_`, `photo`, `image`, `DSC_`, `screenshot` with no context
+
+### Content Signals
+
+- Open Graph tags: `og:title`, `og:description`, `og:url`, `og:image` all present in layout
+- Twitter Card tags: `twitter:card` present
+- JSON-LD structured data block: look for `<script type="application/ld+json">` — note presence/absence; do NOT validate schema (requires external tool)
+- Page `<html lang="">` matches expected locale
+
+## Phase 2 — Server Audit (Optional)
+
+If server detected:
+
+1. Fetch `/` and discover up to 4 additional pages (from `<a>` href values in homepage, or from sitemap.xml)
+2. For each page fetched, extract and compare:
+   - Rendered `<title>` vs source template value
+   - Rendered `<meta name="description">` vs source template value
+   - Rendered `<h1>` vs source template value
+   - Rendered OG tags vs source template
+3. Flag mismatches: `"/about — Source template declares <title>About Us</title> but rendered output shows <title>My App</title> — framework may be overriding"`
+4. Check HTTP status codes — flag any key page returning non-200
+5. Check for redirect chains on common pages (/ → /home → /index is a chain)
+
+> Note in report: "Structured data detected but NOT validated — use Google Rich Results Test (https://search.google.com/test/rich-results) to verify schema markup."
+
+## Phase 3 — Ask Before Fix
+
+After completing Phase 1 (and Phase 2 if run):
+
+1. Collect all auto-fixable findings (see Mechanical Fixes Reference below)
+2. Display numbered list:
+
+```
+Found N auto-fixable issues:
+1. Missing <title> in resources/views/layouts/app.blade.php
+2. Missing alt attribute on <img> in resources/views/home.blade.php:42
+3. Missing robots.txt
+... (all N items)
+
+Apply mechanical fixes? [y/N]
+```
+
+3. Wait for user response
+4. On `y`: apply each fix in order, log `"Fixed: [description] in [file:line]"`, mark as `- [x]` in report. On individual fix failure: log the error, mark that item `- [ ]`, and continue with remaining fixes.
+5. On `n`: mark all as `- [ ]` in report with Fix instructions
+
+## Mechanical Fixes Reference
+
+What this skill CAN auto-apply when user confirms:
+
+| Issue | Fix Applied |
+|-------|------------|
+| Missing `<title>` in `<head>` | Add `<title>TODO: Add page title (50-60 chars)</title>` |
+| Missing `<meta name="description">` | Add `<meta name="description" content="TODO: Add description (150-160 chars)">` |
+| `<img>` missing `alt` attribute | Add `alt="TODO: Describe this image for screen readers"` |
+| Missing `<link rel="canonical">` | Add `<link rel="canonical" href="TODO: Add canonical URL">` |
+| Missing `robots.txt` | Create `robots.txt`: `User-agent: *\nAllow: /\nSitemap: /sitemap.xml` |
+| Missing `sitemap.xml` | Create `sitemap.xml` scaffold with homepage entry |
+| Multiple `<h1>` on same page | Demote 2nd, 3rd... `<h1>` to `<h2>` |
+| Missing OG tags | Add `og:title`, `og:description`, `og:url` block (with TODO placeholders) |
+| Missing `<html lang="">` | Add `lang="en"` — **note in output: verify correct language code** |
+
+Things this skill CANNOT auto-apply (report only):
+- Content quality improvements
+- Keyword targeting
+- Title/description CONTENT (only adds TODOs)
+- Schema markup content (only flags missing)
+- Backlink strategy
+- `<meta name="robots" content="noindex">` removal — only the developer can confirm whether a page is intentionally noindexed
+
+## Generate Report
+
+Write to `tasks/seo-findings.md` — append with date header, never overwrite.
+
+```markdown
+# SEO Audit — YYYY-MM-DD
+
+**Mode:** Source only | Source + Server (`http://localhost:PORT`)
+**Templates scanned:** N files ([detected extensions])
+**Pages fetched:** N | none — server not detected
+
+---
+
+## Critical
+
+- [x] `resources/views/layouts/app.blade.php` — Missing `<title>` tag *(auto-fixed — add real title)*
+- [ ] `resources/views/about.blade.php:1` — Missing `<meta name="description">`
+  **Impact:** Google may auto-generate a description from page content, often poorly.
+  **Fix:** Add `<meta name="description" content="150-160 char description">` in `<head>`
+
+## High
+
+- [ ] `public/robots.txt` — File missing
+  **Impact:** Search engines have no crawl guidance — may index unwanted pages.
+  **Fix:** Create `robots.txt` with `User-agent: *`, `Allow: /`, `Sitemap:` directive
+
+## Medium
+
+- [ ] `resources/views/home.blade.php:42` — `<img src="hero.jpg">` missing alt attribute
+  **Impact:** Accessibility violation + missed keyword opportunity.
+  **Fix:** Add descriptive `alt="..."` text
+
+## Low
+
+- [ ] Image filename `IMG_4521.jpg` — not descriptive
+  **Impact:** Minor missed keyword signal.
+  **Fix:** Rename to describe the image content
+
+## Content Strategy — Manual Action
+
+- [ ] No JSON-LD structured data detected — consider adding schema markup (Article / Product / LocalBusiness / FAQPage) based on your content type. Validate at: https://search.google.com/test/rich-results
+- [ ] `og:image` missing — social shares will have no preview image. Add a default OG image in your layout.
+- [ ] Submit `sitemap.xml` to Google Search Console for faster indexing
+- [ ] Title tags are present but content is generic ("TODO") — research target keywords for each page
+
+## Passed Checks
+
+- `robots.txt` exists and allows crawling *(was: missing — fixed in 2026-03-10 audit)*
+- All `<img>` tags have alt attributes
+- Single `<h1>` per page
+
+(or "First run — no prior baseline to compare against")
+
+## Applied Fixes
+
+- Fixed: Added `<title>` placeholder to `resources/views/layouts/app.blade.php`
+- Fixed: Created `public/robots.txt`
+
+(or "No fixes applied this run")
+
+---
+
+## Summary
+
+| Severity | Open | Fixed this run |
+|----------|------|----------------|
+| Critical | 1 | 1 |
+| High | 1 | 0 |
+| Medium | 3 | 0 |
+| Low | 2 | 0 |
+| Content Strategy | 4 | — |
+| **Total** | **11** | **1** |
+```
+
+**Never overwrite** `tasks/seo-findings.md` — append new audits with a date header.
+
+## When Done
+
+If Critical or High items are open:
+> "SEO audit complete. **N critical/high issues** need attention before this site will rank well. Findings and checklist in `tasks/seo-findings.md`."
+
+If only Medium/Low/Content Strategy open:
+> "Technical SEO is solid. **N medium/low polish items** and **N content strategy items** noted in `tasks/seo-findings.md`. Check off items as you address them."
+
+If all clean:
+> "SEO audit passed — no issues found. `tasks/seo-findings.md` updated with clean baseline."
+
+If fixes were declined (`n`):
+> "SEO audit complete. **N auto-fixable issues** left open (fixes declined). Checklist in `tasks/seo-findings.md` — check off items as you manually address them."
+
+---
+
+## Fix & Retest Protocol
+
+When applying an SEO fix, classify it before committing:
+
+**a. Template/config change** (adding a meta tag, fixing alt text, scaffolding robots.txt, adding lang attribute, creating sitemap.xml) → commit and re-run `/sk:seo-audit`. No test update needed.
+
+**b. Logic change** (changing how a framework generates meta tags, modifying a layout component's data-fetching or rendering logic, changing routing that affects canonical URLs) → trigger protocol:
+1. Update or add failing unit tests for the new behavior
+2. Re-run `/sk:test` — must pass at 100% coverage
+3. Commit (tests + fix together in one commit)
+4. Re-run `/sk:seo-audit` to verify the fix resolved the finding
+
+**Common logic-change SEO fixes:**
+- Changing a Next.js `generateMetadata()` function → update tests asserting metadata output
+- Modifying a Laravel controller that sets page title → update feature tests
+- Changing a Vue component that injects `<head>` tags → update component tests
+
+---
+
+## Model Routing
+
+Read `.shipkit/config.json` from the project root if it exists.
+
+- If `model_overrides["sk:seo-audit"]` is set, use that model — it takes precedence.
+- Otherwise use the `profile` field. Default: `balanced`.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | sonnet |
+| `quality` | sonnet |
+| `balanced` | sonnet |
+| `budget` | haiku |
+
+> `opus` = inherit (uses the current session model). When spawning sub-agents via the Agent tool, pass `model: "<resolved-model>"`.

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)
 ```