ai-for-dummies/plans/astro-refactor

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.

Session state: see HANDOVER.md. Phase 0 is done and green on four branches; nothing is merged or pushed.

Read before starting anything

File	Why
../../AGENTS.md	entry point
../../.agents/context/design-system.md	three drifting palettes, a font that has never rendered
../../.agents/context/verification.md	42 assertions that will all break, and must not be deleted
../../.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 pnpm 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	astro-architect	—	—
02	design tokens	design-system-keeper	01	03, 04
03	verification net	verification-engineer	01	02, 04
04	content schema	content-i18n-migrator	01	02, 03
05	guide content	content-i18n-migrator	04	06
06	review-desk content	content-i18n-migrator	04	05
07	primitives	component-builder	02	—
08	route cards	component-builder	07	09, 10, 11
09	chapter blocks	component-builder	07	08, 10, 11
10	guide blocks	component-builder	07	08, 09, 11
11	review-desk blocks	component-builder	07	08, 09, 10
12	landing page	page-migrator	03, 08	13, 14, 17
13	chapter pages ×4	page-migrator	03, 09	12, 14, 17
14	rules page	page-migrator	03, 09	12, 13, 17
15	full guide	page-migrator	05, 10, 13	16
16	review desk	page-migrator	06, 11, 13	15
17	hands-on passthrough	astro-architect	01	12, 13, 14
18	motion pass	motion-designer	15, 16	19
19	contract re-point	verification-engineer	15, 16	18
20	cutover + cleanup	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

.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 pnpm install --frozen-lockfile 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:

pnpm 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.

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.