# Multi-Repo Coordination

> Managing cross-repo operations (sync, backup, commit, push) in a multi-repo workspace.

## When to Use

- Working across 3+ repos that share dependencies
- Starting a work session (sync all repos to latest)
- Ending a work session (commit + backup all repos)
- After a shared package change that affects consumers

## The Pattern

Organize cross-repo operations as **workflows with the `repo_` prefix**:

| Workflow                  | What it does                 | When to run                |
| ------------------------- | ---------------------------- | -------------------------- |
| `repo_sync-repos`         | Pull latest from origin main | Start of session           |
| `repo_commit-workspace`   | Commit all dirty repos       | End of session             |
| `repo_backup-main-branch` | Create backup/\* branches    | Before risky changes       |
| `repo_push-repos`         | Push main to origin          | After commits are verified |

## Core Workflows

### Sync All Repos

```bash
#!/bin/bash
# sync-repos.sh
REPOS_ROOT="$HOME/code/mygh"
REPOS=(
  "learning_ai_common_plat"
  "learning_voice_ai_agent"
  "learning_multimodal_memory_agents"
  "learning_ai_clock"
  "learning_ai_fastgap"
)

for repo in "${REPOS[@]}"; do
  echo "=== Syncing $repo ==="
  cd "$REPOS_ROOT/$repo" || continue

  # Stash if dirty
  DIRTY=$(git status --porcelain)
  if [ -n "$DIRTY" ]; then
    echo "  Stashing changes..."
    git stash push -m "auto-stash before sync"
  fi

  git pull origin main --rebase

  if [ -n "$DIRTY" ]; then
    echo "  Restoring stash..."
    git stash pop
  fi

  echo "  Done."
done
```

### Backup Main Branches

```bash
#!/bin/bash
# backup-main.sh — Creates backup/main-YYYY-MM-DD branches
DATE=$(date +%Y-%m-%d)

for repo in "${REPOS[@]}"; do
  cd "$REPOS_ROOT/$repo" || continue

  BRANCH="backup/main-$DATE"
  if git show-ref --verify --quiet "refs/heads/$BRANCH"; then
    echo "  $repo: $BRANCH already exists (skipping)"
  else
    git branch "$BRANCH" main
    echo "  $repo: Created $BRANCH"
  fi
done
```

**Important:** Backup does NOT push to remote or modify main. It only creates local backup branches.

### Commit All Repos

For AI agent-driven commits:

```
For each repo with uncommitted changes:
1. Run `git diff --stat` to understand changes
2. Generate a commit message from the diff:
   - feat(scope): description — for new features
   - fix(scope): description — for bug fixes
   - docs: description — for documentation
   - refactor(scope): description — for refactoring
3. git add -A && git commit -m "<message>"
4. Report what was committed
```

### Push All Repos

```bash
#!/bin/bash
# push-repos.sh
for repo in "${REPOS[@]}"; do
  cd "$REPOS_ROOT/$repo" || continue

  # Check if there are commits to push
  AHEAD=$(git rev-list --count origin/main..main 2>/dev/null)
  if [ "$AHEAD" -gt 0 ]; then
    echo "  $repo: Pushing $AHEAD commits..."
    git push origin main
  else
    echo "  $repo: Already up to date"
  fi
done
```

## Dependency Order

When repos depend on each other, operations must follow dependency order:

```
1. learning_ai_common_plat      ← Shared packages (build FIRST)
2. learning_voice_ai_agent      ← Consumes @bytelyst/* packages
3. learning_multimodal_memory_agents ← Consumes @bytelyst/* packages
4. learning_ai_clock             ← Uses platform-service API
5. learning_ai_fastgap           ← Uses platform-service API
```

**After changing a shared package:**

```bash
# 1. Build shared packages
cd learning_ai_common_plat && pnpm build

# 2. Update consumers
cd ../learning_voice_ai_agent/admin-dashboard-web && npm install
cd ../learning_voice_ai_agent/user-dashboard-web && npm install
```

## Health Check Script

A quick script to check status across all repos:

```bash
#!/bin/bash
# repo-status.sh
echo "=== Repo Status ==="
printf "%-40s %-10s %-10s %-10s\n" "REPO" "BRANCH" "DIRTY" "AHEAD"

for repo in "${REPOS[@]}"; do
  cd "$REPOS_ROOT/$repo" || continue
  BRANCH=$(git branch --show-current)
  DIRTY=$(git status --porcelain | wc -l | tr -d ' ')
  AHEAD=$(git rev-list --count origin/main..main 2>/dev/null || echo "?")
  printf "%-40s %-10s %-10s %-10s\n" "$repo" "$BRANCH" "$DIRTY" "$AHEAD"
done
```

## Anti-Patterns

- **Manual sync one repo at a time** — Automate it
- **Forgetting to build shared packages before consumer install** — Dependencies break
- **Pushing without verifying** — Always run tests first
- **No backups before risky operations** — One bad rebase can lose work
- **Cross-repo changes in wrong order** — Shared packages first, consumers second

## Related Skills

- [04 — Workflow Definitions](./04-workflow-definitions.md)
- [14 — Shared Package Extraction](./14-shared-packages.md)
- [18 — Environment & Secrets Management](./18-environment-management.md)
