charieswei
/
TradingAgents
mirror of https://github.com/TauricResearch/TradingAgents.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
TradingAgents/.claude/commands/sync.md

22 KiB
Raw Blame History

name description argument_hint allowed-tools
sync Sync plugin files (--github default, --env, --marketplace, --plugin-dev, --all, --uninstall) Optional flags: --github (default), --env, --marketplace, --plugin-dev, --all, --uninstall [--force] [--local-only]
Task
Read
Write
Bash
Grep
Glob

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

  1. Settings Validation

    • Checks settings.local.json exists and is valid JSON
    • Validates hook paths point to existing files
    • Auto-fixes: Removes invalid hook entries

  2. Hook Integrity

    • Verifies all hooks have valid Python syntax
    • Checks hooks are executable (file permissions)
    • Auto-fixes: chmod +x for non-executable hooks

  3. Semantic Scan

    • Checks agent prompts reference valid skills
    • Detects deprecated patterns
    • Validates version consistency across config files
    • Auto-fixes: Updates deprecated references

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

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

  2. 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:

  1. Environment sync (most critical)
  2. Marketplace update (get latest releases)
  3. 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:

  1. Review changelog for new features/fixes
  2. Run /sync --marketplace to apply updates
  3. Full restart Claude Code (Cmd+Q or Ctrl+Q) to reload commands
  4. 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:

  1. sync_mode_detector.py: Intelligent context detection

    • Analyzes project structure
    • Parses command-line flags
    • Validates all paths for security

  2. 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/

See Also

  • Environment Sync: See archived /sync-dev command for detailed workflow
  • Marketplace Updates: See archived /update-plugin command for update process
  • Security: See docs/SECURITY.md for comprehensive security documentation
  • Development: See docs/DEVELOPMENT.md for plugin development guide

Last Updated: 2025-12-13 Issue: GitHub #44 - Unified /sync command, GitHub #124 - Default to GitHub sync Replaces: /sync-dev, /update-plugin Default Mode: GitHub sync (fetches latest from repository)