balatro-seed-search/AGENT.md

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

  1. Read TASK.md before starting work and keep it current.
  2. Complete tasks in dependency order unless a task explicitly says otherwise.
  3. Every task must end in its own git commit. Do not combine completed tasks into one commit. Include the corresponding TASK.md checkbox update in that task's commit.
  4. Before every commit, run the checks listed for that task. Do not mark a task complete when its required checks fail.
  5. Use concise conventional commit subjects such as cli: add joker search or engine: validate filter inputs.
  6. Keep commits focused. Do not reformat or rewrite unrelated files.
  7. Preserve deterministic engine behavior. Any refactor of RNG, derivation, seed iteration, or filter evaluation requires regression tests.
  8. Keep reusable behavior in target-independent library modules rather than duplicating it in the CLI.
  9. 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.
  10. 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-jokers is the friendly path for the core use case. Repeated joker names are combined with --mode all (default) or --mode any.
  • --before-ante Z is inclusive: it searches appearances in antes 1..=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 --help and 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 Clause variants 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.