Copilot instructions

1# Copilot Instructions for Cline
2 
3This is a VS Code extension. Read `.clinerules/general.md` for tribal knowledge and nuanced patterns.
4 
5## Architecture
6- **Core** (`src/`): `extension.ts` → `WebviewProvider` → `Controller` (single source of truth) → `Task` (agent loop).
7- **Webview** (`webview-ui/`): React/Vite app. State via `ExtensionStateContext.tsx`, synced through message passing.
8- **Communication**: Protobuf-defined gRPC-like protocol over VS Code message passing. Schemas in `proto/`.
9- **MCP**: `src/services/mcp/McpHub.ts`.
10 
11## Build & Test (Critical — non-obvious commands)
12- **Build**: `bun run compile` — NOT `bun run build`.
13- **Watch**: `bun run watch` (extension + webview).
14- **Protos**: `bun run protos` — run **immediately** after any `.proto` change. Generates into `src/shared/proto/`, `src/generated/`.
15- **Tests**: `bun run test:unit`. After prompt/tool changes: `UPDATE_SNAPSHOTS=true bun run test:unit`.
16 
17## Protobuf RPC Workflow (4 steps)
181. **Define** in `proto/cline/*.proto`. Naming: `PascalCaseService`, `camelCase` RPCs, `PascalCase` Messages. Use `common.proto` shared types for simple data.
192. **Generate**: `bun run protos`.
203. **Backend handler**: `src/core/controller/<domain>/`. 
214. **Frontend call**: `UiServiceClient.myMethod(Request.create({...}))`.
22- Adding enums (e.g. `ClineSay`) → also update `src/shared/proto-conversions/cline-message.ts`.
23 
24## Adding API Providers (silent failure risk)
25Three proto conversion updates are **required** or the provider silently resets to Anthropic:
261. `proto/cline/models.proto` — add to `ApiProvider` enum.
272. `convertApiProviderToProto()` in `src/shared/proto-conversions/models/api-configuration-conversion.ts`.
283. `convertProtoToApiProvider()` in the same file.
29 
30Also update: `src/shared/api.ts`, `src/shared/providers/providers.json`, `src/core/api/index.ts`, `webview-ui/.../providerUtils.ts`, `webview-ui/.../validate.ts`, `webview-ui/.../ApiOptions.tsx`.
31 
32For Responses API providers: add to `isNextGenModelProvider()` in `src/utils/model-utils.ts` and set `apiFormat: ApiFormat.OPENAI_RESPONSES` on models.
33 
34## Adding Tools to System Prompt (5+ file chain)
351. Add enum to `ClineDefaultTool` in `src/shared/tools.ts`.
362. Create definition in `src/core/prompts/system-prompt/tools/` (export `[GENERIC]` minimum).
373. Register in `src/core/prompts/system-prompt/tools/init.ts`.
384. Whitelist in `src/core/prompts/system-prompt/variants/*/config.ts` for each model family.
395. Handler in `src/core/task/tools/handlers/`, wire in `ToolExecutor.ts`.
406. If tool has UI: add `ClineSay` enum in proto → `ExtensionMessage.ts` → `cline-message.ts` → `ChatRow.tsx`.
417. Regenerate snapshots: `UPDATE_SNAPSHOTS=true bun run test:unit`.
42 
43## Modifying System Prompt
44Modular: `components/` (shared) + `variants/` (model-specific) + `templates/` (`{{PLACEHOLDER}}`). Variants override components via `componentOverrides` in `config.ts` or custom `template.ts`. XS variant is heavily condensed inline. Always regenerate snapshots after changes.
45 
46## Global State Keys (silent failure risk)
47Adding a key requires updating the typed storage definitions in `src/shared/storage/state-keys.ts`; runtime reads and writes should go through `StateManager`, not VS Code `ExtensionContext` storage. Persistent state is file-backed so it works across VS Code, CLI, and JetBrains hosts.
48 
49## Slash Commands (3 places)
50- `src/core/slash-commands/index.ts` — definitions.
51- `src/core/prompts/commands.ts` — system prompt integration.
52- `webview-ui/src/utils/slash-commands.ts` — webview autocomplete.
53 
54## Conventions
55- **Paths**: Always use `src/utils/path` helpers (`toPosixString`) for cross-platform compatibility.
56- **Logging**: `src/shared/services/Logger.ts`.
57- **Feature flags**: See PR #7566 as reference pattern.
58