skill-neovim-implementation

This skill activates when:

• Task language is "lua"
• Implementation involves Neovim plugins, configurations, or utilities
• /implement command is invoked for a Lua task
• Plan exists with phases ready for execution

Follow strict test-driven development:

```

1. Load implementation plan
2. Identify target functionality
3. Write failing test first (busted/plenary)
4. Implement minimal code to pass
5. Run test to verify pass
6. Refactor while tests pass
7. Repeat for each feature
8. Verify with full test suite

```

TDD Rules

1. Write test first - Never implement without a failing test
2. Minimal implementation - Only write code to make the test pass
3. Refactor under green - Only refactor when all tests pass
4. One feature at a time - Focus on single functionality per cycle

Run All Tests

```bash

# Run all tests with plenary

nvim --headless -c "PlenaryBustedDirectory tests/"

# With minimal init (faster, isolated)

nvim --headless -c "PlenaryBustedDirectory tests/ {minimal_init = 'tests/minimal_init.lua'}"

```

Run Specific Tests

```bash

# Run single test file

nvim --headless -c "PlenaryBustedFile tests/path/to/spec.lua"

# Run tests matching pattern

nvim --headless -c "PlenaryBustedDirectory tests/ {pattern = 'picker'}"

```

Lint Lua Code

```bash

# Check for syntax errors

luacheck lua/ --codes

# Check specific file

luacheck lua/neotex/path/to/file.lua

```

Create test files following this pattern:

```lua

-- tests/module_name_spec.lua

describe("ModuleName", function()

local module

before_each(function()

-- Reset state before each test

package.loaded["neotex.module_name"] = nil

module = require("neotex.module_name")

end)

describe("function_name", function()

it("should do expected behavior", function()

local result = module.function_name(input)

assert.equals(expected, result)

end)

it("should handle edge case", function()

local result = module.function_name(edge_input)

assert.is_nil(result)

end)

end)

end)

```

Assertion Patterns

```lua

-- Use is_nil/is_not_nil for pattern matching

assert.is_not_nil(str:match("pattern")) -- Match found

assert.is_nil(str:match("pattern")) -- Match not found

-- Equality

assert.equals(expected, actual)

assert.same(expected_table, actual_table)

-- Boolean

assert.is_true(condition)

assert.is_false(condition)

-- Errors

assert.has_error(function() error_func() end)

```

Lua Module Directory

```

nvim/

├── lua/neotex/

│ ├── core/ # Core utilities (loader, options, keymaps)

│ │ └── module.lua

│ ├── plugins/ # Plugin configurations

│ │ ├── ai/ # AI integrations

│ │ ├── editor/ # Editor enhancements

│ │ ├── lsp/ # Language server configs

│ │ ├── text/ # Format-specific (LaTeX, Markdown)

│ │ ├── tools/ # Development tools

│ │ └── ui/ # UI components

│ └── util/ # Utility functions

├── after/ftplugin/ # Filetype-specific settings

└── tests/ # Test suites

```

Standard Module Template

```lua

-- lua/neotex/category/module-name.lua

local M = {}

--- Brief description of the module

--- @module neotex.category.module-name

--- Function description

--- @param input string Input parameter

--- @return string|nil result Result or nil on failure

function M.function_name(input)

if not input then

return nil

end

-- Implementation

return result

end

--- Setup function for configuration

--- @param opts table? Optional configuration

function M.setup(opts)

opts = opts or {}

-- Apply configuration

end

return M

```

Plugin Definition Pattern

```lua

-- lua/neotex/plugins/category/plugin-name.lua

return {

"author/plugin-name",

event = "VeryLazy", -- or specific events: BufReadPre, InsertEnter

dependencies = {

"dep/plugin",

},

opts = {

-- Configuration options passed to setup()

option_key = "value",

},

config = function(_, opts)

require("plugin-name").setup(opts)

end,

}

```

Complex Plugin with Keymaps

```lua

return {

"author/plugin-name",

event = "VeryLazy",

keys = {

{ "xx", "PluginCommand", desc = "Plugin: Description" },

{ "xy", function() require("plugin").action() end, desc = "Plugin: Action" },

},

opts = {

-- Options

},

config = function(_, opts)

local plugin = require("plugin-name")

plugin.setup(opts)

-- Additional configuration after setup

end,

}

```

Using pcall for Safe Calls

```lua

local function safe_require(module_name)

local ok, module = pcall(require, module_name)

if not ok then

vim.notify(

"Failed to load " .. module_name .. ": " .. tostring(module),

vim.log.levels.WARN

)

return nil

end

return module

end

-- Usage

local telescope = safe_require("telescope")

if telescope then

telescope.setup({})

end

```

Graceful Degradation

```lua

local function with_fallback(primary_fn, fallback_fn)

local ok, result = pcall(primary_fn)

if ok then

return result

end

return fallback_fn()

end

```

User Notifications

```lua

-- Info level

vim.notify("Operation completed", vim.log.levels.INFO)

-- Warning level

vim.notify("Missing optional dependency", vim.log.levels.WARN)

-- Error level

vim.notify("Critical error: " .. err, vim.log.levels.ERROR)

```

```

1. Receive task context with plan path
2. Load and parse implementation plan
3. Find resume point (first non-completed phase)
4. For each remaining phase:

a. Update phase status to [IN PROGRESS]

b. Write tests for phase features

c. Run tests (should fail)

d. Implement features

e. Run tests (should pass)

f. Verify with luacheck

g. Update phase status to [COMPLETED]

h. Git commit

1. Run full test suite
2. Create implementation summary
3. Return results

```

Create summary at .claude/specs/{N}_{SLUG}/summaries/implementation-summary-{DATE}.md:

```markdown

# Implementation Summary: Task #{N}

Completed: {date}

Duration: {time}

{Overview of implemented features}

• lua/neotex/path/to/file.lua - {description}

• lua/neotex/path/to/file.lua - {change description}

• tests/path/to/spec.lua - {test coverage}

```

N tests passed

0 tests failed

Coverage: X%

```

• All tests pass
• luacheck reports no errors
• Plugin loads correctly

{Any important notes or follow-ups}

```

```json

{

"status": "completed|partial",

"summary": "Implementation complete with TDD",

"artifacts": [

{

"path": ".claude/specs/{N}_{SLUG}/summaries/...",

"type": "summary",

"description": "Implementation summary"

}

],

"phases_completed": 3,

"phases_total": 3,

"files_created": [

"lua/neotex/path/to/file.lua"

],

"files_modified": [

"lua/neotex/existing/file.lua"

],

"tests_added": [

"tests/path/to/spec.lua"

],

"test_results": {

"passed": 10,

"failed": 0,

"total": 10

}

}

```

• Entry point: nvim/init.lua
• Core config: nvim/lua/neotex/config/
• Plugin configs: nvim/lua/neotex/plugins/
• Core utilities: nvim/lua/neotex/core/
• Utilities: nvim/lua/neotex/util/
• Tests: nvim/tests/
• Standards: nvim/CLAUDE.md, nvim/docs/CODE_STANDARDS.md
• Rules: .claude/rules/neovim-lua.md

• Indentation: 2 spaces, expandtab
• Line length: ~100 characters
• Naming: lowercase_with_underscores
• Comments: LuaDoc style for public APIs
• Error handling: pcall for external dependencies
• Testing: All public APIs must have tests