Back to Details

balatro-mod-dev

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Balatro Mod Development

Balatro模组开发

Create and debug Balatro mods with Steamodded, Lovely, and SMODS.
使用Steamodded、Lovely和SMODS创建并调试Balatro模组。

Quick Agent Selection

快速选择Agent

When researching, spawn the right agent:
Need to find...Use agentSearch boundaryDefault Backend
Game function implementation
game-source-researcher
Balatro_src/
only		claude
SMODS API usage/hooks
smods-api-researcher
smods/
only		claude
How other mods do X
mod-pattern-researcher
Mods/
folder only		claude
Lovely patch syntax
lovely-patch-researcher
lovely files onlyclaude
Project architecture/exploration
project-explorer
Current project onlycodex
Run temp script for data
script-runner
N/A (execution)codex
Plan implementation strategy
strategic-planner
Current project onlyopus
Review code for correctness
code-reviewer
Current project onlyopus
Synthesize research findings
research-analyst
Current project onlyopus
Parallel: When researching DIFFERENT sources - spawn multiple agents at once Sequential: When second query depends on first result
⚠️ MANDATORY: Sub-Agent Invocation
ALWAYS use 
scripts/run_subagent.sh
 to spawn sub-agents. This adapter resolves backend config from 
mod.config.json
and routes through codeagent.
DO NOT use built-in agent spawning, direct shell commands, or any other method.
bash
# CORRECT - always use this
./scripts/run_subagent.sh game-source-researcher <<'EOF'
[task content]
EOF

# WRONG - never do this
# spawn_agent(...), create_subagent(...), direct codeagent calls, etc.
See 
references/sub-agents.md
for boundaries, workflow patterns, and creating new agents.
进行研究时，选择合适的Agent：
需要查找...使用Agent搜索范围默认后端
游戏功能实现
game-source-researcher
仅
Balatro_src/
claude
SMODS API用法/钩子
smods-api-researcher
仅
smods/
claude
其他模组实现X的方式
mod-pattern-researcher
仅
Mods/
文件夹		claude
Lovely补丁语法
lovely-patch-researcher
仅Lovely相关文件claude
项目架构/探索
project-explorer
仅当前项目codex
运行临时脚本获取数据
script-runner
N/A（执行）codex
规划实现策略
strategic-planner
仅当前项目opus
代码正确性审查
code-reviewer
仅当前项目opus
研究成果整合
research-analyst
仅当前项目opus
并行执行：当研究不同来源时，可同时启动多个Agent 串行执行：当第二个查询依赖第一个查询结果时
⚠️ 强制要求：子Agent调用方式
**必须使用
scripts/run_subagent.sh
**来启动子Agent。该适配器会从
mod.config.json
读取后端配置，并通过codeagent进行路由。
禁止使用内置Agent启动、直接shell命令或其他任何方式。
bash
# 正确方式 - 请始终使用此命令
./scripts/run_subagent.sh game-source-researcher <<'EOF'
[任务内容]
EOF

# 错误方式 - 请勿使用
# spawn_agent(...), create_subagent(...), 直接调用codeagent等
如需了解范围边界、工作流模式及创建新Agent，请查看
references/sub-agents.md
。

Repo Type Awareness

仓库类型识别

Auto-detection: Compare mod manifest 
author
with git remote username.
bash
undefined
自动检测：将模组清单中的
author
与Git远程仓库用户名进行比对。
bash
undefined

Get git remote username

获取Git远程仓库用户名

git_user=$(git remote get-url origin 2>/dev/null | sed -E 's|.*://[^/]+.git$|\1|' | tr '[:upper:]' '[:lower:]')
git_user=$(git remote get-url origin 2>/dev/null | sed -E 's|.*://[^/]+.git$|\1|' | tr '[:upper:]' '[:lower:]')

Get mod author from manifest (first author, lowercase)

从模组清单中获取作者（第一个作者，转为小写）

mod_author=$(jq -r '.author[0] // .author // ""' *.json 2>/dev/null | head -1 | tr '[:upper:]' '[:lower:]')
mod_author=$(jq -r '.author[0] // .author // ""' *.json 2>/dev/null | head -1 | tr '[:upper:]' '[:lower:]')

Compare: match = own, no match = fork

比对：匹配则为自有仓库，不匹配则为分叉仓库

[[ "$git_user" == "$mod_author" ]] && echo "own" || echo "fork"

| Type | Detection | Implications |
|------|-----------|--------------|
| `new` | Empty repo (no files) | Full docs, Logger.lua, localization |
| `own` | Author matches git user | Full docs, standardize structure |
| `fork` | Author differs from git user | Minimal changes, temp logs only |

See `templates/project-rules-template.md` for detailed rules per type.
[[ "$git_user" == "$mod_author" ]] && echo "own" || echo "fork"

| 类型 | 检测方式 | 影响 |
|------|-----------|--------------|
| `new` | 空仓库（无文件） | 完整文档、Logger.lua、本地化支持 |
| `own` | 作者与Git用户匹配 | 完整文档、标准化结构 |
| `fork` | 作者与Git用户不匹配 | 最小化修改、仅使用临时日志 |

不同类型仓库的详细规则请查看`templates/project-rules-template.md`。

File Naming Convention (Claude & Codex)

文件命名规范（Claude & Codex）

Both Claude and Codex use the same file structure:
FilePurposeGit
INIT.md
Project rules, constraints for AI agentsignored
AGENT.md
Mod structure, functions, dependencies, dev status (for handover)ignored
mod.config.json
File lists for sync/release scriptsignored
docs/knowledge-base.md
Issues & lessons learnedignored
AGENT.md Purpose: Enable seamless handover between agents. Another agent should quickly understand mod structure, functions, dependencies, and current development status without losing context.
Claude和Codex使用相同的文件结构：
文件用途Git状态
INIT.md
AI Agent的项目规则与约束忽略
AGENT.md
模组结构、功能、依赖项、开发状态（用于交接）忽略
mod.config.json
同步/发布脚本的文件列表忽略
docs/knowledge-base.md
问题与经验总结忽略
AGENT.md用途：实现Agent之间的无缝交接。其他Agent应能快速理解模组结构、功能、依赖项及当前开发状态，无需丢失上下文。

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/
仅以下
.md
文件可存放在根目录：
  • README.md
    , 
    README_zh.md
  • CHANGELOG.md
    , 
    CHANGELOG_zh.md
  • AGENT.md
    , 
    INIT.md
  • LICENSE.md
所有其他
.md
文件必须放入
docs/
目录

External References (No Symlinks Needed)

外部引用（无需符号链接）

Access reference code directly via absolute paths. No setup required.
可通过绝对路径直接访问参考代码，无需额外设置。

Source Locations (macOS)

资源路径（macOS）

ResourcePath
Game Source (desktop)
~/Development/GitWorkspace/Balatro_src/desktop/
Game Source (mobile)
~/Development/GitWorkspace/Balatro_src/ios_plus/
Steamodded Source
~/Development/GitWorkspace/smods/src/
Steamodded Lovely
~/Development/GitWorkspace/smods/lovely/
Lovely Docs
~/Development/GitWorkspace/lovely-injector/
Installed Mods
~/Library/Application Support/Balatro/Mods/
Lovely Logs
~/Library/Application Support/Balatro/Mods/lovely/log/
资源路径
游戏源码（桌面端）
~/Development/GitWorkspace/Balatro_src/desktop/
游戏源码（移动端）
~/Development/GitWorkspace/Balatro_src/ios_plus/
Steamodded源码
~/Development/GitWorkspace/smods/src/
Steamodded Lovely
~/Development/GitWorkspace/smods/lovely/
Lovely文档
~/Development/GitWorkspace/lovely-injector/
已安装模组
~/Library/Application Support/Balatro/Mods/
Lovely日志
~/Library/Application Support/Balatro/Mods/lovely/log/

Source Locations (Windows)

资源路径（Windows）

ResourcePath
Game SourceVaries by setup
Installed Mods
%APPDATA%/Balatro/Mods/
Lovely Logs
%APPDATA%/Balatro/Mods/lovely/log/
资源路径
游戏源码因设置而异
已安装模组
%APPDATA%/Balatro/Mods/
Lovely日志
%APPDATA%/Balatro/Mods/lovely/log/

Finding Patterns & Examples

查找模式与示例

When you need to find how something is implemented:
What to FindWhere to SearchCommand
Game functionsBalatro_src/desktop/
grep -rn "function Game:start_run" ~/Development/GitWorkspace/Balatro_src/desktop/
SMODS API usagesmods/src/
grep -rn "SMODS.Joker" ~/Development/GitWorkspace/smods/src/
Lovely patch examplessmods/lovely/
grep -rn "patches.pattern" ~/Development/GitWorkspace/smods/lovely/
Other mods' implementationsInstalled Mods
grep -rn "pattern" ~/Library/Application\ Support/Balatro/Mods/
Mobile differencesBalatro_src/ios_plus/Compare with desktop version
当你需要了解某项功能的实现方式时：
查找内容搜索位置命令
游戏函数Balatro_src/desktop/
grep -rn "function Game:start_run" ~/Development/GitWorkspace/Balatro_src/desktop/
SMODS API用法smods/src/
grep -rn "SMODS.Joker" ~/Development/GitWorkspace/smods/src/
Lovely补丁示例smods/lovely/
grep -rn "patches.pattern" ~/Development/GitWorkspace/smods/lovely/
其他模组的实现方式已安装模组
grep -rn "pattern" ~/Library/Application\ Support/Balatro/Mods/
移动端差异Balatro_src/ios_plus/与桌面端版本对比

Key Dependencies

核心依赖项

DependencyPurpose
SteamoddedCore mod loader, SMODS API
LovelyLua injection framework
MalverkTexture pack API (AltTexture, TexturePack)
依赖项用途
Steamodded核心模组加载器、SMODS API
LovelyLua注入框架
Malverk纹理包API（AltTexture、TexturePack）

Pattern References

模式参考

Read these files for specific topics:
TopicReference File
Lovely.toml syntax
patterns/lovely-patches.md
SMODS hooks, config, localization
patterns/smods-api.md
Desktop vs mobile differences
patterns/mobile-compat.md
UIBox, CardArea, draw order
patterns/ui-system.md
Game source file map + search tips
references/game-files.md
G.GAME, G.STATES, G.P_* globals
references/globals.md
Lua/LuaJIT pitfalls, common mod bugs
references/lua-gotchas.md
如需了解特定主题，请阅读以下文件：
主题参考文件
Lovely.toml语法
patterns/lovely-patches.md
SMODS钩子、配置、本地化
patterns/smods-api.md
桌面端与移动端差异
patterns/mobile-compat.md
UIBox、CardArea、绘制顺序
patterns/ui-system.md
游戏源码文件映射 + 搜索技巧
references/game-files.md
G.GAME、G.STATES、G.P_*全局变量
references/globals.md
Lua/LuaJIT陷阱、常见模组BUG
references/lua-gotchas.md

New Mod Setup (type: new)

新模组初始化（类型：new）

Templates in 
templates/
folder:

templates/
文件夹中的模板：

FilePurpose
project-rules-template.md
INIT.md template (rules)
agent-md-template.md
AGENT.md template (repo docs)
agent-texture-pack-template.md
AGENT.md for Malverk texture packs
mod-config-template.json
Script configuration
gitignore-template
Standard .gitignore
logger-template.lua
Centralized logging utility
文件用途
project-rules-template.md
INIT.md模板（规则）
agent-md-template.md
AGENT.md模板（仓库文档）
agent-texture-pack-template.md
Malverk纹理包的AGENT.md模板
mod-config-template.json
脚本配置
gitignore-template
标准.gitignore
logger-template.lua
集中式日志工具

Meta Files:

元文件：

FilePurpose
mod-json-template.json
SMODS mod manifest ({ModName}.json)
manifest-json-template.json
Thunderstore manifest
文件用途
mod-json-template.json
SMODS模组清单（{ModName}.json）
manifest-json-template.json
Thunderstore清单

User Docs in 
templates/docs/
:

templates/docs/
中的用户文档：

FilePurpose
description-template.md
Concise README for docs/
NEXUSMODS_DESCRIPTION-template.txt
BBCode for NexusMods
knowledge-base-template.md
Issues & lessons learned
文件用途
description-template.md
docs目录下的精简README
NEXUSMODS_DESCRIPTION-template.txt
NexusMods的BBCode格式文档
knowledge-base-template.md
问题与经验总结

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
根目录:
├── README.md, README_zh.md      # 主文档（英文/中文）
├── CHANGELOG.md, CHANGELOG_zh.md # 版本历史（英文/中文）
└── {ModName}.json, manifest.json # 元文件

docs/:
├── description.md               # 精简版README
├── NEXUSMODS_DESCRIPTION.txt    # BBCode格式文档
└── knowledge-base.md            # 问题与经验总结

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
{ModName}/
├── main.lua                 # 入口文件，模组注册
├── config.lua               # 配置默认值（可选）
├── lovely.toml              # Lovely补丁（如需）
├── {ModName}.json           # SMODS模组清单
├── manifest.json            # Thunderstore清单
├── mod.config.json          # 脚本配置
├── Utils/
│   └── Logger.lua           # 集中式日志工具
├── localization/
│   ├── en-us.lua            # 英文（必需）
│   └── zh_CN.lua            # 中文
├── assets/                  # 精灵图、着色器
├── scripts/                 # 实用脚本
└── docs/                    # 文档

AI Agent Config Templates

AI Agent配置模板

FolderContents
templates/claude-config/
Claude hooks.json, init command
templates/codex-config/
Codex-specific templates (if needed)
文件夹内容
templates/claude-config/
Claude的hooks.json、初始化命令
templates/codex-config/
Codex专属模板（如需）

Logging

日志记录

For new/my repos:

自有仓库：

Use 
Utils/Logger.lua
(from 
templates/logger-template.lua
):
lua
local Logger = require("Utils.Logger")
local log = Logger.create("ModuleName")
log("info", "Initialized")
log("error", "Failed: " .. err)
使用
Utils/Logger.lua
（来自
templates/logger-template.lua
）：
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):
lua
pcall(print, "[Debug] checkpoint: " .. tostring(var))
仅使用临时日志（提交PR前需删除）：
lua
pcall(print, "[Debug] checkpoint: " .. tostring(var))

Utility Scripts

实用脚本

ScriptPurpose
scripts/sync_to_mods.template.sh
Sync mod files to game's Mods folder
scripts/create_release.template.sh
Create release packages
scripts/fix_transparent_pixels.py
Fix grey borders on sprites
scripts/mod-scripts-guide.md
Detailed script usage
脚本用途
scripts/sync_to_mods.template.sh
将模组文件同步至游戏的Mods目录
scripts/create_release.template.sh
创建发布包
scripts/fix_transparent_pixels.py
修复精灵图的灰色边框
scripts/mod-scripts-guide.md
脚本详细使用指南

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. Add hookify rules (if missing): 
    .claude/hookify.no-opus-subagents.local.md
    (Opus only for reasoning agents), 
    .claude/hookify.subagent-routing.local.md
  6. 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
对于所有非空仓库（自有或分叉），请首先执行以下步骤：
  1. 删除
    References/
    文件夹    （如果存在，属于旧版符号链接方式）
  2. 将多余的
    .md
    文件移至
    docs/
     - 根目录仅保留：README*.md、CHANGELOG*.md、AGENT.md、INIT.md、LICENSE.md
  3. 添加开发文件（如缺失）：AGENT.md、INIT.md、mod.config.json、scripts/sync_to_mods.sh
  4. 添加Claude配置（如缺失）：
    .claude/commands/
    、
    .claude/hooks/
    、
    .claude/agents/
  5. 添加hookify规则（如缺失）：
    .claude/hookify.no-opus-subagents.local.md
    （仅Opus用于推理Agent）、
    .claude/hookify.subagent-routing.local.md
  6. 在.gitignore中添加Agent相关文件夹
自有仓库额外步骤：检查清单、脚本版本（2.0.1）、添加create_release.sh、Logger.lua
分叉仓库额外步骤：保持AGENT.md简洁、使用分叉模式的INIT.md、不添加发布脚本

Workflow: Debugging

工作流：调试

  1. Check 
    references/lua-gotchas.md
    for known pitfalls (FFI cdata, nil scoping, boolean normalization)
  2. Check platform (desktop vs mobile)
  3. Search game source for function
  4. Check other mods for implementations
  5. Add logs (Logger.lua for own, temp for fork)
  6. Check Lovely logs
  7. If fix fails 3+ times: Document in 
    docs/knowledge-base.md
  1. 查看
    references/lua-gotchas.md
    了解已知陷阱（FFI cdata、nil作用域、布尔值标准化）
  2. 检查平台（桌面端vs移动端）
  3. 在游戏源码中搜索相关函数
  4. 查看其他模组的实现方式
  5. 添加日志（自有仓库用Logger.lua，分叉仓库用临时日志）
  6. 查看Lovely日志
  7. 如果修复失败3次以上：将问题记录在
    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
当用户要求“更新所有用户文档”时：
  1. 检查所有文件：README(_zh).md、CHANGELOG(_zh).md
  2. 检查docs目录：description.md、NEXUSMODS_DESCRIPTION.txt
  3. 更新{ModName}.json、manifest.json中的版本号
  4. 确保英文与中文文档内容一致

Workflow: Draft PR Message (fork repos)

工作流：起草PR消息（分叉仓库）

Use 
/draft-pr
command. Style: 3-5 sentences, casual tone, what/why/done.
使用
/draft-pr
命令。风格：3-5句话，语气随意，说明做了什么、为什么做、完成了什么。

Sub-Agents for Research

用于研究的子Agent

Main agent handles code. Sub-agents handle information gathering via 
scripts/run_subagent.sh
→ codeagent routing.
Shared context: When invoking multiple sub-agents for a task, the main agent must first create 
.tmp/[taskname]/task.md
as a shared brief. Sub-agents read it for context and write their artifacts (research.md, analysis.md, plan.md, review.md) to the same directory. See 
references/sub-agents.md
→ "Shared Task Context" for the full protocol.
SituationUseDefault Backend
Research (game, SMODS, mods, lovely)Research agent
claude
Running temp scripts for data
script-runner
codex
Planning, reviewing, synthesizingReasoning agent
opus
Writing/editing codeMain agent—
User interaction neededMain agent—
Backends and source paths are configurable in 
mod.config.json
:
  • agent_backends.research
    / 
    agent_backends.execution
    / 
    agent_backends.reasoning
    — category defaults
  • agent_backends.overrides.{agent-name}
    — per-agent override (string or 
    {backend, workdir}
    )
  • source_paths
    — where game source, SMODS, mods are located on this machine
Model restriction: Opus is allowed only for reasoning sub-agents (strategic-planner, code-reviewer, research-analyst). Research agents use Sonnet; execution agents use Haiku.
Hookify enforcement (requires hookify plugin on-site):
  • hookify.no-opus-subagents.local.md
    — Blocks Opus for non-reasoning agents (allows strategic-planner, code-reviewer, research-analyst)
  • hookify.subagent-routing.local.md
    — Blocks direct codeagent/route_subagent calls
These are backend hints. Codeagent owns final invocation policy (
~/.codeagent/config.yaml
, 
~/.codeagent/models.json
). 
run_subagent.sh
resolves config and routes through codeagent automatically — no direct 
codeagent-wrapper
calls.
See 
references/sub-agents.md
for full config resolution, invocation patterns, and parallel examples.
主Agent负责代码处理。子Agent通过
scripts/run_subagent.sh
→ codeagent路由来处理信息收集。
共享上下文：当为某任务启动多个子Agent时，主Agent必须先创建
.tmp/[taskname]/task.md
作为共享任务说明。子Agent会读取该文件获取上下文，并将研究成果（research.md、analysis.md、plan.md、review.md）写入同一目录。完整协议请查看
references/sub-agents.md
→ "Shared Task Context"。
场景使用方式默认后端
研究（游戏、SMODS、模组、Lovely）研究Agent
claude
运行临时脚本获取数据
script-runner
codex
规划、审查、整合推理Agent
opus
编写/编辑代码主Agent—
需要用户交互主Agent—
后端配置与资源路径可在
mod.config.json
中自定义：
  • agent_backends.research
    / 
    agent_backends.execution
    / 
    agent_backends.reasoning
    — 分类默认值
  • agent_backends.overrides.{agent-name}
    — 单个Agent的覆盖配置（字符串或
    {backend, workdir}
    ）
  • source_paths
    — 当前机器上游戏源码、SMODS、模组的存放路径
模型限制：Opus仅允许用于推理子Agent（strategic-planner、code-reviewer、research-analyst）。研究Agent使用Sonnet；执行Agent使用Haiku。
Hookify强制规则（需现场安装hookify插件）：
  • hookify.no-opus-subagents.local.md
    — 禁止非推理Agent使用Opus（允许strategic-planner、code-reviewer、research-analyst）
  • hookify.subagent-routing.local.md
    — 禁止直接调用codeagent/route_subagent
以上为后端提示。最终调用策略由Codeagent决定（
~/.codeagent/config.yaml
、
~/.codeagent/models.json
）。 
run_subagent.sh
会自动解析配置并通过codeagent路由 — 无需直接调用
codeagent-wrapper
。
完整的配置解析、调用模式及并行示例请查看
references/sub-agents.md
。

Available Commands

可用命令

  • /familiar
    - Get familiar with this mod (reads AGENT.md, INIT.md, maps architecture)
  • /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
    - Audit project health: scripts, hooks, commands, config, file placement, gitignore
  • /update-docs
    - Review all docs (user docs + AGENT.md + INIT.md) for accuracy, staleness, duplication, verbosity
  • /update-skill [file|instruction]
    - Update skill based on new knowledge
  • /knowledge
    - Review session work, capture discoveries (project-scope → AGENT.md, general → skill)
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
  • project-explorer
    - Extensive codebase exploration (uses codex for token efficiency)
  • script-runner
    - Run temp scripts and return results
  • strategic-planner
    - Plan implementation strategy (uses opus for deep reasoning)
  • code-reviewer
    - Review code for correctness and edge cases (uses opus)
  • research-analyst
    - Synthesize multi-source research findings (uses opus)
  • /familiar
    - 熟悉当前模组（读取AGENT.md、INIT.md，梳理架构）
  • /init-balatro-mod
    - 初始化新模组
  • /sync-mod
    - 启动同步并开启监听模式（启动时运行一次）
  • /bump-version [patch|minor|major]
    - 递增版本号，更新变更日志
  • /release
    - 创建发布包（自动从清单中检测版本号）
  • /fix-sprites <directory> [--preview]
    - 修复精灵图的灰色边框
  • /refactor [focus-area]
    - 审查代码冗余、过时回退逻辑及模块化情况
  • /debug
    - 通过查看Lovely日志验证修复效果（自动从仓库中检测模组密钥）
  • /draft-pr
    - 起草PR消息（适用于分叉仓库）
  • /update
    - 审计项目健康状态：脚本、钩子、命令、配置、文件放置、gitignore
  • /update-docs
    - 审查所有文档（用户文档 + AGENT.md + INIT.md）的准确性、时效性、重复性及冗长性
  • /update-skill [file|instruction]
    - 根据新知识更新技能
  • /knowledge
    - 回顾会话工作内容，记录新发现（项目范围内容写入AGENT.md，通用内容写入技能）
设置完成后可用的子Agent：
  • game-source-researcher
    - 查找游戏函数与注入点
  • smods-api-researcher
    - 查找SMODS API模式与用法
  • mod-pattern-researcher
    - 查找其他模组的功能实现方式
  • lovely-patch-researcher
    - 查找Lovely补丁语法与示例
  • project-explorer
    - 深度探索代码库（使用codex以提高令牌效率）
  • script-runner
    - 运行临时脚本并返回结果
  • strategic-planner
    - 规划实现策略（使用opus进行深度推理）
  • code-reviewer
    - 审查代码正确性与边缘情况（使用opus）
  • research-analyst
    - 整合多来源研究成果（使用opus）