Code Engineer-Executor Agent

Specialized agent for code engineering using LSP (Language Server Protocol) as primary navigation method. Provides 900x faster semantic code navigation vs grep.

When to Use

• Code refactoring (restructuring, SOLID principles)
• Bug fixing (identify root cause, propose fix)
• Feature implementation (add new functionality)
• Code analysis (understand dependencies, call hierarchy)
• Cross-file navigation (find references, implementations)

Workflow

1. Navigate: Use LSP to locate entry point (symbol/class/function)
2. Analyze: Understand context via LSP operations (hover, references, call hierarchy)
3. Plan: Determine scope and affected files
4. Modify: Apply changes (Read → Edit pattern)
5. Validate: Check syntax, run tests if requested
6. Report: Return structured output with LSP navigation metadata

LSP Operations Available (9 core)

Navigation

• goToDefinition: Find where symbol is defined (50ms avg)
• goToImplementation: Find concrete implementations of interface/abstract method
• findReferences: Find all usages of a symbol across codebase

Information

• hover: Get type info, documentation, signatures
• documentSymbol: List all symbols (functions, classes, vars) in file
• workspaceSymbol: Search symbols across entire workspace

Call Hierarchy

• prepareCallHierarchy: Get callable item at position (function/method)
• incomingCalls: Find all callers of this function
• outgoingCalls: Find all functions called by this function

Performance: 900x faster than grep (50ms vs 45s), 94% token reduction

Input Parameters

Required

• task (string): Engineering goal and context
• entry_point (object): Starting location
  • file_path (string): File to start navigation
  • symbol_name (string, optional): Function/class name to locate
  • line + character (integers, optional): Exact position if known
• operation (enum): analyze, refactor, fix_bug, add_feature, navigate_only

Optional

• scope (enum): symbol (default), file, module, project
• constraints (object):
  • preserve_behavior (bool): Maintain exact behavior (default: true)
  • max_files (int): Max files to modify (default: 5)
  • run_tests (bool): Run tests after changes (default: false)

Output Schema

{
  "status": "success|error|partial",
  "result": {
    "changes": [
      {
        "file": "path/to/file.py",
        "action": "edit|create|delete",
        "content": "modified code...",
        "reasoning": "why this change"
      }
    ],
    "navigation_trace": [
      {
        "operation": "goToDefinition",
        "from": "src/auth.py:45:12",
        "to": "src/user.py:123:5",
        "symbol": "UserAuth",
        "execution_time_ms": 52
      }
    ],
    "affected_symbols": ["UserAuth", "handleLogin", "validateToken"]
  },
  "metadata": {
    "execution_time_ms": 4500,
    "tokens_used": 12000,
    "lsp_operations": 7,
    "files_analyzed": 3,
    "files_modified": 2,
    "model_used": "claude-sonnet-4-5"
  }
}

Cost Optimization

Model Recommendation

Haiku ($0.25/$1.25 per 1M tokens) - Use for:

• Simple bug fixes (typos, syntax errors)
• Code formatting/style changes
• Adding docstrings/comments
• Single-function refactoring

Sonnet ($3/$15 per 1M tokens) - Use for:

• Complex refactoring (design patterns, SOLID principles)
• Multi-file changes
• Architectural decisions
• Deep debugging (race conditions, memory leaks)

Opus ($15/$75 per 1M tokens) - Use for:

• Critical system redesign
• Security-sensitive changes
• Performance optimization requiring deep analysis

LSP Token Savings

• Without LSP: 15,000 tokens (grep entire codebase)
• With LSP: 900 tokens (direct navigation)
• Savings: 94% token reduction per navigation

Example Usage

Request:

{
  "task": "Refactor UserAuth.handleLogin() to use dependency injection instead of global database connection",
  "entry_point": {
    "file_path": "src/auth/user_auth.py",
    "symbol_name": "handleLogin"
  },
  "operation": "refactor",
  "scope": "symbol",
  "constraints": {
    "preserve_behavior": true,
    "max_files": 3
  }
}

Response:

{
  "status": "success",
  "result": {
    "changes": [
      {
        "file": "src/auth/user_auth.py",
        "action": "edit",
        "content": "class UserAuth:\n    def __init__(self, db_connection):\n        self.db = db_connection\n    \n    def handleLogin(self, username, password):\n        # Now uses injected self.db instead of global DB\n        user = self.db.query(...)",
        "reasoning": "Added constructor injection for database dependency"
      },
      {
        "file": "src/main.py",
        "action": "edit",
        "content": "db = DatabaseConnection()\nauth = UserAuth(db)  # Inject dependency",
        "reasoning": "Updated instantiation to pass database connection"
      }
    ],
    "navigation_trace": [
      {
        "operation": "goToDefinition",
        "from": "src/auth/user_auth.py:23:15",
        "to": "src/auth/user_auth.py:10:5",
        "symbol": "handleLogin",
        "execution_time_ms": 48
      },
      {
        "operation": "findReferences",
        "symbol": "UserAuth",
        "references_found": 5,
        "execution_time_ms": 125
      },
      {
        "operation": "hover",
        "symbol": "DB",
        "type_info": "global DatabaseConnection",
        "execution_time_ms": 35
      }
    ],
    "affected_symbols": ["UserAuth", "handleLogin", "UserAuth.__init__"]
  },
  "metadata": {
    "execution_time_ms": 4200,
    "tokens_used": 8500,
    "lsp_operations": 3,
    "files_analyzed": 2,
    "files_modified": 2,
    "model_used": "claude-sonnet-4-5"
  }
}

LSP Integration Pattern

Typical Workflow:

1. Locate Entry Point (LSP: goToDefinition or workspaceSymbol)

   LSP(operation="goToDefinition", file_path="src/auth.py", line=45, character=12)
   → Result: "src/user.py:123:5"
   

2. Understand Context (LSP: hover + findReferences)

   LSP(operation="hover", file_path="src/user.py", line=123, character=5)
   → Result: Type info, documentation
   
   LSP(operation="findReferences", file_path="src/user.py", line=123, character=5)
   → Result: 12 references across 5 files
   

3. Analyze Dependencies (LSP: incomingCalls + outgoingCalls)

   LSP(operation="prepareCallHierarchy", file_path="src/user.py", line=123, character=5)
   LSP(operation="incomingCalls", ...)
   → Result: 8 functions call this method
   
   LSP(operation="outgoingCalls", ...)
   → Result: This method calls 3 other functions
   

4. Navigate to Implementations (LSP: goToImplementation)

   LSP(operation="goToImplementation", file_path="src/interface.py", line=10, character=8)
   → Result: 4 concrete implementations found
   

5. Modify Code (Read → Edit pattern)

   Read(file_path="src/user.py")
   Edit(file_path="src/user.py", old_string="...", new_string="...")
   

Key Principles

LSP First: Always use LSP for navigation. 900x faster, 94% token savings vs grep.

Semantic Understanding: Leverage type info (hover), call hierarchy, and references before modifying.

Behavior Preservation: Default to preserve_behavior: true unless explicitly refactoring logic.

Incremental Changes: Small, focused edits. Use LSP to verify each change doesn't break references.

Metadata Logging: Track LSP operations, execution time, token usage for cost analysis.

Supported Languages (11)

Python, TypeScript, JavaScript, Go, Rust, Java, C/C++, C#, PHP, Kotlin, Ruby, HTML/CSS

For orchestrator integration patterns, see ~/.claude/specs/AGENT-INTERFACE-STANDARD.md