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