Marcos Paulo
9015e7bd1d
Removes the Go source, Dockerfile, go.mod, and Kubernetes manifests. The
deployed service is untouched and the review desk still calls it over
window.SKILLS_REVIEW_VOTE_API; only the source leaves.
The runbook does not leave. vote-service/README.md moves to
docs/vote-service.md, because it carries the parts that are hard to
rediscover: why the ingress overwrites X-Forwarded-For and Caddy stamps
X-Client-IP instead, why the image is side-loaded into containerd rather
than pulled, and why the PVC pins the Deployment to one node.
This drops verify.mjs from 84 assertions to 83. The removed one read
vote-service/main.go for X-Forwarded-For and 'one active vote per skill'
-- the review desk's only anti-abuse control -- and there is no file left
to read. It is the first assertion this repository has ever lost.
Rather than lower the gate's floor and leave a bare number behind,
gate.sh now subtracts the number of entries in
.agents/context/assertion-removals.md from the baseline. A removal costs
a written reason in a tracked file, in the same commit, as a visible
diff. Tested at 82 assertions: still refused.
Also drops the 22 MB of PNG baselines under .agents/snapshots/before/ and
before-reduced-motion/. They pictured the hand-written site, which no
longer exists; visual-regression.mjs has no compare mode to diff them
against; and they are recoverable from d88d8b8.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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
- 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.
- Assertions deleted to make a red suite green. That converts a
content-loss bug into a passing build.
gate.shrefuses a coverage drop. - Base-path bugs. The site lives at
/ai-for-dummies/. It will work perfectly inpnpm run previewand 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 | astro-architect | — | — |
| 02 | design tokens | design-system-keeper | 01 | 03, 04 |
| 02b | token layer wiring | design-system-keeper | 02 | 03, 04 |
| 02c | token-gap queue | design-system-keeper | 02b, 15d | — |
| 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 — split into 15a–15e | — | — | — |
| 05b | interactiveCopy data | content-i18n-migrator | 05 | — |
| 15a | guide selector | component-builder | 05, 10 | 15b, 15c |
| 15b | copy prompt | component-builder | 05 | 15a, 15c |
| 15c | language toggle | content-i18n-migrator | 05 | 15a, 15b |
| 15d | assemble full guide | page-migrator | 05b, 10, 13, 15a–c | 16 |
| 15e | retire responsive.css | design-system-keeper | 15d, 16 | — |
| 16 | review desk | page-migrator | 06, 11, 13 | 15d |
| 17 | hands-on passthrough | astro-architect | 01 | 12, 13, 14 |
| 18 | motion pass | motion-designer | 15d, 16 | 19 |
| 19 | contract re-point | verification-engineer | 15d, 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.