Skip to content

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

hyper-plan

Verified

[Hyper] Use this skill when the user asks to plan a change before implementation - a feature, refactor, migration, fix, or multi-step build - and expects a decision-complete plan file that a worker can execute without another interview. It explores read-only, writes only a draft and a plan under `.hyper/`, reviews the plan for gaps, then continues into execution by default unless the user asked for a plan only. Do not use for PRD, spec, or wireframe packages; for immediate edits that need no plan; or for research reports.

rules/plan-review.ko.md

View on GitHub
# 계획 리뷰

계획 파일이 완성되면 이 파일을 사용합니다. 리뷰는 계획을 인계할 수 있는지 판정합니다. 리뷰어는 계획을 쓴 사람이 아닙니다.

## 1. 항상 실행하는 갭 분석

모든 계획은 `## TL;DR`와 `## Todos`를 포함한 완성 파일 전체를 대상으로 독립 갭 분석을 한 번 받습니다. 계획을 쓰지 않은 새 subagent를 우선합니다. subagent 기능이 없으면 §6의 구조 자기 점검과 이 체크리스트를 직접 실행하고 드래프트에 `reviewer: self (no subagent capability)`를 기록합니다.

다음 항목을 점검합니다.

- 요구사항이나 받아들인 결정이 todo 또는 `### Must NOT have`와 모순된다
- 이상 상태에서 영향받는 사용자 하나가 빠졌다
- `GAP-` 행을 닫는 todo가 없다
- `IS-` 행에 `## Success criteria`의 증명 QA가 없다
- 제약이 빠졌다: 예산, 지정 스택, 예상 규모, 대상 사용자나 규정
- 요청과 근거가 뒷받침하지 않는 범위를 더했다
- 결과를 바꾸는 채택 가정이 산문에만 있다
- todo에 실행 가능한 수용 조건이 없거나 QA가 사람의 판단을 요구한다
- 같은 wave의 todo 두 개가 쓰기 범위를 공유한다
- 의존성 행렬이 wave 배정과 어긋난다
- `F1`부터 `F4`가 없거나, 부족분이 todo가 아니라 메모로 적혔다
- 커밋 줄이 저장소 관례를 무시한다

## 2. 고정밀 리뷰

`review_required: true`일 때 이중 리뷰를 실행합니다. 사용자가 정확도를 더 요구했거나, 의도가 UNCLEAR이고 작업이 Trivial이 아닌 경우입니다.

- 계획을 쓰지 않은 독립 리뷰어 두 명이 완성된 계획 파일을 모두 읽습니다.
- 두 리뷰어를 한 턴에 함께 띄우고 병렬로 작업하게 합니다. 각 리뷰어에게 계획 경로, §3의 블로커 범주, 아래 판정 형식, 읽기 전용 범위를 줍니다.
- 한 라운드는 리뷰어 각자의 통과 한 번입니다.
- 인계 전에 두 리뷰어 모두 승인해야 합니다. 끝내지 못한 리뷰어는 `inconclusive`를 내고, 이는 승인이 아닙니다.

모든 리뷰어의 판정 형식. 모든 판정은 §9의 바인딩 필드 두 개도 함께 넣습니다.

```text
round_id: <id of the current review round>
plan_sha256: <shasum -a 256 of the plan file at review time>
verdict: approve | changes_requested | inconclusive
blockers:
  - category: <one of the six in §3> | evidence: <path:line or missing row> | change: <smallest fix>
notes:
  - <non-blocking observation>
```

## 3. 블로커 자격

발견은 아래 범주 중 하나를 구체적 근거와 함께 지목할 때만 블로커가 됩니다.

1. 명시적 요구사항이나 받아들인 결정을 위반한다
2. 이미 실패 중인 회귀를 무시한다
3. 재현 가능한 깨진 흐름을 계획한다
4. 구체적인 보안, 데이터 손실, 호환성 위험을 처리하지 않는다
5. 외부 API, 공급자, 릴리스 계약 충돌을 놓친다
6. `IS-` 행이 대응 todo 없이 남거나 영향받는 사용자에게 도달할 수 없다

나머지는 모두 비블로커 노트입니다. 남은 항목이 전부 노트인 승인은 승인으로 칩니다.

## 4. 범위가 정해진 수렴

- 블로커 원장은 1라운드 뒤 고정합니다. 1라운드의 블로커 자격 발견만 원장에 들어가고, 이후 라운드는 그것을 닫을 수는 있어도 무관한 항목을 더하지 못합니다.
- 앞선 라운드가 새 블로커 자격 발견을 최소 하나 더했거나 원장 블로커를 최소 하나 닫았을 때만 다음 라운드를 돌립니다.
- 둘 다 하지 못하고 승인도 하지 못한 라운드에서 리뷰를 끝냅니다.
- 원장 상태와 무관하게 최대 3라운드입니다.
- 수정은 가장 작은 변경으로 하고 범위를 넓히지 않습니다. 수정은 계획 파일과 드래프트만 건드리고 제품 코드는 건드리지 않습니다. 계획의 형태를 바꾸는 수정은 새 라운드로 다시 들어갑니다.
- 수렴하지 않으면 멈춥니다. 열린 블로커를 근거와 함께 보고하고 권장안이 붙은 질문 하나를 한 뒤 `Auto-execute: no (review did not converge after <n> rounds)`를 기록합니다.

## 5. subagent가 없을 때의 대체

subagent 기능이 없으면 다음과 같이 합니다.

- 갭 분석은 결정적 구조 점검과 §1 체크리스트로 하고 `reviewer: self` 한계를 함께 기록합니다
- 인계 요약은 독립 리뷰를 했다고 하지 않고 그 한계를 밝힙니다
- 필요한 고정밀 이중 리뷰는 충족할 수 없습니다. 흉내 내지 않습니다. 한계를 보고하고 `Auto-execute: no (high-accuracy review needs independent reviewers)`를 기록한 뒤 멈춥니다.

## 6. 구조 자기 점검

완성된 파일에 아래 점검을 실행하고 결과를 드래프트에 기록합니다.

| Check | Pass condition |
|---|---|
| 위치 | 파일이 `.hyper/plans/<slug>.md`이고 slug가 `^[a-z0-9]+(-[a-z0-9]+)*$`에 맞는다 |
| 제목 | `## ` 제목이 패밀리 목록과 순서와 문구까지 같다 |
| todo 행 | 모든 실행 항목이 `## Todos` 안의 column-zero `- [ ] <N>. ` 행이다 |
| 번호 | `N`이 유일한 양의 정수이고 `F` 행이 `## Todos`에 없다 |
| 중첩 필드 | 모든 todo가 `Wave`, `Depends on`, `Write scope`, `References`, `Acceptance`, `QA happy`, `QA failure`, `Commit`, `Tier`를 그 순서로 갖춘다 |
| tier | 모든 tier가 `Tier: low, medium, high` 중 하나와 ` - <reason>` 형식이다 |
| 의존성 | 모든 `Depends on`이 있는 todo를 가리키고, 각 todo가 정확히 한 wave에 있다 |
| 행렬 | 의존성 행렬이 모든 todo를 그 행과 같은 wave로 적는다 |
| 최종 wave | `F1`, `F2`, `F3`, `F4` 행이 패밀리 문구로 있다 |
| 성공 표 | 모든 `IS-` 행이 전달 todo, 증명 QA, 근거 경로와 함께 있다 |
| 인계 | `Auto-execute`, `Delivery`, `Plan-only requested` 줄이 유효한 값으로 있다 |
| 노력도 | `## TL;DR`에 구간이 정확히 하나 있고 시간이나 일수 추정이 없다 |
| 산문 과제 | 제목, 문단, 일반 불릿이 todo를 대신하지 않는다 |
| 변경과 증명 | 다른 todo의 변경을 위한 테스트만 추가하는 todo가 없다. 그런 쌍은 소스와 테스트를 모두 `Write scope`에 담은 한 행으로 합친다 |

실패한 점검은 인계 전에 고칩니다. 새 근거 없이 고칠 수 없는 점검은 실행을 멈춥니다.

## 7. 발견 접어 넣기

- 모든 발견을 계획의 변경으로 접어 넣습니다. 새 todo, 바뀐 수용 점검, 새 QA 방향, 행 수정 중 하나입니다.
- 최종 검증 wave에서 나온 부족분은 새 번호 todo가 되고 메모가 되지 않습니다.
- 접어 넣은 발견마다 범주와 바꾼 내용을 드래프트의 review 절에 기록합니다.
- 블로커를 조용히 받아들이지 않고, 자격 기준을 왜 통과하지 못하는지 밝히지 않은 채 노트로 낮추지도 않습니다.

## 8. 리뷰 기록과 무효화

드래프트에 라운드 수, 리뷰어 신원이나 자기 검토 한계, 각 판정, 받아들인 블로커, 열린 노트, 리뷰한 계획 경로를 기록합니다. 모든 기록에는 §2와 §9의 `round_id`와 `plan_sha256`도 함께 넣습니다. 승인 뒤에 계획이 바뀌면 승인은 무효입니다. 인계 전에 새 판본으로 필요한 리뷰를 다시 실행합니다. 계획이 편집되면 `plan_sha256`이 바뀌므로, 편집 전에 기록된 승인은 편집 뒤에 받아들여지지 않습니다.

`## Handoff`의 세 줄(`Auto-execute`, `Delivery`, `Plan-only requested`)은 예외입니다. 계획 내용이 아니라 인계 결정을 기록하는 줄이고, 리뷰 판정 뒤에 씁니다. 이 줄을 고쳐도 승인은 무효가 되지 않고 리뷰 라운드도 새로 시작하지 않습니다. `## Handoff` 위쪽이 바뀔 때만 승인이 무효가 됩니다.

## 9. digest 바인딩

모든 리뷰 라운드는 판정을 설명하는 정확한 계획 바이트에 묶습니다.

- 리뷰 시점의 계획 파일에 `shasum -a 256`을 계산해 `plan_sha256`을 구하고, 그 라운드의 `round_id` 옆에 드래프트에 기록합니다.
- 판정은 `plan_sha256`과 `round_id`가 현재 라운드와 일치할 때만 받아들입니다. `plan_sha256`이나 `round_id`가 현재 라운드와 맞지 않는 판정은 `stale`로 기록해 무시합니다. 승인으로 세지 않습니다.
- 이미 닫힌 라운드에 대한 중복 결과도 `stale`입니다. 더 새 라운드가 대체한 라운드에 대한 늦은 결과도 `stale`이며 새 결과를 덮어쓰지 않습니다.
- 계획 편집은 digest를 바꾸고 승인된 라운드를 `pending`으로 되돌립니다. 새 digest에 대한 필요한 리뷰를 다시 돌리기 전에는 승인이 무효입니다. §8의 `## Handoff` 예외는 그대로 적용됩니다.
- 실행이 재개될 때 `launching`이나 `in_flight`에 멈춘 라운드는 `inconclusive`가 되고 새 라운드가 시작됩니다. 승인으로는 세지 않습니다. `launching`과 `in_flight`은 디스패치와 결과 수집 사이에 기록되는 진행 중 상태 두 개이며, 라운드 상태는 드래프트의 `## Review` 절에 `launching`, `in_flight`, `collected`, `stale` 중 하나로 그 라운드의 `round_id` 옆에 적습니다.

기존 상한은 그대로입니다: 리뷰어 두 명, 라운드 세 개.

## Sources

> 확인 2026-11-03.

| Claim | Source |
|---|---|
| 독립 갭 분석, 블로커 범주, 고정 원장, 수렴 실패 시 정지는 OmO 공유 스킬 패키지의 `ulw-plan` 리뷰 계약을 각색한 것 | <https://github.com/code-yeongyu/oh-my-openagent/tree/0d80470e4201925727e88afbafcdf24d7801a588> |
| 필요한 리뷰의 트리거, 독립 리뷰어 두 명, 3라운드 상한, 수렴 실패 시 자동 인계 금지 | 이 패키지 자체 설계. 상한은 `instructions/loop-engineering/LOOP_ENGINEERING.md`를 따름 |
| 구조 자기 점검이 확인하는 계획 문법 | `references/plan-format.ko.md` |
| 자기 채점은 리뷰가 아니고 `SKIP`은 통과가 아니다 | `instructions/harness-engineering/HARNESS_ENGINEERING.md` |
| 모든 정지 조건에는 숫자 상한이 필요하다 | `instructions/loop-engineering/LOOP_ENGINEERING.md` |

### 근거 등급

`LOCAL` - 이 파일은 패밀리 계약에서 나온 이 패키지의 리뷰 절차를 서술합니다. 3라운드 상한은 계약의 범위이고, 원본 스킬은 고정 상한 없이 수렴 규칙을 썼습니다.
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: 470kUpdated 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