coalesce-labs/reorganize

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:

1. Remove empty directories left behind:

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

2. Show git status summary:

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

3. 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

4. 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.