ccw-help

Original source / Raw SKILL.md

---
name: ccw-help
description: CCW command help system. Search, browse, recommend commands. Triggers "ccw-help", "ccw-issue".
allowed-tools: Read, Grep, Glob, AskUserQuestion
version: 7.0.0
---

# CCW-Help Skill

CCW 命令帮助系统，提供命令搜索、推荐、文档查看功能。

## Trigger Conditions

- 关键词: "ccw-help", "ccw-issue", "帮助", "命令", "怎么用"
- 场景: 询问命令用法、搜索命令、请求下一步建议

## Operation Modes

### Mode 1: Command Search

**Triggers**: "搜索命令", "find command", "search"

**Process**:
1. Query `command.json` commands array
2. Filter by name, description, category
3. Present top 3-5 relevant commands

### Mode 2: Smart Recommendations

**Triggers**: "下一步", "what's next", "推荐"

**Process**:
1. Query command's `flow.next_steps` in `command.json`
2. Explain WHY each recommendation fits

### Mode 3: Documentation

**Triggers**: "怎么用", "how to use", "详情"

**Process**:
1. Locate command in `command.json`
2. Read source file via `source` path
3. Provide context-specific examples

### Mode 4: Beginner Onboarding

**Triggers**: "新手", "getting started", "常用命令"

**Process**:
1. Query `essential_commands` array
2. Guide appropriate workflow entry point

### Mode 5: Issue Reporting

**Triggers**: "ccw-issue", "报告 bug"

**Process**:
1. Use AskUserQuestion to gather context
2. Generate structured issue template

## Data Source

Single source of truth: **[command.json](command.json)**

| Field | Purpose |
|-------|---------|
| `commands[]` | Flat command list with metadata |
| `commands[].flow` | Relationships (next_steps, prerequisites) |
| `commands[].essential` | Essential flag for onboarding |
| `agents[]` | Agent directory |
| `essential_commands[]` | Core commands list |

### Source Path Format

`source` 字段是相对路径（从 `skills/ccw-help/` 目录）：

```json
{
  "name": "lite-plan",
  "source": "../../../commands/workflow/lite-plan.md"
}
```

## Slash Commands

```bash
/ccw-help                    # 通用帮助入口
/ccw-help search <keyword>   # 搜索命令
/ccw-help next <command>     # 获取下一步建议
/ccw-issue                   # 问题报告
```

## Maintenance

### Update Index

```bash
cd D:/Claude_dms3/.claude/skills/ccw-help
python scripts/analyze_commands.py
```

脚本功能：扫描 commands/ 和 agents/ 目录，生成统一的 command.json

## Statistics

- **Commands**: 88+
- **Agents**: 16
- **Essential**: 10 核心命令

## Core Principle

**智能整合，非模板复制**

- 理解用户具体情况
- 整合多个来源信息
- 定制示例和说明


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### command.json

```json
{
  "_metadata": {
    "version": "2.0.0",
    "total_commands": 45,
    "total_agents": 16,
    "description": "Unified CCW-Help command index"
  },

  "essential_commands": [
    "/workflow:lite-plan",
    "/workflow:lite-fix",
    "/workflow:plan",
    "/workflow:execute",
    "/workflow:session:start",
    "/workflow:review-session-cycle",
    "/memory:docs",
    "/workflow:brainstorm:artifacts",
    "/workflow:action-plan-verify",
    "/version"
  ],

  "commands": [
    {
      "name": "lite-plan",
      "command": "/workflow:lite-plan",
      "description": "Lightweight interactive planning with in-memory plan, dispatches to lite-execute",
      "arguments": "[-e|--explore] \"task\"|file.md",
      "category": "workflow",
      "difficulty": "Intermediate",
      "essential": true,
      "flow": {
        "next_steps": ["/workflow:lite-execute"],
        "alternatives": ["/workflow:plan"]
      },
      "source": "../../../commands/workflow/lite-plan.md"
    },
    {
      "name": "lite-execute",
      "command": "/workflow:lite-execute",
      "description": "Execute based on in-memory plan or prompt",
      "arguments": "[--in-memory] \"task\"|file-path",
      "category": "workflow",
      "difficulty": "Intermediate",
      "flow": {
        "prerequisites": ["/workflow:lite-plan", "/workflow:lite-fix"]
      },
      "source": "../../../commands/workflow/lite-execute.md"
    },
    {
      "name": "lite-fix",
      "command": "/workflow:lite-fix",
      "description": "Lightweight bug diagnosis and fix with optional hotfix mode",
      "arguments": "[--hotfix] \"bug description\"",
      "category": "workflow",
      "difficulty": "Intermediate",
      "essential": true,
      "flow": {
        "next_steps": ["/workflow:lite-execute"],
        "alternatives": ["/workflow:lite-plan"]
      },
      "source": "../../../commands/workflow/lite-fix.md"
    },
    {
      "name": "plan",
      "command": "/workflow:plan",
      "description": "5-phase planning with task JSON generation",
      "arguments": "\"description\"|file.md",
      "category": "workflow",
      "difficulty": "Intermediate",
      "essential": true,
      "flow": {
        "next_steps": ["/workflow:action-plan-verify", "/workflow:execute"],
        "alternatives": ["/workflow:tdd-plan"]
      },
      "source": "../../../commands/workflow/plan.md"
    },
    {
      "name": "execute",
      "command": "/workflow:execute",
      "description": "Coordinate agent execution with DAG parallel processing",
      "arguments": "[--resume-session=\"session-id\"]",
      "category": "workflow",
      "difficulty": "Intermediate",
      "essential": true,
      "flow": {
        "prerequisites": ["/workflow:plan", "/workflow:tdd-plan"],
        "next_steps": ["/workflow:review"]
      },
      "source": "../../../commands/workflow/execute.md"
    },
    {
      "name": "action-plan-verify",
      "command": "/workflow:action-plan-verify",
      "description": "Cross-artifact consistency analysis",
      "arguments": "[--session session-id]",
      "category": "workflow",
      "difficulty": "Intermediate",
      "essential": true,
      "flow": {
        "prerequisites": ["/workflow:plan"],
        "next_steps": ["/workflow:execute"]
      },
      "source": "../../../commands/workflow/action-plan-verify.md"
    },
    {
      "name": "init",
      "command": "/workflow:init",
      "description": "Initialize project-level state",
      "arguments": "[--regenerate]",
      "category": "workflow",
      "difficulty": "Intermediate",
      "source": "../../../commands/workflow/init.md"
    },
    {
      "name": "clean",
      "command": "/workflow:clean",
      "description": "Intelligent code cleanup with stale artifact discovery",
      "arguments": "[--dry-run] [\"focus\"]",
      "category": "workflow",
      "difficulty": "Intermediate",
      "source": "../../../commands/workflow/clean.md"
    },
    {
      "name": "debug",
      "command": "/workflow:debug",
      "description": "Hypothesis-driven debugging with NDJSON logging",
      "arguments": "\"bug description\"",
      "category": "workflow",
      "difficulty": "Intermediate",
      "source": "../../../commands/workflow/debug.md"
    },
    {
      "name": "replan",
      "command": "/workflow:replan",
      "description": "Interactive workflow replanning",
      "arguments": "[--session id] [task-id] \"requirements\"",
      "category": "workflow",
      "difficulty": "Intermediate",
      "source": "../../../commands/workflow/replan.md"
    },
    {
      "name": "session:start",
      "command": "/workflow:session:start",
      "description": "Start or discover workflow sessions",
      "arguments": "[--type <workflow|review|tdd>] [--auto|--new]",
      "category": "workflow",
      "subcategory": "session",
      "difficulty": "Intermediate",
      "essential": true,
      "flow": {
        "next_steps": ["/workflow:plan", "/workflow:execute"]
      },
      "source": "../../../commands/workflow/session/start.md"
    },
    {
      "name": "session:list",
      "command": "/workflow:session:list",
      "description": "List all workflow sessions",
      "arguments": "",
      "category": "workflow",
      "subcategory": "session",
      "difficulty": "Beginner",
      "source": "../../../commands/workflow/session/list.md"
    },
    {
      "name": "session:resume",
      "command": "/workflow:session:resume",
      "description": "Resume paused workflow session",
      "arguments": "",
      "category": "workflow",
      "subcategory": "session",
      "difficulty": "Intermediate",
      "source": "../../../commands/workflow/session/resume.md"
    },
    {
      "name": "session:complete",
      "command": "/workflow:session:complete",
      "description": "Mark session complete and archive",
      "arguments": "",
      "category": "workflow",
      "subcategory": "session",
      "difficulty": "Intermediate",
      "source": "../../../commands/workflow/session/complete.md"
    },
    {
      "name": "brainstorm:auto-parallel",
      "command": "/workflow:brainstorm:auto-parallel",
      "description": "Parallel brainstorming with multi-role analysis",
      "arguments": "\"topic\" [--count N]",
      "category": "workflow",
      "subcategory": "brainstorm",
      "difficulty": "Advanced",
      "source": "../../../commands/workflow/brainstorm/auto-parallel.md"
    },
    {
      "name": "brainstorm:artifacts",
      "command": "/workflow:brainstorm:artifacts",
      "description": "Interactive clarification with guidance specification",
      "arguments": "\"topic\" [--count N]",
      "category": "workflow",
      "subcategory": "brainstorm",
      "difficulty": "Intermediate",
      "essential": true,
      "source": "../../../commands/workflow/brainstorm/artifacts.md"
    },
    {
      "name": "brainstorm:synthesis",
      "command": "/workflow:brainstorm:synthesis",
      "description": "Refine role analyses through Q&A",
      "arguments": "[--session session-id]",
      "category": "workflow",
      "subcategory": "brainstorm",
      "difficulty": "Advanced",
      "source": "../../../commands/workflow/brainstorm/synthesis.md"
    },
    {
      "name": "tdd-plan",
      "command": "/workflow:tdd-plan",
      "description": "TDD planning with Red-Green-Refactor cycles",
      "arguments": "\"feature\"|file.md",
      "category": "workflow",
      "difficulty": "Advanced",
      "flow": {
        "next_steps": ["/workflow:execute", "/workflow:tdd-verify"],
        "alternatives": ["/workflow:plan"]
      },
      "source": "../../../commands/workflow/tdd-plan.md"
    },
    {
      "name": "tdd-verify",
      "command": "/workflow:tdd-verify",
      "description": "Verify TDD compliance with coverage analysis",
      "arguments": "[session-id]",
      "category": "workflow",
      "difficulty": "Advanced",
      "flow": {
        "prerequisites": ["/workflow:execute"]
      },
      "source": "../../../commands/workflow/tdd-verify.md"
    },
    {
      "name": "review",
      "command": "/workflow:review",
      "description": "Post-implementation review (security/architecture/quality)",
      "arguments": "[--type=<type>] [session-id]",
      "category": "workflow",
      "difficulty": "Intermediate",
      "source": "../../../commands/workflow/review.md"
    },
    {
      "name": "review-session-cycle",
      "command": "/workflow:review-session-cycle",
      "description": "Multi-dimensional code review across 7 dimensions",
      "arguments": "[session-id] [--dimensions=...]",
      "category": "workflow",
      "difficulty": "Intermediate",
      "essential": true,
      "flow": {
        "prerequisites": ["/workflow:execute"],
        "next_steps": ["/workflow:review-fix"]
      },
      "source": "../../../commands/workflow/review-session-cycle.md"
    },
    {
      "name": "review-module-cycle",
      "command": "/workflow:review-module-cycle",
      "description": "Module-based multi-dimensional review",
      "arguments": "<path-pattern> [--dimensions=...]",
      "category": "workflow",
      "difficulty": "Intermediate",
      "source": "../../../commands/workflow/review-module-cycle.md"
    },
    {
      "name": "review-fix",
      "command": "/workflow:review-fix",
      "description": "Automated fixing of review findings",
      "arguments": "<export-file|review-dir>",
      "category": "workflow",
      "difficulty": "Intermediate",
      "flow": {
        "prerequisites": ["/workflow:review-session-cycle", "/workflow:review-module-cycle"]
      },
      "source": "../../../commands/workflow/review-fix.md"
    },
    {
      "name": "test-gen",
      "command": "/workflow:test-gen",
      "description": "Generate test session from implementation",
      "arguments": "source-session-id",
      "category": "workflow",
      "difficulty": "Intermediate",
      "source": "../../../commands/workflow/test-gen.md"
    },
    {
      "name": "test-fix-gen",
      "command": "/workflow:test-fix-gen",
      "description": "Create test-fix session with strategy",
      "arguments": "session-id|\"description\"|file",
      "category": "workflow",
      "difficulty": "Intermediate",
      "source": "../../../commands/workflow/test-fix-gen.md"
    },
    {
      "name": "test-cycle-execute",
      "command": "/workflow:test-cycle-execute",
      "description": "Execute test-fix with iterative cycles",
      "arguments": "[--resume-session=id] [--max-iterations=N]",
      "category": "workflow",
      "difficulty": "Intermediate",
      "source": "../../../commands/workflow/test-cycle-execute.md"
    },
    {
      "name": "issue:new",
      "command": "/issue:new",
      "description": "Create issue from GitHub URL or text",
      "arguments": "<url|text> [--priority 1-5]",
      "category": "issue",
      "difficulty": "Intermediate",
      "source": "../../../commands/issue/new.md"
    },
    {
      "name": "issue:discover",
      "command": "/issue:discover",
      "description": "Discover issues from multiple perspectives",
      "arguments": "<path> [--perspectives=...]",
      "category": "issue",
      "difficulty": "Intermediate",
      "source": "../../../commands/issue/discover.md"
    },
    {
      "name": "issue:plan",
      "command": "/issue:plan",
      "description": "Batch plan issue resolution",
      "arguments": "--all-pending|<ids>",
      "category": "issue",
      "difficulty": "Intermediate",
      "flow": {
        "next_steps": ["/issue:queue"]
      },
      "source": "../../../commands/issue/plan.md"
    },
    {
      "name": "issue:queue",
      "command": "/issue:queue",
      "description": "Form execution queue from solutions",
      "arguments": "[--rebuild]",
      "category": "issue",
      "difficulty": "Intermediate",
      "flow": {
        "prerequisites": ["/issue:plan"],
        "next_steps": ["/issue:execute"]
      },
      "source": "../../../commands/issue/queue.md"
    },
    {
      "name": "issue:execute",
      "command": "/issue:execute",
      "description": "Execute queue with DAG parallel",
      "arguments": "[--worktree]",
      "category": "issue",
      "difficulty": "Intermediate",
      "flow": {
        "prerequisites": ["/issue:queue"]
      },
      "source": "../../../commands/issue/execute.md"
    },
    {
      "name": "docs",
      "command": "/memory:docs",
      "description": "Plan documentation workflow",
      "arguments": "[path] [--tool <tool>]",
      "category": "memory",
      "difficulty": "Intermediate",
      "essential": true,
      "flow": {
        "next_steps": ["/workflow:execute"]
      },
      "source": "../../../commands/memory/docs.md"
    },
    {
      "name": "update-related",
      "command": "/memory:update-related",
      "description": "Update docs for git-changed modules",
      "arguments": "[--tool <tool>]",
      "category": "memory",
      "difficulty": "Intermediate",
      "source": "../../../commands/memory/update-related.md"
    },
    {
      "name": "update-full",
      "command": "/memory:update-full",
      "description": "Update all CLAUDE.md files",
      "arguments": "[--tool <tool>]",
      "category": "memory",
      "difficulty": "Intermediate",
      "source": "../../../commands/memory/update-full.md"
    },
    {
      "name": "skill-memory",
      "command": "/memory:skill-memory",
      "description": "Generate SKILL.md with loading index",
      "arguments": "[path] [--regenerate]",
      "category": "memory",
      "difficulty": "Intermediate",
      "source": "../../../commands/memory/skill-memory.md"
    },
    {
      "name": "load-skill-memory",
      "command": "/memory:load-skill-memory",
      "description": "Activate SKILL package for task",
      "arguments": "[skill_name] \"task intent\"",
      "category": "memory",
      "difficulty": "Intermediate",
      "source": "../../../commands/memory/load-skill-memory.md"
    },
    {
      "name": "load",
      "command": "/memory:load",
      "description": "Load project context via CLI",
      "arguments": "[--tool <tool>] \"context\"",
      "category": "memory",
      "difficulty": "Intermediate",
      "source": "../../../commands/memory/load.md"
    },
    {
      "name": "compact",
      "command": "/memory:compact",
      "description": "Compact session memory for recovery",
      "arguments": "[description]",
      "category": "memory",
      "difficulty": "Intermediate",
      "source": "../../../commands/memory/compact.md"
    },
    {
      "name": "task:create",
      "command": "/task:create",
      "description": "Generate task JSON from description",
      "arguments": "\"task title\"",
      "category": "task",
      "difficulty": "Intermediate",
      "source": "../../../commands/task/create.md"
    },
    {
      "name": "task:execute",
      "command": "/task:execute",
      "description": "Execute task JSON with agent",
      "arguments": "task-id",
      "category": "task",
      "difficulty": "Intermediate",
      "source": "../../../commands/task/execute.md"
    },
    {
      "name": "task:breakdown",
      "command": "/task:breakdown",
      "description": "Decompose task into subtasks",
      "arguments": "task-id",
      "category": "task",
      "difficulty": "Intermediate",
      "source": "../../../commands/task/breakdown.md"
    },
    {
      "name": "task:replan",
      "command": "/task:replan",
      "description": "Update task with new requirements",
      "arguments": "task-id [\"text\"|file]",
      "category": "task",
      "difficulty": "Intermediate",
      "source": "../../../commands/task/replan.md"
    },
    {
      "name": "version",
      "command": "/version",
      "description": "Display version and check updates",
      "arguments": "",
      "category": "general",
      "difficulty": "Beginner",
      "essential": true,
      "source": "../../../commands/version.md"
    },
    {
      "name": "enhance-prompt",
      "command": "/enhance-prompt",
      "description": "Transform prompts with session memory",
      "arguments": "user input",
      "category": "general",
      "difficulty": "Intermediate",
      "source": "../../../commands/enhance-prompt.md"
    },
    {
      "name": "cli-init",
      "command": "/cli:cli-init",
      "description": "Initialize CLI tool configurations (.gemini/, .qwen/) with technology-aware ignore rules",
      "arguments": "[--tool gemini|qwen|all] [--preview] [--output path]",
      "category": "cli",
      "difficulty": "Intermediate",
      "source": "../../../commands/cli/cli-init.md"
    }
  ],

  "agents": [
    { "name": "action-planning-agent", "description": "Task planning and generation", "source": "../../../agents/action-planning-agent.md" },
    { "name": "cli-execution-agent", "description": "CLI tool execution", "source": "../../../agents/cli-execution-agent.md" },
    { "name": "cli-explore-agent", "description": "Codebase exploration", "source": "../../../agents/cli-explore-agent.md" },
    { "name": "cli-lite-planning-agent", "description": "Lightweight planning", "source": "../../../agents/cli-lite-planning-agent.md" },
    { "name": "cli-planning-agent", "description": "CLI-based planning", "source": "../../../agents/cli-planning-agent.md" },
    { "name": "code-developer", "description": "Code implementation", "source": "../../../agents/code-developer.md" },
    { "name": "conceptual-planning-agent", "description": "Conceptual analysis", "source": "../../../agents/conceptual-planning-agent.md" },
    { "name": "context-search-agent", "description": "Context discovery", "source": "../../../agents/context-search-agent.md" },
    { "name": "doc-generator", "description": "Documentation generation", "source": "../../../agents/doc-generator.md" },
    { "name": "issue-plan-agent", "description": "Issue planning", "source": "../../../agents/issue-plan-agent.md" },
    { "name": "issue-queue-agent", "description": "Issue queue formation", "source": "../../../agents/issue-queue-agent.md" },
    { "name": "memory-bridge", "description": "Documentation coordination", "source": "../../../agents/memory-bridge.md" },
    { "name": "test-context-search-agent", "description": "Test context collection", "source": "../../../agents/test-context-search-agent.md" },
    { "name": "test-fix-agent", "description": "Test execution and fixing", "source": "../../../agents/test-fix-agent.md" },
    { "name": "ui-design-agent", "description": "UI design and prototyping", "source": "../../../agents/ui-design-agent.md" },
    { "name": "universal-executor", "description": "Universal task execution", "source": "../../../agents/universal-executor.md" }
  ],

  "categories": ["workflow", "issue", "memory", "task", "general", "cli"]
}

```

### scripts/analyze_commands.py

```python
#!/usr/bin/env python3
"""
Analyze all command/agent files and generate index files for ccw-help skill.
Outputs relative paths pointing to source files (no reference folder duplication).
"""

import os
import re
import json
from pathlib import Path
from collections import defaultdict
from typing import Dict, List, Any

# Base paths
BASE_DIR = Path("D:/Claude_dms3/.claude")
COMMANDS_DIR = BASE_DIR / "commands"
AGENTS_DIR = BASE_DIR / "agents"
SKILL_DIR = BASE_DIR / "skills" / "ccw-help"
INDEX_DIR = SKILL_DIR / "index"

def parse_frontmatter(content: str) -> Dict[str, Any]:
    """Extract YAML frontmatter from markdown content."""
    frontmatter = {}
    if content.startswith('---'):
        lines = content.split('\n')
        for i, line in enumerate(lines[1:], 1):
            if line.strip() == '---':
                break
            if ':' in line:
                key, value = line.split(':', 1)
                frontmatter[key.strip()] = value.strip().strip('"')
    return frontmatter

def categorize_command(file_path: Path) -> tuple:
    """Determine category and subcategory from file path."""
    parts = file_path.relative_to(COMMANDS_DIR).parts

    if len(parts) == 1:
        return "general", None

    category = parts[0]  # cli, memory, task, workflow
    subcategory = parts[1].replace('.md', '') if len(parts) > 2 else None

    return category, subcategory

def determine_usage_scenario(name: str, description: str, category: str) -> str:
    """Determine primary usage scenario for command."""
    name_lower = name.lower()

    if any(word in name_lower for word in ['plan', 'design', 'breakdown', 'brainstorm']):
        return "planning"
    if any(word in name_lower for word in ['implement', 'execute', 'generate', 'create', 'write']):
        return "implementation"
    if any(word in name_lower for word in ['test', 'tdd', 'verify', 'coverage']):
        return "testing"
    if any(word in name_lower for word in ['docs', 'documentation', 'memory']):
        return "documentation"
    if any(word in name_lower for word in ['session', 'resume', 'status', 'complete']):
        return "session-management"
    if any(word in name_lower for word in ['analyze', 'review', 'diagnosis']):
        return "analysis"
    return "general"

def determine_difficulty(name: str, description: str, category: str) -> str:
    """Determine difficulty level."""
    name_lower = name.lower()

    beginner_keywords = ['status', 'list', 'chat', 'analyze', 'version']
    if any(word in name_lower for word in beginner_keywords):
        return "Beginner"

    advanced_keywords = ['tdd', 'conflict', 'agent', 'auto-parallel', 'coverage', 'synthesis']
    if any(word in name_lower for word in advanced_keywords):
        return "Advanced"

    return "Intermediate"

def analyze_command_file(file_path: Path) -> Dict[str, Any]:
    """Analyze a single command file and extract metadata."""
    with open(file_path, 'r', encoding='utf-8') as f:
        content = f.read()

    frontmatter = parse_frontmatter(content)

    name = frontmatter.get('name', file_path.stem)
    description = frontmatter.get('description', '')
    argument_hint = frontmatter.get('argument-hint', '')

    category, subcategory = categorize_command(file_path)
    usage_scenario = determine_usage_scenario(name, description, category)
    difficulty = determine_difficulty(name, description, category)

    # Build relative path from INDEX_DIR (need to go up 3 levels: index -> ccw-help -> skills -> .claude)
    # e.g., "../../../commands/workflow/lite-plan.md"
    rel_from_base = file_path.relative_to(BASE_DIR)
    rel_path = "../../../" + str(rel_from_base).replace('\\', '/')

    # Build full command name
    if ':' in name:
        command_name = f"/{name}"
    elif category == "general":
        command_name = f"/{name}"
    else:
        if subcategory:
            command_name = f"/{category}:{subcategory}:{name}"
        else:
            command_name = f"/{category}:{name}"

    return {
        "name": name,
        "command": command_name,
        "description": description,
        "arguments": argument_hint,
        "category": category,
        "subcategory": subcategory,
        "usage_scenario": usage_scenario,
        "difficulty": difficulty,
        "source": rel_path  # Relative from index/ dir (e.g., "../../../commands/workflow/...")
    }

def analyze_agent_file(file_path: Path) -> Dict[str, Any]:
    """Analyze a single agent file and extract metadata."""
    with open(file_path, 'r', encoding='utf-8') as f:
        content = f.read()

    frontmatter = parse_frontmatter(content)

    name = frontmatter.get('name', file_path.stem)
    description = frontmatter.get('description', '')

    # Build relative path from INDEX_DIR (need to go up 3 levels)
    # e.g., "../../../agents/code-developer.md"
    rel_from_base = file_path.relative_to(BASE_DIR)
    rel_path = "../../../" + str(rel_from_base).replace('\\', '/')

    return {
        "name": name,
        "description": description,
        "source": rel_path  # Relative from index/ dir (e.g., "../../../agents/...")
    }

def build_command_relationships() -> Dict[str, Any]:
    """Build command relationship mappings."""
    return {
        "workflow:plan": {
            "calls_internally": ["workflow:session:start", "workflow:tools:context-gather", "workflow:tools:conflict-resolution", "workflow:tools:task-generate-agent"],
            "next_steps": ["workflow:action-plan-verify", "workflow:status", "workflow:execute"],
            "alternatives": ["workflow:tdd-plan"],
            "prerequisites": []
        },
        "workflow:tdd-plan": {
            "calls_internally": ["workflow:session:start", "workflow:tools:context-gather", "workflow:tools:task-generate-tdd"],
            "next_steps": ["workflow:tdd-verify", "workflow:status", "workflow:execute"],
            "alternatives": ["workflow:plan"],
            "prerequisites": []
        },
        "workflow:execute": {
            "prerequisites": ["workflow:plan", "workflow:tdd-plan"],
            "related": ["workflow:status", "workflow:resume"],
            "next_steps": ["workflow:review", "workflow:tdd-verify"]
        },
        "workflow:action-plan-verify": {
            "prerequisites": ["workflow:plan"],
            "next_steps": ["workflow:execute"],
            "related": ["workflow:status"]
        },
        "workflow:tdd-verify": {
            "prerequisites": ["workflow:execute"],
            "related": ["workflow:tools:tdd-coverage-analysis"]
        },
        "workflow:session:start": {
            "next_steps": ["workflow:plan", "workflow:execute"],
            "related": ["workflow:session:list", "workflow:session:resume"]
        },
        "workflow:session:resume": {
            "alternatives": ["workflow:resume"],
            "related": ["workflow:session:list", "workflow:status"]
        },
        "workflow:lite-plan": {
            "calls_internally": ["workflow:lite-execute"],
            "next_steps": ["workflow:lite-execute", "workflow:status"],
            "alternatives": ["workflow:plan"],
            "prerequisites": []
        },
        "workflow:lite-fix": {
            "next_steps": ["workflow:lite-execute", "workflow:status"],
            "alternatives": ["workflow:lite-plan"],
            "related": ["workflow:test-cycle-execute"]
        },
        "workflow:lite-execute": {
            "prerequisites": ["workflow:lite-plan", "workflow:lite-fix"],
            "related": ["workflow:execute", "workflow:status"]
        },
        "workflow:review-session-cycle": {
            "prerequisites": ["workflow:execute"],
            "next_steps": ["workflow:review-fix"],
            "related": ["workflow:review-module-cycle"]
        },
        "workflow:review-fix": {
            "prerequisites": ["workflow:review-module-cycle", "workflow:review-session-cycle"],
            "related": ["workflow:test-cycle-execute"]
        },
        "memory:docs": {
            "calls_internally": ["workflow:session:start", "workflow:tools:context-gather"],
            "next_steps": ["workflow:execute"]
        },
        "memory:skill-memory": {
            "next_steps": ["workflow:plan", "cli:analyze"],
            "related": ["memory:load-skill-memory"]
        }
    }

def identify_essential_commands(all_commands: List[Dict]) -> List[Dict]:
    """Identify the most essential commands for beginners."""
    essential_names = [
        "workflow:lite-plan", "workflow:lite-fix", "workflow:plan",
        "workflow:execute", "workflow:status", "workflow:session:start",
        "workflow:review-session-cycle", "cli:analyze", "cli:chat",
        "memory:docs", "workflow:brainstorm:artifacts",
        "workflow:action-plan-verify", "workflow:resume", "version"
    ]

    essential = []
    for cmd in all_commands:
        cmd_name = cmd['command'].lstrip('/')
        if cmd_name in essential_names:
            essential.append(cmd)

    essential.sort(key=lambda x: essential_names.index(x['command'].lstrip('/')) if x['command'].lstrip('/') in essential_names else 999)
    return essential[:14]

def main():
    """Main analysis function."""
    import sys
    import io

    if sys.platform == 'win32':
        sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')

    print("=== CCW-Help Index Rebuild ===\n")

    # Analyze command files
    print("=== Analyzing Command Files ===")
    command_files = list(COMMANDS_DIR.rglob("*.md"))
    print(f"Found {len(command_files)} command files")

    all_commands = []
    for cmd_file in sorted(command_files):
        try:
            metadata = analyze_command_file(cmd_file)
            all_commands.append(metadata)
            print(f"  OK {metadata['command']}")
        except Exception as e:
            print(f"  ERROR analyzing {cmd_file}: {e}")

    # Analyze agent files
    print("\n=== Analyzing Agent Files ===")
    agent_files = list(AGENTS_DIR.rglob("*.md"))
    print(f"Found {len(agent_files)} agent files")

    all_agents = []
    for agent_file in sorted(agent_files):
        try:
            metadata = analyze_agent_file(agent_file)
            all_agents.append(metadata)
            print(f"  OK {metadata['name']}")
        except Exception as e:
            print(f"  ERROR analyzing {agent_file}: {e}")

    print(f"\nAnalyzed {len(all_commands)} commands, {len(all_agents)} agents")

    # Generate index files
    INDEX_DIR.mkdir(parents=True, exist_ok=True)

    # 1. all-commands.json
    all_commands_path = INDEX_DIR / "all-commands.json"
    with open(all_commands_path, 'w', encoding='utf-8') as f:
        json.dump(all_commands, f, indent=2, ensure_ascii=False)
    print(f"\nOK Generated {all_commands_path.name} ({os.path.getsize(all_commands_path)} bytes)")

    # 2. all-agents.json
    all_agents_path = INDEX_DIR / "all-agents.json"
    with open(all_agents_path, 'w', encoding='utf-8') as f:
        json.dump(all_agents, f, indent=2, ensure_ascii=False)
    print(f"OK Generated {all_agents_path.name} ({os.path.getsize(all_agents_path)} bytes)")

    # 3. by-category.json
    by_category = defaultdict(lambda: defaultdict(list))
    for cmd in all_commands:
        cat = cmd['category']
        subcat = cmd['subcategory'] or '_root'
        by_category[cat][subcat].append(cmd)

    by_category_path = INDEX_DIR / "by-category.json"
    with open(by_category_path, 'w', encoding='utf-8') as f:
        json.dump(dict(by_category), f, indent=2, ensure_ascii=False)
    print(f"OK Generated {by_category_path.name} ({os.path.getsize(by_category_path)} bytes)")

    # 4. by-use-case.json
    by_use_case = defaultdict(list)
    for cmd in all_commands:
        by_use_case[cmd['usage_scenario']].append(cmd)

    by_use_case_path = INDEX_DIR / "by-use-case.json"
    with open(by_use_case_path, 'w', encoding='utf-8') as f:
        json.dump(dict(by_use_case), f, indent=2, ensure_ascii=False)
    print(f"OK Generated {by_use_case_path.name} ({os.path.getsize(by_use_case_path)} bytes)")

    # 5. essential-commands.json
    essential = identify_essential_commands(all_commands)
    essential_path = INDEX_DIR / "essential-commands.json"
    with open(essential_path, 'w', encoding='utf-8') as f:
        json.dump(essential, f, indent=2, ensure_ascii=False)
    print(f"OK Generated {essential_path.name} ({os.path.getsize(essential_path)} bytes)")

    # 6. command-relationships.json
    relationships = build_command_relationships()
    relationships_path = INDEX_DIR / "command-relationships.json"
    with open(relationships_path, 'w', encoding='utf-8') as f:
        json.dump(relationships, f, indent=2, ensure_ascii=False)
    print(f"OK Generated {relationships_path.name} ({os.path.getsize(relationships_path)} bytes)")

    # Print summary
    print("\n=== Summary ===")
    print(f"Commands: {len(all_commands)}")
    print(f"Agents: {len(all_agents)}")
    print(f"Essential: {len(essential)}")
    print(f"\nBy category:")
    for cat in sorted(by_category.keys()):
        total = sum(len(cmds) for cmds in by_category[cat].values())
        print(f"  {cat}: {total}")

    print(f"\nIndex: {INDEX_DIR}")
    print("=== Complete ===")

if __name__ == '__main__':
    main()

```