handoff

name	handoff
description	세션 핸드오프. 컨텍스트가 차기 전에 중요 맥락을 progress.md에 문서화하고 새 세션 킥오프 프롬프트를 클립보드에 복사한다. "핸드오프", "세션 정리하고 넘기자", "컨텍스트 정리", "이어갈 준비" 등의 요청에 사용.

/handoff

auto-compact(자동 요약) 대신 사용자 통제 문서화로 세션을 넘긴다. 컨텍스트의 어떤 부분이 중요한지는 모델의 요약기가 아니라 진행 문서가 결정한다.

끊는 쪽 절반(기록 + 킥오프 프롬프트)을 이 스킬이 자동화하고, 받는 쪽 절반은 session-init.sh의 progress.md 자동 주입(state-schema §5)이 담당한다.

[즉시 실행] 아래 워크플로우를 바로 실행하세요.

옵션

호출	동작
/handoff	기본 — .claude/state/progress.md에 핸드오프 블록 append
/handoff <진행문서경로>	지정 문서(예: REDESIGN_PROGRESS.md)의 ★CURRENT 섹션 교체 갱신

Phase 1 — 맥락 추출 (대화에서)

현재 세션 대화에서 다음 5가지를 추출:

1. 완료 — 이번 세션에서 끝낸 것 (커밋 해시 포함)
2. 잔여 — 하다 만 것 + 정확한 다음 단계
3. 결정 대기 ⚠️ — 사용자 답변이 필요한 미결 질문
4. 환경/전제 변화 — 다음 세션이 알아야 할 환경 사실 (모델/버전/플래그 — 변한 것만)
5. 다음 첫 마디 — 새 세션에 붙여넣을 한 문장 명령

추출 원칙:

• 파일에서 다시 읽을 수 있는 것(코드 내용, 문서 본문)은 적지 않는다 — 포인터만 (file:line)
• 대화에만 존재하는 것을 우선 보존: 결정과 그 이유, 시도했다 버린 접근, 사용자가 말로 준 제약
• 모호함이 있었으면 4섹션 패턴(설계결정/편차/트레이드오프/미결질문 ⚠️)으로 기록 — docs/contracts/state-schema.md §5

Phase 2 — 진행 문서 갱신

• 기본: .claude/state/progress.md에 state-schema §5 포맷으로 새 블록 append
• 진행 문서 지정 시: 해당 문서의 ★CURRENT(또는 최상단 현재 섹션)를 교체 갱신. 이전 ★CURRENT 내용은 문서 하단 히스토리 섹션으로 이동 — 삭제 금지 (정보보존)
• 미결 질문은 ⚠️ 마커 필수 (session-init이 강조 노출)

Phase 3 — 킥오프 프롬프트 생성 + 클립보드 복사

아래 형식으로 생성:

<작업명> 이어가자. /clear 후 새 세션이야.
1. <진행 문서 경로> 의 ★CURRENT(최상단) 읽기 — <한 줄 상태 요약>.
2. 먼저 읽을 것: <파일 1-2개>
3. 잔여: <잔여 한 줄>. 보고 후 진행.
확인 받을 것: <결정 대기 항목, 없으면 생략>
가이드라인(불변): <프로젝트 불변 원칙 1줄>

Bash로 클립보드 복사 (시크릿/키 값 절대 포함 금지):

pbcopy <<'KICKOFF'
<생성한 프롬프트>
KICKOFF

Phase 4 — 마무리 안내

사용자에게 한 줄 보고:

progress.md 갱신 + 킥오프 프롬프트 클립보드 복사 완료. 이제 /clear 입력 후 ⌘V로 붙여넣으세요.

/clear는 사용자 전용 명령이라 모델이 대신 실행할 수 없다. 완전 자동화는 Forge Voice의 ⌘⇧K 매크로로 가능 — /clear 입력 + 클립보드(킥오프) 붙여넣기 + 제출을 단축키 하나로 (tools/forge-voice.lua, /voice setup 시 설치). 음성 셋업을 안 했으면 위 수동 2단계.

graceful skip

• .claude/state/ 없음 → 생성 후 신규 작성
• pbcopy 없음(비 macOS) → 프롬프트를 코드블록으로 출력하고 수동 복사 안내
• 추출할 게 거의 없는 짧은 세션 → phase/next 두 줄만 기록 (4섹션 강제 금지)