feat(react): /react umbrella skill + in-house browser core + debug-agent debug job

Rename the agent skill command to /react (SKILL_NAME) and grow it into a
routing umbrella: ten always-on React baseline rules plus prose routing across
doctor (static scan), perf (the DevTools profiling harness), debug, design, and
grab.

Add @react-doctor/browser, a thin playwright-core wrapper that attaches to a
running Chrome over CDP (launching one only as a fallback) plus a lazily-loaded
`react-doctor browser` command (open/eval/snapshot/screenshot/grab) backing the
debug, design, and grab jobs. Playwright never bundles into the CLI hot path.

The debug job runs the debug-agent (github.com/millionco/debug-agent)
runtime-evidence loop: hypothesize, instrument with NDJSON logs, reproduce in
the live browser, fix only with log proof, verify, then clean up.

Carries the doc.md plan and references/{debug,design,grab}.md playbooks.

Author: aidenybai

.changeset/react-skill-umbrella.md

@@ -0,0 +1,5 @@
+---
+"react-doctor": minor
+---
+
+Rename the skill command to `/react` and expand it into a routing umbrella: ten always-on React baseline rules plus prose routing across doctor (static scan), perf (the DevTools profiling harness), debug, design, and grab. The debug job runs the [debug-agent](https://github.com/millionco/debug-agent) runtime-evidence loop (hypothesize → instrument with NDJSON logs → reproduce → fix with proof → verify). Adds an in-house browser core (`@react-doctor/browser`) that attaches to a running Chrome over CDP (launching one only as a fallback) and a `react-doctor browser` command (open/eval/snapshot/screenshot/grab) that backs the debug, design, and grab jobs. The browser core loads lazily, so playwright never bundles into the CLI's hot path.

doc.md

@@ -0,0 +1,115 @@
+# React Doctor: one skill that makes agents good at React
+
+Today React Doctor is a code scanner. The plan is to grow it into a single skill, `/react`, that does more than scan: it helps a coding agent write better React, quietly checks its own changes in the background, and can open a real browser to measure speed, reproduce bugs, and review design. People pick it up one developer at a time because the local skill is free and useful on its own, and the way it spreads to a whole team is by getting added to continuous integration (CI).
+
+## What it is
+
+It is the skill we already ship, grown, rather than a new wrapper around a pile of separate tools. The cleanup pass it does today becomes one option among several, and [React Grab](https://github.com/aidenybai/react-grab) and the browser piece from [Expect](https://github.com/millionco/expect) get folded in so they stop being separate installs. That consolidation is deliberate. With Expect, having a few separate tools left people unsure what to install and when, and that confusion is a big part of what hurt adoption.
+
+Installation stays the same. You install it with `npx react-doctor` and call it as `/react`. The package name and the brand stay React Doctor — so we keep the GitHub stars, the install command people already know, and the [react.doctor](https://www.react.doctor) domain — but the command itself is the shorter `/react`, since that is what you reach for while writing React.
+
+## What it does
+
+There are really two kinds of work it handles. Most of it runs instantly off the code itself, and the parts that need a browser only spin one up when you actually ask for them.
+
+- **Finding and fixing problems** (`doctor`, or `debug`, `audit`, `review`): it reads your code for the score and the 502 rules, profiles speed when you ask (`perf`), or opens a browser to reproduce a bug (`debug`).
+- **Building and improving the user interface, or UI** (`design`, or `dev`): it writes or refines UI and reviews it against a screenshot, and `grab` lets you point at an element on screen to get its file, line, and component tree.
+
+When something does need a browser, it connects to the Chrome you already have open over the [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) (CDP), and only downloads its own copy of Chrome if nothing is running. That one detail solves the biggest headache Expect had, because logins and cookies work on their own when it is your real session.
+
+The browser part is our own, slimmed down from Expect. It keeps the page open between commands, runs scripts in a sandbox, and carries the accessibility check, the speed trace, the page snapshot, and the network log. We left out the things we do not need, like the video recording, the terminal UI, and the test runner. Since it runs from the command line and the open page holds the state, there is no separate server to keep alive.
+
+## How it picks what to do
+
+We let the model choose which job to run by reading the skill, the same way it already routes to other skills, rather than matching keywords. So `/react` on its own lets it decide, naming a job like `/react perf` forces that one, and when the request is genuinely unclear the skill just asks.
+
+For the common cases it follows a rough guide:
+
+| You say or change                                       | Job                 |
+| ------------------------------------------------------- | ------------------- |
+| "review", "before commit", "clean up", or changed files | doctor (reads code) |
+| "slow", "laggy", "re-rendering"                         | perf                |
+| "broken", "crashes", "not working"                      | debug (browser)     |
+| "looks off", "polish", a pasted element or screenshot   | design              |
+| unclear                                                 | ask                 |
+
+We keep this judgment with the model instead of a fixed keyword list, because keyword matching only gets worse as models get better at reading what you actually meant.
+
+## Where the instructions live
+
+The skill itself stays small, in the same spirit as the [writing-guidelines](.agents/skills/writing-guidelines/SKILL.md) skill. The `SKILL.md` holds only the ten always-on rules and the short routing guide, and each job pulls its full instructions fresh from a web address when it runs:
+
+```bash
+curl --fail --silent --show-error \
+  https://www.react.doctor/prompts/debug.md
+```
+
+The per-rule fix recipes load the same way, for example `https://www.react.doctor/prompts/rules/react-builtins/exhaustive-deps.md`. Editing one of these files updates every user on their next run, with no reinstall, and the `/react` triage flow already works exactly like this.
+
+Because react-doctor is open source, these instruction files live in the repo and download straight from GitHub (`raw.githubusercontent.com`), the same approach writing-guidelines uses, and the `react.doctor/prompts` links are just a stable alias for those same files. A copy ships inside the package as a fallback for when the download fails or the network is blocked.
+
+The reason for the split is that the ten rules belong inside the skill, since they apply to every edit, while the longer job instructions belong online so we can change them without shipping a new version.
+
+## Running in the background
+
+By default the skill works without anyone calling it. When the agent finishes a task it looks only at the changed lines, and it stays quiet unless it finds one to three issues it is genuinely confident about, mentioning each one once.
+
+The browser jobs (perf, debug, design review) never start on their own. They only run when you or the agent asks, because they are slower and need a live page, and firing them on every change would just be noise. Noise is what gets a skill turned off.
+
+## The always-on React rules
+
+The skill ships with ten rules that shape how the agent writes React on every edit. We keep the list at ten on purpose, since the real value is in the browser jobs rather than a long rulebook:
+
+1. Derive state, do not duplicate it.
+2. Skip effects for values you can compute while rendering and for handling events.
+3. Compose components instead of piling on boolean props.
+4. Lift state only as far as it needs to go.
+5. Keep one source of truth.
+6. Render without side effects.
+7. Use stable keys, never the array index.
+8. Fetch independent data in parallel.
+9. Skip manual memoization and let the compiler handle it.
+10. Handle the loading, error, and empty states.
+
+## The debug job
+
+The debug job is [debug-agent](https://github.com/millionco/debug-agent), the runtime-evidence debugging skill, wired into the browser part. Rather than guess a fix from the code, the agent writes down a few hypotheses, drops small [NDJSON](https://github.com/ndjson/ndjson-spec) logs into the suspect spots, reproduces the bug, and only fixes once the logs prove the cause — then verifies against the logs and removes the instrumentation. A short-lived local server (`npx debug-agent`) collects the logs; the browser part drives the reproduction and reads what actually rendered. We reuse debug-agent here instead of writing our own loop because it already solves the hard part — making the agent fix with evidence, not vibes — and it is our own tool, so the two stay in step.
+
+## The design job
+
+We write the design job ourselves, treating [React UI](../brain/react-ui/SKILL.md), [ui.sh](https://ui.sh), [Impeccable](../brain/impeccable/SKILL.md), and the [design reference](../brain/design-reference.md) as source material rather than dependencies. The important part is that a review opens the page, takes a screenshot, and reports things it can actually measure, like contrast ratio, line length, spacing, and tap-target size, instead of offering opinions. Those measured findings are the part a smarter model cannot match just by reading code, whereas plain taste advice is. The `dev` name runs the live loop, where you point at an element and improve it as you build.
+
+## CI: where it goes team-wide
+
+In CI the first version stays code-only: the scan, the score, a pinned pull request comment, and inline suggestions. The browser jobs stay on your machine, and profiling in CI comes later, since it needs the app booted and a stable baseline, and it is really the "prove the impact to my manager" feature.
+
+The local skill earns the habit one developer at a time, and CI is how that becomes the whole team's default on every pull request. Both are free. The path from one to the other is the prompt already in the installer that offers to add the GitHub Action, shown once per repo after the local skill has shown its worth. How we make money is a separate decision, not a paywall on CI.
+
+## What we measure
+
+Three numbers carry the story:
+
+- **Habit**: how often the agent accepts and lands a fix the background check surfaced, plus weekly active repos.
+- **Conversion**: the share of local users who turn on the CI check, which tells us whether personal use spreads to the whole team.
+- **Retention**: whether teams keep the CI check on over time, which is the one that matters most.
+
+Alongside that, a short "very sad, mid, not sad" survey runs in the command line for a sample of users.
+
+## What to build, in order
+
+We build all of this and land it as one pull request, rather than merging anything piecemeal first. [Pull request #811](https://github.com/millionco/react-doctor/pull/811) is the starting point for the profiler, not something we merge on its own. The order we build it in:
+
+1. Take the profiler from pull request #811 as the starting point and rebuild it as the perf job. It is the template for every browser job.
+2. Prove the browser part works: connect to a running Chrome, keep the page open across commands, run sandboxed scripts, and inject the [React DevTools](https://react.dev/learn/react-developer-tools) hooks. Everything else depends on this, so it goes first.
+3. Expand the `/react` skill, with the ten rules plus the routing guide, under 200 lines.
+4. Turn on the background check, code-only and on by default.
+5. Add grab on top of the browser part, and wire the debug job to the [debug-agent](https://github.com/millionco/debug-agent) loop driving that same browser.
+6. Write the design job with measured review.
+7. Deprecate React Grab, leaving a shim so current users do not break.
+
+## What could go wrong
+
+- **The browser part**: if connecting to Chrome, keeping the page open, and injecting the DevTools hooks do not compose, the whole browser story is shaky, so we test it before building on it.
+- **Background noise**: on by default with a loose threshold is how you get uninstalled. We ship it nearly silent and loosen it only once the fix-acceptance data says it is safe.
+- **Conversion**: if people love the local skill but never turn it on in CI, it stays a personal tool and never reaches the team. Better to learn that early and cheaply.
+- **Design**: if measured review turns out no better than the model's own taste, we cut design from the first version.

packages/browser/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@react-doctor/browser",
+  "version": "0.5.4",
+  "private": true,
+  "description": "Internal: the in-house browser core for React Doctor. Attaches to a running Chrome over CDP (launches one only as a fallback), keeps the page open across commands, and exposes eval, snapshot, screenshot, audit, and grab for the debug/design/grab jobs.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && cross-env NODE_ENV=production vp pack",
+    "typecheck": "tsc --noEmit",
+    "test": "vp test run"
+  },
+  "dependencies": {
+    "playwright-core": "^1.49.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.13.0"
+  }
+}

packages/browser/src/connect.ts

@@ -0,0 +1,34 @@
+import { chromium, type Browser } from "playwright-core";
+import { CONNECT_TIMEOUT_MS, DEFAULT_CDP_ENDPOINT } from "./constants.js";
+import type { BrowserConnectOptions } from "./types.js";
+
+export interface BrowserConnection {
+  browser: Browser;
+  // True when we attached to an already-running Chrome over CDP. Closing the
+  // handle then only disconnects; it never kills the user's browser.
+  attached: boolean;
+}
+
+// Attach to the Chrome the user already has open (CDP), falling back to
+// launching the system Chrome when no debuggable instance is reachable.
+export const connectToBrowser = async (
+  options: BrowserConnectOptions = {},
+): Promise<BrowserConnection> => {
+  const endpoint = options.cdpEndpoint ?? DEFAULT_CDP_ENDPOINT;
+  try {
+    const browser = await chromium.connectOverCDP(endpoint, { timeout: CONNECT_TIMEOUT_MS });
+    return { browser, attached: true };
+  } catch (attachError) {
+    if (options.launch === false) {
+      throw new Error(
+        `Could not attach to Chrome at ${endpoint}. Start Chrome with --remote-debugging-port=${new URL(endpoint).port || "9222"}, or allow launching a browser.`,
+        { cause: attachError },
+      );
+    }
+    const browser = await chromium.launch({
+      channel: options.channel ?? "chrome",
+      headless: false,
+    });
+    return { browser, attached: false };
+  }
+};

packages/browser/src/constants.ts

@@ -0,0 +1,16 @@
+// Default Chrome DevTools Protocol endpoint. A user opts their browser in by
+// launching Chrome with `--remote-debugging-port=9222`; we attach to that.
+export const DEFAULT_CDP_PORT = 9222;
+export const DEFAULT_CDP_ENDPOINT = `http://127.0.0.1:${DEFAULT_CDP_PORT}`;
+
+// How long to wait for a CDP attach before falling back to launching Chrome.
+export const CONNECT_TIMEOUT_MS = 5_000;
+
+// How long a single page navigation may take before we give up.
+export const NAVIGATION_TIMEOUT_MS = 30_000;
+
+// React attaches the fiber for a DOM node under a per-render key whose name
+// begins with these prefixes (React 16+). We scan an element's own keys to find
+// it rather than hard-coding the random suffix.
+export const REACT_FIBER_KEY_PREFIX = "__reactFiber$";
+export const REACT_INTERNAL_INSTANCE_KEY_PREFIX = "__reactInternalInstance$";

packages/browser/src/grab/build-grab-result.ts

@@ -0,0 +1,42 @@
+import type { GrabComponent, GrabResult } from "../types.js";
+
+// Assemble the owner chain a grab pulled from the page (nearest component first)
+// into the result the CLI prints. The page hands us a flat, serializable chain;
+// the structure and formatting live here so they stay pure and testable.
+export const buildGrabResult = (ownerChain: GrabComponent[]): GrabResult => {
+  if (ownerChain.length === 0) {
+    return {
+      component: { name: "Unknown", source: null },
+      path: [],
+      approximate: true,
+    };
+  }
+  const [component, ...path] = ownerChain;
+  return {
+    component,
+    path,
+    approximate: component.source === null,
+  };
+};
+
+const formatComponentLine = (component: GrabComponent): string => {
+  if (component.source === null) return component.name;
+  const { fileName, lineNumber } = component.source;
+  return `${component.name}  ${fileName}:${lineNumber}`;
+};
+
+// Render the result as the indented owner tree shown in the grab playbook.
+export const formatGrabResult = (result: GrabResult): string => {
+  const lines = [formatComponentLine(result.component)];
+  result.path.forEach((owner, index) => {
+    const indent = "  ".repeat(index + 1);
+    lines.push(`${indent}← ${formatComponentLine(owner)}`);
+  });
+  if (result.approximate) {
+    lines.push("");
+    lines.push(
+      "(approximate: no React debug source — run a dev build with the JSX source transform for exact lines)",
+    );
+  }
+  return lines.join("\n");
+};

packages/browser/src/grab/grab-in-page.ts

@@ -0,0 +1,71 @@
+import type { FiberSource, GrabComponent } from "../types.js";
+
+// Runs inside the page (serialized by Playwright), so it must be self-contained:
+// no imports, no closure over module constants. Given a selector (or the element
+// a picker stored on `window.__REACT_DOCTOR_GRAB_TARGET`), it finds the React
+// fiber on the DOM node and walks the `_debugOwner` chain into a flat, plain
+// array. The Node side assembles and formats it (build-grab-result.ts).
+export const grabInPage = (selector: string | null): GrabComponent[] => {
+  interface PageFiber {
+    type?: unknown;
+    _debugSource?: { fileName: string; lineNumber: number; columnNumber?: number } | null;
+    _debugOwner?: PageFiber | null;
+  }
+
+  const win = window as unknown as { __REACT_DOCTOR_GRAB_TARGET?: Element | null };
+  const target: Element | null = selector
+    ? document.querySelector(selector)
+    : (win.__REACT_DOCTOR_GRAB_TARGET ?? document.activeElement);
+  if (!target) return [];
+
+  const fiberKey = Object.keys(target).find(
+    (key) => key.startsWith("__reactFiber$") || key.startsWith("__reactInternalInstance$"),
+  );
+  if (!fiberKey) return [];
+  const fiber = (target as unknown as Record<string, PageFiber | undefined>)[fiberKey];
+  if (!fiber) return [];
+
+  const nameOf = (type: unknown): string => {
+    if (!type) return "Unknown";
+    if (typeof type === "string") return type;
+    if (typeof type === "function") {
+      const fn = type as { displayName?: string; name?: string };
+      return fn.displayName || fn.name || "Anonymous";
+    }
+    if (typeof type === "object") {
+      const obj = type as {
+        displayName?: string;
+        render?: { displayName?: string; name?: string };
+        type?: unknown;
+      };
+      return (
+        obj.displayName ||
+        (obj.render && (obj.render.displayName || obj.render.name)) ||
+        nameOf(obj.type) ||
+        "Anonymous"
+      );
+    }
+    return "Unknown";
+  };
+
+  const toSource = (node: PageFiber): FiberSource | null => {
+    const debug = node._debugSource;
+    if (!debug) return null;
+    return {
+      fileName: debug.fileName,
+      lineNumber: debug.lineNumber,
+      columnNumber: debug.columnNumber ?? 0,
+    };
+  };
+
+  const chain: GrabComponent[] = [];
+  let owner: PageFiber | null | undefined = fiber._debugOwner;
+  while (owner) {
+    chain.push({ name: nameOf(owner.type), source: toSource(owner) });
+    owner = owner._debugOwner;
+  }
+  if (chain.length === 0) {
+    chain.push({ name: nameOf(fiber.type), source: toSource(fiber) });
+  }
+  return chain;
+};

packages/browser/src/index.ts

@@ -0,0 +1,7 @@
+export { BrowserSession } from "./session.js";
+export { connectToBrowser } from "./connect.js";
+export type { BrowserConnection } from "./connect.js";
+export { buildGrabResult, formatGrabResult } from "./grab/build-grab-result.js";
+export { grabInPage } from "./grab/grab-in-page.js";
+export * from "./types.js";
+export * from "./constants.js";