ci: add contributor guidelines, agent skills and commit message checks

Contributors and AI agents had no shared rules for commits, code or UI,
so every change drifted a little from the last one. Add guides for the
commit format, coding standards, UI and fixup commits, skills and roles
that carry the same rules for agents, git hooks that format staged files
and check commit messages, a CI workflow that validates the pull request
title and every commit, a skills check, and pull request and issue
templates.

Author: erkamyaman

.claude/agents/a11y-reviewer.md

@@ -0,0 +1,11 @@
+---
+name: a11y-reviewer
+description: Audits the devtools panel and the demo app for accessibility and visual consistency with axe, contrast checks and keyboard walkthroughs. Use before a pull request that changes UI, or when asked to review a page.
+tools: Read, Grep, Glob, Bash
+---
+
+You review accessibility and visual consistency. You don't edit files; you report.
+
+Follow the browser checks in the `devtools-verify` skill: run axe on each page in dark and light color schemes, check horizontal overflow at 1280px and 360px, and walk every interactive element with the keyboard (focus visible, arrow keys in trees and lists, `Escape` closes popups and clears search). Check text contrast by hand where axe can't (gradients, text over images) and compare each page against `docs/contributing/ui-guidelines.md`.
+
+Report findings ranked by user impact, each with the page, the element, what fails (rule or measured contrast), and a concrete fix. Say which pages you checked and how.

.claude/agents/devtools-reviewer.md

@@ -0,0 +1,17 @@
+---
+name: devtools-reviewer
+description: Reviews a change or pull request against this repository's coding standards, commit guidelines and data-collection rules. Use before opening a pull request or when asked to review a diff.
+tools: Read, Grep, Glob, Bash
+---
+
+You review changes to the Angular devtools. You don't edit files; you report.
+
+Check the diff against:
+
+- `docs/contributing/coding-standards.md`: TypeScript and Angular rules, and the page-side rules (debug APIs, stable ids, no DOM writes, `pageId`, expiry, cheap pushes, safe serialization).
+- `docs/contributing/ui-guidelines.md` for anything under `app/`.
+- `docs/contributing/commit-message-guidelines.md` for commit messages and the pull request title.
+- Tests: every behavior change has one, and agent tools changed together with their tests and descriptions.
+- Generated output: `extension/ui` rebuilt and committed when `app/` changed.
+
+Verify claims by reading the code, and run `pnpm test:devtools` and the `ngc` template check when in doubt. Report only real problems, ranked by impact, each with file:line, what is wrong, why it matters and a concrete fix.

.claude/agents/inspector-engineer.md

@@ -0,0 +1,12 @@
+---
+name: inspector-engineer
+description: Owns how inspectors collect data from the running app and serve it to the panel and to agents. Use for new inspectors, wrong or noisy data, unstable ids, tabs overwriting each other, heavy polling, and new MCP tools.
+---
+
+You are the inspector engineer for the Angular devtools.
+
+Follow the `devtools-inspector` skill and the "Reading data from the page" section of `docs/contributing/coding-standards.md`. Read Angular through its debug APIs and check every field you rely on against `node_modules/@angular/core/fesm2022`. Keep ids stable with `WeakMap`s, never write to the app's DOM, send `pageId` with every report, expire and forget pages on the server, and skip unchanged pushes.
+
+Put new logic in its own module and keep edits to `overlay.ts` and `devframe.ts` small. Add jsdom tests with a fake `ng` for every collector change and keep `pnpm test:devtools` green.
+
+Return a short summary: what was wrong, what you changed (file:line), the tests you added, and anything left undone.

.claude/agents/ui-engineer.md

@@ -0,0 +1,12 @@
+---
+name: ui-engineer
+description: Builds and restyles pages in the devtools panel (app/) so they match the design system, work with the keyboard and pass axe. Use for new inspector pages, UI polish, dropdowns, toolbars, empty states and theme changes.
+---
+
+You are the UI engineer for the Angular devtools panel.
+
+Follow the `devtools-ui` skill and `docs/contributing/ui-guidelines.md`. Use the theme variables and SCSS mixins, the shared `app-select` dropdown and the page anatomy (intro, sticky toolbar, list or tree with a detail panel, loading, error, empty and no-match states). Headings start at `h2`.
+
+Don't change RPC names, data shapes or behavior. If the data a page shows is wrong, stop and report it for the inspector engineer instead of working around it in the template.
+
+Before you finish, run the checks in the `devtools-verify` skill that apply to UI (format, `ngc` template check, the axe and 360px audit on the pages you touched) and list what you ran. Return a short summary of what changed, per file.

.claude/skills/devtools-commit/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: devtools-commit
+description: Write commit messages and pull request titles and descriptions for this repository, following this project's commit format and scopes. Use whenever you commit, split work into commits, or open or update a pull request.
+---
+
+# Commits and pull requests
+
+The rules are in `docs/contributing/commit-message-guidelines.md`. Summary:
+
+```
+<type>(<scope>): <short summary>
+
+<body: why the change is needed, old vs new behavior, imperative tense, 20+ characters>
+
+<footer: Fixes #123 | BREAKING CHANGE: ... | DEPRECATED: ...>
+```
+
+- Types: `feat`, `fix`, `perf`, `refactor`, `test`, `docs`, `build`, `ci`, `revert`.
+- Scopes: `hub`, `ui`, `popup`, `overlay`, `components`, `signals`, `injectors`, `router`, `forms`, `store`, `pipes`, `http`, `analog`, `mcp`, `extension`, `vite`, `demo`, `deps`. Leave the scope out for cross-cutting changes.
+- Summary: imperative, lowercase first letter, no period, header under 100 characters.
+
+## Pull requests
+
+- Pull requests are squash merged; the title becomes the commit on `main`, so it must follow the header format.
+- A `commit-msg` hook (`scripts/commit-message.mjs`, enabled by `pnpm install`) warns about a bad message as you commit; CI rejects it, checking the title and every commit in the pull request. Run `pnpm commit:check` before pushing, and fix flagged messages with `git commit --amend` or a reword rebase.
+- Address review feedback with fixup commits (`docs/contributing/using-fixup-commits.md`).
+- One feature per pull request, with its tests (including agent tool tests when tools change).
+- Rebuild and commit `extension/ui` when `app/` changed.
+- Fill in `.github/PULL_REQUEST_TEMPLATE.md`: what changed and why, how it was verified (see the `devtools-verify` skill), screenshots for UI changes.
+- Don't add AI attribution lines to commits or pull requests unless the maintainers ask for them.
+
+## Splitting work
+
+Group commits by area (the scope), keep each one building and passing tests where practical, and put generated output (`extension/ui`, lockfile) in the commit that needs it.

.claude/skills/devtools-inspector/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: devtools-inspector
+description: Add or fix how an inspector collects data, from the page-side overlay through the devframe server to the panel and the MCP tools. Use for new inspectors, wrong or noisy data, unstable selection, tabs overwriting each other, heavy polling, and new agent tools.
+---
+
+# Inspector data pipeline
+
+Every inspector follows the same path:
+
+```
+app page (overlay.ts + <area>-collector.ts)
+  -> rpc.call('push-<area>', { pageId, ... })
+  -> devframe.ts: per-page Map, shared state '<area>', expiry, forget-<area>-page
+  -> panel page (app/src/pages/<area>.ts) via rpc.sharedState('<area>')
+  -> agent tools (ctx.agent.registerTool) and MCP resources
+```
+
+Read `docs/contributing/coding-standards.md` ("Reading data from the page") before you start.
+
+## Page side (`packages/ng-devtools/src`)
+
+- Put collection logic in its own module (`<area>-collector.ts`) and keep `overlay.ts` changes to wiring: import, attach, push, `leave()` and the returned cleanup.
+- Read Angular through the debug APIs on `window.ng` and verify each field against `node_modules/@angular/core/fesm2022` (or the library's fesm build). Known helpers:
+  - `element-id.ts`: stable `WeakMap` ids for elements (`elementId`, `elementById`).
+  - `injector-tree.ts`: `className()` strips bundler `_` prefixes, `tokenName()`, `dependenciesOf()`, environment injector walk.
+  - `serialize.ts`: safe, size-limited serialization.
+  - `router.ts` `providerOf()`: find a service through the injector resolution path.
+- Never write attributes into the app's DOM. Never run app code (validators, guards) on a timer unless the user turned recording on.
+- Pushes: send on change, skip unchanged payloads (compare with the last JSON), re-send every few cycles so the server doesn't expire the page, and avoid full DOM scans on a timer (cache, rescan after a `MutationObserver` signal).
+- Every report carries `pageId` from `claimPageId()`. Call `forget-<area>-page` from `leave()`.
+
+## Server side (`devframe.ts`, `rpc/`)
+
+- Keep a `Map<pageId, report>` with `reportedAt`, drop pages older than 15 seconds in the shared expiry interval, and write the combined value into the shared state.
+- Page actions that the panel triggers (restore, highlight, run) go panel -> `request-<area>-action` -> broadcast `<area>-action` to the page -> `<area>-action-result`, keyed by `requestId`, with a timeout.
+- Source scans in `rpc/` enrich or stand in for live data. They must return a `kind` for anything the Dashboard counts.
+
+## Panel side
+
+- Subscribe with `const state = await rpc.sharedState('<area>'); apply(state.value()); state.on('updated', apply)` and remove the listener through `DestroyRef`. There is no `subscribe()` on shared state.
+- Filter to the current page with the `?pageId` host parameter when the page can show several tabs; offer an "All pages" option.
+- Then follow the `devtools-ui` skill for the page itself.
+
+## Agent tools
+
+- Describe what the tool returns, where the data comes from and what an empty answer means. Answer in markdown.
+- Update descriptions in `devframe.ts` when data shapes change, and the README tool list.
+
+## Tests
+
+- Collector tests run in jsdom with a fake `ng` (see `__tests__/injector-tree.test.ts`, `component-tree.test.ts`, `ngrx-collector.test.ts`). Cover stable ids, dedupe, expiry and the Angular shapes you rely on.
+- Server tests call the RPC handlers directly (see `http-server.test.ts`, `agent-tools.test.ts`).
+- `pnpm test:devtools` must stay green.

.claude/skills/devtools-ui/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: devtools-ui
+description: Build or change any page, component or style in the devtools panel (app/). Use for new inspector pages, restyles, dropdowns, toolbars, empty states, theme or palette changes, and any UI/UX or accessibility work in the panel.
+---
+
+# Devtools panel UI
+
+Read `docs/contributing/ui-guidelines.md` first; it is the source of truth for the theme, tokens and page anatomy. This skill is the working checklist.
+
+## Before you write code
+
+1. Open two recently built pages as references: `app/src/pages/di-inspector.ts` (tree + detail, keyboard, highlight) and `app/src/pages/network-inspector.ts` (toolbar, tables, forms, `app-select`).
+2. Check which data the page gets and from where (`client.scope('ng-devtools').rpc.call(...)` or `rpc.sharedState(...)`). UI work must not change RPC names or data shapes; if the data is wrong, use the `devtools-inspector` skill.
+
+## Rules
+
+- Styles are SCSS in the component `styles` field, starting with `@use 'mixins' as m;`.
+- Colors only through CSS variables (`--surface`, `--text-2`, `--accent`, ...). No hex values except brand colors on their own view (NgRx purple, Angular gradient, Analog, NativeScript, Capacitor).
+- Controls are `var(--control-h)` tall. Use `app/src/ui/select.ts` for every dropdown; never a native `<select>`.
+- Page structure: intro line, sticky toolbar (search with icon and `Escape` to clear, filters, count, actions), content (list or tree plus sticky detail on wide screens), and loading, error with Retry, empty and no-match states.
+- Headings start at `h2` and never skip a level. Section labels use `m.label`.
+- Rows are keyboard reachable (buttons or ARIA tree items with arrow keys). Selection is keyed by stable ids from the page.
+- Rows that map to an element in the app call `request-page-highlight` on hover and focus, and clear it on leave and blur.
+- Focus: `m.focus-ring` (use `-2px` inside scroll containers). Inputs use `m.field-focus`.
+- Motion 150 to 350ms, disabled under `prefers-reduced-motion`.
+- Angular: signals, `computed`, `linkedSignal`, `input`/`output`/`model`, `inject`, native control flow, `class`/`style` bindings, `host` object. No `any` in new code.
+- Copy: short and plain, no em dashes, never compare with other tools.
+- A new tab also needs: the `Tab` union in `app/src/types/tab.types.ts`, `allTabs` and the template switch in `app/src/app.ts`, an icon case in `tab-icon.ts`, and usually a Dashboard card.
+
+## Changing the brand
+
+Edit `app/src/styles/main.scss` (`$accent`) or the maps in `_palette.scss`. Never override tokens inside a page.
+
+## Verify
+
+Use the `devtools-verify` skill: template check with `ngc`, rebuild `extension/ui`, then the axe and 360px overflow audit on every page you touched, in the popup and at `/__devframes/`.

.claude/skills/devtools-verify/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: devtools-verify
+description: Verify a devtools change the way CI and a reviewer would, then check it in a real browser with axe. Use before saying a change is done, before committing, and before opening a pull request.
+---
+
+# Verify a change
+
+## 1. The CI checks
+
+Run them in this order; all must pass:
+
+```sh
+pnpm format:check
+pnpm commit:check
+pnpm skills:check
+pnpm typecheck
+pnpm test
+pnpm test:devtools
+pnpm build
+pnpm extension:build
+pnpm devtools:build-pkg
+git status --porcelain -- extension/ui   # must be committed when app/ changed
+```
+
+`pnpm typecheck` does not type-check panel templates. Also run:
+
+```sh
+NO_COLOR=1 pnpm exec ngc -p app/tsconfig.json --noEmit
+```
+
+and treat any `error TS` or `error NG` line as a failure. Strip color codes before grepping the output, or errors slip through.
+
+## 2. Run the demos
+
+`pnpm build` is a production build and turns the in-page launcher off. For manual checks rebuild in development mode:
+
+```sh
+pnpm build --configuration development
+node dist/angular-devtools/server/server.mjs   # Angular Travel on :4000
+pnpm analog:dev                                 # Analog demo on :5173
+```
+
+Open the panel through the amber launcher on the page, at `/__devframes/`, and directly at `/__devframes/ng-devtools/?view=angular#tab=<tab>`.
+
+## 3. Browser checks
+
+With Playwright and `@axe-core/playwright` (install them in a scratch folder, not in the repo):
+
+- Every page you touched, in dark and light color schemes: axe reports no violations, there are no page errors, and `document.documentElement.scrollWidth <= innerWidth` at 1280px and 360px wide.
+- Hub docks: clicking each rail button shows the matching view and only one frame (the rail selection and the content must match after fast switching and after a reload).
+- The feature itself, with real data from the demo app (for example `/examples/<area>`).
+
+Exclude the launcher (`#ng-devtools-popup-root`) from axe runs on demo pages; it is checked through the panel.
+
+## 4. Report honestly
+
+Say which checks ran and their results. If something was skipped (no browser, no build), say so.

.gitattributes

@@ -0,0 +1,4 @@
+extension/ui/** linguist-generated=true
+pnpm-lock.yaml linguist-generated=true
+*.mjs text eol=lf
+.githooks/* text eol=lf

.githooks/commit-msg

@@ -0,0 +1,3 @@
+#!/bin/sh
+node "$(git rev-parse --show-toplevel)/scripts/commit-message.mjs" --file "$1" || echo "WARNING: this commit message does not follow the guidelines."
+exit 0