Bidirectional upstream sync

.changeset/upstream-auto-sync.md

@@ -0,0 +1,5 @@
+---
+"@bradygaster/squad-sdk": minor
+---
+
+feat: bidirectional upstream sync + auto-propagation (#357)

docs/blog/2026-03-17-upstream-sync.md

@@ -0,0 +1,128 @@
+---
+title: "Upstream Auto-Sync: Keep Squads in Sync"
+date: 2026-03-17
+author: "Squad (Copilot)"
+wave: null
+tags: [squad, sync, orchestration, parent-child, automation]
+status: published
+hero: "Upstream sync enables bidirectional change detection and synchronization between parent and child squads. Detect updates automatically, pull selectively, and propose changes back with a single command."
+---
+
+# Upstream Auto-Sync: Keep Squads in Sync
+
+> _Child squads detect parent changes automatically, pull updates selectively, and propose changes back upstream—no manual diff hunting required._
+
+## The Problem
+
+Many organizations structure squads hierarchically: a parent squad defines shared governance and patterns, while child squads inherit and customize for their teams. Today, keeping them in sync requires manual work:
+
+- Child squads periodically check if parent changed
+- No clear way to decide what to pull (skills vs. governance vs. all)
+- When child squads learn something valuable, proposing it back upstream means manual PR creation with copy-paste
+- Multiple child squads quickly drift from parent, creating inconsistency
+
+Upstream auto-sync solves this with **automatic change detection and bidirectional sync**.
+
+## How It Works
+
+### Register a Parent
+
+```bash
+squad upstream add https://github.com/org/parent-squad --name parent
+```
+
+The squad clones the parent (once) and stores metadata in `.squad/upstream.json`.
+
+### Watch for Changes
+
+```bash
+squad upstream watch --interval 10 --auto-pr
+```
+
+The watcher:
+1. Polls the parent repo every 10 seconds
+2. Hashes files in key directories (`.squad/`, `docs/`, `lib/`)
+3. Detects additions, changes, deletions
+4. Optionally creates a PR in your squad with the updates
+
+### Propose Changes Back
+
+```bash
+squad upstream propose parent --skills --decisions
+```
+
+Your squad packages its learnings (skills, decisions, or all) and creates a PR in the parent for review and merge.
+
+## Real-World Example
+
+### Monorepo Pattern
+
+An organization has:
+- **parent-squad**: Defines shared conventions, governance, and base skills
+- **team-a-squad**: Inherits from parent, customizes for Team A's workflow
+- **team-b-squad**: Inherits from parent, customizes for Team B's workflow
+
+**Day 1:** Both teams sync from parent
+```bash
+squad upstream sync parent
+```
+
+**Day 3:** Parent squad learns a valuable skill (e.g., "jest-mocking-patterns")
+- Parent updates its `.ai-team/skills/jest-mocking-patterns/SKILL.md`
+- Child squads detect the change via `squad upstream watch`
+- Child squads auto-pull the new skill
+
+**Day 5:** Team A discovers an improvement to governance
+```bash
+squad upstream propose parent --decisions
+```
+- Team A's squad creates a PR in parent with the governance update
+- Parent merges it
+- Team B detects the change and auto-pulls it next watch cycle
+
+## Configuration
+
+Upstreams live in `.squad/upstream.json`:
+
+```json
+{
+  "upstreams": [
+    {
+      "name": "parent",
+      "source": "https://github.com/org/parent-squad",
+      "ref": "main",
+      "lastSync": "2026-03-17T10:30:00Z"
+    }
+  ]
+}
+```
+
+## GitHub Actions Integration
+
+For teams using GitHub, automate the watch with a cron job:
+
+```bash
+squad upstream init-ci
+```
+
+This generates `.github/workflows/squad-upstream-sync.yml` that runs every 6 hours and auto-creates PRs when changes are detected.
+
+## Technical Design
+
+Upstream sync uses **file hashing** instead of git diff:
+
+- **Speed**: Hash-based detection is fast (no clone on every check)
+- **Flexibility**: Works with git repos, local paths, and exported squads
+- **Safety**: No merge conflicts—sync creates a PR for human review
+
+How it works:
+1. Parent is cloned to `.squad/_upstream_repos/{name}/` (once)
+2. Files in `.squad/`, `docs/`, `scripts/` are hashed
+3. Hash changed? → Create PR with the diff
+4. User reviews and merges
+
+## See Also
+
+- [Generic Scheduler](/features/generic-scheduler) — Run upstream sync as a scheduled task
+- [Cross-Squad Orchestration](/features/cross-squad-orchestration) — Delegate work across squads
+- [Persistent Ralph](/features/persistent-ralph) — Monitor all squad activity

docs/features/upstream-sync.md

@@ -0,0 +1,171 @@
+# Upstream Auto-Sync
+
+**Try this to see configured upstreams:**
+```
+squad upstream list
+```
+
+**Try this to watch for parent changes:**
+```
+squad upstream watch --interval 10 --auto-pr
+```
+
+**Try this to propose changes back:**
+```
+squad upstream propose --all
+```
+
+Upstream sync keeps your squad in sync with parent repositories. Detect changes automatically, pull them into your squad, and propose your own changes back upstream with minimal friction.
+
+---
+
+## What Upstream Sync Does
+
+Upstream sync enables **bidirectional synchronization** between parent and child squads. Register a parent repository (local path or git URL), and your squad can:
+
+1. **Detect changes** in the parent using fast file hashing
+2. **Pull updates** selectively (skills, decisions, governance, or all)
+3. **Propose changes** back to the parent repo as a pull request
+4. **Monitor continuously** with an optional GitHub Action cron job
+
+## Quick Start
+
+### Register a Parent Upstream
+
+```bash
+squad upstream add https://github.com/org/parent-squad --name parent
+```
+
+For a local path:
+```bash
+squad upstream add ../parent-squad --name local-parent
+```
+
+View registered upstreams:
+```bash
+squad upstream list
+```
+
+### Sync Now
+
+Pull updates from all registered upstreams:
+```bash
+squad upstream sync
+```
+
+Sync a specific upstream:
+```bash
+squad upstream sync parent
+```
+
+### Watch for Changes
+
+Start watching for parent changes every 10 seconds:
+```bash
+squad upstream watch --interval 10
+```
+
+Auto-create a PR when changes are detected:
+```bash
+squad upstream watch --auto-pr
+```
+
+The `watch` command runs until stopped (Ctrl+C), continuously polling for new changes.
+
+### Propose Changes Upstream
+
+Package your squad's learnings to propose back:
+
+All learnings:
+```bash
+squad upstream propose parent --all
+```
+
+Just skills and decisions:
+```bash
+squad upstream propose parent --skills --decisions
+```
+
+The proposal creates a pull request in the parent repository with your changes, formatted for easy review.
+
+## Configuration
+
+Upstreams are stored in `.squad/upstream.json`:
+
+```json
+{
+  "upstreams": [
+    {
+      "name": "parent",
+      "source": "https://github.com/org/parent-squad",
+      "ref": "main",
+      "lastSync": "2026-03-17T10:30:00Z"
+    },
+    {
+      "name": "local",
+      "source": "../parent-squad",
+      "ref": "main",
+      "lastSync": "2026-03-17T10:20:00Z"
+    }
+  ]
+}
+```
+
+- **name**: Identifier for this upstream
+- **source**: Git URL or local filesystem path
+- **ref**: Branch/tag to track (defaults to `main`)
+- **lastSync**: ISO timestamp of last successful sync
+
+## GitHub Actions Integration
+
+Automate upstream sync with a scheduled workflow:
+
+```bash
+squad upstream init-ci
+```
+
+This creates `.github/workflows/squad-upstream-sync.yml` configured to:
+- Run every 6 hours via cron
+- Sync all registered upstreams
+- Auto-create pull requests when changes found
+- Post summaries to GitHub Issues
+
+Customize the schedule and PR behavior in the generated workflow.
+
+## How Change Detection Works
+
+Upstream sync uses **file hashing** (not git diff) for fast, cross-source change detection:
+
+1. Clone/read the parent repo to `.squad/_upstream_repos/{name}/`
+2. Hash all files in key directories (`.squad/`, `docs/`, etc.)
+3. Compare hashes to last known state
+4. If changes found, optionally create PR
+
+This approach works whether the parent is:
+- A remote git repository (over HTTPS/SSH)
+- A local filesystem path
+- An exported squad (local directory)
+
+## Use Cases
+
+### Monorepo Pattern
+- Parent squad defines shared governance, patterns, and skills
+- Child squads inherit and customize
+- Run `squad upstream sync parent` when parent updates
+- Propose back when child squad learns something valuable
+
+### Distributed Teams
+- Each team has their own squad (local branch)
+- Central squad acts as coordinator
+- Cross-team discoveries flow back via `squad upstream propose`
+
+### Export & Reuse
+- Export a proven squad from one org
+- Import into new org via upstream sync
+- Continue receiving updates from original
+
+## See Also
+
+- [Cross-Squad Orchestration](/features/cross-squad-orchestration) — delegate work across squads
+- [Persistent Ralph](/features/persistent-ralph) — track squad activity
+- [Generic Scheduler](/features/generic-scheduler) — run scheduled sync tasks

packages/squad-cli/src/cli-entry.ts

@@ -198,6 +198,8 @@ async function main(): Promise<void> {
     console.log(`                    upstream remove <name>`);
     console.log(`                    upstream list`);
     console.log(`                    upstream sync [name]`);
+    console.log(`                    upstream watch [--interval N] [--auto-pr]`);
+    console.log(`                    upstream propose <name> [--skills] [--decisions] [--governance] [--all]`);
 
     console.log(`  ${BOLD}help${RESET}       Show this help message`);
     console.log(`\nFlags:`);