claudetools/.claude/commands/sync.md

# /sync Command

Synchronize ClaudeTools configuration from Gitea repository.

## Purpose

Pull the latest system configuration, agent definitions, and workflows from the Gitea repository to ensure you're working with the most up-to-date ClaudeTools system.

## What It Does

1. **Connects to Gitea repository** - `azcomputerguru/claudetools`
2. **Pulls latest changes** - Via Gitea Agent
3. **Updates local files**:
   - `.claude/agents/` - Agent definitions
   - `.claude/commands/` - Custom commands
   - `.claude/*.md` - Workflow documentation
   - `README.md` - System overview
4. **Handles conflicts** - Stashes local changes if needed
5. **Reports changes** - Shows what was updated

## Usage

```
/sync
```

Or:
```
Claude, sync the settings
Claude, pull latest from Gitea
Claude, update claudetools config
```

## When to Use

- **After repository updates** - When changes pushed to Gitea
- **On new machine** - After cloning repository
- **Periodic checks** - Weekly sync to stay current
- **Team updates** - When other team members update agents/workflows
- **Before important work** - Ensure latest configurations

## What Gets Updated

✅ **System Configuration:**
- `.claude/agents/*.md` - Agent definitions
- `.claude/commands/*.md` - Custom commands
- `.claude/*.md` - Workflow documentation

✅ **Documentation:**
- `README.md` - System overview
- `.gitignore` - Git ignore rules

❌ **NOT Updated (Local Only):**
- `.claude/settings.local.json` - Machine-specific settings
- `backups/` - Local backups
- `clients/` - Client work (separate repos)
- `projects/` - Projects (separate repos)

## Execution Flow

```
User: "/sync"
  ↓
Main Claude: Invokes Gitea Agent
  ↓
Gitea Agent:
  1. cd D:\ClaudeTools
  2. git fetch origin main
  3. Check for local changes
  4. If clean: git pull origin main
  5. If dirty: git stash && git pull && git stash pop
  6. Report results
  ↓
Main Claude: Shows summary to user
```

## Example Output

```markdown
## Sync Complete ✅

**Repository:** azcomputerguru/claudetools
**Branch:** main
**Changes:** 3 files updated

### Files Updated:
- `.claude/agents/coding.md` - Updated coding standards
- `.claude/CODE_WORKFLOW.md` - Added exception handling notes
- `README.md` - Updated backup strategy documentation

### Status:
- No conflicts
- Local changes preserved (if any)
- Ready to continue work

**Last sync:** 2026-01-15 15:30:00
```

## Conflict Handling

**If local changes conflict with remote:**

1. **Stash local changes**
   ```bash
   git stash save "Auto-stash before /sync command"
   ```

2. **Pull remote changes**
   ```bash
   git pull origin main
   ```

3. **Attempt to restore local changes**
   ```bash
   git stash pop
   ```

4. **If conflicts remain:**
   ```markdown
   ## Sync - Manual Intervention Required ⚠️

   **Conflict detected in:**
   - `.claude/agents/coding.md`

   **Action required:**
   1. Open conflicted file
   2. Resolve conflict markers (<<<<<<, ======, >>>>>>)
   3. Run: git add .claude/agents/coding.md
   4. Run: git stash drop
   5. Or ask Claude to help resolve conflict

   **Local changes stashed** - Run `git stash list` to see
   ```

## Error Handling

### Network Error
```markdown
## Sync Failed - Network Issue ❌

Could not connect to git.azcomputerguru.com

**Possible causes:**
- VPN not connected
- Network connectivity issue
- Gitea server down

**Solution:**
- Check VPN connection
- Retry: /sync
```

### Authentication Error
```markdown
## Sync Failed - Authentication ❌

SSH key authentication failed

**Possible causes:**
- SSH key not loaded
- Incorrect permissions on key file

**Solution:**
- Verify SSH key: C:\Users\MikeSwanson\.ssh\id_ed25519
- Test connection: ssh git@git.azcomputerguru.com
```

### Uncommitted Changes Warning
```markdown
## Sync Warning - Uncommitted Changes ⚠️

You have uncommitted local changes:
- `.claude/agents/custom-agent.md` (new file)
- `.claude/CUSTOM_NOTES.md` (modified)

**Options:**
1. Commit changes first: `/commit` or ask Claude to commit
2. Stash and sync: /sync will auto-stash
3. Discard changes: git reset --hard (WARNING: loses changes)

**Recommended:** Commit your changes first, then sync.
```

## Integration with Gitea Agent

**Sync operation delegated to Gitea Agent:**

```python
# Main Claude (Orchestrator) calls:
Gitea_Agent.sync_from_remote(
    repository="azcomputerguru/claudetools",
    base_path="D:/ClaudeTools/",
    branch="main",
    handle_conflicts="auto-stash"
)

# Gitea Agent performs:
# 1. git fetch
# 2. Check status
# 3. Stash if needed
# 4. Pull
# 5. Pop stash if stashed
# 6. Report results
```

## Safety Features

- **No data loss** - Local changes stashed, not discarded
- **Conflict detection** - User notified if manual resolution needed
- **Rollback possible** - `git stash list` shows saved changes
- **Dry-run option** - `git fetch` previews changes before pulling

## Related Commands

- `/commit` - Commit local changes before sync
- `/status` - Check git status without syncing

## Technical Implementation

**Gitea Agent receives:**
```json
{
  "operation": "sync_from_remote",
  "repository": "azcomputerguru/claudetools",
  "base_path": "D:/ClaudeTools/",
  "branch": "main",
  "handle_conflicts": "auto-stash"
}
```

**Gitea Agent returns:**
```json
{
  "success": true,
  "operation": "sync_from_remote",
  "files_updated": [
    ".claude/agents/coding.md",
    ".claude/CODE_WORKFLOW.md",
    "README.md"
  ],
  "files_count": 3,
  "conflicts": false,
  "local_changes_stashed": false,
  "commit_before": "a3f5b92c...",
  "commit_after": "e7d9c1a4...",
  "sync_timestamp": "2026-01-15T15:30:00Z"
}
```

## Best Practices

1. **Sync regularly** - Weekly or before important work
2. **Commit before sync** - Cleaner workflow, easier conflict resolution
3. **Review changes** - Check what was updated after sync
4. **Test after sync** - Verify agents/workflows work as expected
5. **Keep local settings separate** - Use `.claude/settings.local.json` for machine-specific config

---

**This command ensures you always have the latest ClaudeTools configuration and agent definitions.**