Design First

Design the shape before writing the code. The pass ends in a design sketch the user approves; implementation does not start until it does. Aim for deep modules placed at clean seams — so callers get leverage, maintainers get locality, and tests get a surface to push against.

This is a design pass, not an implementation plan. Decide what shape the code takes and why; leave line-level rules to code-guidelines and test structure to test-guidelines.

When to run

Run for work where the shape is a real decision:

• A new feature or a new integration
• A change to the public barrel (packages/core/src/js/index.ts) or a public option in options.ts — it cascades to every downstream user and the API report
• A change to a codegen spec (src/js/NativeRNSentry.ts, *NativeComponent.ts) or anything crossing the JS↔native bridge — the ABI must move in lockstep across JS/iOS/Android
• Any moment you are choosing where a seam goes, or how a module is shaped to be testable

Skip it — and say you are skipping it — for one-line fixes, localized bug fixes with obvious placement, and refactors that change no interface.

Vocabulary

Use these terms exactly in the sketch — consistent language is what makes the design legible across sessions. Don't substitute "component," "service," or "layer."

• Module — anything with an interface and an implementation: a function, a factory, a class, a file.
• Interface — everything a caller must know to use it correctly: the signature, plus invariants, ordering, error modes, required config.
• Deep module — a lot of behavior behind a small interface. The goal. A shallow module has an interface nearly as complex as its implementation — avoid it.
• Seam — the place where you can swap behavior without editing in that place. Where an interface lives, and where a test double crosses. In this SDK the biggest seam is the NATIVE wrapper (src/js/wrapper.ts) between JS and native.
• Adapter — a concrete thing satisfying an interface at a seam.

Two checks settle most design questions:

• The deletion test. Imagine deleting the module. If complexity vanishes, it was a pass-through — don't build it. If complexity reappears across N callers, it earns its keep.
• The interface is the test surface. Callers and tests cross the same seam. If you need to test past the interface, the module is the wrong shape.

The design pass

1. Frame the change

State the behavior the change introduces, in the domain's own words. Name the surface(s) it lands in — JS, Android, iOS, bridge — and read the relevant AGENTS.md (root, packages/core/, packages/core/android/, packages/core/ios/).

Find the nearest well-shaped precedent and align to it. The codebase has almost certainly solved something adjacent — locate its best current example and match it, or improve on it deliberately and say why. The TurboModule subsystem (turbomodule/ + thin integrations/turboModuleContext*.ts wiring) is a strong precedent for a cohesive feature that touches JS, native, and the bridge; the integration factory in integrations/nativelinkederrors.ts is the precedent for a plain JS integration.