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>

plans/astro-refactor/README.md

@@ -0,0 +1,94 @@
+# Astro refactor — plan
+
+**Status: not started. These are briefs, not work.** Nothing in this plan has
+been implemented.
+
+Goal: move `ai-for-dummies` from ten hand-written HTML pages to Astro, so that
+adding a chapter is a component and a content entry rather than a copy-pasted
+file — **without changing how the site looks, what it says, or what it costs a
+visitor to load.**
+
+## Read before starting anything
+
+| File | Why |
+| --- | --- |
+| [`../../AGENTS.md`](../../AGENTS.md) | entry point |
+| [`../../.agents/context/design-system.md`](../../.agents/context/design-system.md) | three drifting palettes, a font that has never rendered |
+| [`../../.agents/context/verification.md`](../../.agents/context/verification.md) | 42 assertions that will all break, and must not be deleted |
+| [`../../.agents/context/publishing.md`](../../.agents/context/publishing.md) | Gitea Pages serves a branch and cannot build |
+
+## The three things most likely to go wrong
+
+1. **Content loss that nobody notices.** 50 KB of bilingual copy moves between
+   files. Snapshot every route *before* migrating it — task 03 exists to make
+   that possible and blocks all page work.
+2. **Assertions deleted to make a red suite green.** That converts a content-loss
+   bug into a passing build. `gate.sh` refuses a coverage drop.
+3. **Base-path bugs.** The site lives at `/ai-for-dummies/`. It will work
+   perfectly in `npm run preview` and 404 in production. Verify on the real host.
+
+## Phases
+
+```
+Phase 0  foundation        01 → (02 ∥ 03 ∥ 04)
+Phase 1  content           05 ∥ 06                    after 04
+Phase 2  components        07 → (08 ∥ 09 ∥ 10 ∥ 11)   after 02
+Phase 3  pages             12 ∥ 13 ∥ 14 ∥ 17, then 15 ∥ 16
+Phase 4  polish            18 ∥ 19, then 20
+```
+
+| # | Task | Agent | Depends on | Parallel with |
+| --- | --- | --- | --- | --- |
+| 01 | [scaffold + gates](task-01-scaffold.md) | astro-architect | — | — |
+| 02 | [design tokens](task-02-tokens.md) | design-system-keeper | 01 | 03, 04 |
+| 03 | [verification net](task-03-verification-net.md) | verification-engineer | 01 | 02, 04 |
+| 04 | [content schema](task-04-content-schema.md) | content-i18n-migrator | 01 | 02, 03 |
+| 05 | [guide content](task-05-content-guide.md) | content-i18n-migrator | 04 | 06 |
+| 06 | [review-desk content](task-06-content-review.md) | content-i18n-migrator | 04 | 05 |
+| 07 | [primitives](task-07-primitives.md) | component-builder | 02 | — |
+| 08 | [route cards](task-08-route-cards.md) | component-builder | 07 | 09, 10, 11 |
+| 09 | [chapter blocks](task-09-chapter-blocks.md) | component-builder | 07 | 08, 10, 11 |
+| 10 | [guide blocks](task-10-guide-blocks.md) | component-builder | 07 | 08, 09, 11 |
+| 11 | [review-desk blocks](task-11-review-blocks.md) | component-builder | 07 | 08, 09, 10 |
+| 12 | [landing page](task-12-page-landing.md) | page-migrator | 03, 08 | 13, 14, 17 |
+| 13 | [chapter pages ×4](task-13-page-chapters.md) | page-migrator | 03, 09 | 12, 14, 17 |
+| 14 | [rules page](task-14-page-rules.md) | page-migrator | 03, 09 | 12, 13, 17 |
+| 15 | [full guide](task-15-page-full-guide.md) | page-migrator | 05, 10, 13 | 16 |
+| 16 | [review desk](task-16-page-review-desk.md) | page-migrator | 06, 11, 13 | 15 |
+| 17 | [hands-on passthrough](task-17-hands-on.md) | astro-architect | 01 | 12, 13, 14 |
+| 18 | [motion pass](task-18-motion.md) | motion-designer | 15, 16 | 19 |
+| 19 | [contract re-point](task-19-verify-repoint.md) | verification-engineer | 15, 16 | 18 |
+| 20 | [cutover + cleanup](task-20-cutover.md) | astro-architect | all | — |
+
+Widest parallelism: **four agents** (tasks 08–11, then 12/13/14/17). More than
+that and they start contending on review capacity, not on files.
+
+## Running a task
+
+```bash
+.agents/scripts/worktree.sh start 08 route-cards
+cd ../af-task-08
+# agent reads: plans/astro-refactor/task-08-route-cards.md
+#              .agents/agents/component-builder.md  (+ the skills it names)
+```
+
+The script runs `npm ci` and `verify-hooks.sh` for you. That matters: `.husky/_`
+is generated, not committed, so a hand-made worktree has hooks configured but
+**silently not running**.
+
+Finishing:
+
+```bash
+npm run gate                       # tier 2, same as pre-push
+# reviewer agent reads the diff against .agents/checklists/before-merge.md
+.agents/scripts/worktree.sh finish 08 route-cards
+```
+
+## Which model to run each task
+
+See [`MODEL-ROUTING.md`](MODEL-ROUTING.md).
+
+## These files must be committed
+
+Worktrees check out tracked files. If this plan stays untracked, every worktree
+you create will be missing it. Commit `plans/` and `.agents/` before fanning out.