---
base_agent: codebase-architect
base_agent_version: 3.10.0
mode: extend
---

> **How to use this example**
>
> Copy this file to `.baldart/overlays/agents/codebase-architect.md` (drop the
> `.lsp-example`) when you want to add project-specific LSP guidance on top of
> the shipped `agents/code-search-protocol.md`. The framework regenerates
> `.claude/agents/codebase-architect.md` from base + overlay on every
> `npx baldart update`.
>
> Section markers (see `framework/templates/overlays/README.md`):
> - `## [OVERRIDE] <heading>` — replace the entire matching H2 from the base.
> - `## [APPEND] <heading>`  — add content after the base section.
> - `## [PREPEND] <heading>` — add content before the base section.
> - `## <heading>` with no marker — appended at the end as a new custom section.
>
> Skip this overlay entirely if the shipped protocol is enough — the base
> agent already wires LSP correctly when `features.has_lsp_layer: true`.

## [APPEND] LSP Symbol Search

Project-specific tuning on top of `framework/agents/code-search-protocol.md`:

- **Preferred entry points.** For identifier-shaped lookups in this repo,
  start with `find-references` on the symbol exported from
  `src/<your-canonical-module>/index.ts` (or your equivalent). The export
  surface is small enough that the references list converges in 1–2 calls.
- **Per-language quirks.**
  - TypeScript: monorepo packages under `packages/<name>` need
    `tsserver` workspaces enabled. If LSP returns zero references for a
    symbol you know is used cross-package, fall back to Grep scoped to
    `packages/*/src/`.
  - Python: pyright honors `extraPaths` from `pyrightconfig.json` — if
    you re-rooted sources, double-check the config before reporting "no
    references found".
- **Don't chase generated code.** Skip LSP results pointing into `dist/`,
  `.next/`, `coverage/`, or any path matching the project's `.gitignore` —
  treat them as noise.

## Project-only conventions

Custom rules with no equivalent in the base — appended as a new H2:

- All `find-references` outputs over 50 callsites trigger a refactor
  conversation with the maintainer before any rename / signature change
  proceeds.
- When LSP is unavailable, write the reason (binary missing / plugin not
  loaded / language not yet adopted) into the analysis output so reviewers
  understand why Grep was used instead.
