# Syncing Claude Code Automation Across Projects

**Category**: Automation, DevOps, Best Practices
**Use Case**: Maintaining consistent automation across organization projects

## The Problem

You've set up amazing Claude Code automation in one project:
- 162 pre-approved permissions for frictionless development
- PostToolUse hooks for automatic PR iteration
- Scripts for PR review checking
- Slash commands like `/iterate-pr`
- Beautiful configuration

But now you have a problem:
- Other projects don't have this automation
- Manually copying files is error-prone
- Updates need to be propagated to all projects
- Team members have inconsistent setups

## The Solution

Use the **persuade CLI** to treat the persuade repository as a **template** for automation.

```bash
pip install persuade

cd ~/projects/my-app
# Preview what would change
persuade sync --dry-run .

# Apply the sync
persuade sync .
```

## How It Works

The sync tool is **intelligent** about what to sync:

### Files Always Synced (Overwrite)
- `commands/*.md` - Slash commands
- `hooks/*.sh` - Hook scripts
- `scripts/*.sh` - Automation scripts
- `prompts/*.md` - AI instruction templates

**Why:** These should match the template for consistency

### Settings Merged (Union Mode)
- `settings.json` - Permissions and hooks are **merged**
- Your custom permissions are **preserved**
- Template permissions are **added**

**Example:**
```
Before sync:
  Your project: "Bash(npm run custom-script)"
  Template: "Bash(git :*)", "Bash(npm test)"

After sync:
  Result: All three permissions present!
```

### Files Never Touched
- `settings.local.json` - Your personal overrides
- `state/` - Runtime state
- `logs/` - Debug logs

**Why:** Project-specific or temporary

## Key Features

### 1. Automatic Backups

Every sync creates a timestamped backup:
```bash
Creating backup...
✓ Backup created: 20251204_094915
```

Stored in `.claude/.backup/` - rollback anytime:
```bash
persuade rollback .
```

### 2. Dry Run (Preview Changes)

**Always run dry-run first on important projects:**
```bash
persuade sync --dry-run .
```

Output shows exactly what would change:
```
Files to be added:
  + hooks/post-pr-create.sh
  + commands/iterate-pr.md

Permissions added:
  + Bash(git :*)
  + Bash(gh pr create :*)

Hooks added:
  + PostToolUse

Summary:
  Files added: 12
  Permissions added: 89
```

### 3. Smart Merging

**Union Mode (default):**
- Adds template permissions
- Preserves your custom permissions
- Safe for updates

**Strict Mode:**
- Enforces template-only permissions
- Removes custom permissions
- Use for controlled environments

```bash
# Preview strict mode
persuade sync --strict --dry-run .

# Apply strict mode (after review)
persuade sync --strict .
```

### 4. Validation

Automatic post-sync validation:
- JSON syntax check
- Executable permissions on scripts
- Dependency verification
- Permission pattern validation

### 5. Rollback on Errors

If something goes wrong:
```
Sync failed: Invalid JSON syntax
Attempting rollback...
✓ Rollback completed
```

## Common Workflows

### Fresh Project Onboarding

```bash
cd ~/projects/new-project

# 1. Preview
persuade sync --dry-run .

# 2. Install
persuade sync .

# 3. Verify
persuade help-command .
```

### Updating Existing Projects

```bash
# See what's new in the template
pip install --upgrade persuade

# Update all your projects
cd ~/projects/app-1 && persuade sync .
cd ~/projects/app-2 && persuade sync .
cd ~/projects/app-3 && persuade sync .
```

### Batch Update Script

```bash
#!/bin/bash
# sync-all.sh - Update all projects with latest automation

PROJECTS=(
  ~/projects/backend-api
  ~/projects/frontend-app
  ~/projects/mobile-app
)

for project in "${PROJECTS[@]}"; do
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo "Syncing: $project"
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

  cd "$project"
  if persuade sync .; then
    echo "✓ Success"
  else
    echo "✗ Failed - manual intervention needed"
  fi
  echo
done
```

### Health Check

```bash
# Check for configuration issues
persuade doctor .

# Auto-fix common issues
persuade doctor --fix .
```

## When to Sync

### DO Sync When:
- Starting a new project
- Template repository has been updated
- You want to adopt new best practices
- Fixing configuration issues
- Onboarding new team members

### BE CAREFUL When:
- Project has significant custom automation
- You're using strict mode
- Team is actively working (coordinate timing)

### Pro Tips:
- Run `--dry-run` first on production projects
- Sync during low-activity periods
- Communicate changes to team
- Keep backups enabled (default)
- Document custom permissions in project README

## Real-World Example

**Scenario:** You improved the PR iteration workflow and want to share it with all projects.

```bash
# 1. Template updates are released via pip
pip install --upgrade persuade

# 2. Test on development project first
cd ~/projects/dev-app
persuade sync --dry-run .
persuade sync .

# 3. Verify it works
# ... test the improved workflow ...

# 4. Roll out to all projects
for proj in ~/projects/*/; do
  cd "$proj"
  persuade sync .
done
```

## Troubleshooting

### "Not inside a git repository"

**Problem:** Running outside a git repository

**Fix:**
```bash
# Initialize git if needed
git init

# Or use --allow-non-git flag (not recommended)
persuade sync --allow-non-git .
```

### "Permission denied" on scripts

**Problem:** Scripts lost executable permissions

**Fix:**
```bash
# Auto-fix
persuade doctor --fix .
```

### Want to undo changes

**Solution:** Rollback to automatic backup
```bash
# List backups
persuade rollback --list .

# Restore latest
persuade rollback .

# Restore specific backup
persuade rollback --timestamp 20251204_094915 .
```

## Best Practices

### 1. Template Repository as Source of Truth

The persuade repository should be:
- Well-maintained and tested
- Version controlled
- Reviewed before merging changes
- Documented

### 2. Test Before Wide Rollout

```bash
# 1. Test on dev project
cd ~/projects/dev-test && persuade sync .

# 2. Verify functionality
# ... run tests ...

# 3. Roll out to staging
cd ~/projects/staging && persuade sync .

# 4. Finally to production projects
for proj in ~/projects/prod-*/; do
  cd "$proj" && persuade sync .
done
```

### 3. Document Custom Permissions

In project README:
```markdown
## Claude Code Custom Permissions

This project has the following custom permissions beyond the template:
- `Bash(npm run custom-deploy)` - Deploy to staging environment
- `Bash(docker compose :*)` - Docker operations
```

### 4. Regular Sync Schedule

Set up recurring syncs:
```bash
# Weekly cron job
0 0 * * 0 /path/to/sync-all-projects.sh
```

Or use GitHub Actions to notify when template updates.

### 5. Version Control Integration

Add to project's `.gitignore`:
```gitignore
# Claude Code - synced from template (don't commit local changes)
.claude/commands/
.claude/hooks/
.claude/scripts/
.claude/prompts/

# But DO commit project-specific settings
!.claude/settings.local.json
```

## Key Takeaway

**The persuade CLI enables "Infrastructure as Code" for Claude Code automation.**

Instead of manually maintaining `.claude/` in every project:
- Maintain it once in the template repository
- Sync updates to all projects with one command
- Ensure organizational consistency
- Preserve project-specific customizations
- Automatic backups and rollback

This approach:
- Saves countless hours of manual work
- Prevents configuration drift
- Ensures best practices propagate
- Makes onboarding new projects trivial
- Keeps your entire organization in sync

**See full documentation:** [docs/syncing-automation.md](../../docs/syncing-automation.md)
