Skip to content

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

hyper-execute

Verified

[Hyper] Use this skill when the user asks to run an existing written work plan to completion: executing a plan file under `.hyper/plans/` wave by wave in per-wave git worktrees, delegating checkbox work to workers, verifying every done claim independently, recording state and evidence on disk, and delivering locally, as a pull request, or through a full ship flow. Do not use for writing a plan, ad-hoc implementation with no plan file, or commit-only requests.

rules/worktree-and-delivery.ko.md

View on GitHub
# Worktree And Delivery

이 규칙 파일은 첫 웨이브 워크트리를 만들기 전, 웨이브를 반영하기 전, 정리 전에 읽습니다. 통합 기준, 워크트리 생애주기, 반영, 세 가지 전달 방식, 정리를 소유합니다. 선택과 배정은 `execution-loop.ko.md`에 있고, 게이트와 판정은 `verification-gates.ko.md`에 있습니다.

## 1. 통합 기준 기록

0단계에서 메인 워크트리에 체크아웃된 브랜치를 커밋 sha와 함께 `state.json`의 `integration_base`로 기록합니다.

- 모든 웨이브는 그 웨이브에 기록된 기준에서 갈라지고, 로컬 웨이브는 `integration_base`로 다시 반영됩니다.
- 분리된 HEAD는 sha로 기록하고 완료 블록에 경고를 남깁니다. 이후 병합이 진행할 브랜치가 없기 때문입니다.
- 실행 중에 기준이 바뀌지 않습니다. 사용자가 기준을 옮기면 멈추고, 실행 기준을 다시 잡을지 실행을 새로 시작할지 한 번 묻습니다.

## 2. 웨이브 워크트리 만들기

웨이브마다 워크트리 하나를 정해진 위치와 정해진 브랜치로 만듭니다.

```bash
git worktree add -b hyper/<slug>/w<N> <repo-root>/.hyper/worktree/<slug>-w<N> <wave_base>
```

- 경로는 `<repo-root>/.hyper/worktree/<slug>-w<N>`, 브랜치는 `hyper/<slug>/w<N>`입니다.
- `<repo-root>`는 메인 체크아웃의 절대 경로이며 `main_root`로 기록한 값과 같습니다.
- 첫 워크트리를 만들기 전에 `git check-ignore -q --no-index .hyper/`를 실행합니다. 종료 코드가 0이 아니면 `.hyper/`가 무시되지 않은 것이므로 저장소 루트 `.gitignore`(없으면 새로 만듦)에 `.hyper/` 한 줄을 넣고, 그 수정을 이번 실행의 변경으로 기록합니다. 이미 커밋된 `.hyper/` 파일은 추적 해제하지 않습니다.
- 같은 웨이브에서 병렬 레인을 돌리면 레인마다 워크트리를 `<repo-root>/.hyper/worktree/<slug>-w<N>-l<M>`, 브랜치를 `hyper/<slug>/w<N>-l<M>`로 만들고, 모두 같은 `<wave_base>`에서 시작합니다.
- `<wave_base>`는 그 웨이브가 시작하는 브랜치이고, 웨이브별로 `state.json`의 `wave_bases`에 기록합니다.

| 웨이브 | 기준 |
|---|---|
| 웨이브 1 | `integration_base` |
| 웨이브 `N` 안의 레인 `M` | 그 웨이브의 기준. 다른 레인의 브랜치는 절대 쓰지 않음 |
| `local`의 웨이브 `N+1` | 웨이브 `N`이 이미 들어 있는 `integration_base` |
| `--make-pr`의 웨이브 `N+1` | 직전 웨이브의 PR 브랜치인 `hyper/<slug>/w<N>` |
| `--ship`의 웨이브 `N+1` | 웨이브 `N`의 PR이 병합된 뒤의 `integration_base` |

- 배정 전에 `git worktree list --porcelain`으로 확인하고 절대 경로를 `state.json`의 `worktree_path`에 기록합니다.
- `--worktree <absolute-path>`가 주어지면 그 경로가 porcelain 출력에 있고 이 slug가 소유한 브랜치에 있는지 확인합니다. 사용자가 가리킨 워크트리를 새로 만들거나, 옮기거나, 다른 용도로 바꾸지 않습니다. 워크트리가 아니거나 다른 브랜치에 있으면 멈춥니다.

## 3. 안에서만 작업

- 모든 편집, 명령, 테스트, 근거 캡처는 웨이브 워크트리를 작업 디렉터리로 실행합니다.
- 이번 실행이 메인 체크아웃에 쓰는 것은 정확히 세 가지입니다. 반영 병합, `.hyper/` 상태·원장 파일, 계획 체크박스 전환입니다. 구현과 리뷰는 그곳에서 하지 않고, 그 밖의 경로는 쓰지 않습니다.
- 계획, 상태, 원장, 근거 경로는 항상 `state.json`에 기록한 메인 체크아웃 절대 경로인 `main_root` 기준으로 풉니다. `.hyper/`는 gitignore되어 워크트리 안에 없을 수 있으므로, 그 경로들을 워크트리 기준으로 풀지 않습니다.
- 시작할 때 메인 체크아웃의 `git status --porcelain` 출력을 기록합니다. stash, reset, checkout, clean을 하지 않습니다. 실행 중에 그것이 바뀌면 바뀐 경로를 완료 블록에 나열하고 이 실행의 책임으로 돌리지 않습니다.
- 워크트리와 메인 체크아웃 모두에서 그 행의 `Write scope`에 적힌 경로만 스테이징합니다. `git add -A`, `git add .`, `git commit -a`는 쓰지 않습니다.
- 연결된 워크트리는 격리 편의 수단이지 보안 경계가 아닙니다. 적대적인 저장소를 막아 준다고 가정하지 않습니다.

## 4. git이 아닌 경우와 in-place

- git 저장소가 아니고 `--in-place`도 없으면 멈추고 워크트리를 만들 수 없다고 보고합니다. 저장소를 새로 초기화하지 않습니다.
- git 저장소가 아니고 `--in-place`가 있으면 현재 디렉터리에서 작업하고, `state.json`에 `isolation: in-place (no vcs)`를 기록하고, 브랜치·반영·정리 단계를 건너뛰고, 완료 블록에 단서를 밝힙니다. 근거 캡처를 포함한 나머지 규칙은 그대로입니다.
- git 저장소이고 `--in-place`가 있으면 먼저 `git status --porcelain`을 실행합니다. 결과가 비어 있지 않으면 작업을 시작하기 전에 멈추고 더러운 경로를 보고합니다. 자리를 만들려고 stash, reset, 되돌리기를 하지 않습니다. 깨끗하면 현재 체크아웃에서 작업하고, 선언된 `Write scope` 경로만 스테이징해 현재 브랜치에 커밋하는 것으로 반영하며, 워크트리 생성과 제거를 건너뛰고, 줄어든 격리를 완료 블록에 기록합니다.

## 5. 웨이브 반영

웨이브의 모든 행이 `[x]` 또는 `[~]`이고, 모든 판정이 `confirmed`이거나 그 행이 `[~]`이고, 모든 정리 영수증이 있을 때 한 번 반영합니다.

1. `[~]` 행의 미검증 변경을 웨이브 워크트리 안에서 되돌립니다. 추적 파일은 복원하고 그 행이 만든 파일은 제거합니다. 되돌린 사실을 그 행의 `Unmet:` 줄에 기록합니다.
2. 남은 변경을 워크트리에서 커밋합니다. 선언된 `Write scope` 경로만 스테이징하고, 행을 분리할 수 있으면 계획의 `Commit:` 줄마다 커밋 하나를 만듭니다.
3. `local`이면 메인 체크아웃이 깨끗하고 `integration_base`에 있는지 확인합니다. 더러우면 멈추고 더러운 경로를 보고합니다. stash하지 않고 병합하지 않습니다.
4. `local`이면 반영 정책대로 반영합니다. `merge`는 저장소 병합 정책을 따르고 기본은 `--no-ff`이며, `cherry-pick`은 웨이브의 커밋을 순서대로 `integration_base`에 적용합니다. 반영된 sha(또는 sha들)를 그 웨이브 기준에 대고 원장에 기록합니다.
5. `--make-pr`과 `--ship`에서는 PR을 여는 것이 그 웨이브의 반영이고, `--ship`에서는 병합까지가 반영입니다. 다음 웨이브의 기준은 2절 표를 따릅니다. `--make-pr` 웨이브를 통합 기준에 병합하지 않습니다.
6. 병합은 오케스트레이터만 합니다. 워커는 병합하지 않고, 기준 브랜치에 푸시하지 않고, 다른 레인의 충돌을 대신 풀지 않습니다.
7. 웨이브가 병렬 레인으로 돌았다면 두 단계로 반영합니다. 먼저 `state.json`에 기록한 레인 순서대로 각 레인의 커밋을 웨이브 브랜치에 cherry-pick하고, 다음에 웨이브 브랜치를 적용 중인 정책으로 반영합니다. cherry-pick이 충돌한 레인은 멈추고, 오케스트레이터가 풀고, 그 레인의 영향 게이트를 다시 돌린 뒤 추가 검증을 기록합니다. 충돌을 피하려고 레인의 커밋을 버리지 않습니다.

병합 충돌은 오케스트레이터의 일입니다. 웨이브 브랜치에서 풀고, 영향을 받은 게이트를 다시 돌리고, 반영 앞에 새 검증이 있었다는 사실을 기록합니다.

## 6. 전달

| 방식 | 동작 |
|---|---|
| `local`(기본) | 웨이브 브랜치에 커밋하고 통합 기준에 로컬로 병합합니다. 푸시하지 않습니다 |
| `--make-pr` | 웨이브 브랜치를 푸시하고, 그 웨이브의 기준을 대상으로 계획과 행, 근거 경로를 적은 PR을 열고, URL을 인계하고, 병합하지 않습니다 |
| `--ship` | `--make-pr`의 모든 동작 뒤 CI와 리뷰를 감시하고, 워크트리 안에서 새 QA 근거와 함께 고치고, 다시 푸시하고, 초록이 되면 저장소 정책대로 병합합니다. 웨이브 `N`이 병합된 뒤에만 웨이브 `N+1`을 엽니다 |

### 반영 정책

`--land <merge|cherry-pick>`은 웨이브의 커밋이 `integration_base`에 닿는 방식을 고릅니다. 기본은 `merge`입니다.

| 정책 | 쓰는 때 | 기록하는 것 |
|---|---|---|
| `merge`(기본) | 통합 기준이 유일한 대상이고 그 이력에 웨이브가 병합 하나로 보여야 함 | 병합 커밋 sha를 반영된 sha로 기록 |
| `cherry-pick` | 같은 커밋이 다른 브랜치에도 가야 하거나 기준 이력을 선형으로 유지해야 함 | cherry-pick한 sha를 순서대로 반영된 sha들로 기록 |

`cherry-pick`에서는 웨이브 브랜치 끝으로 조상 관계를 판정하지 않습니다. 적용된 커밋은 새 객체이므로 대신 반영된 sha마다 확인합니다.

- 푸시와 PR 생성은 `--make-pr` 또는 `--ship`에서만 일어납니다. 플래그가 없으면 아무것도 기기 밖으로 나가지 않습니다.
- `--make-pr`에서는 웨이브를 쌓습니다. 웨이브 `N+1`은 `hyper/<slug>/w<N>`에서 갈라지고 그 PR은 그 브랜치를 대상으로 열리며, 첫 PR만 통합 기준을 대상으로 합니다. 웨이브 `N`이 들어 있지 않은 통합 기준에서 웨이브 `N+1`을 갈라지게 하지 않고, 웨이브별 기준을 `wave_bases`에 기록합니다.
- `--ship`에서는 웨이브 `N`의 PR이 병합되기 전에 웨이브 `N+1`을 열지 않으므로, 그 기준은 갱신된 통합 기준입니다. 아래 CI 상한이 기다리는 시간을 제한합니다.
- CI 수리 라운드는 PR마다 3회로 제한합니다. 한 라운드는 수리, 새 QA 근거, 푸시를 한 묶음으로 하며 행 시도로 세지 않습니다. 세 번째 라운드에서도 빨간 상태이면 PR URL과 함께 멈추고, `state.json`에 `ci: failing`을 기록하고, 완료 블록에 보고합니다.
- force-push를 하지 않습니다. 거부된 푸시는 원격 메시지를 그대로 보고하며 덮어쓰지 않습니다.
- 통합 기준 브랜치에 직접 푸시하지 않습니다.
- 런타임에 CI나 리뷰 감시 기능이 없으면 `--ship`은 `state.json`에 `ci: unverified`를 기록하고 PR URL과 함께 멈추며, 초록을 확인하지 못했다고 분명히 말합니다. 하지 않은 병합을 했다고 주장하지 않습니다.
- 기본은 웨이브마다 PR 하나입니다. 저장소가 실행당 PR 하나를 기대하면 웨이브 브랜치를 열어 두고 확장하며 마지막 웨이브에서 PR을 열고, 그 선택을 기록합니다.

## 7. 반영 확인 뒤 정리

로컬 병합이든 병합된 PR이든, 그 웨이브 자체의 기준에 반영이 확인된 뒤에만 정리합니다.

1. 웨이브의 근거를 `<main_root>/.hyper/execute/<slug>/evidence/`로 복사하고 복사본이 있는지 확인합니다.
2. `git worktree remove <path>`를 `--force` 없이 실행합니다.
3. 더러운 상태, 미추적 파일, 잠금 때문에 제거가 거부되면 멈추고 경로를 보고합니다. 워크트리는 그대로 둡니다. `--force`로 올리지 않습니다.
4. 브랜치는 반영된 커밋이 그 웨이브의 기준에 있는 것을 확인한 뒤에만 삭제합니다. 로컬 웨이브면 통합 기준, 쌓은 웨이브면 부모 웨이브 브랜치입니다. `merge` 정책에서는 `git merge-base --is-ancestor <landed-sha> <wave_base>`로 확인하고, `cherry-pick` 정책에서는 반영된 sha마다 `git merge-base --is-ancestor <landed-sha> <base>`로 확인합니다. cherry-pick 뒤에는 웨이브 브랜치 끝이 조상이 아니므로 그것으로 판정하지 않습니다. squash 병합이면 브랜치 끝이 조상이 아니므로, 대신 기준의 반영 커밋이나 PR의 병합 상태로 확인합니다. `git branch --merged`를 판정 기준으로 쓰지 않습니다.
5. 원격 브랜치는 푸시되었고 그 PR이 병합된 경우에만 삭제합니다.
6. `<repo-root>/.hyper/worktree/`가 비면 그 디렉터리만 제거하고 `.hyper/`의 나머지는 남깁니다.
7. `cleanup` 원장 행에 제거한 경로와 브랜치, 남긴 항목과 그 사유를 적습니다.

## 8. 실패 대응

| 증상 | 대응 |
|---|---|
| `git worktree add` 실패 | git 오류를 그대로 보고하고 멈춥니다. 메인 체크아웃 편집으로 대체하지 않습니다 |
| `--worktree` 경로가 목록에 없거나 다른 브랜치에 있음 | 멈추고 불일치를 보고합니다 |
| 반영 시점에 메인 체크아웃이 더러움 | 멈추고 더러운 경로를 나열합니다. 그대로 둡니다 |
| `--in-place` 전에 메인 체크아웃이 더러움 | 작업 시작 전에 멈추고 더러운 경로를 나열합니다. stash하거나 되돌리지 않습니다 |
| 병합 충돌 | 웨이브 브랜치에서 풀고, 영향받은 게이트를 다시 돌리고, 추가 검증을 기록합니다 |
| 푸시 거부 | 원격 메시지를 보고합니다. force-push하지 않습니다 |
| CI 실패 | 워크트리에서 고치고 새 QA 근거를 만들고 다시 푸시합니다. 행 시도가 아니라 CI 수리 라운드로 셉니다 |
| 세 번의 CI 수리 라운드 뒤에도 CI 실패 | PR URL과 함께 멈추고, `ci: failing`을 기록하고, 완료 블록에 보고합니다 |
| `git worktree remove` 거부 | 워크트리를 유지하고 멈춥니다. `--force`를 쓰지 않습니다 |
| 반영된 커밋을 기준에서 찾을 수 없음 | 반영 미확인으로 보고, 워크트리를 유지하고 보고합니다 |
| 레인 cherry-pick 충돌 | 그 레인을 멈추고, 웨이브 워크트리에서 풀고, 그 레인의 영향 게이트를 다시 돌리고, 추가 검증을 기록합니다 |

## Sources

> 확인 2026-11-03.

| Claim | Source |
|---|---|
| 웨이브별 워크트리, 브랜치 이름, 통합 기준 반영, 세 가지 전달 방식, `--force` 없는 정리는 `ulw-execute` 스킬을 각색한 것 | <https://github.com/code-yeongyu/oh-my-openagent/tree/0d80470e4201925727e88afbafcdf24d7801a588> |
| 연결된 worktree는 보안 경계가 아니다 | `instructions/autoresearch/references/safety-and-observability.md` |
| 정지 조건에는 관찰 가능한 검사가 필요하고, 보호 장치가 실패하면 확대가 아니라 정지한다 | `instructions/loop-engineering/LOOP_ENGINEERING.md` |
| 부모만 통합하고, 부모가 join을 검증한다 | `instructions/context-engineering/references/parallel-workflows.md` |

### 근거 등급

`LOCAL` - 이 파일은 위에 적은 원본 스킬을 각색한 이 패키지의 절차입니다. 기본 `--no-ff` 병합과 `--land cherry-pick` 선택지, 웨이브당 PR 하나 기본값, squash 병합 뒤 브랜치 삭제 판정은 이 패키지가 고른 값이며, squash된 반영이 병합되지 않은 것처럼 보이는 브랜치를 남기지 않게 하려고 정했습니다.
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: 468kUpdated 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: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated 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: 321kUpdated Claude CodeCodexVerifiedInstall