Jason Morse (JasonVMo) · Oct 15, 2026 · Oct 14, 2026 · Oct 15, 2026 · Oct 15, 2026 · Oct 15, 2026
diff --git a/.changeset/agent-instruction-references.md b/.changeset/agent-instruction-references.md
@@ -0,0 +1,4 @@
+---
+---
+
+Reorganize agent instructions into shared `references/agents` documents; documentation only.
diff --git a/.github/skills/agentic-component-authoring/SKILL.md b/.github/skills/agentic-component-authoring/SKILL.md
@@ -1,69 +1,74 @@
 ---
 name: agentic-component-authoring
-description: Generate or update Fluent UI React Native components in packages/agentic/components. Use for component APIs, slots, state hooks, token styling, render functions, tests, stories, and spec-driven component work.
+description: Implement, change, or plan changes to components and primitives in packages/agentic/components, including every new component. Covers public APIs, slots, state, token styling, rendering, tests, and stories. Not for contract-only work, read-only reviews, v0/v1 maintenance, or the Storybook app toolchain.
 license: MIT
 ---
 
 # Agentic component authoring
 
 Build components in `packages/agentic/components` as React Native adaptations of the Fluent UI v9 component pattern.
-This skill is the workflow router. Load only the references needed for the current change instead of placing every
-authoring rule in one always-loaded instruction file.
+New components always use this workflow; v0 and v1 are maintenance-only. This skill routes the work. Load only the
+references the current change needs.
 
 ## Choose the component kind
 
-- Higher-order components live in `src/components`. Read the
-  [higher-order component instructions](../../../packages/agentic/components/src/components/AGENTS.md).
-- Primitive components live in `src/primitives`. Read the
-  [primitive instructions](../../../packages/agentic/components/src/primitives/AGENTS.md).
-- If the change spans multiple components, repeated helpers, or shared dependency boundaries, read the
-  [package-wide optimization guidance](../agentic-component-optimization/SKILL.md) and
-  [`packages/agentic/components/src/AGENTS.md`](../../../packages/agentic/components/src/AGENTS.md). Do not run a
-  whole-package audit for a tiny single-component edit.
-- Work on the Storybook application, native projects, bundling, or CocoaPods belongs to the
-  [agentic Storybook development skill](../agentic-storybook-development/SKILL.md), not this component workflow.
+- **Higher-order components** live in `src/components`. Read the
+  [package instructions](../../../packages/agentic/components/AGENTS.md) and the
+  [higher-order component instructions](../../../packages/agentic/components/src/components/AGENTS.md). The
+  component's `SPEC.md` and `spec/` companions are its contract.
+- **Primitives** live in `src/primitives`. Read the package instructions and the
+  [primitive instructions](../../../packages/agentic/components/src/primitives/AGENTS.md). A primitive's colocated
+  `CONTRACT.md` is its contract; primitives have no upstream-backed `SPEC.md`.
+- Changes spanning components, repeated helpers, or dependency boundaries also use the
+  [optimization skill](../agentic-component-optimization/SKILL.md). Do not audit the whole package for a small edit.
+- Read-only reviews use [review-component](../review-component/SKILL.md). Storybook application, native project,
+  bundling, or CocoaPods work uses the [Storybook skill](../agentic-storybook-development/SKILL.md).
+- Native views, codegen, or registration also use the
+  [native component skill](../implement-native-component/SKILL.md) as an overlay.
 
 ## Load focused references
 
-| Work                                                                         | Reference                                                                                                                              |
-| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| Source interpretation, provenance, contract drafting, review, or divergences | [Contract authoring](../agentic-component-contract-authoring/SKILL.md)                                                                 |
-| Public props, slots, state types, native prop exposure, or exports           | [Types and slots](references/types-and-slots.md)                                                                                       |
-| Defaults, derived state, interaction hooks, accessibility, or slots          | [State and accessibility](references/state-and-accessibility.md)                                                                       |
-| Focus, focus visuals, keyboard activation, or native focus refs              | [Common focus authoring](references/focus.md), then [Windows/Win32](references/focus-windows.md) or [macOS](references/focus-macos.md) |
-| Tokens, theme caching, state precedence, or slot style application           | [Styles and tokens](references/styles-and-tokens.md)                                                                                   |
-| Pure slot rendering, component assembly, or display names                    | [Rendering and assembly](references/rendering.md)                                                                                      |
-| Runtime tests, type tests, snapshots, Storybook stories, or validation       | [Tests and stories](references/tests-and-stories.md)                                                                                   |
-| Native React Native Windows Fabric components, codegen, registration, or UIA | [Windows Fabric native components](references/windows-fabric-native-components.md)                                                     |
-| Cross-component duplication, shared extraction, or dependency hygiene        | [Package optimization](../agentic-component-optimization/SKILL.md)                                                                     |
+| Work                                                                         | Reference                                                                                                                                                                                           |
+| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Source interpretation, provenance, contract drafting, or divergences         | [Contract authoring](../agentic-component-contract-authoring/SKILL.md)                                                                                                                              |
+| Public props, slots, state types, native prop exposure, or exports           | [Types and slots](../../../references/agents/components/agentic/types-and-slots.md)                                                                                                                 |
+| Defaults, derived state, interaction hooks, accessibility, or slots          | [State and accessibility](../../../references/agents/components/agentic/state-and-accessibility.md)                                                                                                 |
+| Focus, focus visuals, keyboard activation, or native focus refs              | [Common focus authoring](../../../references/agents/focus/common.md), then [Windows/Win32](../../../references/agents/focus/windows-win32.md) or [macOS](../../../references/agents/focus/macos.md) |
+| Tokens, theme caching, state precedence, or slot style application           | [Styles and tokens](../../../references/agents/components/agentic/styles-and-tokens.md) and [tokens and theming](../../../references/agents/design/tokens-and-theming.md)                           |
+| Pure slot rendering, component assembly, or display names                    | [Rendering and assembly](../../../references/agents/components/agentic/rendering.md)                                                                                                                |
+| Runtime tests, type tests, snapshots, Storybook stories, or validation       | [Tests and stories](../../../references/agents/components/agentic/tests-and-stories.md)                                                                                                             |
+| Native React Native Windows Fabric components, codegen, registration, or UIA | [Windows Fabric native components](../../../references/agents/native/windows-fabric.md)                                                                                                             |
 
-A new higher-order component normally needs every reference. A focused fix should load only the affected reference and
-its immediate neighbors. Keep the component's colocated `SPEC.md` and companion files authoritative for its contract.
+A new higher-order component normally needs the types, state, styles, rendering, and tests references, plus focus
+guidance when it is focusable. Load the Windows Fabric reference only for native Windows views. A focused fix loads only
+the affected reference and its immediate neighbors.
 
 ## Workflow
 
-1. Read the repository and package instructions, the component `SPEC.md`,
-   `spec/source.json`, and every React Native companion referenced by the spec.
-2. Use an existing reviewed contract directly when its source evidence and
-   requested behavior are unchanged. If the contract is absent, stale, still a
-   draft, or accompanied by new source evidence, run the
-   [contract authoring workflow](../agentic-component-contract-authoring/SKILL.md)
-   and complete its pre-code review gate first.
-3. Inspect the closest canonical implementation. Use
-   [`components/button`](../../../packages/agentic/components/src/components/button) for a styled higher-order component
-   and [`primitives/icon`](../../../packages/agentic/components/src/primitives/icon) for a direct primitive.
+For a plan-only request, follow steps 1 to 4 without editing, then return the planned contract revision, the
+references used, the implementation order, and the validation plan.
+
+1. Read the package instructions and the component's contract: `SPEC.md`, `spec/source.json`, and every React Native
+   companion it references for a higher-order component, or `CONTRACT.md` for a primitive.
+2. Higher-order components: use an existing reviewed contract directly when its source evidence and requested behavior
+   are unchanged. If the contract is absent, stale, still a draft, or accompanied by new source evidence, run the
+   [contract authoring workflow](../agentic-component-contract-authoring/SKILL.md) and complete its pre-code review
+   gate first (R-AGENTIC-001 in the [package instructions](../../../packages/agentic/components/AGENTS.md)).
+3. Inspect the closest canonical implementation:
+   [`components/button`](../../../packages/agentic/components/src/components/button) for a styled higher-order
+   component, or [`primitives/icon`](../../../packages/agentic/components/src/primitives/icon) for a direct primitive.
 4. Establish the public contract before implementation: variants, slots, native props, accessibility, interaction
    states, and platform behavior.
 5. Implement in dependency order: types and slots, state and accessibility, styles and slot props, pure rendering,
    component assembly, and explicit exports.
-6. Preserve the specification. Record a genuine token or platform gap rather than substituting an unrelated value or
+6. Preserve the contract. Record a genuine token or platform gap rather than substituting an unrelated value or
    web-only behavior.
 7. Add focused tests and stories that exercise the public API and the resolved native output.
-8. Reconcile and ratify the local contract against the realized public types,
-   tests, stories, and platform evidence. Upstream changes require explicit
-   re-review and never overwrite the local contract.
-9. Run the smallest declared validation command while iterating. Finish with package format, lint, build, and tests; run
-   the Storybook bundle for story changes and the root build when public types, manifests, or project references change.
+8. Reconcile and ratify the local contract against the realized public types, tests, stories, and platform evidence.
+   Upstream changes require explicit re-review and never overwrite the local contract.
+9. Run the smallest declared validation command while iterating. Finish with package format, lint, build, and tests;
+   run the Storybook bundle for story changes and the root build when public types, manifests, or project references
+   change. Finish with `yarn clean-lage-cache` and then `yarn lage buildci` (R-VALID-003) and report results truthfully (R-VALID-002).
 
 Do not divide one component implementation into separate sub-agent or sub-skill phases. Its types, state, styling, and
 rendering form one contract and should remain in one implementation context.
diff --git a/.github/skills/agentic-component-authoring/references/spec-source-adaptation.md b/.github/skills/agentic-component-authoring/references/spec-source-adaptation.md
diff --git a/.github/skills/agentic-component-contract-authoring/SKILL.md b/.github/skills/agentic-component-contract-authoring/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: agentic-component-contract-authoring
-description: Create or revise reviewed React Native component contracts in packages/agentic/components from Flex/X3, Fluent v9, HTML/CSS, images, local platform foundations, or composite evidence.
+description: Create or revise reviewed React Native component contracts in packages/agentic/components from Flex/X3, Fluent v9, HTML/CSS, images, local platform foundations, or composite evidence. Use for contract-only or contract-feasibility work, and as the contract gate before implementing or planning a component change.
 license: MIT
 ---
 
@@ -11,14 +11,15 @@ contract. This skill owns source interpretation, authority, provenance,
 uncertainty, React Native adaptation, divergences, and requirement planning. It
 does not own component implementation.
 
-Use this skill directly for contract-only, feasibility, or implementation-plan
-requests. The [component authoring skill](../agentic-component-authoring/SKILL.md)
+Use this skill directly for contract-only or contract-feasibility requests. A
+plan to change a component's implementation or public API starts in the
+[component authoring skill](../agentic-component-authoring/SKILL.md), which
 invokes this workflow before code when a contract is missing, stale, still a
 draft, or accompanied by new source evidence.
 
 ## Choose the request mode
 
-- **Feasibility or plan only:** inspect the evidence, identify blockers and
+- **Feasibility or contract plan:** inspect the evidence, identify blockers and
   unknowns, and describe the contract work without changing implementation.
   Commit contract files only when the user requested a contract.
 - **Contract only:** create or revise the local contract and stop after its
@@ -31,14 +32,14 @@ draft, or accompanied by new source evidence.
 
 Load every adapter represented by the supplied evidence, but no others.
 
-| Evidence                                      | Adapter                                                        |
-| --------------------------------------------- | -------------------------------------------------------------- |
-| Pinned Flex component skill and X3 lineage    | [Flex and X3](references/sources/flex-x3.md)                   |
-| Fluent UI v9 source or specification          | [Fluent v9](references/sources/fluent-v9.md)                   |
-| HTML, CSS, computed styles, or browser output | [HTML and CSS](references/sources/html-css.md)                 |
-| Images, screenshots, or design renders        | [Visual reference](references/sources/visual-reference.md)     |
-| Public native API plus repository precedent   | [Local foundation](references/sources/local-foundation.md)     |
-| More than one of the preceding source sets    | [Composite evidence](references/sources/composite-evidence.md) |
+| Evidence                                      | Adapter                                                                                                    |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Pinned Flex component skill and X3 lineage    | [Flex and X3](../../../references/agents/components/agentic/contract-sources/flex-x3.md)                   |
+| Fluent UI v9 source or specification          | [Fluent v9](../../../references/agents/components/agentic/contract-sources/fluent-v9.md)                   |
+| HTML, CSS, computed styles, or browser output | [HTML and CSS](../../../references/agents/components/agentic/contract-sources/html-css.md)                 |
+| Images, screenshots, or design renders        | [Visual reference](../../../references/agents/components/agentic/contract-sources/visual-reference.md)     |
+| Public native API plus repository precedent   | [Local foundation](../../../references/agents/components/agentic/contract-sources/local-foundation.md)     |
+| More than one of the preceding source sets    | [Composite evidence](../../../references/agents/components/agentic/contract-sources/composite-evidence.md) |
 
 ## Workflow
 
@@ -58,7 +59,9 @@ Load every adapter represented by the supplied evidence, but no others.
 5. Draft the original React Native contract:
    - public API, slots, defaults, state ownership, and requirement IDs in
      `SPEC.md`;
-   - FURN token bindings and gaps in `spec/tokens.yaml`;
+   - FURN token bindings and gaps in `spec/tokens.yaml`, mapped through the
+     [Flex token map](../../../packages/agentic/design/src/tokens/mappings/flex-token-map.yaml).
+     Name each proposed binding or list it as unresolved;
    - native accessibility in `spec/accessibility.md`;
    - keyboard, pointer, focus, and motion behavior in
      `spec/interaction.md`;

diff --git a/.github/skills/agentic-component-optimization/SKILL.md b/.github/skills/agentic-component-optimization/SKILL.md
@@ -12,21 +12,20 @@ primitive or helper should exist at all.
 
 ## Read first
 
-1. Read `packages/agentic/components/AGENTS.md` and `packages/agentic/components/src/AGENTS.md`.
-2. Read the relevant component or primitive `AGENTS.md` file and the colocated `SPEC.md` files for the affected area.
+1. Read the [package instructions](../../../packages/agentic/components/AGENTS.md) and the
+   [source instructions](../../../packages/agentic/components/src/AGENTS.md).
+2. Read the relevant component or primitive `AGENTS.md` file and the colocated `SPEC.md` or `CONTRACT.md` files for the
+   affected area.
 3. Inspect the canonical implementations:
-   - `packages/agentic/components/src/components/button`
-   - `packages/agentic/components/src/primitives/icon`
+   [`components/button`](../../../packages/agentic/components/src/components/button) and
+   [`primitives/icon`](../../../packages/agentic/components/src/primitives/icon).
 
 ## Audit checklist
 
 ### 1. Dependency direction
 
-- Production source may depend only on React / React Native native components, `@fluentui-react-native/design`, and
-  `@fluentui-react-native/framework-base`.
-- Generalizable non-styling hooks belong in `framework-base/src/hooks`.
-- Styling helpers belong in `agentic/design/src/styling`.
-- Component-library-specific non-public types, constants, and helpers belong in `packages/agentic/components/src/common`.
+Apply the [source boundaries](../../../packages/agentic/components/src/AGENTS.md#source-boundaries): production
+dependencies, where generalizable hooks and styling helpers belong, and what stays in `src/common`.
 
 ### 2. Repetition and ownership