/git-workflow

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`:

{
  "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
    - Summary counts: {critical: N, high: N, medium: N, low: N}
    - Recommendations for fixes

    Write your complete review as a single markdown document.

Save the agent's output to `.git-workflow/01-code-review.md`.

Update `state.json`: set `current_step` to 2, add step 1 to `completed_steps`.

Step 2: Dependency and Breaking Change Analysis

Read `.git-workflow/00-git-context.md` and `.git-workflow/01-code-review.md`.

Use the Task tool:

Task:
  subagent_type: "git-pr-workflows-code-reviewer"
  description: "Analyze changes for dependencies and breaking changes"
  prompt: |
    Analyze the changes for dependency and breaking change issues.

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

    ## Code Review
    [Insert contents of .git-workflow/01-code-review.md]

    Check for:
    1. New dependencies or version changes
    2. Breaking API changes
    3. Database schema modifications
    4. Configuration changes
    5. Backward compatibility issues

    Identify any changes that require migration scripts or documentation updates.

    ## Deliverables
    1. Breaking change assessment
    2. Dependency change analysis
    3. Migration requirements
    4. Documentation update needs

    Write your complete analysis as a single markdown document.

Save output to `.git-workflow/02-breaking-changes.md`.

Update `state.json`: set `current_step` to "checkpoint-1", add step 2 to `completed_steps`.

---

PHASE CHECKPOINT 1 — User Approval Required

Display a summary of code review and breaking change analysis and ask:

Pre-commit review complete. Please review:
- .git-workflow/01-code-review.md
- .git-workflow/02-breaking-changes.md

Issues found: [X critical, Y high, Z medium, W low]
Breaking changes: [summary]

1. Approve — proceed to testing (or skip if --skip-tests)
2. Fix issues first — I'll address the critical/high issues
3. Pause — save progress and stop here

If user selects option 2, address the critical/high issues, then re-run the review and re-checkpoint.

Do NOT proceed to Phase 2 until the user approves.

---

Phase 2: Testing and Validation (Steps 3–4)

If `--skip-tests` flag is set, skip to Phase 3. Write a note in `.git-workflow/03-test-results.md` explaining tests were skipped.

Step 3: Test Execution and Coverage

Read `.git-workflow/00-git-context.md` and `.git-workflow/01-code-review.md`.

Use the