peachsolution/peach-worktree

peach-worktree — 기능 브랜치 워크트리 라이프사이클 관리

책임 범위

| 모드 | 역할 | |------|------| | create | base 브랜치 기준으로 새 worktree + feature 브랜치 생성 | | status | 현재 worktree / branch / PR 상태 점검, PR 전 base 동기화 필요 여부, 다음 단계 제안 | | finish | 개발 완료 후 base 동기화, 검증 확인, push, PR 생성, closeout 연결 제안까지 통합 진행 | | closeout | PR 병합, 원격 feature 삭제, base fast-forward, worktree/로컬 브랜치/잔여 폴더 정리 | | cleanup | 병합 완료 후 worktree + 로컬 브랜치 + 원격 브랜치 삭제 |

책임 아님 (일반 git 작업으로 처리)

• 기능 구현 커밋 생성용 git add / git commit
• push rejected 시 rebase 흐름

cleanup 가드에서 PR 머지 여부와 base 반영 여부는 읽기 전용으로 확인한다. PR 전 base 동기화는 status에서 필요 여부를 진단하고, 사용자가 명시 요청한 경우에만 merge 방식으로 체크포인트를 거쳐 진행한다. finish/closeout 통합 체크포인트는 사용자가 "마무리 진행", "PR까지 진행", "머지 후 정리", "워크트리 정리", "끝내자"처럼 완료·정리 의도를 표현한 경우에 제시한다. 단, 실행 전 반드시 체크포인트로 범위를 확인한다.

사용자는 /peach-worktree만 호출해도 된다. 에이전트는 현재 worktree, 브랜치, dirty 여부, PR 상태, base 반영 여부를 먼저 진단한 뒤 mode 후보를 체크포인트로 제시한다.

---

⚠️ 안전 규칙 (절대 준수)

1. dirty worktree 삭제 금지 — 변경사항이 있으면 cleanup 중단, 사용자에게 보고.
2. merge 확인 전 feature 브랜치 삭제 금지 — PR merged 또는 base 반영 확인 필수.
3. 요청 대상 외 worktree 삭제 금지 — 대상이 모호하면 status 보고 후 사용자 확인.
4. force push 금지 — git push -f, --force, --force-with-lease 모두 사용자 명시 승인 필수.
5. git branch -D 금지 — -d로 안 지워지면 원인 보고 후 사용자 승인 필수.
6. git reset --hard 금지 — 사용자 명시 승인 필수.
7. PR 전 base 동기화 기본값은 merge — 이미 push된 feature 브랜치에서 rebase/force push 흐름을 자동 선택하지 않는다.
8. finish/closeout은 통합 체크포인트 1회 — 승인 후에는 명시된 범위 안에서 추가 질문 없이 진행하고, 중단 조건에서만 멈춘다.
9. 체크포인트 단위로만 사용자 확인 — 자잘한 명령마다 묻지 말고, 모드별 체크포인트에서 일괄 요약 1회 확인.
10. PR 없는 직접 base merge 금지 — 마무리 기본 흐름에서 base worktree에 git merge feature/{slug} 또는 git merge --ff-only feature/{slug}를 실행하지 않는다. 사용자가 "PR 없이 직접 merge"를 명시한 경우에만 별도 체크포인트로 이력상 PR이 남지 않음을 먼저 보고하고 진행한다.

---

0. 모든 요청의 2단계 실행 모델

peach-worktree는 사용자 문장을 바로 create / finish / closeout / cleanup 명령으로 실행하지 않는다. 모든 요청은 먼저 Phase 1 초기화 진단으로 현재 상태를 수집하고, 그 결과로 실행 가능한 mode 후보를 확정한 뒤 Phase 2 체크포인트에서 승인 받아 실행한다.

Phase 1. 초기화 진단 (읽기 전용)

git worktree list
git status --short --branch          # 대상 worktree
git status --short --branch          # base worktree
git fetch origin --prune
gh pr list --head feature/{slug} --state all --json number,state,mergedAt,mergeStateStatus,url
git merge-base --is-ancestor feature/{slug} origin/{base}
git rev-list --left-right --count origin/{base}...HEAD

진단 결과로 아래 항목을 확인한다.

• worktree 목록 및 현재 위치
• base / feature 브랜치 식별
• dirty 여부
• PR open / merged / 없음
• feature가 base에 반영됐는지 여부
• 요청 의도와 상태를 조합해 mode 후보 도출

Phase 2. 실행 확정

• create / finish / finish+closeout / closeout / cleanup / residual cleanup 중 하나를 확정한다.
• 실행 명령과 중단 조건을 체크포인트로 제시하고 사용자 승인을 받는다.
• 승인된 범위만 실행하고, 완료 후 worktree / 브랜치 / 원격 브랜치 / base 동기화 상태를 검증한다.

"워크트리 정리", "마무리", "끝내자" 같은 표현은 삭제 명령이 아니라 상태 기반 마무리 요청으로 해석한다. 초기화 진단 없이 git worktree add, git worktree remove, git merge, gh pr create, gh pr merge를 실행하지 않는다.

---

자동 실행 가능 (읽기 전용)

사용자 확인 없이 실행 가능한 진단 명령:

git status --short --branch
git branch --list
git branch -vv
git branch -r
git worktree list
git fetch origin --prune
git log --oneline --decorate --graph --max-count=8
git rev-list --left-right --count origin/{base}...HEAD
git merge-base --is-ancestor origin/{base} HEAD
git diff --stat
git diff --check
gh pr list --head feature/{slug} --state all --json number,state,mergedAt,baseRefName,headRefName,mergeStateStatus,url
gh pr view feature/{slug} --json number,state,mergedAt,baseRefName,headRefName,mergeStateStatus,url
gh pr status

---

진입 — mode 자동 판단

사용자가 /peach-worktree만 입력해도 다음 신호로 mode를 자동 결정한다.

| 현재 상태 | 자동 결정 mode | |---|---| | base 브랜치(develop/main/master) + clean | create (task-slug 추론 → 체크포인트 1회 컨펌) | | feature/* 브랜치 + PR merged + base 반영됨 | cleanup | | feature/* 브랜치 + PR 없음 + base에 이미 반영됨 (merge-base --is-ancestor 통과) | cleanup | | feature/* 브랜치 + clean + pushed + "정리/마무리/끝내자" + PR 없음 + base 미반영 | finish 또는 finish+closeout 후보 제안 | | feature/* 브랜치 + clean + "마무리/PR 생성" 요청 | finish | | feature/* 브랜치 + clean + "PR 생성부터 정리까지/끝까지" 요청 | finish + closeout 통합 | | feature/* 브랜치 + PR open + "머지/정리" 요청 | closeout | | worktree 등록 없음 + 잔여 폴더만 존재 | status 보고 + worktree-cleanup.md Directory-not-empty 절차 안내 | | feature/* 브랜치 + PR open / PR 없음 | status 보고 + 다음 단계 제안 | | feature/* 브랜치 + dirty | status 보고 ("commit/push는 본 스킬 책임 아님" 안내) | | 여러 worktree 존재 + 대상 모호 | status 보고 + 대상 확인 질문 |

자동 결정 결과는 진입 직후 사용자에게 한 줄로 보고하고 진행한다.

---

기본값

• base 브랜치: develop → 없으면 main → 없으면 master → 모두 없으면 사용자 확인.
• feature 브랜치명: feature/{task-slug}
• worktree 경로: ~/source/{project}-{task-slug}
• {project}는 현재 base worktree 폴더명에서 추론, {task-slug}는 사용자에게 질문.

---

1. create 절차

사용자가 task-slug를 직접 주지 않은 경우, AI가 컨텍스트를 분석해 브랜치명과 worktree 경로를 제안하고 체크포인트 1회로 컨펌받는다. 사용자가 인자로 slug를 명시하면 추론을 생략하고 그대로 사용한다.

1) git status --short --branch                       (자동)
2) git fetch origin --prune                          (자동)
3) base 브랜치 결정 (develop → main → master → 질문)  (자동/질문)
4) git pull --ff-only origin {base}                  (자동)
5) task-slug / 경로 분석·제안                         (자동, 사용자 명시 시 생략)
     - 최근 대화 컨텍스트에서 작업 주제 추출
     - 현재 base worktree 폴더명에서 project 추론
     - git status 변경 파일 패턴으로 도메인 보조 판단
     - git worktree list로 중복 slug/경로 회피
6) [체크포인트 1] 일괄 확인 (제안 + 추론 근거):
     - base 브랜치
     - feature 브랜치명 (제안)
     - worktree 경로 (제안)
     - 추론 근거 1~2줄
     - 실행할 명령
     - "그대로 진행 / 다른 이름 / 취소" 중 응답 요청
7) git worktree add {경로} -b feature/{slug} {base}  (컨펌 후 실행)
8) 결과 보고 (worktree list)

추론 실패(컨텍스트 부족·근거 빈약)나 후보가 모호할 때만 task-slug를 사용자에게 직접 묻는다. 추론이 가능한 상황에서 묻기부터 하지 않는다.

상세는 references/worktree-create.md 참조.

---

2. status 절차

1) git worktree list                                 (자동)
2) git status --short --branch (대상 worktree)        (자동)
3) git branch -vv                                    (자동)
4) gh pr status / gh pr view (있으면)                (자동)
5) base ↔ origin/base 동기화 확인                    (자동)
6) origin/{base}가 현재 feature에 포함됐는지 확인     (자동)
7) 보고:
     - 현재 worktree 목록
     - 현재 브랜치 / dirty 여부
     - PR 상태 (open / merged / 없음)
     - base 동기화 여부
     - PR 전 base 동기화 필요 여부
     - 다음 단계 제안 (create / cleanup / 일반 git 안내)

상세 판정 로직과 체크포인트 형식은 references/worktree-status.md 참조. 안전 기준은 references/worktree-safety-checklist.md — PR 전 base 동기화 안전 기준 참조.

---

3. finish 절차 — 개발 완료 후 PR 준비

개발이 완료된 feature worktree에서 PR 생성까지 진행한다. 자세한 절차와 중단 조건은 references/worktree-finish-closeout.md를 따른다.

선행 가드 (자동 검사, 실패 시 중단 + 보고):
  ✗ feature worktree dirty             → 중단, commit 필요 보고
  ✗ 대상 feature / base 불명확          → 중단, 대상 확인
  ✗ 테스트/빌드 증거 없음               → 실행할 검증 명령을 체크포인트에 포함
  ✗ origin/{base} merge conflict        → 중단, 충돌 파일 보고

[통합 체크포인트] finish
  - origin/{base} 반영 필요 시 git merge origin/{base}
  - 지정 검증 명령 실행
  - git push origin feature/{slug}
  - gh pr create --base {base} --head feature/{slug}
  - PR 상태 확인 후 closeout 진행 가능 여부 보고

진행 중 추가 질문 없음:
  - 통합 체크포인트에서 승인된 범위는 계속 실행
  - 실패/충돌/테스트 실패/인증 실패에서만 중단

finish 완료 후:

• PR이 mergeable이고 필수 check가 없거나 통과 상태면 "이어서 closeout까지 진행할까요?"를 제안한다.
• PR check가 pending이면 closeout을 자동 제안하지 않고 check 대기 필요를 보고한다.
• PR이 not mergeable이면 closeout을 제안하지 않고 충돌/리뷰/check 상태를 보고한다.
• 사용자가 처음부터 "PR 생성부터 머지 후 정리까지", "끝까지 마무리"처럼 요청했다면 finish 체크포인트에 closeout 범위까지 포함한다.

---

4. closeout 절차 — PR 병합 후 전체 정리

PR이 mergeable 상태일 때 병합부터 worktree 폴더 정리까지 진행한다. 자세한 절차와 중단 조건은 references/worktree-finish-closeout.md를 따른다.

선행 가드 (자동 검사, 실패 시 중단 + 보고):
  ✗ PR not mergeable                    → 중단, PR 상태 보고
  ✗ feature worktree dirty              → 중단, 변경 내역 보고
  ✗ 삭제 대상 worktree 불명확            → 중단, 대상 확인
  ✗ base worktree dirty                 → 중단, base 상태 보고

[통합 체크포인트] closeout
  - gh pr merge {number} --merge --delete-branch
  - git fetch origin --prune
  - base worktree에서 git pull --ff-only origin {base}
  - git worktree remove {경로}
  - git branch -d feature/{slug}
  - 필요 시 정확한 잔여 worktree 폴더 삭제

진행 중 추가 질문 없음:
  - 통합 체크포인트에서 승인된 범위는 계속 실행
  - merge 실패/삭제 실패/미반영 의심/dirty 상태에서만 중단

---

5. finish + closeout 통합 절차

사용자가 처음부터 PR 생성부터 병합 후 정리까지 요청한 경우에만 사용한다. finish와 closeout을 하나의 체크포인트에 묶고, PR 생성 이후 mergeable/check 상태가 만족될 때만 closeout을 이어서 실행한다.

"워크트리 정리", "마무리 정리", "끝내고 정리"처럼 개발 완료 후 정리 의도가 강한 표현은 PR이 없더라도 finish+closeout 후보로 해석한다. 단, 실행 전 통합 체크포인트에서 PR 생성/병합/정리 범위를 한 번에 확인한다.

[통합 체크포인트] finish + closeout
  - origin/{base} 반영 필요 시 git merge origin/{base}
  - 지정 검증 명령 실행
  - git push origin feature/{slug}
  - PR이 없으면 gh pr create --base {base} --head feature/{slug}
  - PR mergeable/check 통과 확인
  - gh pr merge {number} --merge --delete-branch
  - base worktree에서 git pull --ff-only origin {base}
  - git worktree remove {경로}
  - git branch -d feature/{slug}
  - 승인된 feature worktree 경로의 잔여 폴더 삭제

자동 중단:
  - PR 생성 후 check pending
  - PR not mergeable
  - required check 실패
  - 그 외 finish/closeout 중단 조건

---

6. cleanup 절차

선행 가드 (자동 검사, 실패 시 중단 + 보고):
  ✗ 대상 worktree 명시 안 됨        → 중단, 대상 확인 질문
  ✗ 대상 worktree dirty              → 중단, 변경 내역 보고
  ✗ feature 브랜치가 base에 미반영    → 중단, PR 상태 보고
  ✗ PR이 open 상태                   → 중단, PR 상태 보고

[체크포인트 4] 일괄 확인:
  - 삭제할 worktree 경로
  - 삭제할 로컬 feature 브랜치
  - 삭제할 원격 feature 브랜치
  - 유지할 다른 worktree 목록

실행 (순서 고정):
  1) git worktree remove {경로}
  2) git branch -d feature/{slug}
  3) git push origin --delete feature/{slug}

검증 (자동):
  git worktree list
  git branch --list
  git branch -r | grep feature/{slug}

상세는 references/worktree-cleanup.md 및 references/worktree-safety-checklist.md 참조.

---

최종 보고 형식 (모든 모드 공통)

[ peach-worktree / mode={create|status|finish|closeout|cleanup} ]

수행 결과:
  - (해당 모드의 핵심 결과)

유지 중:
  - base worktree 경로 / 브랜치
  - 다른 작업 worktree 목록 (있으면)

base 상태:
  - {base} ↔ origin/{base} 동기화 여부
  - PR 전 base 동기화 필요 여부

다음 단계 제안:
  - (다음에 사용자가 할 일을 1~2줄)

---

사용자 확인 필수 명령

다음 명령은 자동 mode 결정 흐름에 포함되어 있어도 체크포인트 확인 후에만 실행한다.

• git worktree add
• git worktree remove
• git branch -d
• git push origin feature/{slug} (finish push)
• git push origin --delete
• git pull --ff-only (base 갱신용은 안내 후 실행 가능)
• git merge origin/{base} (PR 전 base 동기화용, 사용자 명시 요청 + 체크포인트 후 실행)
• gh pr create (finish 모드)
• gh pr merge --merge --delete-branch (closeout 모드)
• 정확한 삭제 대상 worktree 경로의 잔여 폴더 삭제 (closeout 모드, git worktree list에서 제거 확인 후)

다음 명령은 본 스킬에서 자동 실행하지 않는다.

• 기능 구현 커밋 생성용 git commit, git rebase, git reset --hard
• git branch -D, git push --force*

이들은 일반 git 작업으로 사용자가 직접 실행하거나 다른 스킬을 사용한다.

---

다음 단계 / 연관 스킬

• 새 worktree에서 개발 시작 → 일반 개발 흐름 (peach-team-dev 등)
• E2E 검증 → peach-team-e2e
• worktree 정리 후 base 동기화 점검은 본 스킬 status 모드로 재확인 가능