Agent Skill

# HotSwan — Agent Skill

You are working on an Android project that uses Compose HotSwan for hot reload.
HotSwan lets you see code changes on a real device in under a second without
restarting the app. Follow these rules when editing UI code.

## How it works

- When a .kt file is saved, HotSwan detects the change, compiles only the
  modified functions, and swaps them into the running app in memory.
- Scroll positions, navigation state, and remember{} values are preserved.
- If a change cannot be hot reloaded (structural change), HotSwan automatically
  falls back to a full incremental build.

## What you can hot reload

- Composable function body changes (text, colors, modifiers, layout, control flow)
- Non-composable function body changes (ViewModel methods, utilities, mappers)
- Adding new composable functions in the same file
- Reordering composable calls within a function
- Resource value changes (strings.xml, colors.xml, dimens.xml)
- Extension functions, suspend functions, vararg functions
- Data class property/field additions (API 30+)

## What triggers a full rebuild

- Adding or removing function parameters or constructor parameters
- Changing class hierarchy (extends, implements)
- Modifying inline functions (they are expanded at call sites)
- Removing a previously added function's definition
- Adding new resource IDs (new R.string, R.drawable entries)

## Best practices

- Make small, focused edits. One change at a time reloads faster.
- Keep changes within function bodies when possible.
- If you need to add a new composable, define it in the same file as its caller.
- After editing, save the file. HotSwan picks up changes automatically.
- If something looks wrong after reload, a full Run will always fix it.
- Do not change build.gradle.kts or version catalogs expecting hot reload — those
  require a full Gradle sync and rebuild.

# HotSwan MCP — Agent Skill

You have access to HotSwan MCP tools for hot reloading Android Compose UI.
Use these tools to edit code, see results on device, and iterate visually.

## Available tools

### Core
- hotswan_get_status() — Check device, app, and watcher state before starting.
- hotswan_start() — Start file watching. Call this before reloading.
- hotswan_reload(filePaths) — Trigger hot reload for edited files.
- hotswan_revert_change(filePaths) — Revert files to git HEAD and reload.
- hotswan_build_and_install() — Full Gradle build + install + start watcher.

### Snapshot
- hotswan_take_screenshot() — Capture device screenshot as a snapshot.
- hotswan_start_snapshot() — Enable snapshot capturing mode.
- hotswan_stop_snapshot() — Disable snapshot capturing mode.

### Decision
- hotswan_select_variant(snapshotId, reason) — Pick a UI variant by snapshot ID.
- hotswan_get_decision_history() — Review selected/rejected variants and reasons.
- hotswan_clear_decisions() — Clear history when starting a new exploration.

### Debug
- hotswan_get_logs(count?) — Get recent compilation and reload logs.
- hotswan_list_devices() — List connected Android devices and emulators.

### Inspector
- hotswan_get_hierarchy() — Get the current Compose composition tree with group keys, names, source locations, and recompose status.

## Workflow

Always follow this sequence:

1. hotswan_get_status() — confirm device is connected and app is running.
2. hotswan_start() — start file watching.
3. Edit code with your file editing tools.
4. hotswan_reload([...files]) — apply changes to device.
5. hotswan_take_screenshot() — capture the result (optional).
6. hotswan_get_hierarchy() — inspect which groups were recomposed (optional).
7. Repeat steps 3-6 for each variant.
8. hotswan_select_variant() — pick the best result (optional).

## Rules

- Always call hotswan_get_status() before starting work.
- Always call hotswan_start() before the first reload.
- Edit files BEFORE calling hotswan_reload, not after.
- Only call hotswan_take_screenshot() when the change is complete and ready
  for review. Do not screenshot intermediate edits.
- If a reload fails, call hotswan_get_logs() to diagnose the issue.
- If the app crashes or gets stuck, call hotswan_build_and_install() to
  do a fresh build.
- After a reload, call hotswan_get_hierarchy() to inspect which groups
  were recomposed and verify the change took effect.
- Keep edits within function bodies when possible. Structural changes
  (new parameters, class hierarchy) trigger a full rebuild automatically.