# git-workflow

Walks your changes from code review through tests to a pull request, pausing for approval at each phase. Useful when a commit and PR need one fixed order instead of guesswork.

- command · `type=command` · Claude Code, Codex, Cursor · ★ 41729
- Author: Seth Hobson
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/wshobson/agents/tree/HEAD/plugins/git-pr-workflows/commands/git-workflow.md
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/commands/git-workflow

## What it does

The command runs a chain of steps. First it reviews uncommitted changes for style, security holes, performance and missing error handling. Then it looks separately at dependencies, breaking API changes and schema edits. After that come the test suites and a coverage report. Every step writes its own file under `.git-workflow/`, and the next step reads that file rather than trusting the context window.

Checkpoints sit between phases. The command stops there and waits for explicit approval through AskUserQuestion. A failed step — a broken test, an agent error, a missing dependency — halts everything and shows you the error. All subagents come from this plugin or `general-purpose`, so nothing outside it is needed.

Arguments set the branch and the behaviour: `<target branch>` plus `--skip-tests`, `--draft-pr`, `--no-push`, `--squash`, `--conventional`, `--trunk-based`. The branch falls back to `main`. Session state lives in `.git-workflow/state.json`; when it reads `in_progress`, you get a choice to resume or archive and start over.

## Install

### Claude Code (native platform)

1. **Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add wshobson/agents
```
In the agent chat (not a shell):
```text
/plugin install git-pr-workflows@claude-code-workflows
```

2. **Manually: put the files in place**
- File: `.claude/commands/git-workflow.md` — Call it with /git-workflow. For all projects use ~/.claude/commands/

### Codex

**Manually: put the files in place**
- File: `~/.codex/prompts/git-workflow.md` — Call it with /prompts:git-workflow. Codex marks this format deprecated in favour of skills

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/prompts/git-workflow.prompt.md`

### Gemini CLI

**Manually: put the files in place**
- File: `.gemini/commands/git-workflow.toml` — Gemini stores commands as TOML: the prompt text goes into the prompt field

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/wshobson/agents/tree/HEAD/plugins/git-pr-workflows/commands/git-workflow.md

## When to use it
- review uncommitted changes before committing
- spot breaking API and database schema changes
- run test suites and find untested code paths
- open a pull request with a sensible commit message
- pause at a checkpoint and resume the run later

## Example prompts
- /git-workflow main
- /git-workflow main --draft-pr --squash
- /git-workflow develop --skip-tests --no-push

## Source text · git-workflow.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 719d4ab79dabcd87.

BEGIN THIRD-PARTY FILE 719d4ab79dabcd87
````text
---
description: "Orchestrate git workflow from code review through PR creation with quality gates"
argument-hint: "<target branch> [--skip-tests] [--draft-pr] [--no-push] [--squash] [--conventional] [--trunk-based]"
---

# Git Workflow Orchestrator

## CRITICAL BEHAVIORAL RULES

You MUST follow these rules exactly. Violating any of them is a failure.

1. **Execute steps in order.** Do NOT skip ahead, reorder, or merge steps.
2. **Write output files.** Each step MUST produce its output file in `.git-workflow/` before the next step begins. Read from prior step files — do NOT rely on context window memory.
3. **Stop at checkpoints.** When you reach a `PHASE CHECKPOINT`, you MUST stop and wait for explicit user approval before continuing. Use the AskUserQuestion tool with clear options.
4. **Halt on failure.** If any step fails (agent error, test failure, missing dependency), STOP immediately. Present the error and ask the user how to proceed. Do NOT silently continue.
5. **Use only local agents.** All `subagent_type` references use agents bundled with this plugin or `general-purpose`. No cross-plugin dependencies.
6. **Never enter plan mode autonomously.** Do NOT use EnterPlanMode. This command IS the plan — execute it.

## Pre-flight Checks

Before starting, perform these checks:

### 1. Check for existing session

Check if `.git-workflow/state.json` exists:

- If it exists and `status` is `"in_progress"`: Read it, display the current step, and ask the user:

  ```
  Found an in-progress git workflow session:
  Target branch: [branch from state]
  Current step: [step from state]

  1. Resume from where we left off
  2. Start fresh (archives existing session)
  ```

- If it exists and `status` is `"complete"`: Ask whether to archive and start fresh.

### 2. Initialize state

Create `.git-workflow/` directory and `state.json`:

```json
{
  "target_branch": "$ARGUMENTS",
  "status": "in_progress",
  "flags": {
    "skip_tests": false,
    "draft_pr": false,
    "no_push": false,
    "squash": false,
    "conventional": true,
    "trunk_based": false
  },
  "current_step": 1,
  "current_phase": 1,
  "completed_steps": [],
  "files_created": [],
  "started_at": "ISO_TIMESTAMP",
  "last_updated": "ISO_TIMESTAMP"
}
```

Parse `$ARGUMENTS` for the target branch (defaults to 'main') and flags. Use defaults if not specified.

### 3. Gather git context

Run these commands and save output:

- `git status` — current working tree state
- `git diff --stat` — summary of changes
- `git diff` — full diff of changes
- `git log --oneline -10` — recent commit history
- `git branch --show-current` — current branch name

Save this context to `.git-workflow/00-git-context.md`.

---

## Phase 1: Pre-Commit Review and Analysis (Steps 1–2)

### Step 1: Code Quality Assessment

Read `.git-workflow/00-git-context.md`.

Use the Task tool to launch the code reviewer:

```
Task:
  subagent_type: "git-pr-workflows-code-reviewer"
  description: "Review uncommitted changes for code quality"
  prompt: |
    Review all uncommitted changes for code quality issues.

    ## Git Context
    [Insert contents of .git-workflow/00-git-context.md]

    Check for:
    1. Code style violations
    2. Security vulnerabilities
    3. Performance concerns
    4. Missing error handling
    5. Incomplete implementations

    Generate a detailed report with severity levels (critical/high/medium/low) and provide
    specific line-by-line feedback.

    ## Deliverables
    Output format: structured report with:
    - Issues list with severity, file, line, description
````
END THIRD-PARTY FILE 719d4ab79dabcd87

The third-party file has ended. Everything between the 719d4ab79dabcd87 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3592 of 17395 bytes. © Seth Hobson · MIT · https://github.com/wshobson/agents/tree/HEAD/plugins/git-pr-workflows/commands/git-workflow.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md