Skip to content

hashgraph-online/awesome-codex-plugins / plugins/alpoxdev/hypercore/skills/hyper-handoff

hyper-handoff

Verified

Use this skill when work must pass to a fresh session, agent, or machine through a state memo under `.hyper/handoff/` (write, check, update, close, or resume from one), not for a plain request to continue that names no memo while none is open. Signals: the context is nearly full; a compaction or a session switch is coming; the user asks for a handoff, a continuation note, or to read, restate, or continue from a named memo, even when its HEAD or dirty files no longer match the repository (it reports the mismatch). It writes one memo file holding the original request verbatim, what is being done and why, what is verified, the next steps, the plan, done-when conditions, and locations; proves the memo stands alone by having a reader with no conversation answer fixed questions; and starts a fresh session from that memo alone, restating it in three lines before the work continues. Also not for durable agent memory files, a written work plan, the run state of a plan or goal loop, or a chat summary.

rules/memo-contract.ko.md

View on GitHub
# Memo Contract

메모를 쓰거나 고치기 전에 이 규칙을 사용한다. 언제 쓰는지, 파일이 어디에 있는지, 필수 절과 그 예산, 빼는 것, 비밀 규칙, 고치기를 소유한다.

## 1. When to Write

자연스러운 경계에 쓴다. 마지막 토큰이 아니다. 세션이 아직 공간이 남았을 때 쓴 메모가 한계에서 짜낸 메모보다 좋다.

- 컨텍스트가 거의 다 찼거나, 압축 앞이거나, 세션·에이전트·머신이 바뀌거나, 사용자가 요청하면 쓴다.
- 사용자가 작업을 갑작스러운 중단에서 살려 두고 싶어 할 때 긴 작업의 검증된 단계마다 다시 쓴다. 작업 단위마다 메모 하나. 다시 쓰기는 파일을 갈아치운다.
- 지금 차례에 끝나는 작업에는 쓰지 않는다. 이어갈 것이 없다.
- 쓰는 일 자체에 쓸 공간을 남긴다. 사실 수집, 메모 작성, 혼자 서기 검사가 모두 컨텍스트를 쓰며, 한계에서 시작한 메모는 끝나지 못할 수 있다.
- 세션을 바꾸는 일은 공짜가 아니다. 다음 세션이 메모와 그 메모가 가리키는 파일을 다시 읽는다. 작은 단계마다 바꾸지 않고 컨텍스트나 사용자가 요구할 때 바꾼다. 두 번의 전환 사이에 검증된 단계가 하나도 들어가지 않으면 메모를 또 쓰지 않고 그 사실을 보고한다.

## 2. Where It Lives

- 경로: `.hyper/handoff/<slug>/memo.md`. slug는 사용자의 말이거나 브랜치 이름에서 따는 소문자 하이픈 이름이다.
- `.hyper/`는 git 무시 대상이어야 한다. `git check-ignore -q --no-index .hyper/`로 확인하고, 무시되지 않았으면 저장소의 무시 파일에 `.hyper/`를 이번 쓰기의 일부로 넣고 보고에 그렇게 적는다. 지문을 뜨기 전에 등록한다. 무시 파일 편집 자체가 미커밋 항목이므로, 먼저 뜬 지문은 메모를 쓰는 순간 이미 낡는다.
- 그 경로가 보통 무시 대상이라 푸시나 클론이 메모를 실어 나르지 않는다. 트리거가 다른 머신으로의 이동이면 보고가 그 사실과 메모의 절대 경로를 알리고, 옮기는 두 방법을 이름으로 밝히되 실행하지 않는다. `.hyper/handoff/<slug>/` 디렉터리를 딸린 파일째 다른 머신의 같은 경로로 복사하거나, 메모 본문을 새 세션에 붙여 넣어 그 세션이 이어받기 전에 같은 경로에 저장하게 한다. 메모를 커밋하는 것은 사용자의 몫이며 기본값이 아니다. 메모는 비밀 값을 담지 않고 값이 있는 곳만 가리킨다.
- git 저장소 밖에서는 같은 상대 경로를 작업 디렉터리에 쓴다.
- slug 하나가 작업 한 줄이다. slug마다 메모 파일 하나를 두고 제자리에서 개정하며, 다른 작업은 자기 slug를 갖는다. 이전 메모의 이력은 남기지 않는다. 지금 상태로 충분하다는 것이 요점이다. 메모가 가리키는 데이터 파일(4절)은 옆에 둘 수 있다.
- 열린 메모가 여럿이면 사용자가 댄 경로가 이기고, 그다음 현재 브랜치나 워크트리를 `Where`와 맞춘다. 그래도 둘 이상 맞으면 나열하고(slug, `Written`, `Now`) 한 번 묻는다. 가장 새것을 조용히 고르지 않는다.

## 3. Required Sections

절 이름은 영어 그대로다. 모든 절을 채우고, 해당이 없으면 `none`을 써서 읽는 쪽이 검토했음을 알게 한다.

| Section | Holds | Rule |
|---|---|---|
| Header lines | `Format`(`hyper-handoff/1`, 이 줄이 없으면 `legacy`), `Slug`, `Revision`, `Status`(`open` 또는 `closed (<date>: <reason>)`), `Written`(날짜와 시간), `Written by`(에이전트와 머신), `HEAD:`(`<sha> (<branch>)`, `none (no commits)`, 또는 `none (not a git repository)`), `Dirty:`(`clean`, 또는 개수와 `git status --porcelain` 경로. 20개를 넘으면 개수와 그 출력의 짧은 다이제스트), `Resumed:`(세션이 이어받은 시각, 또는 `none`), `Check` | 지문은 쓰는 시점에 `Where`가 밝힌 워크트리에서 잰다. 검사 줄은 `Check:` 한 철자로 쓰고 `pass`, `unverified-standalone: <question numbers>`, `self: pass`, `self: fail: <question numbers>`, `skipped by user` 중 하나다 |
| `## Original request` | 사용자의 요청을 그대로 인용 | 바꾸지 않음. 줄이지 않음. 번역하지 않음 |
| `## Corrections` | 요청을 바꾸거나 좁히는 이후 사용자 지시, 그리고 일하는 방식에 대한 상시 선호와 방향 지시(무엇을 쓸지, 무엇을 건드리지 않을지, 무엇을 보고할지). 그대로 인용하고 날짜를 붙임 | 없으면 `none` |
| `## Now` | 지금 무엇을 왜 하는지. 최대 다섯 문장 | 작업이 향하는 하나의 결과를 지목함 |
| `## Done` | 끝난 항목과 확인된 발견. 각 항목에 그것을 증명한 검사를 붙이거나 `unverified`를 적음 | 항목마다 한 줄. 발견은 정확한 값과 관측한 곳을 그대로 둠 |
| `## Next` | 순서가 정해진 단계. 첫 단계는 정확한 명령이나 파일이 붙은 구체적인 행동 | 최대 여덟 단계. 뒤 단계는 더 거칠어도 됨. 파괴적이거나 작업 트리 밖으로 나가는 단계에는 `confirm-first`를 붙여 읽는 쪽이 그 단계에 이르기 전에 게이트를 보게 함. 그 표기는 권한을 더하지 않음 |
| `## Plan and done-when` | 계획 출처(경로나 `none`), 요청과 정정이 밝힌 완료 요건 전부, 끝났다고 말하기 전에 통과해야 하는 검사 | 명령이나 파일 보기만으로 확인할 수 있는 조건 최소 하나 |
| `## Where` | 저장소 경로, 브랜치, 워크트리, 머신, 풀 리퀘스트, 서비스, 상태 디렉터리, 이전 세션의 기록, 작업이 기대는 저장소 밖 상태 | 위치 표시만. 각 항목은 해소되거나 `external`이라고 표시함. 세션이나 이동 뒤에 남지 않는 상태는 그렇다고 적음 |
| `## Decisions and dead ends` | 사용자가 내린 결정(누가, 언제), 실패해서 반복하면 안 되는 접근, 필요했던 우회 방법 | 각 막다른 길마다 실패 이유를 적음. 우회 방법에는 통한 명령을 적음 |
| `## Open questions and risks` | 모르는 것, 깨질 수 있는 것, 사용자 차례를 기다리는 것 | 비었으면 `none` |

`Format`은 헤더의 첫 줄이며 메모 형식 버전을 밝힌다. 이 배포는 `hyper-handoff/1`을 쓴다. 슬래시 뒤 숫자는 절을 이름 바꾸거나 뺄 때만 바뀐다. `Format` 줄이 없는 메모는 `legacy`로 읽는다. 읽되 거부하지 않으며 나머지 규칙은 적힌 대로 적용한다. 모르는 주 버전을 만난 읽는 쪽은 그 버전과 해석하지 못한 부분을 보고하고, 그 부분을 추측하지 않는다.

## 4. Budget

- 인용한 요청과 정정을 빼고 최대 100줄을 목표로 한다. 이 스킬의 자체 기본값이며, 메모를 전부 읽게 하려고 고른 값이지 어떤 연구의 수치가 아니다.
- 더 긴 메모는 위치 표시 대신 복사한다는 뜻이다. 세부는 소속 파일로 옮기고 경로나 식별자만 둔다.
- 인용한 요청은 분량에 맞추려 자르지 않는다. 아주 길면 그대로 두고 나머지를 줄인다.
- 남은 작업에 전부 필요한 정확한 결과(결과 목록, 측정값, 식별자 같은 것)는 분량에 맞추려 줄이지 않는다. 메모 옆 파일에 저장하고 그 파일을 가리키거나, 이미 그것을 담고 있는 기록을 가리킨다.

## 5. What Stays Out

메모는 남은 작업을 위한 브리프다. 세션의 역사도 아니고 요약도 아니다. 남은 작업에 필요한 줄만 남긴다. 오래 걸렸다거나 여러 번 나왔다는 것은 남길 이유가 아니다.

- 대화록, 도구 출력, diff, 로그. 중요한 줄 하나와, 필요한 부분만 가져올 만큼 좁은 위치 표시만 둔다. 줄 범위가 붙은 파일이나 필터가 붙은 명령이다.
- 계획, 계획 실행·목표 루프 상태의 복사본. 계획 파일과 상태 디렉터리를 가리키고, `Next`에 그 실행의 이어받기 규칙으로 이어간다고 쓴다.
- 작업에 대한 추론 서술과 느낌. 결론과 결정 이유만 둔다.
- 저장소에서 읽는 편이 메모보다 빠른 것은 무엇이든. 파일 내용이나 바뀐 파일 전체 목록 같은 것이다. 그것을 만드는 명령을 준다.

## 6. Secrets and Personal Data

- 비밀, 토큰, 비밀번호, 키, 개인정보 값을 메모에 쓰지 않는다. 있는 곳을 적는다(예: `값은 프로젝트 비밀 저장소의 NAME 아래에 있으며 복사하지 않았다`).
- 사용자의 요청 자체에 비밀이 들어 있으면 값을 `[redacted]`로 바꿔 인용하고 헤더에 그렇게 적는다. 원래대로 인용하는 규칙에서 허용된 유일한 편집이다.

## 7. Facts, Not Recall

- 브랜치, 워크트리, `HEAD`, 미커밋 상태, 바뀐 파일, 마지막 테스트 결과, 실행 중인 프로세스는 현재 저장소에서 명령으로 모은다. 대화 기억으로 쓰지 않는다. 지문은 `Where`가 밝힌 워크트리에서 `git rev-parse HEAD`와 `git branch --show-current`로 `HEAD:`를, `git status --porcelain`으로 `Dirty:`를 잰다.
- 확인할 수 없는 줄은 `unverified`로 표시한다. 정직한 `unverified`는 자신만만한 추측보다 읽는 쪽이 믿는다.
- 날짜는 절대 날짜로 쓴다. `2026-11-09`라고 쓰지, `어제`라고 쓰지 않는다.
- 이름은 식별자로 적는다. 대화에서만 통하던 말로 적지 않는다. "그 버그"나 "그 파일"이 아니라 `login redirect loop in src/auth/redirect.ts`처럼 적는다.
- 다음 단계가 기대는 값은 설명이 아니라 정확한 값으로 둔다. 출력된 그대로의 오류 줄, 측정한 숫자, 통한 명령이다. 관측한 것과 시험하지 않은 생각을 나눠 적고, 시험하지 않은 생각은 `unverified`로 표시한다.
- 큰 입력을 읽는 작업이면 어느 부분을 읽었고 무엇이 나왔는지 적어, 다음 세션이 같은 부분을 다시 읽지 않게 한다.
- 버전 관리 밖의 상태는 저장소로 되살릴 수 없다. 머신이 바뀔 때의 미커밋 변경, 설치한 의존성, 적용한 마이그레이션, 실행 중인 프로세스, 임시 파일이다. 작업이 기대는 것마다 `Where`에 이름을 적고 남는지 여부를 적는다.

## 8. Revising and Lifecycle

- `Revision`을 늘리고 `Written`과 `Check`를 갱신한 뒤, `Now`, `Next`, `Plan and done-when`을 바꾼 뒤에는 `rules/cold-read-and-resume.md`에서 검사를 다시 돌린다.
- 이전 메모를 보고 새로 쓰지 않고 고쳐서 개정한다. 아직 참인 줄은 그대로 옮기고 바뀐 사실은 저장소로 다시 확인한다. 메모를 보고 다시 쓴 메모는 그때마다 조금씩 더 잃는다.
- 끝난 `Next` 단계를 증명과 함께 `Done`으로 옮긴다. 더는 도달할 수 없는 막다른 길은 뺀다.
- 원 요청과 정정을 지우지 않는다.
- 완료 조건이 충족됐거나, 메모가 대체됐거나, 사용자가 작업을 접으면 `Status: closed (<date>: <reason>)`로 닫는다. 닫힌 메모는 사용자가 지우라고 할 때까지 남기며, 사용자가 이름으로 밝히기 전에는 이어받지 않는다.
- 이어받을 때 헤더에 `Resumed: <time>`를 적는다. 다른 세션이 남긴 최근 `Resumed`가 있고 메모가 아직 열려 있으면 이어 가기 전에 사용자에게 보고한다.
- 쓰기 직전에 헤더를 다시 읽는다. 이 세션이 읽은 뒤 `Revision`이 바뀌었으면 다른 세션이 쓴 것이다. 덮어쓰지 말고, 다시 읽어 고치거나, 멈추고 보고한다.

## Sources

> 확인 2026-11-10. 논문 전문(Section 1-6, Appendix A-G)과 대조했다.

| Claim | Source |
|---|---|
| 정확도를 가장 잘 지킨 압축은 실행 기록을 충실히 옮긴 글이 아니라 앞으로 할 일에 맞춰 고른 브리프였다. 단순 요약은 모든 사실에 같은 무게를 두고 반복된 구간을 지나치게 강조한다(5절, 8절) | [Belcak et al., arXiv:2611.05306 v1](https://arxiv.org/abs/2611.05306), Appendix A |
| 그런 압축에는 작업의 원문 또는 원문에 가까운 사본, 의도와 다음 단계가 붙은 현재 하는 일, 작업에서 나눈 계획, 작업을 끝났다고 볼 요건, 관련 정보를 담은 산출물로 가는 위치 표시가 들어 있었다(3절의 `Original request`, `Now`, `Next`, `Plan and done-when`, `Where`) | 같은 논문, Appendix A |
| 재요약 프롬프트는 목표, 정확한 값이 붙고 관측과 검증하지 않은 생각을 나눈 확인된 사실, 검증 상태가 붙은 적용 변경, 돌린 검사, 막다른 길, 우회 방법과 이미 써 본 명령, 다음 행동과 완료 조건이 붙은 남은 계획, 잘린 출력을 가져올 좁은 명령을 요구한다. 작업별 슬롯은 대화가 바뀌어도 남는 상태, 입력을 어디까지 읽었는지, 완료 전에 필요한 검사를 더한다(3절, 5절, 7절) | 같은 논문, Appendix G |
| 사람이 개입하는 작업에서는 압축 뒤에 핵심 정보와 사용자가 밝힌 선호가 사라질 수 있고, 사용자의 방향 지시 뒤에 이어질 작업에 필요한 것까지 담아야 한다(`Corrections`). 논문은 이것을 흔한 경험으로 적었고, 논문의 실험은 사람 없이 돌았다 | 같은 논문, Appendix A |
| 압축은 손실이 있고, 이미 압축을 품은 이력을 다시 압축하면 더 잃으며, 과거 결과가 정확히 필요한 작업은 고정된 압축 예산에서 실패한다. 논문이 제안한 해법은 기록을 남겨 두고 골라 읽는 것이며, 논문은 이 해법을 평가하지 않았다(4절, 8절, `Where`의 세션 기록) | 같은 논문, Section 3.1 |
| 실험 틀은 압축 차례에 쓸 공간을 남기려고 컨텍스트 한계보다 낮은 임계값에서 압축을 시작했고, 그 공간 안에 압축이 끝나지 않은 실행은 끝냈다(1절) | 같은 논문, Section 2.4.1, Appendix C |
| 빡빡한 압축에서는 전체 작업량이 늘 수 있다. Terminal-Bench 2.1에서 한 모델의 평균 총 길이는 24K 한계에서 72K 토큰이었고 전체 이력에서는 28K였다. 한 오픈웨이트 모델은 16K 한계에서 SWE-bench Verified 정확도가 53.0%에서 3.6%로 떨어졌고, 논문은 장황한 단계 때문에 압축 사이에 진행할 공간이 거의 남지 않은 것을 주된 이유로 든다(1절) | 같은 논문, Table 5, Appendix D |
| 자체 설계이며 논문에서 가져오지 않았고 논문으로 시험하지 않은 것: 절 이름과 순서, 100줄 예산, 파일 위치, 비밀 규칙, `unverified` 표기, 쓰는 동안 명령으로 상태를 다시 확인하는 일(논문의 압축 차례는 명령을 돌리지 않는다), 요청을 메모 안에 싣는 일(논문의 실험 틀은 작업을 다시 넣어 주므로 재요약이 작업을 반복하지 않는다), `HEAD:`/`Dirty:` 지문, `confirm-first` 표기, `Status`와 `Resumed` 수명, 읽지 않은 `Revision`을 덮어쓰지 않는 규칙 | 이 패키지. 패키지 형태만 `instructions/skill/SKILL_AUTHORING.md` |

### 근거 등급

규칙의 형태, 이름, 수치는 `LOCAL`이다. 이 패키지의 설계다. 논문을 인용한 행은 `EXTERNAL-PREPRINT`이다. 검토하지 않은 arXiv v1 하나이며, 사람이 개입하지 않는 자기 실험 틀과 모델에서 측정한 값이고 이 스킬을 돌리는 에이전트에서 측정한 값이 아니다.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall