Reorganize agent instructions into shared references and component workflow skills

[Jason Morse (JasonVMo)]

Platforms Impacted

• iOS
• macOS
• win32 (Office)
• windows
• android

No runtime platform code changes. This PR changes agent instructions, skills, contributor documentation, and repository validation tooling.

Description of changes

Reorganizes repository agent guidance so shared knowledge lives in one place and loads only when a task needs it. Adds clearer workflows for v0/v1, agentic, native, and review work, and lays groundwork for future agent evaluations.

Shared references (references/agents/)

• New shared library with a taxonomy and a document index. Each document carries standardized frontmatter (id, kind, owner_paths). Documents use R-* rule IDs for testable obligations and C-* claim IDs for version-bound evidence.
• Moved here from skill-local folders: agentic recipes (types/slots, state/accessibility, styles/tokens, rendering, tests/stories), desktop focus guidance, Windows Fabric guidance, and contract source adapters.
• New references:
  • classification and routing;
  • v0 and v1 maintenance recipes;
  • legacy test apps;
  • repository architecture, commands and validation, TypeScript, permissions, release, and dependency security;
  • design tokens;
  • native components;
  • Apple/Office native integration.
• Version-bound platform observations moved into evidence-reference documents: focus/platform-evidence.md and accessibility/action-transport-evidence.md. The rules, and three component accessibility specs, cite them.

Skills (.github/skills/)

• New skills: maintain-v0-v1-component, review-component (read-only, covers all generations), and implement-native-component (also provides a native overlay checklist).
• Existing skills:
  • Descriptions now state positive scope and exclusions.
  • Agentic authoring loads references conditionally and has primitive and plan-only branches.
  • fix-security-issues is split into a 371-word workflow plus a procedure reference, with every rule preserved.

Root and scoped instructions

• Root AGENTS.md shrinks from 27.4 KB to 8.0 KB. It keeps always-on safeguards (permissions, validation truthfulness, code rules, generation policy, native trigger), a task routing table, and a scoped-instruction index. Copilot CLI loads root content twice through the CLAUDE.md import.
• Permissions details and the Apple/Office native rules moved into references. Every sentence was preserved, confirmed by sentence-level comparison.
• v0 and v1 framework AGENTS.md files become short maintainer routes. Stale commands and paths were corrected.
• New components use packages/agentic/components; v0 and v1 are maintenance-only.

Tooling

• yarn check-agent-instructions is a deterministic checker that runs in yarn lage buildci and repo-checks. It validates:
  • frontmatter and the reference index;
  • case-sensitive links and anchors, including inbound anchors into instruction files;
  • code-span paths, skill metadata, and rule IDs;
  • prerequisite cycles and depth;
  • routing consistency;
  • evaluation fixtures.
• The checker has 15 node tests in @fluentui-react-native/scripts.
• yarn clean-lage-cache (lage cache --clear). Final validation is now yarn clean-lage-cache followed by yarn lage buildci.

Evaluation groundwork

• 15 sanitized fixtures in references/agents/evals/cases/ (10 development, 5 holdout), with a documented local result-record shape. No evaluation framework is committed. The efficiency or efficacy skill intentionally stays outside this repository.

Contributor documentation

• CONTRIBUTING.md now directs new components to the agentic package and keeps v0/v1 FluentTester/E2E guidance for maintenance.
• Fixed stale FluentTester and E2E paths in CONTRIBUTING.md and apps/E2E/README.md.

Verification

Automated:

Command	Result
yarn clean-lage-cache then yarn lage buildci --grouped	Passed: 171 tasks, 0 skipped, 0 failed
yarn check-agent-instructions	Passed
yarn workspace @fluentui-react-native/scripts test	Passed: 15 tests
yarn lage test-links --grouped	Passed: 87 workspaces
yarn change:check	Passed (empty changeset; documentation only)
yarn test:agent-permissions	Passed: 10 tests
yarn workspace @fluentui-react-native/components check:spec-contracts	Passed

Agent routing pilot: read-only Copilot CLI 1.0.98 probes, one run per case, comparing the pre-change instructions with this branch.

Configuration	Expected skill reached	Assertions met	Input tokens	AI usage
Claude Sonnet 5.5, medium; 10 cases	Before 4/10, after 10/10	Before 17/22, after 22/22	−32%	−22%
GPT-6.1 Sol, high, long context; 8 development cases; independently scored	Every available skill before; after 10/10 following one routing fix	Before 16 + 4 partial of 20, after 20/20	−24%	−9%
GPT-6.1 Sol, high, long context; 5 holdouts; independently scored	Every available skill before; after 5/5	Before 10 + 1 partial + 1 failed of 12, after 12/12	−17%	−2%

Refinements informed by holdouts were rechecked. Those cases were relabeled as development and replaced with new holdouts.

Before	After
A 27 KB always-on root mixed v0, v1, and modern patterns. Recipes were owned by one skill, and there was no v0/v1, review, or native workflow. In the pilot, v0 and v1 tasks loaded no guidance.	An 8 KB root with safeguards and routing. Shared references are indexed and checked. Tasks route to dedicated workflows and load generation-specific recipes on demand.

Pull request checklist

This PR has considered (when applicable):

• Automated Tests
• Documentation and examples
• Keyboard Accessibility
• Voiceover
• Internationalization and Right-to-left Layouts

Keyboard, VoiceOver, and RTL behavior are not affected; no component runtime code changed.

[github-actions]

Bundle size report

Tree-shaken, minified production esbuild bundles with React and React Native runtimes externalized.

Scenario	Modules-Mac (Δ)	Modules-Win (Δ)	Size-Mac (Δ)	Size-Win (Δ)
components-button	62 (+0)	63 (+0)	49.94k (+0b)	49.87k (+0b)
components-catalog	159 (+0)	160 (+0)	155.26k (+0b)	155.19k (+0b)
design-theme-state	33 (+0)	34 (+0)	30.11k (+0b)	30.03k (+0b)
design-themed-root	37 (+0)	38 (+0)	32.07k (+0b)	32.00k (+0b)
design-color-lib	6 (+0)	6 (+0)	6.33k (+0b)	6.33k (+0b)
design-theme-state-legacy-source	34 (+0)	35 (+0)	31.77k (+0b)	31.69k (+0b)
design-legacy-theme-from-flex	57 (+0)	58 (+0)	97.72k (+0b)	97.59k (+0b)

The job is advisory: size changes are reported but do not fail the pull request. Bundle or analysis errors still fail.

---

View bundle-size workflow run