feat: add harness engineering improvements

.agents/skills/change/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: change
+description: Create a beachball change file for the current changes. Determines change type (patch/minor) and generates a description from the diff.
+disable-model-invocation: true
+allowed-tools: Bash Read Grep Glob
+---
+
+# Create a Beachball Change File
+
+Generate a change file for the current branch's modifications using the repo's beachball setup.
+
+## Steps
+
+1. **Identify changed packages** by running:
+
+   ```bash
+   git diff --name-only HEAD~1
+   ```
+
+2. **Determine the change type:**
+
+   - `patch` — bug fixes, internal refactors, test-only changes
+   - `minor` — new features, new exports, new component variants
+   - `none` — changes that don't affect the published package (stories, docs, tests only)
+   - Never use `major` without explicit user approval
+
+3. **Generate a descriptive message** following the format: `fix(package-name): description` or `feat(package-name): description`
+
+4. **Run the repo's change script** to create the change file:
+
+   ```bash
+   yarn change
+   ```
+
+   This runs `beachball change --no-commit` (configured in root `package.json`).
+
+   For non-interactive usage with a specific type and message:
+
+   ```bash
+   yarn beachball change --no-commit --type <type> --message "<message>"
+   ```
+
+5. **Verify** the change file was created:
+
+   ```bash
+   yarn check:change
+   ```
+
+6. If multiple packages are affected, create separate change files for each.
+
+## Rules
+
+- Every published package change MUST have a change file
+- Do not create change files for unpublished packages (stories packages, internal tools)
+- Do not create change files for changes that only affect tests, stories, or docs within a package
+- The message should describe the user-facing impact, not the implementation detail

.agents/skills/lint-check/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: lint-check
+description: Run lint on affected packages, parse errors, and auto-fix common issues (design tokens, React.FC, SSR safety, import restrictions)
+disable-model-invocation: true
+argument-hint: '[package-name]'
+allowed-tools: Bash Read Edit Grep Glob
+---
+
+# Lint Check and Auto-Fix
+
+Run linting and fix common issues for Fluent UI packages.
+
+## Steps
+
+1. **Determine scope.** If `$ARGUMENTS` is provided, lint that specific package. Otherwise, lint affected packages:
+
+   ```bash
+   # Specific package
+   yarn nx run @fluentui/$ARGUMENTS:lint
+
+   # Or affected packages
+   yarn nx affected -t lint
+   ```
+
+2. **Parse the output** and categorize errors by the custom Fluent UI ESLint rules:
+
+   | Rule                                    | What it catches                             | How to fix                                            |
+   | --------------------------------------- | ------------------------------------------- | ----------------------------------------------------- |
+   | `@fluentui/ban-context-export`          | Context exported from wrong layer           | Move to `react-shared-contexts` package               |
+   | `@fluentui/ban-instanceof-html-element` | `instanceof HTMLElement` (breaks iframes)   | Use element.tagName or feature detection              |
+   | `@fluentui/no-global-react`             | `React.FC`, `React.useState` etc.           | Use named imports: `import { useState } from 'react'` |
+   | `@fluentui/no-restricted-imports`       | Banned import paths                         | Use the allowed import path from the error message    |
+   | `@fluentui/no-context-default-value`    | Context created without `undefined` default | Use `createContext(undefined)` and add a guard hook   |
+
+3. **Auto-fix** any issues found by editing the source files directly. For each fix:
+
+   - Read the file
+   - Apply the fix
+   - Verify the fix by re-running lint on that specific file
+
+4. **Report** a summary of what was found and fixed.
+
+## References
+
+- ESLint plugin source: `packages/eslint-plugin/src/rules/`
+- Design tokens guide: [docs/architecture/design-tokens.md](docs/architecture/design-tokens.md)
+- Component patterns: [docs/architecture/component-patterns.md](docs/architecture/component-patterns.md)

.agents/skills/package-info/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: package-info
+description: Quick lookup for a Fluent UI package — path, dependencies, owner team, Nx project details, and relevant docs
+argument-hint: <package-name>
+allowed-tools: Bash Read Grep Glob
+---
+
+# Package Info Lookup
+
+Get a comprehensive overview of the package **$ARGUMENTS**.
+
+## Steps
+
+1. **Resolve the package path.** Map the name to a filesystem path:
+
+   - `react-button` or `@fluentui/react-button` → `packages/react-components/react-button/`
+   - Check both `library/` (source) and `stories/` (storybook) sub-packages
+
+2. **Get Nx project details:**
+
+   ```bash
+   yarn nx show project @fluentui/$ARGUMENTS --json 2>/dev/null || yarn nx show project $ARGUMENTS --json 2>/dev/null
+   ```
+
+3. **Read the package.json** for version, dependencies, and peer dependencies.
+
+4. **Check ownership** by searching CODEOWNERS:
+
+   ```bash
+   grep -i "$ARGUMENTS" CODEOWNERS
+   ```
+
+5. **Summarize the component structure** — list files under `library/src/components/`.
+
+6. **Check test coverage** — does it have:
+
+   - Unit tests (`*.test.tsx`)
+   - Conformance tests (`testing/isConformant.ts`)
+   - Stories (`stories/` package)
+
+7. **Report** in this format:
+
+   ```
+   Package: @fluentui/<name>
+   Path: packages/react-components/<name>/library/
+   Version: x.y.z
+   Tier: 3 (Component) | 2 (Foundation) | 1 (Core)
+   Owner: <team from CODEOWNERS>
+   Dependencies: <list relevant @fluentui deps>
+   Components: <list exported components>
+   Tests: unit ✓/✗ | conformance ✓/✗ | stories ✓/✗
+   ```
+
+## Useful Commands for the Package
+
+```bash
+yarn nx run <project>:build          # Build
+yarn nx run <project>:test           # Unit tests
+yarn nx run <project>:lint           # Lint
+yarn nx run <project>:type-check     # Type check
+yarn nx run <project>:generate-api   # Regenerate API docs (etc/*.api.md)
+```
+
+## References
+
+- Package layers: [docs/architecture/layers.md](../../../docs/architecture/layers.md)
+- Team routing: [docs/team-routing.md](../../../docs/team-routing.md)

.agents/skills/review-pr/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: review-pr
+description: Review a PR for correctness, pattern compliance, testing, accessibility, and safety. Produces a confidence score for merge readiness.
+argument-hint: <PR-number-or-branch>
+allowed-tools: Bash Read Grep Glob
+---
+
+# Review a Pull Request
+
+Review PR **$ARGUMENTS** and produce a confidence score for merge readiness.
+
+## Phase 1: Gather PR Context
+
+```bash
+# PR metadata
+gh pr view $ARGUMENTS --json title,body,author,labels,files,additions,deletions,baseRefName,headRefName,state,isDraft,number
+
+# Changed files list
+gh pr diff $ARGUMENTS --name-only
+
+# Full diff
+gh pr diff $ARGUMENTS
+
+# CI status
+gh pr checks $ARGUMENTS
+```
+
+## Phase 2: Classify PR Type
+
+Determine the PR type from changed files and metadata:
+
+| Type             | Detection                                                            | Check scope                                    |
+| ---------------- | -------------------------------------------------------------------- | ---------------------------------------------- |
+| **docs-only**    | All files are `*.md`, `docs/**`, `**/stories/**`, `**/.storybook/**` | Change file only                               |
+| **test-only**    | All files are `*.test.*`, `*.spec.*`, `**/testing/**`                | Change file + test quality                     |
+| **bug-fix**      | Branch starts with `fix/` or title contains "fix"                    | All checks, extra weight on tests              |
+| **feature**      | Branch starts with `feat/` or adds new exports                       | All checks, extra weight on API + patterns     |
+| **refactor**     | No new exports, restructures existing code                           | All checks, extra weight on no behavior change |
+| **config/infra** | Changes to CI, configs, scripts only                                 | Change file + no regressions                   |
+
+For **v8 packages** (`packages/react/`): skip V9 pattern checks — those are maintenance-only with different patterns.
+For **web-components** (`packages/web-components/`): skip React-specific checks.
+
+## Phase 3: Run Checks
+
+Run each check category. For each finding, assign a severity:
+
+- **BLOCKER** — must fix before merge
+- **WARNING** — should address
+- **INFO** — consider
+
+### A. Beachball Change File
+
+Required if any published package source code changed (not just tests/stories/docs).
+
+- Check `change/` directory in the diff for new `.json` files
+- Verify change type: `patch` for fixes, `minor` for features, never `major` without explicit approval
+- Not required for changes that only affect tests, stories, docs, or snapshots
+
+**BLOCKER** if missing for published source changes.
+
+### B. V9 Component Pattern Compliance
+
+Only for files in `packages/react-components/react-*/library/src/`:
+
+| Check               | Look for                                                                                            | Severity |
+| ------------------- | --------------------------------------------------------------------------------------------------- | -------- |
+| No `React.FC`       | `React.FC`, `: FC<`, `React.FunctionComponent` in added lines                                       | BLOCKER  |
+| No hardcoded styles | Hex colors `#[0-9a-fA-F]{3,8}`, hardcoded `px` values for spacing/radius/font in `.styles.ts` files | WARNING  |
+| Griffel usage       | Style files must use `makeStyles` from `@griffel/react`, not inline styles                          | WARNING  |
+| mergeClasses order  | User `className` must be the LAST argument in `mergeClasses()`                                      | WARNING  |
+| Slot system         | New components must use `slot.always`/`slot.optional` and `assertSlots`                             | WARNING  |
+
+Reference: [docs/architecture/component-patterns.md](../../../docs/architecture/component-patterns.md)
+
+### C. Dependency Layer Violations
+
+For changes to `package.json` files or new imports in Tier 3 component packages:
+
+- **BLOCKER** if a Tier 3 package (`react-button`, `react-menu`, etc.) adds a dependency on another Tier 3 package
+- Allowed Tier 2 deps: `react-utilities`, `react-theme`, `react-shared-contexts`, `react-tabster`, `react-positioning`, `react-portal`
+- Allowed Tier 1 deps: `@griffel/react`, `@fluentui/tokens`, `@fluentui/react-jsx-runtime`
+
+Reference: [docs/architecture/layers.md](../../../docs/architecture/layers.md)
+
+### D. SSR Safety
+
+Grep added lines for unguarded browser API access:
+
+| Pattern                                                       | Severity |
+| ------------------------------------------------------------- | -------- |
+| `window.` without `canUseDOM` or `typeof window` guard nearby | BLOCKER  |
+| `document.` without guard                                     | BLOCKER  |
+| `navigator.` without guard                                    | BLOCKER  |
+| `localStorage` / `sessionStorage` without guard               | BLOCKER  |
+| `instanceof HTMLElement`                                      | WARNING  |
+
+Check 3 lines above each match for a guard (`canUseDOM`, `typeof window !== 'undefined'`).
+
+### E. Testing
+
+| Check                                                                       | Severity |
+| --------------------------------------------------------------------------- | -------- |
+| Source files changed but no corresponding `.test.tsx` changes               | WARNING  |
+| New component missing `testing/isConformant.ts`                             | WARNING  |
+| Snapshot files need updating (render/style changes without `.snap` updates) | INFO     |
+
+### F. API Surface
+
+| Check                                             | Severity |
+| ------------------------------------------------- | -------- |
+| Public API changed but `etc/*.api.md` not updated | WARNING  |
+| Existing exports removed (breaking change)        | BLOCKER  |
+| New exports added (flag for human review)         | INFO     |
+
+### G. Accessibility
+
+| Check                                              | Severity |
+| -------------------------------------------------- | -------- |
+| Existing `aria-*` attributes removed               | BLOCKER  |
+| `onClick` without `onKeyDown`/`onKeyUp` handler    | WARNING  |
+| Interactive elements missing `role` or `aria-*`    | WARNING  |
+| Images/icons without `aria-label` or `aria-hidden` | WARNING  |
+
+### H. Security and Quality
+
+| Check                                         | Severity |
+| --------------------------------------------- | -------- |
+| `eval()` or `new Function()`                  | BLOCKER  |
+| `dangerouslySetInnerHTML`                     | WARNING  |
+| `console.log` / `debugger` in production code | WARNING  |
+| `// @ts-ignore` without explanation           | WARNING  |
+| `any` type in new code                        | INFO     |
+
+## Phase 4: Calculate Confidence Score
+
+```
+Start at 100
+
+For each BLOCKER:  -25 points
+For each WARNING:  -5 points
+For each INFO:     -1 point
+
+Bonuses:
+  +5 if tests added/updated alongside source changes
+  +3 if change file present and well-described
+  +2 if PR description is thorough
+
+Floor at 0, cap at 100.
+```
+
+Score interpretation:
+
+- **90–100**: High confidence — safe to merge
+- **70–89**: Moderate confidence — minor concerns
+- **50–69**: Low confidence — needs attention
+- **0–49**: Not safe to merge — blockers present
+
+## Phase 5: Produce Output
+
+Use this exact format:
+
+```
+## PR Review: #<number> — <title>
+
+**Author:** <author>
+**Type:** <detected PR type>
+**Packages affected:** <list>
+**CI Status:** <passing/failing/pending>
+
+### Confidence Score: <score>/100
+
+<one-sentence summary>
+
+### Findings
+
+#### Blockers (must fix before merge)
+- [ ] <finding with file:line reference>
+
+#### Warnings (should address)
+- [ ] <finding with file:line reference>
+
+#### Info (consider)
+- <finding>
+
+### Category Breakdown
+
+| Category | Status | Notes |
+|----------|--------|-------|
+| Change file | PASS/FAIL | ... |
+| V9 patterns | PASS/WARN | ... |
+| Dep layers | PASS/FAIL | ... |
+| SSR safety | PASS/WARN | ... |
+| Testing | PASS/WARN | ... |
+| API surface | PASS/WARN | ... |
+| Accessibility | PASS/WARN | ... |
+| Security/Quality | PASS/WARN | ... |
+
+### Recommendation
+
+APPROVE / REQUEST_CHANGES / COMMENT
+
+<brief rationale>
+```
+
+## Notes
+
+- For large PRs (50+ files), prioritize: published source files > test files > config. Note reduced confidence due to review scope.
+- Draft PRs: still review but note WIP status.
+- Merge conflicts: flag as BLOCKER if detected.
+- The `### Confidence Score: NN/100` line must always appear on its own line for machine parsing.