diff --git a/common/engineering/commit-staged/agents/openai.yaml b/common/engineering/commit-staged/agents/openai.yaml new file mode 100644 index 0000000..83eb727 --- /dev/null +++ b/common/engineering/commit-staged/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Commit Staged" + short_description: "Commit staged changes to the repository" +policy: + allow_implicit_invocation: false diff --git a/common/engineering/implement-isolation-tmux/agents/openai.yaml b/common/engineering/implement-isolation-tmux/agents/openai.yaml new file mode 100644 index 0000000..bf6c81e --- /dev/null +++ b/common/engineering/implement-isolation-tmux/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Implement Isolation Tmux" + short_description: "Implement isolation using tmux for the agent" +policy: + allow_implicit_invocation: false diff --git a/common/engineering/implement-isolation/agents/openai.yaml b/common/engineering/implement-isolation/agents/openai.yaml new file mode 100644 index 0000000..8253cc4 --- /dev/null +++ b/common/engineering/implement-isolation/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Implement Isolation" + short_description: "Implement isolation for the agent" +policy: + allow_implicit_invocation: false diff --git a/common/engineering/lsp-code-analysis/SKILL.md b/common/engineering/lsp-code-analysis/SKILL.md new file mode 100644 index 0000000..e7ad684 --- /dev/null +++ b/common/engineering/lsp-code-analysis/SKILL.md @@ -0,0 +1,334 @@ +--- +name: lsp-code-analysis +description: Semantic code analysis via LSP. Navigate code (definitions, references, implementations), search symbols, preview refactorings, and get file outlines. Use for exploring unfamiliar codebases or performing safe refactoring. +license: LICENSE +--- + +# LSP Code Analysis + +## IMPORTANT: PREREQUISITE + +To use this skill, you **MUST** follow these steps: + +1. **Check for updates**: Run the [update script](scripts/update.sh) to ensure you are using the latest version of the tool. +2. **Verify project support**: Run `lsp server start ` to start the LSP server and confirm the project is supported. + +**IF YOU DO NOT PERFORM THESE STEPS, YOU ARE NOT ALLOWED TO USE THIS SKILL.** + +## Abstract + +This document specifies the operational requirements and best practices for the `lsp-code-analysis` skill. It provides a semantic interface to codebase navigation, analysis and refactoring via the Language Server Protocol (LSP). + +## Overview + +You are provided with `lsp` CLI tool for semantic code navigation and analysis. It SHOULD be preferred over `read` or `grep` for most code understanding tasks. + +Usages: + +- **Semantic navigation**: Jump to definitions, find references, locate implementations - understands code structure, not just text patterns. +- **Language-aware**: Distinguishes between variables, functions, classes, types - eliminates false positives from text search. +- **Cross-file intelligence**: Trace dependencies, refactor safely across entire codebase - knows what imports what. +- **Type-aware**: Get precise type information, signatures, documentation - without reading implementation code. + +### Tool Selection + +**Guideline**: You SHOULD prioritize LSP commands for code navigation and analysis. Agents MAY use `read` or `rg` ONLY when semantic analysis is not applicable (e.g., searching for comments or literal strings). + +| Task | Traditional Tool | Recommended LSP Command | +| ------------------- | ---------------- | ----------------------------------------------- | +| **Find Definition** | `rg`, `read` | [`definition`](#definition-navigate-to-source)| +| **Find Usages** | `rg` | [`reference`](#reference-find-all-usages) | +| **Understand File** | `read` | [`outline`](#outline-file-structure) | +| **View Docs/Types** | `read` | [`doc`](#doc-get-documentation) | +| **Refactor** | `sed` | See [Refactoring Guide](references/refactor.md) | + +## Commands + +All commands support `-h` or `--help`. + +### Locating Symbols + +Most commands use a unified locating syntax via the `--scope` and `--find` options. + +**Arguments**: `` + +**Options**: + +- `--scope`: Narrow search to a symbol body or line range. +- `--find`: Text pattern to find within the scope. + +**Scope Formats**: + +- ``: Single line number (e.g., `42`). +- `,`: Line range (e.g., `10,20`). Use `0` for end to mean till EOF (e.g., `10,0`). +- ``: Symbol path with dots (e.g., `MyClass.my_method`). + +**Find Pattern (`--find`)**: + +The `--find` option narrows the target to a **text pattern within the selected scope**: + +- The scope is determined by `--scope` (line/range/symbol). If no `--scope` is given, the entire file is the scope. +- Pattern matching is **whitespace-insensitive**: differences in spaces, tabs, and newlines are ignored. +- You MAY include the cursor marker `<|>` inside the pattern to specify the **exact position of interest** within the match (for example, on a variable name, keyword, or operator). +- If `--find` is omitted, the command uses the start of the scope (or a tool-specific default) as the navigation target. + +**Cursor Marker (`<|>`)**: + +The `<|>` marker indicates the exact position for symbol resolution. It represents the character immediately to its right. Use it within the find pattern to point to a specific element (e.g., `user.<|>name` to target the `name` property). + +**Examples**: + +- `lsp doc foo.py --find "self.<|>"` - Find `self.` in entire file, position at the character after the dot (typically for completion or member access) +- `lsp doc foo.py --scope 42 --find "return <|>result"` - Find `return result` on line 42, position at `r` of `result` +- `lsp doc foo.py --scope 10,20 --find "if <|>condition"` - Find `if condition` in lines 10-20, position at `c` of `condition` +- `lsp doc foo.py --scope MyClass.my_method --find "self.<|>"` - Find `self.` within `MyClass.my_method`, position after the dot +- `lsp doc foo.py --scope MyClass` - Target the `MyClass` symbol directly + +**Guideline for Scope vs. Find**: + +- Use `--scope ` (e.g., `--scope MyClass`, `--scope MyClass.my_method`) to target **classes, functions, or methods**. This is the most robust and preferred way to target symbol. +- Use `--find` (often combined with `--scope`) to target variables or specific positions. Use this when the target is not a uniquely named symbol or when you need to pinpoint a specific usage within a code block. + +Agents MAY use `lsp locate --scope --find ` to verify if the target exists in the file and view its context before running other commands. + +```bash +# Verify location exists +lsp locate main.py --scope 42 --find "<|>process_data" +``` + +### Pagination + +Use pagination for large result sets like `reference` or `search`. + +- `--pagination-id `: (Required) Unique session ID for consistent paging. +- `--max-items `: Page size. +- `--start-index `: Offset (0-based). + +**Example**: + +```bash +# Page 1 +lsp search "User" --max-items 20 --pagination-id "task_123" + +# Page 2 +lsp search "User" --max-items 20 --start-index 20 --pagination-id "task_123" +``` + +**Guideline**: Use pagination with a unique ID for common symbols to fetch results in manageable chunks. Increment `--start-index` using the same ID to browse. + +### Outline: File Structure + +Get hierarchical symbol structure without reading implementation. + +```bash +# Get main symbols (classes, functions, methods) +lsp outline + +# Get all symbols including variables and parameters +lsp outline --all +``` + +Agents SHOULD use `outline` before reading files to avoid unnecessary context consumption. + +### Definition: Navigate to Source + +Navigate to where symbols are defined. + +```bash +# Jump to where User.get_id is defined +lsp definition models.py --scope User.get_id + +# Find where an imported variable comes from +lsp definition main.py --scope 42 --find "<|>config" + +# Find declaration (e.g., header files, interface declarations) +lsp definition models.py --scope 25 --mode declaration --find "<|>provider" + +# Find the class definition of a variable's type +lsp definition models.py --scope 30 --find "<|>user" --mode type_definition +``` + +### Reference: Find All Usages + +Find where symbols are used or implemented. + +```bash +# Find all places where logger is referenced +lsp reference main.py --scope MyClass.run --find "<|>logger" + +# Find all concrete implementations of an interface/abstract class +lsp reference api.py --scope "IDataProvider" --mode implementations + +# Get more surrounding code context for each reference +lsp reference app.py --scope 10 --find "<|>my_var" --context-lines 5 + +# Limit results for large codebases +lsp reference utils.py --find "<|>helper" --max-items 50 --start-index 0 +``` + +### Doc: Get Documentation + +Get documentation and type information without navigating to source. + +```bash +# Get docstring and type info for symbol at line 42 +lsp doc main.py --scope 42 + +# Get API documentation for process_data function +lsp doc models.py --scope process_data +``` + +Agents SHOULD prefer `doc` over `read` when only documentation or type information is needed. + +### Search: Global Symbol Search + +Search for symbols across the workspace when location is unknown. + +```bash +# Search by name (defaults to current directory) +lsp search "MyClassName" + +# Search in specific project +lsp search "UserModel" --project /path/to/project + +# Filter by symbol kind (can specify multiple times) +lsp search "init" --kinds function --kinds method + +# Limit and paginate results for large codebases +lsp search "Config" --max-items 10 +lsp search "User" --max-items 20 --start-index 0 +``` + +Agents SHOULD use `--kinds` to filter results and reduce noise. + +### Symbol: Get Complete Symbol Code + +Get the full source code of the symbol containing a location. + +```bash +# Get complete code of the function/class at line 15 +lsp symbol main.py --scope 15 + +# Get full UserClass implementation +lsp symbol utils.py --scope UserClass + +# Get complete method implementation +lsp symbol models.py --scope User.validate +``` + +Response includes: symbol name, kind (class/function/method), range, and **complete source code**. + +Agents SHOULD use `symbol` to read targeted code blocks instead of using `read` on entire files. + +### Refactoring Operations + +Read [Refactoring Guide](references/refactor.md) for rename, extract, and other safe refactoring operations. + +### Server: Manage Background Servers + +The background manager starts automatically. Manual control is OPTIONAL. + +```bash +# List running servers +lsp server list + +# Start server for a project +lsp server start + +# Stop server for a project +lsp server stop + +# Shutdown the background manager +lsp server shutdown +``` + +## Best Practices + +### General Workflows + +#### Understanding Unfamiliar Code + +The RECOMMENDED sequence for exploring new codebases: + +```bash +# Step 1: Start with outline - Get file structure without reading implementation +lsp outline + +# Step 2: Inspect signatures - Use doc to understand API contracts +lsp doc --scope + +# Step 3: Navigate dependencies - Follow definition chains +lsp definition --scope + +# Step 4: Map usage - Find where code is called with reference +lsp reference --scope +``` + +#### Debugging Unknown Behavior + +```bash +# Step 1: Locate symbol definition workspace-wide +lsp search "" + +# Step 2: Verify implementation details +lsp definition --scope + +# Step 3: Trace all callers to understand invocation context +lsp reference --scope +``` + +### Finding Interface Implementations + +```bash +# Step 1: Locate interface definition +lsp search "IUserService" --kinds interface + +# Step 2: Find all implementations +lsp reference src/interfaces.py --scope IUserService --mode implementations +``` + +### Tracing Data Flow + +```bash +# Step 1: Find where data is created +lsp search UserDTO --kinds class + +# Step 2: Find where it's used +lsp reference models.py --scope UserDTO + +# Step 3: Check transformations +lsp doc transform.py --scope map_to_dto +``` + +### Understanding Type Hierarchies + +```bash +# Step 1: Get class outline +lsp outline models.py + +# Step 2: Find subclasses (references to base) +lsp reference models.py --scope BaseModel + +# Step 3: Check type definitions +lsp definition models.py --scope BaseModel --mode type_definition +``` + +### Performance Tips + +```bash +# Use outline instead of reading entire files +lsp outline large_file.py # Better than: read large_file.py + +# Use symbol paths for nested structures (more precise than line numbers) +lsp definition models.py --scope User.Profile.validate + +# Limit results in large codebases +lsp search "User" --max-items 20 + +# Use doc to understand APIs without navigating to source +lsp doc api.py --scope fetch_data # Get docs/types without jumping to definition + +# Verify locate strings if commands fail +lsp locate main.py --scope 42 --find "<|>my_var" +``` + diff --git a/common/engineering/lsp-code-analysis/agents/openai.yaml b/common/engineering/lsp-code-analysis/agents/openai.yaml new file mode 100644 index 0000000..b1d99d2 --- /dev/null +++ b/common/engineering/lsp-code-analysis/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "LSP Code Analysis" + short_description: "Analyze code using LSP" +policy: + allow_implicit_invocation: true diff --git a/common/engineering/project-context-pack/agents/openai.yaml b/common/engineering/project-context-pack/agents/openai.yaml new file mode 100644 index 0000000..3007365 --- /dev/null +++ b/common/engineering/project-context-pack/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Project Context Pack" + short_description: "Provides context about the project to the agent" +policy: + allow_implicit_invocation: false diff --git a/common/engineering/setup-skills/agents/openai.yaml b/common/engineering/setup-skills/agents/openai.yaml new file mode 100644 index 0000000..8824d5f --- /dev/null +++ b/common/engineering/setup-skills/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Setup Engineering Skills" + short_description: "Setup engineering skills for the agent" +policy: + allow_implicit_invocation: false diff --git a/common/in-progress/agent-handoff/agents/openai.yaml b/common/in-progress/agent-handoff/agents/openai.yaml new file mode 100644 index 0000000..cb07463 --- /dev/null +++ b/common/in-progress/agent-handoff/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Agent Handoff" + short_description: "Handoff the agent to a human operator" +policy: + allow_implicit_invocation: false diff --git a/common/in-progress/knowledge-gardener/agents/openai.yaml b/common/in-progress/knowledge-gardener/agents/openai.yaml new file mode 100644 index 0000000..78c123b --- /dev/null +++ b/common/in-progress/knowledge-gardener/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Knowledge Gardener" + short_description: "Manage and curate knowledge for the agent" +policy: + allow_implicit_invocation: false diff --git a/common/misc/tmux-launch-agent/agents/openai.yaml b/common/misc/tmux-launch-agent/agents/openai.yaml new file mode 100644 index 0000000..749e61d --- /dev/null +++ b/common/misc/tmux-launch-agent/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Tmux Launch Agent" + short_description: "Launch an agent in a new tmux session" +policy: + allow_implicit_invocation: false diff --git a/common/pkm/conversation-summary/agents/openai.yaml b/common/pkm/conversation-summary/agents/openai.yaml new file mode 100644 index 0000000..9584df8 --- /dev/null +++ b/common/pkm/conversation-summary/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Conversation Summary" + short_description: "Summarize the conversation" +policy: + allow_implicit_invocation: false diff --git a/common/pkm/crit/agents/openai.yaml b/common/pkm/crit/agents/openai.yaml new file mode 100644 index 0000000..a148c0f --- /dev/null +++ b/common/pkm/crit/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Context Role Interview Task" + short_description: "CRIT framework is a structured prompting and interaction methodology" +policy: + allow_implicit_invocation: false diff --git a/common/pkm/pkm-curation/agents/openai.yaml b/common/pkm/pkm-curation/agents/openai.yaml new file mode 100644 index 0000000..9a32a16 --- /dev/null +++ b/common/pkm/pkm-curation/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Personal Knowledge Management Curation" + short_description: "Curate and manage personal knowledge for the agent" +policy: + allow_implicit_invocation: false diff --git a/common/pkm/research-vault/agents/openai.yaml b/common/pkm/research-vault/agents/openai.yaml new file mode 100644 index 0000000..a0b3d56 --- /dev/null +++ b/common/pkm/research-vault/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Research Vault" + short_description: "Store and retrieve research notes and documents" +policy: + allow_implicit_invocation: false diff --git a/common/pkm/youtube-video-capture/agents/openai.yaml b/common/pkm/youtube-video-capture/agents/openai.yaml new file mode 100644 index 0000000..0328d2e --- /dev/null +++ b/common/pkm/youtube-video-capture/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Youtube Video Capture" + short_description: "Capture a youtube video" +policy: + allow_implicit_invocation: false