/dev [기능명]              # 전체 워크플로우
/dev --plan [기능명]       # 기획 (PRD)
/dev --discuss [기능명]    # 구현 결정 수집 (그레이 영역 해소)
/dev --design [기능명]     # 설계 (아키텍처)
/dev --tasks [기능명]      # 태스크 분해
/dev --build [TASK-ID]     # 단일 Task 구현 (TDD)
/dev --build --wave [N]    # Wave N의 Task 병렬 실행
/dev --build --all         # 모든 Wave 순차 실행 (Wave 내 병렬)
/dev --roadmap             # 로드맵/Phase 상태 조회
/dev --roadmap add "제목"  # Phase 추가 (마지막에)
/dev --roadmap insert N "제목"  # Phase N 앞에 긴급 삽입
/dev --roadmap remove N    # Phase N 삭제 (예정 상태만)
/dev --roadmap complete N  # Phase N 완료 → 다음 Phase 활성화
/dev --roadmap milestone "v1.0.0"  # 마일스톤 생성 + 아카이빙
/dev --status              # 진행 상황

Task(
    subagent_type="calab-plugin:planner-phase",
    description="기능 기획",
    prompt="... (references/plan-phase.md 참조)"
)

# 1. PRD 분석하여 구현 결정이 필요한 항목 식별
prd = Read(f".claude/docs/active/{feature}/02-PRD.md")

# 2. 그레이 영역 식별 (best-practices 기반 기본값 제공)
gray_areas = identify_gray_areas(prd)
# 예: 기술 선택, UI/UX 결정, 아키텍처 패턴, API 설계 방식

# 3. AskUserQuestion으로 각 결정 수집
for area in gray_areas:
    answer = AskUserQuestion(
        questions=[{
            "question": area.question,
            "header": area.category,
            "options": area.options,  # best-practices 기반 기본값 포함
            "multiSelect": False
        }]
    )

# 4. 산출물 생성: 00-CONTEXT.md
Write(
    file_path=f".claude/docs/active/{feature}/00-CONTEXT.md",
    content=generate_context_doc(decisions)
)

# 구현 결정: {feature-name}

## 기술 선택
- **상태 관리**: {선택값} ({근거})
- **데이터 페칭**: {선택값}

## UI/UX 선택
- **레이아웃**: {선택값}
- **테마**: {선택값}

## 아키텍처 선택
- **에러 처리**: {선택값}
- **타입 정의**: {선택값}

## API 설계
- **응답 형식**: {선택값}
- **인증**: {선택값}

Task(
    subagent_type="calab-plugin:design",
    description="아키텍처 설계",
    prompt="... (references/design-phase.md 참조)"
)

Task(
    subagent_type="calab-plugin:planner-task",
    description="Task 분해",
    prompt="... (references/tasks-phase.md 참조)"
)

Task(
    subagent_type="calab-plugin:dev-executor",
    description="TDD 구현",
    prompt="... (references/build-phase.md 참조)"
)

# 1. worktree.json에서 Wave 정보 로드
worktree = Read(".claude-state/worktree.json")
wave_tasks = [t for t in worktree.tasks if t.wave == target_wave]

# 2. Wave 내 Task를 병렬 스폰 (각 executor는 fresh context)
for task in wave_tasks:
    Task(
        subagent_type="calab-plugin:dev-executor",
        description=f"[Wave {target_wave}] {task.subject}",
        prompt=f"""
        ## Task 정의
        - ID: {task.id}
        - Subject: {task.subject}
        - AC: {task.acceptance_criteria}
        - Files: {task.files}

        ## 지침
        - 이 Task만 구현하세요 (다른 Task 코드 읽지 마세요)
        - TDD: RED → GREEN → REFACTOR
        - 완료 후 TaskUpdate(status="completed")
        """,
        run_in_background=True  # 병렬 실행
    )

# 3. 모든 executor 완료 대기 후 다음 Wave 진행

# Wave 1 → Wave 2 → ... → Wave N 순차 실행
# 각 Wave 내부는 병렬 실행
for wave_num in range(1, total_waves + 1):
    execute_wave(wave_num)  # 병렬 스폰 + 완료 대기
    validate_wave(wave_num)  # Wave 완료 검증

# 1. ROADMAP.md 확인
roadmap_path = f".claude/docs/active/{feature}/ROADMAP.md"
roadmap = Read(roadmap_path)  # 없으면 --plan 먼저 실행 안내

# 2. 서브커맨드에 따라 분기
if subcommand == None:
    # 상태 조회 - 현재 Phase 진행률 출력
    display_roadmap_status(roadmap)

elif subcommand == "add":
    # AskUserQuestion으로 Phase 제목/항목 수집
    phase_info = AskUserQuestion(questions=[{
        "question": "추가할 Phase의 이름은?",
        "header": "Phase 추가",
        "options": [
            {"label": "사용자 입력", "description": "직접 Phase 이름 입력"}
        ],
        "multiSelect": False
    }])
    add_phase(feature, phase_info)

elif subcommand == "insert":
    # Phase N 앞에 긴급 삽입
    insert_phase(feature, position=N, title=title)

elif subcommand == "remove":
    # Phase N 삭제 (예정 상태만, 진행 중은 사용자 확인)
    remove_phase(feature, phase_num=N)

elif subcommand == "complete":
    # Phase N 완료 + 다음 Phase 활성화
    complete_phase(feature, phase_num=N)

elif subcommand == "milestone":
    # 마일스톤 생성 + Git 태그 (선택)
    create_milestone(feature, version=version)

def create_checkpoint(type, context):
    """Checkpoint 생성 시 타입에 따라 처리 방식 결정"""

    if type == "human-verify":
        # 90% - 간결한 요약 + 자동 진행 옵션
        return {
            "message": f"{context.summary}",
            "options": [
                {"label": "확인, 진행 (권장)", "description": "다음 단계로"},
                {"label": "수정 필요", "description": "변경사항 요청"}
            ],
            "auto_proceed": True  # 타임아웃 시 자동 진행 가능
        }

    elif type == "decision":
        # 9% - 트레이드오프 분석 + 추천안 제시
        return {
            "message": f"{context.question}",
            "options": context.analyzed_options,  # 각 옵션에 장단점 포함
            "recommendation": context.recommended,  # 첫 번째 옵션이 추천
            "auto_proceed": False  # 반드시 사용자 선택 대기
        }

    elif type == "human-action":
        # 1% - 명확한 지시 + 완료 대기
        return {
            "message": f"[사용자 행동 필요] {context.action_required}",
            "steps": context.step_by_step,  # 단계별 가이드
            "auto_proceed": False,  # 행동 완료까지 대기
            "blocking": True
        }

graph TD
    IMPL["구현 (dev-executor)"] --> VALIDATE["검증 (validator)"]
    VALIDATE -->|성공| NEXT["다음 Task"]
    VALIDATE -->|실패| REINFORCE["reinforcer"]
    REINFORCE --> REVALIDATE["재검증 (validator)"]
    REVALIDATE -->|성공| NEXT
    REVALIDATE -->|실패| ESCALATE["사용자 결정"]

graph LR
    PLAN["PLAN<br/>01-brainstorm<br/>02-PRD"] --> DISCUSS["DISCUSS<br/>00-CONTEXT<br/>(선택적)"]
    DISCUSS --> DESIGN["DESIGN<br/>03-architecture<br/>04-ERD"]
    DESIGN --> TASKS["TASKS<br/>05-tasks<br/>worktree (wave 할당)"]
    TASKS --> BUILD["BUILD"]

    BUILD --> W1["Wave 1: 병렬"]
    W1 --> W2["Wave 2: 병렬"]
    W2 --> WN["Wave N: 병렬"]

// .claude/settings/model-profile.json
{
  "profile": "balanced",
  "overrides": {}
}

# 프로필에서 모델 결정
profile = load_model_profile()
model = profile.get_model("dev-executor")  # → "sonnet" (balanced)

Task(
    subagent_type="calab-plugin:dev-executor",
    model=model,  # 프로필 기반
    ...
)