---
name: lua-engineering
description: lua engineering guidance seeded from the harness forge knowledge base. use when the repo or task is dominated by .lua files, neovim plugins, openresty, love2d, embedded scripting, luajit, or host-specific lua automation where runtime compatibility matters.
origin: Harness Forge
---

# 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`