docs: extend agent performance and Webpack guidance

AGENTS.md

@@ -2,26 +2,29 @@
 
 ## Scope
 
+- Read [CONTRIBUTING.md](CONTRIBUTING.md) before analyzing or changing this repository; its contribution and PR requirements apply.
 - Read applicable nested `AGENTS.md` files before editing or testing a subtree.
 - Shared routing belongs in `packages/router-core`; check React, Solid, and Vue bindings for shared changes. Shared Start runtime/build logic lives in `packages/start-*-core`.
+- Keep scratch checkouts outside the workspace's project-discovery tree to avoid duplicate Nx projects. Use separate benchmark results and build-output directories for independent comparisons.
 
-## Work and validation
+## Build and test constraints
 
 - Start bug fixes with a failing regression test that uses only public APIs to reproduce and assert user- or developer-visible behavior. Do not manufacture bugs by mutating internals. Establish whether real usage can reach the failing state before adding runtime handling; simplify handling of states proven unreachable.
 - When removing an API, option, or behavior, delete its tests. Never add tests that assert the removed thing is gone, such as `not.toHaveProperty('oldName')`, a type error for the old call, or a runtime throw.
+- Diagnostic counters and profiles may observe a supported public path without changing its behavior. A diagnostic control proves only the measured mechanism; verify the final implementation through public behavior or the supported compiler-plugin boundary.
+- For asynchronous setup and cleanup, identify the authoritative state and lifetime before adding flags, timers, or completion callbacks. Preserve intentional ownership transfers and remove obsolete paths when replacing an implementation.
 - For suspected dependency issues, verify the upstream root cause, then propose an upstream fix to the user, including for other `@tanstack/*` packages. **Never implement a workaround in this repository unless the user explicitly authorizes it.**
-- During debugging/prototyping, keep fixes aligned with the PR's intended architecture. If making a test pass requires another flag, counter, copied deadline, or duplicate completion authority, stop and consolidate state and ownership. Remove superseded paths instead of accumulating patches and bundle growth.
 - Use Node from `.nvmrc` and pnpm from root `package.json`. Install at the root with `CI=1 pnpm install --frozen-lockfile`.
-- For sandbox-blocked registry/store access, escalate the same command; report the blocker if unavailable. Do not change stores, delete dependencies/lockfiles, use `--force`/`--ignore-scripts`, or weaken workspace trust/build policies to bypass it.
+- Diagnose registry, store, and network failures separately from dependency incompatibilities. Preserve the lockfile and workspace trust/build policies when troubleshooting installation; bypassing scripts or policies changes the environment being tested.
 - Never manually edit `pnpm-lock.yaml` or any `routeTree.gen.ts`. Regenerate the lockfile with `pnpm install --no-frozen-lockfile` after intentional dependency changes; regenerate route trees through app builds/dev servers or the generator fixture harness.
-- Always use control-flow braces. Run `pnpm format` before validation.
+- Always use control-flow braces. Format changed files with the repository's Prettier configuration; root `pnpm format` writes across the checkout.
 - Use Nx: workspace imports consume built packages, so direct runners can test stale dependencies. Inspect resolved targets; some are inferred.
 
 ```sh
 CI=1 NX_DAEMON=false pnpm nx run <project>:<target> --outputStyle=stream --skipRemoteCache
 ```
 
-- Run one Nx command at a time. For a ~20-second startup/graph stall, stop, run `pnpm nx reset`, and retry once, then escalate. Do not apply that timeout to running tests.
+- Avoid overlapping Nx invocations that write to the same build outputs. If project-graph startup stalls, inspect logs and running processes before using `pnpm nx reset`; quiet output from running tests or benchmarks is not evidence of a graph stall.
 - For code changes, run affected packages' `test:unit`, `test:types`, and `test:eslint` where available, including affected consumers; use `test:e2e` for browser/app behavior and `test:build` for exports/build changes. Root `pnpm test` includes the full e2e suite. Published-code changes require `pnpm changeset`.
 
 ## Runtime rules
@@ -35,5 +38,5 @@ CI=1 NX_DAEMON=false pnpm nx run <project>:<target> --outputStyle=stream --skipR
 
 ## Performance and final bundle pass
 
-- For runtime/memory changes, compare identical baseline/candidate workloads using the relevant [benchmark guide](benchmarks/AGENTS.md): client navigation, Start SSR, or memory. Add coverage for unmeasured mechanisms.
-- **Last phase for every change affecting emitted client JavaScript**, including core/build transforms: complete the full [bundle-size-optimization skill](.agents/skills/bundle-size-optimization/SKILL.md) after correctness and performance validation. The full workflow is mandatory.
+- For performance audits, runtime lifecycles, hydration/RSC, HMR, dependency upgrades, chunk caching, build, or type-inference cost, use the [performance-review skill](skills/performance-review/SKILL.md). It selects the relevant measurements and regression checks.
+- **Last phase for every change affecting emitted client JavaScript**, including core/build transforms: complete the full [bundle-size-optimization skill](skills/bundle-size-optimization/SKILL.md) after correctness and performance validation. Apply the workflow to the affected code and its consumers.

e2e/AGENTS.md

@@ -6,4 +6,5 @@
 - Use the same `E2E_PORT_KEY`-aware key throughout config, app, and dummy-server setup/teardown. Clean only that key's port files, before allocation, when `TEST_WORKER_INDEX === undefined`; worker config reloads must not remap a running server's port.
 - For new browser tests, reuse the local error-checking fixture. The shared `test` from `@tanstack/router-e2e-utils` fails on unexpected `console.error`, including hydration errors; allow only expected errors with `whitelistErrors`.
 - HMR/watch tests edit real app sources. Reuse existing edit/restore helpers such as `createHmrFileEditor`, restore edits in teardown even after failures, and preserve the suites' single-worker and Nx `parallelism: false` settings.
+- For HMR, hydration/RSC assets, or deployment-cache tests, use the [performance-review skill](../skills/performance-review/SKILL.md) to select the applicable checks. They define repeated-edit, cancellation, warm-server, stylesheet-readiness, and old-tab cases that a successful initial render misses.
 - `@tanstack/router-e2e-utils:test:unit` is a placeholder. Validate helper changes through consuming e2e projects.

packages/AGENTS.md

@@ -10,6 +10,7 @@
 ## Tests
 
 - Inspect test commands: several `test:unit` scripts immediately exit or only echo a message. For these packages, validate behavior in the shared core or consuming e2e app; a successful placeholder target provides no unit coverage.
+- Check test discovery and TypeScript/ESLint includes for newly added files. A passing source-only compiler matrix does not typecheck tests outside its includes; use the applicable test configuration and inspect executed cases. Keep existing compiler/lint rules intact when extending coverage.
 - For `*-router-ssr-query` changes, run `router-ssr-query-core` unit tests and the affected framework's `e2e/<framework>-start/query-integration` tests. The framework wrapper unit targets currently exit without running tests.
 - For single-command Vitest targets, append filters after `--`, e.g. `-- tests/link.test.tsx -t "preloading"`.
 - `solid-router` and `router-generator` chain two Vitest commands in `test:unit`. Trailing file/name/update arguments reach only the final command. Run the full target for verification: Solid needs browser and server suites; the generator needs fixture generation followed by typechecking.

packages/router-plugin/AGENTS.md

@@ -3,5 +3,6 @@
 - Preserve one initialization of shared module state across reference and split chunks. Shared extraction includes transitive dependencies and whole destructured declarations; never extract `Route` or bindings that depend on it. The invariant suite in `tests/code-splitter.test.ts` covers these contracts.
 - `handleRouteUpdate` is stringified and injected into app modules. Keep runtime dependencies inside the function or explicitly emit them; extracting a helper to plugin module scope breaks the generated function. `tests/handle-route-update.test.ts` executes that emitted code.
 - Route HMR rebuilds indexes, clears `resolvePathCache`, replaces lazy-chunk ownership, and refreshes active routes while preserving Fast Refresh component identities. Keep these steps coordinated when adding derived state.
+- For HMR adapter changes, execute generated statements for first import and later hot evaluation; first import must not modify a different router's same-ID route. Match the adapter's actual accept/dispose data lifecycle, including Webpack's fresh disposal data. Follow the [HMR/watch checks](../../skills/performance-review/references/checks.md#hmr-and-watch-lifetimes) for browser state, pending work, route deletion, and configuration replacement.
 - For code-splitting changes, add inputs under `tests/code-splitter/test-files/<framework>/`. Regenerate and review reference, virtual, and shared snapshots for every grouping in [`tests/code-splitter.test.ts`](tests/code-splitter.test.ts).
 - Check [`tests/constants.ts`](tests/constants.ts) for framework coverage: the snapshot matrix currently covers React and Solid only. Validate affected Vue behavior in Vue router e2e apps.