Ru Multi Repo Workflow

ru Multi-Repo Workflow

Core Insight: ru automates the mechanical. Your job is judgment: substantive merge conflicts, scope creep decisions, canonical version selection. If it doesn't require human judgment, it should just happen.

Quick Start

# Health check
ru doctor && gh auth status

# Phase 1: Commit dirty repos
ru status --json | jq '[.repos[] | select(.dirty)]'  # Find dirty
cd /data/projects/REPO && cat AGENTS.md README.md     # Understand
git add FILES && git commit -m "MSG" && git push      # Commit

# Phase 2: Sync all repos
ru sync -j4                                           # Parallel sync
git log --oneline HEAD...origin/main                  # See divergence

# Phase 3: Review issues/PRs
ru review --dry-run                                   # See open items
gh issue view NUMBER -R owner/repo                    # Investigate

# Phase 4: Release & Monitor (for repos with GH Actions)
ls .github/workflows/*.yml 2>/dev/null && echo "Has CI"  # Detect
gh run list --limit 5                                     # Recent runs
gh run watch                                              # Monitor live

The 4 Phases

Always run in order. Can't release if not committed. Can't review if not synced.

What to Surface vs Just Handle

Phase 1: Smart Commits

The only rule: Understand before committing. 2 minutes reading AGENTS.md saves 20 minutes of confusion.

ru status --json 2>/dev/null | jq -r '.repos[] | select(.dirty) | .name'
cd /data/projects/REPO && cat AGENTS.md README.md
git add path/to/related/files && git commit -m "$(cat <<'EOF'
Why this change exists (not what changed)

- Specific detail 1
- Specific detail 2

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
git push

Deep dive: PHASE1-COMMITS.md | Prompt: PROMPTS.md

Phase 2: Smart Sync

Key insight: "Canonical" ≠ "Latest". Manual diff required—this cannot be mechanically determined.

ru sync -j4
git log --oneline HEAD...origin/main  # See divergence
git diff HEAD origin/main             # See actual changes

SURFACE FORMAT: Conflicts

🚨 CONFLICT REQUIRING JUDGMENT: repo_name

Local (abc123): Refactored auth to use JWT
Remote (def456): Refactored auth to use sessions

Options:
1. Keep local (JWT approach)
2. Keep remote (session approach)
3. Manual merge

Which aligns with project direction?

Deep dive: PHASE2-SYNC.md | Prompt: PROMPTS.md

Phase 3: Issue/PR Review

Key insight: Never trust user reports blindly. Independent verification required.

ru review --dry-run --json 2>/dev/null | jq '[.items[] | select(.created_at >= "2025-01-01")]'
gh issue view NUMBER -R owner/repo
gh pr diff NUMBER -R owner/repo  # THE INTEL

SURFACE FORMAT: Scope Decisions

🤔 FEATURE REQUEST: owner/repo#42 — "Add support for X"

User's problem: [What they're trying to do]

Analysis:
+ Would help users doing Y
- Maintenance burden
- Could lead to scope creep

Options:
1. Implement as requested
2. Implement simpler version
3. Decline

My recommendation: [X] because [reason]

Deep dive: PHASE3-REVIEW.md | Prompt: PROMPTS.md

Phase 4: Release & Monitor

Key insight: Push triggers CI. Watch until green. Iterate on failures—don't leave broken.

Detection: Which Repos Have CI?

# Check for workflows
ls .github/workflows/*.yml 2>/dev/null

# Check for release workflow specifically
grep -l "release\|tag" .github/workflows/*.yml 2>/dev/null

The Monitor Loop

# 1. See recent runs
gh run list --limit 5

# 2. Watch active run (blocks until complete)
gh run watch

# 3. If failed: get logs, diagnose, fix, push, repeat
gh run view RUN_ID --log-failed
# ... fix the issue ...
git add . && git commit -m "fix: CI issue" && git push
gh run watch  # Monitor the fix

What NOT to Commit (Ephemeral Filter)

SURFACE FORMAT: Persistent CI Failure

🔴 CI FAILING: owner/repo — Run #12345

Failure: [test name or step]
Error: [key error message]

Attempted fixes:
1. [What you tried]
2. [What you tried]

This may require judgment:
- [ ] Is this a flaky test?
- [ ] Is this a real regression?
- [ ] Is this environment-specific?

Logs: gh run view 12345 --log-failed

Deep dive: PHASE4-RELEASE.md | Prompt: PROMPTS.md

References

Scripts

Validation

./scripts/validate.sh  # Full health check