Neo Geo ROM rewrite

Default invocation contract: ROM + BIOS in, running game out

When the user supplies a game ROM, Neo Geo BIOS and invokes this skill, treat that as a request to execute the rewrite end to end. Do not merely describe how to do it or return an inventory, plan, scaffold or prototype. Produce a runnable source project, launch it locally, verify actual gameplay in the browser, and hand over the working URL and repeatable launch command.

Default to a local browser game, the current workspace, TypeScript/Vite and original artwork unless the user or existing project specifies otherwise. In an unrelated or nonempty workspace, choose a clearly named subdirectory without overwriting existing files. Select an available local port. The user need not choose a framework, driver, memory layout, extraction strategy or implementation order.

This is an autonomous agent workflow, not an automatic ROM converter. Investigation and incremental implementation are how to reach the deliverable, not substitute deliverables. An emulator is a reference tool; embedding one instead of rewriting the game does not satisfy this request.

Read [delivery.md](references/delivery.md) for autonomous execution, persistent checkpoints and the running-game handoff. A user who explicitly asks only for an assessment, plan or bounded change still gets that narrower task.

Required outcome: 100% original-game fidelity

The default end goal is a complete, behaviorally conformant reconstruction of the selected original ROM revision, region and configuration. “Rewrite” means new maintainable source code with the same original game behavior and content, not a similar game, inspired remake, simplified clone, demonstration or MVP. A browser target changes the execution platform, not the fidelity requirement.

• Match original mechanics, physics, collision geometry/order, input handling, frame/update timing, RNG behavior, rules, scoring, state transitions and observable edge cases, including original quirks. Do not rebalance or “improve” behavior without explicit user approval.
• Reproduce all original characters, stages, moves, specials, enemies/CPU behavior, modes, variants, progression, bonus content, endings and rewards present in the selected scope. Unknown inventory is unresolved work, not permission to omit it.
• Match original artwork, composition/layers, palettes, poses, animation frame counts/holds, effects, HUD/results and audio cues/sequencing/timing. Placeholder assets, look-alike graphics, generic sound effects and approximate physics are temporary gaps, not an acceptable final rewrite.
• Every departure needs a specific user-approved exception recorded in the scope ledger. Do not import exclusions from Windjammers or assume CPU, coin handling or cabinet flow is excluded in another project. An approved exception applies only to the named behavior; removing coins does not remove progression or endings.
• A vertical slice is an implementation milestone only. Keep the full target and remaining backlog visible, and continue authorized work toward it. If time, tooling or missing evidence prevents completion, report the concrete blocker and remaining gaps; never silently redefine the request as a prototype.

Record this fidelity contract in the target project's durable instructions and scope ledger so subsequent agents retain it. User-requested limited investigations or slices remain limited tasks, but completing one does not complete the full rewrite.

100% is the required target, not an automatic claim. Do not report whole-game completion while inventory is unresolved, known differences remain, or original-game acceptance is missing. State approved exceptions alongside any conformance claim. Internal source structure need not copy the machine code, but externally observable behavior must match the reference outside those exceptions.

Input discovery and internal preparation

Accept the supplied game ROM and BIOS paths or attachments. Use a target project if provided; otherwise use the defaults above. If a required BIOS or dependency is missing, check the supplied inputs and established local reference location before asking for that specific missing file. Infer already agreed scope and adaptations from the conversation and repository. Ask only for information or authorization that actually blocks progress, not routine implementation choices.

1. Inspect repository instructions and existing implementation before creating files. Keep ROMs, BIOS files, save states and large raw captures local and ignored. Input access does not itself authorize publishing the ROM or derived assets; follow the user's distribution scope. 2. Run scripts/inventory_rom.py ROM [BIOS] to produce a read-only archive/member hash inventory. It does not identify a driver, decrypt data, or prove compatibility. 3. Discover the installed emulator and verify the exact game/BIOS set against its machine metadata. Record version, region, platform, driver and selected BIOS. Resolve actual required missing members; distinguish unused BIOS alternatives from launch blockers. Do not silently download replacements. 4. Establish two reproducible native launches and a short gameplay input sequence. Retain frame counters, inputs, snapshots and hashes. A boot screen alone does not prove usable controls or reproducibility. 5. As internal working artifacts, write a content inventory, scope ledger, environment manifest and first bounded implementation plan. Include every discovered character, stage, mode, rule variant, animation family, sound family, progression and ending. Unknown content stays unresolved.

Read [native-reference.md](references/native-reference.md) for capture and reverse engineering. Do not copy addresses, refresh periods, state codes, pool sizes or asset formats from another game without verifying them.

Build an executable vertical slice

Prefer one character, one stage and one complete interaction before expanding content. For a browser target, TypeScript plus Vite and Canvas/WebGL is a useful default; use the existing stack when present. Use Python for extraction and normalized fixtures, and emulator scripting/debugger tools for native observations. Check local versions and official documentation before relying on emulator or framework APIs.

Separate deterministic simulation, input sampling, presentation state, renderer, audio and browser UI. Start with original artwork and original timing. Make the slice playable through opening, action, collision and result; do not substitute generic physics for recovered rules.

Follow [runtime-and-assets.md](references/runtime-and-assets.md) for numeric semantics, presentation dependencies and extraction. A pure renderer is desirable, but original presentation bookkeeping can affect gameplay: preserve that state in simulation when evidence requires it.

Expand by evidence, not resemblance

For each feature slice:

• Recover the governing routine, tables and callers; describe any uncertainty.
• Capture a bounded native case before deciding what the browser should do.
• Implement original arithmetic, branch order, state transitions and shared-resource behavior.
• Compare native and browser state at aligned update phases. Investigate the first divergence, not only the final outcome.
• Add meaningful logic regressions and reusable native fixtures. Check original-size motion and relevant device behavior separately.
• Expand across asymmetric sides, roster classes, stages, branch boundaries and lifecycle transitions. Use source analysis to choose the matrix rather than multiplying irrelevant cases.
• Update evidence notes and progress status before reporting completion or committing. Follow repository commit/push/deployment rules; this skill grants no deployment authorization.

Read [acceptance.md](references/acceptance.md) before assigning completion or extending a limited sample to a whole feature. Retain controlled setup, substituted state and observed-frame rendering boundaries explicitly.

Preserve intentional adaptations

Use only adaptations the user has explicitly requested or already approved for this project. Preserve that authorization across turns; do not ask again merely because a new slice begins. Record each exception and its exact scope. Pause, rematch, direct selection, modern controls, different CPU decisions, removed coins or timers, audio approximations and visual remastering are not blanket defaults.

The source Windjammers project approved several browser adaptations. Its choices demonstrate how to document exceptions, not what to exclude from a new rewrite. A request for a browser port alone does not authorize simplification of the original game.

Progression and endings are content, even when arcade access restrictions are removed. Offer browser access to that content. Do not omit it because the first prototype has a match menu.

Add networking, accounts, leaderboards and visual remastering only when requested. Deterministic state and serializable presentation make later rollback possible, but a local rewrite is not already multiplayer-ready.

Working artifacts

Use the project's equivalent locations; a new project can start with:

• roms/, reference/local/: ignored immutable input and raw native captures.
• tools/reference/: reproducible capture, export and normalization tools.
• tests/fixtures/: compact retained observations with provenance.
• src/game/, src/render/, src/audio/, src/input/: separated runtime concerns.
• docs/reference/: source maps, assumptions, coverage and unresolved content.
• A progress ledger, optionally a visual /progress-map, whose counts derive from feature data.

Consult [windjammers-lessons.md](references/windjammers-lessons.md) for concrete failure patterns from the source project. These illustrate the method; they are not defaults for a different ROM.

When reporting a slice, state what now works, which original comparisons establish it, what remains unresolved, and where the evidence lives. Never claim emulation, source translation, controlled sampling and full input replay are interchangeable.