Documentation
Open AstroDeck in your coding agent and describe your site; the agent follows the workflow below. Everything it runs, you can run yourself.
Getting Started
Download AstroDeck, open it in your coding agent and describe your site. Requires Node.js >=22.23.4.
No coding experience
- Download the ZIP from the latest release and unzip it.
- Optional: put what you already have into the
brief/folder (texts, PDFs, a logo, aDESIGN.md). - Open the folder in your coding agent (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf) and say what you want:
"Build my website for a physiotherapy practice in Hamburg with online booking."
The agent installs everything, asks a few questions in one message (each with a proposed default), shows a preview at http://localhost:4321 and iterates with you. You do not need to run any command yourself.
Developers
npx degit holger1411/astrodeck my-site
cd my-site
npm install
npm run devgit clone or the release ZIP work the same way. Then let your agent run the workflow, or work by hand: set src/config/site.ts, run npm run theme, compose pages from sections and finish with npm run verify.
Avoid npm create astro -- --template holger1411/astrodeck: create-astro can write its own AGENTS.md over the kit's.
The Build-Site Workflow
"Build my website" routes the agent to the astrodeck-build-site skill (.agents/skills/astrodeck-build-site/SKILL.md). It works through eight steps and names the command and reference for each.
- 1
Intake
The agent inventories your messages, PROJECT.md and brief/. Little input: one message with at most five questions, each with a proposed default. A full briefing: it extracts faithfully, notes sources and lists conflicts and gaps instead of inventing.
- 2
Start clean
The astrodeck-cleanup skill removes the demo before anything is written, after showing the plan.
npm run starter:clean -- --dry-run - 3
Brief and site plan
PROJECT.md is filled, a recipe is chosen (agency-portfolio, event-landing, local-business, personal-creator, saas) and each page gets a section list from the registry.
- 4
Configure
src/config/site.ts and SITE_URL from the brief; interface text in src/config/ui.ts for non-English sites; robots.txt, llms.txt and favicon.svg for the real domain and logo.
- 5
Theme
Brand colors, neutral tone and radius as OKLCH tokens with a contrast gate; fonts only on brand input. npm run icons renders the PNG icons and the social image in the brand color.
npm run theme -- --primary "<hex>" --dry-run - 6
Build pages
Home first with an early preview, then the rest, composed from sections in the recipe order. Facts come only from the brief.
npm run dev - 7
Verify and audit
All checks pass, then the vibe2prod audit targets READY, then the manual items of the quality checklist.
npm run verify -- --starter - 8
Handover
What was built, the defaults it chose, open questions (logo, photos, legal pages, form endpoints, URL), check results and how to deploy.
Task → skill
| The user wants ... | Skill |
|---|---|
| A website, or "adapt AstroDeck to my project" | astrodeck-build-site |
| A new page | astrodeck-new-page |
| A section no registry section covers, or a new prop | astrodeck-new-section |
| Colors, fonts, radius, logo, DESIGN.md | astrodeck-theme |
| Remove the demo | astrodeck-cleanup |
| An audit or launch check | vibe2prod |
Skills live in .agents/skills/ (6 skills: astrodeck-build-site, astrodeck-cleanup, astrodeck-new-page, astrodeck-new-section, astrodeck-theme, vibe2prod). AGENTS.md names every one, so agents that do not load skills on their own still find them.
Brief Folder & PROJECT.md
Your input can be one sentence or a full briefing. More material means fewer questions.
brief/ — your material
- Texts: about, services, company profile PDF, an old flyer
- Page content: opening hours, prices, FAQs, quotes you may use
- Design: a
DESIGN.mdwith color tokens, brand guidelines, logo files (SVG preferred) - Images you own, and a links list (current site, profiles, sites you like)
Files in brief/ are inputs, not part of the website. No passwords or keys: in a public repository this folder is public too.
PROJECT.md — the brief
The agent writes a structured brief and keeps it up to date. It overrides the defaults in AGENTS.md, so later sessions and other agents continue from it. Headings:
Goal & audience · Offer · Sitemap · Tone & language · Brand · Content sources · Must-haves / no-gos · Open questions · Decisions & defaults
Only real facts go in. Missing facts become open questions and stay off the site.
Site Config
Brand, navigation, footer, SEO defaults and feature flags live in one typed file: src/config/site.ts. The production URL lives in src/config/site-url.mjs (SITE_URL), shared with astro.config.mjs.
| Field | Used for |
|---|---|
| name, description | Header, footer, meta tags, manifest |
| url | SITE_URL: canonical URLs, sitemap, RSS |
| lang, locale | <html lang>, Open Graph locale, RSS language |
| titleTemplate | Page titles, e.g. "%s | Harbor Physio" |
| author | Meta author, default blog author |
| logo | Wordmark text, inline SVG or image |
| nav, headerCta | Header navigation and button |
| footer | Tagline, link groups, copyright, optional credit |
| social, contact | Footer: social profile links, contact email (mailto:), phone (tel:) and address; empty renders nothing (real data only) |
| ogImage | Default social preview image |
| features | blog, rss, analytics on or off |
export const site: SiteConfig = {
name: 'Harbor Physio',
url: SITE_URL,
description: 'Physiotherapy in Hamburg-Altona',
lang: 'en',
locale: 'en_US',
titleTemplate: '%s | Harbor Physio',
nav: [
{ href: '/', label: 'Home' },
{ href: '/services', label: 'Services' },
],
// footer, social, contact, ogImage, features ...
};Pages pass plain titles (title="Services"); the layout adds the brand through titleTemplate. Components never repeat the brand name.
Theme & Branding
npm run theme writes OKLCH color tokens for light and dark mode into src/styles/globals.css and checks WCAG contrast of the key text pairs. It fails when a pair is too weak and suggests the nearest passing value.
With your agent
"Use our brand color #0f766e and rounder corners."
"Apply brief/DESIGN.md."
The astrodeck-theme skill collects values (also from a logo or a design-system link), runs a dry run, reads the contrast report and applies it. Fonts change only on brand input.
By hand
npm run theme -- --primary "#0f766e" --dry-run
npm run theme -- --primary "#0f766e" --accent "#f59e0b" \
--neutral slate --radius 0.75rem
npm run theme -- --from brief/DESIGN.md
npm run icons # PNG icons + public/og.png from favicon.svg--neutral: zinc, slate, stone, neutral or gray. The token regions in globals.css are written by the script; do not edit them by hand. There is no tailwind.config.
Sections & Pages
Pages are composed from registry sections with props. Content is data, so a section never has to be copied to change its text.
| Building block | Count | Location |
|---|---|---|
| Sections | 16 | src/components/sections/ |
| UI components | 11 | src/components/ui/ |
| Layouts | 5 | src/layouts/ |
src/registry.json lists every section, layout and UI component with props, a "use when" hint and a usage example; npm run check:registry keeps it in sync with the code. Icons come from IconName in src/lib/icons.ts.
A page
---
import BaseLayout from '@/layouts/BaseLayout.astro';
import Hero from '@/components/sections/Hero.astro';
import FAQ from '@/components/sections/FAQ.astro';
---
<BaseLayout title="Services" description="...">
<Hero title="..." subtitle="..."
primaryCta={{ href: '/contact', label: 'Book a visit' }} />
<FAQ title="Questions" faqs={[{ question: '...', answer: '...' }]} />
</BaseLayout>With your agent
"Add a pricing page with our three packages."
astrodeck-new-page picks the layout and sections, sets title and description, links the page in site.nav and verifies. Only when no section fits does astrodeck-new-section add a prop or a new registered section. Sections that need real data (testimonials, stats, team, logos, pricing) are used only when you supply that data.
Demo Cleanup
The download is this demo site. npm run starter:clean removes it in one step; the build-site workflow does this right after intake.
npm run starter:clean -- --dry-run # show the plan
npm run starter:clean -- --yes # remove the demo
npm run starter:clean -- --yes --keep-blogIt is one-shot and destructive: it runs only while the starter/ folder exists; a second run does nothing (it prints "Already cleaned"). Without --yes it asks for confirmation.
- Removed: docs and showcase pages, changelog, demo templates, login and privacy samples, demo blog posts, screenshots, evals and maintainer docs.
- Replaced with starter versions:
PROJECT.md,site.ts,site-url.mjs, the home page,robots.txt,llms.txt. - Kept: a minimal home page, the 404 page, all sections, layouts, scripts and skills; with
--keep-blogthe blog system with one draft post.
Afterwards, npm run verify -- --starter also fails on demo leftovers.
Verify
npm run verify runs every check in one go, offline and deterministic, and ends with VERIFY PASSED or a short list of what failed. If a step cannot run, it says so instead of passing.
| Step | Checks |
|---|---|
| format | Prettier |
| eslint | ESLint |
| astro-check | Types and templates (astro check) |
| lint-design | Design rules: tokens, links, forms, deprecated APIs |
| lint-docs | Dead paths, version and count drift in docs, skill front matter |
| registry | Registry matches component files, props, page templates and recipes |
| agents-sync | .claude/skills mirrors .agents/skills |
| test | Script tests (node --test) |
| build | Production build |
| dist | Built HTML: one h1, unique titles, meta descriptions, internal links, alt text |
npm run verify # everything
npm run verify -- --starter # + demo leftovers
npm run validate # without build (fast)
npm run lint:design # single checks
npm run lint:docs
npm run check:registryThe design rules behind lint:design (semantic color tokens only, every link and form pointing somewhere real, no ViewTransitions, ...) are shared with the optional Claude Code hook.
vibe2prod Audit
The vibe2prod skill (v0.9.2) ships in .agents/skills/vibe2prod/ (MIT, license included). It audits performance, accessibility, SEO, HTML, security, assets, robustness, AI-slop artifacts and responsiveness and returns a READY / NOT YET / BLOCKED verdict with a 0–100 score.
Run it
"Run the vibe2prod audit on this project."
Without a URL it builds the project and audits a local production server (local project mode). After your first deploy, run it again against the live URL. The build-site workflow runs it in step 7; agents apply technical fixes and propose content changes.
Install its tools once
npm run setup:audit -- --check # what is missing
npm run setup:audit # install itInstalls Lighthouse, the axe CLI, Playwright with Chromium and axe for Playwright (needs network). vibe2prod gives no verdict without its tools; it reports exactly which checks were skipped.
Supported Agents
AGENTS.md is the always-loaded index; the skills in .agents/skills/ hold the workflows. "Tested end to end" means the 4.0 workflow was run with the tool on the eval cases and ended with VERIFY PASSED and a vibe2prod READY verdict (Claude Code CLI 2.1.319, Codex CLI 0.155.1; in Codex's sandbox the browser audit cannot run, so it ran outside). "Documented" means the vendor's documentation says the tool reads these files; the workflow was not run with it.
| Agent | Reads AGENTS.md | Reads skills from | Status in 4.0 |
|---|---|---|---|
| Claude Code | via CLAUDE.md (@AGENTS.md import) | .claude/skills/ (mirror) | tested end to end |
| OpenAI Codex | natively | .agents/skills/ | tested end to end |
| Cursor | natively | .agents/skills/ | documented |
| GitHub Copilot | natively (+ .github/copilot-instructions.md pointer) | .agents/skills/, .claude/skills/ | documented |
| Gemini CLI | via .gemini/settings.json | .agents/skills/ | documented |
| Windsurf (Devin Local) | natively | .agents/skills/ | documented |
Claude Code only, optional: a read-only review subagent (astrodeck-reviewer) and a hook that blocks tailwind.config.*, ViewTransitions and z from astro:content. The workflow never needs them. .claude/skills/ is generated from .agents/skills/ by npm run sync:agents; edit the source. Details: docs/agents/supported-agents.md.
MCP Servers
Optional. .mcp.json declares two servers for Claude Code; other tools use their own config files with the same values.
- astro-docs — current Astro documentation over HTTP:
https://mcp.docs.astro.build/mcp - shadcn — shadcn/ui component search and install:
npx shadcn@latest mcp
Setup for Codex, Cursor and VS Code: docs/agents/mcp-setup.md.
codex mcp add astro-docs --url https://mcp.docs.astro.build/mcp
codex mcp add shadcn -- npx shadcn@latest mcpCursor reads .cursor/mcp.json; VS Code uses a top-level servers key instead of mcpServers.
Build & Deploy
AstroDeck builds static files that run on any static host.
npm run build # static site in dist/
npm run preview # serve the build locallySet SITE_URL in src/config/site-url.mjs first: canonical URLs, sitemap and RSS use it.
- Vercel, Netlify, Cloudflare Pages, GitHub Pages or your own server: deploy
dist/. vercel.jsonadds security headers on Vercel; on other hosts configure equivalent headers.features.analyticsloads Vercel Web Analytics; keep itfalseelsewhere.- After the first deploy, run vibe2prod against the live URL.
Astro 7 Notes
The details agents most often get wrong from older training data. The full list is in AGENTS.md.
- Agents start
npm run devin the background and poll/_astro/statusuntil it returns{"ok":true}. - The compiler is stricter: unclosed or misnested tags fail the build.
compressHTMLdefaults to'jsx': whitespace between elements is removed; write{" "}where a space matters.- Sätteri is the default Markdown processor; remark/rehype plugins need
unified()asmarkdown.processor. src/fetch.tsis reserved for Astro. No@astrojs/db.ClientRouter, neverViewTransitions;zfromastro/zod.- Tailwind 4 is configured in CSS (
@themeinglobals.css); there is notailwind.config.
Migrating from 3.x
4.0 changes section props, adds the site config and replaces the per-tool AI files with skills. The full list is in the changelog.
Brand, URL and navigation → site config
3.x
// hardcoded in Header.astro, Footer.astro, SEO.astro
const navItems = [{ href: '/', label: 'Home' }, ...];4.0
// src/config/site.ts
export const site: SiteConfig = { name, url: SITE_URL,
titleTemplate: '%s | Brand', nav: [...], footer: {...} };Hero and HeroGradient badge
3.x
<Hero badge="true" ... /> <!-- fixed version text -->
<HeroGradient badge="New in v2" ... />4.0
<Hero badge={{ label: 'New: online booking', href: '/news' }} ... />
<HeroGradient badge={{ label: 'New in v2', href: '/changelog' }} ... />LogoCloud
3.x
<LogoCloud /> <!-- built-in logos -->4.0
<LogoCloud title="Built with:" logos={[
{ name: 'Astro', src: '/icons/tech/astro.svg', href: 'https://astro.build' },
]} />AIFeature → IntegrationGrid
3.x
<AIFeature />4.0
<IntegrationGrid title="Works with your tools" items={[
{ name: 'GitHub', href: 'https://github.com', icon: 'code' },
]} />Contact form
3.x
<Contact email="..." /> <!-- always a form, no real endpoint -->4.0
<Contact email="..."
form={{ action: 'https://your-form-backend.example/submit' }} />
<!-- omit form for contact details only -->Newsletter
3.x
<Newsletter title="..." /> <!-- no real endpoint -->4.0
<Newsletter action="https://your-provider.example/subscribe" title="..." />ContentBlock image
3.x
<ContentBlock title="..." description="..." />
<!-- always showed an empty image box -->4.0
<ContentBlock title="..." description="..."
image={{ src: photo, alt: 'What the photo shows' }} />
<!-- without image: one text column -->AI files and commands → skills
3.x
.cursorrules, .windsurfrules, .cursor/rules
/new-page, /new-section, /theme, /audit, /launch-check, /plenum
npm run check:kpis4.0
AGENTS.md + .agents/skills/ (.claude/skills/ is generated)
astrodeck-new-page, -new-section, -theme, vibe2prod,
astrodeck-reviewer (Claude Code)
npm run verifyMultilingual Sites
Not part of 4.0.
The site config has one language (lang, locale). For several languages, add Astro's i18n routing on top. Built-in multilingual support is a candidate for a later release.
Project Structure
Where things live.
| AGENTS.md | Index for every coding agent: rules, commands, task → skill |
| PROJECT.md | Your site brief; overrides AGENTS.md |
| brief/ | Your input material |
| .agents/skills/ | Skills (source); .claude/skills/ is a generated mirror |
| src/config/site.ts | Brand, navigation, footer, SEO defaults, feature flags |
| src/styles/globals.css | Fonts and design tokens (@theme + .dark) |
| src/registry.json | Catalog of sections, layouts and UI components |
| src/components/sections/ | Page sections |
| src/components/ui/ | shadcn/ui React primitives |
| src/layouts/ | Base, FullWidth, Minimal, Auth, Article layouts |
| src/pages/ | File-based routes |
| src/content/blog/ | Blog posts (content collection) |
| scripts/, tests/ | Verify, theme, cleanup and sync scripts with tests |
| docs/agents/ | Supported agents and MCP setup |
Source code, README, issues and releases are on GitHub.
View on GitHub