From ee0649bccdf00d5d5524d2629331cce1a1401f41 Mon Sep 17 00:00:00 2001 From: bl-ue <54780737+bl-ue@users.noreply.github.com> Date: Sun, 11 Jan 2026 09:30:06 -0700 Subject: [PATCH] First attempt --- .../1-high-level-system-architecture.md | 77 ++++++++ architecture/2-agent-delegation-flow.md | 101 +++++++++++ architecture/3-tool-ecosystem.md | 133 ++++++++++++++ architecture/4-conversation-lifecycle.md | 137 +++++++++++++++ architecture/5-plan-mode-flow.md | 165 +++++++++++++++++ architecture/6-slash-commands-and-skills.md | 166 ++++++++++++++++++ 6 files changed, 779 insertions(+) create mode 100644 architecture/1-high-level-system-architecture.md create mode 100644 architecture/2-agent-delegation-flow.md create mode 100644 architecture/3-tool-ecosystem.md create mode 100644 architecture/4-conversation-lifecycle.md create mode 100644 architecture/5-plan-mode-flow.md create mode 100644 architecture/6-slash-commands-and-skills.md diff --git a/architecture/1-high-level-system-architecture.md b/architecture/1-high-level-system-architecture.md new file mode 100644 index 0000000..634033c --- /dev/null +++ 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["Main System Prompt
Behavior, tone, policies,
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
Read, Write, Edit,
Glob, Grep"] + ExecTools["Execution
Bash"] + WebTools["Web
Search, Fetch"] + PlanTools["Planning
TodoWrite,
Enter/Exit PlanMode"] + InteractTools["Interaction
Task, Skill,
AskUserQuestion"] + end + + subgraph Agents["Sub-agents"] + direction LR + Explore["Explore
Read-only search"] + Plan["Plan
Read-only design"] + TaskAgent["Task Agent
Autonomous work"] + 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
Summarization"] + Session["Session Title
& Branch Gen"] + Hooks["Hooks"] + Sentiment["User Sentiment
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) | diff --git a/architecture/2-agent-delegation-flow.md b/architecture/2-agent-delegation-flow.md new file mode 100644 index 0000000..755d23e --- /dev/null +++ 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
Main System Prompt"] + 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 /
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["Explore Agent
Read-only codebase search
Tools: Glob, Grep, Read, Bash"] + Plan["Plan Agent
Read-only architecture design
Tools: Glob, Grep, Read, Bash"] + Custom["Custom Agents
User-defined via config"] + 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
Given to spawned agent"] + ExtraNotes["Extra Notes
Absolute paths, formatting"] + 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) diff --git a/architecture/3-tool-ecosystem.md b/architecture/3-tool-ecosystem.md new file mode 100644 index 0000000..08a3f19 --- /dev/null +++ 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["ReadFile
Read file contents"] + Write["Write
Create/overwrite files"] + Edit["Edit
String replacement in files"] + Glob["Glob
Pattern-based file search"] + Grep["Grep
Content search with regex"] + Notebook["NotebookEdit
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["Bash
Shell command execution"] + BashGit["Git & PR Instructions
Commit and PR creation"] + BashSandbox["Sandbox Note
Security sandboxing"] + 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["WebSearch
Real-time web search"] + WebFetch["WebFetch
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["TodoWrite
Task list management"] + Enter["EnterPlanMode
Start planning mode"] + Exit["ExitPlanMode
Present plan for approval"] + ExitV2["ExitPlanMode v2
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["Task
Launch sub-agents"] + Skill["Skill
Execute skills"] + Ask["AskUserQuestion
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["Computer
Chrome browser automation"] + LSP["LSP
Language Server Protocol"] + MCP["MCPSearch
MCP server discovery"] + MCPTools["MCPSearch
with available tools"] + 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) | diff --git a/architecture/4-conversation-lifecycle.md b/architecture/4-conversation-lifecycle.md new file mode 100644 index 0000000..df9a753 --- /dev/null +++ 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
(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
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 | diff --git a/architecture/5-plan-mode-flow.md b/architecture/5-plan-mode-flow.md new file mode 100644 index 0000000..767455e --- /dev/null +++ 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
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 <> + 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
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
exploration agents"] + end + + subgraph Restricted["❌ Restricted in Plan Mode"] + Write["Write files"] + Edit["Edit files"] + Execute["Execute commands
(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
(implementing)"] + ReEnter["Shift+Tab"] + PlanAgain["Plan Mode
(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) | diff --git a/architecture/6-slash-commands-and-skills.md b/architecture/6-slash-commands-and-skills.md new file mode 100644 index 0000000..5d9d05d --- /dev/null +++ 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
Fetch PR comments"] + ReviewPR["/review-pr
Review a PR"] + 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
Security analysis"] + click SecReview href "../system-prompts/agent-prompt-security-review-slash.md" "/security-review" + end + + subgraph Memory["Memory Commands"] + Remember["/remember
Save learnings"] + 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
User-defined"] + 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
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) |