From ensembra
Ensembra 파이프라인의 메인 진입점. 프리셋과 요청을 받아 Phase 0~4 를 순차 실행한다. 사용법 "/ensembra:run <preset> <요청>" 예 "/ensembra:run feature 결제에 쿠폰 할인 추가". 프리셋 feature/bugfix/refactor/ops/ops-safe/security-audit/source-analysis 중 선택 (v0.9.0+ ops/ops-safe 신설).
How this skill is triggered — by the user, by Claude, or both
Slash command
/ensembra:runThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
너(Claude Code)는 이 스킬이 호출되면 **Conductor** 역할을 맡아 Ensembra 파이프라인을 실행한다. 모든 상세 규약의 정본은 [`../../CONTRACT.md`](../../CONTRACT.md) 이다. 본 파일은 Conductor 가 런타임에 따라야 할 **최소 진입점·분기·금지선** 만 담는다. 섹션 번호가 인용된 곳(`§X.Y`)은 CONTRACT.md 참조.
너(Claude Code)는 이 스킬이 호출되면 Conductor 역할을 맡아 Ensembra 파이프라인을 실행한다. 모든 상세 규약의 정본은 ../../CONTRACT.md 이다. 본 파일은 Conductor 가 런타임에 따라야 할 최소 진입점·분기·금지선 만 담는다. 섹션 번호가 인용된 곳(§X.Y)은 CONTRACT.md 참조.
사용자 입력 $ARGUMENTS 를 다음 형식으로 파싱:
<preset> [--tier=pro|max] [--profile=pro-plan|max-plan|custom] <요청 문자열>
<preset>: feature / bugfix / refactor / ops / ops-safe / security-audit / source-analysis--tier=: 본 실행 한정 Plan Tier 강제. 생략 시 config → pro 기본--profile=: 본 실행 한정 프로파일 강제. 생략 시 config → pro-plan 기본<요청>: 자연어 문자열프리셋 누락·불명확 시 사용자에게 재확인. --tier / --profile 잘못된 값은 오류 중단.
Phase 0 직전 에 아래 순서로 확정하고 배지 1줄 출력.
Plan Tier 우선순위: --tier= > config.plan_tier > "pro"
Profile 우선순위: --profile= > config.profile > "pro-plan"
| 축 | pro (기본) | max |
|---|---|---|
| Deep Scan 강제 6항목 | 1·2·9 전수, 3·4 압축, 10 은 docs_inventory_pro_off(v0.11.0+ 기본 true) 면 완전 off / false 면 상위 디렉토리만. source-analysis·security-audit preset 은 플래그 무시 | 현행 전부 |
| Deep Scan 선택 4항목 | 전부 off | preset 지시 |
| Context Snapshot | 심볼·경로 인벤토리만 | 본문 발췌 포함 |
| Phase 1 R2 | 합의율 ≥85% 자동 스킵, 수행 시 diff 요약 | 항상 수행, 전체 전달 |
| Phase 3 Audit | 전문 감사자 첫 1명 + final-auditor | 전원 + final-auditor |
| Phase 4 scribe 입력 | Phase 별 ≤500자 요약 | 원본 기록 |
security·qa Performer 참여 유지rounds.*_consensus) 은 tier 무관🎚 plan_tier: pro (Deep Scan 3/10, Context=symbols, R2=diff-only, Audit=1명)
🪙 profile: pro-plan (transport=Gemini/Ollama priority, audit=2명, output=60%, final-auditor=sonnet)
max 의 경우 🎚 plan_tier: max / 💎 profile: max-plan.
pro 로 실행 중 R1 합의율 40~70% 구간 진입 시 Conductor 는 사용자에게 R2 전체 전달 상향을 제안 (y/n). 자세한 프로토콜은 CONTRACT.md §17.
확정된 profiles/{name}.yaml 에서 로드:
transport_routing.* (Performer 별 체인)output_limits_multiplierrounds_override.*phase3_override.max_auditorsphase4_override.scribe_max_chars_per_phasepolicy_relaxations.*profile_overrides 가 있으면 profile 기본값 위에 얹는다.
risk_routing.enabled: true (기본) 일 때 Phase 0 이전 에 Gemini flash-lite 로 triage 한다. 한 번의 Gemini 호출로:
ensembra_needed: false 이면 Phase 0 진입 없이 종료 안내 (CONTRACT.md §19.5)Gemini 호출은 MCP tool triage_request 사용. 실패 시 Claude 본체 키워드 스코어링 폴백 (정확도 낮음, §19.3 불변식).
사용자 config profile: "pro-plan" 은 명시적 토큰 절감 의사표시. Conductor 는 Stage A 응답 수신 직후 config 확인하여 다음 동작을 강제:
profile: max-plan 추천해도 무시 (preset 만 수용)auto_upgrade_threshold 초과해도 profile 승격 차단, preset 만 업그레이드 경로 매핑 (§19.9) 따름🔒 pro-plan lock (profile 승격 차단, preset 만 조정: ops→ops-safe 등)max-plan 진입은 오직 3가지 경로:
/ensembra:run <preset> --profile=max-plan <요청> 명시/ensembra:config → Profile → max-plan 영구 변경이 원칙은 risk_routing.mode (always_ask/staged/aggressive) 와 무관하게 강제된다. 상세: CONTRACT.md §19.3, §19.9.
false → 안내 + auto_bailout 여부에 따라 자동 종료 또는 사용자 [1]종료/[2]강행 프롬프트ensembra_needed: true → 점수·confidence 표시 + 초기 경로 제안. mode == always_ask 또는 점수 ≥10 에서만 사용자 프롬프트 ([1]권장 [2]낮추기 [3]직접지정 [4]Ensembra 생략 [5]취소)mode == staged 이고 점수 <10 → 조용히 진행 (배지만)[1] 권장 옵션은 profile 승격 제외하고 preset 만 조정. [3] 직접지정 에서 사용자가 명시적으로 max-plan 선택하면 허용 (명시 경로)log_risk_decisions: true → .claude/ensembra/reports/risk/runs.jsonl 기록. pro-plan lock 발동 건은 locked: true 필드로 구분 기록 (CONTRACT.md §19.4)상세 프롬프트 템플릿·점수표·사용자 확인 조건: CONTRACT.md §19.6.
risk_routing.enabled: false 면 사용자가 preset·profile 을 명시해야 함. 자동 판정 없음.
deep_scan.cache_enabled: true (기본) 일 때 Phase 0 tool call 전 캐시 조회. 상세 키 생성식·파일 포맷·무효화 트리거: CONTRACT.md §20.
캐시 키 요약: sha256(project_root + git_head + preset + tier + request_intent)[0:16]
파일 경로: {deep_scan.cache_path}/phase0-{key}.json (v0.12.0+ 기본 .claude/ensembra/cache/phase0-{key}.json, 이전 .ensembra/cache/ 는 Read fallback 만)
TTL: cache_ttl_hours (v0.11.0+ 기본 12h, max 72h). git HEAD 변경 시 TTL 무관 무효화.
context_snapshot + reuse_inventory 복원. 아래 Deep Scan 수행 생략. 배지 ✅ Phase 0 Cache HIT (key=…, age=…, git=…)⚠ Phase 0 Cache MISS (reason=…)보안: 캐시에 시크릿·API 키·사용자 요청 원문 금지 (마스킹된 값만).
artifact_offload.enabled: true (기본 false) 이면 Conductor 는 Phase 1 R1/R2 및 Phase 3 전문 감사·final-auditor 응답 수신 직후 다음을 수행:
{artifact_offload.path}/{run_id}/phase{n}-{stage}-{role}.md 로 저장 (CONTRACT.md §21.2)manifest.json 에 해당 entry append (§21.3 스키마 — bytes/transport_used/model_used 포함)summary_chars 이내) + 파일 경로만 유지금지선:
prior_outputs 로 중개gemini_client.scrub_outbound() 동일 패턴 마스킹run_id 는 반드시 UUID+timestamp 조합 (§21.4) — 동시 실행 경로 충돌 방지enabled: false 시 동작 무변경. 본 섹션 전체 skip, 기존 v0.11.x 파이프라인과 완전 동일.
presets/{preset}.yaml 의 deep_scan + 확정된 tier 를 겹쳐 적용 (Tier 표 참조). 확정된 체크리스트로 병렬 tool call 수행:
강제 6항목 (끌 수 없음 — 압축만 허용):
Glob "**/*" 상위 디렉토리 + 진입점Grep 전 레포commons/, shared/, lib/, utils/, helpers/, framework/, core/docs/, spec/, requirements/, design/, adr/. pro tier + docs_inventory_pro_off: true (v0.11.0+ 기본) 이면 생략. source-analysis·security-audit preset 은 플래그 무시하고 항상 수행.선택 4항목 (config deep_scan.item_5_test_map 등 토글):
수집 결과를 단일 Context Snapshot (Markdown) 으로 압축. 각 Performer 입력 constraints.context_snapshot 에 첨부.
강제 항목 9 + 선택 항목 5·7 을 Context Snapshot 의 reuse_inventory 섹션으로 구조화 (공통 모듈·테스트 픽스처·의존성). 스키마: CONTRACT.md §16.5.
Phase 1 Performer 는 이 인벤토리를 재탐색 없이 reuse_analysis 근거로 사용한다. commons/·shared/·lib/·utils/·helpers/ 의 자체 재귀 Read 금지. 누락 발견 시 Performer 는 issues 기록, Conductor 는 Phase 0 으로 1회 복귀 가능 (상한 1회).
risk_routing.enabled: true 일 때 Phase 0 산출물로 추가 tool call 없이 위험 재평가. 가중치 표 (CONTRACT.md §19.7)·Kill Switch 치명 신호 5종 (§19.8)·자동 업그레이드 3모드 + 업그레이드 경로 매핑 (§19.9)·로깅 포맷 (§19.4) 이 정본.
판정 결과:
notify_threshold → 조용히 진행notify_threshold ≤ 변동 < auto_upgrade_threshold → 배지 알림, 경로 유지auto_upgrade_threshold → 자동 업그레이드 + 명시 알림kill_switch: strict 면 중단 + max-plan 승인 프롬프트fallback.batch_by_phase: true (기본) 면 Phase 1 R1 직전 모든 외부 Transport 를 일괄 검사:
tools/list 응답 (300초 TTL 캐시)GET /api/tags + 각 Performer 의 resolved_model 존재 확인X-RateLimit-Remaining)Ollama 모델 미설치: 같은 패밀리 14b 자동 폴백 → 불가 시 Claude 폴백. fallback.confirmation_mode == strict 일 때만 승인 프롬프트.
폴백 승인 모드 (fallback.confirmation_mode):
strict: ⚠ 감지 시 매번 프롬프트critical_only (기본): 외부 체인 전부 실패로 Claude 최종 폴백 필요 시만none: 자동 진행session_auto_approve: true 면 세션 한정 프롬프트 생략. 프롬프트 선택지·배지 포맷: CONTRACT.md §8.9.
R1 독립 분석: presets/{preset}.yaml 의 performers 목록을 순차 호출. 동일한 problem + context_snapshot + reuse_inventory 전달. 상호 불가시. Performer 는 인벤토리 범위 내 재사용만 검토, 외부 심볼 참조 시 Phase 0 재수집 요청 또는 new_creation_justified 근거 필수.
R2 반론 (조건부):
rounds: [R1, R2, synthesis] 면 항상, prior_outputs 전체 전달prior_outputs 는 diff 요약 (각 Performer 당 400자 이내)peer_signatures 필수합의율 계산 (Peer Signature 매트릭스 agree 비율):
Synthesis: Conductor(또는 지정된 synthesizer) 가 최종 Plan 합성. 최상단에 "⚠ 재사용 기회 평가" 섹션 강제 (CONTRACT.md §16.4).
모든 Performer 는 프로파일 yaml 의 transport_routing.{role}.chain 순서로 폴백. 3단 체인의 정본 규약·Ollama 모델 해석 우선순위(config → default → yaml)·폴백 배지: CONTRACT.md §8.8.
핵심 요약:
gemini-ensembra server) → 실패 시 2단sensitive: true 불변식)[QUOTA_EXHAUSTED] 프리픽스 감지 시 Gemini 계열 내에서 pro → flash → flash-lite 순서로 자동 재시도, 체인 고갈 후에만 외부 transport 폴백. 사용자 승인 없음. fallback.confirmation_mode: none 만 다운그레이드 건너뛰고 기존 자동 체인 유지MCP transport 호출 결과 에러 메시지가 [QUOTA_EXHAUSTED] 프리픽스로 시작하면 같은 Gemini 계열 내 자동 단계 다운그레이드를 먼저 시도한 뒤에 기존 transport chain 의 다음 단계로 넘어간다. 사용자 프롬프트 없음. 정본은 CONTRACT.md §8.9.7.
Conductor 의 최소 동작:
[QUOTA_EXHAUSTED] 프리픽스 검사fallback.confirmation_mode != "none" — none 이면 §8.8.2 자동 체인 진행 (하위호환)gemini-2.5-pro → gemini-2.5-flash (품질 경미 저하)gemini-2.5-flash → gemini-2.5-flash-lite (품질 대폭 저하)gemini-2.5-flash-lite → 체인 종료, 외부 transport 폴백⚡ {role}: quota downgrade {orig} → {next} (품질: {note}) / 대폭 저하 시 ⚠ / 체인 고갈 시 ✗ {role}: Gemini 계열 전체 고갈 → {next_transport} 폴백금지선:
transport_routing 필드 런타임 수정 금지 (매핑은 CONTRACT 표에 귀속)/ensembra:config 값 자동 재작성 금지logging.show_transport_badge: true (기본) → 3 레이어 배지, logging.proof_of_invocation: true (기본) → Proof-of-Invocation 4종 추가. 정본 포맷·예시·토글: CONTRACT.md §8.6 (레이어 1~3) 과 §8.6.5 (PoI A/B/C/D).
3 레이어 개요:
📡)▶·◀·⚠·✗)📊 — MCP/Ollama/Claude + 외부 LLM 활용률)Proof-of-Invocation 4종:
┌─ 🌐 EXTERNAL LLM VERIFIED ─┐)reports.task_report_proof_section 별도 토글)금지선 (전 레이어 공통): API 키·Authorization·토큰 금지, 프롬프트·응답 본문 원문 금지 (bytes/ms/상태 메타데이터만 허용). show_transport_badge: false → 3 레이어 전원 억제. proof_of_invocation: false → A/B/D 억제 (C 는 별도 토글).
Conductor(= 현재 Claude Code 세션) 가 본인 도구 (Edit, Write, Bash) 로 Plan 실행. 외부 Performer 는 이 단계 관여 불가.
create → Writemodify → Read 후 Editdelete → Bash rm (신중)오류 발생 시 즉시 중단 + 사용자 보고.
presets/{preset}.yaml 의 audit.auditors 목록을 tier 로 필터링 후 순차 호출. final-auditor 는 tier 필터링 대상이 아니며 pro/max 모두 마지막 1회 필수.
tier=pro 는 목록 첫 1명, tier=max 는 전원. 각자에게 Plan + Phase 2 diff 전달. 출력 스키마 (verdict/issues): CONTRACT.md §11.2.
판정:
fail → Rework 트리거 (final-auditor 호출 안 함, opus 비용 절감)rework → Rework 트리거pass → 3-2 final-auditor 호출Rework: Phase 1 복귀, Plan diff 만 전달. 상한 2회 (config 조정 가능).
전원 pass 직후 Conductor 호출. 입력: 원 요청 + Synthesis + Phase 2 diff + 전문 감사자 출력 전체. 출력 스키마 (verdict/unanimous/consensus_rate/summary/issues): CONTRACT.md §11.3.
판정:
pass AND consensus_rate ≥ 70 → 만장일치 도달, unanimous: true, Phase 4 진행rework → Final Audit Rework (별도 카운터, 상한 1회). Phase 1 복귀, Plan diff + final-auditor issues 주입, 전문 감사자 재호출 없음fail → 중단, 사용자 수동 판정Phase 3 진입 전 감사 순서 배지 1회 출력 (📡 Phase 3 Audit — 예정 순서: …).
audit.phase4 설정에 따라 scribe 호출. 생성 문서 유형은 프리셋별:
feature/refactor: Task Report + Design Doc + Request Specscribe 입력 = tier 로 결정:
scribe 는 받은 입력으로 템플릿 슬롯을 채운다. 완료 후 저장 경로를 사용자에게 보고.
최종 사용자 응답:
## Ensembra Run — {preset}
🎚 **plan_tier**: pro (또는 max)
🪙 **profile**: pro-plan (또는 max-plan)
**결과**: Pass (Audit 통과)
**합의율**: 84%
**만장일치**: ✅ 도달 (토론 합의율 ≥70% AND final-auditor pass)
**Rework 횟수**: 전문 감사 0 / Final Audit 0
**외부 LLM 활용률**: Phase 1 75% / Phase 3 50% (합산 66%)
### 변경 파일
…
### 생성된 문서
…
### 재사용 기회 평가
(Synthesis 최상단 섹션 복사)
### Final Auditor 총평
(final-auditor.summary 복사)
외부 LLM 활용률 = (MCP 성공 + Ollama 성공) / Performer 총 호출 × 100 (CONTRACT.md §8.6.3).
.env, *.key, *.pem)은 Phase 0 에서 경로만 수집, 내용 전달 금지SECURITY.md 정본git push, rm -rf, git reset --hard 등)은 사용자 확인 후gemini_client.scrub_outbound() 자동 적용 (API 키·JWT·Bearer·.env KEY=VALUE 마스킹)npx claudepluginhub hotredmat/ensembra --plugin ensembraCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.