{"id":49683985,"url":"https://github.com/willowryu/agent-handoff","last_synced_at":"2026-05-07T09:01:36.756Z","repository":{"id":355649789,"uuid":"1229004036","full_name":"WillowRyu/agent-handoff","owner":"WillowRyu","description":"Strict 3-stage handoff workflow (plan → execute → verify) for coding agents. Disk-backed state lets verify run in a fresh chat.","archived":false,"fork":false,"pushed_at":"2026-05-04T16:54:54.000Z","size":60,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-04T17:37:18.223Z","etag":null,"topics":["agent-skills","ai-agents","aider","claude-code","codex","coding-agent","cursor","gemini-cli","plan-execute-verify","skills"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WillowRyu.png","metadata":{"files":{"readme":"README.ko.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-04T15:47:47.000Z","updated_at":"2026-05-04T16:54:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/WillowRyu/agent-handoff","commit_stats":null,"previous_names":["willowryu/agent-handoff"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/WillowRyu/agent-handoff","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WillowRyu%2Fagent-handoff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WillowRyu%2Fagent-handoff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WillowRyu%2Fagent-handoff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WillowRyu%2Fagent-handoff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WillowRyu","download_url":"https://codeload.github.com/WillowRyu/agent-handoff/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WillowRyu%2Fagent-handoff/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32730282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-07T02:14:30.463Z","status":"ssl_error","status_checked_at":"2026-05-07T02:14:29.405Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-agents","aider","claude-code","codex","coding-agent","cursor","gemini-cli","plan-execute-verify","skills"],"created_at":"2026-05-07T09:01:35.777Z","updated_at":"2026-05-07T09:01:36.749Z","avatar_url":"https://github.com/WillowRyu.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Handoff Skills\n\n[English](README.md) | **한국어**\n\n코딩 에이전트를 위한 엄격한 3단계 핸드오프 워크플로우 — `plan` → `execute` → `verify` — 컨텍스트 사이를 디스크 기반 상태로 이어줍니다.\n\n```mermaid\nflowchart LR\n    A[\"/setup-handoff\u003cbr/\u003e\u003csub\u003econfig.md\u003c/sub\u003e\"] --\u003e B[\"/plan\u003cbr/\u003e\u003csub\u003eplan.md\u003c/sub\u003e\"]\n    B --\u003e C[\"/execute\u003cbr/\u003e\u003csub\u003etask.md + code\u003c/sub\u003e\"]\n    C --\u003e D[\"/verify\u003cbr/\u003e\u003csub\u003ereview.md\u003c/sub\u003e\"]\n    D -.미해결.-\u003e E[\"backlog.md\"]\n    E -.다음 사이클.-\u003e B\n```\n\n## 왜 필요한가\n\n같은 컨텍스트에서 일하는 에이전트는 자신이 만든 결과물을 제대로 검증하지 못합니다. 이 플러그인은 작업을 세 개의 스킬로 나누고 boundary를 강제하며, 상태를 `.handoff/*.md`에 남겨 verify를 새 채팅에서 돌릴 수 있게 합니다. 자세한 배경은 [docs/why-handoff.ko.md](docs/why-handoff.ko.md) 참고.\n\n## 네 개의 스킬\n\n| 스킬 | 사용 시점 | 읽음 | 씀 | 금지 |\n|---|---|---|---|---|\n| `/setup-handoff` | 프로젝트당 한 번 | manifest, 에이전트 가이드, 문서 트리 | `.handoff/config.md` | 코드, 빌드 명령 |\n| `/plan` | 기능/수정 시작 시 | config, backlog | `.handoff/plan.md` | 코드, 빌드 명령 |\n| `/execute` | `/plan` 이후 | config, plan | `.handoff/task.md` + 코드 | test, lint, plan 밖 변경 |\n| `/verify` | `/execute` 이후, 새 채팅 | config, plan, task | `.handoff/review.md`, 정리 | 코드, typecheck (execute가 이미 실행) |\n\n`/execute`는 config의 `typecheck`를 **read-only 컴파일 체크**로 실행합니다 — 타입 에러를 verify까지 끌고 가지 않고 한 단계 일찍 잡음. test/lint/plan-vs-code 판단은 `/verify`에 그대로 (fresh context가 핵심).\n\n## 설치\n\n### 범용 (모든 지원 에이전트 — 권장)\n\n[`vercel-labs/skills`](https://github.com/vercel-labs/skills) 기반. Claude Code, Cursor, Codex, Gemini CLI, Aider 등 50개 이상의 에이전트에서 동작.\n\n\u003e **⚠️ 4개 스킬을 함께 설치하세요.** 스킬은 한 세트로 설계됐습니다: 각 스킬의 gate는 이전 단계가 쓴 상태를 기대합니다 (`/plan`은 `/setup-handoff`가 만든 `config.md`, `/execute`는 `plan.md`, `/verify`는 `task.md`). 부분 설치는 설치되지 않은 슬래시 명령을 가리키는 gate failure를 일으킵니다. `--skill '*'` (또는 `--all`)로 4개 모두 한 번에 설치하세요.\n\n```bash\n# 인터랙티브: 어느 에이전트에 설치할지 선택 (4개 스킬 기본 선택)\nnpx skills@latest add WillowRyu/agent-handoff\n\n# 비인터랙티브: 4개 스킬 모두 Claude Code에 글로벌 설치\nnpx skills@latest add WillowRyu/agent-handoff --skill '*' -g -a claude-code -y\n```\n\n유용한 플래그: `-g` (글로벌, `~/`에 설치), `--list` (dry-run), `--skill '*'` (모든 스킬, 권장), `-a \u003cagent\u003e` (대상 에이전트). `npx skills@latest --help` 참고.\n\n### Claude Code (플러그인 마켓플레이스 대안)\n\n```bash\n/plugin marketplace add WillowRyu/agent-handoff\n/plugin install agent-handoff\n```\n\n## 워크플로우\n\n```\n/setup-handoff              # 한 번만\n/plan \"\u003c작업 설명\u003e\"          # 무엇을 할지 기술\n/execute                    # 새 채팅에서 권장\n/verify                     # 또 다른 새 채팅에서 권장\n```\n\n각 단계의 실제 산출물 예시는 [docs/examples/](docs/examples/) 참고.\n\n## 권한 (Permissions)\n\n각 스킬은 특정 파일을 씁니다. 핸드오프 상태 파일에 대한 쓰기 권한을 에이전트 권한 설정에서 미리 허용해두면 매번 prompt에 막히는 마찰이 줄어듭니다. 나머지 (`/execute` 중 소스 파일 수정, `/verify` 중 `Bash` 실행)는 프로젝트의 기존 관행을 따르세요.\n\n| 스킬 | 필요 권한 |\n|---|---|\n| `setup-handoff` | repo에 대한 Read; `.handoff/config.md`에 대한 Write/Edit |\n| `plan` | repo에 대한 Read; `.handoff/plan.md`와 `.handoff/backlog.md`에 대한 Write/Edit |\n| `execute` | plan에 명시된 소스 파일에 대한 Edit; `.handoff/task.md`에 대한 Write; plan의 sync commands와 config의 `typecheck`를 위한 `Bash` |\n| `verify` | test/lint와 `git diff`(실제 변경분과 plan 비교용)을 위한 `Bash`; `.handoff/{plan,task,review,backlog}.md`에 대한 Edit/Delete |\n\n\u003e **프로젝트 요구사항:** 프로젝트는 git 저장소여야 합니다. `/verify`의 plan-vs-code 검증이 `git diff`로 plan에 적힌 변경이 실제로 들어갔는지 확인하고 plan 밖 변경도 잡아냅니다. git 환경이 아니면 이 검증이 파일 존재 확인 수준으로 약화됩니다.\n\n### Claude Code\n\n`~/.claude/settings.json` (글로벌) 또는 `.claude/settings.json` (프로젝트)에 추가해서 핸드오프 상태 쓰기를 미리 허용:\n\n```json\n{\n  \"permissions\": {\n    \"allow\": [\n      \"Write(.handoff/**)\",\n      \"Edit(.handoff/**)\"\n    ]\n  }\n}\n```\n\n### 다른 에이전트\n\nCursor, Codex, Gemini CLI, Aider 등은 각자의 권한 모델이 있습니다. 스킬은 `.handoff/`와 plan에 명시된 소스 파일 외에는 손대지 않으니, 기존 scoping 관행을 그대로 적용하면 됩니다.\n\n## 설정\n\n`/setup-handoff`이 `.handoff/config.md`를 작성합니다. 평범한 markdown 파일이라 언제든 직접 편집하거나 에이전트에게 편집을 시킬 수 있습니다 — 검증 명령, 응답 언어, 컨벤션 doc 경로, 문서 인덱스 추가/수정 모두 자유. 스킬들은 사이클 도중 `config.md`를 건드리지 않으므로 (`/plan`, `/execute`, `/verify`는 read-only) 사이클 사이에 점진적으로 편집해도 안전합니다.\n\n`/setup-handoff`를 다시 돌리면 `config.md`를 처음부터 다시 작성 (커스텀 추가분 유실), `/setup-handoff --auto`는 인터뷰를 완전히 건너뜁니다 (자동 감지 실패 항목만 묻는 fallback 포함).\n\n## 범위\n\n- 4개 스킬, 엄격한 boundary와 `.handoff/*.md` 디스크 기반 핸드오프\n- Stack-agnostic + **모노레포 인식** 스캔 (pnpm/npm/yarn/turbo/lerna/nx/cargo/go workspaces; workspace 별 docs + verification 후보)\n- Setup 인터뷰가 **응답 언어를 가장 먼저** 물음 — 그 후의 모든 출력 (status 메시지, 작성되는 `.md` 파일)이 해당 언어로\n- Doc index는 클릭 가능한 markdown 링크 + 짧은 설명\n- **Plan이 verification 범위 결정** — `/verify`는 `plan.md`의 `## Verification plan`에 적힌 명령만 실행 (docs-only 변경 같으면 rationale과 함께 전체 skip); 섹션이 없으면 `config.md`로 fallback\n- **`/execute`의 컴파일 체크** — config의 `typecheck`를 execute 안에서 safety net으로 실행. verify 가기 전에 타입 에러 잡고, plan 범위 안에서 1회 fix 시도 후 blocker. (v0.3.0)\n- **위험 태그 change list** — plan 항목에 `low` / `medium` / `high` 위험 태그 부여 가능. execute가 태그로 항목별 체크 빈도를 조절 (low = 끝에 1회, medium = 항목별 컴파일 체크, high = 항목별 체크 + 항목별 task.md 갱신). 태그는 granularity만, 권한은 불변. (v0.3.0)\n- **다단계 plan (`## Phases`)** — 큰 작업을 여러 plan→execute→verify 사이클에 걸쳐 진행. verify가 phase 통과 시 마커만 advance하고 마지막 phase까지 plan.md 유지. Backlog 정리도 마지막 phase까지 보류. (v0.3.0)\n- 선택적 **병렬화** — `/plan`이 `## Parallelization`에 독립 단위 식별; `/execute`가 host(Claude Code Task tool 등) 지원 시 group별 subagent로 분할 dispatch\n- setup-handoff의 `--auto` 모드 (인터뷰 스킵, 자동 감지 실패 항목만 fallback)\n- verify 통과 시 backlog 자동 정리 (single-cycle 또는 final-phase에서만)\n\n## 제외 (Out of scope)\n\n- `/setup-handoff --refresh` (지금은 config.md 수동 편집)\n- backlog 수동 조작 (`/verify --close-backlog ...`)\n- 추가 스킬 (`git-push`, `pr-analyzer`, `verify-all` — v2 가능성)\n- Claude Code 외 도구 형식으로의 자동 변환\n\n## 라이선스\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillowryu%2Fagent-handoff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwillowryu%2Fagent-handoff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillowryu%2Fagent-handoff/lists"}