@friedbotstudio/create-baseline 0.1.0 → 0.2.1

package/obj/template/.claude/skills/optimize-seo/SKILL.md

@@ -0,0 +1,313 @@
+---
+name: optimize-seo
+description: "SEO + performance optimization orchestrator for the Friedbot Studio website. Drives a repeatable measure → diagnose → scope → fix → verify → commit loop. Use when performance scores drop, a PageSpeed audit surfaces issues, or before major traffic events. Trigger on: 'optimize the site', 'run a perf audit', 'fix pagespeed issues', 'improve core web vitals', 'check site performance'."
+metadata:
+  version: 1.0.0
+  disable-model-invocation: true
+---
+
+# Optimize SEO — Performance & Accessibility Workflow
+
+You are the SEO and performance optimization orchestrator. Your job is to take the site from a baseline measurement through diagnosis, targeted fixes, and verification — with repeatability and no guesswork.
+
+This is the **parallel orchestrator to `/orchestrate`**. Where `/orchestrate` delivers new features (requirements → design → copy → build), `/optimize-seo` improves existing features (measure → diagnose → fix → verify).
+
+## Workflow Pipeline
+
+```
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│  1. MEASURE  │───▶│  2. DIAGNOSE │───▶│  3. SCOPE    │
+│  PageSpeed    │    │  Root causes │    │  Fix plan    │
+└─────────────┘    └─────────────┘    └─────────────┘
+                                             │
+┌─────────────┐    ┌─────────────┐    ┌──────▼──────┐
+│  6. COMMIT   │◀───│  5. VERIFY   │◀───│  4. FIX      │
+│  Ship it      │    │  Re-measure   │    │  Apply fixes │
+└─────────────┘    └─────────────┘    └─────────────┘
+```
+
+**Never skip phases.** Never fix before diagnosing. Never ship without re-measuring.
+
+---
+
+## Task-Based Execution (mandatory)
+
+At the start of every optimization cycle, create ALL tasks upfront using TaskCreate. Execute them strictly in order. Do not start a task until the previous one is marked complete.
+
+### Task List Template
+
+Create these tasks when starting a new cycle (replace `[scope]` with e.g. `home-page`, `site-wide`):
+
+```
+ 1. [Measure] Create progress tracker at docs/progress/optimize-[scope].md
+ 2. [Measure] Run pagespeed.mjs for mobile + desktop, capture baseline scores
+ 3. [Measure] Run Playwright MCP to capture baseline screenshots (desktop 1280, tablet 768, mobile 375)
+ 4. [Diagnose] Invoke /pagespeed-insights to interpret the report and identify root causes
+ 5. [Diagnose] Invoke /nextjs-performance for framework-specific optimizations
+ 6. [Diagnose] Invoke /web-design-guidelines for accessibility audits
+ 7. [Diagnose] Cross-reference diagnosis against the codebase (Grep, Read) to confirm root causes
+ 8. [Scope] Draft fix plan in the progress tracker — batched by impact, with acceptance criteria
+ 9. [Scope] Get user approval on scope and batch order
+10. [Fix] Execute fix batches in order — each batch pauses at a visual verification gate
+11. [Verify] Re-run pagespeed.mjs for mobile + desktop, diff against baseline
+12. [Verify] Re-run Playwright screenshots, compare against baseline — no visual regressions
+13. [Verify] Invoke /simplify-code on all changed files
+14. [Verify] Present before/after report to user, confirm acceptance criteria met
+15. [Commit] Invoke /plan-commits
+16. [Commit] Finalize progress tracker — mark all phases Done with completion dates
+17. [Commit] Execute commits — REQUIRES USER APPROVAL (destructive action)
+```
+
+### Execution Rules
+
+- **Mark each task complete immediately** after finishing it. Do not batch completions.
+- **Do not skip tasks.** If a task is not applicable (e.g., no visual changes = skip screenshot diff), mark it complete with a note explaining why.
+- **Task 1 creates the progress tracker**: Write `docs/progress/optimize-[scope].md` with all phases set to Pending. Update Measure to In Progress immediately.
+- **Task 10 (Fix) is a parent task**: During scope (Task 8), break the fix plan into batches. For each batch, add child tasks dynamically via TaskCreate. Each batch must visually verify via Playwright before moving on.
+- **Task 9 is a gate**: Present the scope document to the user and pause. Do not proceed until user approves the fix plan.
+- **Task 14 is a gate**: Present the before/after report. Do not commit unless targets are met.
+- **Task 17 MUST get explicit user approval** via AskUserQuestion before executing. This is destructive (git commits).
+
+---
+
+## Phase Details
+
+### Phase 1: MEASURE
+**Tasks**: 1-3
+
+**Goal**: Establish a factual baseline. No guessing what's slow — measure it.
+
+**Actions**:
+
+1. Create the progress tracker file at `docs/progress/optimize-[scope].md` using the template in the Progress Tracking section. Set Measure to In Progress.
+2. Run `node .claude/skills/optimize-seo/scripts/pagespeed.mjs --url=https://friedbotstudio.com --output=/tmp/psi-baseline.json`. Capture scores and failing audits for both mobile and desktop strategies.
+3. Use **Playwright MCP** to capture screenshots at desktop (1280px), tablet (768px), and mobile (375px) widths. Save to `/tmp/screenshots-baseline/`.
+
+**Required inputs**:
+- `G_PAGESPEED_KEY` in `.env.local` (API key for PageSpeed Insights)
+- Deployed live URL (default: `https://friedbotstudio.com`)
+
+**Output**: Baseline scores + screenshots recorded in the progress tracker
+
+---
+
+### Phase 2: DIAGNOSE
+**Tasks**: 4-7
+
+**Goal**: Understand the root cause of every failing audit. Not the symptom — the cause.
+
+**Actions**:
+
+1. **(Task 4)** Invoke `/pagespeed-insights` — let the skill interpret the Lighthouse report, surface the most impactful issues, and explain what each audit measures.
+2. **(Task 5)** Invoke `/nextjs-performance` — for any Next.js-specific findings (LCP, image optimization, RSC boundaries, bundle splitting, caching). This skill knows framework-level fixes.
+3. **(Task 6)** Invoke `/web-design-guidelines` — for accessibility-related failures (contrast, heading hierarchy, focus states, ARIA).
+4. **(Task 7)** Ground every diagnosis in code. Use Grep and Read to trace each failing audit to a specific file or pattern. Document file paths + line numbers in the progress tracker. If you cannot point to code, you do not have a root cause — keep investigating.
+
+**Sub-skills invoked (mandatory):**
+
+| Skill                    | Role                                               |
+| ------------------------ | -------------------------------------------------- |
+| `/pagespeed-insights`    | Interpret Lighthouse audits, prioritize fixes      |
+| `/nextjs-performance`    | Next.js / React / Tailwind perf patterns           |
+| `/web-design-guidelines` | Accessibility and UX best practices                |
+
+**Output**: Root-cause map — for each failing audit, a concrete file/pattern reference
+
+---
+
+### Phase 3: SCOPE
+**Tasks**: 8-9
+
+**Goal**: A written, approved fix plan before any code changes.
+
+**Actions**:
+
+1. **(Task 8)** Draft the fix plan in the progress tracker. Structure:
+   - Baseline scores
+   - Target scores (explicit numbers)
+   - Findings and root causes (with file references from Phase 2)
+   - Fix plan, batched by impact (biggest wins first)
+   - Acceptance criteria
+   - Risks and mitigations
+   - Out of scope
+2. **(Task 9)** Present the scope document to the user. Pause for approval. Do not proceed to fixes until user confirms batch order and acceptance criteria.
+
+**Gate (Task 9)**: User approves the scope document before any code changes.
+
+---
+
+### Phase 4: FIX
+**Tasks**: 10 (with dynamic child tasks)
+
+**Goal**: Execute fixes in batches. Each batch is independently verifiable.
+
+**Actions**:
+
+1. For each batch in the approved scope:
+   - Create child tasks via TaskCreate for the specific fixes in the batch
+   - Execute the fixes in order
+   - Use **Context7 MCP** for any library API lookups (do not rely on memory)
+   - Use `/code-structure` for all component changes (enforced by PostToolUse hook)
+   - After the batch, take a Playwright screenshot of affected pages at desktop + mobile
+   - Compare against baseline screenshots — no visual regressions allowed
+2. Mark each batch complete before starting the next.
+
+**Sub-skills invoked (mandatory):**
+
+| Skill                       | Role                                    |
+| --------------------------- | --------------------------------------- |
+| `/nextjs-performance`       | Applied during every fix for guidance   |
+| `/code-structure`           | Enforced on every TSX/JSX edit (hook)   |
+| `/tailwind-design-system`   | For any design token changes            |
+
+**Tools invoked (mandatory):**
+
+| Tool               | Role                              |
+| ------------------ | --------------------------------- |
+| **Context7 MCP**   | Live library documentation lookup |
+| **Playwright MCP** | Visual verification per batch     |
+
+**Output**: Implemented fixes, visual parity confirmed per batch
+
+---
+
+### Phase 5: VERIFY
+**Tasks**: 11-14
+
+**Goal**: Prove the fixes worked. No wishful thinking — measure.
+
+**Actions**:
+
+1. **(Task 11)** Re-run `pagespeed.mjs` with `--baseline=/tmp/psi-baseline.json` to get a diff. Save to `/tmp/psi-after.json`.
+2. **(Task 12)** Re-run Playwright screenshots at 3 widths. Compare against `/tmp/screenshots-baseline/`. Flag any unexpected visual changes.
+3. **(Task 13)** Invoke `/simplify-code` on all changed files. Fix any High/Medium confidence issues before committing.
+4. **(Task 14)** Present a before/after report:
+   - Scores table: baseline vs after, per category, per strategy
+   - Specific audits that improved (and by how much)
+   - Any audits that regressed (must be zero)
+   - Visual verification: pass/fail
+   - Code quality: pass/fail
+   - Acceptance criteria met: yes/no
+5. If acceptance criteria are NOT met, loop back to Phase 4 (Fix) with a new batch. Do not commit under-delivered work.
+
+**Sub-skills invoked (mandatory):**
+
+| Skill             | Role                        |
+| ----------------- | --------------------------- |
+| `/simplify-code`  | Code quality + refactoring  |
+
+**Gate (Task 14)**: Acceptance criteria must be met before commit.
+
+---
+
+### Phase 6: COMMIT
+**Tasks**: 15-17
+
+**Goal**: Clean, conventional commits and a finalized progress tracker.
+
+**Actions**:
+
+1. **(Task 15)** Invoke `/plan-commits` — audit `.gitignore`, group changes into logical commits, run pre-commit checks.
+2. **(Task 16)** Finalize the progress tracker — mark all phases Done with completion dates, attach the before/after report.
+3. **(Task 17)** Execute commits. **REQUIRES EXPLICIT USER APPROVAL.** Use AskUserQuestion to confirm before staging any files.
+
+**Gate (Task 17)**: User explicitly approves before commits are executed.
+
+---
+
+## How to Use This Skill
+
+### Starting a new optimization cycle
+
+```
+User: /optimize-seo the home page
+```
+
+The skill will:
+
+1. Create the progress tracker at `docs/progress/optimize-home-page.md`
+2. Create all 17 tasks upfront
+3. Execute tasks in order, pausing at gates for approval
+
+### Resuming work
+
+```
+User: /optimize-seo — where are we on the home page optimization?
+```
+
+Check the task list for current status. Also check `docs/progress/optimize-[scope].md`.
+
+### Running a scheduled audit (no fixes)
+
+```
+User: /optimize-seo audit only
+```
+
+Run phases 1-2 only. Produce a baseline + diagnosis report. Stop before Scope.
+
+---
+
+## Progress Tracking
+
+For each optimization cycle, maintain a progress file at `docs/progress/optimize-[scope].md`:
+
+```markdown
+# Performance Optimization — [Scope] — Progress
+
+| Phase    | Status      | Date       | Notes            |
+| -------- | ----------- | ---------- | ---------------- |
+| Measure  | Done        | YYYY-MM-DD | Baseline captured |
+| Diagnose | In Progress | —          | —                |
+| Scope    | Pending     | —          | —                |
+| Fix      | Pending     | —          | —                |
+| Verify   | Pending     | —          | —                |
+| Commit   | Pending     | —          | —                |
+
+## Baseline Scores
+
+| Category       | Mobile | Desktop |
+| -------------- | ------ | ------- |
+| Performance    | XX     | XX      |
+| Accessibility  | XX     | XX      |
+| Best Practices | XX     | XX      |
+| SEO            | XX     | XX      |
+
+## Target Scores
+...
+
+## Findings & Root Causes
+...
+
+## Fix Plan
+...
+
+## Acceptance Criteria
+...
+
+## Before/After (populated at Verify phase)
+...
+```
+
+**Task 1 creates this file.** Task 16 finalizes it. Update phase statuses as you enter each phase.
+
+---
+
+## Rules
+
+1. **Never fix without diagnosing** — guesswork burns time and introduces risk
+2. **Every root cause must cite a file and/or line** — if you can't point to code, you don't have a root cause
+3. **Every batch must visually verify** — perf wins that break the layout are regressions, not improvements
+4. **Never commit without a before/after diff** — prove the fix worked
+5. **Pause at gates** — scope approval (Task 9), verify report (Task 14), commit approval (Task 17)
+6. **One scope at a time** — full site vs page-specific vs single-component. Don't mix.
+7. **Sub-skill invocation is mandatory** — `/pagespeed-insights`, `/nextjs-performance`, `/web-design-guidelines`, `/simplify-code`, `/plan-commits` all have required invocation points
+8. **Use Context7 MCP for library API lookups during Fix** — do not rely on training data for Next.js, React, Tailwind APIs
+9. **Progress tracker is mandatory** — Task 1 creates it, Task 16 finalizes it before commits are executed
+
+---
+
+## Integration with `/orchestrate`
+
+If a perf issue is discovered while delivering a new page, finish the `/orchestrate` cycle first. Run `/optimize-seo` as a separate follow-up cycle. Do not interleave.
+
+If the same fix will ship alongside a new feature, scope it inside the `/orchestrate` Build phase, document it in the new page's progress tracker, and skip `/optimize-seo` for that cycle.

package/obj/template/.claude/skills/optimize-seo/scripts/pagespeed.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * PageSpeed Insights audit helper.
+ *
+ * Wraps the PageSpeed Insights API for repeatable baseline + diff audits.
+ * Reads G_PAGESPEED_KEY from .env.local at the project root.
+ *
+ * Usage:
+ *   node pagespeed.mjs --url=https://friedbotstudio.com
+ *   node pagespeed.mjs --url=https://friedbotstudio.com --output=/tmp/psi.json
+ *   node pagespeed.mjs --url=https://friedbotstudio.com --baseline=/tmp/psi-baseline.json
+ *
+ * Flags:
+ *   --url       Target URL to audit (required)
+ *   --strategy  "mobile" | "desktop" | "both" (default: "both")
+ *   --output    Write raw results to this JSON file
+ *   --baseline  Compare against a previous --output file, print a diff table
+ *   --silent    Suppress human-readable output (still writes --output if set)
+ */
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ---------- argv parsing ----------
+
+const args = Object.fromEntries(
+  process.argv.slice(2).map((a) => {
+    const [k, v] = a.replace(/^--/, "").split("=");
+    return [k, v ?? true];
+  })
+);
+
+if (!args.url) {
+  console.error("Error: --url is required");
+  console.error("Usage: node pagespeed.mjs --url=https://example.com [--strategy=mobile|desktop|both] [--output=file] [--baseline=file]");
+  process.exit(1);
+}
+
+const strategy = args.strategy || "both";
+const strategies = strategy === "both" ? ["mobile", "desktop"] : [strategy];
+
+// ---------- env loading ----------
+
+function loadEnvKey() {
+  if (process.env.G_PAGESPEED_KEY) return process.env.G_PAGESPEED_KEY;
+  // Walk up looking for .env.local
+  let dir = __dirname;
+  for (let i = 0; i < 6; i++) {
+    const candidate = resolve(dir, ".env.local");
+    if (existsSync(candidate)) {
+      const content = readFileSync(candidate, "utf8");
+      const match = content.match(/^G_PAGESPEED_KEY\s*=\s*(.+)$/m);
+      if (match) return match[1].trim();
+    }
+    dir = resolve(dir, "..");
+  }
+  return null;
+}
+
+const apiKey = loadEnvKey();
+if (!apiKey) {
+  console.error("Error: G_PAGESPEED_KEY not found in environment or .env.local");
+  process.exit(1);
+}
+
+// ---------- API call ----------
+
+async function runAudit(url, strategy) {
+  const params = new URLSearchParams({
+    url,
+    strategy,
+    key: apiKey,
+  });
+  ["PERFORMANCE", "ACCESSIBILITY", "BEST_PRACTICES", "SEO"].forEach((c) =>
+    params.append("category", c)
+  );
+
+  const endpoint = `https://www.googleapis.com/pagespeedonline/v5/runPagespeed?${params}`;
+  const res = await fetch(endpoint);
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`PageSpeed API ${res.status}: ${text}`);
+  }
+  return res.json();
+}
+
+function extractSummary(raw) {
+  const categories = raw.lighthouseResult?.categories ?? {};
+  const audits = raw.lighthouseResult?.audits ?? {};
+
+  const scores = {};
+  for (const [id, cat] of Object.entries(categories)) {
+    scores[id] = Math.round((cat.score ?? 0) * 100);
+  }
+
+  const failures = [];
+  for (const audit of Object.values(audits)) {
+    if (
+      audit.score !== null &&
+      audit.score < 1 &&
+      !["informative", "notApplicable", "manual"].includes(audit.scoreDisplayMode)
+    ) {
+      failures.push({
+        id: audit.id,
+        title: audit.title,
+        score: audit.score,
+        severity: audit.score === 0 ? "FAIL" : "WARN",
+        displayValue: audit.displayValue ?? null,
+      });
+    }
+  }
+
+  // Sort failures: FAIL first, then by score ascending
+  failures.sort((a, b) => {
+    if (a.severity !== b.severity) return a.severity === "FAIL" ? -1 : 1;
+    return a.score - b.score;
+  });
+
+  return { scores, failures };
+}
+
+// ---------- reporting ----------
+
+function printSummary(results) {
+  for (const [strategy, summary] of Object.entries(results)) {
+    console.log(`\n=== ${strategy.toUpperCase()} ===`);
+    console.log("Scores:");
+    for (const [cat, score] of Object.entries(summary.scores)) {
+      console.log(`  ${cat.padEnd(16)} ${score}`);
+    }
+    if (summary.failures.length) {
+      console.log("\nFailing audits:");
+      for (const f of summary.failures) {
+        const display = f.displayValue ? ` — ${f.displayValue}` : "";
+        console.log(`  [${f.severity}] ${f.title}${display}`);
+      }
+    }
+  }
+}
+
+function printDiff(baseline, current) {
+  console.log("\n=== DIFF (baseline → current) ===");
+  for (const strategy of Object.keys(current)) {
+    console.log(`\n${strategy.toUpperCase()}:`);
+    const base = baseline[strategy]?.scores ?? {};
+    const curr = current[strategy].scores;
+    for (const cat of Object.keys(curr)) {
+      const b = base[cat] ?? "—";
+      const c = curr[cat];
+      const delta = typeof b === "number" ? c - b : null;
+      const arrow = delta === null ? "" : delta > 0 ? ` ▲ +${delta}` : delta < 0 ? ` ▼ ${delta}` : " =";
+      console.log(`  ${cat.padEnd(16)} ${String(b).padEnd(4)} → ${String(c).padEnd(4)}${arrow}`);
+    }
+
+    const baseFailures = new Set((baseline[strategy]?.failures ?? []).map((f) => f.id));
+    const currFailures = new Set(current[strategy].failures.map((f) => f.id));
+    const resolved = [...baseFailures].filter((id) => !currFailures.has(id));
+    const regressed = [...currFailures].filter((id) => !baseFailures.has(id));
+    if (resolved.length) {
+      console.log(`  Resolved: ${resolved.length}`);
+      for (const id of resolved) console.log(`    ✓ ${id}`);
+    }
+    if (regressed.length) {
+      console.log(`  Regressed: ${regressed.length}`);
+      for (const id of regressed) console.log(`    ✗ ${id}`);
+    }
+  }
+}
+
+// ---------- main ----------
+
+const results = {};
+for (const s of strategies) {
+  if (!args.silent) console.error(`Running ${s} audit for ${args.url}...`);
+  const raw = await runAudit(args.url, s);
+  results[s] = extractSummary(raw);
+}
+
+if (!args.silent) printSummary(results);
+
+if (args.output) {
+  writeFileSync(args.output, JSON.stringify(results, null, 2));
+  if (!args.silent) console.log(`\nWrote results to ${args.output}`);
+}
+
+if (args.baseline) {
+  if (!existsSync(args.baseline)) {
+    console.error(`Baseline file not found: ${args.baseline}`);
+    process.exit(1);
+  }
+  const baseline = JSON.parse(readFileSync(args.baseline, "utf8"));
+  printDiff(baseline, results);
+}

package/obj/template/.claude/skills/pagespeed-insights/LICENSE.md

@@ -0,0 +1,37 @@
+# License
+
+## Skill License - Free Use
+
+This skill (the documentation, structure, and implementation) was created by **Ender Puentes <Endev/>** and is provided for **free and open use**. You are free to:
+
+- ✅ **Use** this skill in any project, personal or commercial
+- ✅ **Modify** the skill to fit your needs
+- ✅ **Distribute** the skill to others
+- ✅ **Share** modified versions of the skill
+- ✅ **Include** this skill in your own skill collections
+
+**No restrictions apply** - this skill is available for unrestricted use. Attribution is appreciated but not required.
+
+**Note**: This skill documents and references the PageSpeed Insights guidelines and Core Web Vitals specifications, but the skill itself is an independent work created for team use.
+
+---
+
+## PageSpeed Insights Documentation
+
+This skill documents the [PageSpeed Insights documentation](https://developers.google.com/speed/docs/insights/v5/about?hl=es-419), which is a separate work created by Google.
+
+**The PageSpeed Insights documentation is NOT owned by the skill author.** The documentation has its own license:
+
+**Creative Commons Attribution 4.0 International (CC BY 4.0)**
+
+For information about the PageSpeed Insights documentation license, visit: https://creativecommons.org/licenses/by/4.0/
+
+**Documentation Source**: https://developers.google.com/speed/docs/insights/v5/about?hl=es-419
+
+This skill simply documents and references the official PageSpeed Insights guidelines for educational and practical use. The skill author claims no ownership or rights over the PageSpeed Insights documentation itself.
+
+## Skill Author
+
+This skill was created by **Ender Puentes <Endev/>** - https://enderpuentes.com
+
+The skill itself (as a documentation/implementation work) is released for free and unrestricted use. While attribution is appreciated, it is not required for using, modifying, or distributing this skill.