Files

T

Marcos Paulo aae4d42229 docs: add .agents workspace and the Astro refactor plan

Adds the agent-facing workspace and a 20-task plan for migrating the site
to Astro. Nothing here implements the refactor; these are briefs, rules and
templates that the task agents read.

- .agents/ holds context, rules, checklists, skills, specialist agents,
  component/page/config templates and gate scripts. It is vendor-neutral so
  MiniMax, Gemini and Codex can all read it; CLAUDE.md just points at
  AGENTS.md.
- .husky/ plus .lintstagedrc.json wire the three gate tiers. gate.sh locks on
  the shared git-common-dir so parallel worktrees serialise, and guards the
  assertion count in scripts/verify.mjs against a coverage drop.
- plans/astro-refactor/ carries the phase graph, per-task briefs and the
  model-routing recommendation.

These files must be tracked before fanning out: a worktree only checks out
tracked files, so an untracked plan is invisible to every agent working in one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-09-05 01:18:27 +00:00

2.4 KiB

Raw Blame History

name, description

name	description
visual-regression	Prove a refactor did not change how the site looks. Use before and after any page migration, token consolidation, or breakpoint change on ai-for-dummies.

Visual regression

"Maintain the same styles" is a testable claim. Test it.

Capture

The repo already has a Playwright pattern (scripts/inspect.py). Extend it rather than inventing one.

from playwright.sync_api import sync_playwright
ROUTES = ['/', '/full-guide/', '/summary/', '/models/', '/agents/',
          '/skills/', '/rules/', '/skills-review/',
          '/hands-on/starter/', '/hands-on/rules/']
WIDTHS = [560, 800, 1100, 1600]

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    for route in ROUTES:
        for w in WIDTHS:
            page = browser.new_page(viewport={'width': w, 'height': 900})
            page.goto(f'{BASE}{route}', wait_until='networkidle')
            page.screenshot(path=f'{OUT}/{route.strip("/").replace("/","_") or "index"}-{w}.png',
                            full_page=True)
            page.close()
    browser.close()

Run once against the vanilla site (npm run serve), once against npm run preview. Keep both sets.

Compare

for f in before/*.png; do
  compare -metric AE "$f" "after/$(basename $f)" null: 2>&1   # ImageMagick
  echo "  <- $(basename $f)"
done

Pixel-exact is not the bar — antialiasing differs. Judge by eye where the metric is non-trivial, and attach the pair to the task report.

The three widths that catch the most

560px — where the 16 ad-hoc breakpoints collapse to --bp-sm. Highest risk in the whole migration.
800px — the most common existing breakpoint; layout flips here.
1600px — min-width rules that only fire on large screens are the ones nobody notices are broken.

Also screenshot at the old breakpoint values you removed (520, 530, 600, 620, 720, 850, 880, 900), not just the new ones. Regressions hide exactly there.

What a real difference looks like

Expect and accept: sub-pixel text shifts, antialiasing.

Investigate: anything that moves by more than ~2px, any colour change (that is a token bug), any element that appears or disappears (that is content loss — stop and check the snapshot diff).

Reduced motion

Capture one pass with prefers_reduced_motion='reduce'. Animations must land in their correct end state, not vanish.

2.4 KiB Raw Blame History