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/planning-workflow.ko.md

View on GitHub
# 계획 워크플로

첫 계획 턴부터 계획 파일이 생길 때까지 이 파일을 사용합니다. 이 파일은 분류, 근거 확보, 의도 라우팅, 질문, 드래프트, 계획 작성을 맡습니다.

## 1. 기획자 역할과 계획 모드 유지

기획자는 읽고 검색하고 읽기 전용 분석을 실행한 뒤, 정확히 두 종류의 산출물만 씁니다. `.hyper/drafts/<slug>.md`와 `.hyper/plans/<slug>.md`입니다. 제품 코드, 설정, 테스트를 수정하지 않고 구현자를 호출하지도 않습니다. 위임한 구현도 구현입니다.

계획 모드는 유지됩니다. 이 스킬이 활성화된 동안 "X 해줘", "X 고쳐줘", "X 만들어줘", "그냥 해줘"는 "X를 계획하라"는 뜻입니다. 요청 하나는 크기와 무관하게 계획 하나를 만듭니다. 규모는 todo와 wave를 늘릴 뿐 두 번째 계획을 만들지 않습니다.

## 2. 0단계: 분류

분류는 근거 확보의 깊이와 리뷰 강도를 정합니다. 사용자의 요청 범위를 정하지 않습니다.

| Class | Signal | Grounding | Review |
|---|---|---|---|
| Trivial | 파일 하나 또는 뻔한 수정 하나, 교차 선택 없음 | 표적 읽기 한 번과 확인 읽기 한 번 | 갭 분석만 |
| Standard | 파일 1~5개, 분명한 기능이나 리팩터링 | 병렬 lane, 최대 두 wave | 갭 분석, `review_required`이면 이중 리뷰 추가 |
| Architecture | 시스템 설계, 모듈 5개 이상, 장기 영향 | 더 깊은 lane과 외부 계약 | `review_required`이면 이중 리뷰, 의도가 UNCLEAR이면 권장 |

분류를 드래프트에 기록합니다. Trivial이 아닌 작업의 의도가 UNCLEAR이면 사용자가 요청하지 않았어도 `review_required: true`로 둡니다.

## 3. 1단계: 근거 확보

묻기 전에 근거를 확보합니다. 미지수는 두 종류입니다. 저장소, 시스템, 문서에서 나오는 발견 가능한 사실과 사용자만 가진 선호입니다. 질문까지 갈 수 있는 것은 두 번째 종류뿐입니다.

subagent를 쓸 수 있으면 아래 lane을 한 턴에 함께 돌리고, 도는 동안 직접 읽기와 검색을 계속합니다.

- 구현 표면: 호출 지점, 기존 패턴, 테스트 배치, 변경이 닿을 파일
- 제약 표면: 빌드, 린트, 타입 검사, 마이그레이션, 설정, 환경 변수
- 외부 계약 표면: 저장소가 답할 수 없을 때만 보는 공식 문서나 상위 API 계약

모든 lane 프롬프트는 TASK, DELIVERABLE, SCOPE, VERIFY와 읽기 전용이라는 조건을 담습니다. subagent의 답변은 기획자가 인용한 파일을 열거나 인용한 명령을 실행할 때까지 주장일 뿐입니다.

규칙:

- 모은 근거가 질문에 답하거나, 연속 두 wave가 새로 쓸 만한 사실을 더하지 않으면 그 질문의 탐색을 멈춥니다.
- 계획에 들어가는 모든 주장은 `path:line`, 명령과 그 출력, 문서 URL 중 하나를 붙입니다.
- 읽기 전용은 수정, 설치, 브랜치 변경, 상태를 바꾸는 명령이 없다는 뜻입니다.
- 무관하게 수정됐거나 추적되지 않은 파일은 `dirty_worktree` 위험으로 기록하고 그대로 둡니다. 계획은 그 파일을 덮어쓰는 안을 제안하지 않습니다.
- §6의 통과 점검에 답할 수 있으면 이 단계를 끝냅니다.

## 4. 2단계: 영향을 받는 사용자와 이상 상태

결과가 닿는 대상을 지목합니다. 최종 사용자, 다른 프로그래머, 출력을 소비하는 프로그램이나 에이전트가 해당하며 여럿인 경우가 많습니다. 각 대상이 오늘 어떻게 쓰고 앞으로 어떻게 쓸지 적습니다.

드래프트와 계획의 `### Affected user and ideal state` 절에 행을 씁니다.

| ID | Property or gap | Why it matters |
|---|---|---|
| IS-1 | 사용자에게 걸리는 것, 어색한 것, 퇴행하는 것, 나빠지는 것이 없는 상태의 속성 | 그 속성이 중요한 이유 |
| GAP-1 | 그 상태와 오늘의 차이 | 그 차이가 생긴 이유 |

이후의 모든 갈림길은 이 행에 비추어 판단합니다. 모든 todo는 최소 하나의 `GAP-` 행을 닫습니다. 모든 `IS-` 행은 `## Success criteria`의 QA 점검으로 증명합니다.

이상 상태가 문자 그대로의 요청보다 크면 한 줄로 밝히고 이상 상태를 계획합니다. 요청을 임의의 MVP, 1단계, 축소된 부분집합으로 줄이지 않습니다.

## 5. 3단계: 의도 라우팅

근거를 확보한 뒤 판정 하나를 내리고, 첫 질문 전에 한 줄로 알립니다.

| Verdict | Test | Behaviour |
|---|---|---|
| CLEAR | 원하는 결과가 정의되어 있고, 남은 항목은 선호나 소유자 결정이다 | 살아남은 갈림길만 이유와 함께 묻는다 |
| UNCLEAR | 결과 자체가 모호해서, 물으면 기획자의 일을 사용자에게 넘기게 된다 | 탐색하고 채택한 기본값을 알리며, 인터뷰하지 않는다. Trivial이 아니면 `review_required: true` |
| On the fence | CLEAR와 UNCLEAR가 모두 성립한다 | CLEAR로 보고 질문을 정확히 하나 한다 |

예외:

- "나한테 물어봐", "인터뷰해줘", "왜 안 물어봐"가 명시되면 CLEAR로 라우팅하고 인터뷰를 실행하며, 기본값 채택 필터를 끕니다. 살아남은 모든 갈림길을 묻습니다.
- "high accuracy", "ultra high accuracy", "고정밀", "deep review", "꼼꼼히", "정확도 높여"는 어느 턴에서든 `review_required: true`로 둡니다. 계획이 이미 있으면 라우팅을 다시 하지 않고 그 턴에 필요한 리뷰를 실행합니다.

한 줄로 알립니다. `Intent: CLEAR, review required` 또는 `Intent: UNCLEAR, review not required` 형태입니다. 사용자는 인터뷰를 받을지, 이중 리뷰가 오는지 알아야 합니다.

## 6. 4단계: 질문과 토폴로지 고정

모든 후보 질문에 두 필터를 순서대로 적용합니다.

1. 모은 근거가 답할 수 있는가? 그렇다면 묻지 않고 탐색합니다.
2. 영향받는 사용자의 이상 상태, 또는 밝혀진 의도와 방어 가능한 기본값이 정하는가? 그렇다면 정하고 그 결정을 기록하며 묻지 않습니다.

소유자 결정은 두 필터를 통과해 살아남고, 기본값이 있어도 항상 묻습니다.

- 되돌릴 수 없거나 파괴적인 변경
- 롤백할 수 없는 데이터나 스키마 마이그레이션
- 새로 비용이 드는 리소스나 실제 지출
- 자격 증명이나 계정 접근
- 외부 게시나 전송
- 사용자가 계속 감당하는 교차 제품 선택: 공개 설정 표면, 패키징이나 배포, 고정한 외부 의존성, 데이터 형태, 대상 사용자나 규정 한도

질문 형태, 답변 처리, 위임 범위는 `rules/stance-calibration.md`를 따릅니다.

- 턴당 1~3개
- 무엇을 탐색했고 왜 갈림길이 정리되지 않았으며 어떤 계획 결정이 답에 달렸는지 밝힘
- 선택지 2~4개, 권장안을 맨 앞에
- 건너뛴 질문은 권장안으로 정해지고, 그 결정은 uninformed로 기록
- 모든 답변은 다음 턴 전에 resolved, resolved이지만 uninformed, 진행이 있는 unresolved, 막힌 unresolved 중 하나로 분류
- 위임 표현은 그 낱말이 가리키는 가장 좁은 범위만 정하고, 계획 범위 위임 뒤에는 되돌릴 수 없는 손실이나 사용자만 할 수 있는 단계에 대한 질문만 남김
- 사용 중인 질문 형식은 출처와 함께 드래프트에 기록

테스트 전략은 TDD, 테스트 후작성, 없음 중 하나로 항상 확인합니다. 어느 쪽이든 에이전트가 실행하는 QA는 포함합니다.

토폴로지 고정: 요청과 근거에서 독립적으로 성공하거나 실패할 수 있는 최상위 컴포넌트 1~6개를 열거하고 드래프트의 components 원장에 기록합니다. 목록은 한 턴에 확정합니다. 요청이 작아 보인다고 컴포넌트 하나로 접지 않고, 요청과 근거가 뒷받침하지 않는 인접 컴포넌트를 더하지도 않습니다. 모든 todo는 컴포넌트 하나로 이어집니다.

매 턴 뒤의 통과 점검:

- 영향받는 사용자가 지목되고 `IS-`, `GAP-` 행이 기록됐는가?
- 목표가 정의됐는가?
- 범위가 무엇을 포함하고 제외하는지 분명한가?
- 접근 방식이 정해졌는가?
- 테스트 전략이 확인됐는가?
- 예산, 지정 스택, 예상 규모, 대상 사용자를 각각 탐색하거나 기본값으로 정하거나 물어서 훑었는가?
- 막는 모호함이 남았는가?

"아니요"가 하나라도 있으면 그것이 다음 질문입니다. 모두 "예"이면 5단계로 넘어갑니다.

## 7. 5단계: 드래프트와 승인 단계

드래프트는 컨텍스트 압축과 세션 사이를 견딥니다. 계획 파일보다 먼저 쓰고 결정이 날 때마다 갱신합니다.

```markdown
---
slug: <slug>
intent: clear | unclear
review_required: true | false
question_form: batch | one_by_one | examples_first
question_form_source: declared | observed
approval: auto | user | pending
status: exploring | planning | reviewing | delivered | stopped
plan_path: .hyper/plans/<slug>.md
round_id: <id of the current review round>
plan_sha256: <shasum -a 256 of the plan file at review time>
---
## Request
## Affected user and ideal state
## Components

| id | outcome | status | evidence |
|---|---|---|---|

## Open assumptions

| assumption | default | rationale | reversible? |
|---|---|---|---|

## Decisions
## Questions asked
## Review
```

- open-assumptions 원장은 묻지 않고 채택한 모든 기본값을 담습니다. 무엇을 가정했고, 어떤 기본값을 골랐고, 왜 그런지, 되돌릴 수 있는지를 적습니다.
- components 원장은 토폴로지 고정 결과를 컴포넌트별 한 행으로 담습니다.
- `question_form`과 `question_form_source`는 이번 실행이 쓰는 질문 형식과, 사용자가 직접 말했는지(`declared`) 답변에서 읽었는지(`observed`)를 담습니다. 두 값은 `rules/stance-calibration.md` §4가 정합니다.
- `review`는 라운드 수, 판정, 받아들인 블로커, 열린 노트를 담습니다.
- `round_id`와 `plan_sha256`은 현재 라운드의 digest 바인딩을 담습니다. 계획 편집 뒤마다 `plan_sha256`을 갱신합니다. 편집은 승인된 라운드를 `pending`으로 되돌립니다.
- 이후 턴에서는 드래프트를 먼저 읽고 그 필드에서 재개합니다. 기억으로 라우팅을 다시 하지 않습니다. 범위가 바뀌었으면 드래프트를 갱신하고 영향받는 단계만 다시 실행합니다.
- slug는 소문자 ASCII 케밥 표기로 `^[a-z0-9]+(-[a-z0-9]+)*$`에 맞고 48자 이하여야 합니다. `..`, `/`, 절대 경로는 거부합니다.

승인은 기록하는 단계이고 암호를 찾는 절차가 아닙니다.

- 기본 자동 인계로 계획을 전달하고 브리핑을 기다리지 않고 알릴 때 `approval: auto`
- 사용자가 인터뷰를 요청했거나, 계획을 먼저 승인받겠다고 했거나, 소유자 결정이 열려 있을 때 `approval: user`
- 계획 파일이 생기기 전에는 `approval: pending`

승인 보류는 계획 뒤에서 실행을 멈추지만 작업을 끝내지는 않습니다. "승인은 내가 할게", "내가 승인할게", "I'll approve", "wait for my approval"은 `approval: user`로 기록하고, 계획을 전달한 뒤 `Auto-execute: no (approval requested)`로 멈춥니다. 이후 메시지에서 사용자가 승인하면 같은 계획으로 실행에 이어갑니다. 계획을 다시 만들지 않고, 계획 자체가 바뀌지 않은 한 리뷰도 다시 돌지 않습니다.

브리핑은 한 번 알립니다. 영향받는 사용자, `IS-`와 `GAP-` 행, 경로가 붙은 발견, 이상 상태에 비추어 정리한 갈림길, 권장안이 붙은 열린 소유자 결정, 접근 방식을 담습니다. 승인은 계획 작성만 허가하고 구현은 허가하지 않습니다.

## 8. 6단계: 계획 작성

1. `assets/plan-template.ko.md`에서 `.hyper/plans/<slug>.md` 파일을 만듭니다. 제목은 적힌 그대로, 순서를 지켜 유지합니다.
2. `## Scope`, `## Verification strategy`, `## Execution strategy`, `## Todos`, `## Final verification wave`, `## Commit strategy`, `## Success criteria`를 채웁니다.
3. `## TL;DR`는 마지막에 채웁니다. 의도가 아니라 완성된 계획을 요약하게 하려는 것입니다.

의사결정 완결 규칙:

- 작업이 닿는 모든 파일의 정확한 경로를 적고, 훑는 작업이면 "Y 안의 모든 X"로 씁니다.
- `### Must NOT have`에 계획이 거부하는 추가 항목을 적어 실행자가 범위를 발명하지 않게 합니다.
- `Acceptance`에는 실제 명령과 기대 결과를 적습니다.
- `QA happy`와 `QA failure`에는 각각 도구, 정확한 실행 방법, 이분법으로 판정되는 관찰값, 근거 경로를 적습니다.
- `References`에는 줄 앵커가 붙은 경로나 문서 URL을 적습니다.
- 구현자에게 판단거리를 남기지 않습니다.

크기 규칙:

- wave마다 todo 5~8개를 목표로 합니다. 마지막이 아닌 wave에서 3개 미만이면 지나치게 덜 나눈 것입니다.
- 구현과 그 테스트는 todo 하나입니다.
- `Tier: low`는 기계적이거나 파일 하나짜리 작업의 기본값, `medium`은 일반적인 다중 파일 작업, `high`는 하나로 뭉친 어려운 문제입니다. 병렬로 보이게 하려고 high를 억지로 쪼개지 않습니다.
- 같은 wave의 todo는 쓰기 범위가 겹치지 않거나 순차로 실행합니다.

`## TL;DR`에는 사용자가 얻는 것, 이 접근을 고른 이유, 하지 않을 것, 정확히 하나의 노력 구간(Quick, Short, Medium, Large, XL), 위험 줄, 되돌릴 수 있는지와 함께 적은 사용자 대신 내린 결정을 담습니다. 시간이나 일수는 절대 쓰지 않습니다.

## 9. 정지 규칙

- 계획이 완성되고 리뷰를 통과했으며 거부도 승인 보류도 열린 소유자 결정도 없으면 인계 요약을 전달하고 `rules/handoff.ko.md`에 따라 이어갑니다.
- 사용자가 거부했으면 계획을 전달하고 `Auto-execute: no (plan only requested)`를 기록합니다.
- 사용자가 먼저 승인받겠다고 했으면 계획을 전달하고 `Auto-execute: no (approval requested)`로 멈춥니다. 이후 승인이 오면 같은 계획으로 인계를 다시 시작합니다.
- 소유자 결정이 열려 있으면 가능한 계획을 전달하고 권장안이 붙은 질문 하나를 한 뒤 기다립니다.
- 필요한 고정밀 리뷰를 실행할 수 없으면 `Auto-execute: no (high-accuracy review needs independent reviewers)`로 멈춥니다.
- 리뷰가 수렴하지 않았으면 블로커를 보고하고 자동 인계하지 않습니다.
- 구조 자기 점검이 실패했고 새 근거 없이 고칠 수 없으면 실패를 보고하고 자동 인계하지 않습니다.
- 브리핑을 알린 뒤에는 사용자가 범위를 바꾸지 않는 한 다시 탐색하지 않습니다.

## Sources

> 확인 2026-11-03.

| Claim | Source |
|---|---|
| 분류, 묻기 전 탐색, 두 필터, 이상 상태와 갭 행, 토폴로지 고정, 드래프트, 승인 단계, 계획 채우기 순서는 OmO 공유 스킬 패키지의 `ulw-plan` 스킬을 각색한 것 | <https://github.com/code-yeongyu/oh-my-openagent/tree/0d80470e4201925727e88afbafcdf24d7801a588> |
| 계획 파일 경로, slug 규칙, 드래프트 필드, 승인 값, 자동 인계 게이트, 계획 문법 | 이 패키지 자체 설계, 사용자 지시, 2026-11-03. 문법의 정본은 `references/plan-format.ko.md` |
| 분류는 근거 확보와 리뷰의 깊이를 정하고 요청은 그대로 둔다 | 사용자 지시, 2026-11-03 |
| 범위가 정해진 탐색과 질문 루프 | `instructions/loop-engineering/LOOP_ENGINEERING.md` |
| 읽기 전용 위임 프롬프트는 task, deliverable, scope, verify를 담고 부모가 자식 주장을 검증한다 | `instructions/context-engineering/references/parallel-workflows.md` |
| 승인은 지속 상태에 기록되는 구조적 노드다 | `instructions/graph-engineering/GRAPH_ENGINEERING.md` |

### 근거 등급

`LOCAL` - 이 파일은 이 패키지 자체의 절차를 서술하며, 원본 기획자를 패밀리 계약에 맞게 각색한 것입니다. 숫자 범위는 검증된 최적값이 아니라 이 패키지가 고른 값입니다.
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: 469kUpdated 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