Orca Handoff

---
name: orca-handoff
description: >-
  진행 중이거나 새로 시작할 작업을 다른 에이전트에게 완전히 넘길(소유권 이전) 때
  사용 — "핸드오프", "인수인계", "이 작업 다른 에이전트/워크트리로 넘겨",
  "handoff", "handover". 문서 생성만 원하는 요청("핸드오프 문서만 만들어줘")도
  이 스킬이 받아 문서 단계만 수행한다. 단 사용자가 /handoff나 orca-cli 등 특정
  스킬을 명시하면 그 스킬이 우선한다. 넘긴 뒤 지켜보며 조율(폴링·완료 대기·task
  DAG)까지 원하는 요청이면 orchestration — 섞여 있으면 묻는다.
---

# orca-handoff — 소유권 이전 핸드오프

핸드오프 = 소유권 이전. 상대가 받은 것을 확인한 뒤 감시를 멈추고, 그 워크트리에서 작업을 계속하지 않는다(동시 편집 방지). 지켜보며 조율할 거면 이 스킬이 아니라 orchestration이다.

## 0. 라우팅 확인

사용자의 명시 호출이 항상 이긴다 — `/handoff`나 orca-cli를 콕 집으면 그쪽으로. "문서만 만들어달라"는 요청이면 아래 2단계만 수행하고 터미널을 만들지 않는다. "넘기고 끝나면 알려줘"처럼 감시가 섞여 있으면 진행 전에 묻는다(핸드오프인지 오케스트레이션인지).

## 1. 갈래 판별 — 어떤 워크트리로 넘기나

- **미push 커밋, 미커밋 변경(untracked 포함), 이어야 할 브랜치 맥락이 있다** → **같은 워크트리에 새 터미널.** 새 워크트리는 origin에서 갈라지므로 그 브랜치의 로컬 상태가 새 세션의 시야에 없고, git은 같은 브랜치의 이중 체크아웃도 막는다. (사례: 미push 50커밋 브랜치를 독립 워크트리로 넘겼다면 전부 안 보였다.)
- **완전히 새 작업이다** → 독립 워크트리(`--no-parent` 계열).
- **애매하다** → 자동 판정하지 말고 묻는다.

## 2. 지식 문서 — 대화를 압축해 넘긴다

`references/handoff-doc.md`의 규칙(§1)·필수 슬롯(§2)·금지(§3)대로 문서를 만들고, 콜드 리더 검증(§4)을 거친다. 사용자가 밝힌 다음 세션의 목적을 인자로 삼아 문서를 그 목적에 맞춰 재단한다. 산출물(스펙·커밋·diff)은 내용 복제 없이 경로 참조만, 비밀값·PII 는 삭제한다 — 특히 외부 모델(codex 등)로 넘길 때.

레포에 좌표 문서 규약이 있으면(프로젝트 메모리·AGENTS.md가 알려줌) **그 레포 규약이 정한 방식대로만** 갱신·커밋한다 — 이 스킬이 새 쓰기 권한을 만들지 않는다. 내용이 겹치면 핸드오프 문서에는 싣지 않고 좌표 문서 위치를 참조로 적는다.

## 3. 터미널 스폰

**orca-cli 스킬을 Skill 도구로 호출해** 그 규약(CLI resolve·앱 상태 확인·live help로 서브커맨드 확인)을 따른다 — 플래그를 기억이나 예시로 추측하지 않는다. **한 단계** `--command` 프롬프트가 기본형이고, `--json` 응답의 터미널 ID를 보관한다. 형태 예시(실행 전 live help로 확인):

```
orca terminal create --worktree id:<repoId>::<워크트리경로> --title "<인수 제목>" \
  --command "claude --model <현재 모델> --permission-mode auto '<프롬프트>'" --json
```

워크트리 선택자는 live 가이드가 정본이다 — 현재 워크트리의 id는 `worktree current --json`에서 **`id` 필드 전체(`<repoId>::<경로>`)를 복사**한다(리허설 확인: `path:` 선택자는 가이드에 없다).

- 프롬프트는 **한두 줄 경로 안내로 유지**(컨텍스트는 문서가 든다 + 따옴표·멀티라인 인자 파손 회피). 읽기 순서를 번호로: ① 레포 AI 지침 정본(AGENTS.md 등 — 새 세션은 레포 규약을 처음 본다) ② 핸드오프 문서(절대경로) ③ 좌표 문서 항목. 끝에 "읽은 뒤 이해한 상태를 요약하고 시작하라"를 넣는다(4단계 확인의 재료).
- 스폰 기본값은 현재와 같은 claude 모델. 사용자가 codex 등을 지정하면 그쪽 — 명령 형태가 확실치 않으면 실행 전에 사용자에게 보여주고 확인받는다.
- 두 단계(create 후 send)로 갈 수밖에 없으면 반드시 `terminal send ... --enter`.

## 4. 전달 확인 — 상대가 받았을 때 성립한다

보관한 터미널 ID로 `terminal read` 1회. 막 떴다면 짧은 간격 후 1회만 재확인(상한 2회 — 시작 확인이지 폴링이 아니다). 확인 대상: 토큰 소비·도구 호출이 시작됐는지, 프롬프트의 "상태 요약" 지시에 반응하는지.

- 한 단계 `--command` 스폰 뒤의 `terminal wait --for tui-idle`은 **에이전트가 일하는 동안 idle이 되지 않아 timeout이 정상일 수 있다** — 완료 대기로 흐르지 말고 read의 토큰 소비·도구 호출로 판정한다. (tui-idle 대기는 2단계 send 전 기동 대기에 쓰는 것.)

- **미제출 판별**(claude CLI 전용): `❯` 뒤에 프롬프트 글자가 그대로 있고 비용 $0.00 → 제출 안 된 것. `terminal send --enter`로 1회 재제출 후 재확인. (사례: `--enter` 누락으로 글자만 앉아 있었고 사용자가 한참 뒤 발견.)
- 다른 CLI를 스폰했다면 위 판별법 대신 출력에 프롬프트 처리 흔적이 있는지로 판단.
- 그래도 미기동이면 터미널을 남겨둔 채(증거 보존) 상태·시도 내역을 사용자에게 보고하고 멈춘다.

확인 후: 감시 중단, 사용자에게 층별 보고(지식 문서 경로 / 터미널 식별자 / 확인 결과). 세션 정리는 사용자 몫으로 남긴다(물어보되 떠안지 않는다).

## 실패 시

- orca CLI 부재·앱 미기동 → orca-cli 스킬의 상태 확인이 판별. 환경 층 불가면 지식 문서까지만 만들고 경로를 알린 뒤 멈춘다.
- 성공처럼 보고하지 않는다 — 최종 보고는 지식/환경/확인 층별 상태를 구분한다.

## 하지 않는 것

감시·폴링·완료 대기(orchestration 영역) / 레포 특이 규약 하드코딩(각 프로젝트 메모리·AGENTS.md 몫) / 레포 규약 밖의 쓰기 / 세션 정리 떠안기.