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

## 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

   git stash save "Auto-stash before /sync command"
   

2. Pull remote changes

   git pull origin main
   

3. Attempt to restore local changes

   git stash pop
   

4. If conflicts remain:

   ## 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

## 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

## 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

## 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:

# 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:

{
  "operation": "sync_from_remote",
  "repository": "azcomputerguru/claudetools",
  "base_path": "D:/ClaudeTools/",
  "branch": "main",
  "handle_conflicts": "auto-stash"
}

Gitea Agent returns:

{
  "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.