Overview

As discussed, here is a starting point for an AGENTS.md file for the JavaScriptKit repo. The goal is to give AI coding agents enough context to contribute without needing to cross-reference CONTRIBUTING.md or reverse-engineer the codebase structure.

This is a draft - let's add what's missing and iterate on it here.

Notes

The file covers:

• Project structure and source code layout - the dual-package architecture with symlinks between Sources/BridgeJSTool/ and Plugins/BridgeJS/Sources/, quick path reference table
• BridgeJS codegen pipeline - all three stages (SwiftToSkeleton, ExportSwift/ImportTS, BridgeJSLink), the skeleton IR concept, JS conversion directions
• Import and export sides - macro system (@JS for exports, @JSFunction/@JSGetter/@JSSetter/@JSClass for imports), CallJSEmission builder pattern
• Wasm ABI - three ABI strategies (value return, stack, side channel), type mapping table, parameter passing conventions, error handling (both directions), closure lifecycle
• Workflows - before-committing checklist (from CI config), per-area build/test commands, regeneration steps, adding intrinsics
• Testing - snapshot test flow with correct paths (BridgeJSCodegenTests, Inputs/MacroSwift/), E2E test setup
• Adding new types - 10-step checklist from skeleton to docs
• Common pitfalls - toolchain, stack ordering, shared snapshots, tmpRetTag overwrite