사용하기

설치 후 Codex 또는 Claude Code에서 작업 앞에 loopy만 붙이세요.

loopy 결제 모듈 적용해줘

Superloopy가 계획을 세우고, 실행하고, 실제 파일로 각 조각을 검증한 뒤 결과를 보고합니다. 사용자가 중간에 명령을 직접 칠 필요는 없습니다. 패키징된 Stop hook은 기본으로 조용하고, SUPERLOOPY_STOP_HOOK=on일 때만 막아섭니다.

왜 Superloopy?

Superloopy는 "완료"가 자신 있는 상태 문장 이상을 뜻해야 하는 Codex·Claude Code 작업을 위한 것입니다.

• 근거 우선: 모든 pass가 .superloopy/evidence/ 아래의 실제 artifact를 가리킵니다.
• 기본이 가벼움: 작은 CLI 하나, repo 로컬 상태, 런타임 의존성 0.
• 에이전트 친화적: 스킬, hook, 선택적 크루 레인이 최종 게이트를 숨기지 않으면서 에이전트를 안내합니다.

보증 범위. 명령 기반(command-backed) 기준이 강한 보증입니다. 완료 시점에 Superloopy가 각 명령을 프로세스 내에서 다시 실행해 재현을 요구하므로, 오래되었거나 위조된 pass는 "완료"에 도달할 수 없습니다. 수동(명령 없는) 기준은 비어있지 않은 증거 artifact 존재 + 감사자·사람 판단으로 검증됩니다 — 정확성은 결정론적 재실행이 아니라 검토에 의존합니다.

스킬

Superloopy는 명령을 작게 둡니다. 대신 스킬이 작업 방식을 잡습니다. 언제 켜져야 하는지, 무엇을 확인해야 하는지, 어떤 근거를 .superloopy/evidence/ 아래에 남겨야 하는지가 스킬에 들어 있습니다.

스킬	언제 쓰나	남기는 것
superloopy-loop	full loop는 loopy <task> 또는 loopy team <task>로 시작합니다. loopywork, lpy, $lpy는 가벼운 guidance만 넣을 때 씁니다.	full loop는 직접적·간결·완전한 진행/최종 응답과 가벼운 계획, 근거, 품질 게이트, 최종 evidence report를 남깁니다. 정확한 영문/한국어 제어는 현재 미완료 loop에만 적용되며 새 loop는 enabled로 초기화됩니다. guidance alias는 상태를 바꾸지 않습니다.
superloopy-doctor	install, wrapper, plugin cache, hook/bootstrap, agent, Codex/Claude Code host wiring, stale version 문제를 진단할 때.	읽기 전용 health report: wrapper/cache/version 근거, 실패한 체크, 승인 후 실행할 정확한 복구 명령.
superloopy-research	Codex의 $superloopy:superloopy-research나 Claude Code의 /superloopy:superloopy-research를 직접 호출하거나, 리서치 작업을 선행 loopy/루피(예: loopy research)로 시작할 때만. 단순한 조사·검색·요약 요청으로는 켜지지 않습니다.	리서치 축, 확장 wave, 모든 retrieval의 판정 결과, 등급과 시점이 붙은 출처, 비용이 기록된 claim ledger, 검증 메모, 출처가 붙은 synthesis artifact.
superloopy-backend	백엔드·데이터·마이그레이션·런타임 데이터베이스 에이전트 작업에 Codex의 $superloopy:superloopy-backend나 Claude Code의 /superloopy:superloopy-backend를 직접 호출하거나, 해당 작업을 선행 loopy/루피로 시작할 때만. 단순한 백엔드·데이터베이스 용어로는 활성화되지 않습니다.	스택 중립적인 컨텍스트 카드, 명시된 계약, 최소 권한 데이터 안전장치, TDD, 마이그레이션·런타임 에이전트 경계, 명령으로 검증한 운영 근거.
superloopy-clone	loopy clone, 허가된 웹사이트 클론, 리빌드, 마이그레이션, 픽셀 기준 복구를 요청할 때.	브라우저 캡처, 페이지 구조, 디자인 토큰, asset 목록, 구현 메모, build 출력, visual QA 근거.
superloopy-frontend	지원되는 화면 기반 애플리케이션 UI(공개·인증·비공개/내부용·설치형 PWA/확장을 포함한 브라우저 호스팅 웹, 사용자 여정이 있는 인터랙티브 배포형 콘텐츠 중심 웹(캠페인·출판·랜딩 경험 등), 데스크톱, 모바일/태블릿, 임베디드/하이브리드 클라이언트, 커스텀 렌더링 UI, Qt, 혼합 타깃) 작업에 Codex의 $superloopy:superloopy-frontend나 Claude Code의 /superloopy:superloopy-frontend를 직접 호출하거나, 해당 작업을 선행 loopy/루피로 시작할 때만. 단순한 UI·플랫폼·프레임워크 용어로는 켜지지 않으며 TV·웨어러블·XR·자동차·게임 UI·TUI·정적 미디어/문서 결과물·비 UI 작업은 제외됩니다.	하나의 공통 UX 계약에 플랫폼/컴포지션 경로를 더합니다. 근거는 변경한 주장에 비례하며 브라우저, 네이티브 타깃/셸, 렌더러, 혼합 타깃의 각 소유자를 독립적으로 검증합니다. 독립 실행에서는 실행별 영수증을 보존하고 활성 루프에서는 goal과 criterion에 연결합니다.
humanize-korean	한국어 글의 AI 티를 줄이거나 번역투를 고치고, 사실은 바꾸지 않은 채 사람이 쓴 것처럼 다듬어야 할 때.	잘못 놓인 수식어의 의미 검토를 포함한 한국어 자연스러움을 맡습니다. final.md, summary.md, audit.json을 쓰고, Superloopy loop 안에서는 .superloopy/evidence/humanize-korean/ 아래에 근거를 남깁니다.
i-have-adhd	Codex $superloopy:i-have-adhd나 Claude Code /superloopy:i-have-adhd를 직접 호출하거나, 선행 loopy/루피 brief에서 ADHD 친화적·행동 우선·한 단계씩·훑어보기 쉬운 출력을 직접 요청할 때. 문체만 보고 자동 활성화하지 않습니다.	다음 행동이 눈에 띄도록 진행 업데이트의 형태를 바꿉니다. Superloopy evidence artifact를 만들지 않으며 계획·안전·검증·완료 gate를 약화하지 않습니다.
say-it-straight	Codex $superloopy:say-it-straight 또는 Claude /superloopy:say-it-straight를 명시적으로 호출해 제공한 문장이나 task artifact를 다듬을 때만 사용하며 문체만으로 자동 실행하지 않음. full Loopy 진행/최종 응답은 기본으로 직접적이며 정확한 영문/한국어 제어는 현재 미완료 loop에만 적용됩니다.	명시적 artifact 윤문은 사실·말투·보호 텍스트·필수 내용을 보존하고 감사를 실행합니다. ADHD는 구조를, humanize-korean은 한국어 윤문 권한을 유지합니다.
superloopy-slides	슬라이드·프레젠테이션·덱을 요청하거나 PPT/PPTX를 웹으로 변환할 때.	고정 16:9 스테이지의 의존성 없는 단일 HTML 덱, 직접 고르는 스타일 미리보기 3종, .superloopy/evidence/slides/ 아래 렌더링 스크린샷 visual-QA artifact.

자동 안심 문구 게이트. 모든 full Loopy 시작·재개 컨텍스트에는 이 조건부 게이트가 들어갑니다. 영향받는 artifact가 사용자가 보는 한국어 제품 동작 문구를 새로 만들거나 바꿀 때만 켜지고, RC-1부터 RC-4와 humanize-korean의 자연스러움 검토를 plan criterion에 추가합니다. 내부 로그와 진단, 개발자 문서와 주석, 테스트 설명, 인용문, 일반·마케팅 글, 한국어가 아닌 문구는 제외합니다. 제공된 동작만 사용하며 사실이 없으면 결과를 꾸며내지 않고 blocker나 질문으로 남깁니다. 별도 skill이나 호출 이름은 없습니다.

superloopy-backend가 측정된 효과

네 개 백엔드 코드베이스(Java·Go)의 병합된 풀 리퀘스트를 봉인된 체크아웃에 재현하고, 해당 PR의 테스트를 숨겨 오라클로 쓰며, 모든 제출물을 블라인드로 세 번 리뷰해 측정했습니다. 규칙을 뽑아내지 않은 46개 과제에서 스킬을 켜면 테스트 없는 부분이 포함된 변경이 약 1/4 줄었습니다(스킬 없이 실행할 때 대비 비율 0.73, 90% 구간 0.56~0.90). 출력 토큰은 1.7~1.8배입니다. 숨긴 테스트의 통과 여부는 바뀌지 않았고, 수정 경로를 더 찾아주지도 않았습니다. 데이터 안전·마이그레이션·런타임 에이전트 지침은 측정되지 않았으므로 측정된 효과가 아닌 지침으로 읽어야 합니다.

기본 안전장치는 loop 스킬입니다. 문장 맨 앞의 완전한 loopy 토큰은 evidence loop를 시작하거나 이어가고, loopy team은 크루 모드로 올립니다. 선행 loopywork, lpy, $lpy는 시작 안내만 넣고, 구조화된 SUPERLOOPY_STEER는 진행 중인 loop를 조정합니다. full-loop 직접 출력은 제공한 문장이나 task artifact를 몰래 고치지 않으며, 직접 윤문은 명시적 호출만 가능합니다. prompt hook은 일반 문장에서 frontend나 한국어 글쓰기 모드를 추측하지 않습니다. 전문 스킬은 직접 호출하거나, 이미 시작된 loop가 실제 전문 작업을 명시적으로 배정할 때만 사용합니다.

클론 데모

superloopy-clone은 Transferloom.com을 로컬에서 재현했고 desktop/mobile 브라우저 검증을 통과했습니다. 이 레퍼런스 실행은 sticky nav, animated hero, app preview 섹션, comparison table, security panel, sister app banner, footer, local assets, Superloopy evidence trail을 보존했습니다.

슬라이드 데모

superloopy-slides가 만든 라이브 다국어 덱 → — 고정 16:9 스테이지의 무설치 단일 HTML 프레젠테이션으로 English · 한국어 · 中文 · 日本語 · Español를 지원합니다. 실제 브라우저 비주얼 QA(단독·폰 레터박스·iframe 임베드)를 통과해 .superloopy/evidence/slides/에 증거를 남겼습니다.

글쓰기 비교 데모

라이브 글쓰기 비교 뷰어 → 는 원문 문서를 humanize-korean(A)·i-have-adhd(B)·say-it-straight(C) 결과와 나란히 보여줍니다. 한국어·영어 샘플 13개를 담았고, Say It Straight 수정마다 근거 노트가 달리며, 어떤 비교든 URL로 공유할 수 있습니다.

Qt 칸반 데모

Northstar Qt 칸반 데모는 superloopy-frontend Qt 경로로 만든 실행 가능한 Qt Quick 프로토타입 인수 검증 픽스처이며, 프로덕션 편집기임을 증명하지 않습니다. Board·검색·필터·카드·드로어·작업 생성은 검증하지만 Timeline과 Inbox는 눈에 보이는 패시브 데모 전용 문맥이고 Settings와 Help는 없습니다. 영속성과 Undo는 범위 밖입니다. Qt 6.11.1, CMake, Ninja가 준비된 상태에서 저장소 루트에서 설정, 빌드, 실행하세요.

qt-cmake -S examples/qt-kanban -B build/qt-kanban -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build/qt-kanban --parallel
build/qt-kanban/src/app/qtkanban --window-size 1600x1000

크루

큰 작업이라면 Superloopy가 제공하는 선택적 서브에이전트 여섯을 쓸 수 있습니다. 각자 하나의 레인을 맡습니다. Claude Code는 플러그인에 번들된 agents/*.md를 사용합니다. Codex에서는 bootstrap, superloopy install, superloopy agents install이 개인용 agent TOML을 $CODEX_HOME/agents에 만들면서 모델 라우팅도 확정합니다.

Codex는 유효한 모델 선택 기록이 없을 때, 정책 버전이나 설치 대상이 바뀌었을 때, 캐시가 24시간 이상 지났을 때, 또는 --refresh-models를 지정했을 때만 model/list를 조회합니다. 유효 기간 안의 기록과 managed agent 파일이 서로 맞으면 같은 manifest를 그대로 씁니다. 조회나 상태 기록은 반복하지 않습니다. 각 profile은 model/effort/tier를 한 묶음으로 보고 세 값이 모두 지원되는 첫 tuple을 고릅니다. standard는 gpt-5.6-terra / high / priority, deep은 gpt-5.6-sol / xhigh / priority, fast는 gpt-5.6-luna / low / fast가 우선입니다. 선호 모델을 쓸 수 없으면 해당 profile의 gpt-5.5 compatibility tuple을 명시적으로 선택합니다. 첫 조회에서 지원 여부를 확인하지 못하면 policy compatibility를 보수적으로 선택합니다. 기존 기록을 갱신하는 조회가 실패하면 유효한 선택을 그대로 유지합니다. --compat을 쓰면 조회 없이 정해진 compatibility tuple을 선택합니다.

agent 정의가 실제로 바뀐 경우에만 Codex를 재시작해야 합니다. 유효 기간 안의 manifest와 파일이 그대로라면 재시작할 필요가 없습니다. 모델 선택은 launch 전에 끝납니다. launch 후 다시 시도하거나 모델을 바꾸지 않습니다. superloopy doctor --refresh-models는 모델 선택 기록과 agent 파일을 바꾸지 않는 읽기 전용 비교입니다. 자세한 정책은 docs/superloopy-model-policy.md(Codex)와 docs/superloopy-model-policy-claude.md(Claude Code)에 있습니다.

franky 구현	zoro 리뷰	usopp 테스트
jinbe 게이트 검토	robin 감사	nami 탐색

크루를 부를 때는 loopy team <task>를 씁니다. loopy crew, 한 단어 형태인 loopycrew, ultrawork <task>도 같은 흐름입니다. Superloopy는 일을 레인별로 병렬로 펼치지만, 각 조각을 근거로 증명한 뒤에야 끝난 것으로 봅니다. 그냥 loopy <task>로 시작하면 솔로로 진행하고, 조각이 확실히 독립적일 때만 나눕니다.

full 크루 실행에서는 부모 에이전트가 각 레인을 superloopy loop handoff로 기록하고 superloopy loop fleet --json으로 확인하며, 사람이 읽는 최종 게이트 보고서와 기계가 읽는 게이트 JSON을 섞지 않습니다. 게이트 보고서는 Markdown 근거일 수 있지만, superloopy loop finish --artifact는 .json 품질 게이트 출력용입니다.

추적 중인 크루 handoff가 끝나면 Superloopy가 일반 handoff 또는 fleet 상태 앞에 원본 크루 라인을 한 줄 붙일 수 있습니다. 지원 카탈로그에 맞으면 할당문이나 스코프 brief의 언어를 따르고, 아니면 안전하게 영어로 돌아갑니다. 이 문장은 분위기용일 뿐이고, 판정·근거 artifact·outstanding 목록·attention 목록이 실제 기준입니다.

Superpowers와 함께 쓰기

Superloopy는 Superpowers 플러그인과 잘 맞습니다. 한 작업의 서로 다른 반쪽을 맡기 때문에 둘 중 하나를 고를 필요가 없습니다.

• Superpowers는 루프의 앞단을 담당합니다: 브레인스토밍, 계획, 그리고 TDD·코드리뷰 방법론.
• Superloopy는 마무리를 담당합니다: 완료 시점에 다시 실행되는 command 기반 기준. 그래서 "완료"가 말이 아니라 증거로 남습니다.

Superpowers가 설치돼 있으면(Codex든 Claude Code든) Superloopy가 이를 감지해서 자기 안내를 거기에 맞춰 조정합니다. 설계·계획·TDD는 Superpowers에 맡기고, 자신은 바깥쪽 증거 게이트로 남습니다. 감지는 best-effort이고 안내에만 영향을 줄 뿐 게이트를 약하게 만들지 않습니다. 끄려면 SUPERLOOPY_SUPERPOWERS=off, 강제로 켜려면 on으로 두고, superloopy doctor로 무엇을 찾았는지 확인할 수 있습니다. 자세한 내용은 docs/superloopy-interop-superpowers.md에 있습니다.

Q&A

• 둘 다 설치해야 하나요? 아니요. Superloopy는 단독으로도 동작합니다. Superpowers가 함께 있으면 겹치지 않고 서로 손발을 맞춥니다.
• 각자 어느 단계를 맡나요? Superpowers가 브레인스토밍·계획·구현을 맡고, Superloopy가 마지막 증명을 맡습니다. 한 작업에는 운전자 하나만 두세요. 같은 슬라이스에 loopy team과 Superpowers 서브에이전트 흐름을 동시에 돌리지 마세요.
• 완료 판단은 누가 하나요? Superloopy입니다. 마지막에 실제 command를 다시 실행해서 가짜 통과를 막습니다.
• Superpowers 설치는 어떻게 감지하나요? Codex와 Claude Code의 플러그인 폴더를 살펴봅니다. SUPERLOOPY_SUPERPOWERS=on|off로 언제든 바꿀 수 있습니다.

설치

Superloopy는 하나의 repo에서 Codex와 Claude Code 양쪽에 설치됩니다. 코어(loop 상태, evidence 게이트, doctor)는 호스트에 독립적이고, 각 호스트는 얇은 플러그인 manifest, hook 배선, agent 포맷을 따로 받습니다.

Codex

Node.js 22 이상과 codex plugin add를 지원하는 Codex CLI 0.131.0 이상이 필요합니다. Superloopy는 의존성이 없습니다. 런타임 의존성 0, Node만 있으면 됩니다.

codex plugin marketplace add https://github.com/beefiker/superloopy
codex plugin add superloopy@beefiker

플러그인을 설치한 뒤 Codex를 재시작하세요. Codex가 hooks 검토를 요청하면 승인하세요. 승인된 다음 세션에서 SessionStart hook이 bootstrap을 한 번 실행합니다. 이때 superloopy 명령과 agents가 설치됩니다. superloopy를 찾지 못하면 설치 경로가 PATH에 없는 겁니다. bootstrap 출력에 추가할 줄이 나옵니다. 마지막으로 superloopy doctor를 돌려 확인하세요.

checkout에서 설치한다면 node src/cli.js install --json을 실행하세요.

Claude Code

Node.js 22 이상이 필요합니다. 같은 repo에서:

/plugin marketplace add beefiker/superloopy
/plugin install superloopy@beefiker

플러그인을 다시 로드하거나 Claude Code를 재시작하고, 요청이 뜨면 hooks를 승인하세요. Claude Code에서는 스킬, 서브에이전트(agents/*.md), hooks(hooks/hooks.json)가 모두 플러그인에 번들되어 있습니다. ~/.codex 설치 단계도 없고 superloopy wrapper도 없습니다. hooks는 ${CLAUDE_PLUGIN_ROOT}를 통해 CLI를 직접 호출하며, SessionStart는 아무 일도 하지 않는 깨끗한 no-op입니다(bootstrap할 것이 없습니다). 로컬 개발에서는 claude --plugin-dir <checkout>로 Claude Code를 checkout에 연결하세요. 확인은 node "${CLAUDE_PLUGIN_ROOT}/src/cli.js" doctor --json으로 합니다. Claude용 서브에이전트의 권고 모델 기본값은 docs/superloopy-model-policy-claude.md에 정리되어 있습니다.

업데이트

Codex

Codex marketplace로 설치했다면 marketplace snapshot을 갱신합니다.

codex plugin marketplace upgrade beefiker

Superloopy는 SessionStart 때 업데이트를 확인합니다. marketplace 설치는 Codex가 관리하므로 Superloopy가 npx self-update를 시작하지 않습니다. 새 버전이 확인되면 marketplace upgrade를 실행하고 Modified hooks를 다시 승인하라고 안내합니다.

업데이트 뒤 Codex를 재시작하세요. hooks가 Modified로 보이면 정상입니다. 다시 승인하면 그 다음 승인된 세션에서 새 버전 기준으로 SessionStart bootstrap이 다시 실행됩니다. 끝나면 superloopy doctor를 돌려 확인하세요.

그래도 플러그인이 예전 상태처럼 보이거나 degraded가 남으면, 갱신된 marketplace에서 repair reinstall을 한 번 실행하세요.

codex plugin add superloopy@beefiker

checkout에서 설치했다면 checkout을 갱신하고 installer를 다시 실행합니다.

git pull --ff-only
node src/cli.js install --json
superloopy doctor

checkout 설치는 npx 관리 대상이 아닙니다. npx self-update는 안정적인 설치 위치에 superloopy-install.json snapshot을 남기는 별도 installer가 생긴 뒤에만 켭니다.

Claude Code

marketplace를 갱신하고, 설치된 플러그인을 업데이트한 뒤 리로드하세요. 재시작은 필요 없습니다.

/plugin marketplace update beefiker
/plugin update superloopy@beefiker
/reload-plugins

/plugin update가 갱신된 marketplace에서 새 버전을 받고, /reload-plugins가 현재 세션에 적용합니다(Claude Code 재시작이 필요 없고, hooks도 다시 승인할 필요가 없습니다). 확인은 node "${CLAUDE_PLUGIN_ROOT}/src/cli.js" doctor --json으로 합니다. --plugin-dir로 checkout을 로드했다면 git pull --ff-only 후 /reload-plugins만 하면 됩니다.

트러블슈팅

플러그인 설치나 업데이트 명령이 실패하면 Codex CLI를 먼저 최신 버전으로 업데이트하세요. codex plugin add는 Codex CLI 0.131.0부터 사용할 수 있으므로, 구버전 Codex CLI에서는 현재 plugin marketplace 명령이나 hook 승인 흐름이 어려울 수 있습니다.

CLI를 업데이트한 뒤 Codex를 재시작하고 marketplace 설치 또는 업데이트 명령을 다시 실행하세요. Modified hooks가 보이면 승인한 다음 superloopy doctor로 확인하세요.

Claude Code에서는 /plugin 명령이 실패하거나 플러그인이 예전 상태처럼 보이면 /reload-plugins를 실행하거나(또는 Claude Code를 재시작하고) node "${CLAUDE_PLUGIN_ROOT}/src/cli.js" doctor --json으로 확인하세요.

제거

Codex

Codex에서 설치된 플러그인을 제거합니다.

codex plugin remove superloopy@beefiker

marketplace source도 더 이상 필요 없다면 같이 제거합니다.

codex plugin marketplace remove beefiker

제거 뒤 Codex를 재시작하세요. 선택적 local bootstrap cleanup: plugin 제거는 Codex의 plugin config와 cache를 지우지만, superloopy wrapper와 개인 agents 사본은 남을 수 있습니다. agent 파일을 수정한 적이 있다면 지우기 전에 꼭 확인하세요.

rm -f ~/.local/bin/superloopy
rm -f ~/.codex/agents/franky.toml ~/.codex/agents/zoro.toml ~/.codex/agents/usopp.toml ~/.codex/agents/jinbe.toml ~/.codex/agents/robin.toml ~/.codex/agents/nami.toml

Remove-Item "$env:APPDATA\npm\superloopy.cmd" -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.codex\agents\franky.toml", "$env:USERPROFILE\.codex\agents\zoro.toml", "$env:USERPROFILE\.codex\agents\usopp.toml", "$env:USERPROFILE\.codex\agents\jinbe.toml", "$env:USERPROFILE\.codex\agents\robin.toml", "$env:USERPROFILE\.codex\agents\nami.toml" -ErrorAction SilentlyContinue

CODEX_HOME, SUPERLOOPY_BIN_DIR, CODEX_LOCAL_BIN_DIR로 설치 위치를 바꿨다면 그 경로를 정리하세요.

Claude Code

/plugin uninstall superloopy@beefiker
/plugin marketplace remove beefiker

그런 다음 /reload-plugins를 실행하세요. 그 외에 정리할 것은 없습니다. Claude Code 설치는 완전히 플러그인에 번들되어 있습니다(superloopy wrapper도 없고 ~/.codex에 쓰는 것도 없습니다). 마지막으로 남은 스코프에서 marketplace를 제거하면 플러그인도 함께 제거됩니다.

_{MIT 라이선스.}