Ce Polish

Polish

Start the dev server, open the feature in a browser, and iterate. You use the feature, say what feels off, and fixes happen.

Phase 0: Get on the right branch

1. If a PR number or branch name was provided, check it out (probe for existing worktrees first). 2. If blank, use the current branch. 3. Verify the current branch is not main/master.

Phase 1: Start the dev server

1.1 Check for .claude/launch.json

Run bash scripts/read-launch-json.sh. If it finds a configuration, use it — the user already told us how to start the project.

1.2 Auto-detect (when no launch.json)

Run bash scripts/detect-project-type.sh to identify the framework.

Route by type to the matching recipe reference for start command and port defaults:

For framework types that need a package manager, run bash scripts/resolve-package-manager.sh and substitute the result into the start command.

Resolve the port with bash scripts/resolve-port.sh --type <type>.

1.3 Start the server

Start the dev server in the background, log output to a temp file. Probe http://localhost:<port> for up to 30 seconds. If it doesn't come up, show the last 20 lines of the log and ask the user what to do.

1.4 Open in browser

Load references/ide-detection.md for the env-var probe table. Open the browser using the IDE's mechanism (Claude Code → open, Cursor → Cursor browser, VS Code → Simple Browser).

Tell the user:

Dev server running on http://localhost:<port>
Browse the feature and tell me what could be better.

Phase 2: Iterate

This is the core loop. The user browses the feature and tells you what to improve. You fix it. Repeat until they're happy.

• When the user describes something to fix → make the change, the dev server hot-reloads
• When the user asks to check something → use agent-browser to screenshot or inspect the page
• When the user says they're done → commit the fixes and stop

No checklist. No envelope. Just conversation.

References

Reference files (loaded on demand):

• references/launch-json-schema.md — launch.json schema + per-framework stubs
• references/ide-detection.md — host IDE detection and browser-handoff
• references/dev-server-detection.md — port resolution documentation
• references/dev-server-rails.md — Rails dev-server defaults
• references/dev-server-next.md — Next.js dev-server defaults
• references/dev-server-vite.md — Vite dev-server defaults
• references/dev-server-nuxt.md — Nuxt dev-server defaults
• references/dev-server-astro.md — Astro dev-server defaults
• references/dev-server-remix.md — Remix dev-server defaults
• references/dev-server-sveltekit.md — SvelteKit dev-server defaults
• references/dev-server-procfile.md — Procfile-based dev-server defaults

Scripts (invoked via bash scripts/<name>):

• scripts/read-launch-json.sh — launch.json reader
• scripts/detect-project-type.sh — project-type classifier
• scripts/resolve-package-manager.sh — lockfile-based package-manager resolver
• scripts/resolve-port.sh — port resolution cascade

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:

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):

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

{
  "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

Sync-note block

resolve-port.sh and the test-browser skill's inline cascade overlap in purpose but diverge in two specific ways (a, b) and share one deliberate omission (c). These choices 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 for real-world .env files where quoting is common.

(b) Comment stripping on `.env` values. resolve-port.sh truncates at # after trimming whitespace (so PORT=3001 # dev only resolves to 3001). The test-browser inline cascade does not strip comments. Same rationale: real .env files frequently contain inline comments.

(c) No instruction-file port grep (shared). Neither resolve-port.sh nor the test-browser inline cascade greps AGENTS.md/CLAUDE.md for port references. Instruction files carry natural language that may mention ports in contexts unrelated to the dev server (documentation, examples, troubleshooting), producing false positives that are hard to debug; the filename is also harness-specific. Framework config files and .env are the reliable sources of truth. A skill may still honor a dev-server port the agent reads from its in-context project instructions, but it does not shell-grep named instruction files.

Next.js dev-server recipe (auto-detect fallback)

Loaded when detect-project-type.sh returns next and there is no .claude/launch.json to consult.

Signature

• next.config.js, next.config.mjs, next.config.ts, or next.config.cjs exists
• package.json contains a next dependency

Start command

Standard:

npm run dev

Also valid (read package.json scripts to confirm which the project uses):

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: 3000. Next.js respects -p <port> / --port <port> and the PORT env var. Overrides follow the cascade in references/dev-server-detection.md.

Turbopack

Next.js 14+ supports --turbo (and 15+ makes it default). If the dev script in package.json includes --turbo, preserve it. Turbopack changes reload behavior but not port or URL conventions.

Stub generation

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next dev",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 3000
    }
  ]
}

Substitute the resolved package manager (npm / pnpm / yarn / bun) and port.

Common gotchas

• App Router vs Pages Router: dev-server behavior is the same; polish doesn't care. Checklist generation (Unit 5) does — pages in app/ and pages/ are different surfaces.
• Monorepo roots: in a pnpm/Turborepo monorepo, npm run dev at the root typically fans out to multiple packages. Users should set cwd in .claude/launch.json to the specific Next app (cwd: "apps/web").
• Env loading: .env.local is loaded automatically by Next; polish does not need to export it.

Nuxt dev-server recipe (auto-detect fallback)

Loaded when detect-project-type.sh returns nuxt and there is no .claude/launch.json to consult.

Signature

• nuxt.config.js, nuxt.config.mjs, or nuxt.config.ts exists
• package.json contains a nuxt dependency

Start command

Standard:

npm run dev

Also valid (read package.json scripts to confirm which the project uses):

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: 3000. Nuxt respects --port <port> and the PORT env var. Overrides follow the cascade in references/dev-server-detection.md.

Stub generation

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Nuxt dev",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 3000
    }
  ]
}

Substitute the resolved package manager (npm / pnpm / yarn / bun) and port.

Common gotchas

• Nitro server engine: Nitro (Nuxt's server engine) adds its own dev server behind Nuxt's; polish only cares about the Nuxt port. Do not probe the Nitro internal port separately.
• Port auto-increment: Nuxt auto-increments the port if 3000 is already taken (unlike Next.js which errors). Polish's kill-by-port step handles this by reclaiming the port before starting, so the auto-increment behavior does not cause issues in practice.
• Nuxt 3 vs Nuxt 2: Nuxt 3 uses nuxt.config.ts, Nuxt 2 uses nuxt.config.js -- both are detected by the signature check. The dev-server command and port defaults are the same across both versions.

Procfile / Overmind dev-server recipe (auto-detect fallback)

Loaded when detect-project-type.sh returns procfile and there is no .claude/launch.json to consult. Rails apps with bin/dev take precedence over the bare Procfile path (see dev-server-rails.md).

Signature

• Procfile or Procfile.dev exists at the repo root
• bin/dev is not present (if it is, use the Rails recipe)

Start command

Prefer overmind when available — it handles socket files, supports hot-restart per process, and is the community default for multi-process dev:

overmind start -f Procfile.dev

Fallback to foreman when overmind is not installed:

foreman start -f Procfile.dev

If both are missing, prompt the user for the start command rather than guessing.

Port

Default: 3000. Procfile-based projects list their processes in Procfile.dev, so the authoritative port comes from the web: line:

web: bundle exec puma -p 3000 -C config/puma.rb
worker: bundle exec sidekiq

Parse the web: line for -p <n> or --port <n>. If neither is present, fall through to the cascade in references/dev-server-detection.md.

Stub generation

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Overmind dev",
      "runtimeExecutable": "overmind",
      "runtimeArgs": ["start", "-f", "Procfile.dev"],
      "port": 3000
    }
  ]
}

Substitute foreman if overmind is unavailable on the user's machine — the stub represents what the user will run, not a canonical recipe.

Common gotchas

• Socket files: overmind writes a socket to .overmind.sock by default. Polish's kill-by-port logic reclaims the port but does not clean up the socket. If overmind is already running and polish restarts it, the new process may fail with "connection refused" until the stale socket is removed. The OVERMIND_SOCKET env var can redirect the socket to a per-run path if needed.
• Procfile vs Procfile.dev: production and development Procfiles often differ. Always prefer Procfile.dev for polish.
• Multiple web processes: some Procfiles split web traffic across multiple processes (API + frontend). Polish can only open one URL — users with multi-web setups should author .claude/launch.json explicitly to select which process is "the dev server" for polish.

Rails dev-server recipe (auto-detect fallback)

Loaded when detect-project-type.sh returns rails and there is no .claude/launch.json to consult.

Signature

• bin/dev exists and is executable
• Gemfile exists

Start command

bin/dev

bin/dev is the Rails 7+ convention for "start everything" (web + assets watcher + optional workers). It is a one-liner script that invokes foreman start -f Procfile.dev under the hood, so Procfile.dev is the canonical place to read the actual command if bin/dev is missing or non-executable.

Port

Default: 3000. Overrides follow the cascade in references/dev-server-detection.md: 1. Procfile.dev web: line may contain -p <n> 2. config/puma.rb may bind to a non-default port 3. .env / .env.development PORT=<n> 4. a dev-server port explicitly stated in the project's active instructions in context (not grepped from instruction files)

Stub generation for .claude/launch.json

When the user accepts "Save this as .claude/launch.json?", emit the Rails stub from launch-json-schema.md:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Rails dev",
      "runtimeExecutable": "bin/dev",
      "runtimeArgs": [],
      "port": 3000
    }
  ]
}

If the cascade resolved a non-3000 port, substitute it in the stub's port field before writing.

Common gotchas

• Bundler path: some machines require bundle exec bin/dev. If bin/dev fails with a load-path error, fall back to bundle exec bin/dev.
• Foreman vs overmind: Procfile vs Procfile.dev often both exist. Rails' bin/dev resolves to Procfile.dev; if the project uses overmind explicitly, prefer overmind start -f Procfile.dev (see dev-server-procfile.md).
• SSL dev server: rails s with --ssl changes the URL scheme. Polish's reachability probe uses http://; users with SSL dev servers should set port explicitly in .claude/launch.json and note the scheme in the checklist.

Remix dev-server recipe (auto-detect fallback)

Loaded when detect-project-type.sh returns remix and there is no .claude/launch.json to consult.

Signature

• remix.config.js or remix.config.ts exists (classic Remix)
• Remix 2.x+ on Vite has no remix.config.* -- it uses vite.config.ts with the Remix plugin, so it resolves as vite type, not remix

Start command

Standard:

npm run dev

The dev script in package.json typically wraps remix dev. Also valid (read package.json scripts to confirm which the project uses):

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: 3000. Remix respects --port <port> flag. Classic Remix dev server also reads the PORT env var. Overrides follow the cascade in references/dev-server-detection.md.

Stub generation

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Remix dev",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 3000
    }
  ]
}

Substitute the resolved package manager (npm / pnpm / yarn / bun) and port.

Common gotchas

• Classic vs Vite: Classic Remix uses remix.config.js; new Remix (v2+) uses Vite -- detected as vite type, not remix. The remix type is specifically for classic Remix projects that still have a remix.config.* file.
• Remix v1 vs v2 dev server: remix dev in v2 starts an Express-based dev server that binds a port; remix dev in v1 was a watcher only (no server). Polish needs v2+ for the dev server to bind a port and respond to reachability probes.
• Remix on Vite inherits Vite's port: When Remix runs on Vite (no remix.config.*), the default port is 5173 (Vite's default), not 3000. That case is handled by the vite recipe, not this one.

SvelteKit dev-server recipe (auto-detect fallback)

Loaded when detect-project-type.sh returns sveltekit and there is no .claude/launch.json to consult.

Signature

• svelte.config.js, svelte.config.mjs, or svelte.config.ts exists
• package.json contains a @sveltejs/kit dependency

Start command

Standard:

npm run dev

The dev script in package.json typically wraps vite dev via SvelteKit. Also valid (read package.json scripts to confirm which the project uses):

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: 5173 (inherited from Vite). SvelteKit respects --port <port> flag and Vite's server.port config in vite.config.ts. Overrides follow the cascade in references/dev-server-detection.md.

Stub generation

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "SvelteKit dev",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 5173
    }
  ]
}

Substitute the resolved package manager (npm / pnpm / yarn / bun) and port.

Common gotchas

• Vite under the hood: SvelteKit uses Vite internally -- same port default (5173), same HMR behavior. The sveltekit type exists because svelte.config.js is a more precise signal than a generic vite.config.ts, allowing polish to generate a SvelteKit-specific stub name and label.
• Adapter does not matter for dev: adapter-auto, adapter-node, adapter-static, and other adapters all produce the same dev server. The adapter only affects the production build output.
• `svelte.config.js` is the primary signature: svelte.config.js always exists in SvelteKit projects, even when vite.config.ts also exists. This is the file that distinguishes a SvelteKit project from a plain Vite project.

Vite dev-server recipe (auto-detect fallback)

Loaded when detect-project-type.sh returns vite and there is no .claude/launch.json to consult.

Signature

• vite.config.js, vite.config.ts, vite.config.mjs, or vite.config.cjs exists

Start command

Standard:

npm run dev

The dev script in package.json typically wraps vite directly. Prefer the package manager indicated by the lockfile (see the Next.js recipe for the lockfile → command mapping).

Port

Default: 5173. Vite respects --port <n> and the VITE_PORT env var. The cascade in references/dev-server-detection.md picks up --port from package.json scripts and PORT from .env*.

Vite's --strictPort flag causes the dev server to fail rather than increment to the next available port when the requested port is in use. Polish's kill-by-port step will reclaim the port before starting, so strictPort is not a problem in practice — but users who disable port reclamation and run multiple Vite instances will see the port auto-increment unless strictPort: true is set in vite.config.ts.

Host binding

Vite binds to 127.0.0.1 by default. For polish running inside a devcontainer or WSL, users may need --host 0.0.0.0 in runtimeArgs. The checklist can note this if relevant to the diff.

Stub generation

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Vite dev",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 5173
    }
  ]
}

Common gotchas

• HMR websocket port: Vite's HMR uses a separate websocket that inherits the dev-server port by default. If the project pins server.hmr.port in vite.config.ts, the polish reachability probe against the dev-server port still works, but the embedded browser may need additional configuration to reach HMR.
• Framework on top of Vite: SvelteKit, SolidStart, Qwik City, and Astro all use Vite but add their own dev scripts. The vite signature catches them, and npm run dev is the right command for all of them. Different default ports apply (SvelteKit: 5173, Astro: 4321, Qwik: 5173) — rely on the cascade to pick up the actual port from package.json or .env.

IDE detection for browser handoff

Polish attempts to hand the running dev-server URL off to an IDE's embedded browser so the user can test without a context switch. Detection is best-effort — failure falls through to printing the URL in the interactive summary.

Detection order

Probe environment variables in this order and stop at the first positive match. Earlier entries are more specific; later entries are general fallbacks.

Why env-var probe, not a fancier approach

• Env vars are cross-platform (macOS, Linux, Windows/WSL)
• They fail open — if a probe returns nothing, polish still works
• They don't require any IDE API or socket connection
• They encode "is this shell running inside a known IDE" without guessing

Codex and other platforms

Codex (Claude Agent SDK, Antigravity CLI (agy), etc.) do not yet expose an embedded-browser handoff. For these platforms, polish falls through to the terminal branch (print the URL). When a convention emerges, add a new row to the detection table above.

Detection failure is never fatal

If environment probing fails or returns ambiguous results, polish prints the URL verbatim and continues. The dev server is already running by this point — the user can always copy-paste the URL into any browser. The IDE handoff is a convenience, not a gate.

Probe pattern (reference)

The skill consumes these probes inline rather than via a shell script (no state, no parsing, one-shot reads). Typical usage:

if [ -n "${CLAUDE_CODE:-}" ]; then
  IDE="claude-code"
elif [ -n "${CURSOR_TRACE_ID:-}" ]; then
  IDE="cursor"
elif [ "${TERM_PROGRAM:-}" = "vscode" ]; then
  IDE="vscode"
else
  IDE="none"
fi

Never chain probes with || between different variables — a missing env var must resolve to "no signal", not "error". The ${VAR:-} default-to-empty pattern is mandatory under set -u.

.claude/launch.json schema

Polish reads .claude/launch.json at the repo root to resolve the dev-server start command. The schema is a subset of VS Code's launch.json format — chosen because Claude Code, Cursor, and VS Code all understand it and because users often already have one for editor integration.

Top-level shape

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "<human label>",
      "runtimeExecutable": "<binary>",
      "runtimeArgs": ["<arg>", "<arg>"],
      "port": <number>,
      "cwd": "<optional, repo-relative>",
      "env": { "<key>": "<value>" }
    }
  ]
}

Fields polish consumes

Stub template (written on first run when user accepts)

When polish auto-detects a project type and the user confirms "Save this as .claude/launch.json?", polish writes a minimal stub derived from the detected type. These templates intentionally hard-code common defaults — users can edit them later.

Rails stub

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Rails dev",
      "runtimeExecutable": "bin/dev",
      "runtimeArgs": [],
      "port": 3000
    }
  ]
}

Next.js stub

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next dev",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 3000
    }
  ]
}

Vite stub

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Vite dev",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 5173
    }
  ]
}

Procfile / Overmind stub

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Overmind dev",
      "runtimeExecutable": "overmind",
      "runtimeArgs": ["start", "-f", "Procfile.dev"],
      "port": 3000
    }
  ]
}

Nuxt stub

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Nuxt dev",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 3000
    }
  ]
}

Astro stub

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Astro dev",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 4321
    }
  ]
}

Remix stub

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Remix dev",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 3000
    }
  ]
}

SvelteKit stub

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "SvelteKit dev",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 5173
    }
  ]
}

Why a subset of VS Code's schema

Polish does not use type, request, console, stopOnEntry, or any of the other VS Code fields. Including them is harmless — polish ignores them — but the stub writer never adds them. The fields polish cares about are the ones that describe how to start a long-running dev server on a known port, which is a smaller surface than what VS Code uses for debug-stepping.

Cross-IDE notes

.claude/launch.json is not yet a fully unified standard across Claude Code, Cursor, VS Code, and Codex. Polish leads with .claude/launch.json because:

• Claude Code, Cursor, and VS Code can all read it as a launch config
• It sits at a clean repo-root trust boundary (user-authored, not auto-detected)
• Users who prefer .vscode/launch.json can symlink or mirror the two files manually

If a cross-IDE standard emerges (e.g., .workspace/launch.json), the stub writer and reader can swap paths without touching the rest of the skill.