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
parent aa85c1d0b7
commit aae4d42229
79 changed files with 3805 additions and 0 deletions
@@ -0,0 +1,65 @@
+---
+name: astro-page
+description: Migrate one hand-written HTML page of the ai-for-dummies site to an Astro route without changing its URL, content, or JS budget. Use for any page-level migration task.
+---
+
+# Migrating a page to Astro
+
+## Snapshot first, migrate second
+
+The snapshot is the only objective evidence that no content was lost.
+
+```bash
+npm run serve &                                  # vanilla site on :4173
+node .agents/scripts/snapshot-route.mjs http://localhost:4173/models/ \
+  > .agents/snapshots/models.txt
+```
+
+Screenshot the same route at 560 / 800 / 1100 / 1600 px as well.
+
+## Migrate
+
+```bash
+cp .agents/templates/pages/chapter.astro src/pages/models.astro
+```
+
+Then, in order:
+
+1. Move markup into the layout + components. Reuse existing components before
+   creating new ones.
+2. Move copy into `src/content/`. Both `en` and `pt`, copied literally — never
+   retyped.
+3. Move page CSS into component `<style>` blocks. Do **not** port
+   `responsive.css` wholesale; take what this page needs and prove the rest dead.
+4. Keep every `data-*` hook. `verify.mjs` asserts many of them by name
+   (`data-phase`, `data-tree`, `data-route`, `data-model-provider`, …).
+5. Keep every ARIA attribute and the `<title>` / `<meta name="description">`.
+
+## The URL must not change
+
+Served from `/ai-for-dummies/`, so `base` is set in `astro.config.mjs`. Never
+hand-write an internal absolute path; use `import.meta.env.BASE_URL`.
+
+Trailing slashes matter. `/models/` must not become `/models`.
+
+If the page honours query params (the review desk uses `?author=`, `?skill=`,
+`?view=`, `?file=`, `?compare=`, `?render=`), they must still work — they are
+documented in the page footer and shared externally.
+
+## Prove it
+
+```bash
+npm run build
+node .agents/scripts/snapshot-route.mjs dist/models/index.html > /tmp/after.txt
+diff .agents/snapshots/models.txt /tmp/after.txt      # empty, or justify every line
+node scripts/audit-ui.mjs
+npm run verify
+```
+
+Then screenshots at the same four widths, and
+[`../../checklists/before-page.md`](../../checklists/before-page.md).
+
+## JS budget
+
+A page that shipped zero JS must still ship zero. Check the build output. If
+your migration added a `client:load` to a static page, you did it wrong.