nvim_config/AGENTS.md

AGENTS.md

This document is the operating guide for coding agents working in this Neovim configuration repository.

Repository Snapshot

• Project type: personal Neovim config (Lua)
• Entry point: init.lua -> lua/core/* -> lua/plugins/*
• Plugin manager: lazy.nvim
• No dedicated CI, test suite, formatter config, or lint config is committed
• Primary language: Lua (Neovim runtime APIs)

Directory Layout

• init.lua: bootstrap into core config
• lua/core/options.lua: editor options and globals
• lua/core/keymaps.lua: global and command keymaps
• lua/core/lazy.lua: lazy.nvim bootstrap and setup
• lua/plugins/init.lua: plugin spec list
• lua/plugins/config/*.lua: per-plugin config modules
• lua/utils/*.lua: utility helpers (for example reload.lua)

Build / Lint / Test Commands

There is no Makefile/package manager script layer, so use direct commands.

Environment checks

• Verify Neovim can start this config:
  • nvim --headless -u /home/alican/.config/nvim/init.lua +qa
• Verify plugin bootstrap and lockfile resolution:
  • nvim --headless -u /home/alican/.config/nvim/init.lua '+Lazy! sync' +qa
• Optional runtime health checks:
  • nvim --headless -u /home/alican/.config/nvim/init.lua '+checkhealth' +qa

Formatting

• Preferred formatter for Lua: stylua
• Format whole repo:
  • stylua /home/alican/.config/nvim
• Format a single file:
  • stylua /home/alican/.config/nvim/lua/plugins/init.lua

If stylua is not installed, do not mass-reformat; preserve existing style in touched regions only.

Linting

• No lint config is committed (.luacheckrc not found).
• If luacheck is available, run ad hoc:
  • luacheck /home/alican/.config/nvim/lua
• Treat lint as advisory unless the repository later adds pinned lint rules.

Testing

• No test framework is currently configured in-repo.
• Use headless startup as the minimum smoke test:
  • nvim --headless -u /home/alican/.config/nvim/init.lua +qa

Running a single test (important)

There are no existing unit/integration test files, so there is no real single-test command today.

If you add Plenary-based tests, use this pattern for a single test file:

• nvim --headless -u /home/alican/.config/nvim/init.lua -c "PlenaryBustedFile tests/<name>_spec.lua" -c qa

If you add a plain Lua test runner later, document exact single-test invocations here and keep this section updated.

Code Style Guidelines

Follow local conventions observed in current files first, then these rules.

Imports and module structure

• Use require("...") with explicit module paths.
• Keep imports at top of file unless lazy-loading is intentional.
• Prefer locals for required modules (example: local cmp = require("cmp")).
• Return module tables (local M = {}; ...; return M) for utility modules.
• Plugin config modules should avoid side effects outside setup behavior.

Formatting and layout

• Preserve existing indentation style per file (repo currently mixes tabs/spaces).
• Keep lines reasonably short (existing config uses colorcolumn = "80").
• Use trailing commas in multiline Lua tables.
• Keep one logical statement per line.
• Group related options/settings in contiguous blocks.
• Avoid large unrelated reformatting in feature/fix commits.

Types and annotations

• Lua is dynamically typed here; no strict type checker is configured.
• Keep useful EmmyLua annotations when present (for example ---@type ...).
• Add annotations only when they improve editor/LSP inference.
• Do not add noisy type comments for obvious locals.

Naming conventions

• Module/file names: lowercase, path-based (core.options, plugins.config.lsp).
• Local variables: snake_case.
• Exported module tables: M.
• User commands: PascalCase where already used (ReloadConfig).
• Avoid introducing new global functions/variables.
• Exception: if global is required by Vim command callbacks, prefix carefully and document intent.

Neovim API usage

• Prefer modern APIs:
  • vim.keymap.set over vim.api.nvim_set_keymap
  • vim.api.nvim_create_user_command for user commands
• Use buffer-local mappings/options when behavior is buffer-scoped.
• Keep plugin setup isolated in lua/plugins/config/<plugin>.lua when practical.
• Keep core bootstrap files (core/*) minimal and composable.

Error handling and resilience

• Fail softly for optional dependencies when reasonable (pcall(require, ...)).
• Avoid crashing startup for non-critical plugin behavior.
• Use vim.notify(..., vim.log.levels.<LEVEL>) for actionable runtime feedback.
• For external commands in Lua, check return status if failure is meaningful.

Plugin and dependency changes

• Add/modify plugin specs only in lua/plugins/init.lua unless refactoring.
• Keep plugin options in dedicated config modules when they grow beyond trivial.
• For plugins with build hooks (example: markdown preview), do not assume Node/npm is available in all environments; mention prerequisites in PR notes.
• Preserve lockfile intent (lazy-lock.json) when updating plugin versions.

Commit hygiene for agents

• Make focused changes with minimal scope.
• Do not fix unrelated style issues opportunistically.
• Include validation notes in your final response (what you ran, what you could not run).
• If commands are unavailable locally, state that clearly and provide exact follow-up commands.

Cursor / Copilot Rules

Checked paths:

• .cursorrules
• .cursor/rules/
• .github/copilot-instructions.md

Current status: no Cursor or Copilot instruction files were found in this repository.

If these files are added later, agents must treat them as higher-priority repository policy and this document should be updated to summarize them.

Agent Workflow Checklist

• Read nearby files before editing; match local patterns.
• Keep edits minimal and reversible.
• Run at least one headless Neovim smoke check after non-trivial changes.
• For plugin changes, run '+Lazy! sync' headless when possible.
• Update this file when tooling, test framework, or style policy changes.