Imported from celsowm/gbc-to-md (AGENTS.md). Install upstream with npx skills add celsowm/gbc-to-md. Copyright stays with the author.

AGENTS.md

This file defines repository-wide rules for coding agents and automated contributors.

Project goal

gbc-to-md explores a static-recompilation path from Game Boy / Game Boy Color software generated by gbrecomp to Sega Mega Drive / Genesis software built with SGDK. It is not a cycle-accurate emulator and should not silently grow into one.

Non-negotiable rules

1. Keep source code, comments, documentation, commit messages, test output added to the repo, and user-facing scripts in English.
2. Never commit commercial ROMs, copyrighted game assets, save files, or generated ports of commercial games.
3. Do not commit .deps/, build/, generated *.gb fixtures, generated gbrecomp trees, SGDK staging trees, or final ROM binaries.
4. Keep external dependency versions centralized in versions.env; do not duplicate version strings across workflows and scripts unless technically unavoidable.
5. Use the bootstrap scripts instead of vendoring third-party binaries.
6. Preserve the framebuffer-free design. The Mega Drive backend should translate guest hardware state to SGDK/VDP primitives rather than introduce a full software framebuffer.
7. Preserve the distinction between guest cartridge banking (MBC1/MBC3/MBC5) and physical Mega Drive far-ROM banking.
8. Do not claim emulator/hardware compatibility unless the relevant test, cross-link, and boot evidence actually exists.
9. Prefer deterministic synthetic fixtures for new hardware behavior. Add a fixture generator plus an automated assertion before adding game-specific compatibility code.
10. Keep target-only state small. Re-check GBContext + GBMDBackend whenever a change adds persistent arrays or large fields.

Before changing code

Read:

• README.md
• docs/ARCHITECTURE.md
• docs/COMPATIBILITY.md
• docs/TESTING.md

For mapper, SRAM, timing, or far-ROM changes, also read the relevant sections in docs/ARCHITECTURE.md and docs/BUILDING.md.

Required validation

For normal runtime/backend changes:

make test
make syntax-test

For interrupt/timer changes:

make irq-test
make timer-test
make cake-test

For mapper or cartridge-memory changes:

make mbc1-test
make mbc3-test
make mbc5-test
make syntax-test

For broad changes, run:

make verify-ci

Run make verify when changing generated-code scale, ROM-blob handling, or benchmark/reporting code.

For SGDK build-system changes, run at least the host syntax gates and, when a Linux toolchain is available:

make sgdk
make sgdk-mbc5

Generated-code policy

gbrecomp output belongs under build/generated/<fixture>/ and is disposable. If target sanitization needs to change, modify tools/prepare_sgdk_generated.py; do not hand-edit generated C and commit it.

Large retained ROMs must be linked with the .incbin path produced by tools/make_sgdk_rom_blob.py. Do not reintroduce multi-megabyte C byte arrays into the target build.

Style

• C: C11, warnings enabled, no unnecessary heap allocation in target runtime code.
• Python: standard library first; scripts should work with the system Python used by GitHub Actions.
• Shell: Bash with set -euo pipefail; quote paths; fail with actionable messages.
• Make: public targets should be documented by make help.
• Keep functions small when practical, but do not split hot runtime paths merely for stylistic reasons.

Commit hygiene

Keep commits focused and descriptive. Do not rewrite public history. Do not mix large formatting-only changes with behavior changes unless the formatting change is the purpose of the commit.