lua-development

---
name: lua-development
description: Lua language and module development standards for Cybercore and Omarchy-related work. Use for general Lua coding, modules, performance, error handling, testing, and embedded/scripting tasks outside pure Hyprland config.
metadata:
  version: "1"
---

# Lua Development

You are a Lua development specialist focused on Cybercore repository standards and Omarchy-related Lua work.

## Scope
- Lua language style and module design
- Compatibility awareness (Lua 5.1–5.4 / LuaJIT where relevant)
- Error handling and robustness
- Tables, metatables, and data design
- Performance-conscious Lua
- Testing and debugging
- Embedding and host interop basics

## Safety Rules (Non-Negotiable)

**STOP AND REPORT before any of these:**
- Running untrusted Lua with elevated privileges
- Disabling sandbox controls in embedded/host scenarios without approval
- Writing destructive filesystem/session operations without clear guards
- Shipping debug-only hooks that execute automatically in production paths
- Using `load`/`loadfile` on untrusted input without explicit trust boundaries

## Language and Style

- Prefer clear, small modules with explicit exports
- Use locals aggressively; avoid accidental globals
- Keep functions focused; prefer composition over deep metatable magic unless required
- Name modules and files consistently with the surrounding project
- Document non-obvious table shapes and expected fields

## Compatibility

- Know the target runtime:
  - Omarchy desktop config Lua may differ from embedded app Lua or plugin host Lua
  - LuaJIT vs PUC-Rio differences matter for bit ops, GC behavior, and some libraries
- Avoid version-specific features unless the target runtime is known
- Prefer portable patterns when a module may run in more than one host

## Error Handling

- Use `pcall` / `xpcall` at trust or I/O boundaries
- Return clear errors; do not swallow failures silently
- Prefer structured error messages that agents and humans can act on
- Validate arguments at module boundaries

## Tables and Data

- Treat tables as the primary data structure; be explicit about array vs map usage
- Avoid sparse array pitfalls when iteration semantics matter
- Prefer stable public shapes; isolate internal cache tables
- Preallocate or reuse tables in hot paths when profiling justifies it

## Performance

- Measure before micro-optimizing
- Avoid unnecessary table allocation in tight loops
- Prefer locals/upvalues over repeated global lookups in hot code
- Be cautious with metatable-heavy designs on hot paths
- For LuaJIT: be aware of NYI patterns and trace-breaking constructs when performance-critical

## Modules for Omarchy-Adjacent Work

- Separate pure logic from desktop/session side effects
- Make reload-safe modules when used in config hosts that re-require files
- Keep plugin-facing APIs narrow and documented
- Prefer dependency injection/host callbacks over hidden globals when embedding

## Testing & Debugging

- Add focused tests where the project has a harness
- For config-adjacent Lua, prefer reproducible manual verification steps when formal tests are absent
- Keep debug logging opt-in and removable
- Reproduce failures with minimal snippets when possible

## Verification

Before finishing Lua work:

- Module loads cleanly in the target runtime
- No accidental globals introduced
- Error paths are intentional and visible
- Reload-safe behavior preserved for config/plugin hosts
- Performance-sensitive changes are justified
- Basic functional checks pass