Ce Polish Beta
Auto-detect Astro projects and standardize dev-server start commands, ports, and launch.json stubs for Compound Engineering polish workflows.
Overview
ce-polish-beta is an agent skill for the Build phase that defines Astro dev-server detection, start commands, port defaults, and launch.json stubs for Compound Engineering polish.
Install
npx skills add https://github.com/everyinc/compound-engineering-plugin --skill ce-polish-betaWhat is this skill?
- Detects Astro via astro.config and package.json `astro` dependency signature
- Resolves start command from lockfile-aware package manager (`npm`, `pnpm`, `yarn`, `bun`)
- Documents default port 4321 and config override cascade
- Generates example `.claude/launch.json` stub for Astro dev configuration
- Notes SSR versus SSG equivalence at dev time and Astro-over-Vite config precedence
- Default Astro dev port documented as 4321
- Lockfile-driven resolution across four package managers
Adoption & trust: 1k installs on skills.sh; 20.5k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your agent cannot reliably start an Astro dev server because lockfiles, ports, and missing launch.json vary across projects.
Who is it for?
Solo builders using Compound Engineering polish on Astro sites who lack a checked-in `.claude/launch.json`.
Skip if: Non-Astro frameworks, production build/deploy pipelines, or teams that already maintain a complete launch.json the detector should read instead.
When should I use this skill?
When `detect-project-type.sh` returns `astro` and there is no `.claude/launch.json` to consult.
What do I get? / Deliverables
You get lockfile-aware dev commands, port 4321 defaults with override notes, and a copy-paste launch stub so polish runs hit the right local URL.
- Resolved dev start command for the detected package manager
- Launch.json stub JSON for Astro dev on the configured port
Recommended Skills
Journey fit
Build is where solo builders run local frontends daily; this skill encodes Astro-specific dev-server conventions so polish agents do not guess wrong commands. Frontend subphase is the right shelf for Astro site and app dev loops, SSR/SSG aside, because the skill centers on `astro dev` and package-manager scripts.
How it compares
Framework-specific dev-server recipe inside a polish plugin—not a general Astro content or routing tutorial.
Common Questions / FAQ
Who is ce-polish-beta for?
It is for developers running Compound Engineering polish on Astro projects who want agents to start `astro dev` with the right package manager and port.
When should I use ce-polish-beta?
Use it in Build frontend work when detect-project-type returns Astro and you need standardized dev-server commands or launch.json generation before UI polish.
Is ce-polish-beta safe to install?
It suggests local dev commands only; review the Security Audits panel on this Prism page and confirm scripts in your own package.json before running.
SKILL.md
READMESKILL.md - Ce Polish Beta
# Astro dev-server recipe (auto-detect fallback) Loaded when `detect-project-type.sh` returns `astro` and there is no `.claude/launch.json` to consult. ## Signature - `astro.config.js`, `astro.config.mjs`, or `astro.config.ts` exists - `package.json` contains an `astro` dependency ## Start command Standard: ```bash npm run dev ``` The `dev` script in `package.json` typically wraps `astro dev`. Also valid (read `package.json` scripts to confirm which the project uses): ```bash pnpm dev yarn dev bun run dev ``` Prefer the package manager indicated by the lockfile: - `pnpm-lock.yaml` -> `pnpm dev` - `yarn.lock` -> `yarn dev` - `bun.lock` / `bun.lockb` -> `bun run dev` - `package-lock.json` or none -> `npm run dev` ## Port Default: `4321`. Astro respects `--port <port>` and the `server.port` field in `astro.config.*`. Overrides follow the cascade in `references/dev-server-detection.md`. ## Stub generation ```json { "version": "0.2.0", "configurations": [ { "name": "Astro dev", "runtimeExecutable": "npm", "runtimeArgs": ["run", "dev"], "port": 4321 } ] } ``` Substitute the resolved package manager (`npm` / `pnpm` / `yarn` / `bun`) and port. ## Common gotchas - **SSR vs SSG:** `astro dev` runs identically for both output modes; the difference only matters at build time. Polish does not need to distinguish between them. - **Astro config takes precedence over Vite config:** Astro uses Vite under the hood but ships its own config file. The `astro` type takes precedence over `vite` when both `astro.config.*` and `vite.config.*` exist. This is rare -- Astro projects do not usually have a separate Vite config file. - **Dev toolbar (Astro 4+):** Astro 4+ includes a dev toolbar that adds overlay UI in the browser. It does not affect port binding or URL routing -- polish can ignore it. # Dev-server port detection Port resolution runs via `scripts/resolve-port.sh`. This document explains the probe order, framework defaults, and intentional divergences from the `test-browser` skill's inline cascade. This cascade runs **only when** `.claude/launch.json` is absent or has no `port` field for the resolved configuration. When `launch.json` specifies a port, use it verbatim and skip this cascade entirely. ## Priority order 1. **Explicit `--port` flag** -- if the caller passed `--port <n>`, use it directly. 2. **Framework config files** -- `next.config.*`, `vite.config.*`, `nuxt.config.*`, `astro.config.*` scanned with a conservative regex matching only numeric literal port values. Variable references (`process.env.PORT`, `getPort()`) are deliberately not matched. 3. **Rails `config/puma.rb`** -- grep for `port <n>`. 4. **`Procfile.dev`** -- web line scanned for `-p <n>` / `--port <n>` / `-p=<n>` / `--port=<n>`. 5. **`docker-compose.yml`** -- line-anchored grep for `"<n>:<n>"` port mapping patterns. Not full YAML parsing. 6. **`package.json`** -- `dev`/`start` scripts scanned for `--port <n>` / `-p <n>` / `--port=<n>` / `-p=<n>`. 7. **`.env` files** -- checked in override order: `.env.local` -> `.env.development` -> `.env` (first hit wins). Parses `PORT=<n>` with quote stripping and comment truncation. 8. **Framework default lookup table** -- see table below. ## Framework defaults | Framework | Default port | |-----------|-------------| | Rails | 3000 | | Next.js | 3000 | | Nuxt | 3000 | | Remix (classic) | 3000 | | Vite | 5173 | | SvelteKit | 5173 | | Astro | 4321 | | Procfile | 3000 | | Unknown | 3000 | ## Sync-note block `resolve-port.sh` and the `test-browser` skill's inline cascade overlap in purpose but diverge in three specific ways. These divergences are intentional -- do not "fix" one to match the other without understanding the rationale. **(a) Quote stripping on `.env` values.** `resolve-port.sh` strips surrounding `"` and `'` from `PORT=` values (so `PORT="3001"` resolves to `3001`). The `test-browser` inline cascade does not strip quotes. The script version is more robust f