dubstack 0.3.0 → 0.5.0

package/README.md

@@ -75,10 +75,38 @@ dub log
 git checkout main && git pull
 dub restack
 
+# 4b. Sync local stack state with remote branches
+dub sync
+
+# 5. Made a mistake? Undo it
 # 5. Made a mistake? Undo it
 dub undo
 ```
 
+## Agent Skills
+
+DubStack provides skills for AI coding agents (like Cursor, Windsurf, etc.) to use the CLI effectively.
+
+You can install them easily using the `dub skills` command:
+
+```bash
+# Install all skills
+dub skills add
+
+# Install specific skill
+dub skills add dub-flow
+```
+
+Alternatively, you can install them manually via `npx`:
+
+```bash
+# Core CLI reference & workflows
+npx skills add wiseiodev/dubstack/skills/dubstack
+
+# Specialized PR creation workflow
+npx skills add wiseiodev/dubstack/skills/dub-flow
+```
+
 ## Commands
 
 ### `dub init`
@@ -205,6 +233,45 @@ Progress is saved to `.git/dubstack/restack-progress.json`, so the resume picks
 
 ---
 
+### `dub sync`
+
+Synchronizes tracked stack branches with remote refs and optionally restacks.
+
+```bash
+dub sync
+```
+
+Useful flags:
+
+```bash
+# Sync all stacks across trunks
+dub sync --all
+
+# Non-interactive safe mode (skip destructive operations)
+dub sync --no-interactive
+
+# Force overwrite/delete decisions during sync
+dub sync --force
+
+# Skip post-sync restack
+dub sync --no-restack
+```
+
+Current behavior:
+- Fetches tracked roots and branches from `origin`
+- Attempts fast-forward trunk updates (or overwrite with `--force`)
+- Cleans local branches whose PRs are `MERGED`/`CLOSED` and whose commits are
+  confirmed in trunk (interactive/force), while keeping non-cleanable stacks
+  excluded from destructive sync actions
+- Reconciles each tracked branch:
+  - restores missing local branches from remote
+  - fast-forwards branches that are safely behind remote
+  - keeps local-ahead branches
+  - prompts/skips/forces on diverged branches
+- Runs post-sync restack by default
+
+---
+
 ### `dub undo`
 
 Rolls back the last `dub create` or `dub restack` operation.