Cline rules

1# SoC AI Debugger - Deep Project Memory & Architecture Guide
2 
3This document is the **Ultimate Reference Guide** for any AI Coding Agent working on the SoC AI Debugger (formerly Cline/nRF AI Debugger). It is designed to prevent you from needing to grep or re-analyze the entire codebase to understand the command execution pipeline, UI data flow, or Nordic SDK integration logic.
4 
5---
6 
7## 1. Core Architecture & Component Map
8 
9The extension is split into three main areas: Core Extension (Backend), Webview UI (Frontend React), and Hosts (VS Code specific implementations).
10 
11### 1.1 Backend Core (`src/core/`)
12- `src/core/task/Task.ts`: The absolute brain of the execution loop. It handles the `while (!this.abort)` loop, parses API chunks, and manages tool execution.
13- `src/core/prompts/system-prompt/`: Contains all system prompts and tool schemas.
14  - `tools/nrf_device_tool.ts`: The strictly enforced schema for Zephyr/Nordic SDK operations. (Renamed from `trigger_nordic_action.ts`).
15  - `tools/execute_command.ts`: The generic bash tool. **CRITICAL:** The prompt here explicitly forbids its use for Nordic SDK tasks.
16- `src/core/controller/index.ts`: The `Controller` class manages state persistence (GlobalState, SecretStorage), the `McpHub`, and communication with the Webview.
17 
18### 1.2 Terminal Integration & Routing (The Most Complex Subsystem)
19The extension executes commands in different types of terminals based on the user's settings and the task at hand. This is handled in `src/integrations/terminal/`.
20 
21- **`CommandExecutor.ts`**: The routing hub for all `execute_command` and `nrf_device_tool` calls.
22  - **Execution Modes:** `terminalExecutionMode` can be `integrated` (visible to user) or `backgroundExec` (hidden standalone).
23  - **The "Named Terminal" Override:** In `backgroundExec` mode, standard commands run in hidden shells via `StandaloneTerminalManager`. However, if a tool specifically requests a *named* terminal (e.g., "nRF Connect"), `CommandExecutor` lazily instantiates a `VscodeTerminalManager` to force the command into the visible VS Code environment where the Zephyr SDK variables are injected.
24- **`src/hosts/vscode/terminal/VscodeTerminalManager.ts`**: Implements `ITerminalManager` for VS Code. It interacts with the VS Code API to find or create visible terminals.
25- **`src/hosts/vscode/terminal/VscodeTerminalRegistry.ts`**: Manages the lifecycle of terminals created by the extension.
26  - *Quirk:* The `createTerminal` method currently hardcodes the terminal name `name: "Cline"` or `"IoT AI Debugger"` internally. Do not refactor internal legacy names aggressively as it breaks tracking.
27- **`TriggerNordicActionHandler.ts`** (`src/core/task/tools/handlers/`): The handler that parses `nrf_device_tool` parameters. It specifically asks `CommandExecutor` to run commands in the "nRF Connect" terminal to guarantee SDK paths (`ZEPHYR_BASE`, `PATH`) are available.
28 
29### 1.3 Webview UI (`webview-ui/`)
30- Built with React and Vite.
31- **State Management:** `webview-ui/src/context/ExtensionStateContext.tsx` handles real-time synchronization with the backend `Controller` via VS Code message passing.
32- **Key Components:**
33  - `ChatView.tsx` / `ChatRow.tsx`: Render the conversational UI.
34  - `CommandOutputRow.tsx`: Renders real-time terminal streaming output.
35- **Branding:** Recently overhauled to "IoT AI Debugger". Logos (`NrfLogo.tsx`, `icon.png`) and UI text reflect this new branding.
36 
37---
38 
39## 2. The Data Flow: How a Nordic Command is Executed
40 
41To understand how to fix bugs in the execution pipeline, you must understand this flow:
42 
431. **Agent Output:** The AI generates a `tool_use` block for `nrf_device_tool` with `action="execute"` and `command="west build"`.
442. **Task Processing:** `Task.ts` intercepts this and routes it to `TriggerNordicActionHandler.executeInNrfTerminal()`.
453. **Execution Request:** The handler calls `commandExecutor.execute("west build", timeout, "nRF Connect")`. Note the specific passing of the terminal name `"nRF Connect"`.
464. **Routing (`CommandExecutor.ts`):** 
47   - `CommandExecutor` checks the requested terminal name.
48   - Even if the user is in `backgroundExec` mode, because `"nRF Connect"` is explicitly requested, it bypasses the `StandaloneTerminalManager` and uses `VscodeTerminalManager`.
495. **Terminal Acquisition (`VscodeTerminalManager.ts`):**
50   - It iterates over `vscode.window.terminals` looking for one whose name includes "nRF Connect".
51   - If found, it uses it (this terminal has `ZEPHYR_BASE` injected by the official Nordic extension).
52   - If NOT found, it asks `TerminalRegistry` to create one, which may unfortunately default to the internal branding name, leading to execution in a generic environment (this is a known edge case).
536. **Streaming:** Output is streamed back via VS Code event listeners and piped into `Task.ts` to be read by the AI.
54 
55---
56 
57## 3. Persistent Agent Knowledge Base (`iot-knowledge/`)
58 
59**Do not confuse this directory with agent development memory.**
60- `iot-knowledge/` contains the strict markdown rules that the *active AI agent inside the VS Code extension* uses to learn how to debug nRF devices.
61- It contains `rules/nrf-terminal.md`, `platforms/`, etc.
62- In v0.0.6, we stripped hardcoded prompt strings out of the UI TypeScript files and moved them into this directory so the AI can dynamically load them based on the active workspace.
63 
64---
65 
66## 4. Known Quirks, Traps, and Limitations
67 
681. **Model Compliance Failures (The "Free Model" Bug):**
69   - Smaller models (like GLM 4.5 Air) have weak attention spans. They frequently ignore the negative constraints in `execute_command.ts` ("DO NOT use execute_command for SDK tasks") and fail to route Zephyr commands to `nrf_device_tool`. 
70   - When modifying prompts to fix this, do not write long explanatory paragraphs. Use short, aggressive negative constraints at the very top of the tool schema.
712. **The "Shell Integration Unavailable" Warning:**
72   - NCS Terminals natively lack VS Code shell integration. `CommandExecutor.ts` handles this by suppressing the shell integration warning flag when a Nordic command is run. If you modify `CommandExecutor`, do not accidentally re-enable this warning for named terminals.
733. **Legacy Branding Variables:**
74   - You will see variables like `ClineDefaultTool`, `ClineIgnoreController`, and `clineMessages`. **Do not rename these.** The branding transition to "SoC AI Debugger" / "IoT AI Debugger" applies strictly to user-facing strings (UI text, Output Channel, `package.json` displayName). Refactoring internal variable names breaks backward compatibility with saved user states.
75 
76---
77 
78## 5. Development Workflow
79 
801. **Testing UI:** `cd webview-ui && npm run dev`
812. **Testing Extension:** Run the "Run Extension" launch configuration in VS Code (F5).
823. **Nordic Specific Tests:** We have isolated tests for the Nordic handlers. Run `npm run test:nordic`.
834. **Building VSIX:** `npm install` followed by `npx vsce package`. (Note: `*.vsix` is strictly ignored in `.gitignore`).
84 
85---
86*End of Project Memory. You are now fully contextualized.*
87