3.5 KiB
3.5 KiB
Agent instructions
Mission
Maintain this repository as a native Rust command-line application for searching Balatro seeds. The Rust engine is the source of truth; all user-facing behavior must remain available through the native binary.
The minimum useful workflow is:
Find a seed containing JOKER_X and/or JOKER_Y on or before ante Z.
The finished application should also expose the engine's other filters: joker edition and sticker, shop slot, tag, boss, voucher, pack contents, Soul, Wraith, standard-card properties, strict/partial matching, deck, stake, seed length, and bounded seed ranges.
Working rules
- Read
TASK.mdbefore starting work and keep it current. - Complete tasks in dependency order unless a task explicitly says otherwise.
- Every task must end in its own git commit. Do not combine completed tasks
into one commit. Include the corresponding
TASK.mdcheckbox update in that task's commit. - Before every commit, run the checks listed for that task. Do not mark a task complete when its required checks fail.
- Use concise conventional commit subjects such as
cli: add joker searchorengine: validate filter inputs. - Keep commits focused. Do not reformat or rewrite unrelated files.
- Preserve deterministic engine behavior. Any refactor of RNG, derivation, seed iteration, or filter evaluation requires regression tests.
- Keep reusable behavior in target-independent library modules rather than duplicating it in the CLI.
- Reject invalid names and invalid numeric ranges with actionable errors. The current hash-based compiler can otherwise turn a typo into a search that never succeeds.
- Do not claim full game parity unless it is demonstrated by the repository's tests. Clearly distinguish deterministic self-consistency from external Balatro/Immolate parity.
Product decisions
- Deliver a script-friendly CLI first. A full-screen TUI is optional and should only be added after the CLI is complete and stable.
find-jokersis the friendly path for the core use case. Repeated joker names are combined with--mode all(default) or--mode any.--before-ante Zis inclusive: it searches appearances in antes1..=Z.- Unless the user selects another supported source, a joker search means any of
the shop slots/rerolls modeled by the engine. Source limitations must be stated
in
--helpand the README. - Keep an advanced
search --filter <file-or-stdin>path using the serialized filter DSL so every engine capability remains accessible without an enormous set of flags. - Searches must be bounded and interruptible, report progress to stderr, emit results to stdout, and offer a machine-readable output mode.
- Native parallel search should be the default when available, with a thread count option and a deterministic single-thread mode for tests/debugging.
Definition of done
- A user can install/build one native binary and find one or more named jokers on or before an ante without a graphical interface or hand-written JSON.
- AND and OR joker queries have automated tests proving their ante-range semantics.
- All currently implemented
Clausevariants remain available through the advanced filter command. - Invalid filters fail before scanning.
- Results can be inspected/verified through a native command.
- Unit, integration, CLI, and release-build checks pass.
- The repository contains only the native application, engine, tests, documentation, and release automation needed to support it.