Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 134 additions & 0 deletions .agents/scripts/check-guidance.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path';
import { fileURLToPath } from 'node:url';
import { parseDocument } from 'yaml';

// An optional root lets validation be exercised on isolated fixtures.
const root = resolve(process.argv[2] ?? fileURLToPath(new URL('../../', import.meta.url)));
const skillsDir = resolve(root, '.agents/skills');
const errors = [];
const fail = (file, message) => errors.push(`${relative(root, file)}: ${message}`);

function markdownFiles(directory) {
return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
const path = resolve(directory, entry.name);
return entry.isDirectory() ? markdownFiles(path) : entry.name.endsWith('.md') ? [path] : [];
});
}

// Ignore code examples, including indented fences inside Markdown lists.
function prose(content) {
let fence;
return content
.split('\n')
.filter((line) => {
const marker = line.match(/^\s*(`{3,}|~{3,})(.*)$/);
if (!fence && marker) {
fence = marker[1];
return false;
}
if (fence) {
if (
marker &&
marker[1][0] === fence[0] &&
marker[1].length >= fence.length &&
!marker[2].trim()
) {
fence = undefined;
}
return false;
}
return true;
})
.join('\n');
}

const files = markdownFiles(skillsDir);
files.push(resolve(root, 'AGENTS.md'));
const names = new Set();
let skills = 0;

for (const file of files) {
if (!existsSync(file)) {
fail(file, 'file is missing');
continue;
}
let content = readFileSync(file, 'utf8');
if (basename(file) === 'SKILL.md') {
skills++;
const header = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
if (!header) {
fail(file, 'missing YAML frontmatter');
} else {
const document = parseDocument(header[1]);
for (const error of document.errors) fail(file, `invalid YAML: ${error.message}`);
if (!document.errors.length) {
const data = document.toJS();
if (!data || typeof data !== 'object' || Array.isArray(data)) {
fail(file, 'frontmatter must be a mapping');
} else {
const { name, description, metadata } = data;
if (
typeof name !== 'string' ||
name.length > 64 ||
!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name) ||
name !== relative(skillsDir, dirname(file))
) {
fail(
file,
'name must match its skill directory and use lowercase letters/digits/hyphens'
);
}
if (names.has(name)) fail(file, `duplicate skill name: ${name}`);
names.add(name);
if (typeof description !== 'string' || !description.trim() || description.length > 1024) {
fail(file, 'description must be a nonempty string of at most 1024 characters');
}
if (
metadata !== undefined &&
(!metadata ||
typeof metadata !== 'object' ||
Array.isArray(metadata) ||
Object.values(metadata).some((value) => typeof value !== 'string'))
) {
fail(file, 'metadata must be a mapping of string values');
}
}
}
content = content.slice(header[0].length);
}
}

// Repository guidance uses inline Markdown links with simple local paths. External URLs and
// anchors are not fetched. Code spans are left intact so links with code-formatted labels work.
for (const match of prose(content).matchAll(/\[[^\]\n]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g)) {
const target = match[1].replace(/^<|>$/g, '');
if (/^(?:[a-z][a-z\d+.-]*:|#)/i.test(target)) continue;
const path = target.split(/[?#]/)[0];
if (!path) continue;
let decoded;
try {
decoded = decodeURIComponent(path);
} catch {
fail(file, `invalid URL encoding: ${target}`);
continue;
}
const destination = resolve(dirname(file), decoded);
const fromRoot = relative(root, destination);
if (isAbsolute(decoded) || fromRoot === '..' || fromRoot.startsWith(`..${sep}`)) {
fail(file, `local link must stay within the repository: ${target}`);
} else if (!existsSync(destination) || !statSync(destination).isFile()) {
fail(file, `missing local file: ${target}`);
}
}
}

if (!skills) fail(skillsDir, 'no skills found');
if (errors.length) {
console.error(errors.join('\n'));
process.exitCode = 1;
} else {
console.log(
`Validated ${skills} contributor skills and local links in ${files.length} Markdown files.`
);
}
15 changes: 3 additions & 12 deletions .agents/skills/README.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,5 @@
# Development Skills Directory
# Contributor skills

This directory contains specialized skills (recipes) to guide contributors and AI coding assistants in extending the codebase cleanly and consistently.
Task-specific procedures for contributing to React Native ExecuTorch live in each skill's `SKILL.md`.

## Available Skills

- [Core Guidelines](./core-guidelines/SKILL.md) — Symmetrical architecture, conventions, and model rules.
- [Add Native Extension](./add-native-extension/SKILL.md) — C++ operations and JSI bindings.
- [Add Task Pipeline](./add-task-pipeline/SKILL.md) — TypeScript task pipelines and React hooks.
- [Model Schema Validation](./model-schema-validation/SKILL.md) — Model specs, dynamic shapes, and schema validation.
- [Error Handling](./error-handling/SKILL.md) — Error codes, throwing across worklet and JSI boundaries, and catching.
- [Add API Tests](./add-api-tests/SKILL.md) — TypeScript API test suites and the fake native runtime.
- [Verify and Build](./verify-and-build/SKILL.md) — TypeScript typechecking, native rebuilding, and troubleshooting.
- [Skills Maintenance](./skills-maintenance/SKILL.md) — Keeping skills synchronized with core primitives.
Start with the root [AGENTS.md](../../AGENTS.md) for setup, task routing, and verification commands.
42 changes: 23 additions & 19 deletions .agents/skills/add-api-tests/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,18 +8,22 @@ metadata:

# Skill: Add TypeScript API Tests

Every change under `src/` belongs in the Jest suites at
Behavior changes under `src/` should be covered by the Jest suites at
[`packages/react-native-executorch/__tests__/`](../../../packages/react-native-executorch/__tests__/README.md).
They run on a laptop or a CI runner — no simulator, no device, no `.pte` — and
finish in a few seconds.
finish in a few seconds. Reuse existing coverage for comments or changes with no observable behavior;
do not add tests that merely restate the implementation. Fake-runtime tests exercise TypeScript logic,
not production C++ or actual delegated model inference.

```bash
yarn workspace react-native-executorch test
yarn workspace react-native-executorch test __tests__/tasks # one directory
yarn workspace react-native-executorch test -u # update snapshots
```

Types come along for free: `yarn typecheck` already covers `__tests__/`.
From the repository root, `yarn workspace react-native-executorch typecheck` includes `__tests__/`.
Root `yarn typecheck` also builds and checks other workspaces; see the
[verification matrix](../verify-and-build/SKILL.md#verification-matrix).

---

Expand Down Expand Up @@ -49,19 +53,19 @@ expect(await runner.runTask(imageBuffer(8, 8))).toEqual(/* ... */);

Key helpers:

| Helper | Use |
| :--- | :--- |
| `fakeJsi.registerModel(path, program)` | Make `loadModel(path)` succeed with a given schema and `execute` |
| `fakeJsi.registerTokenizer(path, vocabulary)` | Same for `loadTokenizer` |
| `fakeJsi.registerLLMRunner(path, program)` | Same for `createLLMRunner`: a context window and the responses to generate, one per `generate` call |
| `fakePhonemizer.serve(text, phonemes)` | Script the native grapheme-to-phoneme converter |
| `fakeFs.write(path, contents)` | Put a file where a pipeline will read it (a charset, a `tokenizer_config.json`, a voice matrix) |
| `exported(spec)` | Reinterpret a spec built with `method`/`f32`/`i64` as an *exported* one (it verifies no symbolic dims are left) |
| `writesOutputs(...)`, `copiesInputToOutput()` | Ready-made `execute` implementations |
| `tracked(pipeline)` | Auto-dispose at the end of the test |
| `imageBuffer(w, h, format)` | A deterministic input image |
| `cachePathFor(url)` | Where the fetcher will download a URL, so a hook test can register its model up front |
| `fakeNet.serve(url, route)` | Script the server: status, body, `Range` support, and a `gate` to hold a download open |
| Helper | Use |
| :-------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| `fakeJsi.registerModel(path, program)` | Make `loadModel(path)` succeed with a given schema and `execute` |
| `fakeJsi.registerTokenizer(path, vocabulary)` | Same for `loadTokenizer` |
| `fakeJsi.registerLLMRunner(path, program)` | Same for `createLLMRunner`: a context window and the responses to generate, one per `generate` call |
| `fakePhonemizer.serve(text, phonemes)` | Script the native grapheme-to-phoneme converter |
| `fakeFs.write(path, contents)` | Put a file where a pipeline will read it (a charset, a `tokenizer_config.json`, a voice matrix) |
| `exported(spec)` | Reinterpret a spec built with `method`/`f32`/`i64` as an _exported_ one (it verifies no symbolic dims are left) |
| `writesOutputs(...)`, `copiesInputToOutput()` | Ready-made `execute` implementations |
| `tracked(pipeline)` | Auto-dispose at the end of the test |
| `imageBuffer(w, h, format)` | A deterministic input image |
| `cachePathFor(url)` | Where the fetcher will download a URL, so a hook test can register its model up front |
| `fakeNet.serve(url, route)` | Script the server: status, body, `Range` support, and a `gate` to hold a download open |

---

Expand All @@ -70,7 +74,7 @@ Key helpers:
1. **Schema acceptance** — one test per variant the pipeline declares
(`batched`, `unbatched`, ...), asserting the factory resolves.
2. **Schema rejection** — a model that matches no variant, asserting the error
names the mismatch (`Rank mismatch`, `inconsistent bindings`, ...). A caller
has code `SCHEMA_MISMATCH` and describes the mismatch (`Rank mismatch`, `inconsistent bindings`, ...). A caller
should learn what is wrong from the message.
3. **Configuration mismatch** — e.g. a `labels` array that disagrees with the
model's output dimension.
Expand All @@ -80,14 +84,14 @@ Key helpers:
5. **Options** — every default in `modelOpts`, and every per-call override.
6. **Disposal** — `dispose()` leaves `fakeJsi.liveTensors()` at 0 and
`fakeJsi.liveModels()` empty, and repeated calls do not accumulate scratch
tensors. The same has to hold when construction *fails*: allocate through a
tensors. The same has to hold when construction _fails_: allocate through a
`createResourceScope()` and wrap the factory body in `try`/`catch` so a
schema mismatch releases the model instead of stranding it. Add the factory
to `__tests__/tasks/constructionFailure.test.ts`, which drives every one of
them.
7. **Sync/async parity** — `runTaskWorklet(x)` equals `await runTask(x)`.

Only the *weights* are out of scope, not the pipeline that runs on them. Before
Only the _weights_ are out of scope, not the pipeline that runs on them. Before
settling for schema-acceptance-and-disposal, check what is actually TypeScript:
a decode loop, a sliding window, a chunker, an argument check, a streaming
generator and a disposal path all run fine over a scripted `execute`. Reach for
Expand Down
30 changes: 19 additions & 11 deletions .agents/skills/add-native-extension/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
---
name: add-native-extension
description: Use when adding a C++ extension, writing native JSI host functions, registering functions in C++ install maps, or compiling native code.
description: Use when implementing native C++ operations, exposing them through JSI, or updating domain installation and TypeScript wrappers. For build/debug workflows use verify-and-build.
metadata:
id: add_native_extension
scope: cpp/extensions/*, src/extensions/*
scope: packages/react-native-executorch/cpp/extensions/*, packages/react-native-executorch/src/extensions/*
---

# Skill: Add a Native C++ Extension & JSI Bindings
Expand All @@ -17,7 +17,9 @@ Use this guide to add custom, performance-critical native operations in C++ and
Before writing any C++ code, ensure you adhere to the following principles:

1. **Amdahl's Law & Premature Optimization**:
- Evaluate what percentage of total inference/pipeline time the processing step occupies. If the preprocessing/postprocessing step takes `< 5%` of the total inference budget, write it in **pure TypeScript** to reduce codebase complexity and maintenance overhead.
- Prefer existing operations and TypeScript orchestration. Add native code when a missing platform
capability, memory/threading requirement or measured bottleneck justifies it. Record relevant
measurements when performance is the reason; there is no universal percentage cutoff.

2. **Destination Tensors & Local Memory**:
- **Local Memory is Allowed**: You can allocate temporary native C++ memory (such as stack variables, `std::vector`s, or dynamic memory cleaned up before the function exits) for intermediate calculations.
Expand Down Expand Up @@ -129,7 +131,7 @@ namespace rnexecutorch::extensions::<domain>

---

### Step 2: Register in Extension and Core JSI Installs
### Step 2: Register the Operation and, If New, Its Domain

1. **Extension Register** (`cpp/extensions/<domain>/install.cpp`):

Expand All @@ -148,7 +150,7 @@ namespace rnexecutorch::extensions::<domain>
}
```

2. **Core Register** ([cpp/RnExecutorch.cpp](../../../packages/react-native-executorch/cpp/RnExecutorch.cpp)):
2. **New domain only** ([cpp/RnExecutorch.cpp](../../../packages/react-native-executorch/cpp/RnExecutorch.cpp)):
```cpp
#include "extensions/<domain>/install.h"
// ... inside rnexecutorch::install ...
Expand All @@ -161,7 +163,9 @@ namespace rnexecutorch::extensions::<domain>

**Where the wrapper file goes — general vs. model-specific ops:**

- **Domain-general ops** (reusable across every task in the domain, e.g. `image_ops`, `box_ops`) go in the domain's shared op files (`src/extensions/<domain>/ops.ts`), re-exported from `src/extensions/<domain>/index.ts`.
- **Domain-general ops** go in the domain's existing shared op layout, re-exported from its `index.ts`.
For example, CV uses `src/extensions/cv/ops/image.ts` and `ops/box.ts`; inspect the domain before
creating a new `ops.ts`.
- **Model- or task-specific ops** (only meaningful to one model/pipeline, e.g. FSMN-VAD framing) **must** go under `src/extensions/<domain>/utils/<name>.ts` — one file per model/task, named for it (e.g. `vadUtils.ts`, `supertonicUtils.ts`). Keep them out of the shared `ops.ts` so it stays a home for genuinely reusable ops, and group each model's helpers together under `utils/`. Re-export them from the domain `index.ts` too so power users can reach them.

Then, in that wrapper file:
Expand All @@ -172,8 +176,9 @@ Then, in that wrapper file:
- Mark wrapper functions with the `"worklet";` directive.

```typescript
import { rnexecutorchJsi } from '../native/bridge';
import { type Tensor } from '../core/tensor';
// For src/extensions/<domain>/ops.ts; adjust depth for nested ops/<name>.ts.
import { rnexecutorchJsi } from '../../native/bridge';
import { type Tensor } from '../../core/tensor';

/**
* Applies a custom operation scaling the src tensor by factor.
Expand All @@ -193,7 +198,7 @@ export function customOp(src: Tensor, dst: Tensor, factor: number = 1.0): Tensor

When adding a native extension, verify that:

- [ ] You only implemented in C++ if the operation takes `> 5%` of the total inference budget.
- [ ] A native capability or measured performance/memory/threading need justifies the C++ implementation.
- [ ] No JSI Tensors are implicitly allocated and returned in the C++ code.
- [ ] Input and output tensors are extracted and validated using `tensor::fromJs` with strict expected `DType` and shape constraints where possible.
- [ ] Primitive arguments are extracted and converted using `conversions::asType<T>`.
Expand All @@ -203,7 +208,10 @@ When adding a native extension, verify that:
- [ ] Every failure is raised through a factory, `error::X(message)`; no raw `jsi::JSError` / `std::runtime_error` / `std::invalid_argument` was introduced.
- [ ] The host function is registered through `error::guarded(fnBody)`, not a bare `fnBody`.
- [ ] `#include "core/error.h"` and the `namespace error = ...` alias sit at file scope, outside any `#if defined(__ANDROID__)` / `#elif defined(__APPLE__)` branch.
- [ ] The custom operation install function is registered in both the domain `install` function and core [cpp/RnExecutorch.cpp](../../../packages/react-native-executorch/cpp/RnExecutorch.cpp).
- [ ] The TypeScript wrapper lives in the right place: domain-general ops in the shared `ops.ts`, model-/task-specific ops under `src/extensions/<domain>/utils/<name>.ts`.
- [ ] The operation is registered in the domain install; a new domain is registered in [cpp/RnExecutorch.cpp](../../../packages/react-native-executorch/cpp/RnExecutorch.cpp).
- [ ] The TypeScript wrapper follows the domain's existing shared op or task utility layout.
- [ ] The TypeScript wrapper imports and uses `rnexecutorchJsi` instead of the global `__rnexecutorch_jsi__`.
- [ ] The TypeScript wrapper is marked with the `"worklet";` directive and defines all default parameter values.

Use [error handling](../error-handling/SKILL.md) for error-code/guard conventions and
[verify and build](../verify-and-build/SKILL.md#verification-matrix) for static, host and device checks.
Loading
Loading