gh-duongdev-ccpm/commands/utils:organize-docs.md

---
description: Organize repository documentation following CCPM pattern
allowed-tools: [Bash, Read, Write, Edit, Glob, AskUserQuestion]
argument-hint: [repo-path] [--dry-run] [--global]
---

# Organize Documentation

Reorganizes repository documentation following the CCPM documentation pattern for clean, navigable, and scalable documentation structure.

## Arguments

- **$1** - (Optional) Repository path (default: current directory)
- **$2** - (Optional) `--dry-run` to preview changes without applying
- **$3** - (Optional) `--global` to install pattern globally in `~/.claude/templates/`

## Workflow

### Step 1: Analyze Current Structure

```javascript
const repoPath = $1 || process.cwd()
const dryRun = args.includes('--dry-run')
const installGlobal = args.includes('--global')

// Analyze current documentation
const analysis = {
  rootMarkdownFiles: findMarkdownFiles(repoPath, { maxDepth: 1 }),
  existingDocsDir: dirExists(`${repoPath}/docs`),
  categories: {
    guides: [],
    reference: [],
    architecture: [],
    research: []
  }
}

// Categorize files
analysis.rootMarkdownFiles.forEach(file => {
  const category = categorizeFi le(file)
  if (category) {
    analysis.categories[category].push(file)
  }
})
```

Display analysis:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Documentation Analysis
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Repository: ${basename(repoPath)}
Path: ${repoPath}

📄 Found ${analysis.rootMarkdownFiles.length} markdown files in root

${analysis.rootMarkdownFiles.length > 5 ? '⚠️  Too many files in root (>5)' : '✅ Root is clean (≤5 files)'}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### Step 2: Categorize Files

Categorization rules:

```javascript
function categorizeFile(filename) {
  // Keep in root
  const keepInRoot = [
    'README.md',
    'CHANGELOG.md',
    'CONTRIBUTING.md',
    'LICENSE.md',
    'LICENSE',
    'CLAUDE.md',
    'MIGRATION.md'
  ]

  if (keepInRoot.includes(filename)) {
    return 'root'
  }

  // Guides (user-facing how-to)
  if (filename.match(/GUIDE|INSTALL|SETUP|WORKFLOW|TUTORIAL/i)) {
    return 'guides'
  }

  // Reference (API, catalog, reference)
  if (filename.match(/CATALOG|REFERENCE|API|COMMANDS/i)) {
    return 'reference'
  }

  // Architecture
  if (filename.match(/ARCHITECTURE|DESIGN/i)) {
    return 'architecture'
  }

  // Research (historical planning)
  if (filename.match(/RESEARCH|PLAN|PROPOSAL|STATUS|SUMMARY|COMPARISON|MATRIX|QUICK.?REFERENCE/i)) {
    return 'research'
  }

  return null // Unknown, ask user
}
```

Display categorization:

```
📦 Proposed File Organization
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Keep in Root (${analysis.categories.root?.length || 0}):
${analysis.categories.root?.map(f => `  - ${f}`).join('\n') || '  (none)'}

📘 Move to docs/guides/ (${analysis.categories.guides.length}):
${analysis.categories.guides.map(f => `  - ${f} → docs/guides/${kebabCase(f)}`).join('\n') || '  (none)'}

📖 Move to docs/reference/ (${analysis.categories.reference.length}):
${analysis.categories.reference.map(f => `  - ${f} → docs/reference/${kebabCase(f)}`).join('\n') || '  (none)'}

🏗️ Move to docs/architecture/ (${analysis.categories.architecture.length}):
${analysis.categories.architecture.map(f => `  - ${f} → docs/architecture/${kebabCase(f)}`).join('\n') || '  (none)'}

📚 Move to docs/research/ (${analysis.categories.research.length}):
${analysis.categories.research.map(f => `  - ${f} → docs/research/${categorizeTopic(f)}/${kebabCase(f)}`).join('\n') || '  (none)'}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### Step 3: Ask for Confirmation

Use AskUserQuestion for files with unclear categorization:

```javascript
{
  questions: [{
    question: "Some files need categorization. Where should these go?",
    header: "Categorize",
    multiSelect: false,
    options: [
      {
        label: "Apply Auto-Categorization",
        description: "Use CCPM pattern rules for all files"
      },
      {
        label: "Review Each File",
        description: "I'll categorize unclear files manually"
      },
      {
        label: "Cancel",
        description: "Don't reorganize"
      }
    ]
  }]
}
```

If "Review Each File" selected, ask for each unclear file:

```javascript
{
  questions: [{
    question: `Where should ${filename} go?`,
    header: "Categorize File",
    multiSelect: false,
    options: [
      { label: "Keep in Root", description: "Important user-facing file" },
      { label: "docs/guides/", description: "User how-to guide" },
      { label: "docs/reference/", description: "API or feature reference" },
      { label: "docs/architecture/", description: "Design decision" },
      { label: "docs/research/", description: "Historical planning (archive)" },
      { label: "Skip", description: "Don't move this file" }
    ]
  }]
}
```

### Step 4: Apply Changes

If `--dry-run`:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 DRY RUN - No changes will be made
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Would perform these operations:

📁 Create directories:
  ✓ docs/guides/
  ✓ docs/reference/
  ✓ docs/architecture/decisions/
  ✓ docs/development/
  ✓ docs/research/

📦 Move files (${totalMoves}):
  ${moves.map(m => `  ${m.from} → ${m.to}`).join('\n')}

📄 Create index files (6):
  ✓ docs/README.md
  ✓ docs/guides/README.md
  ✓ docs/reference/README.md
  ✓ docs/architecture/README.md
  ✓ docs/development/README.md
  ✓ docs/research/README.md

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Run without --dry-run to apply changes.
```

If not dry-run, execute:

```bash
#!/bin/bash
set -e

cd "${repoPath}"

# Phase 1: Create directory structure
echo "📁 Creating directory structure..."
mkdir -p docs/{guides,reference,architecture/decisions,development,research}

# Phase 2: Move files
echo "📦 Moving files..."
${moves.map(m => `
if [ -f "${m.from}" ]; then
  mv "${m.from}" "${m.to}"
  echo "  ✓ ${m.from} → ${m.to}"
fi`).join('\n')}

# Phase 3: Create index files
echo "📄 Creating index files..."
# [Generate index file content using templates]

echo "✅ Documentation reorganization complete!"
```

### Step 5: Create Index Files

Use CCPM templates for all index files:

**docs/README.md**:
```markdown
# [Project] Documentation

Welcome to the [Project] documentation.

## Quick Links

- **[Quick Start](guides/quick-start.md)** - Get started in 5 minutes
- **[Installation](guides/installation.md)** - Detailed setup
- **[Reference](reference/)** - Complete documentation

## Documentation Structure

### 📘 [Guides](guides/) - How-to guides
- [Quick Start](guides/quick-start.md)
- [Installation](guides/installation.md)

### 📖 [Reference](reference/) - API & feature reference
- [API](reference/api.md)
- [Configuration](reference/config.md)

### 🏗️ [Architecture](architecture/) - Design decisions
- [Overview](architecture/overview.md)
- [Decisions](architecture/decisions/)

### 🔧 [Development](development/) - For contributors
- [Setup](development/setup.md)
- [Testing](development/testing.md)

### 📚 [Research](research/) - Historical context
Archived research and planning documents.

## Contributing

See [CONTRIBUTING.md](../CONTRIBUTING.md).
```

**docs/guides/README.md**:
```markdown
# User Guides

How-to guides for using [Project].

## Getting Started

- [Quick Start](quick-start.md) - 5-minute introduction
- [Installation](installation.md) - Detailed installation

## Features

[Auto-generated list of guides]

## Need Help?

See the main [Documentation Index](../README.md).
```

**docs/research/README.md**:
```markdown
# Research & Planning Documents

**Archived historical documents** - For current docs, see main [Documentation](../README.md).

## Purpose

These documents explain why decisions were made and how features were researched.

**Note**: May be outdated - refer to main docs for current state.

## Contents

[Auto-generated list of research topics]
```

### Step 6: Update Links

Scan all moved files for internal links and update them:

```javascript
// Find all markdown links
const linkPattern = /\[([^\]]+)\]\(([^)]+)\)/g

movedFiles.forEach(file => {
  let content = readFile(file.newPath)
  let updated = false

  content = content.replace(linkPattern, (match, text, url) => {
    if (url.startsWith('http')) return match // External link

    // Calculate new relative path
    const oldPath = resolvePath(file.oldPath, url)
    const newPath = calculateRelativePath(file.newPath, oldPath)

    if (newPath !== url) {
      updated = true
      return `[${text}](${newPath})`
    }

    return match
  })

  if (updated) {
    writeFile(file.newPath, content)
  }
})
```

Display link updates:

```
🔗 Updating Internal Links
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Updated links in ${updatedFiles.length} files:
${updatedFiles.map(f => `  ✓ ${f.path} (${f.linksUpdated} links)`).join('\n')}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### Step 7: Update CLAUDE.md

If CLAUDE.md exists, add documentation pattern section:

```javascript
const claudeMdPath = `${repoPath}/CLAUDE.md`

if (fileExists(claudeMdPath)) {
  const claudeMd = readFile(claudeMdPath)

  // Check if documentation section already exists
  if (!claudeMd.includes('## Documentation Structure') && !claudeMd.includes('## Documentation Pattern')) {
    const documentationSection = generateDocumentationSection(analysis)

    // Append to CLAUDE.md
    appendToFile(claudeMdPath, `\n\n${documentationSection}`)
  } else {
    // Update existing section
    updateDocumentationSection(claudeMdPath, analysis)
  }
}
```

Documentation section template:

```markdown
## Documentation Structure

This repository follows the CCPM documentation pattern for clean, navigable, and scalable documentation.

### Pattern Overview

```
docs/
├── README.md               # Documentation navigation hub
├── guides/                 # 📘 User how-to guides
├── reference/              # 📖 API & feature reference
├── architecture/           # 🏗️ Design decisions & ADRs
├── development/            # 🔧 Contributor documentation
└── research/               # 📚 Historical context (archived)
```

### Documentation Guidelines

**When creating new documentation:**

1. **User guides** → `docs/guides/`
   - Installation, setup, configuration
   - Feature walkthroughs and tutorials
   - Troubleshooting guides
   - Use descriptive filenames: `installation.md`, `quick-start.md`

2. **Reference documentation** → `docs/reference/`
   - API documentation
   - Command/feature catalogs
   - Configuration references
   - Technical specifications

3. **Architecture documentation** → `docs/architecture/`
   - System architecture overviews
   - Component designs
   - Architecture Decision Records (ADRs) in `decisions/`
   - Use ADR template for decisions

4. **Development documentation** → `docs/development/`
   - Development environment setup
   - Testing guides
   - Release processes
   - Contribution workflows

5. **Research/Planning documents** → `docs/research/`
   - Historical planning documents
   - Research findings
   - Implementation journeys
   - **Note**: These are archived - current docs go elsewhere

### Root Directory Rules

**Keep ONLY these files in root:**
- `README.md` - Main entry point
- `CHANGELOG.md` - Version history
- `CONTRIBUTING.md` - Contribution guide
- `LICENSE` - License file
- `CLAUDE.md` - This file
- `MIGRATION.md` - Migration guide (if applicable)

**All other documentation goes in `docs/`**

### Index Files

Each documentation directory has a `README.md` that:
- Explains what the directory contains
- Links to all documents in that directory
- Provides navigation back to main docs

### Maintaining Documentation

**When you create or move documentation:**

1. Place it in the appropriate `docs/` subdirectory
2. Update the relevant index `README.md`
3. Update internal links to use correct relative paths
4. Keep root directory clean (≤5 markdown files)

**When you reference documentation:**

1. Use relative links from current location
2. Link to `docs/README.md` for main navigation
3. Link to specific guides/references as needed

### Auto-Organization

To reorganize documentation automatically:

```bash
/ccpm:utils:organize-docs [repo-path] [--dry-run] [--global]
```

This command:
- Analyzes current documentation structure
- Categorizes files using CCPM pattern rules
- Moves files to appropriate locations
- Creates index files
- Updates internal links
- Can be installed globally for use in any repository

### Navigation

All documentation is accessible from `docs/README.md`:
- **Quick Start**: `docs/guides/quick-start.md`
- **Full Documentation**: Browse by category in `docs/`
- **Contributing**: `CONTRIBUTING.md`

### Pattern Benefits

- ✅ Clean root directory
- ✅ Clear separation of concerns
- ✅ Easy to find documentation
- ✅ Scales with project growth
- ✅ Historical context preserved
- ✅ AI assistant friendly
- ✅ Consistent across projects
```

Display update confirmation:

```
📝 Updating CLAUDE.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

${exists ? '✓ Updated documentation structure section' : '✓ Added documentation structure section'}

CLAUDE.md now includes:
  - Documentation pattern overview
  - Guidelines for new documentation
  - Root directory rules
  - Index file conventions
  - Auto-organization instructions
  - Navigation guidelines

This ensures AI assistants always follow the pattern.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### Step 8: Global Installation (if --global)

If `--global` flag is set:

```bash
#!/bin/bash
set -e

echo "🌍 Installing CCPM docs pattern globally..."

# Create global template directory
mkdir -p ~/.claude/templates/ccpm-docs-pattern
mkdir -p ~/.claude/scripts

# Copy pattern documentation
cp GLOBAL_DOCS_PATTERN.md ~/.claude/templates/ccpm-docs-pattern/

# Copy organize script
cp scripts/organize-docs.sh ~/.claude/templates/ccpm-docs-pattern/

# Create global auto-organize script
cat > ~/.claude/scripts/organize-docs << 'SCRIPT'
#!/bin/bash
# Auto-organize documentation for any repository

REPO_PATH="${1:-.}"
cd "$REPO_PATH" || exit 1

# Use CCPM organize command
claude /ccpm:utils:organize-docs "$REPO_PATH"
SCRIPT

chmod +x ~/.claude/scripts/organize-docs

# Add to PATH if not already there
if [[ ":$PATH:" != *":$HOME/.claude/scripts:"* ]]; then
  echo ""
  echo "Add to your shell profile (~/.zshrc or ~/.bashrc):"
  echo "  export PATH=\"\$HOME/.claude/scripts:\$PATH\""
fi

echo "✅ Global installation complete!"
echo ""
echo "Usage in any repository:"
echo "  organize-docs"
echo "  organize-docs /path/to/repo"
echo "  organize-docs --dry-run"
```

### Step 9: Summary

Display completion summary:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎉 Documentation Reorganization Complete!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Summary:
  ✓ Root files: ${before} → ${after} (-${reduction}%)
  ✓ Files moved: ${movedCount}
  ✓ Index files created: 6
  ✓ Links updated: ${linksUpdated}

📁 New Structure:
  docs/
  ├── guides/          (${guidesCount} files)
  ├── reference/       (${referenceCount} files)
  ├── architecture/    (${architectureCount} files)
  ├── development/     (${developmentCount} files)
  └── research/        (${researchCount} files, archived)

📝 Next Steps:
  1. Review changes: git status
  2. Test documentation links
  3. Update README.md with new structure
  ${hasClaude ? '4. ✅ CLAUDE.md updated with documentation pattern' : ''}
  5. Commit changes: git add . && git commit -m "docs: reorganize documentation"

${installGlobal ? `
🌍 Global Pattern Installed:
  Pattern available at: ~/.claude/templates/ccpm-docs-pattern/
  Command available: organize-docs

  Use in any repository:
    cd ~/projects/any-repo
    organize-docs
` : `
💡 Install Globally:
  Run: /ccpm:utils:organize-docs . --global
  Then use 'organize-docs' in any repository
`}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

## Examples

### Example 1: Analyze Current Repository

```bash
/ccpm:utils:organize-docs --dry-run
```

Output:
- Analysis of current structure
- Proposed changes
- No files moved

### Example 2: Reorganize Current Repository

```bash
/ccpm:utils:organize-docs
```

Performs:
1. Analyzes documentation
2. Shows categorization
3. Asks for confirmation
4. Creates docs/ structure
5. Moves files
6. Creates index files
7. Updates links
8. Shows summary

### Example 3: Reorganize Different Repository

```bash
/ccpm:utils:organize-docs ~/projects/my-app
```

Same as Example 2 but for different repository.

### Example 4: Install Global Pattern

```bash
/ccpm:utils:organize-docs . --global
```

Performs:
1. Reorganizes current repository
2. Installs pattern to ~/.claude/templates/
3. Creates global organize-docs script
4. Adds to PATH

Then can use in any repo:
```bash
cd ~/projects/any-repo
organize-docs
```

## File Categorization Rules

### Keep in Root
- README.md - Entry point
- CHANGELOG.md - Version history
- CONTRIBUTING.md - Contribution guide
- LICENSE/LICENSE.md - License
- CLAUDE.md - AI assistant instructions
- MIGRATION.md - Migration guide

### docs/guides/
Files matching: `*GUIDE*`, `*INSTALL*`, `*SETUP*`, `*WORKFLOW*`, `*TUTORIAL*`

Examples:
- INSTALL_HOOKS.md → docs/guides/hooks.md
- MCP_INTEGRATION_GUIDE.md → docs/guides/mcp-integration.md
- UI_WORKFLOW.md → docs/guides/ui-workflow.md

### docs/reference/
Files matching: `*CATALOG*`, `*REFERENCE*`, `*API*`, `*COMMANDS*`

Examples:
- SKILLS_CATALOG.md → docs/reference/skills.md
- API_REFERENCE.md → docs/reference/api.md

### docs/architecture/
Files matching: `*ARCHITECTURE*`, `*DESIGN*`

Examples:
- SKILLS_ARCHITECTURE.md → docs/architecture/skills-system.md
- SYSTEM_DESIGN.md → docs/architecture/overview.md

### docs/research/
Files matching: `*RESEARCH*`, `*PLAN*`, `*PROPOSAL*`, `*STATUS*`, `*SUMMARY*`, `*COMPARISON*`, `*MATRIX*`

Examples:
- SKILLS_INTEGRATION_PLAN.md → docs/research/skills/integration-plan.md
- HOOKS_RESEARCH_SUMMARY.md → docs/research/hooks/research-summary.md

## Notes

- Always creates backup before moving files (git makes this easy)
- Preserves git history for moved files
- Updates internal markdown links automatically
- Creates index files for easy navigation
- **Updates CLAUDE.md** with documentation pattern instructions
- Ensures AI assistants always follow the pattern
- Follows CCPM documentation pattern globally
- Can be used on any repository, not just CCPM
- Dry-run mode for safe preview
- Global installation for reuse across all projects

## Success Metrics

After running this command:
- ✅ Root directory has ≤5 markdown files
- ✅ All docs reachable within 2 clicks from docs/README.md
- ✅ Clear separation: guides/reference/architecture/research
- ✅ Index files guide navigation
- ✅ Historical context preserved in research/
- ✅ Pattern reusable across projects