AGENTS.md

AGENTS.md

Agent-facing contributor guide for this Neovim config repository.

Repository Snapshot

• Project type: personal/forked kickstart.nvim configuration.
• Primary language: Lua.
• Entry point: init.lua.
• Additional modules: lua/custom/** and lua/kickstart/**.
• Plugin manager: lazy.nvim.
• Lockfile: lazy-lock.json (tracks plugin versions).

Sources Used For This Guide

• README.md
• .stylua.toml
• init.lua
• lua/custom/**/*.lua
• lua/kickstart/**/*.lua

Cursor/Copilot Rules

• No .cursorrules file found.
• No .cursor/rules/ directory found.
• No .github/copilot-instructions.md found.
• Therefore: follow this AGENTS.md + existing repository conventions.

Environment and Prerequisites

• Neovim target: latest stable or nightly (README states this explicitly).
• External tools commonly expected:
  • git, make, unzip, rg (checked by lua/kickstart/health.lua).
  • Often useful: fd, tree-sitter CLI.
  • Formatters used by config: stylua, prettier, bean-format.
• If tooling is missing, prefer graceful degradation over hard failure.

Build / Lint / Test Commands

This repo is a config repo, so "build" and "test" are mostly lint/health/smoke checks.

Quick Command Matrix

• Full format check:
  • stylua --check .
• Apply Lua formatting:
  • stylua .
• Sync/install plugins headlessly:
  • nvim --headless "+Lazy! sync" +qa
• Run kickstart health checks headlessly:
  • nvim --headless "+checkhealth kickstart" +qa
• Open once for runtime/plugin errors (manual smoke):
  • nvim

Single-Test Guidance (Important)

There is no formal unit-test framework (no busted, plenary test suite, make test, etc.).

Use one of these "single check" equivalents when you need narrow validation:

• Single file syntax check (if Lua compiler available):
  • luac -p path/to/file.lua
• Single module load check in Neovim:
  • nvim --headless "+lua require('custom.plugins.opencode')" +qa
  • Replace module path as needed.
• Single feature health check:
  • nvim --headless "+checkhealth kickstart" +qa
  • Read only the section relevant to your change.

If a task asks for "run one test", use a module-load or syntax check above and report it as a targeted smoke test.

Validation Order For Agents

When making code changes, run checks in this order unless task says otherwise:

1. stylua --check .
2. Targeted module/syntax check for changed file(s).
3. nvim --headless "+checkhealth kickstart" +qa for broader sanity.

If a command is unavailable locally, state it clearly and provide the exact command for humans/CI. If a command is unavailable locally, state it clearly and provide the exact command for the local machine.

Code Style: Formatting

Formatting rules are authoritative in .stylua.toml:

• Indentation: 2 spaces.
• Max column width: 160.
• Line endings: Unix.
• Quote style: AutoPreferSingle (prefer single quotes).
• Call parentheses: None where valid (require 'x' style).
• Collapse simple statements: always.

Never hand-format against Stylua output; run Stylua instead.

Code Style: Imports and Module Structure

• Prefer local requires near first use:
  • local builtin = require 'telescope.builtin'
• For plugin specs, return a Lua table from module root:
  • return { ... }
• Keep plugin declarations declarative (opts) unless imperative setup is necessary (config = function() ... end).
• In init.lua, follow existing kickstart ordering and comment style.
• Avoid introducing new top-level globals.

Code Style: Types and Annotations

This repo uses LuaLS annotations heavily. Preserve and extend when useful:

• ---@module 'lazy'
• ---@type LazySpec
• Plugin-specific types where available (e.g. Gitsigns.Config, conform.setupOpts).
• Use ---@diagnostic disable-next-line: ... only when justified and narrowly scoped.

Do not remove useful annotations just to reduce lines.

Code Style: Naming Conventions

• Modules/files:
  • lower_snake_case for filenames where practical.
  • plugin files grouped by feature under lua/custom/plugins/enable/ (active) and lua/custom/plugins/disable/ (inactive).
• Local variables/functions:
  • descriptive lower_snake_case.
  • short names only for conventional temporary values (buf, opts, client).
• Augroup names:
  • stable, descriptive strings (e.g. 'NeoTreeAutoRefresh', 'kickstart-lsp-highlight').
• Keymap descriptions:
  • concise, action-oriented, consistent bracket hints used by which-key.

Code Style: Error Handling and Resilience

• Prefer non-fatal behavior for optional dependencies.
  • Example pattern already used: pcall(require('telescope').load_extension, 'fzf').
• Guard external tool usage with vim.fn.executable(...) when needed.
• Use vim.notify(..., vim.log.levels.WARN/ERROR) for actionable user-facing issues.
• Keep startup robust: avoid hard errors for optional plugin features.

Plugin and Dependency Conventions

• Add plugins through lazy specs, keeping structure consistent with existing blocks.
• When adding a new plugin, prefer putting it under lua/custom/plugins/enable/*.lua (or other custom modules) instead of editing upstream kickstart blocks in init.lua, to minimize merge conflicts with upstream updates.
• To disable a custom plugin without deleting its spec, move it to lua/custom/plugins/disable/.
• Prefer minimal configuration first (opts = {}), then extend only if needed.
• Respect platform guards (e.g., make checks, Windows conditionals).
• Do not edit lockfile manually; let lazy manage lazy-lock.json updates.

Custom Keymap and Layout Conventions

• Keep custom keymaps in lua/custom/keymaps.lua.
• Keep upstream kickstart keymaps in init.lua unless intentionally overriding behavior.
• If adding a new <leader> namespace in lua/custom/keymaps.lua, also register its group in which-key (init.lua which-key spec).
• Keep layout/window helper logic centralized in lua/custom/layout.lua (for example focus_main_window()), and reuse it from plugin modules instead of duplicating sidebar/window filtering logic.
• If a plugin needs startup window choreography, call require('custom.layout') helpers rather than re-implementing window focus rules.

Editing and Change Scope

• Keep changes minimal and local to the requested task.
• Do not refactor unrelated sections opportunistically.
• Preserve existing comments unless they become inaccurate.
• Maintain ASCII unless file already relies on Unicode symbols/icons.

Change Hygiene For Agents

• Before finalizing: run formatting + at least one targeted runtime check.
• Mention exactly what you validated and what you could not validate.
• If no formal tests exist, explicitly say "no unit test suite in this repo".
• Include file paths in reports so reviewers can jump directly.

When Unsure

• Follow existing patterns in nearby files first.
• Prefer reversible, low-risk changes.
• Ask for clarification only when ambiguity materially changes behavior.