name	setup
description	finops 플러그인 초기 설정 (모델 버전 확인, generate_image 설치, DMAP Office 빌더 런타임 설치, 라우팅 등록)
type	setup
user-invocable	true

Setup

[SETUP 활성화]

목표

finops 플러그인의 도구/환경/라우팅을 초기화하여 즉시 사용 가능 상태로 만듦. gateway/runtime-mapping.yaml 모델 버전 갱신, generate_image 선택적 설치, DMAP Office 빌더 런타임(pptxgenjs) 자동 검증·설치, CLAUDE.md 라우팅 등록을 순차 수행함.

활성화 조건

사용자가 /finops:setup 호출 시 또는 "finops 설치" 키워드 감지 시.

워크플로우

Step 1: 플러그인 변수 확인 (`ulw` 활용)

프로젝트 AGENTS.md(./AGENTS.md)의 ## 플러그인 변수 섹션에서 아래 4개 변수를 확인함.

변수	기대값 예시
`AI_RUNTIME`	`Claude Code`
`DMAP_PLUGIN_DIR`	`/Users/dreamondal/plugins/dmap`
`PLUGIN_DIR`	`/Users/dreamondal/plugins/finops-lab`
`PLUGIN_NAME`	`finops`

누락된 변수 발견 시 사용자에게 해당 변수명과 예시값을 안내하고 ./AGENTS.md의 ## 플러그인 변수 섹션에 추가할 것을 요청함. 4개 모두 확인 시 Step 2로 진행함.

Step 2: 런타임 최신 모델 버전 확인 (`ulw` 활용)

gateway/runtime-mapping.yaml의 tier_mapping.{claude-code, cursor, codex, antigravity} 4런타임 엔트리를 읽어 사용자에게 표시함.

Claude 계열 런타임(claude-code / cursor / antigravity):

WebFetch로 https://docs.anthropic.com/en/docs/about-claude/models 조회 → 최신 Opus/Sonnet/Haiku 확인

OpenAI 계열 런타임(codex):

WebFetch로 OpenAI 모델 페이지 조회 → gpt-5.4(flagship), gpt-5.2-codex, gpt-5.1-codex-max, gpt-5.4-mini 중 최신 버전 확인

WebFetch 접근 불가 시 사용자에게 최신 모델명 직접 입력을 안내함.

현재 값과 최신 값을 비교하여 차이가 있을 경우 AskUserQuestion으로 4런타임 일괄 갱신 여부를 질의함.

"Yes" 선택 시: gateway/runtime-mapping.yaml의 해당 tier_mapping 엔트리를 최신 모델명으로 갱신함 + Step 2.5 실행
"No" 선택 시: 현재 버전 유지, Step 3으로 진행함

Step 2.5: 런타임 어댑터 frontmatter 일괄 갱신 (`ulw` 활용)

Step 2에서 tier_mapping이 갱신된 경우, 런타임 어댑터 포인터 스텁의 frontmatter model: 필드를 새 매핑값으로 일괄 치환함 (본문·주석은 절대 수정 금지).

대상 경로	파일	매핑 참조
`.claude/agents/*.md`	9개	`tier_mapping.claude-code.{tier}.model`
`.cursor/agents/*.md`	9개	`tier_mapping.cursor.{tier}.model`
`.codex/agents/*.toml`	9개	`tier_mapping.codex.{tier}.model`
`.antigravity/agents/*.md`	9개	`tier_mapping.antigravity.{tier}.model`

각 어댑터 파일의 에이전트 이름으로 agents/{name}/agentcard.yaml을 참조하여 tier를 해결한 뒤, 런타임·tier 조합에 따른 최신 모델명으로 frontmatter model: 한 줄만 치환함. 총 36개 파일 일괄 처리.

본 Step은 Step 2의 갱신 여부와 무관하게 어댑터 파일 존재 여부를 점검하며, 누락된 어댑터가 있으면 사용자에게 보고함.

Step 3-A: generate_image 도구 설치 (`ulw` 활용)

gateway/install.yaml에서 generate_image 항목의 required: false 확인 후 AskUserQuestion으로 설치 여부를 질의함.

"Yes" 선택 시:

Python 의존성 설치:
```
pip install python-dotenv google-genai
```

설치 검증:

python gateway/tools/generate_image.py --help

.env 파일 생성:
- gateway/tools/.env.example 존재 시: 해당 파일을 gateway/tools/.env로 복사 후 GEMINI_API_KEY 값 입력을 요청함
- .env.example 부재 시: GEMINI_API_KEY 한 줄만 받아 gateway/tools/.env를 직접 생성함
- AskUserQuestion으로 GEMINI_API_KEY 값을 수집하여 파일에 기록함

"No" 선택 시:

설치를 스킵함. 이후 /finops:ppt-writer 실행 시 이미지 생성 없이 텍스트 슬라이드로만 제작됨을 안내함.

Step 3-B: DMAP Office 빌더 런타임(`pptxgenjs`) 설치 (`ulw` 활용)

gateway/install.yaml의 runtime_dependencies 섹션을 파싱하여 pptxgenjs 엔트리를 처리함.

3-B-1. 사전 런타임 확인

node --version 실행 → v18 이상 확인
미설치 또는 v18 미만 시 Node.js 18+ 설치 안내(https://nodejs.org/) 후 Step 3-B 중단
npm --version 실행 → npm 사용 가능 확인

3-B-2. pptxgenjs 설치 검증·설치

check 명령 실행 (install.yaml의 runtime_dependencies.pptxgenjs.check):
```
node -e "require('pptxgenjs')"
```
exit code 0이면 이미 설치됨 → 표시하고 3-B-3으로 진행

실패 시 AskUserQuestion으로 설치 동의 요청 → 동의 시 install 명령 실행:

# 설치 위치: 플러그인 루트(finops-lab/)
#   사유: Node 모듈 해석은 스크립트 디렉토리에서 상위로 탐색함.
#        out/ppt-scripts/{대상}-build.js 에서 require('pptxgenjs')가
#        finops-lab/node_modules/를 찾아야 하므로 플러그인 루트 설치 필수.
#        gateway/는 out/과 형제라 해석 경로에 포함되지 않음.
cd "$PLUGIN_DIR"
[ -f package.json ] || npm init -y
npm install pptxgenjs

설치 후 check 재실행으로 결과 검증
.gitignore에 node_modules/ 등록 권장 (미등록 시 자동 추가)

3-B-3. 실사용 CWD 해석 검증

/finops:ppt-writer가 실제 빌드를 실행하는 CWD에서 모듈 해석 성공 여부 확인:

cd "$PLUGIN_DIR/out" && node -e "require('pptxgenjs')"

실패 시 설치 위치 오류(예: gateway/ 설치됨) — 플러그인 루트 재설치 안내.

Step 4: 라우팅 테이블 등록 (`ulw` 활용)

AskUserQuestion으로 라우팅 등록 적용 범위를 질의함.

선택지	대상 파일	동작
모든 프로젝트	`~/.claude/CLAUDE.md`	전역 라우팅 섹션 추가 (Claude Code 전역 설정)
이 프로젝트만	`./AGENTS.md`	현재 프로젝트 AGENTS.md에 섹션 추가

등록 내용 (## finops 플러그인 섹션):

## finops 플러그인

### 라우팅 키워드
- `@setup`, "finops 설치" → `/finops:setup`
- `@help`, "finops 도움말", "finops 뭘 할 수 있어" → `/finops:help`
- `@why-finops`, "FinOps 왜" → `/finops:why-finops`
- `@inform`, "FOCUS 정규화", "대시보드" → `/finops:inform`
- `@optimize`, "Right-sizing", "약정" → `/finops:optimize`
- `@operate`, "KPI", "리뷰 런북" → `/finops:operate`
- `@review`, "최종 검증" → `/finops:review`
- `@ppt-writer`, "PPT deck", "발표자료" → `/finops:ppt-writer`
- `@core`, "FinOps 랩 전체" → `/finops:core`

Step 5: 설치 결과 요약 보고 (`ulw` 활용)

모든 Step 완료 후 결과를 체크리스트 형식으로 출력함.

✅ Step 1: 플러그인 변수 4개 확인 완료 (AI_RUNTIME·DMAP_PLUGIN_DIR·PLUGIN_DIR·PLUGIN_NAME)
✅ Step 2: 4런타임 모델 버전 확인/갱신 완료 (claude-code·cursor·codex·antigravity)
✅ Step 2.5: 런타임 어댑터 36개 frontmatter 일괄 갱신 완료
✅ Step 3-A: generate_image 설치 [완료 | 스킵]
✅ Step 3-B: pptxgenjs 설치 [완료 | 이미 설치됨 | 스킵(Node 미설치)]
✅ Step 4: 라우팅 테이블 등록 완료 ([모든 프로젝트 | 이 프로젝트만])

다음 단계:
- 전체 명령 목록 확인: /finops:help
- FinOps 전체 파이프라인 실행: /finops:core
- PPT deck 빌드: /finops:ppt-writer

사용자 상호작용

AskUserQuestion을 활용한 5가지 질의 (최대 5회):

순서	질의 내용	선택지
1	최신 모델 버전으로 `runtime-mapping.yaml` 갱신 여부	Yes / No
2	`generate_image` 도구 설치 여부	Yes / No
3	`GEMINI_API_KEY` 입력 (Step 3-A "Yes" 선택 시에만)	문자열 입력
4	`pptxgenjs` 설치 여부 (check 실패 시에만)	Yes / No
5	라우팅 등록 적용 범위	모든 프로젝트 / 이 프로젝트만

스킬 위임

없음. 모두 직결형 Gateway 도구(Bash, Read, Write, AskUserQuestion, WebFetch) 직접 사용.

문제 해결

문제	대응
Python 미설치	`python --version` 확인 후 미설치 시 https://python.org 에서 3.9 이상 버전 설치 안내함
Node.js 미설치 / v18 미만	`node --version` 확인 후 https://nodejs.org/ 에서 18 LTS 이상 설치 안내함
Gemini API Key 발급 필요	https://ai.google.dev/ 에서 Google 계정으로 로그인 후 API 키 발급 안내함
`GEMINI_API_KEY` 오류 (401/403)	키 값 오타 확인 및 `gateway/tools/.env` 파일 내 `GEMINI_API_KEY=<값>` 형식 점검 안내함
`node -e "require('pptxgenjs')"` 오류	pptxgenjs 미설치
`/ppt-writer` 실행 시 `Cannot find module 'pptxgenjs'`	`gateway/` 등 하위 디렉토리에 설치됨 (Node 해석 경로 밖) — 플러그인 루트로 재설치: `cd "$PLUGIN_DIR" && npm install pptxgenjs`
CLAUDE.md 쓰기 권한 오류	해당 파일 권한(`chmod 644` 또는 Windows ACL) 확인 및 수동 등록 방법 안내함
WebFetch 접근 불가	Anthropic 최신 모델 목록(https://docs.anthropic.com/en/docs/about-claude/models) 수동 확인 후 직접 입력 요청함

MUST 규칙

#	규칙
1	`disable-model-invocation` 설정 금지 — 설정 시 스킬 로드 자체가 불가함
2	모델명은 항상 Anthropic 공식 최신 버전을 반영해야 함
3	AskUserQuestion 없이 사용자 선택을 임의 결정하지 않음

검증

각 Step 완료 증거:

Step	완료 증거
Step 1	`./AGENTS.md` 내 4개 변수(`AI_RUNTIME`·`DMAP_PLUGIN_DIR`·`PLUGIN_DIR`·`PLUGIN_NAME`) 존재 확인 (Read 도구 출력)
Step 2	`gateway/runtime-mapping.yaml` diff — 4런타임 변경 전/후 모델명 출력 (갱신 선택 시)
Step 2.5	`.claude/agents/.md`, `.cursor/agents/.md`, `.codex/agents/.toml`, `.antigravity/agents/.md` frontmatter `model:` 필드가 runtime-mapping.yaml 값과 일치
Step 3-A	`python gateway/tools/generate_image.py --help` 정상 출력 (설치 선택 시)
Step 3-B	`cd "$PLUGIN_DIR/out" && node -e "require('pptxgenjs')"` 정상 종료(exit 0)
Step 4	대상 파일(AGENTS.md 또는 ~/.claude/CLAUDE.md) 내 `## finops 플러그인` 섹션 존재 확인 (Read 도구 출력)
Step 5	체크리스트 출력 및 다음 단계 안내 완료

setup

Mais deste repositório

Mais deste repositório

Setup

목표

활성화 조건

워크플로우

Step 1: 플러그인 변수 확인 (ulw 활용)

Step 2: 런타임 최신 모델 버전 확인 (ulw 활용)

Step 2.5: 런타임 어댑터 frontmatter 일괄 갱신 (ulw 활용)

Step 3-A: generate_image 도구 설치 (ulw 활용)

Step 3-B: DMAP Office 빌더 런타임(pptxgenjs) 설치 (ulw 활용)

3-B-1. 사전 런타임 확인

3-B-2. pptxgenjs 설치 검증·설치

3-B-3. 실사용 CWD 해석 검증

Step 4: 라우팅 테이블 등록 (ulw 활용)

Step 5: 설치 결과 요약 보고 (ulw 활용)

사용자 상호작용

스킬 위임

문제 해결

MUST 규칙

검증

Setup

목표

활성화 조건

워크플로우

Step 1: 플러그인 변수 확인 (ulw 활용)

Step 2: 런타임 최신 모델 버전 확인 (ulw 활용)

Step 2.5: 런타임 어댑터 frontmatter 일괄 갱신 (ulw 활용)

Step 3-A: generate_image 도구 설치 (ulw 활용)

Step 3-B: DMAP Office 빌더 런타임(pptxgenjs) 설치 (ulw 활용)

3-B-1. 사전 런타임 확인

3-B-2. pptxgenjs 설치 검증·설치

3-B-3. 실사용 CWD 해석 검증

Step 4: 라우팅 테이블 등록 (ulw 활용)

Step 5: 설치 결과 요약 보고 (ulw 활용)

사용자 상호작용

스킬 위임

문제 해결

MUST 규칙

검증

Step 1: 플러그인 변수 확인 (`ulw` 활용)

Step 2: 런타임 최신 모델 버전 확인 (`ulw` 활용)

Step 2.5: 런타임 어댑터 frontmatter 일괄 갱신 (`ulw` 활용)

Step 3-A: generate_image 도구 설치 (`ulw` 활용)

Step 3-B: DMAP Office 빌더 런타임(`pptxgenjs`) 설치 (`ulw` 활용)

Step 4: 라우팅 테이블 등록 (`ulw` 활용)

Step 5: 설치 결과 요약 보고 (`ulw` 활용)

Step 1: 플러그인 변수 확인 (`ulw` 활용)

Step 2: 런타임 최신 모델 버전 확인 (`ulw` 활용)

Step 2.5: 런타임 어댑터 frontmatter 일괄 갱신 (`ulw` 활용)

Step 3-A: generate_image 도구 설치 (`ulw` 활용)

Step 3-B: DMAP Office 빌더 런타임(`pptxgenjs`) 설치 (`ulw` 활용)

Step 4: 라우팅 테이블 등록 (`ulw` 활용)

Step 5: 설치 결과 요약 보고 (`ulw` 활용)