peach-worktree

peach-worktree — feature branch worktree lifecycle management

Scope of responsibility

Mode	Role
`create`	Create a new worktree + feature branch based on the base branch
`status`	Inspect current worktree / branch / PR status, whether base sync is needed before PR, and suggest next steps
`finish`	Integrated flow covering base sync after development completion, verification check, push, PR creation, and suggesting closeout linkage
`closeout`	PR merge, remote feature deletion, base fast-forward, worktree/local branch/leftover folder cleanup
`cleanup`	After merge completion, delete worktree + local branch + remote branch

Not a responsibility (handle with general git operations)

For creating feature implementation commits git add / git commit
Rebase flow when push is rejected

In the cleanup guard, whether the PR is merged and whether it is reflected in base are read-only confirmed. Pre-PR base sync is diagnosed for necessity in status, and only when the user explicitly requests it, it proceeds via merge method through checkpoints. The finish/closeout integrated checkpoint is presented when the user expresses intent to complete/clean up, such as "proceed with finishing", "proceed through PR", "clean up after merge", "clean up worktree", "let's finish". However, before execution, the scope must always be confirmed via checkpoint.

The user can /peach-worktreejust call it. The agent first diagnoses the current worktree, branch, dirty status, PR status, and whether it is reflected in base, then presents mode candidates as a checkpoint.

⚠️ Safety rules (strictly observe)

Do not delete a dirty worktree — if there are changes, stop cleanup and report to the user.
Do not delete a feature branch before merge confirmation — PR merged or base reflection confirmation is required.
Do not delete worktrees other than the requested target — if the target is ambiguous, report status and confirm with the user.
No force push — git push -f, --force, --force-with-lease all require explicit user approval.
git branch -D prohibited — -dif it cannot be deleted with, report the cause and require user approval.
git reset --hard prohibited — explicit user approval required.
The default for pre-PR base sync is merge — do not automatically choose the rebase/force push flow on an already-pushed feature branch.
finish/closeout is one integrated checkpoint — after approval, proceed within the specified scope without additional questions, and stop only on interruption conditions.
Confirm with the user only at checkpoint granularity — do not ask for every minor command; confirm once with a batch summary at each mode's checkpoint.
No direct base merge without a PR — in the default finishing flow, to the base worktree git merge feature/{slug} or git merge --ff-only feature/{slug}do not run. Only when the user explicitly states "direct merge without PR" shall it first report that no PR will remain in the history as a separate checkpoint, then proceed.

0. Two-phase execution model for all requests

peach-worktreedoes not immediately execute the user's sentence as create / finish / closeout / cleanup commands. For every request, first Phase 1 Initialization Diagnosiscollects the current state, and based on the result confirms the executable mode candidates, then Phase 2 Checkpointobtains approval and executes.

Phase 1. Initialization Diagnosis (read-only)

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

Confirm the following items based on the diagnosis results.

worktree list and current location
base / feature branch identification
dirty status
PR open / merged / none
whether the feature is reflected in base
derive mode candidates by combining the request intent and state

Phase 2. Execution Confirmation

Confirm one of create / finish / finish+closeout / closeout / cleanup / residual cleanup.
Present the execution commands and abort conditions as a checkpoint and obtain user approval.
Execute only the approved scope, and after completion verify the worktree / branch / remote branch / base synchronization state.

Expressions such as "clean up the worktree", "wrap up", "let's finish" are state-based wrap-up requests, not deletion commands. Without initialization diagnosis, git worktree add, git worktree remove, git merge, gh pr create, gh pr mergedo not run.

Auto-executable (read-only)

Diagnostic commands that can be run without user confirmation:

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

Entry — automatic mode determination

Even if the user enters only /peach-worktree, the mode is automatically determined from the following signals.

Current state	Automatically determined mode
base branch (develop/main/master) + clean	create (infer task-slug → confirm once at checkpoint)
feature/* branch + PR merged + reflected in base	cleanup
feature/* branch + no PR + already reflected in base (`merge-base --is-ancestor` passed)	cleanup
feature/* branch + clean + pushed + "clean up/wrap up/let's finish" + no PR + not reflected in base	propose finish or finish+closeout candidate
feature/* branch + clean + "wrap up/create PR" request	finish
feature/* branch + clean + "from PR creation to cleanup/all the way" request	finish + closeout integrated
feature/* branch + PR open + "merge/clean up" request	closeout
no worktree registered + only residual folder exists	status report + worktree-cleanup.md Directory-not-empty procedure guidance
feature/* branch + PR open / no PR	status report + next step proposal
feature/* branch + dirty	status report (guidance that "commit/push is not the responsibility of this skill")
Multiple worktrees exist + target ambiguous	status report + target confirmation question

The automatic decision result is reported to the user in one line immediately upon entry, and then proceeds.

Default

base branch: develop → if none, main → if none, master → if all are absent, user confirmation.
feature branch name: feature/{task-slug}
worktree path: ~/source/{project}-{task-slug}
{project}is inferred from the current base worktree folder name, {task-slug}is asked to the user.

1. create procedure

If the user did not directly provide a task-slug, the AI analyzes the context and suggests a branch name and worktree pathand gets confirmation with one checkpoint. If the user explicitly specifies a slug as an argument, inference is skipped and it is used as is.

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)

Only when inference fails (insufficient context or weak basis) or candidates are ambiguous, ask the user directly for the task-slug. Do not start by asking when inference is possible.

For details, see references/worktree-create.md .

2. status procedure

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 안내)

For the detailed determination logic and checkpoint format, see references/worktree-status.md . For safety criteria, see references/worktree-safety-checklist.md — safety criteria for base synchronization before PR .

3. finish procedure — PR preparation after development completion

Proceed from the feature worktree where development is complete to PR creation. For detailed procedures and stop conditions, follow 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 진행 가능 여부 보고

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

After finish completion:

If the PR is mergeable and required checks are absent or passing, suggest "Shall we continue to closeout?"
If PR checks are pending, do not automatically suggest closeout and report that waiting for checks is necessary.
If the PR is not mergeable, do not suggest closeout and report the conflict/review/check status.
If the user requested from the start something like "from PR creation to post-merge cleanup" or "finish it all the way," include the closeout scope in the finish checkpoint.

4. closeout procedure — full cleanup after PR merge

When the PR is mergeable, proceed from merge to worktree folder cleanup. For detailed procedures and stop conditions, follow 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 integrated procedure

Use only when the user requested from the start from PR creation to post-merge cleanup. Bind finish and closeout into a single checkpoint, and execute closeout subsequently only when the mergeable/check status is satisfied after PR creation.

Expressions with a strong intent to clean up after development completion, such as "clean up the worktree," "final cleanup," or "finish and clean up," are interpreted as finish+closeout candidates even if there is no PR. However, before execution, confirm the PR creation/merge/cleanup scope all at once in the integrated checkpoint.

[통합 체크포인트] 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 procedure

선행 가드 (자동 검사, 실패 시 중단 + 보고):
  ✗ 대상 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}

For details, see references/worktree-cleanup.md 및 references/worktree-safety-checklist.md .

Final report format (common to all modes)

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

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

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

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

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

Commands requiring user confirmation

The following commands, even if included in the automatic mode decision flow, Only after checkpoint confirmation executes.

git worktree add
git worktree remove
git branch -d
git push origin feature/{slug} (finish push)
git push origin --delete
git pull --ff-only (For base update, can be executed after guidance)
git merge origin/{base} (For base synchronization before PR, executed after explicit user request + checkpoint)
gh pr create (finish mode)
gh pr merge --merge --delete-branch (closeout mode)
Delete remaining folders at the exact target worktree path to delete (closeout mode, git worktree listafter confirming removal in)

The following commands are not automatically executed by this skill.

For creating feature implementation commits git commit, git rebase, git reset --hard
git branch -D, git push --force*

These are general git operations that the user executes directly or uses another skill for.

Next Steps / Related Skills

Start development in a new worktree → general development flow (peach-team-dev, etc.)
E2E verification → peach-team-e2e
After worktree cleanup, base synchronization check can be re-confirmed with this skill's status mode