kwakseongjae omd:release-hygiene
오픈소스 레포가 "최적의 결과물만 push"하도록 강제하는 루틴. 실험 과정에서 생긴 부산물이 public repo로 새는 것을 막고, 새 deliverable이 문서/패키징과 어긋나지 않게 한다.
자동 게이트는 scripts/check-release-hygiene.sh가 husky pre-commit에서 돌린다. 이 스킬은 그 게이트가 잡지 못하는 판단(문서 동기화, npm 배포 여부)을 사람/에이전트가 책임지게 한다.
0. 언제 트리거하나
- 새 스킬 / 에이전트 / CLI 플래그 / 큰 기능을 추가한 직후
- 커밋 또는 push 직전 ("정리하고 올리자")
- 실험(
experiments/,.promo/)을 돌린 세션의 마무리
1. 4-항목 체크리스트 (전부 통과해야 push)
[1] 부산물 0건 (자동 + 수동)
자동: bash scripts/check-release-hygiene.sh staged — pre-commit이 이미 실행.
수동 확인 대상 (게이트 정규식 밖일 수 있는 것):
- 반복 드래프트:
*.v1.html,*-draft,*-old,*-copy - 빌드 스크립트가 산출물 옆에 남은 경우:
build.mjs,crop-*.mjs(experiments 안이면 gitignore로 OK) - 에이전트 로그 / 리뷰 덤프:
.orchestrator.log,.reviews/ - 소스 크롭 / 컨택트 시트:
_source-*,*-contact-sheet*
판단 기준: "이 파일이 6개월 뒤 처음 보는 기여자에게 의미가 있나?" No면 부산물.
[2] scratch 디렉토리는 gitignore (절대 추적 X)
.gitignore에 다음이 있어야 한다 (이미 설정됨):
experiments/ # 갤러리 + 브랜드 목업 + 저니 (로컬 전용)
.promo/ # hyperframes 프로모 영상
.experiments/ # /omd-lab-* 런
.codex/ # codex 채널 self-install 산출물
.agents/skills/omd*/ # generic-agent 채널 self-install
web/.husky/ # root .husky의 중복본
새 채널/툴이 self-install 산출물을 만들면 같은 패턴으로 추가.
[3] 문서 동기화 (deliverable 추가 시)
새 스킬/에이전트를 추가했으면 다음을 전부 갱신:
| 위치 | 무엇을 |
|---|---|
README.md |
스킬 표 / 카운트. shipped vs local-preview 구분 명시 |
web/src/app/docs/page.tsx |
SKILLS 또는 V2_SKILLS 배열 + 섹션 eyebrow 카운트 + 상단 nav anchor |
web/src/components/landing-v2/sections.tsx |
"N skills + M sub-agents" 하드코딩 카운트 — 번들(npm) 기준으로만. local-preview는 카운트에서 제외 |
홈 화면 카운트는 npm 번들 기준이다. local-preview 스킬을 더해도 홈 카운트는 안 올린다 (그게 일관성 신호).
[4] npm 배포 판단 (shipped vs local-preview)
새 스킬/에이전트가 npm 패키지로 나갈지 결정한다. 두 갈래:
Shipped (번들) — 다음을 모두 해야 함:
skills/<name>/SKILL.md로 복사 (package source)..claude/skills/는 dogfood 미러.- 에이전트는
agents/<name>.md로 복사 (agents/는 통째로 ship). package.json의files배열에skills/<name>추가 (files가 npm tarball을 gate).- 스킬이 의존하는 스크립트/데이터도
files에 포함 (예:data/research/*.md). 외부 스크립트 의존이 실효성 없으면 ship 전에 제거 (precedent: kr-spellcheck heuristic은 recall 낮아 폐기). - README/docs에서 "preview" 딱지 제거, 홈 카운트 +1.
- 버전 bump: 기능 추가 = minor. 단, 버전 bump와
npm publish는 사용자 명시 요청 시에만.
Local-preview (dogfood만) — 기본값:
.claude/skills/+.claude/agents/에만 존재.skills/·files에는 넣지 않음.- README/docs에 "local preview, not bundled" 명시 + 수동 채택 방법(디렉토리 복사) 안내.
- 기존 local-only 선례:
omd-add-reference,omd-batch-launch,omd-migrate,omd-lab-*. - 기존 shipped 선례: v0.2 agent layer (orchestrator / kr-writer / locale-adapter / designer-review / final-qa / codex-image) — 6 skills + 6 agents.
판단 휴리스틱: 미완성 의존성(없는 스크립트 참조 등)·preview 성숙도·매 설치마다 footprint 증가가 걸리면 → local-preview. 안정적이고 자급자족이며 모든 채널에서 작동하면 → shipped 후보.
2. 실행 순서 (에이전트용)
1. bash scripts/check-release-hygiene.sh all # 부산물 전수 스캔
2. git status --porcelain | grep -iE '_old|_source|\.bak|v[0-9]\.|contact-sheet' # 이중 확인
3. .gitignore에 scratch dir 누락 없는지 확인
4. 이번 changeset에 새 스킬/에이전트가 있나? → [3] 문서 동기화
5. 새 스킬을 ship할까? → [4] 판단. 기본 local-preview
6. 사용자에게 요약 보고. 커밋/푸시는 명시 요청 시에만.
3. 출력 형식
release-hygiene
[1] byproducts: ✓ 0 in changeset
[2] scratch dirs: ✓ experiments/ .promo/ .codex/ ignored
[3] docs sync: ✓ README + /docs updated (or: N/A — no new deliverable)
[4] npm decision: local-preview (joins omd-migrate et al.) (or: shipped → files updated)
4. 금지
- ❌
experiments//.promo/를git add -f로 강제 추적 - ❌ 부산물 게이트를
--no-verify로 우회 (긴급시 외) - ❌ 사용자 요청 없이 버전 bump 또는
npm publish - ❌ local-preview 스킬을 홈 화면 번들 카운트에 합산
- ❌ shipped로 승격하면서 의존 스크립트를
files에 빠뜨림 (= 깨진 설치)
5. 관련
scripts/check-release-hygiene.sh— 자동 부산물 게이트 (pre-commit).husky/pre-commit— 게이트 + catalog-integrity 실행package.json#files— npm tarball allowlist (shipped 판단의 ground truth)