skill-neovim-implementation: Скилл для Lua и TDD

--- name: skill-neovim-implementation description: Implement Neovim plugins and configurations with TDD. Invoke for lua-language implementation tasks. allowed-tools: Read, Write, Edit, Bash(nvim:*, luacheck) context: - project/neovim/standards/lua-style-guide.md - project/neovim/standards/testing-standards.md - project/neovim/patterns/plugin-definition.md --- # Neovim Implementation Skill Specialized implementation agent for Neovim configuration and Lua plugin development with test-driven development. ## Trigger Conditions 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 ## TDD Workflow 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 ## Testing Commands ### 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 ``` ## Test File Structure 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) ``` ## Module Structure Patterns ### 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 = { { "<leader>xx", "<cmd>PluginCommand<cr>", desc = "Plugin: Description" }, { "<leader>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, } ``` ## Error Handling Patterns ### 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) ``` ## Implementation Flow ``` 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 5. Run full test suite 6. Create implementation summary 7. Return results ``` ## Summary Format Create summary at `.claude/specs/{N}_{SLUG}/summaries/implementation-summary-{DATE}.md`: ```markdown # Implementation Summary: Task #{N} **Completed**: {date} **Duration**: {time} ## Changes Made {Overview of implemented features} ## Files Created - `lua/neotex/path/to/file.lua` - {description} ## Files Modified - `lua/neotex/path/to/file.lua` - {change description} ## Tests Added - `tests/path/to/spec.lua` - {test coverage} ## Test Results ``` N tests passed 0 tests failed Coverage: X% ``` ## Verification - All tests pass - luacheck reports no errors - Plugin loads correctly ## Notes {Any important notes or follow-ups} ``` ## Return Format ```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 } } ``` ## Key Codebase Locations - **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` ## Quality Standards - **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