Reorganize Directory

You are tasked with analyzing a directory structure, identifying clutter and organizational issues, proposing a reorganization plan, and safely executing it with reference updates.

Initial Response

When invoked, check the argument:

If a directory path was provided: validate it exists and is inside a git repo
If no argument: ask the user which directory to reorganize

I'll analyze and reorganize a directory structure.

This command will:
1. Analyze the directory for empty, sparse, and overlapping categories
2. Map cross-references to assess move risk
3. Propose a reorganization plan
4. Execute safely via move-and-rereference.sh after your approval

Which directory should I analyze?

Process

Step 1: Validate Input

# Check directory exists
if [[ ! -d "<directory>" ]]; then
  echo "Error: Directory does not exist: <directory>"
  exit 1
fi

# Check git repo
REPO_ROOT=$(cd "<directory>" && git rev-parse --show-toplevel 2>/dev/null)
if [[ -z "$REPO_ROOT" ]]; then
  echo "Error: Directory is not inside a git repository"
  exit 1
fi

Determine the relative path of the directory within the repo root. All paths in the analysis and mapping should be relative to the repo root.

Step 2: Parallel Analysis

Spawn 3 Task agents simultaneously to analyze the directory.

Task 1 — Structure Analysis (subagent_type: Explore):

Analyze the directory structure of <directory>. For each subdirectory:
1. Count the number of real files (exclude .gitkeep, .DS_Store)
2. Identify empty directories (0 files)
3. Identify sparse directories (1-2 files)
4. Identify large directories (>20 files)
5. Detect naming overlaps (e.g., notes/ vs meeting-notes/, research/ vs other_research/)

Return a structured report with:
- Directory name, file count, and category (empty/sparse/active/large)
- Any detected naming overlaps with specific directory pairs
- Total file count

Task 2 — Cross-Reference Analysis (subagent_type: Explore):

Analyze cross-references within <directory>. Search all .md files for path references to files and
directories within this directory tree:

1. Grep for path patterns that reference sibling files/directories
2. Count inbound references per directory (how many times paths under that dir are referenced)
3. Identify the highest-risk directories to move (most references)

Return:
- Per-directory reference count (sorted by count, descending)
- Total reference count
- Top 5 most-referenced individual files

Task 3 — Content Analysis (subagent_type: Explore):

Sample files from each subdirectory of <directory> (read first 20 lines of up to 3 files per
subdirectory). For each subdirectory:

1. Categorize the content type (research, plans, notes, meetings, analyses, handoffs, etc.)
2. Flag any files that seem miscategorized (e.g., a meeting note in research/)
3. Note if the subdirectory name accurately describes its content

Return:
- Per-directory content summary (directory name, content type, sample file names)
- List of potentially miscategorized files with suggested locations

WAIT for all 3 tasks to complete.

Step 3: Present Findings

Combine the results into a structured report:

## Directory Analysis: <directory>

### Summary
- {N} subdirectories, {M} files
- {X} empty directories (can remove)
- {Y} overlapping categories (can merge)
- {Z} sparse directories (can consolidate)

### Empty (can remove)
- decisions/ (0 files)
- journey-maps/ (0 files)
...

### Overlapping (can merge)
- notes/ ({N} files) + meeting-notes/ ({M} files) → notes/
- other_research/ ({N} files) + research/ ({M} files) → research/
...

### Sparse (can consolidate)
- business/ (1 file) → could merge into notes/ or keep
- learnings/ (1 file) → could merge into notes/ or keep
...

### Large (might benefit from subdirectories)
- research/ ({N} files) — consider subfolders by topic
...

### Cross-Reference Impact
- research/ has {N} inbound references (highest risk — most refs to update)
- plans/ has {N} inbound references
- analyses/ has {N} inbound references
...

### Content Issues
- {file} in {dir}/ appears to be a {type}, consider moving to {suggested_dir}/
...

Step 4: Propose Reorganization

Based on the analysis, generate a reorganization proposal. Present it as a table:

## Proposed Reorganization

| # | Current Path | Proposed Path | Reason | Risk |
|---|---|---|---|---|
| 1 | decisions/ | (remove) | Empty directory | None |
| 2 | other_research/file.md | research/file.md | Merge into research/ | Low (1 ref) |
| 3 | meeting-notes/file.md | notes/meetings/file.md | Consolidate under notes/ | Medium (3 refs) |
| 4 | research-synthesis/file.md | research/synthesis/file.md | Subdir of research/ | Low (1 ref) |
...

### Not Moving (keeping as-is)
- research/ — active, well-organized (73 files)
- plans/ — active, well-organized (36 files)
- handoffs/ — active, well-organized
...

Ask for user feedback:

Does this reorganization look right?

Options:
1. Approve as-is — proceed to dry run
2. Edit — tell me which rows to change
3. Add more — suggest additional moves
4. Cancel — abort without changes

Wait for user response. Iterate on the proposal until approved.

Step 5: Generate Mapping File

Write the approved mappings to a temporary TSV file:

MAPPING_FILE="/tmp/reorganize-$(date +%Y%m%d-%H%M%S).tsv"

Format: old_path<TAB>new_path per line, relative to repo root.

For empty directory removals, note them separately — the script handles file moves, not directory removal.

Step 6: Dry Run

Run the backing script in dry-run mode:

SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
"${SCRIPT_DIR}/move-and-rereference.sh" --dry-run --verbose --root "$REPO_ROOT" "$MAPPING_FILE"

Present the dry-run output to the user. Highlight:

Number of files that will move
Number of references that will be updated
Any files with high reference counts (potential risk)

Ask for final confirmation:

The dry run shows:
- {N} files will be moved
- {M} references will be updated across {K} files

Proceed with execution? (y/N)

Step 7: Execute

After user confirmation:

"${SCRIPT_DIR}/move-and-rereference.sh" --execute --verbose --root "$REPO_ROOT" "$MAPPING_FILE"

Present the execution report.

Step 8: Cleanup

After successful execution:

Remove empty directories left behind:

# Find and remove empty directories (excluding .git)
find "<directory>" -type d -empty -not -path '*/.git/*' -delete 2>/dev/null

Show git status summary:

cd "$REPO_ROOT" && git status --short

Suggest commit message:

Suggested commit:

  refactor: reorganize <directory> structure

  - Removed {N} empty directories
  - Merged {overlapping dirs} into {target dirs}
  - Consolidated {sparse dirs}
  - Updated {M} cross-references across {K} files

Clean up mapping file:

rm -f "$MAPPING_FILE"

Important Notes

Safety first: Always dry-run before execute. Always ask for user confirmation.
Non-destructive: Uses git mv for tracked files, preserving history.
Reference integrity: Updates all references across the repository, not just within the target directory.
Iterative: User can modify the proposal before execution. Multiple rounds of feedback are expected.
Idempotent backing script: Running the script again after execution finds nothing to do.

Error Handling

If the backing script is not found at ${CLAUDE_PLUGIN_ROOT}/scripts/move-and-rereference.sh, report the error and suggest the user check their plugin installation.
If git mv fails for any file, the script stops and reports the error. The user can fix the issue and re-run.
If the directory has uncommitted changes, warn the user and suggest committing first.