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,15 @@
+# Checklist: before you call a component done
+
+- [ ] It appears (or will appear) in **three** places, or has a name a person says out loud
+- [ ] Lives in the right folder: `primitives/`, `blocks/`, or `islands/`
+- [ ] Typed `interface Props`; every field intentional; no `any`
+- [ ] **No raw hex, px font sizes, or ad-hoc breakpoints** — tokens only
+- [ ] Ships zero JS, or has a `client:*` directive with a written justification
+- [ ] Markup under ~120 lines
+- [ ] Native elements: `<button>` for actions, `<a>` for navigation
+- [ ] Keyboard: tab to it, operate with Enter/Space, focus ring visible
+- [ ] Interactive state exposed via ARIA (`aria-pressed`, `aria-current`), not just colour
+- [ ] Any motion respects `prefers-reduced-motion` and animates only `transform`/`opacity`
+- [ ] Renders correctly at 560 / 800 / 1100 / 1600 px
+- [ ] Both `en` and `pt` strings present; no hard-coded copy
+- [ ] `npm run verify` green with no assertion deleted
@@ -0,0 +1,12 @@
+# Checklist: before you merge a task branch
+
+- [ ] Rebased on current `origin/main`, conflicts resolved in the worktree
+- [ ] `npm run verify` and `node scripts/audit-ui.mjs` both green
+- [ ] **Assertion count in `verify.mjs` did not fall** (`grep -c 'throw new Error' scripts/verify.mjs`)
+- [ ] Only files in your task's scope changed — `git diff --stat origin/main` matches the brief
+- [ ] No contended file edited unless you own it (see `rules/git-worktrees.md`)
+- [ ] No `.serena/`, `__pycache__/`, `dist/`, or scratch files staged
+- [ ] Commit message: what, why, and what you deliberately did not do
+- [ ] Task report written: verified behaviours, known gaps, follow-ups
+- [ ] `reviewer` agent has read the diff
+- [ ] Worktree and branch cleaned up after merge
@@ -0,0 +1,14 @@
+# Checklist: before you call a page migrated
+
+- [ ] URL identical to the old one, **trailing slash included**
+- [ ] Any query params the old page honoured still work (`?author=`, `?skill=`, `?view=`, `?file=`, `?compare=`, `?render=`)
+- [ ] Rendered text content diffs clean against the pre-migration snapshot — or every difference is listed and justified
+- [ ] Same number of JS bytes or fewer; a previously-zero-JS page still ships zero
+- [ ] `<title>`, `<meta name="description">`, and `<meta name="viewport">` preserved
+- [ ] One `<h1>`; heading levels do not skip
+- [ ] Every ARIA attribute from the original survived (`verify.mjs` asserts several)
+- [ ] No external `<script>`, `<link>`, `@import`, or `url()` — `node scripts/audit-ui.mjs` green
+- [ ] Internal links go through `BASE_URL`, not hand-written absolute paths
+- [ ] Screenshots at 560 / 800 / 1100 / 1600 px compared against the old page
+- [ ] `<html lang>` correct and still switching with the language toggle
+- [ ] `npm run verify` green with no assertion deleted