Lua Engineering

Lua Engineering

Use this skill when the repository is Lua-first and the safest next move depends on runtime flavor, host APIs, coroutine behavior, editor or game integration, or disciplined module boundaries.

Activation

• the task touches .lua files, host-specific Lua config, Neovim plugins, OpenResty services, Love2D gameplay code, or embedded automation
• the runtime may vary across Lua 5.x, LuaJIT, or a host-specific flavor such as Luau or editor-embedded Lua
• the change depends on module contracts, async or coroutine behavior, or host lifecycle hooks

Load Order

• rules/common/README.md
• rules/common/coding-style.md
• rules/common/patterns.md
• rules/common/testing.md
• rules/common/security.md
• rules/lua/README.md
• rules/lua/coding-style.md
• rules/lua/patterns.md
• rules/lua/testing.md
• rules/lua/security.md
• templates/workflows/implement-lua-change.md
• knowledge-bases/seeded/lua/docs/overview.md
• knowledge-bases/seeded/lua/docs/frameworks.md
• knowledge-bases/seeded/lua/docs/examples-guide.md
• the closest matching file in knowledge-bases/seeded/lua/examples/
• knowledge-bases/seeded/lua/docs/review-checklist.md
• skills/lua-engineering/references/

Execution Contract

1. identify the active runtime and host before changing code: pure Lua, LuaJIT, Neovim, OpenResty, Love2D, or embedded automation
2. preserve local module conventions and avoid accidental global state
3. prefer small table-based modules, explicit contracts, and readable control flow over metatable-heavy cleverness unless the repo already relies on it
4. treat coroutine, event-loop, and host-lifecycle behavior as first-class design constraints
5. validate with the host's actual entrypoint, tests, formatting, or language-server checks before finalizing

Outputs

• touched-file plan grouped by module or host surface
• implementation or debugging summary with the exact runtime assumption that changed
• validation path with formatter, tests, host smoke steps, or editor checks
• compatibility note when the runtime flavor or host API assumptions changed

Validation

• use the repo's preferred test and formatting path first
• confirm the target runtime version and host before using syntax or standard-library APIs
• use LuaLS diagnostics and annotations when the repo already depends on them
• add or update Busted tests when the code is pure enough to isolate from the host
• consult knowledge-bases/seeded/lua/docs/review-checklist.md before finalizing a patch or design note

Escalation

• escalate when the repo mixes Lua versions or host APIs with incompatible assumptions
• escalate when performance-sensitive LuaJIT or FFI behavior is changed without evidence
• escalate when host lifecycle, coroutine scheduling, or plugin loading order are unclear

Supplemental Engineering References

• skills/lua-engineering/references/repo-exploration.md
• skills/lua-engineering/references/output-templates.md
• skills/lua-engineering/references/agent-patterns.md
• skills/lua-engineering/references/debugging-playbook.md
• skills/lua-engineering/references/language-idioms.md
• skills/lua-engineering/references/runtime-profiles.md
• skills/lua-engineering/references/neovim-and-editor-patterns.md
• skills/lua-engineering/references/openresty-patterns.md
• skills/lua-engineering/references/game-and-addon-patterns.md
• skills/lua-engineering/references/debugging-and-testing.md
• skills/lua-engineering/references/tooling-and-quality.md
• skills/lua-engineering/references/examples.md