diff --git a/ARCHITECTURE_NOTES.md b/ARCHITECTURE_NOTES.md
new file mode 100644
index 0000000000..efa3a85258
--- /dev/null
+++ b/ARCHITECTURE_NOTES.md
@@ -0,0 +1,393 @@
+# Architecture Notes - Roo Code Extension
+
+**Date:** 2026-02-16  
+**Phase:** 0 - Archaeological Dig  
+**Goal:** Map the codebase structure for hook system injection
+
+---
+
+## Executive Summary
+
+This document maps the Roo Code extension architecture to identify injection points for the Intent-Code Traceability hook system. The hook system will enforce a two-stage state machine (Reasoning Loop) and maintain `.orchestration/` directory for intent tracking.
+
+---
+
+## 1. Tool Execution Flow
+
+### 1.1 Entry Point: `presentAssistantMessage()`
+
+**File:** `src/core/assistant-message/presentAssistantMessage.ts`
+
+**Function:** `presentAssistantMessage(cline: Task)` (line 61)
+
+**Flow:**
+
+1. LLM generates assistant message with tool calls
+2. Function processes content blocks sequentially
+3. For each `ToolUse` block, routes to specific tool handler via `switch (block.name)` (line 678)
+4. Tools are executed with callbacks: `askApproval`, `handleError`, `pushToolResult`
+
+**Key Tool Handlers:**
+
+- `write_to_file` → `WriteToFileTool.handle()` (line 681)
+- `execute_command` → `ExecuteCommandTool.handle()` (line 750)
+- `edit_file` → `EditFileTool.handle()` (line 721)
+- Custom tools → `customToolRegistry.get(block.name)` (line 419)
+
+**Hook Injection Point:**
+
+- **Pre-Hook:** Before `tool.handle()` call (line 681, 721, etc.)
+- **Post-Hook:** After `tool.execute()` completes, before `pushToolResult()`
+
+---
+
+### 1.2 Tool Base Architecture
+
+**File:** `src/core/tools/BaseTool.ts`
+
+**Class:** `BaseTool<TName extends ToolName>` (line 29)
+
+**Key Methods:**
+
+- `abstract execute(params, task, callbacks): Promise<void>` - Main execution logic
+- `async handlePartial(task, block): Promise<void>` - Streaming support
+- `resetPartialState(): void` - Cleanup
+
+**Tool Instances:**
+All tools are singleton instances imported at module level:
+
+- `writeToFileTool` from `WriteToFileTool.ts`
+- `executeCommandTool` from `ExecuteCommandTool.ts`
+- `editFileTool` from `EditFileTool.ts`
+- etc.
+
+**Hook Injection Strategy:**
+
+- Wrap `execute()` method calls
+- Intercept in `presentAssistantMessage()` before tool.handle()
+- Store active intent context in `Task` instance
+
+---
+
+### 1.3 Tool Registration
+
+**File:** `src/core/task/build-tools.ts`
+
+**Function:** `buildNativeToolsArrayWithRestrictions()` (line 82)
+
+**Process:**
+
+1. Filters native tools based on mode
+2. Loads MCP tools from `mcpHub`
+3. Loads custom tools from `.roo/tools/` directories via `customToolRegistry`
+4. Returns combined tool array for LLM
+
+**Custom Tool Registry:**
+
+- **File:** `packages/core/src/custom-tools/custom-tool-registry.ts`
+- **Class:** `CustomToolRegistry` (line 31)
+- **Methods:** `register()`, `get()`, `has()`, `getAllSerialized()`
+
+**Hook Injection Point:**
+
+- Add `select_active_intent` to native tools array
+- Register via custom tool registry OR add to native tools list
+
+---
+
+## 2. System Prompt Construction
+
+### 2.1 Prompt Builder
+
+**File:** `src/core/prompts/system.ts`
+
+**Main Function:** `SYSTEM_PROMPT()` (line 112)
+
+**Called From:** `Task.getSystemPrompt()` (line 3745 in `Task.ts`)
+
+**Construction Flow:**
+
+1. Gets mode configuration and role definition
+2. Builds sections: formatting, tool use, capabilities, modes, rules, system info
+3. Adds custom instructions and rooignore rules
+4. Returns complete prompt string
+
+**Key Sections:**
+
+- `roleDefinition` - Mode-specific role (line 65)
+- `getSharedToolUseSection()` - Tool catalog
+- `getToolUseGuidelinesSection()` - Tool usage rules
+- `getRulesSection()` - Workspace rules
+- `getObjectiveSection()` - Task objectives
+
+**Hook Injection Point:**
+
+- Modify `getToolUseGuidelinesSection()` or add new section
+- Add Reasoning Loop instructions before tool guidelines
+- Enforce: "You MUST call select_active_intent before writing code"
+
+---
+
+### 2.2 Prompt Usage
+
+**File:** `src/core/task/Task.ts`
+
+**Method:** `getSystemPrompt()` (line 3745)
+
+**Called During:**
+
+- Initial task creation
+- Each LLM request (via `recursivelyMakeClineRequests()`)
+
+**Hook Injection Point:**
+
+- Intercept prompt before sending to LLM
+- Inject active intent context if `select_active_intent` was called
+- Add `<intent_context>` XML block to prompt
+
+---
+
+## 3. Task Lifecycle
+
+### 3.1 Task Class
+
+**File:** `src/core/task/Task.ts`
+
+**Class:** `Task` (line 163)
+
+**Key Properties:**
+
+- `taskId: string` - Unique task identifier
+- `cwd: string` - Working directory
+- `providerRef: WeakRef<ClineProvider>` - Extension provider reference
+- `api: ApiHandler` - LLM API handler
+- `clineMessages: Anthropic.Message[]` - Conversation history
+
+**Key Methods:**
+
+- `startTask(text, images)` - Initialize task
+- `recursivelyMakeClineRequests()` - Main LLM request loop
+- `getSystemPrompt()` - Get system prompt
+- `say()`, `ask()` - User interaction methods
+
+**Hook Storage Point:**
+
+- Add `activeIntentId?: string` property to Task
+- Store intent context loaded from `.orchestration/active_intents.yaml`
+
+---
+
+## 4. Extension Architecture
+
+### 4.1 Extension Host
+
+**File:** `src/extension.ts`
+
+**Function:** `activate(context: vscode.ExtensionContext)` (line 120)
+
+**Initialization:**
+
+1. Creates `ClineProvider` instance
+2. Registers commands and webview
+3. Sets up MCP hub if enabled
+4. Initializes code index manager
+
+**Provider:**
+
+- **File:** `src/core/webview/ClineProvider.ts`
+- **Class:** `ClineProvider`
+- Manages tasks, state, and webview communication
+
+---
+
+### 4.2 Webview Communication
+
+**Flow:**
+
+1. Webview (UI) sends messages via `postMessage`
+2. `webviewMessageHandler.ts` routes messages
+3. Provider creates/updates tasks
+4. Tasks execute tools and send results back
+
+**Hook Injection Point:**
+
+- Intercept webview messages before task creation
+- Validate intent selection before allowing tool execution
+
+---
+
+## 5. File System Operations
+
+### 5.1 Write Operations
+
+**Tools:**
+
+- `WriteToFileTool` - Full file write
+- `EditFileTool` - Partial file edits
+- `ApplyDiffTool` - Diff-based edits
+- `SearchReplaceTool` - Search/replace operations
+
+**Common Pattern:**
+
+1. Validate parameters
+2. Check `rooIgnoreController` for access
+3. Show diff view (if enabled)
+4. Request approval via `askApproval()`
+5. Save changes via `diffViewProvider.saveChanges()`
+6. Track file context
+7. Push tool result
+
+**Hook Injection Points:**
+
+- **Pre-Hook:** Before `askApproval()` - Check intent scope
+- **Post-Hook:** After `saveChanges()` - Log to `agent_trace.jsonl`
+
+---
+
+## 6. Hook System Architecture (Planned)
+
+### 6.1 Hook Engine Location
+
+**Proposed File:** `src/core/hooks/HookEngine.ts`
+
+**Responsibilities:**
+
+- Intercept tool execution requests
+- Enforce Pre-Hook and Post-Hook logic
+- Manage intent context injection
+- Validate scope and constraints
+
+**Integration Points:**
+
+1. Wrap tool execution in `presentAssistantMessage()`
+2. Inject into `BaseTool.execute()` wrapper
+3. Store hook state in `Task` instance
+
+---
+
+### 6.2 Orchestration Directory
+
+**Location:** `.orchestration/` in workspace root
+
+**Files:**
+
+- `active_intents.yaml` - Intent specifications
+- `agent_trace.jsonl` - Append-only trace ledger
+- `intent_map.md` - Spatial mapping
+- `AGENT.md` - Shared knowledge base
+
+**Access:**
+
+- Read/write via Node.js `fs` APIs
+- Initialize on first task creation
+- Validate on extension activation
+
+---
+
+## 7. Implementation Strategy
+
+### 7.1 Phase 1: The Handshake
+
+**Steps:**
+
+1. Create `SelectActiveIntentTool` extending `BaseTool`
+2. Add tool to native tools array in `build-tools.ts`
+3. Create `HookEngine` class with Pre-Hook/Post-Hook methods
+4. Modify `presentAssistantMessage()` to call hooks
+5. Create `.orchestration/` directory structure
+6. Implement `OrchestrationDataModel` for YAML/JSONL access
+7. Modify system prompt to enforce Reasoning Loop
+8. Implement context injection for `select_active_intent`
+
+---
+
+### 7.2 File Structure (Planned)
+
+```
+src/
+  core/
+    hooks/
+      HookEngine.ts          # Main hook middleware
+      PreHook.ts             # Pre-execution hooks
+      PostHook.ts            # Post-execution hooks
+      OrchestrationDataModel.ts  # Data model access
+    tools/
+      SelectActiveIntentTool.ts  # New intent selection tool
+    orchestration/
+      ActiveIntentsManager.ts    # YAML management
+      AgentTraceLogger.ts        # JSONL logging
+      IntentMapManager.ts         # Markdown mapping
+```
+
+---
+
+## 8. Key Dependencies
+
+### 8.1 External Libraries
+
+- `@anthropic-ai/sdk` - LLM API
+- `yaml` - YAML parsing (need to add)
+- `crypto` - SHA-256 hashing (built-in)
+- `fs/promises` - File system operations
+
+### 8.2 Internal Dependencies
+
+- `@roo-code/types` - Type definitions
+- `@roo-code/core` - Core utilities
+- `Task` class - Task lifecycle
+- `BaseTool` - Tool base class
+
+---
+
+## 9. Testing Strategy
+
+### 9.1 Unit Tests
+
+- Hook engine interception logic
+- Orchestration data model read/write
+- Intent context injection
+- Scope validation
+
+### 9.2 Integration Tests
+
+- End-to-end tool execution with hooks
+- Intent selection → context injection → code write
+- Trace logging verification
+- Parallel agent collision detection
+
+---
+
+## 10. Open Questions
+
+1. **Tool Registration:** Should `select_active_intent` be a native tool or custom tool?
+
+    - **Decision:** Native tool (simpler, always available)
+
+2. **Hook Timing:** Should hooks be synchronous or async?
+
+    - **Decision:** Async (allows for file I/O and user prompts)
+
+3. **Error Handling:** How to handle hook failures?
+
+    - **Decision:** Fail-safe - log error, allow execution to continue with warning
+
+4. **State Persistence:** Where to store active intent ID?
+    - **Decision:** Task instance property + `.orchestration/active_intents.yaml`
+
+---
+
+## 11. Next Steps
+
+1. ✅ Complete Phase 0 (this document)
+2. ⏳ Implement Phase 1: The Handshake
+    - Create `SelectActiveIntentTool`
+    - Build `HookEngine` infrastructure
+    - Implement `.orchestration/` data models
+    - Modify system prompt
+3. ⏳ Implement Phase 2: Hook Middleware & Security
+4. ⏳ Implement Phase 3: AI-Native Git Layer
+5. ⏳ Implement Phase 4: Parallel Orchestration
+
+---
+
+**End of Architecture Notes**