Marcos Paulo
48c31dc1b3
Ten git worktrees each carried their own 225 MB node_modules (1.1 GB across five) and paid 11s per `npm ci`. pnpm hardlinks from a shared store: the same five worktrees cost ~250 MB total, and a fresh install is 4s. What changed beyond the mechanical rename: - `overrides` moved to `pnpm-workspace.yaml`. pnpm 11 does not read the `pnpm` field in package.json *or* npm's top-level `overrides`, and it fails silently — the vite/defu/language-server pins would have quietly stopped applying. - Build scripts are blocked by default in pnpm; esbuild and sharp are allowed explicitly via `allowBuilds` (renamed from `onlyBuiltDependencies` in 11). - `packageManager` + `engines` pin the toolchain. - gate.sh rejects a package-lock.json/yarn.lock/bun.lock outright, so an agent running `npm install` out of habit fails loudly instead of building a second, divergent dependency tree. - CI bootstraps pnpm with `npm install --global pnpm@11.25.0` rather than corepack (unbundled as of Node 25) or pnpm/action-setup (this self-hosted act-runner has never run a job; fetching a third-party action is not something to discover on the first one). Two pre-existing CI bugs fixed while in the file: - the gate installed with `npm install --package-lock=false`, which discarded the lockfile the previous session had just fixed. - the visual-regression step imported `playwright`, which is not a dependency, and `visual-regression.mjs` has no compare mode anyway — in CI it overwrote its own baselines and passed unconditionally. Removed with a comment; it comes back when it can diff. The `publish` job is now manual (`workflow_dispatch`). During the migration dist/ holds three HTML files against the live pages branch's ten, so publishing on every push to main would take the site down to a stub. Restore at task 20. HANDOVER.md's incident log still says npm where it describes what happened at the time; that is history, not a missed rename. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1.9 KiB
name, description, tools
| name | description | tools |
|---|---|---|
| page-migrator | Migrates one hand-written HTML page to an Astro route with identical URL, content, and JS budget. Use for the page-migration tasks (10-16). Do not use for component extraction or config changes. | Read, Write, Edit, Bash, Grep, Glob |
You migrate one page per task. The bar is that a visitor cannot tell.
Read first: .agents/context/architecture.md,
.agents/context/verification.md. Load skills: astro-page,
content-migration, visual-regression.
Snapshot before you touch anything
Rendered-text snapshot plus screenshots at 560/800/1100/1600 px, from the vanilla site. Without a before, you cannot prove an after. This is not optional and it is the step agents skip.
Hard constraints
- URL identical, trailing slash included. Internal links go through
import.meta.env.BASE_URL, never a hand-written absolute path. - Query params survive — the review desk uses
?author=,?skill=,?view=,?file=,?compare=,?render=and they are shared externally. - JS budget does not grow. A page that shipped zero JS still ships zero. Seven of ten pages are in that category.
- Every
data-*hook, ARIA attribute,<title>, and<meta>preserved. - Reuse existing components before creating new ones.
- Do not port
responsive.csswholesale. Take what the page needs; prove the rest is dead and delete it.
hands-on/ is not yours
hands-on/starter/ and hands-on/rules/ are lab fixtures that ship from
public/ unchanged. Their value is being plain dependency-free files an
attendee hands to an agent. If your task appears to ask you to componentize
them, it is wrong — stop and report.
Done when
.agents/checklists/before-page.md complete, snapshot diff empty (or every line
justified), node scripts/audit-ui.mjs and pnpm run verify green, screenshots
compared, and your task report lists what you deliberately left alone.