feat(agents): add AGENTS.md knowledge system and rnmacos-organize-knowledge skill by JasonVMo · Pull Request #3157 · microsoft/react-native-macos

Jason Morse (JasonVMo) · 2026-10-29T06:26:22Z

Summary:

Coding agents working in this fork have no shared, fork-specific guidance. Nothing tells them how to tag fork diffs for clean upstream merges, which files the fork owns, how CI builds RNTester-macOS, or which yarn commands to run. Ad hoc instruction files also tend to duplicate and contradict each other over time.

This PR adds a small, validated knowledge system:

AGENTS.md is the single instruction entry point. All fork content sits in one [macOS] block, so upstream AGENTS.md changes merge cleanly. .github/copilot-instructions.md just points to it.
.agents/knowledge/ holds one topic per concern, each with front matter (id, summary, load_when, sources, rules). Topics are listed in taxonomy.yaml and in a generated index.md, so agents load only the topics they need. First topics:
- fork.diff-tags and fork.ownership
- tooling.commands and tooling.format-lint
- testing.rntester-macos
- process.pull-requests
- evals.knowledge-checks
.claude/skills/rnmacos-organize-knowledge keeps new instructions placed, deduplicated, and indexed. The rnmacos- prefix avoids collisions with skills upstream may add. The skill stays short, and detail lives in references/.
.agents/knowledge/tools/knowledge.mts generates the index and checks:
- structure and front matter
- links and source paths
- yarn commands
- duplicate rules
- size budgets
- [macOS] fork-block rules
microsoft-pr.yml runs the checker, its tests, and markdownlint.

This is agent tooling specific to the fork, so there's no corresponding facebook/react-native PR. It's the base of a stack; #3158 builds the macOS accessibility topics on it.

Test Plan:

Run at the head of this branch (447e205e55), with Node 24.18.0:

Command	Result
`node .agents/knowledge/tools/knowledge.mts check --ci`	Passed: `20 files checked: 0 errors, 0 warnings.`
`node --test .agents/knowledge/tools/knowledge.test.mts`	Passed: 21 pass, 0 fail
`yarn markdownlint-cli2 --no-globs AGENTS.md ".agents/knowledge/*/.md" ".claude/skills/rnmacos-//.md" .github/copilot-instructions.md`	Passed: `Summary: 0 error(s)`
`yarn format-check`	Passed (exit 0)

The new CI steps in microsoft-pr.yml run the first three commands. No native code changes, so no native build was needed.

…wledge skill Add a structured, validated knowledge system for coding agents: - AGENTS.md is the single instruction entry point; its fork content lives in one [macOS] block so upstream AGENTS.md changes merge cleanly. .github/copilot-instructions.md only points to it. - .agents/knowledge/ holds one topic per concern (fork, tooling, testing, process, evals), a taxonomy.yaml, and a generated index.md. - .claude/skills/rnmacos-organize-knowledge keeps new instructions placed, deduplicated, and indexed, with detail in references/. - .agents/knowledge/tools/knowledge.mts checks structure, links, source paths, yarn commands, duplicates, budgets, and fork-block rules, and generates the index. CI runs it, its tests, and markdownlint. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…inks Skills now live in .agents/skills, which Copilot and Codex both discover. .claude/skills/<name> is a relative symlink for Claude Code, and KC-08 requires that link and rejects real files or dangling links there. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Saad Najmi (Saadnajmi) · 2026-10-29T17:18:44Z

Copilot Could you locally use Matt Pococks retro skill, go through my comments on PRs (in particular, ones doing the big version updates) and make some suggestions (as comments on this PR or the other one Jason has open) for more knowledge?

Copilot · 2026-10-29T17:24:33Z

Copilot Could you locally use Matt Pococks retro skill, go through my comments on PRs (in particular, ones doing the big version updates) and make some suggestions (as comments on this PR or the othe...

The retro skill wasn’t installed in this environment, so I read Matt Pocock’s public retro skill and applied its categories to your comments on #2824 and #3022 (the large 0.83 syncs), plus #3099. Two durable knowledge candidates emerged:

Add a fork.upstream-sync checklist for large version merges. Diff tags explain how to mark fork changes, but not how to decide what to forward-port. chore(0.83): prepare stable 0.83.0 with React Native 0.83.10 #3022 and chore: merge up to 0.83-stable branch #2824 suggest classifying local fixes as already present upstream/later in the merge stack, stable-only, applicable to main, or inapplicable because the target has no corresponding implementation; verify branch-specific config and cite the evidence. For example, Changesets baseBranch differs between 0.83-stable and main, and the RCTDevLoadingView fix had no corresponding main callsite.
Consider adding an imperative focus check to feat(agents): add macOS accessibility knowledge topics #3158’s testing.ax-probes procedure: exercise JS ref.current.focus()/blur() separately from Tab/Shift-Tab. In chore: merge up to 0.83-stable branch #2824 you explicitly flagged that focus path as something an upstream refactor might affect; the new probe procedure currently covers keyboard focus, not the JS ref path.

The first looks like a new topic; the second could be a small addition to testing.ax-probes if you think it belongs in scope.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Saad Najmi (Saadnajmi) · 2026-10-29T20:49:39Z

+        run: node --test .agents/knowledge/tools/knowledge.test.mts
+
+      - name: Lint agent knowledge Markdown
+        run: yarn markdownlint-cli2 --no-globs AGENTS.md ".agents/knowledge/**/*.md" ".agents/skills/rnmacos-*/**/*.md" .github/copilot-instructions.md


Did we already have this dependency elsewhere?

Saad Najmi (Saadnajmi) · 2026-10-29T20:52:09Z

+## Commands
+
+```sh
+node .agents/knowledge/tools/knowledge.mts index --write
+node .agents/knowledge/tools/knowledge.mts check
+node --test .agents/knowledge/tools/knowledge.test.mts
+yarn markdownlint-cli2 --no-globs AGENTS.md ".agents/knowledge/**/*.md" ".agents/skills/rnmacos-*/**/*.md" .github/copilot-instructions.md
+yarn exec prettier --check path/to/changed/files
+```
+
+- Run `index --write` a second time and confirm it reports no changes.
+- Pass Prettier only the files that have a pragma: topics, skill files, the Copilot pointer, `taxonomy.yaml`, and the `.mts` tools. `AGENTS.md` and `index.md` have none.
+- Run `node --test` only when you changed `knowledge.mts` or its tests.
+- CI runs `check --ci`, which ignores untracked files. Stage new files and run it before you push.
+
+## Telling new failures from old ones


Non blocking: Since this is a non trivial set of commands, I wonder if a small CLI with --help might help keep in sync? That might be over complicating it.

Saad Najmi (Saadnajmi) · 2026-10-29T20:54:55Z

+## Pitfalls
+
+- A PR from a `changeset-release/` branch is the version bump itself and skips the Changeset check.
+
+## Verify


One pitfall is adding "macos" to scope. This is the macOS firk, so nearly all changes have macOS as scope.

Saad Najmi (Saadnajmi) · 2026-10-29T20:55:57Z

+
+## Rules
+
+- **testing.rntester-macos.build-like-ci:** Install Pods with `RCT_NEW_ARCH_ENABLED=1` and build through `.ado/scripts/xcodebuild.sh`, as CI does. Report the exact commands you ran and their result.


We're past 0.81, where the old arch is gone, so this flag is useless. Unless some tooling depends on it, I think this is not true.

Saad Najmi (Saadnajmi) · 2026-10-29T20:57:09Z

+
+## Facts
+
+- CI builds three schemes on a `macos-26` runner: `RNTester-macOS` (`macosx`), `RNTester` (`iphonesimulator`), and `RNTester-visionOS` (`xrsimulator`). It builds them but runs no native tests.


We aim to have the latest available runner, which at time of writing was macos-26. It might even be ideal to test against multiple xcode versions but I don't want to increase the matrix that much. Speaking of.. might be good to have some dependabot style PR update our macOS image, but out of scope.

Saad Najmi (Saadnajmi) · 2026-10-29T20:58:40Z

+- Each scheme builds with static libraries and with `USE_FRAMEWORKS=dynamic`. Dynamic builds are still in progress and don't fail the check.
+- The wrapper passes `CODE_SIGNING_ALLOWED=NO`, writes derived data next to the workspace, and installs `xcbeautify` with Homebrew if it's missing. Set `USE_CCACHE=1` to build through ccache.
+- The Podfile needs cmake and installs it with Homebrew if it's missing. It builds for iOS, macOS, and visionOS.
+- The macOS example list re-exports the iOS list, so an example added to the iOS list also appears on macOS.


Yeah.. this feels a bit too specific. We borrowed react-native-test-apps' script here to run xcodebuild, but really the goal was just to have a repeatable way to run xcodebuild with some flags or args The particulars of the script shouldn't matter, if anything we should infer from what CI is running rather than encode in skill docs that can go stale.

Saad Najmi (Saadnajmi) · 2026-10-29T20:59:07Z

+## Pitfalls
+
+- After you change native dependencies or switch branches, run `pod install` again before building.
+- A green macOS build doesn't prove iOS or visionOS still compile. When you change shared Apple code, build the `RNTester` scheme with `iphonesimulator` too.


Cocoapods will eventually go away for SPM, so maybe "If building with cocoapods"

Saad Najmi (Saadnajmi) · 2026-10-29T21:01:30Z

+if (
+  process.argv[1] &&
+  fileURLToPath(import.meta.url) === path.resolve(process.argv[1])
+) {
+  process.exitCode = main(process.argv.slice(2));
+}


Normally I wouldn't comment on the AI script but I guess if 1700 lines, is it very necessary? Not blocking we can keep it. If the world changes and we move from knoweldge graphs to something else, I guess this code is disposable

Saad Najmi (Saadnajmi) · 2026-10-29T21:02:31Z

+budgets:
+  warn_ratio: 0.8
+  agents_fork_block: {lines: 60, bytes: 4096}
+  agents_total: {lines: 150, bytes: 12288}
+  tier0: {bytes: 16384}
+  copilot_pointer: {lines: 8}
+  instructions_pointer: {lines: 12, bytes: 1024}
+  index: {lines: 100}
+  topic: {lines: 150, bytes: 8192}
+  skill: {lines: 150, bytes: 6144}
+  reference: {lines: 200, bytes: 10240}
+  skill_description: {warn: 400, max: 1024}
+
+skill_budgets:
+  rnmacos-organize-knowledge: {lines: 80}


What's going on with this file? When did we become an accounting firm?

Saad Najmi (Saadnajmi) · 2026-10-29T21:02:46Z

+## Procedure
+
+1. Step one. Load `references/reference-name.md` only when this step needs it, and link to it.
+2. Step two.


Saad Najmi (Saadnajmi)

Left some comments, mostly ok. I feel I won't "feel" the workflow till I start using it so I'm more wanting to just try it and iterate I think

Jason Morse (JasonVMo) mentioned this pull request Oct 29, 2026

feat(agents): add macOS accessibility knowledge topics #3158

Open

Jason Morse (JasonVMo) marked this pull request as ready for review October 29, 2026 06:44

Jason Morse (JasonVMo) requested a review from a team as a code owner October 29, 2026 06:44

Jason Morse (JasonVMo) added this pull request to stack #3159 October 29, 2026 06:44

Vladimir Morozov (vmoroz) approved these changes Oct 29, 2026

View reviewed changes

Copilot started work on behalf of Saad Najmi (Saadnajmi) October 29, 2026 17:19

View session

Copilot finished work on behalf of Saad Najmi (Saadnajmi) October 29, 2026 17:24

Copilot AI requested a review from Saad Najmi (Saadnajmi) October 29, 2026 17:24

docs(agents): add upstream-sync forward-port checklist

f16d0f1

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Saad Najmi (Saadnajmi) reviewed Oct 29, 2026

View reviewed changes


		## Rules

		- testing.rntester-macos.build-like-ci: Install Pods with `RCT_NEW_ARCH_ENABLED=1` and build through `.ado/scripts/xcodebuild.sh`, as CI does. Report the exact commands you ran and their result.


		## Facts

		- CI builds three schemes on a `macos-26` runner: `RNTester-macOS` (`macosx`), `RNTester` (`iphonesimulator`), and `RNTester-visionOS` (`xrsimulator`). It builds them but runs no native tests.

Conversation

Jason Morse (JasonVMo) commented Oct 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary:

Test Plan:

Uh oh!

Saad Najmi (Saadnajmi) commented Oct 29, 2026

Uh oh!

Copilot AI commented Oct 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Saad Najmi (Saadnajmi) left a comment

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Jason Morse (JasonVMo) commented Oct 29, 2026 •

edited

Loading