the-grid-cc 1.7.12 → 1.7.14

package/commands/grid/branch.md

@@ -0,0 +1,567 @@
+# /grid:branch - Branch Management
+
+---
+name: grid:branch
+description: Manage git branches for Grid sessions
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Task
+  - AskUserQuestion
+---
+
+Manage feature branches for Grid work sessions. Handles branch creation, switching, PR creation, and cleanup.
+
+## USAGE
+
+```
+/grid:branch                    # Show current branch status
+/grid:branch create {name}      # Create new feature branch
+/grid:branch switch {name}      # Switch to existing branch
+/grid:branch pr                 # Create PR for current branch
+/grid:branch cleanup            # Delete merged branches
+/grid:branch list               # List all grid branches
+```
+
+## SUBCOMMANDS
+
+### status (default)
+
+Show current git branch state:
+
+```bash
+# Get branch info
+BRANCH=$(git branch --show-current)
+COMMITS_AHEAD=$(git rev-list --count main..HEAD 2>/dev/null || echo "0")
+COMMITS_BEHIND=$(git rev-list --count HEAD..main 2>/dev/null || echo "0")
+UNCOMMITTED=$(git status --porcelain | wc -l | tr -d ' ')
+
+# Check remote tracking
+REMOTE=$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo "none")
+```
+
+**Output:**
+
+```
+BRANCH STATUS
+=============
+
+Current: grid/react-todo-app
+Remote:  origin/grid/react-todo-app
+
+         main
+          |
+    +--- 5 commits behind
+    |
+    +--- 12 commits ahead ---> [grid/react-todo-app]
+                                    |
+                               (3 uncommitted changes)
+
+Actions available:
+  /grid:branch pr       Create pull request
+  /grid:branch sync     Pull latest from main
+
+End of Line.
+```
+
+### create
+
+Create a new feature branch:
+
+```
+/grid:branch create {name}
+```
+
+**Process:**
+
+```bash
+# Validate name
+NAME=$1
+if [[ ! "$NAME" =~ ^[a-z0-9-]+$ ]]; then
+  echo "ERROR: Branch name must be lowercase alphanumeric with hyphens only"
+  exit 1
+fi
+
+# Add prefix if not present
+if [[ ! "$NAME" =~ ^grid/ ]]; then
+  NAME="grid/$NAME"
+fi
+
+# Check if exists
+if git show-ref --verify --quiet "refs/heads/$NAME"; then
+  echo "ERROR: Branch '$NAME' already exists"
+  exit 1
+fi
+
+# Ensure we're on latest main
+git fetch origin main
+git checkout main
+git pull origin main
+
+# Create branch
+git checkout -b "$NAME"
+
+echo "Created and switched to: $NAME"
+```
+
+**Output:**
+
+```
+BRANCH CREATED
+==============
+
+Branch: grid/add-dark-mode
+From:   main (commit abc1234)
+
+Ready for work. Commits will be tracked.
+
+Start building with /grid or /grid:quick.
+
+End of Line.
+```
+
+### switch
+
+Switch to an existing branch:
+
+```
+/grid:branch switch {name}
+```
+
+**Process:**
+
+```bash
+NAME=$1
+
+# Add prefix if searching
+if [[ ! "$NAME" =~ ^grid/ ]] && ! git show-ref --verify --quiet "refs/heads/$NAME"; then
+  NAME="grid/$NAME"
+fi
+
+# Check uncommitted changes
+if [[ -n $(git status --porcelain) ]]; then
+  echo "WARNING: Uncommitted changes detected"
+  echo "Options:"
+  echo "  1. Stash changes and switch"
+  echo "  2. Commit changes first"
+  echo "  3. Cancel"
+  # Prompt user
+fi
+
+git checkout "$NAME"
+```
+
+**Output:**
+
+```
+BRANCH SWITCHED
+===============
+
+Now on: grid/fix-login-bug
+Commits: 3 ahead of main
+Status:  Clean working tree
+
+Resume work or view with /grid:status.
+
+End of Line.
+```
+
+### pr
+
+Create a pull request for the current branch:
+
+```
+/grid:branch pr
+/grid:branch pr --title "Custom title"
+/grid:branch pr --draft
+```
+
+**Pre-flight checks:**
+
+```bash
+# Must be on feature branch
+BRANCH=$(git branch --show-current)
+if [[ "$BRANCH" =~ ^(main|master|production)$ ]]; then
+  echo "ERROR: Cannot create PR from protected branch"
+  exit 1
+fi
+
+# Must have commits
+COMMITS=$(git rev-list --count main..HEAD)
+if [ "$COMMITS" -eq 0 ]; then
+  echo "ERROR: No commits to create PR from"
+  exit 1
+fi
+
+# Must be pushed
+if ! git rev-parse --abbrev-ref --symbolic-full-name @{u} &>/dev/null; then
+  echo "Pushing branch to origin..."
+  git push -u origin "$BRANCH"
+fi
+
+# Check for existing PR
+EXISTING=$(gh pr view --json number 2>/dev/null | jq -r '.number // empty')
+if [ -n "$EXISTING" ]; then
+  echo "PR #$EXISTING already exists for this branch"
+  echo "View at: $(gh pr view --json url -q '.url')"
+  exit 0
+fi
+```
+
+**Generate PR content:**
+
+```bash
+# Gather commit info
+COMMITS=$(git log main..HEAD --pretty=format:"- %s" | head -20)
+FILES_CHANGED=$(git diff --stat main..HEAD | tail -1)
+
+# Check for Grid metadata
+CLUSTER=""
+if [ -f ".grid/STATE.md" ]; then
+  CLUSTER=$(grep "^## CLUSTER:" .grid/STATE.md | cut -d: -f2 | xargs)
+fi
+
+# Check for summaries
+SUMMARIES=""
+for f in .grid/phases/**/SUMMARY.md .grid/quick/*/SUMMARY.md; do
+  if [ -f "$f" ]; then
+    SUMMARIES="$SUMMARIES\n$(cat $f)"
+  fi
+done 2>/dev/null
+```
+
+**Create PR:**
+
+```bash
+gh pr create \
+  --title "$TITLE" \
+  --body "$(cat <<EOF
+## Summary
+$DESCRIPTION
+
+## Changes
+$COMMITS
+
+## Stats
+$FILES_CHANGED
+
+## Grid Session
+- **Cluster:** $CLUSTER
+- **Commits:** $(git rev-list --count main..HEAD)
+
+## Test Plan
+- [ ] Code review
+- [ ] Functionality verified
+- [ ] No regressions
+
+---
+*Created via /grid:branch pr*
+EOF
+)" \
+  --base main
+```
+
+**Output:**
+
+```
+PULL REQUEST CREATED
+====================
+
+PR #42: feat: add user authentication
+URL: https://github.com/user/repo/pull/42
+
+Branch: grid/add-auth -> main
+Commits: 8
+Files changed: 12
+
+Status: Open (ready for review)
+
+View PR: gh pr view 42
+Check status: gh pr checks 42
+
+End of Line.
+```
+
+### cleanup
+
+Delete branches that have been merged:
+
+```
+/grid:branch cleanup
+/grid:branch cleanup --dry-run
+/grid:branch cleanup --force
+```
+
+**Process:**
+
+```bash
+# Get merged branches
+MERGED=$(git branch --merged main | grep "grid/" | grep -v "^\*")
+
+if [ -z "$MERGED" ]; then
+  echo "No merged grid branches to clean up."
+  exit 0
+fi
+
+echo "Merged branches to delete:"
+echo "$MERGED"
+
+if [ "$1" == "--dry-run" ]; then
+  echo "(Dry run - no changes made)"
+  exit 0
+fi
+
+# Confirm
+read -p "Delete these branches? [y/N] " confirm
+if [[ ! "$confirm" =~ ^[Yy]$ ]]; then
+  echo "Cancelled."
+  exit 0
+fi
+
+# Delete local
+echo "$MERGED" | xargs git branch -d
+
+# Delete remote
+for branch in $MERGED; do
+  git push origin --delete "$branch" 2>/dev/null || true
+done
+```
+
+**Output:**
+
+```
+BRANCH CLEANUP
+==============
+
+Deleted local branches:
+  - grid/add-auth (was abc1234)
+  - grid/fix-login (was def5678)
+
+Deleted remote branches:
+  - origin/grid/add-auth
+  - origin/grid/fix-login
+
+Remaining grid branches: 2
+  - grid/react-todo-app (current)
+  - grid/feature-x
+
+End of Line.
+```
+
+### list
+
+List all Grid-managed branches:
+
+```
+/grid:branch list
+/grid:branch list --all        # Include remote
+/grid:branch list --stale      # Only stale (>30 days)
+```
+
+**Output:**
+
+```
+GRID BRANCHES
+=============
+
+Local:
+  * grid/react-todo-app     (current, 12 commits ahead)
+    grid/feature-x          (3 commits ahead)
+    grid/old-experiment     (stale: 45 days)
+
+Remote only:
+    origin/grid/abandoned   (stale: 60 days)
+
+Legend:
+  * = current
+  (stale) = no commits in 30+ days
+
+Actions:
+  /grid:branch switch {name}
+  /grid:branch cleanup --stale
+
+End of Line.
+```
+
+### sync
+
+Sync current branch with main:
+
+```
+/grid:branch sync
+/grid:branch sync --rebase    # Rebase instead of merge
+```
+
+**Process:**
+
+```bash
+# Fetch latest
+git fetch origin main
+
+# Check for conflicts
+CONFLICTS=$(git merge-tree $(git merge-base HEAD origin/main) HEAD origin/main | grep -c "^<<<<<<<" || echo "0")
+
+if [ "$CONFLICTS" -gt 0 ]; then
+  echo "WARNING: Merge will have conflicts"
+  echo "Files with conflicts: $CONFLICTS"
+  read -p "Continue? [y/N] " confirm
+fi
+
+# Merge or rebase
+if [ "$1" == "--rebase" ]; then
+  git rebase origin/main
+else
+  git merge origin/main --no-edit
+fi
+```
+
+**Output:**
+
+```
+BRANCH SYNCED
+=============
+
+Merged main into grid/react-todo-app
+
+Before: 5 commits behind main
+After:  Up to date with main
+
+Merge commit: ghi7890
+
+Ready to continue work.
+
+End of Line.
+```
+
+## AUTONOMOUS MODE
+
+When Grid is in AUTOPILOT mode, branch operations happen automatically:
+
+### Session Start
+1. Check if on protected branch
+2. If yes, create `grid/{cluster-slug}` branch
+3. If existing grid branch matches cluster, switch to it
+
+### After Each Wave
+1. Check for uncommitted changes (shouldn't be any with atomic commits)
+2. Push to remote if auto_push enabled
+
+### Session Complete
+1. Push final state
+2. Offer PR creation
+3. Report branch status
+
+## CONFIGURATION
+
+Set preferences in `.grid/config.json`:
+
+```json
+{
+  "git": {
+    "auto_branch": true,
+    "branch_prefix": "grid/",
+    "auto_push": "wave",
+    "auto_pr": false,
+    "protected_branches": ["main", "master", "production"],
+    "default_base": "main",
+    "sync_strategy": "merge"
+  }
+}
+```
+
+## ERROR HANDLING
+
+### No Git Repository
+
+```
+ERROR: Not a git repository
+
+Initialize with:
+  git init
+  git remote add origin {url}
+
+Then retry /grid:branch.
+```
+
+### No Remote
+
+```
+WARNING: No remote configured
+
+Branch operations will be local only.
+Add remote with:
+  git remote add origin {url}
+```
+
+### Uncommitted Changes
+
+```
+WARNING: Uncommitted changes detected
+
+Options:
+  1. Stash: git stash
+  2. Commit: /grid:quick "commit message"
+  3. Discard: git checkout -- . (DANGER)
+
+Choose action before switching branches.
+```
+
+### Merge Conflicts
+
+```
+CONFLICT: Merge conflicts detected
+
+Conflicting files:
+  - src/components/Chat.tsx
+  - src/lib/api.ts
+
+Options:
+  1. Resolve manually and continue
+  2. Abort merge: git merge --abort
+  3. Accept ours: git checkout --ours {file}
+  4. Accept theirs: git checkout --theirs {file}
+
+After resolving: git add {files} && git commit
+```
+
+## INTEGRATION
+
+### With /grid
+
+```
+/grid "build a chat app"
+-> Auto-creates grid/chat-app branch
+-> All commits go to this branch
+-> On completion, offers PR
+```
+
+### With /grid:quick
+
+```
+/grid:quick "fix login bug"
+-> Checks current branch
+-> If on main, creates grid/fix-login-bug
+-> Commits to feature branch
+```
+
+### With /grid:status
+
+```
+/grid:status
+-> Shows branch info in status output
+-> Includes commits ahead/behind
+-> Shows remote tracking status
+```
+
+## RULES
+
+1. **Never commit to protected branches** - Always create feature branch
+2. **Atomic commits** - One logical change per commit
+3. **Descriptive names** - Branch names describe the work
+4. **Clean before switch** - Handle uncommitted changes
+5. **Push after waves** - Keep remote in sync
+6. **Clean up merged** - Delete branches after PR merge
+7. **Sync regularly** - Keep branches up to date with main
+
+End of Line.