dd-setup

name	dd-setup
description	Interactive setup wizard for dding-dong notifications. This skill should be used when the user says "setup notifications", "initial setup", "configure dding-dong", "install plugin", "알림 설정", "초기 설정", "플러그인 설정", "설정 마법사", or wants to configure the notification plugin for the first time. 환경 감지 및 초기 설정.
allowed-tools	["Bash","Read","Write","AskUserQuestion"]
disable-model-invocation	true

dding-dong 설정 마법사

사용자의 환경을 확인하고 dding-dong 알림 플러그인을 설정합니다.

플래그 파싱

$ARGUMENTS에서 플래그를 확인합니다:

• --help: 아래 사용법을 출력하고 종료합니다.

  dding-dong 설정 마법사
  
  사용법: /dding-dong:dd-setup [옵션]
  
  옵션:
    --scope global|project|local  설치 범위 지정 (2단계 건너뜀)
    --force                       기존 설정 무시, 전체 재설정
    --help                        이 도움말 표시
  

• --scope <값>: global, project, local 중 하나. 지정 시 2단계(스코프 선택)를 건너뛰고 해당 스코프로 진행합니다.

• --force: Pre-Setup Check를 건너뛰고 바로 "전체 재설정" 모드로 진행합니다.

실행 순서

1단계: Pre-Setup Check + 환경 감지

아래 명령어를 실행하여 환경을 감지합니다:

node "${CLAUDE_PLUGIN_ROOT}/scripts/setup-wizard.mjs" detect --cwd "$(pwd)"

결과 JSON을 파싱하여 사용자에게 한국어로 안내합니다:

• "플랫폼: [macOS/Linux/WSL] 감지됨"
• "사운드 플레이어: [이름] 사용 가능" 또는 "사운드 플레이어를 찾을 수 없습니다"
• "알림 도구: [이름] 사용 가능" 또는 "알림 도구를 찾을 수 없습니다"

Graceful Degradation:

• 사운드 플레이어가 없으면: "사운드 재생기를 찾을 수 없습니다." 안내 (정보 메시지만, 플래그 설정은 3단계에서 처리)
• 알림 도구가 없으면: "OS 알림 도구를 찾을 수 없습니다." 안내 (정보 메시지만, 플래그 설정은 3단계에서 처리)
• 둘 다 없으면: "터미널 벨을 사용합니다." 안내 후 sound.enabled: false, notification.enabled: false로 설정하고 3단계를 건너뜁니다
• 감지 자체가 실패하면 기본값으로 조용히 계속 진행

WSL에서 wsl-notify-send가 없으면:

• "wsl-notify-send 설치를 권장합니다: https://github.com/stuartleeks/wsl-notify-send"

Pre-Setup Check (기존 설정 감지):

--force 플래그가 있으면 이 단계를 건너뛰고 "전체 재설정" 모드로 2단계에 진행합니다.

existingConfig 필드를 확인하여:

• 기존 설정이 있으면 (global.exists, project.exists, projectLocal.exists 중 하나라도 true):

  기존 dding-dong 설정이 발견되었습니다.
  - 전역 설정: ~/.config/dding-dong/config.json [존재/없음]
  - 프로젝트 설정: .dding-dong/config.json [존재/없음]
  - 내 설정: .dding-dong/config.local.json [존재/없음]
  

  구버전 업그레이드 감지:

  기존 설정이 발견된 경우, detect 결과의 setupVersion과 pluginVersion 필드를 비교합니다:

  • setupVersion이 null → "이전 버전에서 업그레이드된 설정이 감지되었습니다. 설정을 업데이트하면 최신 기능을 활용할 수 있습니다."
  • setupVersion과 pluginVersion이 다름 → "dding-dong이 v{setupVersion}에서 v{pluginVersion}으로 업데이트되었습니다. 설정을 업데이트하여 새 기능을 반영할 수 있습니다."
  • 버전이 같음 → 별도 안내 없음

  이 안내는 정보 제공만 하며, 이후 AskUserQuestion 흐름을 변경하지 않습니다.

  AskUserQuestion으로 질문:

  • "기존 설정을 어떻게 하시겠습니까?"
    1. "설정 업데이트 (Recommended)" -- 기존 값 유지, 변경할 항목만 수정
    2. "전체 재설정" -- 기본값부터 다시 설정
    3. "취소" -- 설정 마법사 종료

  "취소"를 선택하면 마법사를 종료합니다. "설정 업데이트"를 선택하면 기존 설정을 로드한 후 2단계로 진행합니다. "전체 재설정"을 선택하면 기본값으로 2단계로 진행합니다.

• 기존 설정이 없으면: 바로 2단계로 진행합니다.

2단계: 설치 스코프 선택

--scope 플래그가 지정되어 있으면 이 단계를 건너뛰고 해당 스코프로 3단계에 진행합니다.

AskUserQuestion으로 질문합니다:

"설치 범위를 선택해주세요."

선택지:

1. 전역 설정 (Recommended) -- "모든 프로젝트에 적용됩니다. 설정 경로: ~/.config/dding-dong/config.json"
2. 프로젝트 설정 -- "팀원과 공유되는 프로젝트 설정입니다. Git에 커밋됩니다. 경로: .dding-dong/config.json"
3. 내 설정 (Local) -- "이 프로젝트에서 나만 사용하는 개인 설정입니다. Git에 포함되지 않습니다. 경로: .dding-dong/config.local.json"

• 선택 결과를 기억하여 이후 단계에서 사용합니다

3단계: 알림 모드 선택

1단계에서 감지한 사운드 플레이어와 알림 도구의 가용 여부에 따라 분기합니다.

케이스 A: 사운드 플레이어 + 알림 도구 모두 감지됨

AskUserQuestion으로 질문합니다:

"어떤 알림 방식을 사용하시겠습니까?"

선택지:

1. 사운드 + OS 알림 (Recommended) -- "소리와 데스크톱 알림을 모두 사용합니다."
2. 사운드만 -- "소리만 재생합니다. OS 알림은 표시하지 않습니다."
3. OS 알림만 -- "데스크톱 알림만 표시합니다. 소리는 재생하지 않습니다."

선택지와 config 필드 매핑:

• 사운드 + OS 알림 → sound.enabled: true, notification.enabled: true
• 사운드만 → sound.enabled: true, notification.enabled: false
• OS 알림만 → sound.enabled: false, notification.enabled: true

"설정 업데이트" 모드인 경우: 기존 설정의 sound.enabled와 notification.enabled 조합을 읽어 현재 모드에 해당하는 선택지를 기본값(Recommended)으로 표시합니다. 예를 들어, 기존 설정이 sound.enabled: true, notification.enabled: false이면 "사운드만" 옵션에 "(현재 설정)"을 표시합니다.

케이스 B: 사운드 플레이어만 감지됨 (알림 도구 없음)

AskUserQuestion으로 질문합니다:

"OS 알림 도구를 찾을 수 없어 사운드만 사용할 수 있습니다. 이대로 진행하시겠습니까?"

선택지:

1. 예, 사운드만 사용 (Recommended) -- "사운드 알림만 활성화합니다."
2. 아니오, 알림을 사용하지 않겠습니다 -- "사운드와 OS 알림 모두 비활성화합니다. 터미널 벨만 사용합니다."

• "예" → sound.enabled: true, notification.enabled: false
• "아니오" → sound.enabled: false, notification.enabled: false

케이스 C: 알림 도구만 감지됨 (사운드 플레이어 없음)

AskUserQuestion으로 질문합니다:

"사운드 재생기를 찾을 수 없어 OS 알림만 사용할 수 있습니다. 이대로 진행하시겠습니까?"

선택지:

1. 예, OS 알림만 사용 (Recommended) -- "OS 알림만 활성화합니다."
2. 아니오, 알림을 사용하지 않겠습니다 -- "사운드와 OS 알림 모두 비활성화합니다. 터미널 벨만 사용합니다."

• "예" → sound.enabled: false, notification.enabled: true
• "아니오" → sound.enabled: false, notification.enabled: false

케이스 D: 둘 다 감지되지 않음

이 단계를 건너뜁니다. 1단계에서 이미 sound.enabled: false, notification.enabled: false로 설정되어 있습니다.

4단계: 사운드팩 선택

3단계에서 사운드가 활성화된 경우에만 이 단계를 실행합니다. 사운드가 비활성화된 경우 기본 팩(default)을 유지하고 5단계로 건너뜁니다.

AskUserQuestion으로 질문합니다:

"사운드 테마를 선택해주세요."

선택지:

1. 기본 효과음 (Recommended) -- "깔끔한 사인파 비프음. 심플하고 방해가 적습니다."
2. 레트로 게임 (8-bit) -- "칩튠 스타일의 게임기 효과음. NES/게임보이 감성."
3. 뮤지컬 코드 (Musical) -- "피아노 코드 기반의 화성적 알림음. 풍성하고 따뜻한 느낌."

선택지와 sound.pack 값 매핑:

• 기본 효과음 → "default"
• 레트로 게임 → "retro"
• 뮤지컬 코드 → "musical"

선택 후 미리듣기를 제안합니다:

AskUserQuestion으로 질문: "선택한 팩의 사운드를 미리 들어보시겠습니까?"

• 예 (Recommended)
• 아니오

미리듣기 선택 시, 선택한 팩의 task.complete 사운드를 재생합니다:

DDING_DONG_PACK="${SELECTED_PACK}" node "${CLAUDE_PLUGIN_ROOT}/scripts/notify.mjs" test task.complete

미리듣기 후 변경을 원하면 다시 팩 선택으로 돌아갑니다. 만족하면 5단계로 진행합니다.

5단계: 사용자 선호도 확인

AskUserQuestion으로 순차적으로 질문합니다:

5-a. 이벤트 선택 (multiSelect): "어떤 이벤트에 알림을 받으시겠습니까?"

• 작업 완료 (task.complete) - 기본 ON
• 오류 발생 (task.error) - 기본 ON
• 입력 필요 (input.required) - 기본 ON
• 세션 시작 (session.start) - 기본 OFF
• 세션 종료 (session.end) - 기본 OFF

5-b. 볼륨 (3단계에서 사운드가 활성화된 경우에만 질문): "사운드 볼륨을 선택해주세요."

• 0.3 (작게)
• 0.5 (보통)
• 0.7 (기본, Recommended)
• 1.0 (최대)

3단계에서 사운드가 비활성화된 경우 이 질문을 건너뜁니다.

5-c. 야간 모드: "야간 모드를 사용하시겠습니까?"

• 사용 안 함 (기본, Recommended)
• 사용 (22:00~08:00)

6단계: 설정 저장

사용자 응답을 바탕으로 설정 객체를 구성합니다. 3단계에서 결정한 sound.enabled와 notification.enabled 값을 설정 객체에 반영합니다. 사운드가 활성화된 경우, 4단계에서 선택한 사운드팩 이름을 sound.pack 필드에 포함합니다.

스코프에 따라 아래 명령어로 설정을 저장합니다:

node "${CLAUDE_PLUGIN_ROOT}/scripts/config-save.mjs" '${CONFIG_JSON}' --scope '${SCOPE}' --cwd "$(pwd)"

• ${SCOPE}는 2단계에서 선택한 스코프 (global, project, local)
• ${CONFIG_JSON}은 사용자 응답을 바탕으로 구성한 설정 JSON 문자열

스코프별 동작:

• Global (--scope global): ~/.config/dding-dong/config.json에 전체 설정을 저장합니다.
• Project (--scope project): .dding-dong/config.json에 오버라이드 키만 (diff-only) 저장합니다. 기본값과 다른 항목만 설정 객체에 포함합니다. config.local.json을 .gitignore에 자동으로 추가합니다 (개인 설정 보호).
• Local (--scope local): .dding-dong/config.local.json에 오버라이드 키만 (diff-only) 저장합니다. 기본값과 다른 항목만 설정 객체에 포함합니다. .gitignore에 config.local.json 라인이 없으면 추가합니다.

결과 JSON의 success 필드로 저장 성공 여부를 확인합니다. error 필드가 있으면 사용자에게 안내합니다.

Project/Local 공통 — .gitignore 처리:

• 프로젝트 루트의 .gitignore에 config.local.json 패턴이 없으면 추가합니다.
• AskUserQuestion으로 추가 질문 (Project 스코프에서만): ".dding-dong/ 디렉토리 전체를 .gitignore에 추가하시겠습니까?"
  1. "config.local.json만 제외 (Recommended)" -- 팀 공유 config.json은 커밋, 개인 설정만 제외
  2. "디렉토리 전체 제외" -- .dding-dong/ 전체를 Git 추적에서 제외

6-a단계: 설정 완료 메타데이터 기록

글로벌 설정 파일에 _meta 필드를 기록합니다 (doctor 스킬에서 셋업 완료 여부 판별에 사용):

node "${CLAUDE_PLUGIN_ROOT}/skills/dd-setup/scripts/setup-meta.mjs"

결과 JSON의 success 필드로 기록 성공을 확인합니다. setupVersion은 plugin.json에서 자동으로 읽어옵니다.

이 단계는 자동으로 실행됩니다 (사용자 인터랙션 없음).

6-b단계: 플러그인 설치 검증

플러그인이 Claude Code에 등록되어 있는지 확인합니다:

claude plugin list 2>/dev/null | grep -qi dding-dong && echo "REGISTERED" || echo "NOT_REGISTERED"

• REGISTERED: "dding-dong 플러그인이 정상 등록되어 있습니다." 안내
• NOT_REGISTERED 또는 명령 실행 실패:

  dding-dong 플러그인이 Claude Code에 등록되지 않았습니다.
  아래 명령어로 등록해주세요:
    claude plugin add ${CLAUDE_PLUGIN_ROOT}
  

이 확인이 실패해도 셋업을 중단하지 않고 안내만 합니다.

7단계: 테스트 + 완료 요약

테스트 알림을 실행합니다:

node "${CLAUDE_PLUGIN_ROOT}/scripts/notify.mjs" test task.complete

3단계에서 "OS 알림만"을 선택한 경우, 테스트 시 소리가 나지 않는 것이 정상입니다. "OS 알림만 모드입니다. 소리 없이 데스크톱 알림만 표시됩니다." 안내를 추가합니다.

결과를 확인하고 완료 요약 메시지를 출력합니다:

성공 시:

dding-dong 설정 완료!
- 설정 파일: [설정 파일 경로]
- 범위: [전역/프로젝트/내 설정(Local)]
- 알림 방식: [사운드 + OS 알림 / 사운드만 / OS 알림만]
- 사운드 팩: [선택된 팩 displayName] (사운드 활성화 시에만 표시)
- 활성 이벤트: [활성화된 이벤트 목록]
- 볼륨: [설정된 볼륨] (사운드 활성화 시에만 표시)
- 야간 모드: [활성/비활성]

테스트 실패 시:

설정이 저장되었지만 테스트 알림에 실패했습니다.
/dding-dong:dd-config show 로 설정을 확인해주세요.

8단계: GitHub 스타 요청

이 단계는 셋업 결과에 영향을 주지 않는 부가적 단계입니다.

먼저 gh CLI 인증 여부를 확인합니다:

gh auth status 2>&1 && echo "GH_AUTHENTICATED" || echo "GH_NOT_AUTHENTICATED"

인증된 경우 (GH_AUTHENTICATED):

AskUserQuestion으로 질문합니다: "dding-dong이 마음에 드셨다면 GitHub에 스타를 남겨주세요!"

선택지:

1. 스타 남기기 -- "CaesiumY/dding-dong 저장소에 스타를 남깁니다."
2. 건너뛰기 -- "다음에 남기겠습니다."

• "스타 남기기" 선택 시:

  gh repo star CaesiumY/dding-dong
  

  성공 시: "감사합니다! 스타가 등록되었습니다." 안내 실패 시: 오류를 무시하고 조용히 진행

• "건너뛰기" 선택 시: 그냥 진행

미인증 또는 실패한 경우 (GH_NOT_AUTHENTICATED):

저장소 URL만 안내합니다:

dding-dong이 마음에 드셨다면 GitHub에 스타를 남겨주세요!
https://github.com/CaesiumY/dding-dong

---

관련 스킬

• 설정 조회/변경 → /dding-dong:dd-config
• 알림 문제 진단 → /dding-dong:dd-doctor
• 전체 기능 안내 → /dding-dong:dd-help