dubstack

name	dubstack
description	Use when managing stacked branch workflows with DubStack, including create/modify, navigation, sync/restack, submit, PR opening, and recovery.

DubStack CLI Skill

Use this skill whenever the user is working in a repo that uses dub for stacked diffs.

Core Concepts

• Stack: A chain of dependent branches (main -> feat/a -> feat/b)
• Root: Trunk branch for a stack (commonly main)
• Restack: Rebase branches so each child is based on its updated parent
• Submit: Push stack branches and create/update PRs

Fast Command Map

Intent	Command
Create branch	dub create <name>
AI create	dub create --ai
Create + commit	dub create <name> -am "msg"
AI full flow	dub flow --ai -a / dub f --ai -a
Modify current branch	dub modify / dub m
Navigate stack	dub up, dub down, dub top, dub bottom
Interactive checkout	dub checkout / dub co
View stack	dub log / dub ls
View current stack only	dub log --stack
Sync with remote	dub sync
Rebase stack	dub restack
Continue interrupted op	dub continue
Abort interrupted op	dub abort
Track/re-parent branch	dub track [branch] --parent <branch>
Untrack metadata only	dub untrack [branch] [--downstack]
Stack-aware delete	`dub delete [branch] [--upstack
Show parent/children/trunk	dub parent, dub children, dub trunk
Submit PR stack	dub submit / dub ss
AI PR description	dub submit --ai
Open PR in browser	`dub pr [branch
Undo / redo	dub undo / dub redo (multi-level, 20-entry ring)
Ask AI assistant	dub ai ask "..."
AI conflict help	dub ai resolve / dub continue --ai

Command Notes

Create

dub create feat/x
dub create feat/x -m "feat: ..."
dub create feat/x -am "feat: ..."
dub create feat/x -um "feat: ..."
dub create feat/x -pm "feat: ..."

• -a: stage all
• -u: stage tracked-file updates
• -p: interactive hunk staging
• staging flags require -m

AI create mode:

dub create --ai
dub create -ai
dub create --no-ai feat/x

• --ai generates both branch name and commit message from staged changes.
• --no-ai overrides repo AI defaults for a single invocation.
• if a repo commit template is configured via git config commit.template, AI create preserves that structure in the generated commit body.

Modify

dub m
dub m -c -m "fix: ..."
dub m -p
dub m -u
dub m -v
dub m -vv
dub m --interactive-rebase

• Restacks descendants after modification.
• -m can be passed multiple times.
• -v prints staged diff, -vv also prints unstaged diff.

Checkout and Navigation

dub co
# or
dub checkout --stack
dub checkout --show-untracked
dub checkout --trunk

dub up
dub up 2
dub down
dub down --steps 2
dub top
dub bottom

Sync, Restack, Submit, PR

dub sync
dub sync --all
dub sync --no-interactive
dub sync --force
dub sync --no-restack

dub restack
dub restack --continue
dub continue
dub abort

dub ss
dub submit
dub submit --upstack
dub submit --stack
dub submit --branch feat/api
dub submit --dry-run
dub submit --ai
dub submit --no-ai
dub submit --merge-when-ready
dub submit --merge-when-ready --method squash
dub flow --ai -a
dub f --dry-run

dub pr
dub pr feat/a
dub pr 123

Track, Untrack, Delete

dub track
dub track feat/a --parent main

dub untrack feat/a
dub untrack feat/a --downstack

dub delete feat/a
dub delete feat/a --upstack
dub delete feat/a --downstack
dub delete feat/a --force --quiet

Orientation

dub parent
dub children
dub trunk

Recommended Workflow

1. Start from trunk: git checkout main && git pull
2. Create layers with dub create ... -am ...
3. Inspect stack with dub log
4. Submit with dub ss
5. Iterate with dub m ... and dub ss
6. Keep updated with dub sync (or dub restack when needed)

AI Setup

# choose a provider and enter your key via a masked prompt
# (keys passed as CLI flags would leak into shell history)
dub ai setup

dub config ai-assistant on
dub config ai-defaults create on
dub config ai-defaults submit on
dub config ai-defaults flow on

Precedence:

1. command flag such as --ai or --no-ai
2. repo-local dub config ai-defaults ...
3. built-in fallback of off

AI Workflow

Manual path:

1. stage changes
2. run dub create <name> -am "type: summary"
3. run dub submit

AI-assisted path:

1. stage changes or use -a, -u, or -p
2. run dub flow --ai
3. review the rendered branch, commit, and PR previews
4. approve or edit
5. let DubStack create and submit

Notes:

• In non-interactive terminals, add -y because dub flow approval prompts require a TTY.
• dub ai ask streams response text live and renders tool/status lines separately in TTY output.

Template Setup

If a repo wants DubStack AI to follow existing formatting, set up templates first.

Pull request templates:

• .github/pull_request_template.md
• .github/PULL_REQUEST_TEMPLATE.md
• .github/PULL_REQUEST_TEMPLATE/*.md
• docs/pull_request_template.md
• pull_request_template.md

Commit message templates:

cat <<'EOF' > .gitmessage
feat(scope): summary

## Testing
- [ ] added coverage
EOF

git config commit.template .gitmessage

Notes:

• PR titles still come from the last commit message.
• AI-generated PR descriptions preserve repo PR template structure when present.
• AI-generated commit bodies preserve repo commit template structure when present, but the first line still needs to be a valid Conventional Commit subject.

Recovery Patterns

Restack conflict

# after conflict
git add <resolved-files>
dub restack --continue

Undo mistaken create/restack

dub undo

Branch not tracked

• Track branch explicitly:

dub track <branch> --parent <parent>

• Verify placement:

dub parent <branch>
dub trunk <branch>

Common Errors

Symptom	Action
gh CLI not found	Install gh
Not authenticated with GitHub	gh auth login
branch missing from stack	Use dub create from tracked context
sync skips branches	rerun with interactive mode or --force if appropriate

References

• Command Reference
• Workflow Reference