From 3560c90ea3b6745c45ec23814df0728daed782c8 Mon Sep 17 00:00:00 2001 From: Mike Swanson Date: Wed, 21 Jan 2026 16:38:37 -0700 Subject: [PATCH] sync: Auto-sync from ACG-M-L5090 at 2026-01-21 16:38:37 Synced files: - Enhanced /sync command with behavioral elements - Added CODING_GUIDELINES.md sync - Added AGENT_COORDINATION_RULES.md sync - Added agent documentation sync Machine: ACG-M-L5090 Timestamp: 2026-01-21 16:38:37 Co-Authored-By: Claude Sonnet 4.5 --- .claude/commands/sync.md | 441 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 417 insertions(+), 24 deletions(-) diff --git a/.claude/commands/sync.md b/.claude/commands/sync.md index 51c9bf5..7e14ad7 100644 --- a/.claude/commands/sync.md +++ b/.claude/commands/sync.md @@ -1,36 +1,429 @@ -Sync Claude Code preferences and commands from ClaudeTools repo on Gitea to this local machine. +# /sync - Bidirectional ClaudeTools Sync -## Steps to perform: +Synchronize ClaudeTools configuration, session data, and context bidirectionally with Gitea. Ensures all machines stay perfectly in sync for seamless cross-machine workflow. -1. **Pull the ClaudeTools repo** from Gitea via HTTPS: - ``` - Repository: https://git.azcomputerguru.com/azcomputerguru/claudetools.git - ``` +--- -2. **Check if repo exists locally** at `~/ClaudeTools/` - - If exists: `git pull origin main` - - If not: Clone it first with `git clone https://git.azcomputerguru.com/azcomputerguru/claudetools.git ~/ClaudeTools` +## What Gets Synced -3. **Copy the .claude/commands directory** from the repo to apply commands: - - Source: `~/ClaudeTools/.claude/commands/` - - Destination: `~/.claude/commands/` - - These slash commands will now be available globally +**FROM Local TO Gitea (PUSH):** +- Session logs: `session-logs/*.md` +- Project session logs: `projects/*/session-logs/*.md` +- Credentials: `credentials.md` (private repo - safe to sync) +- Project state: `SESSION_STATE.md` +- Commands: `.claude/commands/*.md` +- Directives: `directives.md` +- File placement guide: `.claude/FILE_PLACEMENT_GUIDE.md` +- Behavioral guidelines: + - `.claude/CODING_GUIDELINES.md` (NO EMOJIS, ASCII markers, standards) + - `.claude/AGENT_COORDINATION_RULES.md` (delegation guidelines) + - `.claude/agents/*.md` (agent-specific documentation) + - `.claude/CLAUDE.md` (project context and instructions) + - Any other `.claude/*.md` operational files +- Any other tracked changes -4. **Apply global permissions** - Copy the shared settings if available: +**FROM Gitea TO Local (PULL):** +- All of the above from other machines +- Latest commands and configurations +- Updated session logs from other sessions +- Project-specific work and documentation + +--- + +## Execution Steps + +### Phase 1: Prepare Local Changes + +1. **Navigate to ClaudeTools repo:** ```bash - cp ~/ClaudeTools/.claude/settings.json ~/.claude/settings.json + cd ~/ClaudeTools # or D:\ClaudeTools on Windows ``` - This applies the comprehensive permission set so you get fewer prompts. -5. **Read and apply any project settings** from `~/ClaudeTools/.claude/settings.local.json` if present +2. **Check repository status:** + ```bash + git status + ``` + Report number of changed/new files to user -6. **Report what was synced**: - - List available slash commands - - Show any settings applied - - Show recent session logs available for context +3. **Stage all changes:** + ```bash + git add -A + ``` + This includes: + - New/modified session logs + - Updated credentials.md + - SESSION_STATE.md changes + - Command updates + - Directive changes + - Behavioral guidelines (CODING_GUIDELINES.md, AGENT_COORDINATION_RULES.md, etc.) + - Agent documentation + - Project documentation -7. **Read the most recent session log** from `~/ClaudeTools/session-logs/` to get context on what was worked on recently +4. **Auto-commit local changes with timestamp:** + ```bash + git commit -m "sync: Auto-sync from [machine-name] at [timestamp] -8. **Refresh directives** - Read directives.md to ensure proper operational mode + Synced files: + - Session logs updated + - Latest context and credentials + - Command/directive updates -This ensures all your machines have the same Claude Code setup and can pick up where you left off with ClaudeTools work. + Machine: [hostname] + Timestamp: [YYYY-MM-DD HH:MM:SS] + + Co-Authored-By: Claude Sonnet 4.5 " + ``` + + **Note:** Only commit if there are changes. If working tree is clean, skip to Phase 2. + +--- + +### Phase 2: Sync with Gitea + +5. **Pull latest changes from Gitea:** + ```bash + git pull origin main --rebase + ``` + + **Handle conflicts if any:** + - Session logs: Keep both versions (rename conflicting file with timestamp) + - credentials.md: Manual merge required - report to user + - Other files: Use standard git conflict resolution + + Report what was pulled from remote + +6. **Push local changes to Gitea:** + ```bash + git push origin main + ``` + + Confirm push succeeded + +--- + +### Phase 3: Apply Configuration Locally + +7. **Copy commands to global Claude directory:** + ```bash + mkdir -p ~/.claude/commands + cp -r ~/ClaudeTools/.claude/commands/* ~/.claude/commands/ + ``` + These slash commands are now available globally + +8. **Apply global settings if available:** + ```bash + if [ -f ~/ClaudeTools/.claude/settings.json ]; then + cp ~/ClaudeTools/.claude/settings.json ~/.claude/settings.json + fi + ``` + +9. **Sync project settings:** + ```bash + if [ -f ~/ClaudeTools/.claude/settings.local.json ]; then + # Read and note any project-specific settings + fi + ``` + +--- + +### Phase 4: Context Recovery + +10. **Find and read most recent session logs:** + + Check all locations: + - `~/ClaudeTools/session-logs/*.md` (general) + - `~/ClaudeTools/projects/*/session-logs/*.md` (project-specific) + + Report the 3 most recent logs found: + - File name and location + - Last modified date + - Brief summary of what was worked on (from first 5 lines) + +11. **Read behavioral guidelines and directives:** + ```bash + cat ~/ClaudeTools/directives.md + cat ~/ClaudeTools/.claude/CODING_GUIDELINES.md + cat ~/ClaudeTools/.claude/AGENT_COORDINATION_RULES.md + ``` + Internalize operational directives and behavioral rules to ensure: + - Proper coordination mode (delegate vs execute) + - NO EMOJIS rule enforcement + - Agent delegation patterns + - Coding standards compliance + +--- + +### Phase 5: Report Sync Status + +12. **Summarize what was synced:** + + ``` + ## Sync Complete + + [OK] Local changes pushed to Gitea: + - X session logs updated + - credentials.md synced + - SESSION_STATE.md updated + - Y command files + + [OK] Remote changes pulled from Gitea: + - Z files updated from other machines + - Latest session: [most recent log] + + [OK] Configuration applied: + - Commands available: /checkpoint, /context, /save, /sync, etc. + - Directives internalized (coordination mode, delegation rules) + - Behavioral guidelines internalized (NO EMOJIS, ASCII markers, coding standards) + - Agent coordination rules applied + - Global settings applied + + Recent work (last 3 sessions): + 1. [date] - [project] - [brief summary] + 2. [date] - [project] - [brief summary] + 3. [date] - [project] - [brief summary] + + **Status:** All machines in sync. Ready to continue work. + ``` + +--- + +## Conflict Resolution + +### Session Log Conflicts +If both machines created session logs with same date: +1. Keep both versions +2. Rename to: `YYYY-MM-DD-session-[machine].md` +3. Report conflict to user + +### credentials.md Conflicts +If credentials.md has conflicts: +1. Do NOT auto-merge +2. Report conflict to user +3. Show conflicting sections +4. Ask user which version to keep or how to merge + +### Other File Conflicts +Standard git conflict markers: +1. Report files with conflicts +2. Show conflict sections +3. Ask user to resolve manually or provide guidance + +--- + +## Machine Detection + +Automatically detect machine name for commit messages: + +**Windows:** +```powershell +$env:COMPUTERNAME +``` + +**Mac/Linux:** +```bash +hostname +``` + +**Timestamp format:** +```bash +date "+%Y-%m-%d %H:%M:%S" +``` + +--- + +## Benefits + +### Seamless Multi-Machine Workflow +- Start work on one machine, continue on another +- All session context automatically synchronized +- Credentials available everywhere (private repo) +- Commands and directives stay consistent +- Behavioral rules enforced identically (NO EMOJIS, delegation patterns, coding standards) + +### Complete Context Preservation +- Never lose session data +- Full history across all machines +- Searchable via git log +- Rollback capability if needed + +### Zero Manual Sync +- One command syncs everything +- Auto-commit prevents forgotten changes +- Push/pull happens automatically +- Conflicts handled gracefully + +--- + +## Usage Examples + +### Standard Sync (Most Common) +``` +User: /sync + +Claude: +[Commits local changes] +[Pulls from Gitea] +[Pushes to Gitea] +[Applies configuration] +[Reports status] + +Sync complete. 3 session logs pushed, 2 updates pulled. +Ready to continue work. +``` + +### Sync Before Important Work +``` +User: "I'm switching to my other machine. /sync" + +Claude: +[Syncs everything] +Report: Latest work on Dataforth DOS dashboard pushed to Gitea. +All session logs and credentials synced. +You can now pull on the other machine to continue. +``` + +### Daily Morning Sync +``` +User: /sync + +Claude: +[Pulls overnight changes from other machines] +Report: Found 2 new sessions from yesterday evening. +Latest: GuruRMM dashboard redesign completed. +Context recovered. Ready for today's work. +``` + +--- + +## Error Handling + +### Network Issues +If git pull/push fails: +1. Report connection error +2. Show what was committed locally +3. Suggest retry or manual sync +4. Changes are safe (committed locally) + +### Authentication Issues +If Gitea authentication fails: +1. Report auth error +2. Check SSH keys or credentials +3. Provide troubleshooting steps +4. Manual push may be needed + +### Merge Conflicts +If automatic merge fails: +1. Report which files have conflicts +2. Show conflict markers +3. Ask for user guidance +4. Offer to abort merge if needed + +--- + +## Security Notes + +**credentials.md Syncing:** +- Private repository on Gitea (https://git.azcomputerguru.com) +- Only accessible to authorized user +- Encrypted in transit (HTTPS/SSH) +- Safe to sync sensitive credentials +- Enables cross-machine access + +**What's NOT synced:** +- `.env` files (gitignored) +- API virtual environment (api/venv/) +- Database files (local development) +- Temporary files (*.tmp, *.log) +- node_modules/ directories + +--- + +## Integration with Other Commands + +### After /checkpoint +User can run `/sync` after `/checkpoint` to push the checkpoint to Gitea: +``` +User: /checkpoint +Claude: [Creates git commit] + +User: /sync +Claude: [Pushes checkpoint to Gitea] +``` + +### Before /save +User can sync first to see latest context: +``` +User: /sync +Claude: [Shows latest session logs] + +User: /save +Claude: [Creates session log with full context] +``` + +### With /context +Syncing ensures `/context` has complete history: +``` +User: /sync +Claude: [Syncs all session logs] + +User: /context Dataforth +Claude: [Searches complete session log history including other machines] +``` + +--- + +## Frequency Recommendations + +**Daily:** Start of work day +- Pull overnight changes +- See what was done on other machines +- Recover latest context + +**After Major Work:** End of coding session +- Push session logs +- Share context across machines +- Backup to Gitea + +**Before Switching Machines:** +- Push all local changes +- Ensure other machine can pull +- Seamless transition + +**Weekly:** General maintenance +- Keep repos in sync +- Review session log history +- Clean up if needed + +--- + +## Troubleshooting + +### "Already up to date" but files seem out of sync +```bash +# Force status check +cd ~/ClaudeTools +git fetch origin +git status +``` + +### "Divergent branches" error +```bash +# Rebase local changes on top of remote +git pull origin main --rebase +``` + +### Lost uncommitted changes +```bash +# Check stash +git stash list + +# Recover if needed +git stash pop +``` + +--- + +**Created:** 2026-01-21 +**Purpose:** Bidirectional sync for seamless multi-machine ClaudeTools workflow +**Repository:** https://git.azcomputerguru.com/azcomputerguru/claudetools.git +**Status:** Active - comprehensive sync with context preservation