6502-skills

How to read and write 6502/65C02/65816 assembly source for the Merlin macro assembler (Merlin 8, Merlin Pro, Merlin 16/16+, Merlin 32 on Apple II/IIgs, and Merlin 64/128 on Commodore). Covers Merlin's source column layout, its pseudo-opcodes/directives (ORG, EQU, DFB, DW, DDB, DCI, ASC, HEX, DS, LUP, DO/FIN, MAC/EOM), the macro system and parameters (]1..]8), label and variable conventions (:local, ]var), expression operators and Merlin's left-to-right evaluation, the low/high/bank byte-select operators, and forced addressing. Use this skill WHENEVER you encounter, write, or port Merlin-format assembly source, see Merlin directives like DFB/DCI/LUP/MAC/EOM/PUT, see labels like ]LOOP or :SKIP, or need to understand a .S Merlin listing. Especially trigger when the user mentions Merlin, or asks why an assembler expression evaluates oddly (left-to-right!), or how a macro expands. Pairs with the 6502-instruction-set, 6502-memory-map, and 6502-to-rust skills.

Reference and semantics for the MOS 6502 / 65C02 / 65816 instruction set: mnemonics, addressing modes, opcode bytes, cycle counts, and exact flag effects. Use this skill WHENEVER you read, write, disassemble, trace, explain, or port 6502-family assembly (including Apple II, Commodore, NES, Atari, BBC Micro code), or when you need to know what an instruction does to the registers, status flags, or memory. Trigger on questions like "what does this 6502 routine do", "what flags does ADC set", "is this a 65C02 instruction", "trace this assembly", or any opcode/mnemonic (LDA, STA, JSR, ROL, BIT, SWEET16 excepted) appearing in a file. Pairs with the 6502-merlin-assembler, 6502-memory-map, and 6502-to-rust skills.

Memory maps, I/O register layouts, ROM entry points, and zero-page conventions for the main 6502 home computers: the Apple II family, the Commodore 64, and the Atari 400/800/XL/XE. Covers Apple II soft switches ($C000-$C0FF), language card, Monitor ROM and Applesoft FP; C64 6510 $00/$01 banking, VIC-II/SID/CIA and the KERNAL table ($FFD2 CHROUT); and Atari ANTIC/GTIA/POKEY chips, shadow registers, CIO/SIO and the $E450 OS vectors. Use this skill WHENEVER you need to know what a memory address or hardware register means on an Apple II, C64, or Atari, what a soft switch or ROM routine does, where the screen/zero page/stack are, or how banking works. Trigger on addresses like $C050, $FDED, $D020, $FFD2, $D40A, $E456, on names like COUT/CHROUT/CIOV/POKEY/FAC, or any "what is at address X" / "what does this poke/STA do to hardware" question. Pairs with the 6502-instruction-set, 6502-merlin-assembler, 6502-sweet16, and 6502-to-rust skills.

Reference for SWEET16, Steve Wozniak's 16-bit interpreted pseudo-processor built into the Apple II Integer BASIC ROM (entry $F689). SWEET16 is a tiny virtual machine with sixteen 16-bit registers (R0-R15) living in zero page, invoked by JSR SWEET16 followed by inline bytecode and terminated by RTN. Use this skill WHENEVER you see a JSR $F689 (or JSR SWEET16) followed by data bytes, encounter SWEET16 mnemonics (SET, LDD, STD, POP, STP, CPR, BNC, RTN, BS/RS), need to disassemble or trace SWEET16 bytecode, or are porting Apple II code that drops into SWEET16 for compact 16-bit pointer math and block moves. Trigger on "what is SWEET16", "$F689", inline bytecode after a JSR, or 16-bit register ops like "SET R1" / "LDD @R1". Pairs with the 6502-instruction-set, 6502-memory-map, and 6502-to-rust skills.

A workflow for porting 6502/65C02/65816 assembly (Apple II, Commodore 64, Atari 8-bit, NES, Merlin source, SWEET16) to modern Rust by first lifting it to an explicit intermediate language (IL) and then raising that IL to idiomatic Rust. Covers the two-stage method (faithful flag-explicit lift → idiom recovery → emit), modeling A/X/Y/flags/memory, translating carry/overflow/BCD correctly, recognizing idioms (16-bit math, multiply, pointer loops, jump tables), and mapping ROM/hardware calls. Use this skill WHENEVER the user wants to port, translate, convert, reimplement, decompile, or "rewrite in Rust/a modern language" any 6502-family assembly or disassembly, or asks how a 6502 routine would look in Rust, or how to build an intermediate representation of 6502 code. Trigger on "port this assembly to Rust", "convert this 6502 routine", "reimplement this Apple II code". Pairs with the 6502-instruction-set, 6502-merlin-assembler, 6502-memory-map, and 6502-sweet16 skills.