claude-code-workflow 6.2.1 → 6.2.3

package/.claude/skills/command-guide/guides/implementation-details.md

@@ -0,0 +1,1010 @@
+# Implementation Details
+
+Detailed implementation logic for command-guide skill operation modes.
+
+## Architecture Overview
+
+```
+User Query
+    ↓
+Intent Recognition
+    ↓
+Mode Selection (1 of 6)
+    ↓
+Index/File/Reference Query
+    ↓
+Optional CLI Analysis (Mode 6)
+    ↓
+Response Formation
+    ↓
+User Output + Recommendations
+```
+
+---
+
+## Intent Recognition
+
+### Step 1: Parse User Input
+
+Analyze query for trigger keywords and patterns:
+
+```javascript
+function recognizeIntent(userQuery) {
+  const query = userQuery.toLowerCase();
+
+  // Mode 5: Issue Reporting (highest priority)
+  if (query.includes('ccw-issue') || query.includes('ccw-help') ||
+      query.match(/报告.*bug/) || query.includes('功能建议')) {
+    return 'ISSUE_REPORTING';
+  }
+
+  // Mode 1: Command Search
+  if (query.includes('搜索') || query.includes('find') ||
+      query.includes('search') || query.match(/.*相关.*命令/)) {
+    return 'COMMAND_SEARCH';
+  }
+
+  // Mode 2: Recommendations
+  if (query.includes('下一步') || query.includes("what's next") ||
+      query.includes('推荐') || query.match(/after.*\/\w+:\w+/)) {
+    return 'RECOMMENDATIONS';
+  }
+
+  // Mode 3: Documentation
+  if (query.includes('参数') || query.includes('怎么用') ||
+      query.includes('如何使用') || query.match(/\/\w+:\w+.*详情/)) {
+
+    // Special case: CLI tools usage guide
+    if (query.match(/cli.*工具/) || query.match(/如何.*使用.*cli/) ||
+        query.match(/gemini|qwen|codex.*使用/) || query.match(/优雅.*使用/) ||
+        query.includes('cli能力') || query.includes('cli特性') ||
+        query.includes('语义调用') || query.includes('命令调用')) {
+      return 'CLI_TOOLS_GUIDE';
+    }
+
+    return 'DOCUMENTATION';
+  }
+
+  // Mode 4: Onboarding
+  if (query.includes('新手') || query.includes('入门') ||
+      query.includes('getting started') || query.includes('常用命令')) {
+    return 'ONBOARDING';
+  }
+
+  // Mode 6: Deep Command Analysis
+  // Triggered by specific command/agent names or complexity indicators
+  if (query.match(/\/\w+:\w+/) || // Contains command name pattern
+      query.match(/agent.*工作|实现.*原理|命令.*细节/) || // Asks about internals
+      query.includes('详细说明') || query.includes('实现细节') ||
+      query.match(/对比.*命令|workflow.*对比/) || // Comparison queries
+      query.match(/\w+-agent/) || // Agent name pattern
+      query.includes('最佳实践') && query.match(/\w+:\w+/)) { // Best practices for specific command
+    return 'DEEP_ANALYSIS';
+  }
+
+  // Default: Ask for clarification
+  return 'CLARIFY';
+}
+```
+
+---
+
+## Mode 1: Command Search 🔍
+
+### Trigger Analysis
+
+**Keywords**: 搜索, find, search, [topic] 相关命令
+
+**Examples**:
+- "搜索 planning 命令"
+- "find commands for testing"
+- "实现相关的命令有哪些"
+
+### Processing Flow
+
+```
+1. Extract Search Parameters
+   ↓
+2. Determine Search Type
+   ├─ Keyword Search (in name/description)
+   ├─ Category Search (workflow/cli/memory/task)
+   └─ Use-Case Search (planning/implementation/testing)
+   ↓
+3. Query Appropriate Index
+   ├─ Keyword → all-commands.json
+   ├─ Category → by-category.json
+   └─ Use-Case → by-use-case.json
+   ↓
+4. Filter and Rank Results
+   ↓
+5. Format Response
+   ├─ List matching commands
+   ├─ Show key metadata (name, description, args)
+   └─ Suggest related commands
+```
+
+### Implementation
+
+```javascript
+async function searchCommands(query, searchType) {
+  let results = [];
+
+  switch (searchType) {
+    case 'keyword':
+      // Load all-commands.json
+      const allCommands = await readIndex('all-commands.json');
+      results = allCommands.filter(cmd =>
+        cmd.name.toLowerCase().includes(query.toLowerCase()) ||
+        cmd.description.toLowerCase().includes(query.toLowerCase())
+      );
+      break;
+
+    case 'category':
+      // Load by-category.json
+      const byCategory = await readIndex('by-category.json');
+      const category = extractCategory(query); // e.g., "workflow"
+      results = flattenCategory(byCategory[category]);
+      break;
+
+    case 'use-case':
+      // Load by-use-case.json
+      const byUseCase = await readIndex('by-use-case.json');
+      const useCase = extractUseCase(query); // e.g., "planning"
+      results = byUseCase[useCase] || [];
+      break;
+  }
+
+  // Rank by relevance
+  results = rankResults(results, query);
+
+  // Add related commands
+  results = await enrichWithRelated(results);
+
+  return results;
+}
+```
+
+---
+
+## Mode 2: Smart Recommendations 🤖
+
+### Trigger Analysis
+
+**Keywords**: 下一步, what's next, 推荐, after [command]
+
+**Examples**:
+- "执行完 /workflow:plan 后做什么？"
+- "What's next after planning?"
+- "推荐下一个命令"
+
+### Processing Flow
+
+```
+1. Extract Context
+   ├─ Current/Last Command
+   ├─ Workflow State
+   └─ User's Current Task
+   ↓
+2. Query Relationships
+   └─ Load command-relationships.json
+   ↓
+3. Find Next Steps
+   ├─ Check next_steps array
+   ├─ Consider prerequisites
+   └─ Check related_commands
+   ↓
+4. Generate Recommendations
+   ├─ Primary recommendation (most common next step)
+   ├─ Alternative options
+   └─ Rationale for each
+   ↓
+5. Add Workflow Context
+   └─ Link to workflow-patterns.md
+```
+
+### Implementation
+
+```javascript
+async function getRecommendations(currentCommand) {
+  // Load relationships
+  const relationships = await readIndex('command-relationships.json');
+
+  // Get relationship data
+  const cmdData = relationships[currentCommand];
+
+  if (!cmdData) {
+    return defaultRecommendations();
+  }
+
+  // Primary next steps
+  const nextSteps = cmdData.next_steps || [];
+
+  // Alternative related commands
+  const alternatives = cmdData.related_commands || [];
+
+  // Build recommendations
+  const recommendations = {
+    primary: await enrichCommand(nextSteps[0]),
+    alternatives: await enrichCommands(alternatives),
+    workflow_pattern: findWorkflowPattern(currentCommand),
+    rationale: generateRationale(currentCommand, nextSteps[0])
+  };
+
+  return recommendations;
+}
+```
+
+---
+
+## Mode 3: Full Documentation 📖
+
+### Trigger Analysis
+
+**Keywords**: 参数, 怎么用, 如何使用, [command] 详情
+
+**Examples**:
+- "/workflow:plan 的参数是什么？"
+- "如何使用 /cli:execute？"
+- "task:create 详细文档"
+
+**Special Case - CLI Tools Guide**:
+**Keywords**: cli工具, 如何使用cli, gemini/qwen/codex使用, 优雅使用, cli能力, cli特性, 语义调用, 命令调用
+
+**Examples**:
+- "如何优雅的使用cli工具"
+- "cli工具能做什么"
+- "gemini和codex的区别"
+- "语义调用是什么"
+
+### Processing Flow
+
+```
+1. Extract Command Name
+   └─ Parse /workflow:plan or workflow:plan
+   ↓
+2. Locate in Index
+   └─ Search all-commands.json
+   ↓
+3. Read Full Command File
+   └─ Use file_path from index
+   ↓
+4. Extract Documentation
+   ├─ Parameters section
+   ├─ Arguments specification
+   ├─ Examples section
+   └─ Best practices
+   ↓
+5. Format Response
+   ├─ Command overview
+   ├─ Full parameter list
+   ├─ Usage examples
+   └─ Related commands
+```
+
+### Implementation
+
+```javascript
+async function getDocumentation(commandName, queryType = 'DOCUMENTATION') {
+  // Special case: CLI tools usage guide
+  if (queryType === 'CLI_TOOLS_GUIDE') {
+    const guideContent = await readFile('guides/cli-tools-guide.md');
+    return {
+      type: 'CLI_TOOLS_GUIDE',
+      title: 'CLI 工具使用指南',
+      content: guideContent,
+      sections: {
+        introduction: extractSection(guideContent, '## 🎯 快速理解'),
+        comparison: extractSection(guideContent, '## 📋 三大工具能力对比'),
+        how_to_use: extractSection(guideContent, '## 🚀 如何调用'),
+        capabilities: extractSection(guideContent, '## 💡 能力特性清单'),
+        scenarios: extractSection(guideContent, '## 🔄 典型使用场景'),
+        quick_reference: extractSection(guideContent, '## 📚 快速参考'),
+        faq: extractSection(guideContent, '## 🆘 常见问题')
+      },
+      related_docs: [
+        'intelligent-tools-strategy.md',
+        'workflow-patterns.md',
+        'getting-started.md'
+      ]
+    };
+  }
+
+  // Normal command documentation
+  // Normalize command name
+  const normalized = normalizeCommandName(commandName);
+
+  // Find in index
+  const allCommands = await readIndex('all-commands.json');
+  const command = allCommands.find(cmd => cmd.name === normalized);
+
+  if (!command) {
+    return { error: 'Command not found' };
+  }
+
+  // Read full command file
+  const commandFilePath = path.join(
+    '../commands',
+    command.file_path
+  );
+  const fullDoc = await readCommandFile(commandFilePath);
+
+  // Parse sections
+  const documentation = {
+    name: command.name,
+    description: command.description,
+    arguments: command.arguments,
+    difficulty: command.difficulty,
+    usage_scenario: command.usage_scenario,
+    parameters: extractSection(fullDoc, '## Parameters'),
+    examples: extractSection(fullDoc, '## Examples'),
+    best_practices: extractSection(fullDoc, '## Best Practices'),
+    related: await getRelatedCommands(command.name)
+  };
+
+  return documentation;
+}
+```
+
+---
+
+## Mode 4: Beginner Onboarding 🎓
+
+### Trigger Analysis
+
+**Keywords**: 新手, 入门, getting started, 常用命令, 如何开始
+
+**Examples**:
+- "我是新手，如何开始？"
+- "getting started with workflows"
+- "最常用的命令有哪些？"
+
+### Processing Flow
+
+```
+1. Assess User Level
+   └─ Identify as beginner
+   ↓
+2. Load Essential Commands
+   └─ Read essential-commands.json
+   ↓
+3. Build Learning Path
+   ├─ Step 1: Core commands (Top 5)
+   ├─ Step 2: Basic workflow
+   ├─ Step 3: Intermediate commands
+   └─ Step 4: Advanced features
+   ↓
+4. Provide Resources
+   ├─ Link to getting-started.md
+   ├─ Link to workflow-patterns.md
+   └─ Suggest first task
+   ↓
+5. Interactive Guidance
+   └─ Offer to walk through first workflow
+```
+
+### Implementation
+
+```javascript
+async function onboardBeginner() {
+  // Load essential commands
+  const essentialCommands = await readIndex('essential-commands.json');
+
+  // Group by difficulty
+  const beginner = essentialCommands.filter(cmd =>
+    cmd.difficulty === 'Beginner' || cmd.difficulty === 'Intermediate'
+  );
+
+  // Create learning path
+  const learningPath = {
+    step1: {
+      title: 'Core Commands (Start Here)',
+      commands: beginner.slice(0, 5),
+      guide: 'guides/getting-started.md'
+    },
+    step2: {
+      title: 'Your First Workflow',
+      pattern: 'Plan → Execute',
+      commands: ['workflow:plan', 'workflow:execute'],
+      guide: 'guides/workflow-patterns.md#basic-workflow'
+    },
+    step3: {
+      title: 'Intermediate Skills',
+      commands: beginner.slice(5, 10),
+      guide: 'guides/workflow-patterns.md#common-patterns'
+    }
+  };
+
+  // Resources
+  const resources = {
+    getting_started: 'guides/getting-started.md',
+    workflow_patterns: 'guides/workflow-patterns.md',
+    cli_tools: 'guides/cli-tools-guide.md',
+    troubleshooting: 'guides/troubleshooting.md'
+  };
+
+  return {
+    learning_path: learningPath,
+    resources: resources,
+    first_task: 'Try: /workflow:plan "create a simple feature"'
+  };
+}
+```
+
+---
+
+## Mode 5: Issue Reporting 📝
+
+### Trigger Analysis
+
+**Keywords**: CCW-issue, CCW-help, 报告 bug, 功能建议, 问题咨询
+
+**Examples**:
+- "CCW-issue"
+- "我要报告一个 bug"
+- "CCW-help 有问题"
+- "想提个功能建议"
+
+### Processing Flow
+
+```
+1. Detect Issue Type
+   └─ Use AskUserQuestion if unclear
+   ↓
+2. Select Template
+   ├─ Bug → templates/issue-bug.md
+   ├─ Feature → templates/issue-feature.md
+   └─ Question → templates/issue-question.md
+   ↓
+3. Collect Information
+   └─ Interactive Q&A
+      ├─ Problem description
+      ├─ Steps to reproduce (bug)
+      ├─ Expected vs actual (bug)
+      ├─ Use case (feature)
+      └─ Context
+   ↓
+4. Generate Filled Template
+   └─ Populate template with collected data
+   ↓
+5. Save or Display
+   ├─ Save to templates/.generated/
+   └─ Display for user to copy
+```
+
+### Implementation
+
+```javascript
+async function reportIssue(issueType) {
+  // Determine type (bug/feature/question)
+  if (!issueType) {
+    issueType = await askUserQuestion({
+      question: 'What type of issue would you like to report?',
+      options: ['Bug Report', 'Feature Request', 'Question']
+    });
+  }
+
+  // Select template
+  const templatePath = {
+    'bug': 'templates/issue-bug.md',
+    'feature': 'templates/issue-feature.md',
+    'question': 'templates/issue-question.md'
+  }[issueType.toLowerCase()];
+
+  const template = await readTemplate(templatePath);
+
+  // Collect information
+  const info = await collectIssueInfo(issueType);
+
+  // Fill template
+  const filledTemplate = fillTemplate(template, {
+    ...info,
+    timestamp: new Date().toISOString(),
+    auto_context: gatherAutoContext()
+  });
+
+  // Save
+  const outputPath = `templates/.generated/${issueType}-${Date.now()}.md`;
+  await writeFile(outputPath, filledTemplate);
+
+  return {
+    template: filledTemplate,
+    file_path: outputPath,
+    instructions: 'Copy content to GitHub Issues or use: gh issue create -F ' + outputPath
+  };
+}
+```
+
+---
+
+## Mode 6: Deep Command Analysis 🔬
+
+**Path Configuration Note**:
+This mode uses absolute paths (`~/.claude/skills/command-guide/reference`) to ensure the skill works correctly regardless of where it's installed. The skill is designed to be installed in `~/.claude/skills/` (user's global Claude configuration directory).
+
+### Trigger Analysis
+
+**Keywords**: 详细说明, 命令原理, agent 如何工作, 实现细节, 对比命令, 最佳实践
+
+**Examples**:
+- "action-planning-agent 如何工作？"
+- "/workflow:plan 的实现原理是什么？"
+- "对比 workflow:plan 和 workflow:tdd-plan"
+- "ui-design-agent 详细说明"
+
+### Processing Flow
+
+```
+1. Parse Query
+   ├─ Identify target command(s)/agent(s)
+   ├─ Determine query complexity
+   └─ Extract specific questions
+   ↓
+2. Classify Query Type
+   ├─ Simple: Single entity, basic explanation
+   └─ Complex: Multi-entity comparison, best practices, workflows
+   ↓
+3. Simple Query Path
+   ├─ Locate file in reference/
+   ├─ Read markdown content
+   ├─ Extract relevant sections
+   └─ Format response
+   ↓
+4. Complex Query Path
+   ├─ Identify all relevant files
+   ├─ Construct CLI analysis prompt
+   ├─ Execute gemini/qwen analysis
+   └─ Return comprehensive results
+   ↓
+5. Response Enhancement
+   ├─ Add usage examples
+   ├─ Link to related docs
+   └─ Suggest next steps
+```
+
+### Query Classification Logic
+
+```javascript
+function classifyDeepAnalysisQuery(query) {
+  const complexityIndicators = {
+    multiEntity: query.match(/对比|比较|区别/) && query.match(/(\/\w+:\w+.*){2,}/),
+    bestPractices: query.includes('最佳实践') || query.includes('推荐用法'),
+    workflowAnalysis: query.match(/工作流.*分析|流程.*说明/),
+    architecturalDepth: query.includes('架构') || query.includes('设计思路'),
+    crossReference: query.match(/和.*一起用|配合.*使用/)
+  };
+
+  const isComplex = Object.values(complexityIndicators).some(v => v);
+
+  return {
+    isComplex,
+    indicators: complexityIndicators,
+    requiresCLI: isComplex
+  };
+}
+```
+
+### Simple Query Implementation
+
+```javascript
+async function handleSimpleQuery(query) {
+  // Extract entity name (command or agent)
+  const entityName = extractEntityName(query); // e.g., "action-planning-agent" or "workflow:plan"
+
+  // Determine if command or agent
+  const isAgent = entityName.includes('-agent') || entityName.includes('agent');
+  const isCommand = entityName.includes(':') || entityName.startsWith('/');
+
+  // Base path for reference documentation
+  const basePath = '~/.claude/skills/command-guide/reference';
+
+  let filePath;
+  if (isAgent) {
+    // Agent query - use absolute path
+    const agentFileName = entityName.replace(/^\//, '').replace(/-agent$/, '-agent');
+    filePath = `${basePath}/agents/${agentFileName}.md`;
+  } else if (isCommand) {
+    // Command query - need to find in command hierarchy
+    const cmdName = entityName.replace(/^\//, '');
+    filePath = await locateCommandFile(cmdName, basePath);
+  }
+
+  // Read documentation
+  const docContent = await readFile(filePath);
+
+  // Extract relevant sections based on query keywords
+  const sections = extractRelevantSections(docContent, query);
+
+  // Format response
+  return {
+    entity: entityName,
+    type: isAgent ? 'agent' : 'command',
+    documentation: sections,
+    full_path: filePath,
+    related: await findRelatedEntities(entityName)
+  };
+}
+
+async function locateCommandFile(commandName, basePath) {
+  // Parse command category from name
+  // e.g., "workflow:plan" → "~/.claude/skills/command-guide/reference/commands/workflow/plan.md"
+  const [category, name] = commandName.split(':');
+
+  // Search in reference/commands hierarchy using absolute paths
+  const possiblePaths = [
+    `${basePath}/commands/${category}/${name}.md`,
+    `${basePath}/commands/${category}/${name}/*.md`,
+    `${basePath}/commands/${name}.md`
+  ];
+
+  for (const path of possiblePaths) {
+    if (await fileExists(path)) {
+      return path;
+    }
+  }
+
+  throw new Error(`Command file not found: ${commandName}`);
+}
+
+function extractRelevantSections(markdown, query) {
+  // Parse markdown into sections
+  const sections = parseMarkdownSections(markdown);
+
+  // Determine which sections are relevant
+  const keywords = extractKeywords(query);
+  const relevantSections = {};
+
+  // Always include overview/description
+  if (sections['## Overview'] || sections['## Description']) {
+    relevantSections.overview = sections['## Overview'] || sections['## Description'];
+  }
+
+  // Include specific sections based on keywords
+  if (keywords.includes('参数') || keywords.includes('参数说明')) {
+    relevantSections.parameters = sections['## Parameters'] || sections['## Arguments'];
+  }
+
+  if (keywords.includes('例子') || keywords.includes('示例') || keywords.includes('example')) {
+    relevantSections.examples = sections['## Examples'] || sections['## Usage'];
+  }
+
+  if (keywords.includes('工作流') || keywords.includes('流程')) {
+    relevantSections.workflow = sections['## Workflow'] || sections['## Process Flow'];
+  }
+
+  if (keywords.includes('最佳实践') || keywords.includes('建议')) {
+    relevantSections.best_practices = sections['## Best Practices'] || sections['## Recommendations'];
+  }
+
+  return relevantSections;
+}
+```
+
+### Complex Query Implementation (CLI-Assisted)
+
+```javascript
+async function handleComplexQuery(query, classification) {
+  // Identify all entities mentioned in query
+  const entities = extractAllEntities(query); // Returns array of command/agent names
+
+  // Build file context for CLI analysis
+  const contextPaths = [];
+  for (const entity of entities) {
+    const path = await resolveEntityPath(entity);
+    contextPaths.push(path);
+  }
+
+  // Construct CLI prompt based on query type
+  const prompt = buildCLIPrompt(query, classification, contextPaths);
+
+  // Execute CLI analysis
+  const cliResult = await executeCLIAnalysis(prompt);
+
+  return {
+    query_type: 'complex',
+    analysis_method: 'CLI-assisted (gemini)',
+    entities_analyzed: entities,
+    result: cliResult,
+    source_files: contextPaths
+  };
+}
+
+function buildCLIPrompt(userQuery, classification, contextPaths) {
+  // Extract key question
+  const question = extractCoreQuestion(userQuery);
+
+  // Build context reference
+  const contextRef = contextPaths.map(p => `@${p}`).join(' ');
+
+  // Determine analysis focus based on classification
+  let taskDescription = '';
+  if (classification.indicators.multiEntity) {
+    taskDescription = `• Compare the entities mentioned in terms of:
+  - Use cases and scenarios
+  - Capabilities and features
+  - When to use each
+  - Workflow integration
+• Provide side-by-side comparison
+• Recommend usage guidelines`;
+  } else if (classification.indicators.bestPractices) {
+    taskDescription = `• Analyze best practices for the mentioned entities
+• Provide practical usage recommendations
+• Include common pitfalls to avoid
+• Show example workflows`;
+  } else if (classification.indicators.workflowAnalysis) {
+    taskDescription = `• Trace the workflow execution
+• Explain process flow and dependencies
+• Identify key integration points
+• Provide usage examples`;
+  } else {
+    taskDescription = `• Provide comprehensive analysis
+• Explain implementation details
+• Show practical examples
+• Include related concepts`;
+  }
+
+  // Construct full prompt using Standard Template
+  // Note: CONTEXT uses @**/* because we'll use --include-directories to specify the reference path
+  return `PURPOSE: Analyze command/agent documentation to provide comprehensive answer to user query
+TASK:
+${taskDescription}
+MODE: analysis
+CONTEXT: @**/*
+EXPECTED: Comprehensive answer with examples, comparisons, and recommendations in markdown format
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | Focus on practical usage and real-world scenarios | analysis=READ-ONLY
+
+User Question: ${question}`;
+}
+
+async function executeCLIAnalysis(prompt) {
+  // Use absolute path for reference directory
+  // This ensures the command works regardless of where the skill is installed
+  const referencePath = '~/.claude/skills/command-guide/reference';
+
+  // Execute gemini with analysis prompt using --include-directories
+  // This allows gemini to access reference docs while maintaining correct file context
+  const command = `gemini -p "${escapePrompt(prompt)}" --include-directories ${referencePath}`;
+
+  try {
+    const result = await execBash(command, { timeout: 120000 }); // 2 min timeout
+    return parseAnalysisResult(result.stdout);
+  } catch (error) {
+    // Fallback to qwen if gemini fails
+    console.warn('Gemini failed, falling back to qwen');
+    const fallbackCmd = `qwen -p "${escapePrompt(prompt)}" --include-directories ${referencePath}`;
+    const result = await execBash(fallbackCmd, { timeout: 120000 });
+    return parseAnalysisResult(result.stdout);
+  }
+}
+
+function parseAnalysisResult(rawOutput) {
+  // Extract main content from CLI output
+  // Remove CLI wrapper/metadata, keep analysis content
+  const lines = rawOutput.split('\n');
+  const contentStart = lines.findIndex(l => l.trim().startsWith('#') || l.length > 50);
+  const content = lines.slice(contentStart).join('\n');
+
+  return {
+    raw: rawOutput,
+    parsed: content,
+    format: 'markdown'
+  };
+}
+```
+
+### Helper Functions
+
+```javascript
+function extractEntityName(query) {
+  // Extract command name pattern: /workflow:plan or workflow:plan
+  const cmdMatch = query.match(/\/?(\w+:\w+)/);
+  if (cmdMatch) return cmdMatch[1];
+
+  // Extract agent name pattern: action-planning-agent or action planning agent
+  const agentMatch = query.match(/(\w+(?:-\w+)*-agent|\w+\s+agent)/);
+  if (agentMatch) return agentMatch[1].replace(/\s+/g, '-');
+
+  return null;
+}
+
+function extractAllEntities(query) {
+  const entities = [];
+
+  // Find all command patterns
+  const commands = query.match(/\/?(\w+:\w+)/g);
+  if (commands) {
+    entities.push(...commands.map(c => c.replace('/', '')));
+  }
+
+  // Find all agent patterns
+  const agents = query.match(/(\w+(?:-\w+)*-agent)/g);
+  if (agents) {
+    entities.push(...agents);
+  }
+
+  return [...new Set(entities)]; // Deduplicate
+}
+
+async function resolveEntityPath(entityName) {
+  // Base path for reference documentation
+  const basePath = '~/.claude/skills/command-guide/reference';
+  const isAgent = entityName.includes('-agent');
+
+  if (isAgent) {
+    // Return relative path within reference directory (used for @context in CLI)
+    return `agents/${entityName}.md`;
+  } else {
+    // Command - need to find in hierarchy
+    const [category] = entityName.split(':');
+    // Use glob to find the file (glob pattern uses absolute path)
+    const matches = await glob(`${basePath}/commands/${category}/**/${entityName.split(':')[1]}.md`);
+    if (matches.length > 0) {
+      // Return relative path within reference directory
+      return matches[0].replace(`${basePath}/`, '');
+    }
+    throw new Error(`Entity file not found: ${entityName}`);
+  }
+}
+
+function extractCoreQuestion(query) {
+  // Remove common prefixes
+  const cleaned = query
+    .replace(/^(请|帮我|能否|可以)/g, '')
+    .replace(/^(ccw|CCW)[:\s]*/gi, '')
+    .trim();
+
+  // Ensure it ends with question mark if it's interrogative
+  if (cleaned.match(/什么|如何|为什么|怎么|哪个/) && !cleaned.endsWith('?') && !cleaned.endsWith('？')) {
+    return cleaned + '？';
+  }
+
+  return cleaned;
+}
+
+function escapePrompt(prompt) {
+  // Escape special characters for bash
+  return prompt
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\$/g, '\\$')
+    .replace(/`/g, '\\`');
+}
+```
+
+### Example Outputs
+
+**Simple Query Example**:
+```javascript
+// Input: "action-planning-agent 如何工作？"
+{
+  entity: "action-planning-agent",
+  type: "agent",
+  documentation: {
+    overview: "# Action Planning Agent\n\nGenerates structured task plans...",
+    workflow: "## Workflow\n1. Analyze requirements\n2. Break down into tasks...",
+    examples: "## Examples\n```bash\n/workflow:plan --agent \"feature\"\n```"
+  },
+  full_path: "~/.claude/skills/command-guide/reference/agents/action-planning-agent.md",
+  related: ["workflow:plan", "task:create", "conceptual-planning-agent"]
+}
+```
+
+**Complex Query Example**:
+```javascript
+// Input: "对比 workflow:plan 和 workflow:tdd-plan 的使用场景和最佳实践"
+{
+  query_type: "complex",
+  analysis_method: "CLI-assisted (gemini)",
+  entities_analyzed: ["workflow:plan", "workflow:tdd-plan"],
+  result: {
+    parsed: `# 对比分析: workflow:plan vs workflow:tdd-plan
+
+## 使用场景对比
+
+### workflow:plan
+- **适用场景**: 通用功能开发，无特殊测试要求
+- **特点**: 灵活的任务分解，focus on implementation
+...
+
+### workflow:tdd-plan
+- **适用场景**: 测试驱动开发，需要严格测试覆盖
+- **特点**: Red-Green-Refactor 循环，test-first
+...
+
+## 最佳实践
+
+### workflow:plan 最佳实践
+1. 先分析需求，明确目标
+2. 合理分解任务，避免过大或过小
+...
+
+### workflow:tdd-plan 最佳实践
+1. 先写测试，明确预期行为
+2. 保持 Red-Green-Refactor 节奏
+...
+
+## 选择建议
+
+| 情况 | 推荐命令 |
+|------|----------|
+| 新功能开发，无特殊测试要求 | workflow:plan |
+| 核心模块，需要高测试覆盖 | workflow:tdd-plan |
+| 快速原型，验证想法 | workflow:plan |
+| 关键业务逻辑 | workflow:tdd-plan |
+`,
+    format: "markdown"
+  },
+  source_files: [
+    "~/.claude/skills/command-guide/reference/commands/workflow/plan.md",
+    "~/.claude/skills/command-guide/reference/commands/workflow/tdd-plan.md"
+  ]
+}
+```
+
+---
+
+## Error Handling
+
+### Not Found
+```javascript
+if (results.length === 0) {
+  return {
+    message: 'No commands found matching your query.',
+    suggestions: [
+      'Try broader keywords',
+      'Browse by category: workflow, cli, memory, task',
+      'View all commands: essential-commands.json',
+      'Need help? Ask: "CCW-help"'
+    ]
+  };
+}
+```
+
+### Ambiguous Intent
+```javascript
+if (intent === 'CLARIFY') {
+  return await askUserQuestion({
+    question: 'What would you like to do?',
+    options: [
+      'Search for commands',
+      'Get recommendations for next steps',
+      'View command documentation',
+      'Learn how to get started',
+      'Report an issue or get help'
+    ]
+  });
+}
+```
+
+---
+
+## Optimization Strategies
+
+### Caching
+```javascript
+// Cache indexes in memory after first load
+const indexCache = new Map();
+
+async function readIndex(filename) {
+  if (indexCache.has(filename)) {
+    return indexCache.get(filename);
+  }
+
+  const data = await readFile(`index/${filename}`);
+  const parsed = JSON.parse(data);
+  indexCache.set(filename, parsed);
+  return parsed;
+}
+```
+
+### Lazy Loading
+```javascript
+// Only load full command files when needed
+// Use index metadata for most queries
+// Read command file only for Mode 3 (Documentation)
+```
+
+---
+
+**Last Updated**: 2025-11-06
+
+**Version**: 1.3.0 - Added Mode 6: Deep Command Analysis with reference documentation backup and CLI-assisted complex queries