Balatro Mod Development

Create and debug Balatro mods with Steamodded, Lovely, and SMODS.

Quick Agent Selection

When researching, spawn the right agent:

Parallel: When researching DIFFERENT sources - spawn multiple agents at once Sequential: When second query depends on first result

See references/sub-agents.md for boundaries, workflow patterns, and creating new agents.

Repo Type Awareness

See templates/project-rules-template.md for detailed rules per type.

File Naming Convention (Claude & Codex)

Both Claude and Codex use the same file structure:

AGENT.md Purpose: Enable seamless handover between agents. Another agent should quickly understand mod structure, functions, dependencies, and current development status without losing context.

File Placement Rules

Only these .md files belong in root:

• •README.md, README_zh.md
• •CHANGELOG.md, CHANGELOG_zh.md
• •AGENT.md, INIT.md
• •LICENSE.md

ALL other .md files MUST go in docs/

External References (No Symlinks Needed)

Access reference code directly via absolute paths. No setup required.

Source Locations (macOS)

Source Locations (Windows)

Finding Patterns & Examples

When you need to find how something is implemented:

Key Dependencies

Pattern References

Read these files for specific topics:

New Mod Setup (type: new)

Templates in templates/ folder:

Meta Files:

User Docs in templates/docs/:

Required User Docs (new repos):

Root:
├── README.md, README_zh.md      # Main docs (EN/ZH)
├── CHANGELOG.md, CHANGELOG_zh.md # Version history (EN/ZH)
└── {ModName}.json, manifest.json # Meta files

docs/:
├── description.md               # Concise README
├── NEXUSMODS_DESCRIPTION.txt    # BBCode format
├── knowledge-base.md            # Issues & lessons
└── AGENT.md                     # Repo structure (AI)

Basic Mod Structure (new repos):

{ModName}/
├── main.lua                 # Entry point, mod registration
├── config.lua               # Config defaults (optional)
├── lovely.toml              # Lovely patches (if needed)
├── {ModName}.json           # SMODS mod manifest
├── manifest.json            # Thunderstore manifest
├── mod.config.json          # Script configuration
├── Utils/
│   └── Logger.lua           # Centralized logging
├── localization/
│   ├── en-us.lua            # English (required)
│   └── zh_CN.lua            # Chinese
├── assets/                  # Sprites, shaders
├── scripts/                 # Utility scripts
└── docs/                    # Documentation

AI Agent Config Templates

Logging

For new/my repos:

Use Utils/Logger.lua (from templates/logger-template.lua):

local Logger = require("Utils.Logger")
local log = Logger.create("ModuleName")
log("info", "Initialized")
log("error", "Failed: " .. err)

For forks/others' repos:

Use temp logs only (remove before PR):

pcall(print, "[Debug] checkpoint: " .. tostring(var))

Utility Scripts

Workflow: Init Any Existing Repo

For ALL non-empty repos (own or fork), ALWAYS do these first:

1. •Delete References/ folder if exists (legacy symlink approach)
2. •Move extra .md files to docs/ - only keep in root: README*.md, CHANGELOG*.md, AGENT.md, INIT.md, LICENSE.md
3. •Add dev files (if missing): AGENT.md, INIT.md, mod.config.json, scripts/sync_to_mods.sh
4. •Add Claude config (if missing): .claude/commands/, .claude/hooks/, .claude/agents/
5. •Update .gitignore with agent folders

Then for OWN repos: Also check manifest, scripts version (2.0.1), add create_release.sh, Logger.lua

Then for FORK repos: Keep AGENT.md lightweight, use fork-mode INIT.md, don't add release scripts

Workflow: Debugging

1. •Check platform (desktop vs mobile)
2. •Search game source for function
3. •Check other mods for implementations
4. •Add logs (Logger.lua for own, temp for fork)
5. •Check Lovely logs
6. •If fix fails 3+ times: Document in docs/knowledge-base.md

Workflow: Update User Docs

When user says "update all user docs":

1. •Review ALL files: README(_zh).md, CHANGELOG(_zh).md
2. •Review docs/: description.md, NEXUSMODS_DESCRIPTION.txt
3. •Update version in {ModName}.json, manifest.json
4. •Ensure EN/ZH consistency

Workflow: Draft PR Message (fork repos)

Use /draft-pr command. Style: 3-5 sentences, casual tone, what/why/done.

Sub-Agents for Research

Main agent handles code. Sub-agents handle information gathering.

See references/sub-agents.md for detailed boundaries, workflow patterns, and creating new agents.

Available Commands

• •/init-balatro-mod - Initialize new mod
• •/sync-mod - Start sync with watch mode (run once at start)
• •/bump-version [patch|minor|major] - Increment version, update changelogs
• •/release - Create release packages (auto-detects version from manifests)
• •/fix-sprites <directory> [--preview] - Fix grey borders on sprites
• •/refactor [focus-area] - Review code for redundancy, outdated fallbacks, modularization
• •/debug - Verify fix by checking Lovely logs (auto-detects mod key from repo)
• •/draft-pr - Draft PR message (for forks)
• •/update-docs - Review all user docs
• •/update-skill [file|instruction] - Update skill based on new knowledge

Sub-agents available after setup:

• •game-source-researcher - Find game functions and injection points
• •smods-api-researcher - Find SMODS API patterns and usage
• •mod-pattern-researcher - Find how other mods implement features
• •lovely-patch-researcher - Find Lovely patch syntax and examples
• •script-runner - Run temp scripts and return results