/symlinks - Project Symlink Manager

Scan, validate, and fix CODITECT symlinks (.coditect and .claude) across all projects in ~/PROJECTS/.

System Prompt

EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

1. Scan ~/PROJECTS/ - Find all directories with .coditect or .claude
2. Validate symlink chains - Ensure they resolve to the protected installation
3. Report status - Show table of all projects and their symlink health
4. Offer fixes - For broken or outdated symlinks, offer to fix them
5. Execute fixes - With user confirmation, update symlinks to correct targets

MODIFIES FILES: This command can update symlinks with --fix flag.

---

Usage

/symlinks                    # Scan and report symlink status
/symlinks --check            # Check only, no modifications (default)
/symlinks --fix              # Fix all broken/outdated symlinks
/symlinks --fix <project>    # Fix symlinks for specific project
/symlinks --verbose          # Show detailed resolution chains

What It Does

Step 1: Identify Protected Installation

# Determine the correct target for symlinks
PROTECTED_LOC="$HOME/Library/Application Support/CODITECT/core"

# Verify installation
if [ -d "$PROTECTED_LOC" ]; then
    echo "✓ Protected installation: $PROTECTED_LOC"
else
    echo "⚠ Protected installation not found - run CODITECT-CORE-INITIAL-SETUP.py"
    exit 1
fi

# Check root symlinks
ROOT_CODITECT="$HOME/PROJECTS/.coditect"
if [ -L "$ROOT_CODITECT" ]; then
    TARGET=$(readlink "$ROOT_CODITECT")
    echo "✓ Root symlink: $ROOT_CODITECT -> $TARGET"
fi

Step 2: Scan All Projects

# Find all .coditect entries in ~/PROJECTS/
for dir in ~/PROJECTS/*/; do
    project=$(basename "$dir")
    coditect_path="$dir.coditect"
    claude_path="$dir.claude"

    if [ -e "$coditect_path" ] || [ -L "$coditect_path" ]; then
        # Check if symlink
        if [ -L "$coditect_path" ]; then
            target=$(readlink "$coditect_path")
            resolved=$(python3 -c "import os; print(os.path.realpath('$coditect_path'))")
            echo "$project: $target -> $resolved"
        else
            echo "$project: DIRECTORY (not symlink)"
        fi
    fi
done

Step 3: Validate Symlink Chains

For each project, verify the symlink chain resolves to the protected installation:

Status	Meaning	Action
✅ VALID	Resolves to protected location	None
⚠️ OUTDATED	Resolves to development copy	Recommend fix
❌ BROKEN	Symlink target doesn't exist	Recommend fix
❌ DIRECTORY	Embedded copy, not symlink	Recommend replacement

Step 4: Report Results

╔══════════════════════════════════════════════════════════════════╗
║                    CODITECT Symlink Status                       ║
╠══════════════════════════════════════════════════════════════════╣
║ Protected Location: ~/Library/Application Support/CODITECT/core  ║
║ Root Symlink: ~/PROJECTS/.coditect ✅                            ║
╠══════════════════════════════════════════════════════════════════╣
║ Project              │ .coditect        │ .claude    │ Status   ║
╠══════════════════════════════════════════════════════════════════╣
║ BUILDER-OS           │ ../.coditect     │ .coditect  │ ✅ VALID ║
║ MECHANIZE.WORK       │ ../.coditect     │ .coditect  │ ✅ VALID ║
║ whozin               │ ../.coditect     │ .coditect  │ ✅ VALID ║
║ old-project          │ DIRECTORY        │ MISSING    │ ❌ FIX   ║
╚══════════════════════════════════════════════════════════════════╝

Step 5: Fix Symlinks (with --fix)

fix_project_symlinks() {
    local project_dir="$1"
    local project_name=$(basename "$project_dir")

    # Remove existing .coditect (symlink or directory)
    if [ -L "$project_dir/.coditect" ]; then
        rm "$project_dir/.coditect"
    elif [ -d "$project_dir/.coditect" ]; then
        echo "⚠ $project_name has embedded .coditect directory"
        echo "  Backing up to ~/PROJECTS/BU/$project_name-coditect-backup/"
        mkdir -p ~/PROJECTS/BU
        mv "$project_dir/.coditect" ~/PROJECTS/BU/$project_name-coditect-backup/
    fi

    # Create correct symlinks
    ln -sf ../.coditect "$project_dir/.coditect"
    ln -sf .coditect "$project_dir/.claude"

    echo "✓ Fixed: $project_name"
}

Expected Symlink Architecture

PROTECTED INSTALLATION (Read-Only):
~/Library/Application Support/CODITECT/core/

ROOT SYMLINKS:
~/.coditect ──────────────────────┐
~/PROJECTS/.coditect ─────────────┼──► Protected Location
~/PROJECTS/.claude ───────────────┘
        ↑
PROJECT SYMLINKS (relative):
  project-a/.coditect → ../.coditect ──┐
  project-b/.coditect → ../.coditect ──┼──► ~/PROJECTS/.coditect
  project-c/.coditect → ../.coditect ──┘

  project-a/.claude → .coditect
  project-b/.claude → .coditect
  project-c/.claude → .coditect

Common Issues

Issue: Symlink points to development copy

whozin/.coditect → ../coditect-rollout-master/.coditect
                   ↓
                   submodules/core/coditect-core (DEVELOPMENT)

Fix: Update to use root symlink:

ln -sf ../.coditect whozin/.coditect

Issue: Embedded directory instead of symlink

old-project/.coditect/  (43MB embedded copy)

Fix: Backup and replace with symlink:

mv old-project/.coditect ~/PROJECTS/BU/old-project-coditect-backup/
ln -sf ../.coditect old-project/.coditect

Issue: Missing .claude symlink

project/.coditect  ✅ exists
project/.claude    ❌ missing

Fix: Create .claude pointing to .coditect:

ln -sf .coditect project/.claude

Integration

This command works with:

• /project-new - Creates correct symlinks for new projects
• CODITECT-CORE-INITIAL-SETUP.py - Sets up root symlinks
• projects-db.py - Registers projects in the database

See Also

• /project-new - Create new project with symlinks
• /orient - Session orientation
• CODITECT-CORE-INITIAL-SETUP.py - Main installation script