claude-code-workflow 6.2.3 → 6.2.5

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

@@ -1,1010 +0,0 @@
-# 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