Astro Code Doctor

Astro code generated quickly — by an AI agent or a human moving fast — tends to drift from spec over time and pile up as monolithic pages instead of reusable components. Catching this manually means re-reading every file against changing Astro conventions, which nobody has time to do consistently. ## What it does - Checks spec compliance: invalid export default in .astro files, missing client:* hydration directives, Tailwind v4 class naming (space-y-* to gap-*, flex-shrink/flex-grow to shrink/grow), img tags that should use the Image component, deprecated z imports in MDX/MD content collections, and basic accessibility structure (nav > ul > li, button text, input labels) - Extracts components at medium and deep levels: repeated inline HTML blocks, page-level monoliths with no component imports, and inconsistent granularity across files - Restructures with an atomic-design lens at the deep level: atoms, molecules, organisms, and proper slot composition, including the Header/Footer-belongs-in-Layout rule - Looks up current Astro documentation (via the Astro Docs MCP or Context7 when available) for the handful of things it is not fully certain about, rather than relying only on built-in knowledge - Optionally checks responsive images with --images: adds layout to Image components (full-width, constrained, or fixed) so the browser picks the right size from a srcset, adds priority to the first-view image, and proposes an explicit sizes when an image fills only part of the viewport. Off by default, independent of the three levels, and it never changes how the page looks - Always shows the full optimization plan before touching anything, and builds the project afterward to confirm nothing broke ## How it works - Collects every .astro, .tsx, .ts, .mdx, and .md file in the given scope - Analyzes each file across spec compliance, component granularity, and (deep only) architecture - Queries live Astro documentation for the most uncertain findings - Displays a structured, file-by-file plan with severity labels and asks how to proceed: apply everything, spec fixes only, file-by-file, or cancel - Applies the confirmed changes, then runs the project's build command and fixes any resulting errors before reporting ## What it is not This is a code reviewer and refactorer, not a linter you wire into CI — it runs interactively, shows its plan, and waits for confirmation before changing anything. It does not add new features or content; it restructures and corrects what is already there. ## Requirements Works on any Astro project. Uses the Astro Docs MCP or Context7 MCP for up-to-date documentation lookups when either is available in the agent — falls back to built-in Astro knowledge otherwise, so neither is required to run it. The optional responsive-image check needs Astro 5.10 or later; on older versions it is skipped and says so.