Dreamcast decomp guide

What this system is like

The Dreamcast runs on a Hitachi SH-4 chip. Most games are one boot file, 1ST_READ.BIN, built with Sega's Katana SDK. That makes the code easy to find. In late 2026, a wave of PC ports came out in a few weeks each.

For Path A, every reviewed port used static recompilation. A tool turns the SH-4 code into C or C++. A runtime then stands in for the graphics chip, the sound chip and the disc. You can build on dream-recomp or the Dreamcomp kit, or write your own tool, as SoulCalibur and Street Fighter Alpha 3 did. The Flycast emulator is the judge of right and wrong.

For Path B, the common route is an equivalence decomp. First the boot file is rebuilt byte for byte with the SDK's own assembler. Then each function gets C that a simulator proves acts the same. The dc-decomp-kickoff skill runs this whole plan. It needs a Katana SDK, which Sega never released to the public. You must supply it yourself.

Path A runs on Windows. Path B runs in Docker or in WSL, because the Hitachi tools run there through wibo. You need your own disc dump. No BIOS file is needed for the reviewed recomps.

Two paths

Path A: Get it running on PC

A translator reads the SH-4 code in 1ST_READ.BIN and writes one C++ function per game function. A runtime stands in for the PowerVR2, the AICA sound chip, the pads and the disc. Library calls go to native code or to emulated hardware. You then fix one stop at a time, checking against Flycast. Fixes go in the config or in hooks, never in the machine-made code.

1. Scope the disc and look for prior work

   Pick one game and one exact disc. Check that its code sits in one boot file. Check that it is not a Windows CE game. Search for a port that already exists. Write SCOPE.md and get it approved before any code.

   • Dump your own disc. Keep the image outside any repo, like C:\dcdiscs\mygame.gdi.
   • Get the disc tool first. Run git clone --recurse-submodules https://github.com/phobos665/dream-recomp, then pip install -e dream-recomp/tools/dcdisc. Step 2 builds the rest.
   • Run dcdisc inspect C:\dcdiscs\mygame.gdi -o notes\disc-report.md. Read how many files look like code. One is the easy case.
   • dcdisc inspect exits with code 1 if it finds Windows CE markers. Those games are out of scope for dream-recomp.
   • Run dcdisc manifest C:\dcdiscs\mygame.gdi > notes\disc-manifest.json. It lists the SHA-256 of every file and of the boot file. Copy the boot file's hash into SCOPE.md.
   • Search GitHub and RecompLauncher for the game plus recomp, decomp and port. Check the dream-recomp table too: Crazy Taxi plays there, and five more titles boot.
   • Write SCOPE.md: goal, disc serial, boot file hash, technique, first milestone and its check, out of scope, never edit.
   Prompt for ClaudeCopy

   GOAL: Draft `SCOPE.md` for a PC port of <GAME> (product <PRODUCT_NO>) by static recompilation on `dream-recomp`.
   READ FIRST: `notes/disc-report.md` (from `dcdisc inspect`), the boot file SHA-256 in `notes/disc-manifest.json` (from `dcdisc manifest`), the `dream-recomp` README at https://github.com/phobos665/dream-recomp.
   FENCE: Write only `SCOPE.md` and `notes/prior-work.md`. Do not open, copy or upload any game file. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `grep -cE '^## (Goal|Disc and hash|Technique|Milestone 1|Out of scope|Never edit)' SCOPE.md`. Done means it prints 6, and each line in `notes/prior-work.md` has a URL you opened.
   BUDGET: Stop after 45 minutes of searching.
   IF BLOCKED: If the report shows Windows CE or more than one code file, stop and tell me. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Prior work with URLs. 3) Code files found and what that means. 4) Your recommended base: `dream-recomp`, `Dreamcomp` or your own translator, and why. 5) Questions for me.

   Done whengrep -cE '^## (Goal|Disc and hash|Technique|Milestone 1|Out of scope|Never edit)' SCOPE.md prints 6, the file holds the boot file hash, and its last line is Approved: <date> in your words.

   Proof this works: https://github.com/phobos665/dream-recomp (dcdisc inspect, Windows CE refused, table of titles), https://github.com/phobos665/dream-recomp/blob/main/tools/dcdisc/README.md (pip install -e tools/dcdisc; inspect exit code 1 on Windows CE; manifest hashes), Bomberman Online Recomp (boot file SHA-1 pinned in the TOML and in CI), Army Men: Sarge's Heroes - Recompiled (supported discs picked by boot file SHA-1)

2. Set up the repo, the toolchain and one check

   Make a repo that holds only your own code. The disc and anything taken from it stay outside git. Build dream-recomp and its disc tool. Then write one script that builds and one that checks.

   • Install Build Tools for Visual Studio 2022 with C++, plus CMake, Ninja, Python 3.9 or newer and git. The 2022 tools are on Microsoft's older downloads page now. For a window, add the Vulkan SDK, SDL3 and glslc.
   • In the dream-recomp folder from step 1, build: cmake -S . -B build -DDREAM_DEV_INTERPRETER=ON, then cmake --build build --parallel.
   • Run its tests: ctest --test-dir build --output-on-failure. The disc tool is already installed from step 1.
   • Run dcdisc doctor. It lists what is missing and what is required.
   • Or use Dreamcomp on Windows: python tools/dc.py doctor, then python tools/dc.py deps. It wraps dream-recomp and adds Claude Code skills.
   • Make extracted/, gen/ and build/ ignored. Add a pre-commit hook that refuses .bin, .gdi, .chd, .cdi and generated code. Dreamcomp ships tools/audit.py for this.
   • Write tools/check.py. It checks the boot file hash, builds, runs headless for a set time, and prints PASS or FAIL.
   • Give it the modes later steps use: --hash-only, --boot --seconds N, --test <ID> and --regress. Have --boot save a picture with the run flag --screenshot-at N.
   Prompt for ClaudeCopy

   GOAL: Create the repo layout, the build script and the one check command for the <GAME> port.
   READ FIRST: `SCOPE.md`, `CLAUDE.md`, the `dream-recomp` README sections Requirements and Build the toolchain.
   FENCE: Edit only `tools/`, `.gitignore`, `.githooks/` and `PROGRESS.md`. Never copy anything from the disc or `extracted/` into tracked folders. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python tools/check.py --hash-only`. Done means it prints the expected SHA-256 and PASS. Then run `git status --ignored` and show `extracted/` is ignored.
   BUDGET: Stop after 3 failed tries at the same error.
   IF BLOCKED: If `dcdisc doctor` reports a required tool missing, stop and name it. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output and `dcdisc doctor` output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenpython tools/check.py --hash-only prints PASS, ctest passes in the dream-recomp build, and git status shows no game file as tracked.

   Proof this works: https://github.com/phobos665/dream-recomp (build commands, dcdisc doctor), https://github.com/phobos665/dream-recomp/blob/main/docs/dev-setup.md (--screenshot-at N for a run with nobody at the keyboard), https://visualstudio.microsoft.com/vs/older-downloads/ (Build Tools for Visual Studio 2022), https://github.com/danielgomesvieira2000/dreamcomp (Windows quick start, tools/audit.py), Bomberman Online Recomp and Army Men (no-game-data audit in a pre-commit hook and CI)

3. Extract the boot file and map the code

   The translator finds functions by following calls from the entry point. That finds about 79 to 90% of the code. The rest hides behind jump tables and pointers. Ghidra helps you find it. Mark Katana SDK code, so nobody rewrites it by hand.

   • Set the title up: dcdisc new-game C:\dcdiscs\mygame.gdi. It reads IP.BIN, extracts the files, and writes games/<id>/<id>.toml.
   • Check the TOML: load_address = 0x8C010000, link_address = 0x0C010000, entry = 0x8C010000. These hold for nearly every game.
   • Build once and read the coverage line. It lists the byte runs that are not yet code or data.
   • Load games/<id>/extracted/fs/1ST_READ.BIN in Ghidra as raw binary with language SuperH4:LE:32:default. Bomberman Online says to use the 0x0C... base, not 0x8C....
   • Seed Ghidra with the translator's function list. The Ikaruga port found 2,708 functions alone, and 3,918 with seeds.
   • List Katana library calls in notes/functions.csv: Kamui, Ninja, sound, GD-ROM and pads. Voldorium found about 130 that it replaced with native code.
   • Write tools/validate_map.py. It fails on overlapping rows, on a start inside another function, and on any uncovered run from the build log that has no row.
   Prompt for ClaudeCopy

   GOAL: Produce `notes/functions.csv` for <GAME>: every known function with address, size, library tag and status, plus the uncovered byte runs.
   READ FIRST: `games/<ID>/<ID>.toml`, the coverage line in `logs/build-latest.txt`, Ghidra through the MCP server (read-only).
   FENCE: Write only `notes/functions.csv` and `notes/map-notes.md`. Do not rename, retype or save anything in the Ghidra project. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python tools/validate_map.py notes/functions.csv`. Done means no overlaps, no start inside another function, and every uncovered run from the build log is listed.
   BUDGET: Stop after 2 hours or 3 failed fixes of the same overlap.
   IF BLOCKED: If Ghidra is not reachable, stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Function count, library count, coverage percent, and the validator output. 3) Files changed. 4) Addresses you were unsure about. 5) New parking-lot items.

   Done whennotes/functions.csv passes the validator, and every uncovered run in the build log has a row with a status.

   Proof this works: https://github.com/phobos665/dream-recomp (dcdisc new-game, coverage line, 79 to 90% found by discovery), Ikaruga port (functions seeded from dream-translate), Bomberman Online Recomp (Ghidra 12.1.4 with SuperH4, P0 addresses), Voldorium (about 130 library functions replaced by native code)

4. Build and reach the first frame

   This is first light. The game starts, the runtime answers it, and a window shows a picture. It will stop at untranslated addresses. The run can write the fix for those. Keep the dev interpreter on, so gaps fall back and show up in the report.

   • Build the title: cmake --build build --target <id>_boot -j8.
   • Run headless first. It prints a report: build/games/<id>/<id>_boot --config games/<id>/<id>.toml.
   • When it stops at an address, run with --suggest-config next.toml. Paste the suggested [functions] extra seeds into your TOML and rebuild.
   • Repeat until the report shows zero untranslated call targets. Crazy Taxi got there with ten entries in three rounds.
   • Then run with --window --screenshot-at 300. It saves a picture at the 300th frame with nobody at the keyboard. Keep it with the log line that proves the run.
   • On Dreamcomp, python tools/dc.py report <port> --frames 600 prints the same run report, and python tools/dc.py shots <port> --at 300,900 saves pictures.
   • Split the generated C++ into several files. Bomberman Online split 179 MB into eight parts to avoid a 20-minute compile.
   Prompt for ClaudeCopy

   GOAL: Get <GAME> to show its first frame (<LOGO_OR_SCREEN>) from a cold start.
   READ FIRST: `PROGRESS.md`, `logs/run-latest.txt`, the `dream-recomp` README section When it stops.
   FENCE: Edit only `games/<ID>/<ID>.toml` and `PROGRESS.md`. Never edit generated C++. Add seeds only from `--suggest-config` output or a Ghidra address you can show. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python tools/check.py --boot --seconds 60`. Done means it saves `out/first-frame.png`, and the report says 0 untranslated call targets.
   BUDGET: One round of seeds per try. Stop after 5 rounds with no new address passed.
   IF BLOCKED: If the stop is not an untranslated address, stop and paste the report. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Seeds added, with where each came from. 4) What is left. 5) New parking-lot items.

   Done whenpython tools/check.py --boot --seconds 60 saves a first-frame picture, and the run report shows 0 untranslated call targets.

   Proof this works: https://github.com/phobos665/dream-recomp (--suggest-config, Crazy Taxi: ten entries over three rounds), Bomberman Online Recomp (dc.py report with 0 untranslated targets; eight-part split), https://github.com/phobos665/dream-recomp/blob/main/docs/dev-setup.md (--screenshot-at N, --capture-at N), https://github.com/danielgomesvieira2000/dreamcomp/tree/main/.claude/skills/dc-playtest (dc.py shots --at)

5. Grind: one stop or one wrong behaviour per task

   Now play further, one problem at a time. Compare with Flycast to see what the real game does. Fix it in the config, a hook, or the translator, never in generated code. Write each finding down with its address.

   • Write each problem as one issue: what happens, where it stops, the log line.
   • Run the same input in Flycast. dream-recomp compares its translated code with Flycast's interpreter, step by step. See its docs/differential-harness.md.
   • That compare needs a Flycast oracle core. Build it with tools/flycast/oracle/build_oracle.sh, then configure with -DDREAM_FLYCAST_CORE=<core>. It is a shell script, so run it in WSL.
   • If the translator gets one function wrong, list that function so the interpreter runs it. deSPIRIA did this for three functions.
   • Use --rtc-seed 1000000 so two runs act the same. Use --write-hash FILE to find the first frame where two runs split.
   • Add every address you learn to notes/game-internals.md. Mark each one observed, derived or guessed, as Bomberman Online does.
   • Keep one verified change per commit. A fix is done when the symptom is gone, not when a counter moves.
   Prompt for ClaudeCopy

   GOAL: Fix issue <ISSUE_ID>: <ONE_LINE_SYMPTOM>.
   READ FIRST: `notes/issues/<ISSUE_ID>/spec.md`, `notes/game-internals.md`, the failing log `logs/<ISSUE_ID>.txt`, the Flycast reference capture `ref/<ISSUE_ID>/`.
   FENCE: Edit only `games/<ID>/<ID>.toml`, `src/hooks/`, `tests/` and `notes/issues/<ISSUE_ID>/`. Never edit generated C++ or a test's pass rule. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: First show the new test fails. Then run `python tools/check.py --test <ISSUE_ID>` and `python tools/check.py --regress`. Done means both pass, with the symptom shown gone in a screenshot or log.
   BUDGET: Stop after 3 failed fixes or 90 minutes without new evidence.
   IF BLOCKED: If the cause is in the translator itself, stop and name the SH-4 instruction and address. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What you did not verify. 5) New parking-lot items.

   Done whenThe issue's test failed before the fix and passes after, the full regression run still passes, and no generated file changed.

   Proof this works: deSPIRIA reBIRTH (three functions sent to the interpreter through the game config), Blue Stinger Recompiled (each subsystem proved against Flycast before moving on), Bomberman Online and Army Men (dreamcomp/CLAUDE.md: one verified change at a time; symptom shown gone), https://github.com/phobos665/dream-recomp (--rtc-seed, --write-hash), https://github.com/phobos665/dream-recomp/blob/main/docs/dev-setup.md (Flycast oracle core: build_oracle.sh, -DDREAM_FLYCAST_CORE)

6. Get graphics, sound and movies right

   Most visible bugs live in the PowerVR2 renderer, the AICA sound chip and the movie player. Capture a bad frame and replay it offline. Fix the generic cause, not one texture. Check every fix against the same capture.

   • Press F11 on a wrong frame. You get five files, capture-000.ppm, .ta, .vram, .vram.regs and .txt: the picture, the display list, video memory, the graphics registers and a note. --capture-at N does this with no person.
   • Replay it with no game: build/render/dream_render_view --vram capture-000.vram capture-000.ta. Bisect the bug there.
   • Make a generic fix. Army Men fixed a sort rule for see-through polygons, not each texture.
   • If the game is silent, check how 32-bit stores reach the AICA. deSPIRIA had to treat them as 16-bit stores.
   • For smeared movies, check textures the game rewrites in place each frame. deSPIRIA fixed its movies this way.
   • For widescreen, change the projection and anchor the HUD. Do not stretch 2D art. Voldorium documents how.
   Prompt for ClaudeCopy

   GOAL: Fix the rendering or sound bug <BUG_ID> shown in capture `captures/<BUG_ID>/`.
   READ FIRST: `captures/<BUG_ID>/` (the five F11 files), the Flycast reference picture `ref/<BUG_ID>.png`, `docs/runtime-render.md` or `docs/runtime-aica.md` in `dream-recomp`.
   FENCE: Edit only the renderer or AICA files named in `notes/issues/<BUG_ID>/spec.md`, and `tests/`. No per-texture or per-address special cases. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `build/render/dream_render_view --vram captures/<BUG_ID>/capture-000.vram captures/<BUG_ID>/capture-000.ta` before and after, then `python tools/check.py --regress`. Done means the replay matches the reference and all old captures still match.
   BUDGET: Stop after 3 failed fixes.
   IF BLOCKED: If the hardware behaviour is unclear in the docs and in Flycast, stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: before and after pictures and the regress output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe replayed capture matches the Flycast reference, and every older capture in the regression set still matches.

   Proof this works: https://github.com/phobos665/dream-recomp (F11 capture and dream_render_view), Army Men: Sarge's Heroes - Recompiled (generic fix for see-through overlap from captured frames), deSPIRIA reBIRTH (AICA 16-bit store fix, movie texture fix), Voldorium (widescreen by projection scale and HUD anchors)

7. Harden: replays, hashes and a clean repo

   Lock in what works. Record runs a machine can replay with no person. Compare memory hashes and pictures, not your eyes. Keep tests off your real saves. Make sure no game data is in git.

   • Record input scripts that both Flycast and your build can play. Blue Stinger does this with tools/dev/assistido.py.
   • Write a rolling hash of memory per frame with --write-hash. Store only the hash files.
   • Give tests their own save folder. Sonic Adventure Recompiled uses KATANA_USER_DATA_ROOT.
   • Run tests hidden and muted, with no OS input. SARecomp's AGENTS.md makes this a rule.
   • Keep a frozen, hash-checked baseline build. Compare each change against it.
   • Run the no-game-data audit on every push. Army Men runs tools/audit_release.py --history in CI.
   Prompt for ClaudeCopy

   GOAL: Add a regression set of <N> scripted runs and make `python tools/check.py --regress` run them all.
   READ FIRST: `PROGRESS.md`, `runs/README.md`, `CLAUDE.md`.
   FENCE: Edit only `runs/`, `tools/` and `PROGRESS.md`. Store hashes and input scripts only, never frames, saves or game data. Use a separate save folder for every run. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python tools/check.py --regress` twice on a clean checkout. Done means the same PASS both times and `git ls-files` shows no game-derived file.
   BUDGET: Stop after 3 failed tries at one run.
   IF BLOCKED: If a run is not repeatable with a fixed `--rtc-seed`, stop and show the two hash files. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste both check outputs. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenpython tools/check.py --regress passes twice in a row on a clean checkout, and the no-game-data audit passes.

   Proof this works: Blue Stinger Recompiled (recorded gameplay scripts, tiered regression tools/dev/regressao.ps1), Sonic Adventure Recompiled (isolated save root, frozen hash-checked baseline), Army Men: Sarge's Heroes - Recompiled (audit_release.py --history in CI)

8. Package a builder for the player's own disc

   You may not share the translated game. So ship the translator and runtime only. The player's PC checks their disc, translates it and compiles it. Six reviewed ports work this way: Voldorium, Hail to the King, deSPIRIA, Street Fighter Alpha 3, Blue Stinger and Ikaruga.

   • Check the player's boot file by hash first. Refuse any other release.
   • Download pinned, checksummed tools on first run. Voldorium fetches llvm-mingw and Zig; Hail to the King fetches llvm-mingw, CMake, Ninja, Python and SDL2.
   • Translate and compile on the player's PC. The reviewed ports report from half a minute to 30 minutes.
   • Refuse to finish a release if any file holds translated code. Voldorium's build does this.
   • Warn players that Windows Defender may flag an unsigned builder. Voldorium documents a false alarm.
   Prompt for ClaudeCopy

   GOAL: Make `tools/make_release.py` produce a builder that turns the player's own disc into the game, with no game code inside the release.
   READ FIRST: `SCOPE.md`, `PROGRESS.md`, `tools/check.py`, `LEGAL.md`.
   FENCE: Edit only `tools/make_release.py`, `launcher/` and `docs/players.md`. Pin every downloaded tool by version and SHA-256. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python tools/make_release.py --audit dist/`. Done means it lists every file, finds no translated function or disc data, and a fresh folder builds the game from my disc to the first frame.
   BUDGET: Stop after 3 failed tries.
   IF BLOCKED: If the audit flags a file you think is safe, stop and ask. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the audit output and the first-frame log. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe release audit finds no game code or data, and a clean folder builds the game from your disc to the first frame.

   Proof this works: Voldorium (local translate and compile; release refuses translated functions; pinned SHA-256 downloads), Evil Dead: Hail to the King PC (build.bat downloads pinned tools into .tools), deSPIRIA reBIRTH (upstream pinned to a commit, fixes as an overlay), Street-Alpha-3-Dreamcast-Recomp (setup app converts the player's disc), Blue Stinger Recompiled (Builder makes the exe from the player's CDI), ikaruga-decomp (decompiles on the player's Mac)

Path B: Full decomp for porting

First the boot file is split into one assembly file per function. The SDK's own assembler and linker rebuild it byte for byte. Then C is written for each function and proven in an SH-4 simulator. The dc-decomp-kickoff skill runs all nine steps, up to a disc built from the C. A PC port after that is new ground on this system.

1. Scope: code layout, SDK release and prior work

   Check the game fits the method. Its code must sit in the boot file at a fixed address. Find which SDK release it was built with. Check for a decomp that already exists.

   • Search GitHub for <game> decomp. dc-decomp-kickoff lists worked examples. A complete matching decomp of Sonic Adventure already exists.
   • Look at the disc with dcdisc, as in Path A step 1: dcdisc inspect <disc>.gdi -o notes/disc-report.md and dcdisc manifest <disc>.gdi > notes/disc-manifest.json.
   • Check the boot file. If it is 0WINCEOS.BIN, the game uses Windows CE and the skill does not apply.
   • If the game loads most code from other files, like Phantasy Star Online, the skill stops at step 1.
   • Find out if a later port, a prototype or cheat codes exist. The kickoff uses these to name functions. An Android port with symbols helps most.
   • Write SCOPE.md with the disc serial, boot file hash, SDK release, mode (equivalent or matching) and what is out of scope.
   Prompt for ClaudeCopy

   GOAL: Draft `SCOPE.md` for a decomp of <GAME> (product <PRODUCT_NO>) and say if `dc-decomp-kickoff` fits it.
   READ FIRST: `notes/disc-report.md` and `notes/disc-manifest.json` from `dcdisc`, the `dc-decomp-kickoff` README at https://github.com/consolesplayingconsoles/dc-decomp-kickoff (What it reads, Worked examples).
   FENCE: Write only `SCOPE.md` and `notes/prior-work.md`. Do not fetch any SDK, disc or compiler. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `grep -cE '^## (Code layout|SDK release|Mode|Prior work|Out of scope)' SCOPE.md`. Done means it prints 5, and every prior-work line has a URL you opened.
   BUDGET: Stop after 1 hour.
   IF BLOCKED: If the game loads its code from many files or is Windows CE, stop and say so first. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Fits or does not fit, with the reason. 3) Prior work with URLs. 4) Materials that could name functions. 5) Questions for me.

   Done whengrep -cE '^## (Code layout|SDK release|Mode|Prior work|Out of scope)' SCOPE.md prints 5, and its last line is Approved: <date> in your words.

   Proof this works: https://github.com/consolesplayingconsoles/dc-decomp-kickoff (What it reads; PSO not compatible), https://github.com/reshaped/sonic-adventure (complete matching decomp of Sonic Adventure JP 1.007), Crazy Taxi decomp (setup refuses other releases by SHA-1)

2. Set up the kickoff skill, Docker or WSL, and your SDK

   The skill runs the Hitachi tools and Ghidra in Docker. On Windows, Docker Desktop uses WSL. Or run everything in WSL with DC_LOCAL=1. You hand over the disc as .gdi and your SDK folder. The skill never downloads them.

   • Run Claude Code inside WSL for this path. Keep the disc, the SDK and the repo under your WSL home folder.
   • Install the skill: git clone https://github.com/consolesplayingconsoles/dc-decomp-kickoff ~/.claude/skills/dc-decomp-kickoff.
   • Docker route: install Docker Desktop. In Settings > Resources > WSL Integration, turn on your Ubuntu. Then docker info must work in WSL.
   • No-Docker route in WSL: bash ~/.claude/skills/dc-decomp-kickoff/scripts/setup_tools.sh --check, then the same without --check. It installs pinned wibo, unshield, JDK 21 and Ghidra. Then source ~/dc-tools/env.sh and set DC_LOCAL=1.
   • Check python3 --version prints 3.6 or newer. The skill needs Python 3 on every route.
   • Keep about 4 GB free. Run one Ghidra job at a time, since each needs about 1 GB.
   • In Claude Code, run /dc-decomp-kickoff. Step 1 checks your disc and SDK.
   Prompt for ClaudeCopy

   GOAL: Complete kickoff step 1 (Decomp project setup) for <GAME>.
   READ FIRST: `~/.claude/skills/dc-decomp-kickoff/SKILL.md` (Requirements and the machine, Step 1), `SCOPE.md`.
   FENCE: Use only the disc folder <DISC_DIR> and SDK folder <SDK_DIR> I name. Never search my folders, never download an SDK or disc. Write only inside <REPO_DIR>. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `docker info` (or `bash ~/.claude/skills/dc-decomp-kickoff/scripts/setup_tools.sh --check` with `DC_LOCAL=1`). Done means the skill prints `=== Step 1 of 8 done: Decomp project setup ===` and the boot file hash matches `SCOPE.md`.
   BUDGET: Stop after 3 failed tries at the same error.
   IF BLOCKED: If the SDK lacks `asmsh.exe`, `lnk.exe` or `lbr.exe`, stop and tell me. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the step summary and the tool check. 3) Files changed. 4) SDK release found. 5) New parking-lot items.

   Done whenThe skill prints === Step 1 of 8 done: Decomp project setup === (its own banner says 8, though it runs nine steps), and docker info or setup_tools.sh --check passes.

   Proof this works: https://github.com/consolesplayingconsoles/dc-decomp-kickoff (install line, Docker or DC_LOCAL=1, setup_tools.sh), https://github.com/consolesplayingconsoles/dc-decomp-kickoff/blob/main/SKILL.md (step banners, Python 3.6+, about 4 GB free, unshield), https://docs.docker.com/desktop/features/wsl/ (WSL Integration setting), Zombie Revenge decomp (Hitachi tools under wibo in Docker; DC_LOCAL=1 on Linux)

3. Rebuild the boot file byte for byte and name what you can

   This is kickoff steps 2 and 3. The boot file is split into one assembly file per function. The SDK's tools rebuild it, and build.sh must print MATCH. SDK functions get names by signature. Then maps of text, models and sounds are written.

   • Let the skill run step 2. It uses Ghidra, splits the code, and builds with asmsh, lnk and elf2bin.
   • Check the gate by hand: bash build.sh must print MATCH.
   • functions.txt is the source of truth for names and sizes. Rename only there, rerun split_asm.py, and build. Names never change bytes.
   • Let step 3 write the text, model, texture and audio maps.
   • Open the result in Shuriken Explorer in your browser to look at models and code side by side. Your files stay on your PC.
   Prompt for ClaudeCopy

   GOAL: Complete kickoff steps 2 and 3 for <GAME>: a byte-identical rebuild with SDK names, and the asset maps.
   READ FIRST: `SKILL.md` Step 2 and Step 3, `SCOPE.md`, `PROGRESS.md`.
   FENCE: Edit only files the skill's scripts write, plus `PROGRESS.md`. Never hand-edit files in `asm/`. Run one Ghidra action at a time. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `bash build.sh` and `python3 tools/progress.py`. Done means `build.sh` prints `MATCH` and progress shows the named function count.
   BUDGET: Stop after 3 failed builds with the same error.
   IF BLOCKED: If a script prints an empty table, stop at once. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste `build.sh` output and `progress.py` output. 3) Files changed. 4) Functions named versus `FUN_`. 5) New parking-lot items.

   Done whenbash build.sh prints MATCH, and python3 tools/progress.py reports the named and unnamed counts.

   Proof this works: Crazy Taxi decomp (build.sh prints MATCH; SDK names by unique signature match), Zombie Revenge decomp (names only in functions.txt; build still MATCH), https://consolesplayingconsoles.github.io/dc-shuriken-explorer/

4. Prove the first functions: scripts first, then one by hand

   This is kickoff step 5. Free scripts write C and test cases first. Then you prove one small file by hand, end to end. Each function runs twice in the simulator: original bytes and your C. Calls, memory writes and the result must agree.

   • If you have the SDK's library source, run python3 tools/5-generated/sdk_source.py <folder>.
   • Run python3 tools/5-generated/gen_equiv. It writes C and cases in parallel. Read the blockers in build/gen_failed.txt.
   • Run python3 tools/5-generated/gen_equiv --retest to widen weak test coverage.
   • Pick one small file. Write its C and cases in tests/<file>/<function>.json, split into dev and holdout.
   • Check it: python3 tools/equiv.py src/<file>.c. A function counts only when both case sets pass.
   • Run python3 tools/progress.py. Generated and hand-written C are counted apart.
   Prompt for ClaudeCopy

   GOAL: Run the script-generated pass, then prove every function in `src/<FILE>.c` Equivalent by hand.
   READ FIRST: the repo's `AGENTS.md` (The C loop), `functions.txt`, `python3 tools/shdis.py --func <FUNC>` output for each function.
   FENCE: Edit only `src/<FILE>.c`, `tests/<FILE>/` and `docs/equivalent.md`. Never edit `tools/equiv.py`, `tools/sh4sim.py` or a case to make it pass. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python3 tools/equiv.py src/<FILE>.c` and `bash build.sh`. Done means every function is Equivalent on dev and holdout cases, and `build.sh` still prints `MATCH`.
   BUDGET: At most 5 serious tries per function. Then move it to `partial/` with a note.
   IF BLOCKED: If `tools/5-generated/classify.py <FUNC>` says it cannot be C, stop for that function. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the `equiv.py` output with instruction coverage. 3) Files changed. 4) Functions left in `partial/`. 5) New parking-lot items.

   Done whenpython3 tools/equiv.py src/<FILE>.c shows every function Equivalent on dev and holdout cases, and bash build.sh still prints MATCH.

   Proof this works: Crazy Taxi decomp (gen_equiv, dev and holdout cases, equiv.py), Virtua Tennis decomp (script-generated C first, then agentic pockets), Tokyo Bus Guide decomp (the same idea with sh4objtest: original and C run against one test spec)

5. Grind: workers on separate pockets

   This is kickoff step 6. The rest is done pocket by pocket: library code without source, the game's own code, then runtime routines. Give each worker its own files. One lead owns the build, the progress file and git.

   • Pick functions that unlock the most others first. Smallest first is only the tie-break.
   • Give each worker a disjoint set of src/ files in its own git worktree.
   • Workers run only python3 tools/equiv.py src/<file>.c for their files.
   • Use RAM dumps from the running game for functions that need world state. tools/4-boosts/live.py reads them from RetroArch with its Flycast core. Run it with no arguments to see its setup.
   • The lead merges one worker at a time, runs bash build.sh and python3 tools/progress.py, then commits.
   • Run python3 tools/consistency.py after runs overlap. It finds C defined twice and cases with no C.
   Prompt for ClaudeCopy

   GOAL: Lead session: hand out the next <N> files from the pocket <POCKET> to <N> workers and merge their proven results.
   READ FIRST: the repo's `AGENTS.md`, `tests/equivalent.txt`, `python3 tools/progress.py` output.
   FENCE: Workers edit only their own `src/` and `tests/` files in their own worktree. Only you run `build.sh`, `consistency.py` and git. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: After each merge run `python3 tools/equiv.py src/<FILE>.c`, `bash build.sh` and `python3 tools/consistency.py`. Done means `MATCH`, no consistency errors, and progress went up.
   BUDGET: Stop the batch when 2 merges in a row fail a check.
   IF BLOCKED: If two workers touched the same file or a shared header, stop and tell me. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Check output after the last merge and the new progress numbers. 3) Files merged. 4) Files sent back. 5) New parking-lot items.

   Done whenAfter each batch, bash build.sh prints MATCH, consistency.py is clean, and progress.py shows the new Equivalent count.

   Proof this works: Crazy Taxi decomp (functions that unlock the most others first; RAM dumps via live.py), https://github.com/consolesplayingconsoles/crazy-taxi-decomp/blob/main/AGENTS.md (live.py needs RetroArch with the Flycast core), Zombie Revenge decomp (all 5,189 C-able functions Equivalent in about four weeks)

6. The hard tail: junk RAM, dropped arguments and matching

   Some C passes the simulator but fails on a console. The simulator fills unset RAM with zero, but a console holds leftovers. Calls can also drop arguments without the check seeing it. Find these before you build from C. Then try byte matching where it pays off.

   • Run python3 tools/5-generated/overreads.py src/<file>.c. It reruns cases with junk in unused RAM.
   • Before the first build, compare trampolines with state/arity_scan.json. Regenerate short ones with python3 tools/5-generated/gen_equiv --regen <name>.
   • For the matching tier, write a whole unit with an @unit header. Iterate until build.sh prints MATCH.
   • Compare function by function while you iterate. The first wrong function shifts everything after it.
   • If no rewording moves a difference, try another SHC release. decomp.me's archive has SHC 5.0 and 5.1 builds.
   • Leave a unit as assembly after a fair try. Write down what differs.
   Prompt for ClaudeCopy

   GOAL: Clear the hard tail for `src/<FILE>.c`: no over-reads, no dropped arguments, and match the unit if it can be done fairly.
   READ FIRST: the repo's `AGENTS.md` (Matching notes, Building from C), `state/arity_scan.json`, `notes/hard/<FILE>.md`.
   FENCE: Edit only `src/<FILE>.c`, its cases and `notes/hard/<FILE>.md`. No inline assembly. No changes to `equiv.py`, `sh4sim.py`, `build.sh` or the expected hash. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python3 tools/5-generated/overreads.py src/<FILE>.c`, `python3 tools/equiv.py src/<FILE>.c` and `bash build.sh`. Done means no over-read, all Equivalent, and `MATCH`.
   BUDGET: Stop matching after 20 serious variants without progress. Write what you learned.
   IF BLOCKED: If a function needs FPU bank or control register tricks that C cannot express, stop for it. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste all three outputs. 3) Files changed. 4) What still differs and why. 5) New parking-lot items.

   Done whenoverreads.py reports no difference, equiv.py shows all Equivalent, and bash build.sh prints MATCH.

   Proof this works: Crazy Taxi decomp (overreads.py, arity scan, literal pools shared per file), Virtua Tennis decomp (dropped-argument trampolines; units stay asm after a fair try), https://github.com/decompme/compilers/tree/main/platforms/dreamcast (SHC 5.0 and 5.1 releases)

7. Harden: the gate, the ledger and a cheat hunt

   Make the build and the simulator the only judges. Run the gate before every commit. Let the progress script write the numbers. A fresh session hunts for weakened cases and edited tools.

   • Turn on the progress hook once per clone: git config core.hooksPath tools/hooks.
   • Block edits to asm/, tools/equiv.py, tools/sh4sim.py, build.sh and the expected hash with a PreToolUse hook. Exit code 2 blocks the edit.
   • Check that every function in tests/equivalent.txt has holdout cases and an entry in docs/equivalent.md.
   • Grep for C in partial/ counted as done, and for cases with only one input.
   • Keep the instruction coverage figure from equiv.py. Crazy Taxi reports 82.6%, Zombie Revenge 68.5%.
   Prompt for ClaudeCopy

   GOAL: Audit the last <N> commits for fake proofs and broken rules.
   READ FIRST: `git log -<N> --stat`, the repo's `AGENTS.md`, `CLAUDE.md`.
   FENCE: Read only. Write findings to `notes/audit-<DATE>.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: From a clean checkout run `bash build.sh`, `python3 tools/consistency.py` and `python3 tools/progress.py`. Grep the diff for edits to `tools/`, `asm/`, holdout cases and the expected hash. Done means the gate passes and each finding cites a file and line.
   BUDGET: Stop after 1 hour.
   IF BLOCKED: If the gate fails on a clean checkout, stop at once. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Gate output. 3) Findings with file and line. 4) Commits to revert. 5) New parking-lot items.

   Done whenA fresh checkout passes bash build.sh with MATCH, consistency.py is clean, and the audit file lists every finding with a file and line.

   Proof this works: Zombie Revenge decomp (git config core.hooksPath tools/hooks; progress badge from a pre-commit hook), Crazy Taxi decomp (coverage 82.6%; partial/ counted apart), https://code.claude.com/docs/en/hooks (exit code 2 blocks a PreToolUse call)

8. Build the game from C and fix it at run time

   This is kickoff steps 7 to 9. The proven C must fit where the original code was. Then the boot file is built from C and put on a disc image. You run it in Flycast and fix each stop. Libraries stay as original bytes.

   • Shrink code that is too big: tools/7-reduction/shrink.py <name> keeps new C only if it is smaller and still passes.
   • Mark the NAOMI library, the C runtime and the Katana libraries as keep in layout.txt. Their hand-written code passes state in registers.
   • Build: make c, then make disc GDI="<your disc>.gdi".
   • Build Flycast with -DENABLE_GDB_SERVER=ON, since GDB is off by default. Its default port is 3263.
   • If the build from C hangs, put half the C functions back to assembly and test again. Virtua Tennis logged this in docs/hang-bisect.md.
   • Do not put new code in the filler after the boot block. Virtua Tennis got a black screen that way.
   • Tick status.txt only with proof: BUILDS FROM C, BOOTS TO MENU, PLAYABLE, STABLE.
   Prompt for ClaudeCopy

   GOAL: Build <GAME> from the proven C and reach <STATUS_TICK> in `status.txt`.
   READ FIRST: the repo's `AGENTS.md` (Building from C, Changing the game), `layout.txt`, `state/arity_scan.json`, `docs/hang-bisect.md` if it exists.
   FENCE: Edit only `layout.txt`, `src/` files named in the issue, `docs/` and `status.txt`. Never move code into the boot block filler. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `make c` and `make disc GDI="<DISC>.gdi"`, then boot the disc in Flycast to <MARKER>. Done means the image has the original size and a screenshot or GDB read proves the marker.
   BUDGET: Stop after 3 bisect rounds without narrowing the cause.
   IF BLOCKED: If the build from C runs in Flycast but you cannot test on a console, say so. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: `make c` output and the screenshot or GDB read. 3) Files changed. 4) What you did not verify. 5) New parking-lot items.

   Done whenmake c builds an image of the original size, the disc boots in Flycast to the named point, and status.txt cites the proof.

   Proof this works: Virtua Tennis decomp (all four status.txt ticks; hang bisect; restart-loop log), Zombie Revenge decomp (PLAYABLE in Flycast, crashes at the VMU screen on a console), https://github.com/flyinghead/flycast (CMake option ENABLE_GDB_SERVER, default off)

9. Port: move the proven C to a PC host

   No reviewed Dreamcast decomp has a PC port yet. The kickoff's C is shaped for machines, not people. One outside project, a full Sonic Adventure match, builds a PC game. The realistic route is a port layer for each Katana library, checked against Flycast.

   • Read how the Sonic Adventure decomp does it. Its make pc builds a PC game from your disc, and ENGINE.md describes the backends.
   • Make one stand-in per SDK part: Kamui or Ninja graphics, sound, GD-ROM files, pads and memory card. Voldorium's list of about 130 library calls is a guide.
   • Replace the console graphics with Vulkan or OpenGL drawn from the game's own polygon lists, as the recomps do.
   • Model SH-4 float behaviour. Sonic Adventure credits a header for bit-exact SH-4 FPU math.
   • Keep 32-bit pointers in game structs, or audit each struct, before you build for 64-bit.
   • Prove it with replays: the same inputs in Flycast and on PC, with memory hashes compared per frame.
   • Write tools/golden.py first. It runs the PC build with a fixed input script and passes only when the named point shows in the log.
   Prompt for ClaudeCopy

   GOAL: Make the PC stand-in for <SDK_PART> (for example GD-ROM file reads) and boot the PC build past it.
   READ FIRST: `port/README.md`, `functions.txt`, `sdk.txt`, the Katana call list in `notes/sdk-calls.md`, the KallistiOS docs for the matching hardware.
   FENCE: Edit only `port/<SDK_PART>/` and code inside `#ifdef TARGET_PC` blocks. Keep the Dreamcast build passing `bash build.sh` with `MATCH`. Never paste Sega SDK source or headers. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `cmake --build build-pc && ctest --test-dir build-pc` and `python3 tools/golden.py --until <MARKER>`. Then run `bash build.sh`. Done means tests pass, the marker appears, and `MATCH` still prints.
   BUDGET: Stop after 3 failed tries.
   IF BLOCKED: If the game relies on hardware you cannot model from docs or Flycast, stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe PC build passes its tests and reaches the named point in a scripted run, and the Dreamcast build still prints MATCH.

   Proof this works: https://github.com/reshaped/sonic-adventure (make pc, make play; bit-exact SH-4 FPU header credited), Voldorium (about 130 Katana library calls replaced with native code), Ikaruga port (decompiled C++ plus a hand-written port layer for Ninja, Kamui and Metal), https://github.com/phobos665/dream-recomp (rule: never paste Sega SDK source; use KallistiOS as the reference)

Tools you need

Skills and add-ons

Read any skill before you install it. A skill is a set of instructions that Claude will follow. See Tools and Skills for the full list and safety notes.

Claude setup for this system

On Dreamcast the unit is small. For Path A, one task is one stop address, one wrong frame, or one sound or movie bug. For Path B, one task is one source file of functions proven in the simulator. Every unit has a check: a run report with zero untranslated targets, a replayed capture, or equiv.py plus build.sh printing MATCH. One lead session owns the full build, the progress file and git.

Which model and effort for each job

The model and effort names come from one shared table, so they stay the same on every guide. See Claude Setup for the reasons.

How many sessions at once

Lines for this project's CLAUDE.md

- Read `SCOPE.md` and `PROGRESS.md` at the start of every session.
- Never edit generated C++. Fix the TOML config, a hook, or the translator instead.
- The one check is `python tools/check.py` (Path A) or `bash build.sh` printing `MATCH` (Path B). A claim of PASS pastes its output.
- No game data in any commit: no disc files, boot files, extracted assets, generated code, BIOS, flash, VMU saves or SDK files.
- Never paste Sega SDK source or headers into this repo, even in comments. Describe the interface in your own words.
- Do not copy GPL emulator code into this repo. Use Flycast only as a reference for behaviour.
- A fix is done when the symptom is shown gone in the reported condition. Say plainly what you did not verify.
- A function counts only when its dev and holdout cases both pass. Run `overreads.py` before claiming a file done.
- Libraries stay as original bytes: keep the Katana, NAOMI and C runtime ranges in `layout.txt`.
- Log each verification in `STATUS.md` with the date and the method. Keep failed ideas in `notes/dead-ends.md`.
- Test runs use their own save folder and never touch my real VMU files or settings.
- Write patch scripts with the edit tool, not shell heredocs. Heredocs eat backslashes here.
- In a worktree, use absolute paths and keep temp files in `tmp/` inside the project.

Keep the context small

• Give Claude an address and a file path, not pasted disassembly. Let it print one function with tools/shdis.py --func <name>.
• Keep CLAUDE.md short and point to docs by topic. Blue Stinger's grew to about 19 KB and costs context every session.
• Put history and experiments in docs/, not in the agent file. SARecomp's AGENTS.md says this outright.
• Use a subagent to read a long run report or gen_failed.txt, and have it report ten lines back.
• Clear the chat after each task. State lives in PROGRESS.md, functions.txt and tests/equivalent.txt.
• Turn on tracing only for the one subsystem you test. Big logs fill the disk and the context.

More prompts for this system

Each step above has its own prompt. These extra prompts cover the rest of the work. Fill in the parts in <ANGLE_BRACKETS>.

GOAL: Tell me if <GAME> (product <PRODUCT_NO>) can be ported to PC, by which technique, and what already exists.
READ FIRST: `notes/disc-report.md` from `dcdisc inspect`, https://github.com/phobos665/dream-recomp, https://github.com/consolesplayingconsoles/dc-decomp-kickoff.
FENCE: Write only `notes/feasibility.md` and a draft `SCOPE.md`. Do not touch game files or SDK files. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Write one claim per line starting with `- `. Run `grep -c '^- ' notes/feasibility.md` and `grep -cE '^- .*(https://|disc-report)' notes/feasibility.md`. Done means both print the same number.
BUDGET: Stop after 1 hour.
IF BLOCKED: If the game is Windows CE or loads code from many files, say so first. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Recommended path: recomp on `dream-recomp`, own translator, or kickoff decomp. 3) Prior work with URLs. 4) Risks: overlays, movies, Katana SDK access. 5) Questions for me.

GOAL: Build `notes/functions.csv` for <GAME> with address, size, library tag and status for every function, plus the uncovered byte runs.
READ FIRST: the coverage line in `logs/build-latest.txt`, `games/<ID>/<ID>.toml`, Ghidra through the MCP server (read-only).
FENCE: Write only `notes/functions.csv` and `notes/map-notes.md`. Do not rename or save anything in Ghidra. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `python tools/validate_map.py notes/functions.csv`. Done means no overlaps, and the row count matches the translator's function count plus seeds.
BUDGET: Stop after 2 hours.
IF BLOCKED: If Ghidra's addresses do not line up with the translator's, stop and show three examples. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) Katana library calls found. 5) New parking-lot items.

GOAL: Fix one issue: <SYMPTOM> at <ADDRESS_OR_LOG_LINE>.
READ FIRST: `notes/issues/<ID>/spec.md`, `logs/<ID>.txt`, `notes/game-internals.md`, the Flycast reference for the same input.
FENCE: Edit only `games/<GAME_ID>/<GAME_ID>.toml`, `src/hooks/`, `tests/` and `notes/issues/<ID>/`. Never edit generated C++. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Show the new test failing first. Then run `python tools/check.py --test <ID>` and `python tools/check.py --regress`. Done means both pass.
BUDGET: Stop after 3 failed fixes.
IF BLOCKED: If the bug is in the translator, stop and describe the SH-4 instruction. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What you did not verify. 5) New parking-lot items.

GOAL: Prove every function in `src/<FILE>.c` Equivalent.
READ FIRST: the repo's `AGENTS.md` (The C loop), `functions.txt`, `python3 tools/shdis.py --func <FUNC>` for each function.
FENCE: Edit only `src/<FILE>.c` and `tests/<FILE>/`. No inline asm. Do not run `build.sh`, `consistency.py` or git. Never edit `tools/`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `python3 tools/equiv.py src/<FILE>.c` and `python3 tools/5-generated/overreads.py src/<FILE>.c`. Done means each function you claim is Equivalent on dev and holdout cases with no over-read.
BUDGET: Five serious tries per function. Then move it to `partial/` with a note.
IF BLOCKED: If a shared header must change, stop and ask. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) `equiv.py` output with coverage. 3) Equivalent versus `partial/`. 4) Guessed names. 5) Notes marked verified or inferred.

GOAL: Pick the next <N> files from pocket <POCKET> and start one worker per file in its own worktree.
READ FIRST: `python3 tools/progress.py` output, `tests/equivalent.txt`, the repo's `AGENTS.md`.
FENCE: Assign disjoint files only. Edit only `notes/assignments.md`. Workers follow the unit loop card. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: When workers report, merge one at a time and run `bash build.sh` and `python3 tools/consistency.py`. Done means `MATCH` and a clean consistency check after every merge.
BUDGET: Stop the batch if two merges in a row fail.
IF BLOCKED: If a worker reports a tool or simulator problem, pause the batch. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Gate output after the last merge. 3) Files merged and files returned. 4) New progress numbers. 5) Parking-lot items.

GOAL: Find the cause of <SYMPTOM>. Do not fix it yet.
READ FIRST: `logs/<RUN>.txt`, the F11 capture `captures/<ID>/`, the `--write-hash` files `runs/<RUN>/*.hash`, the Flycast reference.
FENCE: Read only, plus new files in `notes/debug/<ID>/`. Turn on tracing only for the one subsystem you test. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Name the first frame or address where the PC build and Flycast differ, with the hash line or log lines that prove it.
BUDGET: Stop after 2 hours or 3 disproved theories.
IF BLOCKED: If you cannot reproduce it twice with the same `--rtc-seed`, stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The proven cause with evidence. 3) Theories ruled out and how. 4) The smallest fix you propose. 5) Parking-lot items.

GOAL: Check that the work in commits <RANGE> is real.
READ FIRST: `git log <RANGE> --stat`, `CLAUDE.md`, the repo's `AGENTS.md`.
FENCE: Read only. Write findings to `notes/verify-<DATE>.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: From a clean checkout run `python tools/check.py --regress` (Path A) or `bash build.sh` and `python3 tools/consistency.py` (Path B). Look for edits to generated code, `tools/`, holdout cases, expected hashes, new interpreter fallbacks and success stubs.
BUDGET: Stop after 1 hour.
IF BLOCKED: If the check fails on a clean checkout, report that first. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Check output. 3) Each finding with file and line. 4) Commits to revert. 5) Parking-lot items.

GOAL: Report project status with numbers from the ledgers only.
READ FIRST: `PROGRESS.md`, `STATUS.md`, `notes/functions.csv` or `python3 tools/progress.py` output, `status.txt`, `notes/parking-lot.md`.
FENCE: Read only. Write only `notes/status-<DATE>.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Every number cites the file it came from. Run the project check once and paste its summary line.
BUDGET: Stop after 20 minutes.
IF BLOCKED: If two files disagree, stop and show both. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Milestone status. 3) Counts: Equivalent functions, coverage, open issues, untranslated targets. 4) Top three blockers. 5) Parking-lot size.

GOAL: Write what the next session needs into the ledger files.
READ FIRST: `PROGRESS.md`, `notes/handoff.md`, this session's work.
FENCE: Edit only `PROGRESS.md`, `notes/handoff.md` and `notes/dead-ends.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run the project check (`python tools/check.py --regress` or `bash build.sh`) and `git status --short`. Paste both into `notes/handoff.md`. Done means it also names the next task and every dead end tried.
BUDGET: Stop after 15 minutes.
IF BLOCKED: If you are unsure what is done, mark it PARTIAL and say why. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Next task in one line. 3) Last check output. 4) Dead ends added. 5) Files changed.

GOAL: Give me a plain answer on <TASK>: can it be done now, and if not, why.
READ FIRST: `notes/issues/<ID>/work.md`, the last three check outputs.
FENCE: Read only. Write only `notes/issues/<ID>/blocked.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run the task's own check once more and paste its output. Start with DONE, PARTIAL or BLOCKED. Every claim cites a log or file.
BUDGET: Stop after 20 minutes.
IF BLOCKED: If the honest answer is no, say no first. A missing Katana SDK, an untestable console bug, or a game that loads code from many files are valid answers. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
REPORT: 1) Outcome word. 2) What cannot be done and why. 3) What was tried. 4) Two or three options with cost. 5) What you need from me.

GOAL: Ask me before leaving the fence for <CHANGE>.
READ FIRST: `SCOPE.md`, the issue that led here, `docs/engine-changes.md` if you use `Dreamcomp`.
FENCE: Change nothing. Write only `notes/scope-requests.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `git status --short`. Done means only `notes/scope-requests.md` changed, and the request names the files, the reason, the risk and the check.
BUDGET: Stop after 15 minutes.
IF BLOCKED: If the change touches generated code, the translator, `tools/equiv.py` or `build.sh`, say so in the first line. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
REPORT: 1) The change in one line. 2) Why it is needed now. 3) Files it touches. 4) Its check. 5) What happens if I say no.

Keep Claude on task

These are the detours Claude tends to take on this system, and the rule that stops each one. The full method is on Stay on Task.

Problems other projects hit

How long it takes

What makes it faster or slower

• Overlays. One boot file is the easy case. Many code files add work, and some games do not fit the tools at all.
• Starting point. A game that dream-recomp already boots, or that a sister game shares a library with, saves weeks.
• Movies and sound. Sofdec movies and the AICA chip caused most late bugs in the reviewed ports.
• The Katana SDK. Path B cannot start without one, and finding one can take longer than the decomp.
• Names. A later port with symbols, cheat codes or a prototype can name many functions for free.
• The PC port in Path B. No reviewed Dreamcast decomp has one yet, so this part has no time data.

The facts behind these numbers

Projects reviewed (14)

Dreamcast has fewer than 10 games on RecompLauncher: 10 projects for 9 games, so all 10 were reviewed. The two Blue Stinger entries are one GitHub repo. Four decomps came from outside it. At least 10 real outside projects exist, so this list is a sample.

What each project teaches

What we could not check

• No step was run here. No tool was installed or built on this machine; every command comes from a tool's README, SKILL.md, AGENTS.md or a review card.
• Whether Flycast's ready-made builds include the GDB server. Its CMake option is off by default, so this guide says to build it yourself.
• Whether the decomp.me compiler archive also holds asmsh, lnk and elf2bin. The kickoff needs these from a Katana SDK.
• Where to get a Katana SDK legally. This guide does not say, and neither do the tools.
• Which retail games were built with Metrowerks CodeWarrior instead of Hitachi SHC.
• Six of the nine Dreamcomp skills. Only /dc-playtest, /dc-investigate and /dc-audit were read.
• The static-recomp-scope-plan install. Its skills.sh page said on 2026-11-13 that it is not listed, though its SKILL.md is still on GitHub. Whether npx skills add still finds it was not tested.
• Whether dream-recomp's Flycast oracle core (tools/flycast/oracle/build_oracle.sh) builds in WSL or on Windows. Its docs show it on the owner's Mac.
• How to add the Flycast core inside RetroArch. Only the need for it was read, in Crazy Taxi's AGENTS.md.
• Where --screenshot-at N saves its picture. The docs say it writes the same picture as F12, but name no folder.
• KatanaRecomp, the recompiler behind Sonic Adventure Recompiled. It is not in that repo and was not found.
• The tools/check.py, validate_map.py, golden.py and make_release.py scripts are ones you write. Their names follow the reviewed projects but are not standard tools.
• Whether tools/new-game.sh from dream-recomp runs on Windows. This guide uses dcdisc new-game instead.
• Whether Claude Code installs and runs smoothly inside WSL for Path B. The kickoff assumes ~/.claude/skills on the machine that runs the tools.
• How many hours a week any dated project took, and how much private work came before its first public commit.
• The Sonic Adventure matching decomp's history and AI use. Its repo shows only a few commits and one contributor.
• Whether an equivalence decomp can be turned into a clean PC port. No reviewed project has done it, so Path B step 9 is a plan, not a proven route.
• The Vulkan SDK download page did not render, so its current version and whether it ships glslc were not confirmed here.

Sources

• dream-recomp README
• dcdisc README (dream-recomp)
• dream-recomp dev-setup.md (run flags, F11 files, oracle core)
• Dreamcomp project skills
• dc-decomp-kickoff SKILL.md
• Visual Studio older downloads (Build Tools 2022)
• Microsoft Learn: Clang/LLVM support in Visual Studio
• Microsoft Learn: CMake projects in Visual Studio
• Ninja releases
• RetroArch README
• static-recomp-scope-plan SKILL.md (GitHub)
• Dreamcomp README
• dc-decomp-kickoff README and SKILL.md
• Crazy Taxi decomp AGENTS.md
• Flycast README
• Flycast CMakeLists.txt (ENABLE_GDB_SERVER)
• Ghidra README
• Ghidra SuperH4 language definitions
• GhidraMCP README
• wibo README
• decomp.me compilers: Dreamcast SHC releases
• objdiff README
• sh4objtest README
• Tokyo Bus Guide decomp README
• Sonic Adventure matching decomp README
• dcrecomp README (sp00nznet)
• Shuriken Explorer README
• llvm-mingw README
• Capstone README
• Docker Desktop WSL 2 backend
• Dreamcast Wiki: Hardware overview
• Dreamcast Wiki: Boot process
• Dreamcast Wiki: Memory map
• Dreamcast Programming by Marcus Comstedt
• KallistiOS README
• Claude Code hooks