Files

T

Marcos Paulo aae4d42229 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>

2026-09-05 01:18:27 +00:00

2.6 KiB

Raw Blame History

Task 15 — Full guide

Agent: page-migrator · Model: Codex — hardest task in the plan Depends on: 05, 10, 13 · Parallel with: 16 Worktree: .agents/scripts/worktree.sh start 15 page-full-guide

Goal

/full-guide/ → Astro. 22 KB of HTML, a 50 KB script, 30 KB of CSS, twelve render functions, bilingual throughout.

What `app.js` actually is

Not application code — a bilingual content database (task 05 already moved it) plus ~12 render* functions that swap innerHTML on tab clicks. Once content is a collection, the remaining JS is small: tab state and a language toggle.

Islands

Only these hydrate. Everything else is server-rendered.

Island	Directive	Why
Phase tabs	`client:visible`	click-driven panel swap
Tree / worker / route / model / effort / skill selectors	`client:visible`	same pattern; consider one generic selector island
Language toggle	`client:idle`	page-wide, not urgent
Copy-prompt buttons	`client:visible`	clipboard

If you end up with 12 separate islands you have missed the pattern — they are one selector component with different data.

Asserted by verify.mjs — all must survive

const phases, const handsOnPrompts, const modelGuide, const skillSources, const skillInstallPrompts, render('plan'), renderTree, renderWorker, renderRoute, renderModelProvider, renderEffort, renderSkillFile, renderSkillWorkflow, renderCommonSkill, renderHandsOn, copyPrompt.

These are implementation-detail assertions — they look deletable and are not. Each pins a feature. Coordinate with task 19 to replace each with an output-level assertion of the same behaviour. Never delete one yourself.

Also: data-copy-target="prompt-install-skills|prompt-basic|prompt-skills", hands-on/starter/, additional-reading.md, role="tablist", <table>.

Watch for

copyPrompt uses navigator.clipboard with a document.execCommand fallback. Keep both — the fallback exists for non-secure contexts.
The hands-on prompt strings are copy-pasted by attendees into an agent. Exact whitespace and line breaks matter.
responsive.css (30 KB) mostly serves this page. Port what is needed, prove the rest dead, delete it. Screenshots are the proof.

Done when

Snapshot diff empty
Every interaction works: all tabs, both languages, all copy buttons
Keyboard: arrow keys move between tabs; focus visible throughout
JS payload smaller than today's 50 KB (content is now static)
Screenshots match at four widths; checklist complete; npm run gate green

2.6 KiB Raw Blame History