feat: Add /ce:polish skill for human-in-the-loop refinement before merge

Overview

Add a new workflow skill at plugins/compound-engineering/skills/ce-polish/SKILL.md that implements the "polish phase" — a human-in-the-loop refinement step that runs AFTER /ce:review (tests + review green) and BEFORE merge. Polish is the second of two human-in-the-loop moments in an otherwise-automated flow; the first is /ce:brainstorm (WHAT to build). Polish answers: does this feel right to a real user?

The skill accepts a PR number, URL, or branch name (blank → current branch), verifies that review has already completed successfully, merges latest main into the branch with the user's confirmation, starts a local dev server from a user-authored .claude/launch.json (with per-framework auto-detect as a fallback), opens the app in the host IDE's built-in browser when available (Claude Code desktop, Cursor, soon Codex) and falls back to printing the URL otherwise, generates an end-user-testable checklist from the diff and PR body, and dispatches polish sub-agents (design iterators, frontend race reviewers, simplicity reviewers) to fix issues the human flags. If the polish batch exceeds one "focus area" (more than one component, cross-cutting files, or cannot be tested as a single user flow), the skill refuses to batch-fix and emits a stacked-PR hand-off artifact.

Ship as ce:polish-beta first per the beta-skills framework; promote to stable after usage feedback.

Problem Frame

The compound-engineering plugin automates most of the development flow end-to-end (/ce:ideate → /ce:brainstorm → /ce:plan → /ce:work → /ce:review). Today there is no structured step between a green review and merge. Two gaps result:

1. Craft/UX is never experienced as an end user. Review catches correctness, security, and structural issues. It does not catch "this animation is janky," "the empty state is ugly," or "this response feels slow." A human has to use the feature to notice those.
2. Polish work accidentally becomes scope creep. When a human does sit down to polish, it's easy to keep adding to the same PR until it's too large to understand or review again — and the polish never ships cleanly.

Polish needs its own shaped step: bounded, human-driven, but automation-assisted for the fixes themselves. It also needs an explicit size gate so polish tasks that outgrow the PR get split into stacked PRs rather than bloating the original.

The transcript that motivated this plan frames polish as "the second human-in-the-loop moment" — deliberately paired with brainstorm on either end of an automated middle.

Requirements Trace

From the feature description (10 deliverables):

• R1. Command lives as a skill at plugins/compound-engineering/skills/ce-polish-beta/SKILL.md with frontmatter name, description, argument-hint, disable-model-invocation: true — matching the canonical ce:review / ce:work / ce:brainstorm shape under the beta-first convention (promoted to skills/ce-polish/ in a follow-up PR).
• R2. Skill SKILL.md structured for progressive disclosure: body under ~500 lines, per-framework dev-server recipes and checklist/dispatch templates extracted to references/, deterministic classifiers in scripts/.
• R3. $ARGUMENTS parses PR number, PR URL, branch name, or blank → current branch, plus named tokens that strip before the target is interpreted: mode:headless (machine envelope for LFG/pipelines) and trust-fork:1 (explicit fork-PR trust override). Additional tokens (mode:report-only, mode:autonomous) are deferred to follow-up PRs so the surface stays honest about what's actually implemented.
• R4. Dev-server lifecycle is config-driven with auto-detect fallback. Primary source is .claude/launch.json at the repo root (Claude Code's launch-config convention); when absent or incomplete, fall back to per-framework auto-detection (Rails / Next.js / Vite / Procfile / Overmind) and offer to write a minimal launch.json stub the user can confirm and save for future runs. Kill and restart surface the PID and log path so the user can reclaim control.
• R4b. When running inside an IDE with an embedded browser (Claude Code desktop, Cursor, future Codex), open the polish URL in that browser; otherwise print the URL for the user to open manually. Detection is best-effort and non-blocking — failure to detect the IDE always falls through to printing the URL.
• R5. Skill refuses to polish untested or unreviewed work, based on two signals: the latest .context/compound-engineering/ce-review/<run-id>/ artifact's verdict, plus gh pr checks green.
• R6. Test checklist is generated from the diff, PR body, and (if available) the plan referenced via plan:<path> — never by asking the human "what would you like to test?".
• R7. Polish sub-agents are dispatched via fully qualified names (compound-engineering:design:design-iterator, compound-engineering:review:julik-frontend-races-reviewer, etc.). Dispatch is sequential below 5 items, parallel above — with the invariant that items touching the same file path never run concurrently.
• R8. A "too big" detector operates on two tiers. Per-item: items exceeding file-count, cross-surface, or diff-line thresholds are refused and routed to a stacked-PR hand-off artifact. Per-batch: when the overall polish run shows the PR as a whole is too large (majority-oversized items, repeated replan actions from the user, or a preemptive diff-size probe before checklist generation), polish escalates to re-planning — writes a replan-seed.md pointing back to the originating brainstorm/plan and routes the user to /ce:plan or /ce:brainstorm. The size gate at both tiers is load-bearing, not decoration.
• R9. /ce:polish slots between /ce:review and /git-commit-push-pr in the workflow. /ce:work Phase 3 offers polish as a next step after /ce:review completes. mode:headless variant exists so LFG and future pipelines can chain it.
• R10. Feature branch for this work: feat/ce-polish-command. No release-owned versions bumped in the PR.

Scope Boundaries

In scope:

• New beta skill skills/ce-polish-beta/ (promoted to skills/ce-polish/ in a follow-up PR per the beta-skills framework)
• .claude/launch.json reader + auto-detect fallback + stub-writer; per-framework dev-server recipes (Rails, Next.js/Node, Vite, Procfile/Overmind) as the fallback path
• IDE detection (Claude Code, Cursor, future Codex) for embedded-browser handoff; progressive enhancement, never a gate
• Edit-file-then-ack human interaction loop via .context/compound-engineering/ce-polish/<run-id>/checklist.md
• Two-tier size gate: per-item (stacked-PR seed) and per-batch (replan escalation back to /ce:plan or /ce:brainstorm)
• Fork-PR trust boundary check at the entry gate (requires trust-fork:1 token for cross-repository PRs)
• Reuse of resolve-base.sh (duplicated into the new skill's references/, per the "no cross-directory references" rule)
• Sub-agent orchestration of existing design and review agents — no new agents created in this PR
• README.md component count update (author edit, not release-owned)

Out of scope:

• Creating a new "copy/microcopy polish" sub-agent — out of scope; surfaced as a future consideration. Copy polish folds into the design-iterator loop for v1.
• Modifying /ce:work or /ce:review to automatically chain into /ce:polish. The first release is manually invoked after /ce:review. Automatic chaining belongs in a follow-up PR once beta usage proves the shape.
• Version bumps in plugins/compound-engineering/.claude-plugin/plugin.json or .claude-plugin/marketplace.json, or manual CHANGELOG.md entries — release-please automation owns these (per plugins/compound-engineering/AGENTS.md).
• Adding a web UI / browser-extension annotation layer for polish note-taking. The transcript mentions annotating in the browser; in v1, notes are captured as plain prose input to the skill, which then dispatches fixes. Browser-side annotation is a follow-up.

Context & Research

Relevant Code and Patterns

• Skill-as-slash-command pattern: Since v2.39.0, former /command-name slash commands live under plugins/compound-engineering/skills/<command-name>/SKILL.md (see plugins/compound-engineering/AGENTS.md). No commands/ directory exists. Polish follows this pattern.
• Argument parsing (token-based): plugins/compound-engineering/skills/ce-review/SKILL.md:19-33 defines the canonical mode:*, base:*, plan:* token-stripping pattern. Polish adopts it verbatim for future extensibility.
• Frontmatter for interactively-invocable workflow skills: plugins/compound-engineering/skills/ce-review/SKILL.md:1-5 and plugins/compound-engineering/skills/ce-work/SKILL.md:1-5 — name: ce:<verb>, description with natural-language trigger phrases, argument-hint, no disable-model-invocation for stable workflow skills.
• Beta-first convention: plugins/compound-engineering/skills/ce-work-beta/ shows the beta pattern. Frontmatter: name: ce:<verb>-beta, description prefixed [BETA], disable-model-invocation: true. Convention documented in docs/solutions/skill-design/beta-skills-framework.md.
• Branch / PR acquisition: plugins/compound-engineering/skills/ce-review/SKILL.md:184-267 — clean-worktree check via git status --porcelain, then gh pr checkout <n> for PRs, git checkout <branch> for branches, shared resolve-base.sh helper for base-branch resolution.
• Port detection cascade: plugins/compound-engineering/skills/test-browser/SKILL.md:97-143 — CLI flag → AGENTS.md/CLAUDE.md → package.json dev-script → .env* → default 3000. Polish reuses this cascade as-is.
• Review artifact location and envelope: plugins/compound-engineering/skills/ce-review/SKILL.md:509-516 (headless envelope exposes Artifact: .context/compound-engineering/ce-review/<run-id>/) and SKILL.md:675-680 (what's written). Polish reads this to gate entry.
• Scratch space convention: .context/compound-engineering/<workflow>/<run-id>/ with RUN_ID=$(date +%Y%m%d-%H%M%S)-$(head -c4 /dev/urandom | od -An -tx1 | tr -d ' '). Used by ce-review, ce-optimize, ce-plan-deepening.
• Sub-agent dispatch: plugins/compound-engineering/skills/resolve-pr-feedback/SKILL.md:135-164 is the canonical parallel-dispatch pattern. plugins/compound-engineering/skills/ce-review/references/subagent-template.md is the canonical sub-agent prompt shape. Fully qualified names mandatory; omit mode on tool calls to honor user permission settings.
• Polish-relevant existing agents: agents/design/design-iterator.md, agents/design/design-implementation-reviewer.md, agents/design/figma-design-sync.md, agents/review/code-simplicity-reviewer.md, agents/review/maintainability-reviewer.md, agents/review/julik-frontend-races-reviewer.md. All referenced via fully qualified compound-engineering:<category>:<name>.
• Complexity / focus-area heuristic: plugins/compound-engineering/skills/ce-work/SKILL.md:36-42 (Trivial / Small / Large matrix) and plugins/compound-engineering/skills/ce-work/references/shipping-workflow.md:25-30, 108-112 (Tier 1 single-concern criteria). Polish's "too big" detector extends these.
• Mode detection and headless envelope: plugins/compound-engineering/skills/ce-review/SKILL.md:36-72 — the mode table, the headless rules, and the terminal Review complete signal. Polish mirrors this shape with Polish complete.

Institutional Learnings

• docs/solutions/skill-design/git-workflow-skills-need-explicit-state-machines-2026-03-27.md — Branch/PR-switching skills must be modeled as explicit state machines and re-probe at each transition. Polish re-reads git branch --show-current, server PID, and PR number after every checkout or kill. Never carries earlier values forward in prose.
• docs/solutions/skill-design/compound-refresh-skill-improvements.md — Question-before-evidence is an anti-pattern. Polish generates the test checklist before asking the human what to test; the human edits the generated list rather than authoring it from scratch. All confirmations include concrete command/port/PID so the human can judge without a follow-up.
• docs/solutions/skill-design/pass-paths-not-content-to-subagents-2026-03-26.md — Orchestrator hands paths to sub-agents; sub-agents do their own reads. Polish passes the diff file list, the review artifact path, and the PR number — never inlined diff content.
• docs/solutions/best-practices/codex-delegation-best-practices-2026-04-01.md — ~5-7 unit crossover for parallel dispatch; "never split units that share files." Polish goes sequential below 5 items, parallel above, with the same-file collision guard.
• docs/solutions/skill-design/script-first-skill-architecture.md — Deterministic classification (project-type, file-to-surface mapping, oversize detection) belongs in bundled scripts, not the model. 60-75% token reduction.
• docs/solutions/workflow/todo-status-lifecycle.md — Status fields only have value when a downstream consumer branches on them. Polish's status: {manageable | oversized} per-item field is load-bearing — the dispatcher branches on it (manageable → fix, oversized → stacked-PR seed).
• docs/solutions/developer-experience/branch-based-plugin-install-and-testing-2026-03-26.md — Shared checkout can't serve two branches. If the user is already on a worktree for the target PR, attach; do not silently re-checkout the primary.
• docs/solutions/skill-design/beta-skills-framework.md + .../ce-work-beta-promotion-checklist-2026-03-31.md — New workflow skills ship first as -beta with disable-model-invocation: true. Promotion later requires updating every caller in the same PR.

External References

None required. Repo patterns and institutional learnings cover every decision; no external framework behavior is in dispute. (For cross-platform "kill process by port," lsof -i :$PORT -t | xargs -r kill is portable across macOS/Linux; documented inline in the dev-server reference file.)

Key Technical Decisions

• Ship as beta first (skills/ce-polish-beta/, name: ce:polish-beta). Polish is a new human-in-the-loop workflow skill with multiple novel patterns (dev-server lifecycle, CI-check verification, checklist generation, stacked-PR hand-off). Per beta-skills-framework.md, new workflow skills ship beta first with disable-model-invocation: true. Promote to ce:polish in a follow-up PR once real usage validates the shape. Rationale: every novel pattern listed below could miss on first design; beta contains blast radius and signals "this shape is not final yet."
• **Follow ce:review's token-based argument parsing