Spec: route browser debugging to the chrome-devtools CLI

Find the control-ui skill, the perf-issue and runtime-forensics playbooks, the diagnosing-bugs feedback-loops reference, go-help, and any doctor checks. Start by reading their current tool routing and verify the listed Chrome DevTools CLI and MCP capabilities against current docs. Update the named skill text and fallback paths, then validate each changed skill and build; run the perf-issue playbook with and without the CLI to confirm the CDP fallback.

Problem

An agent working on a web app has one browser skill in gstack, control-ui, and that skill does two jobs. It drives the browser to prove a change works, and it debugs the browser to find out why something is wrong. For both jobs it tells the agent to write its own script on the playwright library or on raw CDP. The perf-issue and runtime-forensics playbooks send the agent to "the matching control skill", so every perf trace, heap snapshot, or network log starts with hand-written CDP code.

Chrome's own DevTools tooling already does that work. It records performance traces with named insights for LCP, INP, and CLS. It takes V8 heap snapshots, lists network requests and console messages, and can connect to the user's signed-in Chrome. gstack never sends the agent to it, so the agent rebuilds a weaker version of it each time.

Solution

gstack picks the browser tool by what the agent is doing. To prove a change, the agent drives the browser with Playwright. To find out why something is wrong, the agent debugs it with the chrome-devtools CLI, or with Chrome DevTools MCP when the CLI lacks a tool it needs. control-ui stays one skill. It routes to these tools first and keeps its hand-written harness for surfaces they cannot reach, such as Electron and IDEs.

When a bug needs the user's sign-in, the user hands their Chrome to the agent. The agent then reads what it needs and asks before it changes anything.

User stories

1. As an agent proving a change, I want control-ui to send me to the project's Playwright test runner or @playwright/cli, so that proof runs on the same tool as the project's tests.
2. As an agent diagnosing a slow page load or a slow interaction, I want to record a performance trace with the chrome-devtools CLI and read its insights, so that the cause comes from the trace and not from reading source.
3. As an agent hunting a memory leak, I want to compare heap snapshots taken before and after the suspect flow, so that I find the objects that stay in memory.
4. As an agent debugging a running page, I want to read its network requests and console messages and run a script on the live page to test a hypothesis, so that I prove the mechanism before I believe it.
5. As a user debugging a bug that needs sign-in, I want to start the handoff myself by enabling remote debugging in my Chrome and asking the agent to take over, so that the agent never connects to my real session on its own.
6. As a user who handed over my Chrome, I want the agent to read freely but ask before any action that changes data, such as submitting a form or clicking a button that writes, so that debugging never changes real data without my say.
7. As a user who handed over my Chrome, I want the agent to save no heap snapshot or network log without my consent, and to redact auth headers in what it shows, so that my credentials stay out of files and replies.
8. As an agent without the chrome-devtools CLI or MCP, or working on Electron or an IDE, I want to fall back to control-ui's CDP harness, so that the playbooks still work.
9. As an agent, I want to know that the Lighthouse audit covers accessibility, SEO, and best practices but not performance, so that I use a trace to measure performance.
10. As a repo owner, I want the debugging tools used only when a debugging task needs them, so that they cost no context the rest of the time.

Implementation decisions

• Tool order for debugging. The chrome-devtools CLI and its bundled skill come first. Chrome DevTools MCP is the fallback for a tool the CLI lacks. control-ui's CDP harness is the last resort.
• control-ui stays one skill. A new opening section picks the tool by the verb: drive to prove, debug to diagnose. The section gives the order above for each verb. The existing CDP harness and the CDP capabilities list are marked as the fallback. The skill description says it routes.
• Perf-issue playbook, step 1. On a web surface, capture the baseline as a chrome-devtools performance trace. On other surfaces, use the matching control skill as today.
• Runtime-forensics playbook, steps 1 and 3. Name the debugging tool for each signal: a trace for a visual glitch or slow interaction, a heap snapshot for a leak, network requests and console messages for a failing call. Step 3 tests a hypothesis by running a script on the live page.
• Diagnosing-bugs feedback-loops reference. The headless-browser option names Playwright for a loop that drives the page, and the chrome-devtools CLI for a loop that reads console or network.
• The live-session rule sits in control-ui's guardrails and covers stories 5 to 7. It points to rules gstack already has: go-mode's Always-pause list, control-ui's privacy guardrail, and the redaction rule in diagnosing-bugs.
• Setup. control-ui says how to install the chrome-devtools CLI, with the MCP server as the fallback.
• go-help. The control-ui row says the skill routes between driving and debugging.
• The Chrome-only limit stays implicit. Proof on WebKit and Firefox stays on Playwright either way.
• Vendor facts are checked against current docs before they go in a skill. These include the CLI's commands, the MCP tool names, the flag that connects to a running Chrome, the Chrome version that flag needs, the memory-leak-debugging skill, and what the Lighthouse audit leaves out. The source article is Steve Kinney's "Playwright vs. Chrome DevTools MCP".

Left to the build

• Whether the chrome-devtools CLI supports each tool the playbooks name. A tool it lacks goes to the MCP server.
• Whether the CLI can connect to the user's running Chrome, or whether the handoff in stories 5 to 7 needs the MCP server.
• Whether doctor checks that the chrome-devtools CLI is installed.

Testing

None for the skill text. If doctor gains a check for the chrome-devtools CLI, the check gets a case in the existing doctor tests, which run the real script on fixture files.

Everything else is verified by running it. Each changed skill passes the authoring-a-skill validation and the build. The perf-issue playbook runs once on a real page with the chrome-devtools CLI installed and once without it, and the second run falls back to control-ui's CDP harness.

Out of scope

• Performance budgets. #15 leaves them out too.
• Splitting control-ui into separate driving and debugging skills.
• Chrome DevTools AI assistance. It runs in the DevTools panel for a person, not for an agent.
• Community CDP wrappers and cloud browser platforms.
• Claude in Chrome. It acts in the user's real browser and is not for testing.
• The driving-side changes. #15 covers them: the Playwright reference, flaky-test reruns, and Playwright Test Agents.