Imported from YI-TING-EE13/SlideDo (AGENTS.md). Install upstream with npx skills add YI-TING-EE13/SlideDo. Copyright stays with the author.

SlideDo Agent Guide

Use this file to get productive quickly in a new coding session.

Project Snapshot

SlideDo is a Java number Klotski / sliding puzzle game.

• Shared core: src/com/klotski/core
• Desktop Swing UI: src/com/klotski/ui
• Android app: android/app/src/main/java/com/klotski/android
• Shared core tests: test/com/klotski/core
• Main development record: DEVELOPMENT.md

The shared GameModel and the other platform-independent core types own shared puzzle and domain semantics. Desktop and Android use platform-specific UI, lifecycle, and persistence mechanisms; parity means equivalent documented outcomes and data boundaries, not one UI serving as a blanket reference for the other.

Current Product Direction

The eight-stage Personal Play program and the eight-stage Personal Play 2.0 program for offline, owner-only use are complete. The Desktop/Android parity qualification through the packaged Stage 8 evidence is also recorded as complete for its current scope; Issue #13 is the final contract-led Java API and documentation synchronization stage before umbrella Issue #4 review. Public store submission is not a prerequisite for this owner-only milestone.

Prioritize:

• True active-play timer pausing (completed).
• Difficulty selection and reproducible scrambles (completed).
• Replay of the same puzzle (completed).
• Independent saves by board size (completed).
• Local history and personal statistics (completed).
• Offline daily challenge and streak state (completed).
• Strategic hints with assisted-record protection (completed).
• Optional sound and themes (completed).

Preserve the completed program and use the same implement, verify, document, and commit gate for future feature stages. Personal Play 2.0 backup/restore, Daily Calendar/history replay, Favorite Puzzles, personal trends/custom weekly goals, Continuous Challenge, and Move History/Redo, Adaptive and Accessibility Reinforcement, and Toolchain and CI Maintenance are complete. The full Personal Play 2.0 program is complete; new feature work should start only from an owner-approved stage. Defer store signing, store assets, accounts, cloud sync, ads, analytics, and other public-distribution work unless the owner changes direction.

Keep the supported conservative build baseline at AGP 8.13.2, Gradle 8.14.5, JDK 17, compile/target SDK 36, and build-tools 36.0.0. Run verify-toolchain.ps1 after changing build or CI files. AGP 9 is a separate major migration that requires explicit owner approval and the Android Studio Upgrade Assistant preflight.

Keep GameModel platform-independent. Navigation and presentation changes belong in Android UI/controller code.

Core Gameplay Rules

• Empty cell is 0.
• Solved order is row-major with 0 in the last cell.
• Direction means where the empty cell moves, not where the numbered tile moves.
• GameModel.move(Direction) is a single-step move.
• GameModel.slideLineTo(row, col) is the required whole-line slide path.
• Whole-line slide counts as one move and one action-history entry.
• Scrambles must be generated by valid moves from the solved board.
• Difficulty changes scramble depth only; it does not change movement rules.
• Equal size, difficulty, and seed values must reproduce the same scramble.
• Undo moves the latest completed action to Redo; Redo reapplies that exact action, and any new valid action clears Redo.
• Restart restores initialGrid and clears both action histories.
• Results Replay Puzzle restores the same initialGrid; it must not reshuffle.
• Saves must preserve size, difficulty, grid, initial grid, move count, elapsed milliseconds, completed action history, and Redo history. Legacy saves without histories still load safely with both histories empty.
• Best records compare fewer moves first, then lower time.
• Android best records are scoped by both size and difficulty.
• Every player and solver-assisted completion updates local history and lifetime statistics; only player completions can update best records.
• Solver-assisted wins must not overwrite player best records.
• Favorite identity includes size, difficulty, and the exact initialGrid.
• Favorite replay is isolated practice: it must not overwrite normal/daily saves or update best records, completion history, lifetime statistics, or daily streaks.
• Daily saves are independent by ISO date. Historical daily completion remains visible but must not move the latest-date streak backward; future dates are not playable.
• Continuous Challenge supports 3, 5, or 10 puzzles in one fixed size and difficulty scope. Its exact current board and aggregate totals use an isolated save namespace and must not replace normal, daily, or favorite-practice saves.
• Each continuous puzzle updates completion history and lifetime statistics once. Solver-assisted completions must not update player best records.
• Home resumes an unfinished continuous session. Ending it or Reset Saved Games clears only continuous progress; Reset Records preserves the active session.

Working Style

• Communicate with the user in Chinese unless they ask otherwise.
• Write code comments, Javadocs, README content, and development docs in clear English.
• Read existing code and DEVELOPMENT.md before implementing.
• Prefer small, coherent changes with focused verification.
• Use existing project patterns before adding abstractions.
• Update DEVELOPMENT.md for planning, roadmap, workflow, or behavior changes.
• Keep public/API behavior documented with English Javadocs or API comments.
• Do not push to a remote unless the user explicitly asks.

Git Rules

• Work is developed on a feature branch created from the exact protected origin/main baseline. Push the feature branch only when the project owner explicitly asks for it, then use pull-request review; never push directly to protected main.
• Commit cohesive changes after implementation and verification.
• Do not rewrite history, reset, rebase, squash, or force-push unless explicitly requested.
• Do not track generated files, local saves, IDE files, or machine-specific config.
• .gitignore and .gitattributes are part of the workflow and should remain respected.

Useful status checks:

git status --short
git log --oneline --decorate -5

Verification Commands

Run the smallest relevant set first, then broaden when changing shared behavior.

Shared core tests:

android\gradlew.bat -p . test

Desktop compile:

if exist bin rmdir /s /q bin
mkdir bin
dir /s /b src\*.java > sources.txt
javac -encoding UTF-8 -d bin @sources.txt

Android build and lint:

cd android
build-debug.bat :app:assembleDebug :app:lintDebug

Toolchain and complete no-device CI contract:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File verify-toolchain.ps1
ci.bat

Android install and launch:

adb devices
adb install -r android/app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n com.klotski.android/.MainActivity

Public core/desktop Javadocs (run with the supported JDK 17 toolchain on PATH):

javadoc -quiet -public -Xdoclint:all -encoding UTF-8 -charset UTF-8 -d %TEMP%\slidedo-javadocs src\com\klotski\core\*.java src\com\klotski\ui\*.java

Android API comments:

javadoc -quiet -public -Xdoclint:all -encoding UTF-8 -charset UTF-8 -classpath "%LOCALAPPDATA%\Android\Sdk\platforms\android-36\android.jar;src" -sourcepath "android\app\src\main\java;src" -d %TEMP%\slidedo-android-javadocs android\app\src\main\java\com\klotski\android\*.java

Android Manual Smoke Tests

Use the emulator when Android gameplay or UI changes.

• Launch app.
• Switch 3x3, 4x4, and 5x5.
• Tap adjacent aligned tile.
• Tap non-adjacent aligned tile; move count should increase by one.
• Undo after whole-line slide; move count should decrease by one, then Redo should restore the entire line as one action.
• Open Move History and verify completed/Redo counts and direction labels.
• Restart; moves and timer should reset.
• Save after a move, Restart, then Load; state should restore.
• Open BFS on 4x4; warning dialog should appear.
• Rotate, switch portrait/landscape, and background/resume when relevant.
• At 1.5x system font size, verify dense Home/favorite rows stack, game actions remain complete, and the board remains playable on the compact AVD.
• Verify the screen title is an accessibility heading, game focus order is Home/Menu/status/board/Undo/Redo/Restart/Assist, and every movable board tile is an actionable virtual accessibility child.
• Keep button text/icon contrast at or above 4.5:1 in both visual themes.

Files To Keep In Mind

• DEVELOPMENT.md: single source of truth for roadmap, workflow, behavior notes, and development log.
• README.md: user-facing project overview and usage.
• android/README.md: Android-specific setup and smoke test notes.
• GameModel.java: canonical rules and state transitions.
• KlotskiView.java: Android board rendering, touch handling, and animation.
• MainActivity.java: Android screen/controller glue, persistence, records, and solver actions.

Common Pitfalls

• Do not duplicate puzzle rules in Android UI; use GameModel.
• Do not implement whole-line movement as repeated model.move(...) user actions.
• Do not let solver-assisted wins update best records.
• Do not let Save/Load lose initialGrid; Restart depends on it.
• Do not accept input while the board is animating or solver playback is queued.
• Do not replace KlotskiView's per-cell virtual accessibility nodes with one non-actionable whole-board node; screen-reader users must be able to play.
• Do not commit bin/, build/, android/app/build/, android/local.properties, or local save files.