First attempt

2026-05-30 05:35:24 +08:00 · 2026-01-11 09:30:06 -07:00 · 2026-01-11 09:30:06 -07:00 · ee0649bccd
commit ee0649bccd
parent 0410732c78
6 changed files with 779 additions and 0 deletions
--- a/architecture/1-high-level-system-architecture.md
+++ b/architecture/1-high-level-system-architecture.md
@ -0,0 +1,77 @@
+# High-Level System Architecture
+
+This diagram shows the overall structure of Claude Code's prompt system.
+
+```mermaid
+flowchart TB
+    subgraph Core["Core System"]
+        Main["<b>Main System Prompt</b><br/>Behavior, tone, policies,<br/>task handling"]
+        click Main href "../system-prompts/system-prompt-main-system-prompt.md" "Main System Prompt"
+    end
+
+    subgraph Conditional["Conditional Additions"]
+        Security["Security Policy"]
+        Learning["Learning Mode"]
+        Git["Git Status"]
+        Scratchpad["Scratchpad Directory"]
+        MCP["MCP CLI"]
+        Chrome["Chrome Browser"]
+        click Learning href "../system-prompts/system-prompt-learning-mode.md" "Learning Mode"
+        click Git href "../system-prompts/system-prompt-git-status.md" "Git Status"
+        click Scratchpad href "../system-prompts/system-prompt-scratchpad-directory.md" "Scratchpad Directory"
+        click MCP href "../system-prompts/system-prompt-mcp-cli.md" "MCP CLI"
+        click Chrome href "../system-prompts/system-prompt-claude-in-chrome-browser-automation.md" "Chrome Browser Automation"
+    end
+
+    subgraph Tools["Built-in Tools"]
+        direction LR
+        FileTools["File Operations<br/>Read, Write, Edit,<br/>Glob, Grep"]
+        ExecTools["Execution<br/>Bash"]
+        WebTools["Web<br/>Search, Fetch"]
+        PlanTools["Planning<br/>TodoWrite,<br/>Enter/Exit PlanMode"]
+        InteractTools["Interaction<br/>Task, Skill,<br/>AskUserQuestion"]
+    end
+
+    subgraph Agents["Sub-agents"]
+        direction LR
+        Explore["Explore<br/><i>Read-only search</i>"]
+        Plan["Plan<br/><i>Read-only design</i>"]
+        TaskAgent["Task Agent<br/><i>Autonomous work</i>"]
+        click Explore href "../system-prompts/agent-prompt-explore.md" "Explore Agent"
+        click Plan href "../system-prompts/agent-prompt-plan-mode-enhanced.md" "Plan Mode Agent"
+        click TaskAgent href "../system-prompts/agent-prompt-task-tool.md" "Task Tool Agent"
+    end
+
+    subgraph Utilities["Utility Agents"]
+        direction LR
+        Summary["Conversation<br/>Summarization"]
+        Session["Session Title<br/>& Branch Gen"]
+        Hooks["Hooks"]
+        Sentiment["User Sentiment<br/>Analysis"]
+        click Summary href "../system-prompts/agent-prompt-conversation-summarization.md" "Conversation Summarization"
+        click Session href "../system-prompts/agent-prompt-session-title-and-branch-generation.md" "Session Title Generation"
+        click Hooks href "../system-prompts/agent-prompt-agent-hook.md" "Agent Hook"
+        click Sentiment href "../system-prompts/agent-prompt-user-sentiment-analysis.md" "User Sentiment Analysis"
+    end
+
+    Main --> Conditional
+    Main --> Tools
+    Main --> Agents
+    Main --> Utilities
+
+    style Core fill:#e1f5fe
+    style Tools fill:#f3e5f5
+    style Agents fill:#e8f5e9
+    style Utilities fill:#fff3e0
+    style Conditional fill:#fce4ec
+```
+
+## Components
+
+| Component | Description | Key Prompts |
+|-----------|-------------|-------------|
+| **Core System** | The main system prompt that defines Claude Code's behavior, tone, and policies | [Main System Prompt](../system-prompts/system-prompt-main-system-prompt.md) |
+| **Conditional Additions** | Context-dependent prompt sections added based on environment and configuration | [Learning Mode](../system-prompts/system-prompt-learning-mode.md), [Git Status](../system-prompts/system-prompt-git-status.md), [MCP CLI](../system-prompts/system-prompt-mcp-cli.md) |
+| **Built-in Tools** | Tool descriptions injected when tools are available | See [Tool Ecosystem](./3-tool-ecosystem.md) |
+| **Sub-agents** | Specialized agents spawned for complex tasks | [Explore](../system-prompts/agent-prompt-explore.md), [Plan](../system-prompts/agent-prompt-plan-mode-enhanced.md), [Task](../system-prompts/agent-prompt-task-tool.md) |
+| **Utility Agents** | Background agents for session management and analysis | [Summarization](../system-prompts/agent-prompt-conversation-summarization.md), [Session Title](../system-prompts/agent-prompt-session-title-and-branch-generation.md) |
--- a/architecture/2-agent-delegation-flow.md
+++ b/architecture/2-agent-delegation-flow.md
@ -0,0 +1,101 @@
+# Agent Delegation Flow
+
+This diagram shows how the main Claude Code agent decides when to handle tasks directly versus delegating to specialized sub-agents.
+
+```mermaid
+flowchart TB
+    User["👤 User Request"]
+    Main["Main Agent<br/><i>Main System Prompt</i>"]
+    click Main href "../system-prompts/system-prompt-main-system-prompt.md" "Main System Prompt"
+
+    Decision{{"Task Complexity?"}}
+
+    subgraph Direct["Direct Tool Use"]
+        direction TB
+        Read["ReadFile"]
+        Write["Write"]
+        Edit["Edit"]
+        Bash["Bash"]
+        Glob["Glob"]
+        Grep["Grep"]
+        Web["WebSearch /<br/>WebFetch"]
+        click Read href "../system-prompts/tool-description-readfile.md" "ReadFile Tool"
+        click Write href "../system-prompts/tool-description-write.md" "Write Tool"
+        click Edit href "../system-prompts/tool-description-edit.md" "Edit Tool"
+        click Bash href "../system-prompts/tool-description-bash.md" "Bash Tool"
+        click Glob href "../system-prompts/tool-description-glob.md" "Glob Tool"
+        click Grep href "../system-prompts/tool-description-grep.md" "Grep Tool"
+        click Web href "../system-prompts/tool-description-websearch.md" "WebSearch Tool"
+    end
+
+    subgraph TaskTool["Task Tool Delegation"]
+        Task["Task Tool"]
+        click Task href "../system-prompts/tool-description-task.md" "Task Tool"
+        
+        subgraph SubAgents["Sub-agent Types"]
+            Explore["<b>Explore Agent</b><br/><i>Read-only codebase search</i><br/>Tools: Glob, Grep, Read, Bash"]
+            Plan["<b>Plan Agent</b><br/><i>Read-only architecture design</i><br/>Tools: Glob, Grep, Read, Bash"]
+            Custom["<b>Custom Agents</b><br/><i>User-defined via config</i>"]
+            click Explore href "../system-prompts/agent-prompt-explore.md" "Explore Agent"
+            click Plan href "../system-prompts/agent-prompt-plan-mode-enhanced.md" "Plan Mode Agent"
+        end
+    end
+
+    TaskPrompt["Task Agent Prompt<br/><i>Given to spawned agent</i>"]
+    ExtraNotes["Extra Notes<br/><i>Absolute paths, formatting</i>"]
+    click TaskPrompt href "../system-prompts/agent-prompt-task-tool.md" "Task Agent Prompt"
+    click ExtraNotes href "../system-prompts/agent-prompt-task-tool-extra-notes.md" "Task Tool Extra Notes"
+
+    Result["📋 Result returned to Main Agent"]
+    Response["💬 Response to User"]
+
+    User --> Main
+    Main --> Decision
+    
+    Decision -->|"Simple / Specific"| Direct
+    Decision -->|"Complex / Multi-step"| TaskTool
+    
+    Task --> SubAgents
+    SubAgents --> TaskPrompt
+    TaskPrompt --> ExtraNotes
+    
+    Direct --> Response
+    ExtraNotes --> Result
+    Result --> Main
+    Main --> Response
+
+    style Direct fill:#e8f5e9
+    style TaskTool fill:#e1f5fe
+    style SubAgents fill:#f3e5f5
+```
+
+## When to Use Direct Tools vs. Task Delegation
+
+| Scenario | Approach | Reason |
+|----------|----------|--------|
+| Read a specific file | **Direct** (ReadFile) | Known path, simple operation |
+| Search for "class Foo" | **Direct** (Grep) | Specific needle query |
+| Find all TypeScript files | **Direct** (Glob) | Simple pattern match |
+| "Where are errors handled?" | **Task** (Explore) | Requires codebase exploration |
+| "What's the architecture?" | **Task** (Explore) | Needs broad understanding |
+| Design a new feature | **Task** (Plan) | Requires analysis and design |
+| Run tests after code changes | **Task** (Custom) | Multi-step autonomous work |
+
+## Sub-agent Characteristics
+
+### Explore Agent
+- **Purpose**: Fast, read-only codebase search
+- **Constraints**: Cannot create, modify, or delete files
+- **Tools**: Glob, Grep, ReadFile, Bash (read-only commands only)
+- **Prompt**: [agent-prompt-explore.md](../system-prompts/agent-prompt-explore.md)
+
+### Plan Agent  
+- **Purpose**: Architecture analysis and implementation planning
+- **Constraints**: Read-only, outputs a plan with critical files
+- **Tools**: Glob, Grep, ReadFile, Bash (read-only commands only)
+- **Prompt**: [agent-prompt-plan-mode-enhanced.md](../system-prompts/agent-prompt-plan-mode-enhanced.md)
+
+### Task Agent (Generic)
+- **Purpose**: Autonomous execution of delegated tasks
+- **Prompt**: [agent-prompt-task-tool.md](../system-prompts/agent-prompt-task-tool.md)
+- **Extra Notes**: [agent-prompt-task-tool-extra-notes.md](../system-prompts/agent-prompt-task-tool-extra-notes.md)
--- a/architecture/3-tool-ecosystem.md
+++ b/architecture/3-tool-ecosystem.md
@ -0,0 +1,133 @@
+# Tool Ecosystem
+
+This diagram maps all of Claude Code's built-in tools, organized by category.
+
+```mermaid
+flowchart TB
+    subgraph FileOps["📁 File Operations"]
+        direction TB
+        Read["<b>ReadFile</b><br/>Read file contents"]
+        Write["<b>Write</b><br/>Create/overwrite files"]
+        Edit["<b>Edit</b><br/>String replacement in files"]
+        Glob["<b>Glob</b><br/>Pattern-based file search"]
+        Grep["<b>Grep</b><br/>Content search with regex"]
+        Notebook["<b>NotebookEdit</b><br/>Jupyter cell editing"]
+        click Read href "../system-prompts/tool-description-readfile.md" "ReadFile"
+        click Write href "../system-prompts/tool-description-write.md" "Write"
+        click Edit href "../system-prompts/tool-description-edit.md" "Edit"
+        click Glob href "../system-prompts/tool-description-glob.md" "Glob"
+        click Grep href "../system-prompts/tool-description-grep.md" "Grep"
+        click Notebook href "../system-prompts/tool-description-notebookedit.md" "NotebookEdit"
+    end
+
+    subgraph Execution["⚡ Execution"]
+        direction TB
+        Bash["<b>Bash</b><br/>Shell command execution"]
+        BashGit["Git & PR Instructions<br/><i>Commit and PR creation</i>"]
+        BashSandbox["Sandbox Note<br/><i>Security sandboxing</i>"]
+        click Bash href "../system-prompts/tool-description-bash.md" "Bash"
+        click BashGit href "../system-prompts/tool-description-bash-git-commit-and-pr-creation-instructions.md" "Git Instructions"
+        click BashSandbox href "../system-prompts/tool-description-bash-sandbox-note.md" "Sandbox Note"
+        
+        Bash --> BashGit
+        Bash --> BashSandbox
+    end
+
+    subgraph Web["🌐 Web"]
+        direction TB
+        WebSearch["<b>WebSearch</b><br/>Real-time web search"]
+        WebFetch["<b>WebFetch</b><br/>Fetch URL contents"]
+        click WebSearch href "../system-prompts/tool-description-websearch.md" "WebSearch"
+        click WebFetch href "../system-prompts/tool-description-webfetch.md" "WebFetch"
+    end
+
+    subgraph Planning["📋 Planning & Tasks"]
+        direction TB
+        Todo["<b>TodoWrite</b><br/>Task list management"]
+        Enter["<b>EnterPlanMode</b><br/>Start planning mode"]
+        Exit["<b>ExitPlanMode</b><br/>Present plan for approval"]
+        ExitV2["<b>ExitPlanMode v2</b><br/>Enhanced plan dialog"]
+        click Todo href "../system-prompts/tool-description-todowrite.md" "TodoWrite"
+        click Enter href "../system-prompts/tool-description-enterplanmode.md" "EnterPlanMode"
+        click Exit href "../system-prompts/tool-description-exitplanmode.md" "ExitPlanMode"
+        click ExitV2 href "../system-prompts/tool-description-exitplanmode-v2.md" "ExitPlanMode v2"
+    end
+
+    subgraph Interaction["💬 Interaction"]
+        direction TB
+        Task["<b>Task</b><br/>Launch sub-agents"]
+        Skill["<b>Skill</b><br/>Execute skills"]
+        Ask["<b>AskUserQuestion</b><br/>Clarification prompts"]
+        click Task href "../system-prompts/tool-description-task.md" "Task"
+        click Skill href "../system-prompts/tool-description-skill.md" "Skill"
+        click Ask href "../system-prompts/tool-description-askuserquestion.md" "AskUserQuestion"
+    end
+
+    subgraph Specialized["🔧 Specialized"]
+        direction TB
+        Computer["<b>Computer</b><br/>Chrome browser automation"]
+        LSP["<b>LSP</b><br/>Language Server Protocol"]
+        MCP["<b>MCPSearch</b><br/>MCP server discovery"]
+        MCPTools["MCPSearch<br/><i>with available tools</i>"]
+        click Computer href "../system-prompts/tool-description-computer.md" "Computer"
+        click LSP href "../system-prompts/tool-description-lsp.md" "LSP"
+        click MCP href "../system-prompts/tool-description-mcpsearch.md" "MCPSearch"
+        click MCPTools href "../system-prompts/tool-description-mcpsearch-with-available-tools.md" "MCPSearch with tools"
+        
+        MCP --> MCPTools
+    end
+
+    style FileOps fill:#e8f5e9
+    style Execution fill:#fff3e0
+    style Web fill:#e1f5fe
+    style Planning fill:#f3e5f5
+    style Interaction fill:#fce4ec
+    style Specialized fill:#f5f5f5
+```
+
+## Tool Quick Reference
+
+### File Operations
+| Tool | Purpose | Prompt File |
+|------|---------|-------------|
+| **ReadFile** | Read file contents with optional offset/limit | [tool-description-readfile.md](../system-prompts/tool-description-readfile.md) |
+| **Write** | Create or overwrite entire files | [tool-description-write.md](../system-prompts/tool-description-write.md) |
+| **Edit** | Exact string replacement in existing files | [tool-description-edit.md](../system-prompts/tool-description-edit.md) |
+| **Glob** | Find files by pattern (e.g., `**/*.ts`) | [tool-description-glob.md](../system-prompts/tool-description-glob.md) |
+| **Grep** | Search file contents with regex | [tool-description-grep.md](../system-prompts/tool-description-grep.md) |
+| **NotebookEdit** | Edit Jupyter notebook cells | [tool-description-notebookedit.md](../system-prompts/tool-description-notebookedit.md) |
+
+### Execution
+| Tool | Purpose | Prompt File |
+|------|---------|-------------|
+| **Bash** | Execute shell commands | [tool-description-bash.md](../system-prompts/tool-description-bash.md) |
+| ↳ Git Instructions | How to create commits and PRs | [tool-description-bash-git-commit-and-pr-creation-instructions.md](../system-prompts/tool-description-bash-git-commit-and-pr-creation-instructions.md) |
+| ↳ Sandbox Note | Security sandboxing info | [tool-description-bash-sandbox-note.md](../system-prompts/tool-description-bash-sandbox-note.md) |
+
+### Web
+| Tool | Purpose | Prompt File |
+|------|---------|-------------|
+| **WebSearch** | Search the web for real-time information | [tool-description-websearch.md](../system-prompts/tool-description-websearch.md) |
+| **WebFetch** | Fetch content from specific URLs | [tool-description-webfetch.md](../system-prompts/tool-description-webfetch.md) |
+
+### Planning & Tasks
+| Tool | Purpose | Prompt File |
+|------|---------|-------------|
+| **TodoWrite** | Create and manage task lists | [tool-description-todowrite.md](../system-prompts/tool-description-todowrite.md) |
+| **EnterPlanMode** | Enter planning mode for complex tasks | [tool-description-enterplanmode.md](../system-prompts/tool-description-enterplanmode.md) |
+| **ExitPlanMode** | Present plan for user approval | [tool-description-exitplanmode.md](../system-prompts/tool-description-exitplanmode.md) |
+| **ExitPlanMode v2** | Enhanced plan dialog | [tool-description-exitplanmode-v2.md](../system-prompts/tool-description-exitplanmode-v2.md) |
+
+### Interaction
+| Tool | Purpose | Prompt File |
+|------|---------|-------------|
+| **Task** | Launch specialized sub-agents | [tool-description-task.md](../system-prompts/tool-description-task.md) |
+| **Skill** | Execute predefined skills | [tool-description-skill.md](../system-prompts/tool-description-skill.md) |
+| **AskUserQuestion** | Ask user for clarification | [tool-description-askuserquestion.md](../system-prompts/tool-description-askuserquestion.md) |
+
+### Specialized
+| Tool | Purpose | Prompt File |
+|------|---------|-------------|
+| **Computer** | Chrome browser automation | [tool-description-computer.md](../system-prompts/tool-description-computer.md) |
+| **LSP** | Language Server Protocol operations | [tool-description-lsp.md](../system-prompts/tool-description-lsp.md) |
+| **MCPSearch** | Search for MCP servers | [tool-description-mcpsearch.md](../system-prompts/tool-description-mcpsearch.md) |
--- a/architecture/4-conversation-lifecycle.md
+++ b/architecture/4-conversation-lifecycle.md
@ -0,0 +1,137 @@
+# Conversation Lifecycle
+
+This diagram shows how different prompts are used throughout a Claude Code session, from start to finish.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant User
+    participant CC as Claude Code
+    participant Main as Main Agent
+    participant Tools as Tools
+    participant SubAgent as Sub-agents
+    participant Utility as Utility Agents
+
+    Note over CC: Session Start
+    
+    rect rgb(225, 245, 254)
+        Note over Main: System Prompt Assembly
+        CC->>Main: Load Main System Prompt
+        CC->>Main: Inject Tool Descriptions
+        CC->>Main: Add Conditional Sections<br/>(Git Status, Learning Mode, etc.)
+    end
+
+    User->>CC: Initial message
+    CC->>Main: Process request
+
+    rect rgb(232, 245, 233)
+        Note over Main,Tools: Work Phase
+        loop Task Execution
+            Main->>Tools: Use tools (Read, Write, Bash, etc.)
+            Tools-->>Main: Results
+            
+            alt Complex task
+                Main->>SubAgent: Delegate via Task tool
+                Note over SubAgent: Agent-specific prompt loaded
+                SubAgent-->>Main: Results
+            end
+        end
+    end
+
+    rect rgb(255, 243, 224)
+        Note over Utility: Context Management
+        alt Context grows large
+            CC->>Utility: Trigger Summarization
+            Note over Utility: Conversation Summarization prompt
+            Utility-->>CC: Compressed context
+        end
+    end
+
+    User->>CC: Follow-up messages
+    Note over Main: Continue with context
+
+    rect rgb(252, 228, 236)
+        Note over Utility: Session End
+        CC->>Utility: Generate session title
+        Note over Utility: Session Title & Branch prompt
+        Utility-->>CC: Title and branch name
+    end
+```
+
+## Lifecycle Phases
+
+### 1. Session Initialization
+
+When a Claude Code session starts, the system prompt is assembled from multiple pieces:
+
+```mermaid
+flowchart LR
+    subgraph Assembly["System Prompt Assembly"]
+        direction TB
+        Base["Main System Prompt"]
+        Tools["Tool Descriptions"]
+        Cond["Conditional Sections"]
+        
+        Base --> Final["Complete System Prompt"]
+        Tools --> Final
+        Cond --> Final
+    end
+    
+    click Base href "../system-prompts/system-prompt-main-system-prompt.md" "Main System Prompt"
+```
+
+**Key Prompts:**
+- [Main System Prompt](../system-prompts/system-prompt-main-system-prompt.md) - Core behavior and policies
+- [Git Status](../system-prompts/system-prompt-git-status.md) - Repository state (if in git repo)
+- [Learning Mode](../system-prompts/system-prompt-learning-mode.md) - Educational mode (if enabled)
+- [Scratchpad Directory](../system-prompts/system-prompt-scratchpad-directory.md) - Temp file location (if configured)
+
+### 2. Work Phase
+
+During active work, the main agent uses tools and may delegate to sub-agents:
+
+| Action | Prompts Used |
+|--------|-------------|
+| Direct tool use | Individual [tool descriptions](./3-tool-ecosystem.md) |
+| Codebase exploration | [Explore Agent](../system-prompts/agent-prompt-explore.md) via Task |
+| Planning | [Plan Agent](../system-prompts/agent-prompt-plan-mode-enhanced.md) via Task |
+| Task management | [TodoWrite](../system-prompts/tool-description-todowrite.md) |
+
+### 3. Context Management
+
+As conversation grows, summarization preserves important context:
+
+```mermaid
+flowchart LR
+    Long["Long Conversation"] --> Trigger{"Context<br/>too large?"}
+    Trigger -->|Yes| Summary["Summarization Agent"]
+    Summary --> Compact["Compacted Context"]
+    Compact --> Continue["Continue Session"]
+    Trigger -->|No| Continue
+    
+    click Summary href "../system-prompts/agent-prompt-conversation-summarization.md" "Summarization"
+```
+
+**Key Prompts:**
+- [Conversation Summarization](../system-prompts/agent-prompt-conversation-summarization.md) - Standard summarization
+- [Summarization with Additional Instructions](../system-prompts/agent-prompt-conversation-summarization-with-additional-instructions.md) - Custom summarization rules
+
+### 4. Session End
+
+When a session concludes, utility agents generate metadata:
+
+**Key Prompts:**
+- [Session Title & Branch Generation](../system-prompts/agent-prompt-session-title-and-branch-generation.md) - Creates descriptive title and git branch name
+- [Session Notes Template](../system-prompts/agent-prompt-session-notes-template.md) - Structure for session notes
+- [Session Notes Update](../system-prompts/agent-prompt-session-notes-update-instructions.md) - How to update notes during session
+
+## Prompt Injection Points
+
+| Phase | Injection Point | Prompt Type |
+|-------|----------------|-------------|
+| Start | System message | Main + conditionals |
+| Tool call | Tool schema | Tool descriptions |
+| Sub-agent spawn | New context | Agent prompts |
+| Context compact | Background | Summarization prompt |
+| Plan mode | System reminder | Plan mode reminders |
+| Session end | Background | Title/branch generation |
--- a/architecture/5-plan-mode-flow.md
+++ b/architecture/5-plan-mode-flow.md
@ -0,0 +1,165 @@
+# Plan Mode Flow
+
+This diagram shows the planning subsystem—how Claude Code enters, operates in, and exits plan mode.
+
+```mermaid
+stateDiagram-v2
+    [*] --> NormalMode: Session Start
+    
+    NormalMode --> PlanMode: Shift+Tab OR<br/>EnterPlanMode tool
+    
+    state PlanMode {
+        direction TB
+        [*] --> Exploring
+        Exploring --> Designing: Understanding complete
+        Designing --> ProposingPlan: Design ready
+        
+        state Exploring {
+            direction LR
+            ReadFiles: Read relevant files
+            SearchCode: Search codebase
+            AnalyzeArch: Analyze architecture
+        }
+        
+        state Designing {
+            direction LR
+            IdentifyPatterns: Identify patterns
+            ConsiderTradeoffs: Consider trade-offs
+            PlanSteps: Plan implementation steps
+        }
+    }
+    
+    PlanMode --> ExitDecision: ExitPlanMode tool
+    
+    state ExitDecision <<choice>>
+    ExitDecision --> Implementation: User approves
+    ExitDecision --> PlanMode: User requests changes
+    
+    Implementation --> NormalMode: Work complete
+    NormalMode --> PlanMode: Re-enter (Shift+Tab)
+    
+    NormalMode --> [*]: Session End
+```
+
+## Plan Mode Entry Points
+
+```mermaid
+flowchart LR
+    subgraph Triggers["Entry Triggers"]
+        Keyboard["⌨️ Shift+Tab"]
+        Tool["🔧 EnterPlanMode tool"]
+        Complex["🤔 Complex task detected"]
+    end
+    
+    subgraph Entry["Plan Mode Activation"]
+        Enter["EnterPlanMode"]
+        Reminder["Plan Mode Reminder<br/>injected into context"]
+    end
+    
+    Triggers --> Entry
+    
+    click Enter href "../system-prompts/tool-description-enterplanmode.md" "EnterPlanMode"
+    click Reminder href "../system-prompts/system-reminder-plan-mode-is-active.md" "Plan Mode Reminder"
+```
+
+**Key Prompts:**
+- [EnterPlanMode Tool](../system-prompts/tool-description-enterplanmode.md) - Tool description for entering plan mode
+- [Plan Mode Active Reminder](../system-prompts/system-reminder-plan-mode-is-active.md) - System reminder injected when plan mode is active
+
+## Plan Mode Operation
+
+While in plan mode, Claude Code operates in **read-only** mode with specific capabilities:
+
+```mermaid
+flowchart TB
+    subgraph Capabilities["✅ Allowed in Plan Mode"]
+        Read["Read files"]
+        Search["Search codebase"]
+        Analyze["Analyze patterns"]
+        Design["Design solutions"]
+        Parallel["Spawn parallel<br/>exploration agents"]
+    end
+    
+    subgraph Restricted["❌ Restricted in Plan Mode"]
+        Write["Write files"]
+        Edit["Edit files"]
+        Execute["Execute commands<br/>(except read-only)"]
+        Create["Create anything"]
+    end
+    
+    PlanAgent["Plan Mode Agent"]
+    PlanAgent --> Capabilities
+    PlanAgent -.->|blocked| Restricted
+    
+    click PlanAgent href "../system-prompts/agent-prompt-plan-mode-enhanced.md" "Plan Mode Agent"
+```
+
+**Key Prompts:**
+- [Plan Mode Agent](../system-prompts/agent-prompt-plan-mode-enhanced.md) - Enhanced planning prompt
+- [Plan Mode for Subagents](../system-prompts/system-reminder-plan-mode-is-active-for-subagents.md) - Simplified reminder for spawned sub-agents
+
+## Plan Mode Exit
+
+```mermaid
+flowchart TB
+    PlanReady["Plan Ready"]
+    Exit["ExitPlanMode Tool"]
+    
+    subgraph Dialog["Plan Approval Dialog"]
+        Present["Present plan to user"]
+        UserChoice{{"User Decision"}}
+        Approve["✅ Approve"]
+        Modify["✏️ Request changes"]
+        Reject["❌ Reject"]
+    end
+    
+    PlanReady --> Exit
+    Exit --> Present
+    Present --> UserChoice
+    UserChoice --> Approve
+    UserChoice --> Modify
+    UserChoice --> Reject
+    
+    Approve --> Implement["Begin Implementation"]
+    Modify --> Continue["Continue Planning"]
+    Reject --> Normal["Return to Normal Mode"]
+    
+    click Exit href "../system-prompts/tool-description-exitplanmode.md" "ExitPlanMode"
+```
+
+**Key Prompts:**
+- [ExitPlanMode Tool](../system-prompts/tool-description-exitplanmode.md) - Standard exit tool
+- [ExitPlanMode v2](../system-prompts/tool-description-exitplanmode-v2.md) - Enhanced plan dialog
+
+## Re-entry Flow
+
+Users can re-enter plan mode after exiting:
+
+```mermaid
+flowchart LR
+    Normal["Normal Mode<br/>(implementing)"]
+    ReEnter["Shift+Tab"]
+    PlanAgain["Plan Mode<br/>(re-entered)"]
+    Reminder["Re-entry Reminder"]
+    
+    Normal --> ReEnter
+    ReEnter --> PlanAgain
+    PlanAgain --> Reminder
+    
+    click Reminder href "../system-prompts/system-reminder-plan-mode-re-entry.md" "Re-entry Reminder"
+```
+
+**Key Prompt:**
+- [Plan Mode Re-entry](../system-prompts/system-reminder-plan-mode-re-entry.md) - Reminder when re-entering plan mode after implementation
+
+## All Plan Mode Prompts
+
+| Prompt | Purpose | File |
+|--------|---------|------|
+| **EnterPlanMode** | Tool to enter plan mode | [tool-description-enterplanmode.md](../system-prompts/tool-description-enterplanmode.md) |
+| **ExitPlanMode** | Tool to exit with plan | [tool-description-exitplanmode.md](../system-prompts/tool-description-exitplanmode.md) |
+| **ExitPlanMode v2** | Enhanced exit dialog | [tool-description-exitplanmode-v2.md](../system-prompts/tool-description-exitplanmode-v2.md) |
+| **Plan Mode Agent** | Agent behavior in plan mode | [agent-prompt-plan-mode-enhanced.md](../system-prompts/agent-prompt-plan-mode-enhanced.md) |
+| **Active Reminder** | Injected while plan mode active | [system-reminder-plan-mode-is-active.md](../system-prompts/system-reminder-plan-mode-is-active.md) |
+| **Subagent Reminder** | Simplified reminder for sub-agents | [system-reminder-plan-mode-is-active-for-subagents.md](../system-prompts/system-reminder-plan-mode-is-active-for-subagents.md) |
+| **Re-entry Reminder** | When re-entering after exit | [system-reminder-plan-mode-re-entry.md](../system-prompts/system-reminder-plan-mode-re-entry.md) |
--- a/architecture/6-slash-commands-and-skills.md
+++ b/architecture/6-slash-commands-and-skills.md
@ -0,0 +1,166 @@
+# Slash Commands & Skills
+
+This diagram maps Claude Code's built-in slash commands and the skill system to their prompts.
+
+```mermaid
+flowchart TB
+    subgraph SlashCommands["Slash Commands"]
+        direction TB
+        
+        subgraph PR["Pull Request Commands"]
+            PRComments["/pr-comments<br/><i>Fetch PR comments</i>"]
+            ReviewPR["/review-pr<br/><i>Review a PR</i>"]
+            click PRComments href "../system-prompts/agent-prompt-pr-comments-slash-command.md" "/pr-comments"
+            click ReviewPR href "../system-prompts/agent-prompt-review-pr-slash-command.md" "/review-pr"
+        end
+        
+        subgraph Security["Security Commands"]
+            SecReview["/security-review<br/><i>Security analysis</i>"]
+            click SecReview href "../system-prompts/agent-prompt-security-review-slash.md" "/security-review"
+        end
+        
+        subgraph Memory["Memory Commands"]
+            Remember["/remember<br/><i>Save learnings</i>"]
+            click Remember href "../system-prompts/agent-prompt-remember-skill.md" "/remember"
+        end
+    end
+    
+    subgraph SkillSystem["Skill System"]
+        SkillTool["Skill Tool"]
+        SkillDesc["Skill Description"]
+        CustomSkills["Custom Skills<br/><i>User-defined</i>"]
+        click SkillTool href "../system-prompts/tool-description-skill.md" "Skill Tool"
+    end
+    
+    User["👤 User"]
+    User -->|"/command"| SlashCommands
+    User -->|"Skill invocation"| SkillSystem
+    
+    style SlashCommands fill:#e1f5fe
+    style SkillSystem fill:#f3e5f5
+    style PR fill:#e8f5e9
+    style Security fill:#fff3e0
+    style Memory fill:#fce4ec
+```
+
+## Built-in Slash Commands
+
+### `/pr-comments` - Fetch PR Comments
+
+Fetches and displays comments from a GitHub Pull Request.
+
+```mermaid
+flowchart LR
+    Cmd["/pr-comments"] --> Agent["PR Comments Agent"]
+    Agent --> Fetch["Fetch from GitHub"]
+    Fetch --> Display["Display comments"]
+    
+    click Agent href "../system-prompts/agent-prompt-pr-comments-slash-command.md" "PR Comments Agent"
+```
+
+**Prompt:** [agent-prompt-pr-comments-slash-command.md](../system-prompts/agent-prompt-pr-comments-slash-command.md)
+
+---
+
+### `/review-pr` - Review Pull Request
+
+Performs a code review on a GitHub Pull Request.
+
+```mermaid
+flowchart LR
+    Cmd["/review-pr"] --> Agent["PR Review Agent"]
+    Agent --> Analyze["Analyze changes"]
+    Analyze --> Review["Generate review"]
+    
+    click Agent href "../system-prompts/agent-prompt-review-pr-slash-command.md" "PR Review Agent"
+```
+
+**Prompt:** [agent-prompt-review-pr-slash-command.md](../system-prompts/agent-prompt-review-pr-slash-command.md)
+
+---
+
+### `/security-review` - Security Analysis
+
+Comprehensive security review focusing on exploitable vulnerabilities (OWASP Top 10, etc.).
+
+```mermaid
+flowchart LR
+    Cmd["/security-review"] --> Agent["Security Review Agent"]
+    Agent --> Scan["Scan for vulnerabilities"]
+    Scan --> Report["Generate report<br/>with severity levels"]
+    
+    click Agent href "../system-prompts/agent-prompt-security-review-slash.md" "Security Review Agent"
+```
+
+**Prompt:** [agent-prompt-security-review-slash.md](../system-prompts/agent-prompt-security-review-slash.md)
+
+*Note: This is the largest slash command prompt at ~2610 tokens, reflecting the depth of security analysis.*
+
+---
+
+### `/remember` - Save Learnings
+
+Reviews session memories and updates `CLAUDE.local.md` with recurring patterns and learnings.
+
+```mermaid
+flowchart LR
+    Cmd["/remember"] --> Agent["Remember Skill Agent"]
+    Agent --> Review["Review session"]
+    Review --> Update["Update CLAUDE.local.md"]
+    
+    click Agent href "../system-prompts/agent-prompt-remember-skill.md" "Remember Skill Agent"
+```
+
+**Prompt:** [agent-prompt-remember-skill.md](../system-prompts/agent-prompt-remember-skill.md)
+
+---
+
+## Skill System
+
+The Skill tool allows execution of both built-in and custom skills.
+
+```mermaid
+flowchart TB
+    subgraph Invocation["Skill Invocation"]
+        Direct["Direct call"]
+        SlashCmd["Via slash command"]
+        Auto["Automatic trigger"]
+    end
+    
+    SkillTool["Skill Tool"]
+    
+    subgraph Execution["Skill Execution"]
+        Load["Load skill definition"]
+        Context["Inject into conversation"]
+        Run["Execute skill logic"]
+    end
+    
+    Invocation --> SkillTool
+    SkillTool --> Execution
+    
+    click SkillTool href "../system-prompts/tool-description-skill.md" "Skill Tool"
+```
+
+**Prompt:** [tool-description-skill.md](../system-prompts/tool-description-skill.md)
+
+---
+
+## Quick Reference
+
+| Command | Purpose | Prompt File |
+|---------|---------|-------------|
+| `/pr-comments` | Fetch GitHub PR comments | [agent-prompt-pr-comments-slash-command.md](../system-prompts/agent-prompt-pr-comments-slash-command.md) |
+| `/review-pr` | Review a Pull Request | [agent-prompt-review-pr-slash-command.md](../system-prompts/agent-prompt-review-pr-slash-command.md) |
+| `/security-review` | Security vulnerability analysis | [agent-prompt-security-review-slash.md](../system-prompts/agent-prompt-security-review-slash.md) |
+| `/remember` | Save session learnings | [agent-prompt-remember-skill.md](../system-prompts/agent-prompt-remember-skill.md) |
+| *Skill Tool* | Execute custom skills | [tool-description-skill.md](../system-prompts/tool-description-skill.md) |
+
+## Related Prompts
+
+These utility prompts support the slash command system:
+
+| Prompt | Purpose | File |
+|--------|---------|------|
+| **CLAUDE.md Creation** | Generate project documentation | [agent-prompt-claudemd-creation.md](../system-prompts/agent-prompt-claudemd-creation.md) |
+| **Agent Creation** | Create custom agents | [agent-prompt-agent-creation-architect.md](../system-prompts/agent-prompt-agent-creation-architect.md) |
+| **Prompt Suggestions** | Generate follow-up prompts | [agent-prompt-prompt-suggestion-generator-v2.md](../system-prompts/agent-prompt-prompt-suggestion-generator-v2.md) |