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

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 --dry-run
dub submit --ai
dub submit --no-ai
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

dub ai env --gemini-key "<your-key>"
# or
dub ai env --gateway-key "<your-key>"

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

References

• Command Reference
• Workflow Reference