ppt-writer

name	ppt-writer
description	DMAP 표준 2단계 PPT 빌드 오케스트레이션 — N 산출물을 pptx-spec-writer로 명세 작성 후 pptxgenjs build.js를 직접 실행하여 각 .pptx 생성 (다중 deck 루프)
type	orchestrator
user-invocable	true

PPT-Writer

[PPT_WRITER 활성화]

목표

FinOps 파이프라인 산출물을 선별하여 DMAP 표준 2단계 PPT 빌드 패턴으로 다중 .pptx를 생성함:

• Phase 1: orchestrator가 직접 산출물 선별 + (선택) 이미지 생성
• Phase 2: pptx-spec-writer 에이전트가 산출물당 1 spec.md 작성 (N회 루프)
• Phase 3: orchestrator가 pptxgenjs로 build.js를 직접 작성·실행 (N회 루프, 각 deck.pptx 생성)
• Phase 4: 자가 검증 + 사용자 보고

DMAP 표준 Office 빌드 패턴 준수:

• PPT: 2단계(Spec Agent + Orchestrator Builder) — {DMAP_PLUGIN_DIR}/resources/guides/office/pptx-build-guide.md
• 외부 변환 스킬(anthropic-skills:pptx 등) 의존 제거
• Marp deck md 산출 폐기 — spec.md가 유일한 중간 산출물

활성화 조건

다음 중 하나 이상 해당 시 활성화됨:

• @ppt-writer 멘션
• "PPT deck", "발표자료", "PPT 스크립트" 키워드 포함
• /finops:ppt-writer 직접 호출

에이전트 호출 규칙

에이전트 FQN

에이전트	FQN	티어	담당
pptx-spec-writer	finops:pptx-spec-writer:pptx-spec-writer	MEDIUM	Phase 2 (산출물당 1 spec 작성, N회 루프)

프롬프트 조립

• resources/guides/combine-prompt.md에 따라 AGENT.md + agentcard.yaml + tools.yaml 합치기
• Agent(subagent_type=FQN, model=tier_mapping 결과, prompt=조립된 프롬프트) 호출
• tier → 모델 매핑은 gateway/runtime-mapping.yaml 참조

서브 에이전트 호출

워크플로우 단계에 Agent: {agent-name}이 명시된 경우, 메인 에이전트는 해당 단계를 직접 수행하지 않고, 반드시 위 프롬프트 조립 규칙에 따라 해당 에이전트를 호출하여 결과를 받아야 함.

서브에이전트 호출 없이 메인 에이전트가 해당 산출물을 직접 작성하면 스킬 미준수로 간주함.

PPT 빌드는 위임 없이 오케스트레이터가 직접 수행

• DMAP 2단계 패턴 Phase 3은 orchestrator가 pptxgenjs build.js를 Write + Bash로 직접 작성·실행
• anthropic-skills:pptx에 Skill→Skill 위임 금지
• spec.md → build.js 변환 로직은 본 스킬이 DMAP pptx-build-guide.md 6절 11항을 필독 후 직접 작성

워크플로우

Phase 0: 선행 확인 & 옵션 수집 (ulw 활용)

다음 항목을 순서대로 확인:

• out/ 디렉토리에 PPT 선별 가능한 산출물 최소 2종 존재 확인
  • 미존재 시 /finops:core 선행 실행 안내 후 중단
• gateway/tools/.env 존재 여부 확인 → GEMINI_API_KEY 유효성 체크
• pptxgenjs 설치 확인: Bash cd out && node -e "require('pptxgenjs')" 실행
  • 실패 시 /finops:setup 재실행 안내 후 중단 (runtime_dependencies 설치 필요)

AskUserQuestion으로 이미지 포함 여부를 질의:

• "이미지 포함 (Gemini 호출)" — GEMINI_API_KEY 존재 시에만 선택지 제공
• "텍스트만 (이미지 스킵)" — 항상 제공

Phase 1: 산출물 선별 + (선택) 이미지 생성 (오케스트레이터 직접 수행 — ulw 활용)

외부 에이전트 위임 없이 orchestrator가 직접 수행:

1. 산출물 선별: Read + Glob로 out/**/*.md 스캔
   • 평가 후보: why-statement, maturity-diagnosis, rightsize-plan, commit-strategy, review-runbook, maturity-transition, review-report 등
   • 선정 기준: 경영진·의사결정·교육 관점 중요도, 시각화 적합성, 슬라이드 밀도
   • 선별 결과를 out/ppt-scripts/index.md에 저장 — 대상 목록 + 선정 근거 + 예상 슬라이드 수
2. 이미지 생성 (이미지 모드 시): generate_image 커스텀 도구 직접 호출
   • 각 산출물 핵심 개념에 대해 finops-ppt-addendum.md §6의 파일명 규칙 준수
   • 교육용 일러스트 스타일(§7) 프롬프트 적용
   • 산출: out/ppt-scripts/images/{finops_*}.png + out/ppt-scripts/images/index.md (이미지↔슬라이드 매핑)
3. 이미지 스킵 모드: out/ppt-scripts/index.md에 "이미지 모드: 스킵" 명기

Phase 2: Spec 작성 → Agent: pptx-spec-writer (산출물당 1회 루프, ulw 활용)

Phase 1에서 선별된 산출물 N건 각각에 대해 pptx-spec-writer 에이전트에 루프 위임:

• TASK: 산출물 1건을 분석하여 PPT 시각 명세({대상}-spec.md) 작성
• EXPECTED OUTCOME: out/ppt-scripts/{대상}-spec.md (패턴 A~F 매핑 + 이미지 참조)
• MUST DO:
  • {DMAP_PLUGIN_DIR}/resources/guides/office/pptx-build-guide.md 1~5절 필독
  • {PLUGIN_DIR}/agents/pptx-spec-writer/references/finops-ppt-addendum.md 필독 (산출물별 표준 흐름 §1)
  • 슬라이드당 본문 ≤7줄, 이미지는 ![설명](images/파일명.png) 형식
  • 모든 수치에 범위·출처 명시 (addendum §3·§4)
• MUST NOT DO: 실제 PPT 파일 생성 금지, 컬러·폰트 직접 지정 금지, 단일 숫자 수치 표기 금지
• CONTEXT (산출물별 다름): 해당 out/{대상}.md 경로, 이미지 목록, 목표 슬라이드 수, 대상 청중

루프 완료 후 N개 {대상}-spec.md 존재 확인.

Phase 3: PPT 파일 빌드 (오케스트레이터 직접 수행, 산출물당 1회 루프 — ulw 활용)

외부 스킬 위임 없이 orchestrator가 직접 수행 (산출물 N건 각각):

1. 가이드 로드 (루프 외부, 1회만): {DMAP_PLUGIN_DIR}/resources/guides/office/pptx-build-guide.md 전체 읽기 (특히 6절 "코드 생성 시 필수 검증 규칙" 11항 모두 준수)
2. 각 산출물에 대해 (루프): a. out/ppt-scripts/{대상}-spec.md 읽고 슬라이드별 패턴(A~F) 매핑 b. 빌드 코드 작성: Write 도구로 out/ppt-scripts/{대상}-build.js 생성
   • pptxgenjs 사용
   • 반드시 가이드 6절 전체 규칙 준수:
     • pptx.shapes.RECTANGLE/ROUNDED_RECTANGLE 사용 (ShapeType 금지)
     • defineLayout({name:"CUSTOM", width:16, height:9})
     • async function createSlideXX(pptx) 패턴
     • slide.addTable() 사용 (수동 셀 그리기 금지)
     • fs12() 헬퍼로 12pt 미만 폰트 차단
     • 이미지 임베딩 전 경로·크기 검증
     • Pretendard 폰트 통일
     • main().catch(e => { console.error(...); process.exit(1); }) 진입점 c. 빌드 실행: Bash로 cd out/ppt-scripts && node {대상}-build.js 실행 → out/ppt-scripts/{대상}-deck.pptx 생성
   • 전제: pptxgenjs가 플러그인 루트(finops-lab/node_modules/)에 설치됨 (Node 해석 경로: out/ppt-scripts → out → finops-lab/node_modules ✓)
   • Cannot find module 'pptxgenjs' 발생 시 /finops:setup 재실행하여 플러그인 루트에 설치 d. 검증 A — 빌드 확인:
   • 빌드 종료 코드 0 확인
   • .pptx 파일 존재 및 0바이트 초과 확인
   • 자가 검증 체크리스트 11항 통과
   • 실패 시 에러 분석 → 코드 수정 → 재실행 (해당 deck만 최대 3회) e. 검증 B — PowerShell COM 시각적 검토:
   • 아래 PS1 템플릿으로 .temp/export-{대상}.ps1을 생성 후 슬라이드별 PNG 추출

   $pptxPath = '<절대경로\{대상}-deck.pptx>'
   $outDir   = '<절대경로\preview\{대상}>'
   if (-not (Test-Path $outDir)) { New-Item -ItemType Directory -Path $outDir | Out-Null }
   Add-Type -AssemblyName Microsoft.Office.Interop.PowerPoint
   $ppt  = New-Object -ComObject PowerPoint.Application
   $pres = $ppt.Presentations.Open($pptxPath, 0, 0, 0)
   foreach ($i in 1..$pres.Slides.Count) {
       $pres.Slides.Item($i).Export("$outDir\slide-$i.png", 'PNG', 1600, 900)
   }
   $pres.Close(); $ppt.Quit()
   

   • PowerShell 실행 전 Get-Process POWERPNT -ErrorAction SilentlyContinue | Stop-Process -Force로 파일 잠금 해제
   • 추출된 PNG를 Read 도구로 열어 레이아웃·이미지 비율·텍스트 잘림 시각 확인
   • 이상 발견 시 {대상}-build.js 수정 → 재빌드 → 재검토 (최대 2회)
   • 기존 이미지 파일(images/ 폴더)은 절대 삭제하지 말 것 — 레이아웃·크기만 조정
   • 시각 검토 완료 후 임시 파일 정리: Remove-Item '<preview경로>\*.png' -Force; Remove-Item '.temp\export-{대상}.ps1' -Force
3. 루프 집계: 성공 deck / 실패 deck을 리스트로 분리 수집

Phase 4: 자가 검증 & 사용자 보고 (/oh-my-claudecode:verify 활용)

루프 전체에 대해 다음 항목을 검증:

• 각 {대상}-spec.md 파일 존재 (Phase 2 결과)
• 각 {대상}-build.js 파일 존재 (Phase 3 결과)
• 각 {대상}-deck.pptx 파일 존재 및 크기 > 10KB
• 슬라이드 수가 spec md의 ## 슬라이드 N: 항목 수와 일치
• 이미지 모드 시 images/*.png 파일이 실제 존재 (참조된 항목)
• 빌드 실패 deck 리스트 비어있음 (또는 사용자에게 원인 보고)

완료 시 생성된 .pptx 파일 목록·경로·크기·슬라이드 수를 표로 안내.

완료 조건

• 선별 결과(out/ppt-scripts/index.md) 존재
• N개 {대상}-spec.md 생성 (Phase 2)
• N개 {대상}-build.js 생성 (Phase 3)
• 동일 수의 {대상}-deck.pptx 생성 (Phase 3)
• 이미지 모드 시 out/ppt-scripts/images/ 디렉토리 및 index.md 존재
• 각 .pptx 크기 > 10KB

검증 프로토콜

1. ppt-writer SKILL.md의 완료 조건 체크박스 전항목 통과
2. 각 {대상}-spec.md의 ## 슬라이드 N: 매치 수 = 빌드된 .pptx의 슬라이드 수
3. 이미지 모드 시 spec.md 내 ![](images/*.png) 참조 파일 모두 디스크에 존재
4. 빌드 실패 deck은 별도 리스트로 사용자에게 원인과 함께 보고
5. pptxgenjs 미설치 시 graceful failure + /finops:setup 안내

MUST / MUST NOT

MUST

• Phase 순차 수행 및 완료 시마다 사용자 보고
• Phase 0에서 pptxgenjs 설치 확인 (cd out && node -e "require('pptxgenjs')")
• Phase 1은 orchestrator가 직접 수행 (artifact 선별 + 이미지 생성)
• Phase 2는 산출물당 1회 pptx-spec-writer 에이전트 위임 (5항목 프롬프트)
• Phase 3는 orchestrator가 직접 build.js 작성·실행 (산출물당 1회 루프)
• Phase 3 시작 시 pptx-build-guide.md 전체(특히 6절 11항) 필독
• 빌드 스크립트({대상}-build.js)를 산출물로 보존
• 실제 .pptx 파일 생성 및 >10KB 검증

MUST NOT

• anthropic-skills:pptx 등 외부 변환 스킬 호출
• anthropic-skills:pptx에 Skill→Skill 위임
• pptx-spec-writer 에이전트 우회 (orchestrator가 spec 직접 작성 금지)
• Phase 순서 건너뛰기
• 가이드 미독상태로 build.js 작성
• 검증 없이 "생성 완료" 보고
• Marp deck md(*-deck.md) 산출 (폐기됨 — spec.md가 유일한 중간 산출물)
• 시각적 검토 후 수정 시 images/ 폴더의 기존 이미지 파일 삭제 (레이아웃·크기 조정만 허용)

상태 정리

임시 상태 파일 미사용. 산출물은 out/ppt-scripts/ 경로에 영구 저장. 빌드 스크립트(*-build.js)도 산출물과 함께 보존 → 재빌드·디버깅 가능.

취소

cancelomc 입력 시 현재 Phase 중단. 이미 생성된 .pptx 파일은 보존.

재개

• out/ppt-scripts/index.md 존재 → Phase 1 완료 판정
• {대상}-spec.md 존재 → Phase 2 해당 deck 완료 판정
• {대상}-deck.pptx 존재 → Phase 3 해당 deck 완료 판정
• 실패 deck만 선택 재빌드 가능 (Phase 3만 재실행)

출력 형식

사용자 보고 형식 (권장)

## PPT-Writer 생성 결과 (DMAP 2단계 빌드)

### 성공한 .pptx 파일
| 파일명 | 슬라이드 수 | 파일 크기 | 빌드 스크립트 |
|---|---|---|---|
| out/ppt-scripts/{대상1}-deck.pptx | N | NKB | {대상1}-build.js |
| out/ppt-scripts/{대상2}-deck.pptx | N | NKB | {대상2}-build.js |

### 실패한 deck (있을 경우)
| 대상 | 단계 | 오류 | 조치 |
|---|---|---|---|
| {대상3} | Phase 3 빌드 | ... | 재빌드 또는 spec 수정 |

### 이미지 생성 현황
- 모드: [이미지 포함 | 텍스트만]
- 이미지 수: N개

### 파일 경로
- 선별 결과: out/ppt-scripts/index.md
- 이미지: out/ppt-scripts/images/ (이미지 모드 시)
- Spec md: out/ppt-scripts/{대상}-spec.md
- 빌드 스크립트: out/ppt-scripts/{대상}-build.js
- PowerPoint: out/ppt-scripts/{대상}-deck.pptx