PAIR-code/deliberate-lab / .agents/skills/workspace-sync
workspace-sync
VerifiedDeterministic synchronization of trunk, PR evaluation worktrees, and drift reporting in Deliberate Lab's bare repository workspace.
Workspace Sync
Synchronize all branches and worktrees in Deliberate Lab's bare repository layout against upstream and origin.
This skill replaces manual, multi-step git operations with a single deterministic automation script that fast-forwards trunk, mirrors PR evaluation worktrees, identifies merged/closed PRs for cleanup, and reports feature branch drift.
When to use
Invoke this skill when asked to:
- "Sync workspace"
- "Update all PR worktrees"
- "Pull latest changes"
- "Catch up with upstream"
- "Check branch drift"
- "Sync my fork"
Procedure
1. Run the Synchronization Script
From any worktree directory or the parent repository container:
./.agents/skills/workspace-sync/scripts/workspace-sync.sh
To preview changes without altering any git refs or worktree checkouts:
./.agents/skills/workspace-sync/scripts/workspace-sync.sh --dry-run
To only sync trunk and feature branch status without touching PR worktrees:
./.agents/skills/workspace-sync/scripts/workspace-sync.sh --skip-pr-mirror
The script visibly echoes the underlying git commands by default (prefixed with [dry-run] during dry-run mode) and formats all worktree targets with actionable relative paths. If the sync report exceeds 7 KB, it automatically saves to a temporary file via mktemp and provides the path for lossless inspection via view_file (ADR 0003).
2. Understanding the Execution Phases
The script executes four deterministic stages:
- Remote Pruning: Runs
git fetch --all --pruneto refresh all remotes and clean up deleted remote-tracking refs. - Trunk Synchronization (
main):- Ensures
main/is clean before touching it. - Fast-forwards
maintoupstream/main(git merge --ff-only upstream/main). - Pushes
maintoorigin/mainto keep your personal fork in sync.
- Ensures
- PR Worktree Mirroring (
pr-<number>):- Finds all sibling worktrees matching
pr-[0-9]*. - Safety First: Any worktree with uncommitted changes (
git status --porcelain) is skipped to prevent data loss. - Lifecycle Awareness & Automated Cleanup: Queries GitHub CLI (
gh pr view) to see if the PR isMERGEDorCLOSED. If so and the worktree is clean, automatically removes the worktree (git worktree remove) and deletes the local branch (git branch -D), keeping the workspace free of zombie checkouts. - Exact Mirroring: For open PRs, fetches
upstream pull/<number>/headand resets the local branch toFETCH_HEAD. - Dependency Notice: If
package.jsonorpackage-lock.jsonchanged during the update, reminds you to runnpm ciin that worktree.
- Finds all sibling worktrees matching
- Feature Branch Drift Awareness:
- Inspects active development branches (e.g.
<issue>-<slug>). - Reports commit counts ahead and behind
main. - If a feature branch is behind, suggests running
git rebase maininside that worktree when the author is ready.
- Inspects active development branches (e.g.
Safety Rules
- Never rebase or merge PR evaluation worktrees: External PRs must remain exact mirrors of their upstream head.
- Never clobber dirty worktrees: Any worktree with unstaged or uncommitted changes is protected and skipped.
- Do not auto-rebase active feature branches: Feature branches may be in the middle of active development or testing. The script only reports divergence; rebasing is left to the developer or agent at an intentional time.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |