AI Git Workflow - User Guide

An enhanced Git workflow designed for AI-assisted development, providing safe experimentation, easy rollback, and isolated task management.

🎯 Who This Is For

• AI-assisted developers working with Claude, ChatGPT, or other AI coding assistants
• Developers new to the tool who want a safety net while experimenting
• Teams who want isolated task branches without cluttering their main repository

🚀 Quick Start

# Source the workflow script
source git-test/ai-workflow-enhanced.sh

# Get help anytime
ai_help

---

📖 Core Concepts

Why This Workflow Exists

When working with AI assistants, you often face these challenges:

Problem	Solution
AI makes breaking changes	ai_abort to rollback instantly
Many experimental iterations	ai_wip for quick saves, ai_squash to clean up
Want to try multiple approaches	ai_snap for named snapshots
Fear of losing working code	ai_checkpoint before major changes
Multiple concurrent tasks	ai_task with isolated worktrees

Three Layers of Protection

Level 1: ai_wip     - Quick commits for iterations (seconds to save)
Level 2: ai_snap    - Stash-based snapshots (preserves git history)
Level 3: ai_fssnap  - Full filesystem backup (includes untracked files)

---

🎬 Scenario 1: Classic AI-Assisted Feature Development

Scenario: You're building a new feature with AI help. The AI will iterate multiple times, and you want safety.

Step-by-Step Workflow

# 1. Start a new AI task
ai_task add-user-auth
# Output: ✓ AI task workspace ready
#         Task: add-user-auth
#         Branch: ai/add-user-auth-20250217-143022
#         Worktree: ../wt-ai-add-user-auth-20250217-143022

# You're now in an isolated worktree - safe to experiment!

# 2. Let AI work - save iterations quickly
ai_wip "initial auth scaffold"
# AI writes code... you save again
ai_wip "added login form"
# AI tries approach A...
ai_wip "attempt A - basic JWT"
# AI tries approach B...
ai_wip "attempt B - session based"

# 3. See your iteration history
ai_wip_log
# Output:
#   === Work In Progress History ===
#   Found 4 WIP commits:
#
#   0  abc1234 WIP: attempt B - session based
#   1  def5678 WIP: attempt A - basic JWT
#   2  ghi9012 WIP: added login form
#   3  jkl3456 WIP: initial auth scaffold

# 4. Decide approach B is better, but needs cleanup
# Reset to approach B and discard A
git reset --hard HEAD~2  # Go back 2 commits

ai_wip "session auth - cleaned up"

# 5. Ready to integrate? Squash into clean commits
ai_squash
# Opens interactive rebase - consolidate WIPs into:
# "feat: implement user authentication with session management"

# 6. Merge back to main branch
ai_finish main
# Output:
#   ✓ AI task completed and merged
#     Merged into: main
#     Branch deleted: ai/add-user-auth-20250217-143022
#     Worktree cleaned up

What Just Happened?

• Your main branch stayed clean throughout
• All experimental iterations were isolated in a worktree
• You can undo anytime with ai_abort
• No messy WIP commits polluted your history

---

🎬 Scenario 2: "I Broke Something" - Emergency Rollback

Scenario: AI made changes that broke your code, and you're not sure how to fix it.

Immediate Recovery

# Before starting risky AI work, create a checkpoint
ai_checkpoint "before ai refactor"
# Output: ✓ Checkpoint created: checkpoint-20250217-143022

# Let AI work...
# ... oh no, tests are failing, nothing works

# List all checkpoints
ai_abort
# Output:
#   === Tag Checkpoints (0-499) ===
#   [0] checkpoint-20250217-143022 (2 hours ago)
#   [1] checkpoint-20250217-120000 (5 hours ago)
#
#   Usage: ai_abort <number>

# Rollback to before the disaster
ai_abort 0
# Output: ✓ Reset to checkpoint-20250217-143022

# You're back to your working state!

Pro Tip: Milestone Checkpoints

For important milestones, use --commit-tag:

ai_checkpoint --commit-tag "feature complete - user auth"
# Creates both commit AND tag for permanent reference

---

🎬 Scenario 3: Comparing Multiple AI Approaches

Scenario: AI suggested 3 different solutions. You want to compare them.

# Start task
ai_task optimize-db-queries

# AI suggests approach 1
ai_wip "approach 1 - add indexes"
ai_snap "approach-1-indexes"

# AI suggests approach 2
git reset --hard HEAD~1  # Discard approach 1
ai_wip "approach 2 - caching layer"
ai_snap "approach-2-cache"

# AI suggests approach 3
git reset --hard HEAD~1  # Discard approach 2
ai_wip "approach 3 - denormalization"
ai_snap "approach-3-denorm"

# List all approaches
ai_snap_list
# Output:
#   === Saved Snapshots ===
#   [0] [ai/optimize-db-queries-...] approach-1-indexes (5 minutes ago)
#   [1] [ai/optimize-db-queries-...] approach-2-cache (3 minutes ago)
#   [2] [ai/optimize-db-queries-...] approach-3-denorm (1 minute ago)

# Compare approach 1 vs 3
ai_compare 0 2
# Shows diff between the two approaches

# Decide approach 3 is best - restore it
ai_snap_restore 2

# Clean up unused snapshots
ai_snap_restore 1  # This auto-backs up current state first
ai_snap_restore 0  # Compare others if needed

---

🎬 Scenario 4: Parallel Task Management

Scenario: Working on multiple features simultaneously, switching between them.

# Start task A
ai_task user-profile-page
# Working on profile page...
ai_wip "basic profile layout"

# Start task B (switch to new task)
ai_switch
# Output:
#   === Available AI Tasks ===
#   [0] ✓ ai/user-profile-page-...
#        Path: ../wt-ai-user-profile-page-...
#
#   [m] Return to main repository
#
# Enter task number to switch, [m] for main, or 'q' to cancel:

# Press Ctrl+C to cancel, start new task
ai_task email-notification-system

# Work on email system...
ai_wip "email template design"

# Check status of all tasks
ai_status
# Output:
#   === Active AI Tasks (with worktree) ===
#   ✓ ai/user-profile-page-... ← YOU ARE HERE
#     Path: ../wt-ai-user-profile-page-...
#     Status: dirty
#
#   ○ ai/email-notification-system-...
#     Path: ../wt-ai-email-notification-system-...
#     Status: clean
#
#   === Completed AI Branches (no worktree) ===
#   (no orphan branches)

# Switch back to task A
ai_switch
# Select [0] to switch to user-profile-page

# Continue work...
ai_wip "profile photo upload"

# When done with each task
ai_finish main  # Completes user-profile-page
ai_switch       # Switch to email-notification-system
ai_finish main  # Completes email-notification-system

---

🎬 Scenario 5: Filesystem Snapshots for Radical Changes

Scenario: AI wants to refactor the entire codebase architecture. This is risky - use full filesystem backup.

# Create complete filesystem snapshot
ai_fssnap "before-monolith-to-microservices"
# Output:
#   ✓ Filesystem snapshot created
#     Name: before-monolith-to-microservices
#     Location: ../.ai-snapshots/before-monolith-to-microservices
#     Size: 245M
#     Linked files: 1234 / 5678 (saved space via hard links)

# Let AI do radical refactoring...
# ... weeks of work ...
# ... oops, this approach isn't working

# List filesystem snapshots
ai_fssnap_list
# Output:
#   === Filesystem Snapshots ===
#   [0] before-monolith-to-microservices
#       Created: 2025-02-17 14:30:22
#       Branch: main
#       Size: 245M

# Restore to before the refactoring
ai_fssnap_restore 0
# Output:
#   Safety: Creating backup of current state...
#   ✓ Your current state is backed up as: pre-restore-backup-2025...
#   WARNING: This will overwrite your current working directory!
#   Continue with restore? (y/N): y
#   ✓ Snapshot restored

# Your entire codebase is restored to the previous state

When to Use ai_fssnap vs ai_snap

Use ai_fssnap when...	Use ai_snap when...
Major refactoring	Quick iterations
Include untracked files	Only git-tracked files
Need complete safety	Lightweight checkpoint
Large-scale changes	Small experiments

---

🎬 Scenario 6: "AI, Try This Crazy Idea" - Sandbox Mode

Scenario: You want to let AI experiment freely without fear of breaking anything.

# Create a checkpoint first
ai_checkpoint "before ai experiments"

# Start task
ai_task crazy-experiment-ai

# Tell AI: "Feel free to try anything, break anything, explore wild ideas"
# AI iterates rapidly...
ai_wip "crazy idea v1"
ai_wip "crazy idea v2 - broken"
ai_wip "crazy idea v3 - worse"
ai_wip "crazy idea v4 - brilliant!"

# If v4 is brilliant but needs cleanup:
ai_squash  # Consolidate into clean commit
ai_finish main

# If nothing worked:
ai_abort   # Rollback to checkpoint, task deleted

---

🔧 Command Reference

Task Management

ai_task <name>          # Start new AI task with isolated worktree
ai_finish [branch]      # Complete and merge task (default: main)
ai_status               # Show all AI tasks with status
ai_switch               # Switch between active tasks

Checkpoint & Rollback

ai_checkpoint [msg]              # Create checkpoint (auto: tag or stash)
ai_checkpoint --commit-tag [msg] # Milestone checkpoint (commit + tag)
ai_abort [num]                   # List or restore checkpoints
ai_checkpoint_clean              # Clean up old checkpoint tags

Lightweight Iterations

ai_wip [msg]            # Save work-in-progress commit
ai_wip_log              # List all WIP commits
ai_squash               # Consolidate WIPs into clean commits

Snapshots (Git-based)

ai_snap [name]          # Create named snapshot (stash)
ai_snap_list            # List all snapshots
ai_snap_restore <num>   # Restore snapshot
ai_snap_show <num>      # View snapshot contents

Filesystem Snapshots

ai_fssnap [name]        # Create filesystem snapshot (rsync)
ai_fssnap_list          # List filesystem snapshots
ai_fssnap_restore <num> # Restore filesystem snapshot
ai_fssnap_diff <n1> <n2> # Compare two snapshots
ai_fssnap_clean         # Clean up old snapshots

Utilities

ai_compare <v1> [v2]    # Compare two versions
ai_clean                # Clean up all WIPs and snapshots
ai_help                 # Show help

---

💡 Best Practices

1. Always Checkpoint Before Major Work

# Before letting AI do big refactors
ai_checkpoint "before major refactor"

# Before starting complex task
ai_task complex-feature
ai_checkpoint "start of complex-feature"

2. Use ai_wip for Rapid Iteration

# Let AI work freely, save often
ai_wip "iteration 1"
ai_wip "iteration 2"
ai_wip "iteration 3"
# ... 20 iterations later ...
ai_squash  # Clean up in one go

3. Name Snapshots Meaningfully

# Bad
ai_snap "snap1"

# Good
ai_snap "before-removing-legacy-code"
ai_snap "after-migration-to-new-api"
ai_snap "working-auth-implementation"

4. Clean Up Regularly

# After merging task
ai_finish main

# Periodically clean old checkpoints
ai_checkpoint_clean
# Choose option 1: Keep last 5 checkpoints

# Clean snapshots
ai_fssnap_clean

5. Use Task Isolation for Parallel Work

# Task A: Fix bug
ai_task fix-login-bug
ai_finish main

# Task B: New feature
ai_task add-dark-mode
ai_finish main

# Both isolated, no conflicts

---

🎯 Common Workflows

Debugging AI-Generated Code

ai_task debug-ai-code
ai_wip "initial ai version"  # Save what AI gave you

# Debug and fix...
ai_wip "fix bug 1"
ai_wip "fix bug 2"

ai_squash  # Clean up
ai_finish main

Trying Multiple AI Suggestions

ai_task explore-ai-suggestions

ai_snap "suggestion-A"
git reset --hard HEAD~1

ai_snap "suggestion-B"
git reset --hard HEAD~1

ai_snap "suggestion-C"

# Compare and choose best
ai_snap_list
ai_snap_restore 1  # Restore suggestion-B

Safe AI Experimentation

ai_checkpoint "safety-net"

ai_task ai-experiment

# Let AI go wild...
ai_wip "crazy idea"
ai_wip " crazier idea"

# If it works:
ai_squash
ai_finish main

# If it fails:
ai_abort  # Back to safety net

---

❓ FAQ

Q: What's the difference between ai_wip and ai_snap?

A: ai_wip creates commits (pollutes history but easy to version control). ai_snap uses git stash (cleaner history, but less visible).

Q: Can I use this without AI?

A: Absolutely! It's useful for any experimental development, AI-assisted or not.

Q: What happens to my main branch?

A: Your main branch stays untouched. All work happens in isolated worktrees.

Q: How do I undo ai_finish?

A: Use ai_abort to rollback to a checkpoint created before the finish.

Q: Can I push ai_task branches to remote?

A: Yes, but they're designed for local work. Push the merged result to remote after ai_finish.

Q: Do filesystem snapshots use a lot of disk space?

A: No! They use hard links for incremental snapshots. Only changed files take new space.

---

📚 Advanced Tips

Recovering from "Oh No, I Deleted the Wrong Thing"

# Every restore auto-backs up your current state
ai_fssnap_restore 0  # This creates pre-restore-backup-*

# If you restored wrong, go back:
ai_fssnap_list
# Find the pre-restore-backup-* snapshot
ai_fssnap_restore <number-of-backup>

Branch-Specific Snapshots

Snapshots remember which branch they're from:

ai_task feature-a
ai_snap "feature-a-work-in-progress"

ai_task feature-b
ai_snap_list  # Only shows feature-b snapshots

ai_switch  # Switch back to feature-a
ai_snap_list  # Shows feature-a snapshots

Checkpoint Types Explained

# Clean working dir → Creates tag checkpoint
ai_checkpoint
# Type: tag (clean working dir)

# Dirty working dir → Creates stash checkpoint
ai_checkpoint
# Type: stash (uncommitted changes preserved)

# Force commit + tag (milestone)
ai_checkpoint --commit-tag "release v1.0"
# Type: commit + tag

---

🤖 Integration with AI Tools

Recommended AI Prompt Pattern

I'm using the AI Git Workflow. Here's my current status:

[run: ai_status]

Please help me [task]. I'll save your iterations with ai_wip.
Feel free to suggest multiple approaches - I'll snapshot each one.

Example AI Conversation

# You: Create a user authentication system
# AI: Sure! I'll implement JWT-based auth...

# You: Wait, save that first
ai_wip "jwt-auth-v1"

# You: Now try session-based instead
# AI: Okay, I'll refactor to use sessions...

# You: Save that too
ai_wip "session-auth-v1"

# You: Compare both
ai_compare HEAD~1 HEAD

# You: I like sessions better. Keep it.
ai_squash

---

🎓 Learning Path

Day 1: Basics

source ai-workflow-enhanced.sh
ai_task my-first-task
ai_wip "test"
ai_finish main

Day 2: Safety Net

ai_checkpoint "before changes"
# Make changes
ai_abort 0  # Rollback

Day 3: Snapshots

ai_snap "approach-A"
ai_snap "approach-B"
ai_snap_restore 0

Week 1: Full Workflow

Use all features in your daily development

Month 1: Advanced

Multiple parallel tasks, filesystem snapshots, cleanup automation

---

📝 Summary

The AI Git Workflow gives you:

✓ Safety: Rollback anytime with checkpoints ✓ Isolation: Worktrees keep experiments separate ✓ Flexibility: Multiple layers of protection (WIP, snap, fssnap) ✓ Clean History: Squash messy iterations into clean commits ✓ Parallel Work: Switch between multiple tasks easily

Start today: source ai-workflow-enhanced.sh && ai_task my-first-feature

---

🆘 Getting Help

ai_help  # Show all commands

For issues or questions, refer to the script comments or create an issue in your repository.

---

Version: Enhanced with lightweight checkpointing and filesystem snapshots Last Updated: 2025-02-17