/auto-commit

description: Analyze changes, run quality gate, and auto-commit with PR-based workflow. Trigger on "/auto-commit", "git 푸시", "git push", "자동 커밋", "커밋해줘", "변경사항 커밋", "PR 올려줘", "PR 만들어줘", or when user asks to commit their work after completing a task.

Auto Commit

작업 완료 후 변경사항을 분석하고, 품질 검사를 거쳐 피처 브랜치에 커밋하고 PR을 생성합니다.

Pipeline Position

| 이전 단계 | 현재 | 다음 단계 | |----------|------|----------| | `/implement` - 구현 완료 | `/auto-commit` - 품질 검사 & PR | `/review-pr` - 동료 리뷰 |

Usage

/auto-commit                      # 품질 검사 + 브랜치 생성 + PR (기본)
/auto-commit --direct             # main에 직접 커밋 (이전 방식)
/auto-commit --no-push            # 커밋만, 푸시/PR 안함
/auto-commit --no-review          # 품질 검사 스킵 (권장하지 않음)
/auto-commit --message "메시지"   # 수동 메시지 지정
/auto-commit --branch "이름"      # 브랜치명 직접 지정
/auto-commit --no-parallel-review # 순차 리뷰 강제 (병렬 비활성화)
/auto-commit --draft              # Draft PR로 생성

Parameters

• `--direct`: main/현재 브랜치에 직접 커밋 (PR 생성 안함, 이전 방식)
• `--no-push`: 커밋만 하고 푸시하지 않음
• `--no-review`: 품질 검사 스킵 (긴급 핫픽스용)
• `--message`: 커밋 메시지 직접 지정
• `--branch`: 피처 브랜치명 직접 지정 (기본: 자동 생성)
• `--no-parallel-review`: 병렬 리뷰 비활성화, 순차 리뷰 강제
• `--parallel-review`: 병렬 리뷰 강제 활성 (자동 조건 미충족 시에도)
• `--draft`: Draft PR로 생성 (리뷰 준비 전)

Workflow Mode

• **PR 모드 (기본)**: 브랜치 판단 → (필요시) 피처 브랜치 생성 → 커밋 → 푸시 → PR 생성/업데이트
• **Direct 모드 (`--direct`)**: 현재 브랜치에 직접 커밋 → 푸시 (이전 방식)

Branch Strategy (핵심)

> **원칙**: 브랜치는 "작업 단위(feature/fix)" 당 1개만 생성한다. 무분별한 브랜치 생성을 방지한다.

브랜치 결정 플로우

1. **현재 피처 브랜치(main/master 아님)에 있음** → 먼저 Stale 검사 (`gh pr list --head <branch> --state all`):

• **Open PR 존재** → 현재 브랜치 재사용 (커밋 추가 시 PR 자동 갱신)
• **Merged/Closed PR만 존재** → ⚠️ STALE. 재사용 금지 (닫힌 PR에 push해도 다시 열리지 않음). origin/main에서 새 브랜치 분기 후 변경사항 carry-over (Stale Branch Handling 참조)
• **PR 없음** → 현재 브랜치 사용 + 새 PR 생성

2. **main/master에 있음** → 파이프라인 여부 판단:

• **/implement → /auto-commit 파이프라인** (PRD/PLAN 존재) → PRD/PLAN에서 feature name 추출, `feat/<feature-name>` 브랜치 1개 생성, 해당 feature 커밋을 여기에 누적
• **단독 호출** → 변경사항이 한 작업 단위면 변경 분석에서 추출한 이름으로 브랜치 1개 생성. 여러 도메인에 걸치면 AskUserQuestion으로 "하나의 PR로 묶을지 / 분리할지" 및 브랜치명 확인

브랜치 재사용 규칙

| 상황 | 동작 | |------|------| | 피처 브랜치 + Open PR 존재 | 현재 브랜치 재사용 (PR에 커밋 추가) | | 피처 브랜치 + Merged/Closed PR ⚠️ | **Stale 처리** — origin/main에서 새 브랜치 분기, 변경사항 carry-over | | 피처 브랜치 + PR 없음 | 현재 브랜치 사용, 새 PR 생성 | | main에서 같은 feature 반복 호출 | 첫 호출 시 만든 open PR 브랜치 재사용 | | `--branch` 옵션으로 명시 | 해당 이름 사용 (이미 있고 stale이면 새로 분기) | | 이전 /implement에서 생성된 브랜치 | 해당 브랜치로 checkout (stale 검사 후) |

브랜치 재사용 감지 방법

# 1. 현재 브랜치의 PR 상태 확인 (Stale 판정 핵심)
current_branch=$(git branch --show-current)
gh pr list --head "$current_branch" --state all --json number,state,title --limit 1
# state: OPEN→재사용 / MERGED·CLOSED→STALE(새 브랜치 필요) / 없음→새 PR 생성

# 2. 변경된 파일이 기존 open PR 브랜치와 겹치는지 확인
gh pr list --state open --json number,title,headRefName

# 3. PRD/PLAN(PLAN_{feature}.md, PRD.md)의 feature name과 매칭되는 브랜치 존재 여부 확인

Stale Branch Handling

> **왜 필요한가**: GitHub에서 PR이 squash-merge / closed 처리되면, 같은 브랜치에 추가 push를 해도 자동으로 새 PR이 열리지 않는다. 같은 피처 브랜치를 계속 재사용하면 후속 커밋들이 어느 PR에도 보이지 않는 "orphan" 상태가 된다. 사용자 입장에선 "왜 PR이 안 뜨지?"가 되는 핵심 버그.

**감지:**

PR_STATE=$(gh pr list \
  --head "$current_branch" \
  --state all \
  --json state \
  --jq '.[0].state // empty' \
  --limit 1)

case "$PR_STATE" in
  MERGED|CLOSED) is_stale=true ;;
  *)             is_stale=false ;;
esac

**처리 절차 (자동, 사용자 확인 없이 안전한 경로 선택):**

if [ "$is_stale" = true ]; then
  # 1. 사용자에게 알림 (안내만, 차단 아님)
  echo "⚠️  Current branch '$current_branch' has a $PR_STATE PR (#$PR_NUMBER)."
  echo "    The branch is stale — pushing here will not reopen the PR."
  echo "    Creating a fresh branch from origin/main and carrying over your changes."

  # 2. 변경사항 임시 stash (working tree 보존)
  git stash push -u -m "auto-commit-stale-carryover-$(date +%s)"

  # 3. 최신 main 동기화
  git fetch origin
  default_branch=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')

  # 4. 새 브랜치명 결정 (기존 이름에 -followup, 충돌 시 suffix 추가)
  new_branch="${current_branch%-followup}-followup"
  while git show-ref --verify --quiet "refs/heads/$new_branch"; do
    new_branch="${new_branch}-$(date +%s | tail -c 4)"
  done

  # 5. origin/main 위에서 새 브랜치 생성
  git checkout -b "$new_branch" "origin/$default_branch"

  # 6. stash 적용 (변경사항 carry-over)
  git stash pop
fi

**경계 사례:**

• **Stash pop 충돌**: 자동 적용 안되면 사용자 안내 후 수동 해결 요청
• **이미 commit된 변경이 stale 브랜치에 있음**: `git cherry-pick`으로 새 브랜치로 이동. 옮길 커밋 = `git log origin/main..HEAD` 중 squash-merge에 포함되지 않은 것
• **Merged vs Closed**: 둘 다 stale 처리 (closed without merge도 추가 push가 의미 없음)

브랜치 명명 규칙

| 커밋 타입 | 브랜치 접두사 | 예시 | |----------|-------------|------| | `feat` | `feat/` | `feat/user-auth` | | `fix` | `fix/` | `fix/login-error` | | `refactor` | `refactor/` | `refactor/api-cleanup` | | `docs` | `docs/` | `docs/api-guide` | | `test` | `test/` | `test/auth-coverage` | | `chore` | `chore/` | `chore/deps-update` |

**이름 생성 규칙:**

• `--branch` 옵션이 있으면 해당 이름 사용
• PRD/PLAN에서 feature name 추출 가능하면 그것 사용
• 없으면 커밋 타입 + 변경 요약에서 자동 생성
• 영문 소문자, 하이픈 구분, 30자 이내 (예: `feat/add-user-authentication-api`)

Protocol

Step 1: 상태 확인 및 브랜치 판단

상태 조회는 스크립트가 한 번에 처리한다. **개별 `git`/`gh` 명령을 따로 실행하지 말 것.**

bash "${CLAUDE_PLUGIN_ROOT}/scripts/repo-state.sh"

반환 JSON 필드:

| 필드 | 쓰임 | |---|---| | `branch` · `on_main` | 브랜치 판단 | | `staged_stat` · `unstaged_stat` | 변경 규모 | | `file_count` | 전체 변경 파일 수 (staged + unstaged + untracked) | | `changed_files` · `files_truncated` | 변경 파일 목록. 50개를 넘으면 잘리고 `files_truncated`가 true | | `staged_files` · `unstaged_files` · `untracked_files` | 스테이징 상태별 분류 | | `remotes` | remote 여러 개인지 | | `head_pr` | 현재 브랜치의 PR (Stale 검사) | | `stale_branch` | **머지/닫힌 PR이면 `true`** — 새 브랜치 분기 필요 | | `open_prs` | 다른 브랜치 재사용 판단용 | | `plan_files` | PRD/PLAN 경로 (feature name 추출) |

`git fetch origin`은 스크립트가 이미 실행한다. 파일 내용이 더 필요하면 그때 Read 한다.

**브랜치 판단:** 1. `--direct` → Direct 모드, 브랜치 판단 스킵 2. 피처 브랜치