827 lines
22 KiB
Markdown
827 lines
22 KiB
Markdown
---
|
|
name: sync
|
|
description: "Sync plugin files (--github default, --env, --marketplace, --plugin-dev, --all, --uninstall)"
|
|
argument_hint: "Optional flags: --github (default), --env, --marketplace, --plugin-dev, --all, --uninstall [--force] [--local-only]"
|
|
allowed-tools: [Task, Read, Write, Bash, Grep, Glob]
|
|
---
|
|
|
|
## Implementation
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
/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**:
|
|
```bash
|
|
/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**:
|
|
```bash
|
|
/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**:
|
|
```bash
|
|
/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**:
|
|
```bash
|
|
/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**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
/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:
|
|
```python
|
|
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:
|
|
```bash
|
|
/sync-dev
|
|
```
|
|
|
|
New equivalent:
|
|
```bash
|
|
/sync --env
|
|
```
|
|
|
|
**Note**: `/sync-dev` still works but shows deprecation warning. Update your workflows to use `/sync --env`.
|
|
|
|
---
|
|
|
|
### `/update-plugin` → `/sync --marketplace`
|
|
|
|
Old command:
|
|
```bash
|
|
/update-plugin
|
|
```
|
|
|
|
New equivalent:
|
|
```bash
|
|
/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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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`)
|
|
|
|
```bash
|
|
# ❌ 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
|
|
|
|
```bash
|
|
# ❌ 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)
|
|
```bash
|
|
/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)
|
|
```bash
|
|
/sync --marketplace --cleanup -y
|
|
# Automatically deletes all orphans without prompting
|
|
```
|
|
|
|
**Option 3: Keep files** (Conservative)
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Morning: Sync environment before starting work
|
|
/sync
|
|
|
|
# Auto-detects environment mode
|
|
# Validates dependencies, config, migrations
|
|
```
|
|
|
|
---
|
|
|
|
### Plugin Update Workflow
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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):
|
|
```bash
|
|
# 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)
|