# Workflow Synchronization Guide

> How to keep Windsurf workflows consistent across all 7 repos in the workspace.

---

## Quick Reference

| Command                                   | Purpose                            |
| ----------------------------------------- | ---------------------------------- |
| `zsh scripts/sync-workflows.sh`           | Sync common workflows to all repos |
| `zsh scripts/sync-workflows.sh --dry-run` | Preview changes without applying   |

---

## Overview

The workspace has **42 workflows** across **8 repos**. To keep cross-repo workflows (like `repo_backup-main-branch`, `repo_sync-repos`) consistent, use the sync script.

### Workflow Categories

| Category            | Prefix     | Count | Synced?                  |
| ------------------- | ---------- | ----- | ------------------------ |
| **Cross-repo**      | `repo_`    | 6     | ✅ Yes                   |
| **Product release** | `release_` | 3     | ❌ No (product-specific) |
| **Testing**         | `test_`    | 4     | ❌ No (product-specific) |
| **Utilities**       | various    | 2     | Case-by-case             |

---

## The Sync Script

### Location

```
learning_ai_common_plat/scripts/sync-workflows.sh
```

### What It Syncs

These 6 workflows are pushed from `learning_ai_common_plat/.windsurf/workflows/` to all repos:

1. `repo_backup-main-branch.md`
2. `repo_backup-and-push.md`
3. `repo_sync-repos.md`
4. `repo_commit-workspace.md`
5. `repo_update-agent-docs.md`
6. `refresh-chat-history.md`

### Target Repos

```
learning_voice_ai_agent          (LysnrAI)
learning_multimodal_memory_agents (MindLyst)
learning_ai_clock                (ChronoMind)
learning_ai_peakpulse            (PeakPulse)
learning_ai_fastgap              (NomGap)
learning_ai_jarvis_jr            (JarvisJr)
```

### How It Works

1. **Compares** source workflow (in common-plat) with destination
2. **Skips** if files are identical
3. **Copies** if destination is missing or different
4. **Reports** how many were updated vs skipped

### Output Examples

**All up to date:**

```
=== Sync complete ===
  Updated: 0
  Skipped (identical): 36

✓ All workflows are synchronized across all repos.
  No changes needed — everything is up to date.
```

**After editing a workflow:**

```
=== Sync complete ===
  Updated: 6
  Skipped (identical): 30

✓ Synced 6 workflow(s) to repos.
  Run again to verify all repos are identical.
```

---

## When to Sync

| Scenario                                   | Action                         |
| ------------------------------------------ | ------------------------------ |
| Edited a `repo_*` workflow in common-plat  | Run sync immediately           |
| New repo added to workspace                | Run sync to populate workflows |
| Workflow behaving differently across repos | Run sync to reconcile          |
| Unsure if workflows are current            | Run with `--dry-run` to check  |

---

## Workflow Naming Convention

Use these prefixes for clarity:

| Prefix     | Purpose                   | Example              |
| ---------- | ------------------------- | -------------------- |
| `repo_`    | Cross-repo Git operations | `repo_sync-repos`    |
| `release_` | Product releases          | `release_testflight` |
| `test_`    | Testing/verification      | `test_coverage`      |
| `product_` | Product-specific ops      | `product_build_ios`  |

---

## Archive Integration

The `/refresh-chat-history` workflow (which runs daily at 11 PM) also archives all workflows from all repos to:

```
__LOCAL_LLMs/AI_IDE_CHAT_HISTORY/WINDSURF/repo_workflows/
```

This provides a historical backup and cross-repo visibility.

---

## Troubleshooting

### "Source not found" warning

```
⚠ Source not found: .../repo_update-agent-docs.md
```

**Fix:** The workflow exists in the sync list but not in common-plat. Either:

- Create the missing workflow in common-plat, or
- Remove it from `WORKFLOWS_TO_SYNC` in the script

### Workflow not syncing

Check that:

1. Workflow is in `WORKFLOWS_TO_SYNC` array in the script
2. Source file exists in `learning_ai_common_plat/.windsurf/workflows/`
3. Destination `.windsurf/workflows/` directory exists (script auto-creates if missing)

### Merge conflicts in workflows

If a workflow was edited independently in two repos:

1. Decide which version is correct
2. Copy the correct version to common-plat
3. Run sync to propagate

---

## Current Workflow Inventory

| Repo             | Count | Notable Workflows                                                                                                                        |
| ---------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| LysnrAI          | 14    | release-testflight, release-desktop, test-ios-app, test-desktop-app, test-coverage, docker-compose, debug-service, generate-store-assets |
| PeakPulse        | 8     | mobile-code-quality, production-readiness, repo_push-repos                                                                               |
| ChronoMind       | 6     | repo_push-repos                                                                                                                          |
| MindLyst         | 7     | mobile-code-quality, release-testflight                                                                                                  |
| NomGap           | 6     | (baseline repo\_\* workflows)                                                                                                            |
| JarvisJr         | 6     | (baseline repo\_\* workflows)                                                                                                            |
| Common-plat      | 7     | sync-workflows.sh, refresh-chat-history, all repo\_\* workflows                                                                          |
| Agent-monitoring | 1     |                                                                                                                                          |

---

## See Also

- `/refresh-chat-history` — Archive refresh workflow
- `/repo_sync-repos` — Pull latest from all repos
- `/repo_update-agent-docs` — Regenerate AGENTS.md, CLAUDE.md, etc.