| name | neovim-plugin-review |
| description | Review Neovim plugins for best practices, maintainability, and idiomatic Lua. Use when asked to review or improve a Neovim plugin, Lua code under lua/, plugin/, after/, ftplugin/, autoload/, doc/, tests/, or when checking setup/config APIs, autocmds, keymaps, async jobs, health checks, docs, tests, or plugin architecture. |
Neovim Plugin Review
Review plugins like a maintainer: start from behavior and user-facing API, then check architecture, Lua idioms, Neovim lifecycle, async/performance, and quality gates. Prioritize concrete bugs, regressions, race conditions, invalid APIs, user-state stomping, and missing tests before style preferences.
Workflow
- Inspect the plugin shape first: entrypoints,
setup(), public API, commands, docs, tests, and CI/tooling.
- For stacked PRs, compare each PR against its declared PR base branch, not against
main or the stack tip.
- Compare implementation against the focused references below. Load only the files relevant to the review.
- Report findings first, ordered by severity, with file and line references. Keep praise and architecture summary brief.
- Prefer small, actionable fixes that preserve the plugin's current design unless the architecture itself is the problem.
Reference Map
- Read
references/architecture.md for module layout, public/private boundaries, setup idempotency, and API shape.
- Read
references/lua-config.md for idiomatic Lua, config defaults, validation, buffer-local config, mappings, and user-state preservation.
- Read
references/neovim-lifecycle.md for autocmds, commands, keymaps, buffers, highlights, health checks, and plugin runtime behavior.
- Read
references/async-performance.md for jobs, timers, watchers, scheduling, race avoidance, debounce/throttle, and hot-path performance.
- Read
references/quality-gates.md for docs, tests, formatting, type annotations, CI, release hygiene, and review checklists.
Baseline Rules
require() should be cheap and mostly side-effect free; setup() owns validation and registration.- Public APIs should be typed, documented, stable, and separated from CLI/user-command parsing.
- Config should deep-copy defaults, validate user input, avoid mutating caller tables, and support runtime overrides only where behavior truly updates at runtime.
- Autocmds, timers, jobs, namespaces, extmarks, and watchers need explicit ownership and cleanup.
- UI work and notifications must be scheduled out of fast events and async callbacks when needed.
- Expensive features need guards for big files, invalid buffers, changed buffers, missing tools, and repeated setup.
- Tests should cover boundary behavior: commands, mappings, buffer attach/detach, async races, external processes, generated docs, and config validation.
Source Models
These rules were distilled from high-quality plugins cloned under tmp/: folke/lazy.nvim, folke/snacks.nvim, echasnovski/mini.nvim, stevearc/conform.nvim, and lewis6991/gitsigns.nvim. Use them as pattern sources, not as rigid style mandates.
