lsp-architecture

Files (1)

• SKILL.md

SKILL.md (first lines)

> Requires the agent-lsp MCP server.

# lsp-architecture

Generate a structural architecture overview of any codebase: language
distribution, package hierarchy, entry points, dependency flow, and hotspot
files. One invocation for the big picture.

Read-only; does not modify any files.

**Invocation:** User provides the workspace root path (e.g.
`"/home/user/myproject"`). If omitted, use the current working directory.

---

## Depth Controls (hard limits)

These limits are strict constraints. Never exceed them:

- Package enumeration: **cap at 30 packages**
- Hotspot analysis: **cap at 10 files**
- Workspace symbol queries: **cap at 5 queries**
- Do NOT recurse into `vendor/`, `node_modules/`, `.git/`, or other dependency directories

---

## Step 0 — Initialize

If LSP is not yet running, start it with the workspace root:

```
mcp__lsp__start_lsp({
  "workspace_root": "<workspace-root>"
})
```

Then detect which language servers are available:

```
mcp__lsp__detect_lsp_servers({
  "workspace_root": "<workspace-root>"
})
→ returns: list of detected servers with language names and file patterns
```

Record the available languages and their file globs. This determines which
queries to run in later steps.

---

## Step 1 — Language Detection

Scan the workspace to determine language distribution. Use file extension
counts from the detected servers and supplement with a filesystem scan
(via Glob tool) to count files per language.

For each detected language, report:
- Language name
- File count
- Estimated lines of code (sample 3-5 representative files and extrapolate)

Skip files in `vendor/`, `node_modules/`, `.git/`, `dist/`, `build/`, and
other common dependency or output directories.

---

## Step 2 — Package Structure

Use `find_symbol` with broad queries to discover the package and
module hierarchy. Tailor queries by language:

**Go:**
```
mcp__lsp__find_symbol({
  "query": "",
  "symbol_kind_filter": "Package"
})
```

Also query for top-level types and functions to fill in package-level detail:

```
mcp__lsp__find_symbol({
  "query": "",
  "symbol_kind_filter": "Function"
})
```

**Python:**
```
mcp__lsp__find_symbol({
  "query": "",
  "symbol_kind_filter": "Class"
})
```

**TypeScript/JavaScript:**
```
mcp__lsp__find_symbol({
  "query": "",
  "symbol_kind_filter": "Function"
})
```

From the returned symbols, extract the directory paths and build a tree of
the package hierarchy. Group symbols by their containing directory. For each
package/directory, note:
- Path relative to workspace root
- Brief description (inferred from symbol names and directory name)
- Approximate symbol count

**Cap at 30 packages.** If more than 30 directories contain symbols, keep only
the top 30 by symbol count and note that others were omitted.

**Cap workspace symbol queries at 5 total** across all of Step 2.

---

## Step 3 — Entry Points

From blackwell-systems/agent-lsp, MIT.

More from blackwell-systems/agent-lsp