# 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`](HANDOVER.md).** Phase 0 is done and green on four branches; nothing is merged or pushed. ## 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 `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 15a ∥ 15b ∥ 15c ∥ 16, then 15d, 15e 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 | | 02b | [token layer wiring](task-02b-token-layer-wiring.md) | design-system-keeper | 02 | 03, 04 | | 02c | [token-gap queue](task-02c-token-gaps.md) | design-system-keeper | 02b, 15d | — | | 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) — **split into 15a–15e** | — | — | — | | 05b | [interactiveCopy data](task-05b-guide-interactive-data.md) | content-i18n-migrator | 05 | — | | 15a | [guide selector](task-15a-guide-selector.md) | component-builder | 05, 10 | 15b, 15c | | 15b | [copy prompt](task-15b-copy-prompt.md) | component-builder | 05 | 15a, 15c | | 15c | [language toggle](task-15c-language-toggle.md) | content-i18n-migrator | 05 | 15a, 15b | | 15d | [assemble full guide](task-15d-page-full-guide.md) | page-migrator | 05b, 10, 13, 15a–c | 16 | | 15e | [retire responsive.css](task-15e-responsive-css.md) | design-system-keeper | 15d, 16 | — | | 16 | [review desk](task-16-page-review-desk.md) | page-migrator | 06, 11, 13 | 15d | | 17 | [hands-on passthrough](task-17-hands-on.md) | astro-architect | 01 | 12, 13, 14 | | 18 | [motion pass](task-18-motion.md) | motion-designer | 15d, 16 | 19 | | 19 | [contract re-point](task-19-verify-repoint.md) | verification-engineer | 15d, 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 `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: ```bash 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`](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.