Implementation

python3 ~/.claude/lib/sync_dispatcher.py "$@"

Sync - Unified Synchronization Command

Smart context-aware sync with automatic mode detection

The unified /sync command replaces /sync-dev and /update-plugin with intelligent context detection. It automatically detects whether you're syncing your development environment, updating from the marketplace, or working on plugin development.

Quick Start

# Auto-detect and sync (recommended)
/sync                    # Fetches latest from GitHub (default)

# Force specific mode
/sync --github           # Fetch latest from GitHub (explicit)
/sync --env              # Environment sync only
/sync --marketplace      # Marketplace update only
/sync --plugin-dev       # Plugin dev sync only
/sync --all              # Execute all modes
/sync --uninstall        # Preview uninstallation (safe)
/sync --uninstall --force # Execute uninstallation

Time: 10-90 seconds (depends on mode) Interactive: Shows detected mode, asks for confirmation Smart Detection: Auto-detects context - developers get plugin-dev, users get GitHub sync Post-Sync Validation: Automatic 4-phase validation with auto-fix

Post-Sync Validation (NEW)

After every successful sync, automatic validation runs to ensure everything is working:

4 Validation Phases

Settings Validation
- Checks settings.local.json exists and is valid JSON
- Validates hook paths point to existing files
- Auto-fixes: Removes invalid hook entries
Hook Integrity
- Verifies all hooks have valid Python syntax
- Checks hooks are executable (file permissions)
- Auto-fixes: chmod +x for non-executable hooks
Semantic Scan
- Checks agent prompts reference valid skills
- Detects deprecated patterns
- Validates version consistency across config files
- Auto-fixes: Updates deprecated references
Health Check
- Verifies expected component counts (agents, hooks, commands)
- Reports any missing components

Output Example

Post-Sync Validation
========================================

Settings Validation
  ✅ All checks passed

Hooks Validation
  ⚠️  Hook not executable: my_hook.py
      -> Auto-fixed: chmod +x my_hook.py

Semantic Validation
  ✅ No deprecated patterns detected

Health Validation
  ✅ All checks passed

========================================
Summary
========================================
✅ Sync validation PASSED
   Auto-fixed: 1 issue

When Issues Require Manual Fixes

If validation finds issues that can't be auto-fixed, it provides step-by-step guidance:

❌ Sync validation FAILED (1 error)

HOW TO FIX
==========

1. Fix hooks/broken_hook.py syntax error:
   Location: .claude/hooks/broken_hook.py:45
   Error: Missing closing parenthesis
   Action: Add ')' at end of line 45

Auto-Detection Logic

The command automatically detects the appropriate sync mode:

Detection Priority (highest to lowest):

Plugin Development → --plugin-dev
- Detected when: plugins/autonomous-dev/ directory exists
- Action: Sync plugin files to local .claude/ directory
- Use case: Plugin developers testing changes in the autonomous-dev repo
GitHub Sync → --github (DEFAULT)
- Detected when: Not in plugin development context
- Action: Fetch latest files directly from GitHub
- Use case: Users updating to latest version in any project

Simplified Logic: If you're in the autonomous-dev repo, you get plugin-dev mode. Otherwise, you get GitHub sync.

Sync Modes

GitHub Mode (`--github`) - DEFAULT

Fetches the latest plugin files directly from GitHub:

What it does:

Downloads files directly from raw.githubusercontent.com/akaszubski/autonomous-dev/master
Uses install_manifest.json to determine which files to fetch
Creates/updates .claude/ directory structure
No git installation required - works anywhere

When to use:

Updating to latest version (default behavior)
Getting new features and bug fixes
Running /sync in any project

Example:

/sync                    # Auto-detects and uses GitHub mode
/sync --github           # Explicitly use GitHub mode

Output:

Fetching latest from GitHub (akaszubski/autonomous-dev)...
Downloading install_manifest.json...
Syncing 47 files...
✓ GitHub sync completed: 47 files updated from akaszubski/autonomous-dev

Requirements:

Internet connection
No GitHub account needed (public repo)

Environment Mode (`--env`)

Synchronizes your development environment using the sync-validator agent:

What it does:

Detects dependency conflicts (package.json, requirements.txt, etc.)
Validates environment variables (.env files)
Checks for pending database migrations
Removes stale build artifacts
Ensures configuration consistency

When to use:

Daily development workflow
After pulling upstream changes
When dependencies seem out of sync
Before starting new feature work

Example:

/sync --env

Output:

Detecting sync mode... Environment sync detected
Invoking sync-validator agent...
✓ Environment sync complete: 3 files updated, 0 conflicts

Marketplace Mode (`--marketplace`)

Updates plugin files from the Claude marketplace installation with intelligent version detection and orphan cleanup:

What it does:

Version Detection (NEW in v3.7.1): Checks marketplace vs project version and informs about available updates
Smart Copy: Copies latest commands from ~/.claude/plugins/marketplaces/autonomous-dev/
Security Updates: Syncs hooks with latest security fixes
Agent Sync: Updates agent definitions
Orphan Cleanup (NEW in v3.7.1): Detects and removes files no longer in plugin (safe dry-run by default)
Local Preservation: Preserves local customizations in .claude/local/

When to use:

After installing plugin updates via /plugin update
When commands aren't showing expected behavior
To reset to marketplace defaults
To clean up old/deprecated plugin files

Example:

/sync --marketplace

Output:

Detecting sync mode... Marketplace update detected

Checking version...
  Project version: 3.7.0
  Marketplace version: 3.7.1
  ⬆ Update available: 3.7.0 → 3.7.1

Copying files from installed plugin...
✓ Marketplace sync complete: 47 files updated
  - Commands: 18 updated
  - Hooks: 12 updated
  - Agents: 17 updated

Checking for orphaned files...
  Found 2 orphaned files (marked for cleanup):
    - .claude/commands/deprecated-sync-dev.md (no longer in v3.7.1)
    - .claude/hooks/old-validation.py (consolidated into newer hook)

  Dry-run mode: No files deleted (use --cleanup to remove)

✓ All marketplace sync operations complete

Version Detection (NEW in v3.7.1 - GitHub #50):

How it works: Parses MAJOR.MINOR.PATCH[-PRERELEASE] from both marketplace and project plugin.json
Comparison: Detects upgrade available, downgrade risk, or up-to-date status
Shows available upgrades: 3.7.0 → 3.7.1 (tells you what's new)
Warns about downgrade risk: If project is newer than marketplace (edge case)
Prevents silent stale issues: You always know if updates are available
Implementation: lib/version_detector.py (531 lines, 20 unit tests)
- Version class: Semantic version object with comparison operators
- VersionComparison dataclass: Result with is_upgrade, is_downgrade, status, message
- detect_version_mismatch() function: High-level API for version comparison
- Security: Path validation, audit logging (CWE-22, CWE-59 protection)
- Error handling: Clear messages with expected format and troubleshooting hints
- Pre-release handling: Correctly handles 3.7.0, 3.8.0-beta.1, 3.8.0-rc.2 patterns

Orphan Cleanup (NEW in v3.7.1 - GitHub #50):

What is an orphan?: Files in .claude/ that aren't in the current plugin version
Why cleanup matters: Old/deprecated files can cause confusion or silent behavior changes
Detection: Scans .claude/commands/, .claude/hooks/, .claude/agents/ against plugin.json manifest
Reports orphans in dry-run mode: Safe default - shows what would be deleted
Optional cleanup with --cleanup flag: Removes old files (requires confirmation unless -y flag)
Atomic cleanup with rollback: If deletion fails, changes automatically rolled back
Implementation: lib/orphan_file_cleaner.py (514 lines, 22 unit tests)
- OrphanFile dataclass: Represents orphaned file with path and reason
- CleanupResult dataclass: Result with orphans_detected, orphans_deleted, success, summary
- OrphanFileCleaner class: Low-level API for fine-grained control
- detect_orphans(): Detection without cleanup
- cleanup_orphans(): Cleanup with mode control (dry-run, confirm, auto)
- Security: Path validation, audit logging to logs/orphan_cleanup_audit.log (JSON format)
- Error handling: Graceful per-file failures (one orphan deletion failure doesn't block others)

Implementation Integration (GitHub #51):

Both version detection and orphan cleanup are integrated into sync_dispatcher.py
Enhancement doesn't block core sync - non-blocking error handling
See lib/sync_dispatcher.py for complete integration details

See lib/version_detector.py and lib/orphan_file_cleaner.py for implementation details.

Plugin Development Mode (`--plugin-dev`)

Syncs plugin development files to local .claude/ directory:

What it does:

Copies plugins/autonomous-dev/commands/ → .claude/commands/
Copies plugins/autonomous-dev/hooks/ → .claude/hooks/
Copies plugins/autonomous-dev/agents/ → .claude/agents/
Enables testing plugin changes without reinstalling

When to use:

Developing new plugin features
Testing command modifications
Debugging agent behavior
Contributing to plugin development

Example:

/sync --plugin-dev

Output:

Detecting sync mode... Plugin development detected
Syncing plugin files to .claude/...
✓ Plugin dev sync complete: 52 files updated
  - Commands: 18 synced
  - Hooks: 29 synced
  - Agents: 18 synced

All Mode (`--all`)

Executes all sync modes in sequence:

Execution order:

Environment sync (most critical)
Marketplace update (get latest releases)
Plugin dev sync (apply local changes)

When to use:

Fresh project setup
Major version updates
Comprehensive synchronization
Troubleshooting sync issues

Example:

/sync --all

Output:

Executing all sync modes...

[1/3] Environment sync...
✓ Environment: 3 files updated

[2/3] Marketplace sync...
✓ Marketplace: 47 files updated

[3/3] Plugin dev sync...
✓ Plugin dev: 52 files updated

✓ All sync modes complete: 102 total files updated

Rollback support: If any mode fails, changes are rolled back automatically.

Uninstall Mode (`--uninstall`)

Completely removes the autonomous-dev plugin from your project:

What it does:

Shows preview of files to be removed (default behavior)
Creates timestamped backup before deletion (when using --force)
Removes all plugin files from .claude/ directory
Preserves protected files (PROJECT.md, .env, settings.local.json)
Supports rollback from backup if needed

Modes:

Preview (default): Shows what will be removed without deleting
Execute: Requires --force flag for actual deletion
Local-only: Use --local-only to skip global ~/.claude/ files

When to use:

Removing plugin from a project
Clean uninstall before reinstalling
Testing plugin installation/uninstallation

Examples:

# Preview what will be removed (safe, no deletion)
/sync --uninstall

# Execute actual uninstallation
/sync --uninstall --force

# Uninstall from project only (preserve global files)
/sync --uninstall --force --local-only

Preview output:

Uninstall Preview
========================================
Files to remove: 47
Total size: 1.2 MB
Backup will be created before deletion

Files:
  .claude/commands/auto-implement.md
  .claude/commands/sync.md
  .claude/agents/planner.md
  ...

Protected files (will NOT be removed):
  .claude/PROJECT.md
  .claude/config/settings.local.json
  .env

Run with --force to execute uninstallation

Execute output:

/sync --uninstall --force

Uninstalling autonomous-dev plugin...
Creating backup: .autonomous-dev/uninstall_backup_20251214_120000.tar.gz
Removing 47 files...
✓ Uninstall complete: 47 files removed (1.2 MB)
✓ Backup: .autonomous-dev/uninstall_backup_20251214_120000.tar.gz

To rollback:
  python3 ~/.claude/lib/uninstall_orchestrator.py <project_root> --rollback .autonomous-dev/uninstall_backup_20251214_120000.tar.gz

Rollback: If you need to restore files after uninstallation:

from pathlib import Path
from uninstall_orchestrator import UninstallOrchestrator

orchestrator = UninstallOrchestrator(project_root=Path.cwd())
result = orchestrator.rollback(backup_path=Path(".autonomous-dev/uninstall_backup_20251214_120000.tar.gz"))
print(f"Restored {result.files_restored} files")

Security:

Path traversal prevention (CWE-22)
Symlink attack prevention (CWE-59)
TOCTOU detection (CWE-367)
Whitelist enforcement (only operates within .claude/ and .autonomous-dev/)
Protected file preservation
Audit logging for all operations

Protected files (never removed):

.claude/PROJECT.md (project goals and scope)
.claude/config/settings.local.json (user settings)
.env (environment variables and secrets)
Any user-modified plugin files

Migration from Old Commands

`/sync-dev` → `/sync --env`

Old command:

/sync-dev

New equivalent:

/sync --env

Note: /sync-dev still works but shows deprecation warning. Update your workflows to use /sync --env.

`/update-plugin` → `/sync --marketplace`

Old command:

/update-plugin

New equivalent:

/sync --marketplace

Note: /update-plugin still works but shows deprecation warning. Update your workflows to use /sync --marketplace.

Security

All sync operations include comprehensive security validation:

Path Validation: CWE-22 (path traversal) protection via security_utils
Symlink Detection: CWE-59 (symlink resolution) protection
Audit Logging: All operations logged to logs/security_audit.log
Backup Support: Automatic backup before sync (rollback on failure)
Whitelist Validation: Only allow writes to approved directories

Security requirements:

All paths validated through 4-layer security checks
Symlinks resolved before validation
Log injection prevention (CWE-117)
User permissions only (no privilege escalation)

See docs/SECURITY.md for comprehensive security documentation.

Troubleshooting

"Failed to fetch manifest from GitHub"

Cause: Network error or GitHub unavailable Fix: Check internet connection and try again

# Verify internet connection
curl -I https://raw.githubusercontent.com

# If working, try sync again
/sync --github

"Sync failed: Project path does not exist"

Cause: Invalid project path Fix: Ensure you're running /sync from a valid project directory

cd /path/to/project
/sync

"Plugin directory not found" (plugin-dev mode)

Cause: Not in a plugin development environment Fix: Only use --plugin-dev when working on the plugin itself

# Check if plugin directory exists
ls plugins/autonomous-dev/

# If not present, you probably want environment sync instead
/sync --env

"Conflicting sync flags"

Cause: Multiple incompatible flags specified Fix: Use only one flag (or --all)

# ❌ Wrong
/sync --env --marketplace

# ✓ Correct
/sync --env

# ✓ Or use --all
/sync --all

"Cannot use --all with specific flags"

Cause: Mixing --all with specific mode flags Fix: Choose either --all OR specific flags

# ❌ Wrong
/sync --all --env

# ✓ Correct
/sync --all

# ✓ Or specific mode
/sync --env

"Update available" notification during marketplace sync

What it means: Your project plugin is older than the marketplace version Example: Project v3.7.0, Marketplace v3.7.1

What to do:

Review changelog for new features/fixes
Run /sync --marketplace to apply updates
Full restart Claude Code (Cmd+Q or Ctrl+Q) to reload commands
Test updated commands to verify

Note: This is just informational. Your current version still works fine, but updates may include security fixes, performance improvements, or bug fixes.

"Orphaned files detected" warning during marketplace sync

What it means: Files exist in your project that aren't in the current plugin version Examples:

Old commands from previous version (e.g., sync-dev.md if upgrading from v3.6 to v3.7)
Deprecated hooks that were consolidated into newer versions
Agent files that were renamed

What to do:

Option 1: Review before cleanup (RECOMMENDED)

/sync --marketplace     # Shows orphans in dry-run mode
# Review the list of orphaned files

/sync --marketplace --cleanup  # Prompts for each file
# Confirm deletion: y/n for each orphan

Option 2: Auto-cleanup (Non-interactive)

/sync --marketplace --cleanup -y
# Automatically deletes all orphans without prompting

Option 3: Keep files (Conservative)

# Just ignore the warning - old files won't hurt anything
# They'll still be there but won't interfere

When to be cautious:

If you made custom modifications to plugin files
If you have local extensions relying on old files
If you're not sure what files do

Safe choice: Use --cleanup (with confirmation) - it's the best practice to keep your .claude/ directory clean and in sync with the current plugin version.

"Orphan cleanup failed" during marketplace sync

Cause: Permission denied or file locked Fix: Ensure the file isn't in use

# Close Claude Code completely
# (Press Cmd+Q on Mac or Ctrl+Q on Linux/Windows)

# Wait 5 seconds for process to exit

# Restart Claude Code

# Try sync again
/sync --marketplace --cleanup -y

If still fails:

# Check file permissions
ls -la .claude/commands/problematic-file.md

# Fix permissions if needed
chmod 644 .claude/commands/problematic-file.md

# Try cleanup again
/sync --marketplace --cleanup -y

Examples

Daily Development Workflow

# Morning: Sync environment before starting work
/sync

# Auto-detects environment mode
# Validates dependencies, config, migrations

Plugin Update Workflow

# Step 1: Update plugin via marketplace
/plugin update autonomous-dev

# Step 2: FULL RESTART REQUIRED
# CRITICAL: /exit is NOT enough! Claude Code caches commands in memory.
# Press Cmd+Q (Mac) or Ctrl+Q (Windows/Linux) to fully quit
# Verify: ps aux | grep claude | grep -v grep (should return nothing)
# Wait 5 seconds, then restart Claude Code

# Step 3: Sync marketplace updates to project
/sync --marketplace

# Step 4: FULL RESTART AGAIN
# Commands won't reload until you fully restart Claude Code
# Press Cmd+Q again, wait 5 seconds, restart

Plugin Development Workflow

# Step 1: Make changes to plugin files
vim plugins/autonomous-dev/commands/new-feature.md

# Step 2: Sync to .claude/ for testing
/sync --plugin-dev

# Step 3: FULL RESTART REQUIRED
# CRITICAL: /exit is NOT enough! You must fully quit Claude Code.
# Press Cmd+Q (Mac) or Ctrl+Q (Windows/Linux)
# Verify: ps aux | grep claude | grep -v grep (should return nothing)
# Wait 5 seconds, then restart Claude Code

# Step 4: Test the command
/new-feature

# Step 5: Repeat as needed (restart required each time!)

Fresh Project Setup

# Sync everything
/sync --all

# Ensures:
# - Environment is configured
# - Marketplace updates applied
# - Plugin dev files synced (if applicable)

Technical Details

Architecture

The unified /sync command uses two core libraries:

sync_mode_detector.py: Intelligent context detection
- Analyzes project structure
- Parses command-line flags
- Validates all paths for security
sync_dispatcher.py: Mode-specific sync operations
- Delegates to sync-validator agent (environment mode)
- Copies files from marketplace (marketplace mode)
- Syncs plugin dev files (plugin-dev mode)
- Executes all modes in sequence (all mode)

Performance

Environment mode: 30-60 seconds

Dominated by sync-validator agent analysis
Depends on project size and changes

Marketplace mode: 5-10 seconds

Fast file copy operations
Depends on plugin size (~50 files)

Plugin dev mode: 5-10 seconds

Fast local file sync
Depends on number of files changed

All mode: 40-80 seconds

Sum of all individual modes
Progress reported for each phase

Backup and Rollback

All sync operations create automatic backups:

Backup location: $(mktemp -d)/claude_sync_backup_*/
Backup contents: Complete .claude/ directory
Rollback trigger: Any sync failure
Cleanup: Automatic after successful sync

Manual rollback (if needed):

# Find backup
ls -la /tmp/claude_sync_backup_*

# Restore manually
cp -r /tmp/claude_sync_backup_*/`.claude/` .claude/

/sync

Implementation

Sync - Unified Synchronization Command

Quick Start

Post-Sync Validation (NEW)

4 Validation Phases

Output Example

When Issues Require Manual Fixes

Auto-Detection Logic

Detection Priority (highest to lowest):

Sync Modes

GitHub Mode (--github) - DEFAULT

Environment Mode (--env)

Marketplace Mode (--marketplace)

Plugin Development Mode (--plugin-dev)

All Mode (--all)

Uninstall Mode (--uninstall)

Migration from Old Commands

/sync-dev → /sync --env

/update-plugin → /sync --marketplace

Security

Troubleshooting

"Failed to fetch manifest from GitHub"

"Sync failed: Project path does not exist"

"Plugin directory not found" (plugin-dev mode)

"Conflicting sync flags"

"Cannot use --all with specific flags"

"Update available" notification during marketplace sync

"Orphaned files detected" warning during marketplace sync

"Orphan cleanup failed" during marketplace sync

Examples

Daily Development Workflow

Plugin Update Workflow

Plugin Development Workflow

Fresh Project Setup

Technical Details

Architecture

Performance

Backup and Rollback

See Also

Other plugins with /sync

GitHub Mode (`--github`) - DEFAULT

Environment Mode (`--env`)

Marketplace Mode (`--marketplace`)

Plugin Development Mode (`--plugin-dev`)

All Mode (`--all`)

Uninstall Mode (`--uninstall`)

`/sync-dev` → `/sync --env`

`/update-plugin` → `/sync --marketplace`