Git & GitHub Workflows (via Grove Wrap)

All git and GitHub operations go through gw — never use raw git or gh commands directly. Grove Wrap adds safety tiers, Conventional Commits enforcement, protected branch guards, and agent-safe defaults.

When to Activate

Activate this skill when:

Making git commits, pushing, pulling, branching, or stashing
Creating, reviewing, or merging pull requests
Creating, viewing, or closing GitHub issues
Checking CI/workflow run status
Reviewing git history, diffs, or blame
Resolving merge conflicts
Any version control operation

Safety System

gw enforces a three-tier safety model:

Tier	Flag Required	Examples
READ	None	`gw git status`, `gw git log`, `gw gh pr list`
WRITE	`--write`	`gw git commit`, `gw git push`, `gw git pull`, `gw gh pr create`
DANGEROUS	`--write --force`	`gw git reset`, `gw git force-push`, `gw git rebase`

Protected branches (main, master, production, staging) can NEVER be force-pushed, even with --force.

Agent mode (auto-detected for Claude Code): stricter row limits, force operations blocked, all operations audit-logged.

Dry run any command with --dry-run to preview what would happen.

Conventional Commits Format

gw validates commit messages against Conventional Commits automatically. Format:

<type>(<optional scope>): <brief description>

<optional body>

<optional footer>

Commit Types

Type	Purpose	Example
`feat`	New feature	`feat: add user authentication`
`fix`	Bug fix	`fix: correct validation error`
`docs`	Documentation	`docs: update README`
`style`	Code formatting	`style: format with prettier`
`refactor`	Code restructure	`refactor: extract helper function`
`test`	Add/modify tests	`test: add auth tests`
`chore`	Maintenance	`chore: update dependencies`
`perf`	Performance	`perf: optimize query speed`
`ci`	CI/CD changes	`ci: fix deploy workflow`

Breaking changes: Add an exclamation mark after the type, e.g. feat!: replace XML config with YAML

Git Commands — Reading (Always Safe)

gw git status                  # Enhanced git status
gw git log                     # Formatted commit history
gw git log --limit 20          # Last 20 commits
gw git diff                    # Show changes
gw git diff --staged           # Show staged changes
gw git blame file.ts           # Blame with context
gw git show abc123             # Show commit details

Git Commands — Writing (Needs `--write`)

gw git add --write .                              # Stage files
gw git add --write src/lib/thing.ts               # Stage specific file
gw git commit --write -m "feat: add new feature"  # Commit (validates conventional commits!)
gw git push --write                               # Push to remote
gw git pull --write                               # Pull from remote
gw git pull --write --rebase                      # Pull with rebase strategy
gw git branch --write feature/new-thing           # Create branch
gw git switch --write feature/new-thing           # Switch branches
gw git stash --write                              # Stash changes
gw git stash --write pop                          # Pop stash
gw git unstage --write file.ts                    # Unstage files

Git Commands — Dangerous (Needs `--write --force`)

gw git push --write --force          # Force push (blocked to protected branches!)
gw git reset --write --force HEAD~1  # Hard reset
gw git rebase --write --force main   # Rebase onto main
gw git merge --write --force feature # Merge branches

Grove Shortcuts

These combine common multi-step operations into single commands:

# Quick save: stage all + WIP commit
gw git save --write

# Quick sync: fetch + rebase + push
gw git sync --write

# WIP commit that skips hooks
gw git wip --write

# Undo last commit (keeps changes staged)
gw git undo --write

# Amend last commit message
gw git amend --write -m "better message"

# FAST MODE: skip ALL hooks, commit + push in one shot
gw git fast --write -m "fix: emergency hotfix"

Branching Strategy

Branch Naming

feature/feature-name    # New features
fix/bug-description     # Bug fixes
experiment/new-idea     # Experiments
release/v1.0.0          # Releases

Feature Branch Workflow

# Create and switch to feature branch
gw git branch --write feature/user-auth
gw git switch --write feature/user-auth

# Work and commit
gw git add --write .
gw git commit --write -m "feat: add JWT authentication"

# Push and create PR
gw git push --write
gw gh pr create --write --title "feat: add JWT authentication"

GitHub — Pull Requests

# Reading (always safe)
gw gh pr list                   # List open PRs
gw gh pr view 123               # View PR details
gw gh pr status                 # PR status (CI, reviews, etc.)

# Writing (needs --write)
gw gh pr create --write --title "feat: new thing" --body "Description"
gw gh pr comment --write 123 "LGTM!"
gw gh pr merge --write 123      # Merge PR (prompts for confirmation)

GitHub — Issues

# Reading (always safe)
gw gh issue list                # List open issues
gw gh issue view 456            # View issue details

# Writing (needs --write)
gw gh issue create --write --title "Bug: thing broke"
gw gh issue close --write 456

GitHub — Workflow Runs (CI)

# Reading (always safe)
gw gh run list                  # List recent runs
gw gh run view 12345678         # View run details
gw gh run watch 12345678        # Watch a running workflow

# Writing (needs --write)
gw gh run rerun --write 12345678 --failed  # Rerun failed jobs
gw gh run cancel --write 12345678          # Cancel a run

GitHub — API & Rate Limits

# GET requests (always safe)
gw gh api repos/AutumnsGrove/Lattice

# POST/PATCH (needs --write)
gw gh api --write repos/{owner}/{repo}/labels -X POST -f name="bug"

# DELETE (needs --write --force)
gw gh api --write --force repos/{owner}/{repo}/labels/old -X DELETE

# Check rate limit status
gw gh rate-limit

GitHub — Project Boards

gw gh project list              # List project boards
gw gh project view              # View current project

Commit Examples

Feature

gw git commit --write -m "feat: add dark mode toggle

- Implement theme switching logic
- Add localStorage persistence
- Update CSS variables"

Bug Fix with Issue Link

gw git commit --write -m "fix: correct timezone handling bug

Fixes off-by-one error in date calculations.

Closes #123"

Breaking Change

gw git commit --write -m "feat!: replace XML config with YAML

BREAKING CHANGE: XML configuration no longer supported.
See docs/migration.md for upgrade instructions."

Agent-Optimized Commands (NEW)

These commands are specifically designed for agentic workflows:

Session Start (Always run this first!)

gw context                      # One-shot session snapshot (rich output)
gw --json context               # JSON snapshot (branch, changes, packages, issues)

Ship with Auto-Stage

# Stage all + format + check + commit + push in ONE command
gw git ship --write -a -m "feat: implement feature"

# Equivalent to: gw git add --write . && gw git ship --write -m "..."

PR Preparation

gw git pr-prep                  # Full PR readiness report
gw --json git pr-prep           # JSON: commits, files, packages, suggested title

Targeted CI

gw ci --affected               # Only check packages with changes
gw ci --affected --fail-fast   # Fast feedback: stop on first failure
gw ci --diagnose               # Structured error output when steps fail
gw --json ci --affected        # JSON with parsed error details

Batch Issue Creation

# Create multiple issues from JSON
gw gh issue batch --write --from-json issues.json
echo '[{"title":"Bug: thing","labels":["bug"]}]' | gw gh issue batch --write --from-json -

Impact Analysis (via gf)

gf impact src/lib/auth.ts       # Who imports this? What tests? Which routes?
gf test-for src/lib/auth.ts     # Find tests covering this file
gf diff-summary                 # Structured diff with per-file stats
gf --json impact src/lib/auth.ts  # All of the above as parseable JSON

Common Workflows

Start a new feature

gw context                      # Orient: what branch, what's changed?
gw git branch --write feature/my-feature
gw git switch --write feature/my-feature
# ... make changes ...
gw git ship --write -a -m "feat: implement my feature"
gw git pr-prep                  # Check readiness
gw gh pr create --write --title "feat: implement my feature"

Quick fix and ship

gw git fast --write -m "fix: correct typo in header"

Ship with full checks

gw git ship --write -a -m "feat: add auth refresh"
# This does: auto-stage all → format → type-check → commit → push

Check CI before merging

gw ci --affected --fail-fast    # Quick: only changed packages
gw gh pr status                 # See CI status on current PR
gw gh run list                  # See recent workflow runs
gw gh run watch 12345678        # Watch the current run

Pull latest changes

gw git pull --write             # Pull from remote (merge strategy)
gw git pull --write --rebase    # Pull with rebase (cleaner history)
gw git pull --write origin main # Pull specific remote/branch

Sync branch with main

gw git sync --write             # Fetch + rebase + push

Save work in progress

gw git save --write             # Stage all + WIP commit
# or
gw git stash --write            # Stash without committing

Merge Conflicts

When conflicts occur during sync/rebase/merge:

gw git status                   # See conflicted files

# Edit files to resolve conflicts:
# <<<<<<< HEAD
# Your changes
# =======
# Incoming changes
# >>>>>>> feature-branch

# After resolving:
gw git add --write resolved-file.ts
gw git commit --write -m "fix: resolve merge conflicts"

Worktrees

Work on multiple branches simultaneously without stashing:

gw git worktree add --write ../grove-hotfix fix/urgent
gw git worktree list
gw git worktree remove --write ../grove-hotfix

Best Practices

DO

Start every session with gw context (or gw --json context for structured data)
Use gw for all git/GitHub operations (never raw git or gh)
Use gf for all codebase search (never raw grep or rg)
Use Conventional Commits format (gw enforces this)
Use gw git ship --write -a -m "..." for the fastest commit+push workflow
Use gw ci --affected instead of full CI when possible
Use gw git pr-prep before creating PRs
Use gf impact before making changes to understand blast radius
One logical change per commit
Keep subject under 50 characters
Use imperative mood ("Add" not "Added")
Use --dry-run to preview destructive operations

DON'T

Use raw git or gh commands directly
Force-push to protected branches
Use vague messages ("Update files", "Fix stuff")
Combine multiple unrelated changes in one commit
Skip the --write flag (even if it seems tedious — it's a safety net)

Troubleshooting

"Protected branch"

You tried to force-push to main. Create a PR instead:

gw gh pr create --write --title "My changes"

"Rate limit exhausted"

gw gh rate-limit               # Check when it resets

Committed to wrong branch

gw git log --limit 1            # Note the commit hash
gw git switch --write correct-branch
# Cherry-pick the commit, then remove from wrong branch

Need to undo last commit

gw git undo --write             # Keeps changes staged

Related Resources

gw source: tools/grove-wrap-go/ — Go source code and Makefile
gw spec: docs/specs/gw-cli-spec.md — Technical specification
Git guide: AgentUsage/git_guide.md — Extended documentation
MCP integration: gw mcp serve exposes all commands as MCP tools for Claude Code

git-workflows