Repo Updater

Bash CLI for synchronizing dozens or hundreds of GitHub repositories with AI-assisted code review and agent-sweep for uncommitted changes.

Critical Concepts

Concept	Rule
Git plumbing only	Never parse human-readable output; use `rev-list`, `status --porcelain`, `rev-parse`
Stream separation	Human-readable → stderr; data → stdout (`--json 2>/dev/null \| jq`)
No global `cd`	All git operations use `git -C`

Command	Purpose
`ru sync`	Sync all configured repos (add `-j8` for parallel)
`ru sync --dry-run`	Preview what would happen
`ru sync --resume`	Resume interrupted sync
`ru status`	Read-only check of all repos
`ru add owner/repo`	Add repo to sync list
`ru remove owner/repo`	Remove from list
`ru list`	Show configured repos
`ru prune`	Detect orphaned repos
`ru doctor`	System health check
`ru review --plan`	Discover issues/PRs for AI review
`ru review --apply --push`	Apply reviewed changes
`ru agent-sweep`	Process repos with uncommitted changes
`ru agent-sweep -j4`	Parallel agent processing

Factor	Points	Logic
Type	0-20	PRs: +20, Issues: +10, Draft PRs: -15
Labels	0-50	security/critical: +50, bug/urgent: +30
Age (bugs)	0-50	>60 days: +50, >30 days: +30
Recency	0-15	Updated <3 days: +15, <7 days: +10
Staleness	-20	Recently reviewed: -20

Levels: CRITICAL (≥150), HIGH (≥100), NORMAL (≥50), LOW (<50)

Phase	Default Timeout	Action
1: Planning	300s	Analyze uncommitted changes, generate commit plan
2: Commit	600s	Validate plan, stage files, create commit, quality gates
3: Release	300s (opt-in)	Determine version bump, create tag/release

Execution modes: agent (full workflow), plan (phase 1 only), apply (phase 2+3)

Strategy	Behavior
`ff-only`	Fast-forward only; fails if diverged (default)
`rebase`	Rebase local commits on top of remote
`merge`	Create merge commit if needed

Code	Meaning
0	All repos processed successfully
1	Some repos failed
2	Conflicts or quality gate failures
3	System/dependency error
4	Invalid arguments
5	Interrupted (use `--resume`)

Variable	Default	Description
`RU_PROJECTS_DIR`	`/data/projects`	Base directory for repos
`RU_LAYOUT`	`flat`	Path layout (flat, owner-repo, full)
`RU_PARALLEL`	`1`	Parallel workers
`RU_TIMEOUT`	`30`	Network timeout (seconds)
`RU_UPDATE_STRATEGY`	`ff-only`	Pull strategy
`GH_TOKEN`	(from gh CLI)	GitHub token

Mistake	Correct Pattern
Parsing human-readable git output (e.g., `git status` text)	Use git plumbing: `rev-list`, `status --porcelain`, `rev-parse`
Using `cd` to change into repo directories	Use `git -C <path>` for all git operations
Mixing data and human-readable output on the same stream	Data goes to stdout, human-readable to stderr (`--json 2>/dev/null \| jq`)
Running sync without `--dry-run` first on unfamiliar repos	Always preview with `ru sync --dry-run` before executing
Using `service_role` key or bypassing auth in agent-sweep scripts	Follow security guardrails; agent-sweep has preflight checks for a reason

Discover which repos have uncommitted changes or are out of sync: Use Explore agent to run ru status and analyze the output
Process dirty repos with agent-sweep across multiple repositories: Use Task agent to run ru agent-sweep -j4 and handle quality gate failures
Plan a multi-repo sync strategy with review prioritization: Use Plan agent to design sync order, parallelism settings, and review budget allocation

Commands — sync, status, repo management, diagnostics, output modes, jq examples
Review System — two-phase workflow, session drivers, cost budgets, priority scoring
Agent Sweep — three-phase workflow, preflight checks, security guardrails, execution modes
Configuration — XDG directory structure, repo list format, layout modes, per-repo config
Troubleshooting — common issues, debug mode, preflight failure debugging, integration points