browser-debugger-cli: Skill for Claude Code

Ship (bdg)

You are the orchestrator: you choose the issues, write the briefs, judge the reports, route the findings, and merge. You don't write feature code. Everything mechanical goes through the script, so your attention stays on judgment:

ship() { node "$(git rev-parse --show-toplevel)/.claude/skills/ship/scripts/ship.mjs" "$@"; }   # ship help

Call it only through this function: a command kept in a variable (S="node …"; $S brief …) is not split into words in zsh, and in S14 that wrote two empty briefs.

Each PR gets three independent looks before it lands, none of which sees the author's reasoning: tests written first that fail before the fix (the red commit), a fresh reviewer with the diff and the issue only, and a fresh-agent test in which a new agent uses the change as bdg's real users (coding agents) would. Skip none of them for behaviour changes.

Files:

• briefs.md: the four briefs and their shared blocks; render them with ship brief. Read before spawning any subagent.
• scenarios.md: fresh-agent test rounds, the report format, scenarios S01–S17, the exploratory sweep. Read before any fresh-agent test.
• log.md: one row per merged PR (ship log); the retro's data.
• scripts/ship.mjs: the commands below; its tests run in npm test.

Session start

• ship snapshot (gate 8 compares against it; it lives in ~/.cache/ship/, so a reboot keeps it). It and ship brief warn when the load average is above 50: find what is running before starting agents or Chromes (S27: the Mac rebooted mid-session). It also warns when the main checkout's node_modules don't match package-lock.json, as after dependabot merges (S16 #803: an implementer wrote a dead type extension against stale types); run npm ci there, not npm install, which rewrites the lockfile's libc fields. ship worktree warns the same way.
• Only verified issues go in. Verified means one command you have already run that shows the symptom on main: a bdg invocation on a fixture page or a real site, a test, or a script; deterministic, or for timing bugs reproducing at a rate you can debug against. Record the command and output on the issue; it becomes the red commit's first test. Behaviour that can't be run (dead code, a wrong doc) may be confirmed with file:line. Neither: verify first or ask.
• Themed sweep first. A session has a theme (one root cause or one area). One verifier (verifier brief, Sweep block filled in) re-runs every open issue of the theme on main and sweeps the theme's surfaces for symptoms the issues don't name. Issues it can't reproduce get a needs repro comment and drop out; new symptoms join an existing issue or an umbrella issue.
• A pick by the user (named issues, or a mix such as "one hard, two medium, two easy") replaces the theme: the verifier re-runs the picked issues' commands instead of a sweep, and the polish sweep PR is optional.
• Propose 4–6 issues, one line each on why; recommend one set, no menu. The proposal carries the plan per issue: tier, the acceptance criteria as the tests the red commit will hold, the 5–8 files to read first, open questions. The user's pick of the set is the go for the implementers; it is neither merge authority (its own yes/no below) nor an answer to a product decision. Show the balance: issues opened vs closed since the last session (from log.md and the tracker), and the target of at least two closed for each one filed. At least half of a wave's PRs close issues that predate the session; a feature-only session is the user's explicit choice.
• Polish sweep PR (themed sessions): one tier-1 PR, last in the session, one commit per wording nit of the queue: human-output text that no test asserts and no agent parses. A --json field, an asserted hint or --help --json text is tier 2, not a sweep item.
• Waves of at most 2 parallel implementers. Issues touching the same functions or output run in sequence. Two PRs that change different functions of one file may run in parallel; the one that merges second rebases before its gates (S14 #785 next to #782, S15 #799 next to #798: clean rebases, 1–2 h saved each). Light, conflict-free changes first; docs last.
• Ask for merge authority as a yes/no question: "May I merge on my own once the gates hold, or do you want to OK each PR?" A bare "OK" is not an answer. It doesn't carry over to the next session.
• Product decisions belong to the user: changed defaults, contracts, exit codes, removed --json fields. Options with a recommendation, then wait. A standing "pick the recommended option" never covers a contract change or a third fix round.