Git Spice Workflow Assistant

Overview

This skill provides comprehensive support for Git Spice, a modern stacked PR workflow tool. Use this skill for:

Learning: Understanding Git Spice concepts and commands
Automation: Executing Git Spice workflows (branch creation, stacking, submission)
Troubleshooting: Resolving conflicts, fixing failed rebases, recovering from errors
Migration: Transitioning from Graphite or standard Git workflows
Best Practices: Following team conventions for commits, PRs, and stack management

Core Principles

Git Spice is a "Native Git Citizen":

Uses standard git for commits and file operations
Handles stacking logic and PR management
Integrates with GitHub CLI (gh) for PR operations
Never use deprecated gt commands - use gs for Git Spice, git for native operations

⚠️ CRITICAL: Command Verification Rule

NEVER assume Git Spice commands or syntax.

If a command or flag is not explicitly documented in this skill:

STOP - Do not guess or assume the command exists
CHECK - Fetch the live documentation: https://abhinav.github.io/git-spice/cli/reference/
VERIFY - Confirm the exact command syntax and available flags
PROCEED - Only use commands that are verified in the official docs

This rule applies to:

Command names (e.g., gs branch create vs. gs create-branch)
Flags and options (e.g., --no-commit, --fill, --force)
Subcommands and arguments
New features not listed in this skill

Examples of what NOT to do:

❌ Assuming gs branch delete exists without checking
❌ Guessing that --interactive is a valid flag
❌ Inventing command syntax based on git commands
❌ Using outdated Graphite (gt) command patterns

Examples of correct behavior:

✅ "Let me verify this command in the Git Spice docs first"
✅ Fetching https://abhinav.github.io/git-spice/cli/reference/ to confirm
✅ Using only commands explicitly listed in this skill or verified online
✅ Asking user for clarification if docs are unclear

When to Use This Skill

Questions & Learning

"How do I create a stacked PR?"
"What's the difference between gs bc and gs bs?"
"How do I fix a branch in the middle of my stack?"
"What's the Git Spice equivalent of git rebase -i?"

Workflow Automation

Creating branches and commits following team conventions
Submitting stacks with proper PR descriptions
Restacking after changes to lower branches
Syncing and cleaning up merged branches

Troubleshooting

Resolving rebase conflicts in stacked branches
Recovering from failed gs sr operations
Fixing broken stack relationships
Handling authentication issues with GitHub

Team Collaboration

Reviewing stack status before merging
Understanding dependencies between PRs
Coordinating merges in the correct order
Managing long-running feature stacks

Quick Command Reference

See CHEATSHEET.md for comprehensive command guide.

⚠️ Important: Commands listed here are verified as of this documentation. For the latest commands and flags, always check: https://abhinav.github.io/git-spice/cli/reference/

Essential Commands

Command	Alias	Purpose
`gs branch create <name>`	`gs bc`	Create new branch in stack
`gs branch create --no-commit <name>`	`gs bc --no-commit`	Create branch without auto-committing
`gs stack submit`	`gs ss`	Submit entire stack (create/update PRs)
`gs branch submit`	`gs bs`	Submit only current branch
`gs stack restack`	`gs sr`	Rebase stack after changes
`gs repo sync`	`gs rs`	Pull trunk, delete merged branches
`gs up`	`gs u`	Navigate to child branch
`gs down`	`gs d`	Navigate to parent branch
`gs log`	`gs l`	Visualize stack tree
`gs stack edit`	`gs se`	Interactive reorder/squash

Common Workflows

1. Creating a New Stack

# Start fresh
gs rs

# Create first branch
gs bc feat/api-changes
git add .
git commit -m "feat: update api schema"

# Stack second branch on top
gs bc feat/ui-integration
git add .
git commit -m "feat: integrate new api in ui"

# Submit all PRs
gs ss --fill

2. Fixing a Branch in the Middle

# Navigate to the branch that needs changes
gs down  # or: git checkout feat/api-changes

# Make fixes
git add .
git commit --amend --no-edit

# Restack children
gs sr

# Update PRs
gs ss

3. Handling Merge Conflicts During Restack

# Attempt restack
gs sr

# If conflicts occur:
# 1. Git will pause and show conflicted files
# 2. Resolve conflicts in your editor
# 3. Stage resolved files: git add <file>
# 4. Continue: git rebase --continue
# 5. Retry: gs sr

4. Cleaning Up After Merge

# Merge PR on GitHub (bottom of stack first)
gh pr merge --squash

# Sync locally
gs rs

# Check remaining stack
gs log

Automation Protocol for AI Agents

When automating Git Spice workflows:

Phase 1: Pre-flight Checks

Verify staged changes exist: git diff --cached --quiet (should return 1)
Check authentication: gh auth status
Verify current branch: git branch --show-current
Check stack status: gs log

Phase 2: Propose Actions

Present recommendations to user:

Branch name (following team conventions)
Commit message (Conventional Commits format)
Stack strategy (new stack vs. add to existing)
PR description

Phase 3: Execute (After Approval)

CRITICAL: Execute commands one at a time, no chaining.

Create Branch:

gs branch create --no-commit <branch-name>

Commit Changes:

# Write commit message to temp file
cat > commit-message.txt << 'EOF'
<message>
EOF

# Commit using file
git commit -F commit-message.txt

# Clean up
rm commit-message.txt

Submit Stack:
```
gs stack submit --fill
```

Update PR Body (if needed):

# Write enhanced description
cat > pr-body.md << 'EOF'
<description>
EOF

# Update PR
gh pr edit --body-file pr-body.md

# Clean up
rm pr-body.md

Phase 4: Verify & Report

Confirm PR created: gh pr view
Show stack status: gs log
Provide next steps

Troubleshooting Guide

"Cannot create branch: working directory has uncommitted changes"

Solution: Stash or commit changes first:

git stash
gs bc <branch-name>
git stash pop

Or use force flag:

gs bc --force <branch-name>

"Rebase conflict detected"

Solution: Manual resolution required:

Edit conflicted files
git add <resolved-files>
git rebase --continue
gs sr (retry restack)

"PR already exists for this branch"

This is normal! Git Spice updates existing PRs. Use:

gs ss  # Updates all PRs in stack

"Authentication required"

Solution: Authenticate GitHub CLI:

gh auth login

"Branch relationship broken"

Solution: Rebuild stack manually:

# Check current state
gs log

# Checkout parent branch
git checkout main

# Create new stack starting from parent
gs bc --parent main <branch-name>

Integration with Team Conventions

This skill works in conjunction with:

create-pr prompt (.github/prompts/pr.prompt.md): For standardized commit/PR format
Conventional Commits: Enforced commit message format
Azure DevOps Integration: Magic links (AB#, Fixes AB#)
Story Artifacts: Discovering and using story.md, spec.md, tasks.md

When automating PR creation:

Use this skill for Git Spice operations
Follow create-pr prompt for commit/PR conventions
Integrate story artifacts when available

Advanced Scenarios

Reordering Branches in Stack

# Interactive stack editor
gs stack edit

# Reorder like git rebase -i:
# - Move lines to reorder
# - Change 'pick' to 'squash' to combine
# Save and close

Cherry-picking Changes Between Branches

# Standard git cherry-pick works
git checkout target-branch
git cherry-pick <commit-sha>

# Then restack if needed
gs sr

Working with Multiple Stacks

# Each stack starts from trunk
git checkout main
gs bc feat/stack-one-base

# Later, create independent stack
git checkout main
gs bc feat/stack-two-base

# View all stacks
gs log --all

Splitting a Branch

# On branch to split
git reset HEAD~1  # Unstage last commit

# Create new branch for subset of changes
gs bc feat/split-feature
git add <subset-of-files>
git commit -m "feat: part one"

# Return to original and commit rest
gs down
git add .
git commit -m "feat: part two"

✅ VERIFY all commands in https://abhinav.github.io/git-spice/cli/reference/ if not explicitly listed in this skill

❌ Never bypass git hooks without explicit permission
❌ Never force push without discussing with user
❌ Never delete branches without confirmation
❌ Never use deprecated gt commands
❌ Never assume or guess Git Spice command syntax. Keep stacks 3–5 branches max for easier review

Commit often: Small, focused commits are easier to restack
Test each branch: Ensure each PR can merge independently
Merge bottom-up: Merge lower branches first
Clean up regularly: gs rs after merges
Communicate dependencies: Note in PR if order matters
Use descriptive names: Branch names should indicate relationship

Documentation & Resources

Cheatsheet: (USE THIS TO VERIFY COMMANDS)
Team Templates: .github/pull_request_template.md, .github/commit_template.txt

When in doubt: Always fetch https://abhinav.github.io/git-spice/cli/reference/ to verify command syntax before suggesting or executing commands.

CLI Reference: https://abhinav.github.io/git-spice/cli/reference/
Team Templates: .github/pull_request_template.md, .github/commit_template.txt

Safety Guardrails

When automating or assisting:

✅ Run commands one at a time (no chaining with && or ;)
✅ Use temp files for multi-line input (commit messages, PR bodies)
✅ Clean up temp files after use
✅ Wait for user approval before executing risky operations
✅ Provide clear error messages and recovery steps
✅ Verify authentication before GitHub operations
✅ Check working directory is repo root
❌ Never bypass git hooks without explicit permission
❌ Never force push without discussing with user
❌ Never delete branches without confirmation
❌ Never use deprecated gt commands

Success Criteria

A successful Git Spice operation includes:

Clean command execution (no errors)
Proper stack relationships maintained
PRs created/updated on GitHub
Working directory clean (no temp files)
User understands next steps
Stack visualized and validated