kdynext — 프로젝트 건강 진단 + 스킬 오케스트레이션

기존 프로젝트의 "다음에 뭘 해야 하지?"를 7개 건강 차원 진단 → 작업 우선순위 산출 → DAG 구축 → 병렬/서브에이전트 실행까지 자동 수행하는 오케스트레이터입니다.

핵심 원칙

기본 경로

GENERAL_PRO 결정 순서:
1. 환경변수 GENERAL_PRO_PATH
2. CWD가 00-general-pro* 내부이면 해당 루트
3. ~/{develop,dev}/00-general-pro-web 존재 탐색
4. 실패 시 AskUserQuestion: "00-general-pro-web 경로를 입력해주세요"

GENERAL_PRO = {결정된 경로}
SKILL_DIR = $GENERAL_PRO/03-skills/kdynext
PHASES_DIR = $SKILL_DIR/phases
REFERENCES_DIR = $SKILL_DIR/references

인수 처리

사용자가 제공한 인수: $ARGUMENTS

Phase 흐름

Step 0-0: 체크포인트 확인  → --resume 또는 기존 체크포인트 탐지
Phase 0: 컨텍스트 탐지    → 프로젝트 루트, 스택, 베이스라인, 규모 측정
Phase 1: 건강 스캔        → 7차원 병렬/순차 스캔
Phase 2: 작업 식별        → 점수화 + 병합 + 우선순위 정렬      [--scan-only 시 여기서 종료]
Phase 3: DAG 구축         → 의존성 그래프 + 병렬 그룹 + 실행 모드
Phase 4: 사용자 확인      → 실행 범위 결정                      [--auto 시 건너뜀]
Phase 5: 오케스트레이션 실행 → 그룹 순회 + 서브에이전트 병렬 발사
Phase 6: 완료 보고서      → 결과 요약 + 조건부 아카이브

Step 0-0: 체크포인트 확인

--resume 인수 또는 기존 체크포인트 파일 존재 시 중단 지점에서 재개합니다.

if --resume:
  Read: docs/references/_CHECKPOINT_KDYNEXT.md
  → 마지막 완료 Phase 확인
  → "수집 데이터 요약" 로드 (Phase 0~1 재실행 불필요)
  → 해당 Phase 이후부터 재개
elif _CHECKPOINT_KDYNEXT.md 파일이 이미 존재:
  AskUserQuestion: "이전 세션의 체크포인트가 있습니다. 재개/새로 시작?"
  → "재개" → 위 --resume 로직과 동일
  → "새로 시작" → 새 체크포인트 생성, Phase 0부터 정상 진행
else:
  새 체크포인트 생성, Phase 0부터 정상 진행

체크포인트 파일 위치: 대상 프로젝트의 docs/references/_CHECKPOINT_KDYNEXT.md

Phase 0: 컨텍스트 탐지

상세: phases/context-detection.md 참조

Read: $PHASES_DIR/context-detection.md

0-0-A. 이전 실행 비교 (반복 진단 방지)

체크포인트 로드 후, 이전 실행 결과와 비교하여 반복 감지된 결함을 식별합니다.

if _CHECKPOINT_KDYNEXT.md 존재 AND "## 이연 카운터" 섹션 존재:
  Read: _CHECKPOINT_KDYNEXT.md의 이연 카운터
  EACH 이전 미해결 항목:
    이연 횟수 + 1
    if 이연 횟수 >= 2:
      해당 항목 심각도 1단계 승격 (MEDIUM→HIGH, HIGH→CRITICAL)
    if 이연 횟수 >= 3:
      출력: "⚠️ [{항목}]은 {N}회 연속 미해결입니다. 이번 세션에서 반드시 착수하세요."
      출력: "💡 진단만 반복하는 것보다 실행을 권장합니다."

이 단계는 Phase 2(작업 식별)에서 DEFERRAL_BONUS 점수로 반영됩니다.

0-1. 프로젝트 루트 식별

Glob: CLAUDE.md, package.json, pyproject.toml

--project <path> 지정 시 해당 경로 사용. 새 프로젝트 감지 시 /kdygenesis 안내.

0-2. 스택 감지

0-3. 기존 상태 베이스라인

CLAUDE.md, docs/ 구조, verify 스킬, 레퍼런스 파일 존재 여부를 수집합니다.

0-4. 프로젝트 규모 기반 조건 분기

소스 파일 수에 따라 스캔/실행 전략을 자동 조정합니다.

0-5. 컨텍스트 요약 표시

Phase 1: 건강 스캔

상세: phases/health-scan.md 참조 차원 정의: references/health-dimensions.md 참조

Read: $PHASES_DIR/health-scan.md
Read: $REFERENCES_DIR/health-dimensions.md

1-1. 독립 4차원 병렬 스캔 (서브에이전트)

D1(구조), D2(코드품질), D3(문서화), D5(정리) → Task(Explore) × 4 동시 발사

1-2. 의존 3차원 순차 직접 스캔

D4(의존성), D6(테스트), D7(자산 신선도) → 순차 Glob/Read 직접 실행

1-3. 통합 건강 보고서

7차원 결과를 병합하여 건강 등급(A~F) 표시.

Phase 2: 작업 식별

상세: phases/task-identification.md 참조 점수 공식: references/scoring-algorithm.md 참조

Read: $PHASES_DIR/task-identification.md
Read: $REFERENCES_DIR/scoring-algorithm.md

2-1. 결함 → 작업 변환 + SCORE 계산

각 결함을 health-dimensions.md의 매핑 테이블로 스킬에 매핑하고 점수를 산출합니다.

2-2. 동일 스킬 작업 병합 (중복 제거)

동일 스킬 + 동일 모드 → 단일 작업으로 병합, MAX 점수 사용.

2-3. 우선순위 정렬된 작업 목록 출력

--scan-only 시 여기서 종료.

Phase 3: DAG 구축

상세: phases/dag-construction.md 참조 병렬 규칙: references/parallelization-matrix.md 참조 실행 모드: references/subagent-decision-tree.md 참조

Read: $PHASES_DIR/dag-construction.md
Read: $REFERENCES_DIR/parallelization-matrix.md
Read: $REFERENCES_DIR/subagent-decision-tree.md

3-1. 하드 의존성 그래프

G0(전제조건) → G1(스캔) → G2(대화형) → G3(수정) → G4(검증) → G5(동기화) → G6(반성)

3-2. 병렬 그룹 할당

G1, G3, G4는 병렬. G0, G2, G5, G6은 순차.

3-3. 실행 모드 결정

subagent-decision-tree.md로 각 작업을 Explore/general-purpose/직접 대화형으로 분류.

3-4. DAG 시각화 + 빈 그룹 제거

Phase 4: 사용자 확인

상세: phases/user-review.md 참조

Read: $PHASES_DIR/user-review.md

4-1. 전체 계획 표시

DAG 시각화 + 작업 상세 목록을 표시합니다.

4-2. 사용자 선택

AskUserQuestion: 전체 실행 / 스캔만 / 그룹 선택 / 취소

--auto 시 이 Phase 건너뜀 (전체 실행, 대화형 작업 SKIPPED).

Phase 5: 오케스트레이션 실행

상세: phases/orchestrated-execution.md 참조

Read: $PHASES_DIR/orchestrated-execution.md

5-1. 그룹 순회 루프

EACH 활성 그룹 G(n):
  서브에이전트 가능 작업 → Task 병렬 발사
  대화형 작업 → 직접 순차 실행
  결과 수집 → 상태 업데이트

5-2. 에러 처리

• 서브에이전트 타임아웃 → FAILED 기록, 다음 진행
• 서브에이전트 에러 → 1회 재시도 후 FAILED
• 대화형 실패 → AskUserQuestion (재시도/건너뛰기/전체 중단)

Phase 6: 완료 보고서

상세: phases/completion-report.md 참조

Read: $PHASES_DIR/completion-report.md

6-1. 결과 보고서 출력

실행 요약, 그룹별 결과, 변경 파일, 미해결 항목, 다음 권장 작업.

6-2. 조건부 아카이브

CRITICAL 1+ 또는 전체 실행 완료 시 docs/logs/YYYY-MM.md에 기록.

Superpowers 연계

이 스킬 실행 중 아래 superpowers 원칙을 적용한다.

kdyswarm 위임 조건

다음 조건이 모두 충족될 때 /kdyswarm으로 위임을 권장한다:

• Phase 5에서 코드 수정 스킬이 5개 이상
• 프로젝트가 LARGE (501개+ 파일)

예외사항

다음은 문제가 아닙니다:

1. 00 general-pro 자체 — D2(reusable-code만), D5, D7만 스캔. 구조/문서/의존성/테스트는 N/A
2. 새 프로젝트 (빈 디렉토리) — kdynext 대상 아님. /kdygenesis로 안내
3. 결함 0개 — 건강 상태 양호 표시 후 간소화 보고서
4. --scan-only 모드 — Phase 2까지만 실행, 수정 없음
5. 대화형 작업 --auto 건너뜀 — SKIPPED로 기록, 미해결 항목에 추가

관련 스킬/에이전트

사용 예시

# 기본: 전체 진단 + 실행 계획 + 사용자 확인 후 실행
/kdynext

# 스캔만 (수정 없음, 보고서만)
/kdynext --scan-only

# 자동 실행 (대화형 작업 건너뜀)
/kdynext --auto

# 특정 차원만 스캔
/kdynext --focus code-quality
/kdynext --focus D7

# 다른 프로젝트 경로 지정
/kdynext --project {프로젝트 경로}/my-project

# 이전 세션에서 중단된 지점부터 재개
/kdynext --resume

주의사항

1. kdynext는 기존 프로젝트 전용 — 빈 디렉토리에서는 kdygenesis를 사용하세요
2. 서브에이전트 비용 — 병렬 스캔 시 최대 4개 서브에이전트가 동시 실행됩니다
3. 대화형 작업 순차 — 사용자 입력이 필요한 스킬은 병렬화할 수 없습니다
4. inception/kdyupdate 순서 — 반드시 inception → kdyupdate 순서를 지켜야 합니다
5. 00 general-pro 특수 모드 — 자산 신선도, 정리, 코드 품질만 스캔합니다