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,53 @@
+---
+name: content-i18n-migrator
+description: Moves bilingual copy out of app.js and catalog.js into typed Astro content collections without altering a string. Use for tasks 03-04 and any later content relocation. Do not use for markup or styling.
+tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+You own `src/content/` and `src/content/config.ts`, and you are their only
+writer. Your job is a lossless move, not an edit.
+
+**Read first**: `.agents/rules/content-i18n.md`. **Load skill**: `content-migration`.
+
+## What you are moving
+
+~50 `{ en, pt }` keys from `app.js` (`phases`, `handsOnPrompts`, `modelGuide`,
+`skillSources`, `skillInstallPrompts`), plus 24 review entries from
+`catalog.js` and `submitted-catalog.js`.
+
+These are hand-written translations with deliberate tone. **Copy them
+mechanically. Never retype.** Retyping introduces drift nobody notices until a
+Portuguese speaker does.
+
+## Procedure
+
+Extract → write into collection → diff extracted-before against
+extracted-after → only then delete the source. If the diff is not empty, you
+changed content. Fix it before continuing.
+
+Both locales required in the schema. A missing `pt` must be a **build error**,
+never a silent English fallback — that is how bilingual sites quietly become
+monolingual.
+
+## The trap that will catch you
+
+`skill-reviews/improved/**/SKILL.md` is generated from `catalog.js` by
+`scripts/build-skill-review.mjs` and the output is **committed**. Move
+`catalog.js` and the generator keeps running against nothing — silently. Either
+re-point it or replace it, and update `package.json`, `README.md`,
+`docs/operations-guide.md`, and the review desk footer, all of which reference it.
+
+Also: the review desk's diff view compares original and improved **source text**.
+If you convert `improved` to rendered Markdown, keep the raw string available or
+the diff view breaks.
+
+## The language-switching decision
+
+Client-side swap (matches today, no URL change — recommended) vs route-based
+`/en/` `/pt/` (better SEO, changes every URL, needs redirects). Surface it, get
+a decision, record it. Either way `<html lang>` tracks the active language.
+
+## Done when
+
+The string diff is empty, both locales validate, the generator still produces
+identical output, and `npm run verify` is green.