@henry1981/presentation-plugin

KHC presentation harness — Claude Code plugin for gated chunk-based deck production with 9-stage workflow.

Install

External users (via marketplace):

/plugin marketplace add henry-1981/context-first-harness
/plugin install presentation@khc-marketplace

Local development (clone):

git clone https://github.com/henry-1981/KHC.git
claude --plugin-dir /path/to/KHC/plugins/presentation

Lazy Dependencies (v0.2.3+)

본 plugin은 무거운 native dependency 두 개를 lazy install 방식으로 처리합니다. 첫 설치 분량을 약 45MB 수준으로 줄여 macOS·Windows 양쪽의 npm install ENOTEMPTY rmdir 실패 위험을 줄였습니다.

| Dependency | 트리거 | 동작 | |---|---|---| | [email protected] (≈14.5MB + chromium ~92MB) | html→pptx 변환·web-ppt bundle·chunk visual checkpoint 흐름 진입 | runtime 자동 install (plugin root cwd, npm install [email protected] --no-save) — 첫 호출 후 npx playwright install chromium도 한 번 실행 필요 | | @anthropic-ai/[email protected] (≈7.6MB) | 사용자 명시 Vision review 호출 시 | runtime 자동 install |

두 dependency는 plugin root의 node_modules/에 install되며 사용자 프로젝트 install에는 영향을 주지 않습니다. 첫 흐름 진입 시 stderr에 [presentation] installing optional dependency ... 한 줄이 출력됩니다.

오프라인 환경에서 위 흐름이 필요하면 plugin 설치 직후 다음 명령으로 사전 install 가능합니다:

cd ~/.claude/plugins/cache/<marketplace>/presentation/0.2.3
npm install [email protected] @anthropic-ai/[email protected] --no-save
npx playwright install chromium

Public Skills

External invoke namespace: /presentation:<skill-name>. Plugin loader generates namespace from manifest name + skill folder.

| Skill | Stage / Role | |---|---| | prd | Presentation Requirements Document — 발표 목적·청중·핵심 메시지 정의 | | research | Research gap analysis — PRD 본문 기반 부족 자료 식별 + 외부 dispatch | | message | Message architecture — 핵심 메시지 트리·논리 구조 | | storyboard | Storyboard — 슬라이드 흐름·전환 시나리오 | | design-contract | Design contract — 비주얼 시스템·디자인 토큰 정의 | | design-sample | Design sample — 디자인 contract 검증용 sample slide | | chunk | Chunk production — slide 단위 본문·디자인 생성 | | integrate | Integration review — chunk 통합 + 일관성 검증 | | review | Review — 최종 검토 + 수정 dispatch | | run | Router — 9 stage 흐름 자동 진입 |

사용 가이드: skills/run/reference.md — /presentation:run 진입 후 사용 흐름·분기·문제 대응을 한 자리에 모은 가이드입니다.

Utility Skills

| Skill | Role | |---|---| | template-copy | Reference design source extraction — 기존 HTML/WebPPT/PDF/PPTX/PNG 레퍼런스를 base-templates/templates-slide-{source-id}/로 복제하고, 그 evidence에서 reusable Archetype DESIGN.md seed를 base-templates/references/archetypes/{source-id}/에 추출 |

template-copy는 9-stage production chain에 포함되지 않고 Stage 8 progressive chunk visual loop와도 분리된 독립 utility skill이다. 추출된 Archetype DESIGN.md seed는 Stage 6 design-contract에서 design_source_mode = reference-extracted로 선택해 Deck DESIGN.md draft를 만든다. copied template HTML은 evidence/example이며 chunk가 직접 베끼는 source-of-truth가 아니다.

Stage / State / Gate / Final Bundle Contract

본 plugin은 gated chunk-based workflow를 구현:

• 9 stage linear chain (prd → research → message → storyboard → deck_design → design_sample → chunk_production → integration_review → final_bundle)
• stage gate: 각 stage 진입 직전 HB approve/revise/override 결정 의무. gate event는 state.json에 immutable 기록.
• state: presentation state 단일 JSON file 영구 저장. core function이 read·mutate·write.
• final_bundle: chunk artifacts 통합 + PPTX 또는 WebPPT format으로 output. mode = ready (모든 gate approved) 또는 draft_fast_path (override 허용).

CLI 단일 진입점: ${CLAUDE_PLUGIN_ROOT}/scripts/runtime-cli.mjs (subcommand 패턴 + JSON I/O contract).

Dependency / Preflight

Plugin install 시 Claude Code marketplace가 cache(ROOT) 영역에 node_modules + dist 자동 배치 — 별도 npm install step 의무 X.

Chromium 설치는 첫 사용 시 setup wizard(/presentation:setup)에서 처리:

1. 사용자가 /presentation:prd 등 stage skill 첫 호출 → config 부재 감지 → setup wizard 자동 진입
2. Wizard가 작업 공간 위치 입력 받음 + Chromium 부재 시 npx playwright install chromium 실행
3. Config 저장 (${CLAUDE_PLUGIN_DATA}/config.json) + 원래 skill 진입

사용자가 직접 /presentation:setup 호출해 설정 변경도 가능.

Legacy Migration Map

KHC monorepo 내부 사용자 migration (cycle 4-A~4-E ship 완료):

| 이전 위치 | 현재 위치 | |---|---| | tools/presentation/.claude/skills/presentation/{name}/ | plugins/presentation/skills/{name}/ | | tools/presentation/.claude/agents/{name}.md | plugins/presentation/agents/{name}.md | | tools/presentation/CLAUDE.md | docs/presentation/_archive/legacy-md/CLAUDE.md | | Legacy alias plan·design·export | 폐기 — 9 stage skill + run router로 단일화 |

Troubleshooting

Setup wizard 진입 안 됨

• /plugin list 실행해 presentation@khc-marketplace 등재 확인
• /presentation:setup 직접 호출로 wizard 진입 시도
• Playwright Chromium 다운로드 fail 시 npx playwright install chromium 수동 실행

config 파일 위치

• ${CLAUDE_PLUGIN_DATA}/config.json — Claude Code plugin이 자동 관리
• 변경 시 /presentation:setup 재호출 또는 node ${CLAUDE_PLUGIN_ROOT}/scripts/runtime-cli.mjs config set --field workspace_path --value <new-path>

/presentation:<skill> invoke 안 됨

• /plugin list 실행해 presentation@khc-marketplace 등재 확인
• /plugin marketplace update 후 재시도

Adapter Coexistence (Claude Code + Codex)

본 plugin은 양 adapter 양립:

• Claude Code adapter: .claude-plugin/plugin.json manifest + skills/·agents/·hooks/·scripts/ 표준 디렉터리
• Codex adapter: .codex-plugin/ (Codex 자체 plugin spec, KHC monorepo 영역)

각 adapter는 자기 manifest만 로드. src/ 19 module은 양 adapter 공통 import 영역.

License

MIT — LICENSE 파일 참조.

Source

• Plugin source: https://github.com/henry-1981/KHC/tree/main/plugins/presentation
• Marketplace catalog: https://github.com/henry-1981/context-first-harness/blob/main/.claude-plugin/marketplace.json
• npm registry: @henry1981/presentation-plugin