# Specification: Tree-Sitter Lua MCP Tools

## Overview
Expand the Conductor's AI context-gathering and surgical editing capabilities by introducing full Tree-Sitter parsing support for the Lua programming language. This will bring Lua to feature-parity with the existing Python MCP tools, enabling deep AST-driven structural mapping, documentation extraction, and precise code modification.

## Functional Requirements
- **Grammar Integration:**
  - Introduce `tree-sitter-lua` (or a suitable native equivalent) to the project's parsing environment to generate deterministic Abstract Syntax Trees for Lua files.
- **Structural Parsing Tools:**
  - **`lua_get_skeleton`:** Extract a high-level view of a Lua file, containing all table/module declarations and function signatures with their associated comments, replacing function bodies with `...`.
  - **`lua_get_code_outline`:** Generate a hierarchical text outline showing line ranges for major structural elements (functions, loops, distinct blocks).
- **Documentation & Context Tools:**
  - **`lua_get_docstring` (or comment block):** Extract the block comment immediately preceding a function or module definition.
  - **`lua_find_usages`:** Locate usages of specific Lua symbols/functions across a file or directory using AST or strict regex boundaries.
- **Surgical Editing Tools:**
  - **`lua_get_definition`:** Extract the full source code of a specific Lua function or table definition.
  - **`lua_update_definition`:** Surgically replace the implementation of a specific Lua function without relying on generic search-and-replace strings.
  - **`lua_set_signature`:** Update only the signature (parameters) of a Lua function.

## Non-Functional Requirements
- **Performance:** Parsing and skeleton generation should be heavily cached (using `mtime` invalidation) to ensure near-instantaneous responses, matching the current Python tool performance.
- **Robustness:** The parser must gracefully handle malformed Lua code, returning as much structural information as possible rather than failing entirely.

## Acceptance Criteria
- [ ] A new suite of Lua-specific tools (`lua_get_skeleton`, `lua_get_code_outline`, `lua_get_definition`, `lua_update_definition`) is available via the MCP Client.
- [ ] Automated tests verify that `lua_get_skeleton` correctly identifies local functions, global functions, and table-assigned methods.
- [ ] `lua_update_definition` can successfully replace a multi-line function body while maintaining the surrounding file structure and indentation.
- [ ] The `tree-sitter-lua` grammar is successfully integrated into the build/setup pipeline.

## Out of Scope
- Full language server protocol (LSP) features like deep type inference or cross-file variable renaming.
- Automated code formatting or linting for Lua (formatting relies on external ecosystem tools if needed).
