| name | spec-polish-beta |
| description | [BETA] Start the dev server, open the feature in a browser, and iterate on improvements together. |
| disable-model-invocation | true |
| argument-hint | [PR number, branch name, or blank for current branch] |
Polish
Start the dev server, open the feature in a browser, and iterate. You use the feature, say what feels off, and fixes happen.
Workflow Contract Summary
When To Use
Use when a browser-visible UI exists and the user explicitly wants an interactive polish loop on the current branch or a named PR/branch.
When Not To Use
Do not use for non-UI code, backend-only work, headless code review, production deployment, or when the current branch is main/master.
Inputs
Current branch or PR/branch argument, launch config or detected project type, package manager/port facts, dev-server command, browser URL, and user polish feedback.
Outputs
Applied UI polish changes, dev-server URL/status, browser observations when requested, and a final commit when the user says the polish pass is done.
Artifacts
Temporary dev-server log files and source changes in the target app; no durable spec-first audit artifact is promised.
Failure Modes
Unsafe branch, missing launch/start command, dependency/server startup failure, port conflict, unavailable browser helper, or user stops the loop.
Workflow
Resolve the branch, start the dev server, open or print the browser URL, iterate on user-visible feedback, verify hot reload or browser state, and commit when done.
Downstream Consumers
Human UI reviewers, spec-code-review, PR preparation, and product/design stakeholders checking the polished experience.
Scenario Capability
Follows docs/contracts/workflows/scenario-capability-matrix.md (default).
Overrides: none
Phase 0: Get on the right branch
- If a PR number or branch name was provided, check it out (probe for existing worktrees first).
- If blank, use the current branch.
- Verify the current branch is not main/master.
Phase 1: Start the dev server
Resolve all scripts/<name>.sh paths relative to this skill's loaded directory. The target app stays in the user's project checkout; only these helper scripts live beside the skill.
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:
| Type | Recipe |
|---|
rails | references/dev-server-rails.md |
next | references/dev-server-next.md |
vite | references/dev-server-vite.md |
nuxt | references/dev-server-nuxt.md |
astro | references/dev-server-astro.md |
remix | references/dev-server-remix.md |
sveltekit | references/dev-server-sveltekit.md |
procfile | references/dev-server-procfile.md |
unknown | Ask the user how to start the project |
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 supported host mechanism (Claude Code browser hint; Codex and terminal contexts print the URL).
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; if it is missing, tell them: "Browser automation helper unavailable. To install/repair, set SPEC_FIRST_BROWSER_HELPER_REQUIRED=1 and rerun spec-mcp-setup (or this host's MCP setup entrypoint). This does not block spec-first baseline." Continue the human browser loop when automated screenshots are unavailable.
- 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 stubsreferences/ide-detection.md — host IDE detection and browser-handoffreferences/dev-server-detection.md — port resolution documentationreferences/dev-server-rails.md — Rails dev-server defaultsreferences/dev-server-next.md — Next.js dev-server defaultsreferences/dev-server-vite.md — Vite dev-server defaultsreferences/dev-server-nuxt.md — Nuxt dev-server defaultsreferences/dev-server-astro.md — Astro dev-server defaultsreferences/dev-server-remix.md — Remix dev-server defaultsreferences/dev-server-sveltekit.md — SvelteKit dev-server defaultsreferences/dev-server-procfile.md — Procfile-based dev-server defaults
Scripts (invoked via bash scripts/<name>):
scripts/read-launch-json.sh — launch.json readerscripts/detect-project-type.sh — project-type classifierscripts/resolve-package-manager.sh — lockfile-based package-manager resolverscripts/resolve-port.sh — port resolution cascade
