jarvis

name

jarvis

description

Meta-orchestrator that decomposes user goals into agent execution plans with model routing and dependency ordering, optionally pursuing them via Goal Mode with pursuing/paused/achieved/unmet/budget-limited lifecycle states. Maintains a persistent TODO backlog under state/todos/. Pipeline Mode auto-triggers for registered pipelines (report, persona, deep-research, research-report) and executes immediately. Use when: "jarvis", "자비스", "plan how to do X", "decompose this goal", "goal mode", "목표 모드", "pursue this until done", "jarvis goal", "jarvis plan", "자비스 계획", "자비스 목표", "long-running objective", "multi-turn goal", "멀티턴 목표", "장기 목표", "계획 세워줘", "jarvis todo", "자비스 TODO", "보고서 작성해줘", "리포트 만들어줘", "보고서 생성", "분석 보고서", "슬랙에 리포트 보고", "슬랙에 보고서 공유", "리서치해서 슬랙에 보고", "페르소나 분석", "관점 분석해줘", "관점 분석", "딥 리서치", "리서치해서 보고서로". Do NOT use for a single known skill (invoke directly), simple edits, or one-shot tasks. Do NOT use for daily pipeline (use today). Do NOT use for "딥 리서치" without "보고서" → use deep-research-pipeline.

Jarvis — Meta-Orchestrator for Claude Code

Decompose → Search → Classify → Plan → (optionally) Pursue.

---

Layer 0: Context Pre-flight (READ THIS FIRST every turn)

When the user's request touches git, GitHub, issues, Project #5, repos, or the user's working environment, immediately load:

• references/user-environment.md — user profile, working directories, all 5 managed repos, Project #5 IDs, default field values, decision trees for repo/issue ambiguity, and gotchas seen in production (e.g., ThakiCloud/ai-platform-strategy doesn't exist; date fields need --date not --text).

This single file prevents most disambiguation back-and-forth. Read it eagerly — it's <300 lines.

Other references to load on-demand:

• commit-to-issue/references/project-config.md — full Project #5 field IDs, GraphQL queries, set_all_fields() helper. Mandatory for any issue-creation work.
• eod-ship/references/managed-repos.md — the 5 repos EOD-ship iterates over.
• domain-commit/references/hooks-and-domains.md — domain→path mapping and pre-commit hook recovery.

---

Layer 0.5: APS Operating-System Skill Family (이 repo의 하네스/자동화 자체를 다룰 때)

작업이 이 repo의 운영체제 자체 — 에이전트 하네스, 무인 자동화 플릿(launchd/loops/signals), 스킬 진화 루프, 하네스 설정·환경·문서·검증 — 에 관한 것이면, 개별 스킬을 흩어 찾지 말고 aps-* 패밀리(16개) 로 라우팅한다. retrieve.py가 이미 자동 색인하므로 발견은 자동이지만, 아래 표로 *어느 aps- 인지**를 결정론적으로 고른다. (일반 제품/도메인 작업은 해당 없음 — 기존 Pipeline/Search 로직 사용. 단발 편집·grep·단순 Q&A는 native, [[sra-incorporation-guard]].)

의도 신호	스킬
변경을 분류/게이트/롤백, 커밋·푸시·서브모듈 범프, "자동화 깨지면 안 됨"	aps-change-control
스케줄 잡 실패/이중발화/401/Slack·MCP·서브모듈·env 장애 트리아지	aps-debugging-playbook
"예전에 이런 적?", "왜 이렇게 되어 있어", 죽은 브랜치 부활, 결정 재론	aps-failure-archaeology
"왜 이 구조냐", 불변식, 약점, 바꿔도 되나	aps-architecture-contract
루프/검색/모델경제/캐시/검증 이론	aps-agent-harness-reference
model policy·훅 배선·plist·contracts·env-parity·머신레지스트리 읽기/수정/추가	aps-config-and-flags
새 맥북 세팅, venv·서브모듈·헤드리스 인증 재구축	aps-build-and-env
러너 실행/launchd 라이프사이클/신호버스/outputs 컨벤션/듀얼머신	aps-run-and-operate
측정(레지스트리 --check, pending 신호, fail streak, 라우터 벤치, 비용)	aps-diagnostics-and-tooling
무엇이 증거인가, 임계값, 골든셋, 벤치/회귀/게이트 추가	aps-validation-and-qa
기록 문서·룰/스킬 작성 규칙·하우스 스타일·렌더 파이프라인	aps-docs-and-writing
공개 전 주장 검증, 블로그/릴리스, 신규성·재현성	aps-external-positioning
플릿 신뢰성·스킬진화 캠페인(만성 실패·열린 루프·벤치 개선)	aps-automation-reliability-campaign
주장 증명: A/B·전후 벤치·ablation·비용 포렌식·반증	aps-proof-and-analysis-toolkit
다음 연구 주제, beyond-SOTA, 반증가능 마일스톤	aps-research-frontier
도입할까·증거 기준·가설·아이디어 수명주기·실험 프로토콜	aps-research-methodology

*불변식 (aps- 라우팅 시)**:

• 라이브 러너/plist/훅/생성파일을 바꾸는 작업은 실행 전 aps-change-control 게이트를 거친다. 제1조 = 동작하던 자동화를 깨지 마라. Jarvis Safety Gates·[[close-the-agent-loop]]와 정합.
• 캠페인(aps-automation-reliability-campaign)은 Pipeline이 아니다 — 자동 발화하지 않는다. 다주 결정-게이트 작전이므로 Plan/Goal로 진입해 수치 게이트로만 승격한다.
• aps-* 는 이 repo 운영체제 전용. ThakiCloud 제품 코드(Go/K8s 서브모듈)는 참조만 ([[thaki-platform-repos]] 라우터) — aps-* 로 라우팅하지 않는다.

---

Layer 1: 직무 정의 (Job Definition)

Dimension	Answer
Problem	복잡한 목표를 받았을 때, 어떤 스킬을 어떤 순서로 조합해야 하는지 결정하는 것
User	1인 AI 엔지니어가 1000+ 스킬 생태계를 효과적으로 활용해야 하는 상황
Success	(1) 계획의 스킬 매칭 정확도 ≥ 80%, (2) Goal Mode 달성률 ≥ 70%, (3) 사용자가 계획 수정 없이 승인하는 비율 ≥ 60%
Non-Goal	단일 스킬로 해결 가능한 작업 실행, 코드 직접 작성, 일상 파이프라인 운영

---

Layer 3: 모델 선택 전략 (Model Selection & Fallback)

Routing Table (Claude Code 환경)

Claude Code는 세션 기본 모델(Sonnet)을 사용하며, subagent 생성 시 --model 플래그로 다른 모델을 지정한다.

Task Type	Model	Rationale
Exploration / file reading	haiku (via --model haiku)	낮은 비용, 높은 처리량
Implementation / code gen	(세션 기본 = Sonnet)	균형 잡힌 품질-비용 비율
Architecture / multi-step reasoning	opus (via --model opus)	복잡한 의존성 분석에 필요
Subagent quick lookup	haiku	read-only 작업
Goal Mode iteration	(세션 기본)	비용-품질 밸런스
Consolidation	haiku → 세션 기본 escalation	단순 패턴 추출 → 복잡 분석

Claude Code 모델 지정 방법:

• 세션 기본 모델: 별도 지정 불필요 (현재 세션의 모델)
• 하위 에이전트: claude --model opus "task" 또는 claude --model haiku "task"
• MCP 서버: Claude Code subagent에서는 MCP 서버 접근 불가 (메인 에이전트만 사용)

Fallback Chain

Primary Model (selected by task)
  ↓ timeout/rate-limit/error
Fallback 1: retry with backoff (같은 모델)
  ↓ 3 consecutive failures
Fallback 2: downgrade (opus → 세션 기본 → haiku)
  ↓ all tiers unavailable
Circuit Break: pause + notify user

---

Layer 4: 런타임 루프 — PTAO Cycle

모든 Jarvis 실행은 Perceive-Think-Act-Observe 루프를 따른다.

Phase Definitions

Phase	Mapping	Inputs	Outputs
Perceive	사용자 입력 + 메모리 로드	user query, goal state, MemKraft	정제된 context
Think	LLM reasoning + plan gen	context + agent registry	실행 계획
Act	도구 호출 또는 subagent dispatch	plan step + skill	실행 결과
Observe	결과 검증 + exit check	output + criteria	continue/stop

Exit Conditions

Condition	Trigger	Action
Success	모든 criteria 통과	status → achieved
Budget Exhausted	consumed > budget	status → budget-limited
Deadline	current_time > deadline	status → budget-limited
Stall	동일 action 3회 반복	pause + 사용자 개입 요청
User Interrupt	"stop" / "pause" 명시	status → paused
Error	모든 fallback 소진	status → unmet
Context Window Pressure	컨텍스트 윈도우 80%+ 소진 감지	진행 상황 요약 저장 + 계속 진행 제안 (handoff brief 생성)

---

Layer 5: 메모리 전략

Short-Term (세션 내)

Source	Purpose	Access
Goal state JSON	목표 반복 기록	state/goals/<id>.json
TODO backlog	작업 대기열	state/todos/*.md
Current plan	승인된 계획	context window

Long-Term (세션 간)

Source	Purpose	Access
MemKraft	과거 패턴, 선호	memkraft-ingest / ai-recall
Plan archive	계획 이력	outputs/jarvis-plans/
Consolidation	자기 개선 결과	state/kb-intel-compile.log

---

Modes

Mode	Trigger	Behavior
Plan	jarvis plan <goal>	단일 응답: 번호 매겨진 계획. 실행 없음.
Pipeline	등록된 파이프라인 트리거 감지	Pipeline Registry 매칭 → 즉시 실행. 계획 출력 없음.
Goal	jarvis goal <objective>	Multi-turn 추적. State 유지.
TODO	`jarvis todo [add	list
Consolidation	jarvis consolidate	야간 자기 개선 사이클

Mode 결정 순서: Pipeline Registry 매칭 → sub-command 파싱 → Default (Plan Mode).

---

Pipeline Registry

등록된 파이프라인은 Plan Mode를 건너뛰고 즉시 실행한다. 사용자 입력이 아래 트리거 패턴에 매칭되면 해당 파이프라인의 스킬 체인을 순차 실행한다.

Intent Matching

사용자 입력 도착
  │
  ▼
[1] Pipeline Registry 트리거 매칭 (정확 키워드 우선)
  │── 매칭 → Pipeline Mode 진입, 즉시 실행
  │── 미매칭 → 기존 Mode 결정 로직 (Plan/Goal/TODO)

트리거 충돌 방지 규칙:

• 정확 키워드 매칭 우선 (부분 매칭 < 정확 매칭)
• 하나의 입력에 여러 파이프라인 매칭 시: 가장 구체적인 것 선택
• 모호하면 사용자에게 1회 확인 ("보고서 파이프라인으로 실행할까요?")

등록 파이프라인

---

report — 보고서 생성 파이프라인 (리서치 + 분석 + 팩트체크 + 배포)

항목	값
트리거	"보고서 작성해줘", "리포트 만들어줘", "보고서 생성", "report 작성", "분석 보고서 만들어줘", "슬랙에 리포트 보고", "슬랙에 리포트 올려줘", "슬랙에 보고서 공유", "리서치해서 슬랙에 보고"
스킬 체인	Research → Analysis → Fact-Check → DOCX Generate → Distribute(Drive 공개 + Slack)
출력	DOCX 파일 + Google Drive 링크(누구나 열람) + Slack #h-report 요약·링크 포스트

"슬랙에 리포트 보고" 표준 계약 (사용자 지시 2026-06-18): 리포트를 슬랙에 보고하라는 요청은 항상 (1) DOCX 생성 → (2) Google Drive 업로드 → (3) anyone-reader로 접근 공개(해제) → (4) Slack #h-report에 요약 + Drive 링크 게시. 마크다운 텍스트만 올리는 것은 보고 미완성. 업로드/공개는 검증된 gws drive +upload + gws drive permissions create 경로 사용(Phase 6 참조).

실행 단계:

Phase 1: Context — 주제/범위/깊이 결정
  │  사용자 입력에서 추출:
  │  - 보고서 주제 (필수)
  │  - 분석 깊이: quick(30분) / standard(1시간) / deep(2시간+)
  │  - 타겟 독자 (경영진/기술팀/투자자/일반)
  │  주제 불명확 시 1회만 질문
  ▼
Phase 2: Research — 정보 수집 (병렬)
  │  총동원 가능한 리서치 스킬:
  │
  │  [필수] WebSearch + WebFetch: 최신 뉴스, 시장 데이터, 경쟁사 동향
  │  [필수] unified-knowledge-search: 내부 KB(MemKraft, gbrain, Karpathy) 검색
  │  [선택] naver-news-search: 한국 시장/기업 관련 국내 뉴스
  │  [선택] hf-papers / alphaxiv-paper-lookup: 기술/AI 논문 기반 근거
  │  [선택] kb-search: 축적된 인텔리전스 검색
  │  [선택] last30days: 최근 30일 소셜 여론(Reddit/HN/YouTube/GitHub/Polymarket, 무키). 트렌드·반응·VoC 주제에 강함
  │         실행: .venv/bin/python .claude/skills/last30days/scripts/last30days.py "<topic>" --emit md
  │         (호스팅 LLM이 --plan JSON 작성해 넘기면 품질↑; bare 호출은 fallback)
  │  [선택] competitive-analyst: 경쟁사 분석 필요 시
  │  [선택] pm-market-research: 시장 규모/세분화 필요 시
  │
  │  주제별 리서치 소스 선택:
  │  - 기술/AI → WebSearch + hf-papers + kb-search
  │  - 시장/산업 → WebSearch + naver-news-search + competitive-analyst
  │  - 투자/재무 → WebSearch + naver-news-search + k-dart
  │  - 제품/서비스 → WebSearch + unified-knowledge-search + pm-market-research
  │
  │  Agent tool로 병렬 subagent 3-5개 동시 파견:
  │  각 subagent는 특정 소스 담당, 구조화된 결과 반환
  ▼
Phase 2.5: Source Integrity Gate — 날조 차단 (ARS 패턴 적용)
  │  ⛔ 날조/환각 소스는 분석 단계 진입 금지.
  │
  │  각 수집된 소스에 대해:
  │  1. URL 실존 확인: WebFetch로 실제 페이지 fetch — 404/error면 폐기
  │  2. 날짜 확인: 수집일로부터 18개월 이내인지 검증 (오래된 데이터 = 명시 또는 폐기)
  │  3. 저자/기관 확인: 주요 주장에서 저자명·기관명이 실제 존재하는지 WebSearch 확인
  │  4. 핵심 수치 확인: 통계/수치가 원본과 일치하는지 대조
  │
  │  통과 기준:
  │  - 소스 80% 이상 URL 실존 → 다음 단계
  │  - 50~79% → 경고 플래그 달고 진행 (분석에서 약한 근거 명시)
  │  - 50% 미만 → Phase 2로 되돌아가 추가 리서치
  │
  │  [SKIP 조건] quick 모드 or 사용자가 "빠르게" 명시 시 → 폐기만 수행, 확인 생략
  ▼
Phase 3: Analysis — 수집 데이터 분석 (순차)
  │
  │  [필수] 메인 에이전트에서 직접 분석:
  │  - 수집된 정보 종합 및 패턴 도출
  │  - 핵심 인사이트 3-5개 추출
  │  - 리스크/기회 식별
  │  - 데이터 기반 결론 도출
  │
  │  [선택] 전문 분석 스킬 호출 (주제에 따라):
  │  - 투자 → financial-report-analyzer, equity-research-agent
  │  - 시장 → competitive-analyst, pm-market-research
  │  - 기술 → codebase-archaeologist, system-thinker
  │  - 전략 → first-principles-analysis, second-order-thinker
  │
  │  분석 결과를 구조화된 마크다운으로 정리
  ▼
Phase 4: Fact-Check — 검증 (필수, Skill: fact-checker)
  │
  │  fact-checker 스킬 호출 (source-ranker + contradiction-finder + WebFetch 체인):
  │  1. 소스 신뢰도 평가: 모든 출처의 Credibility/Recency/Relevance 판정
  │  2. 모순 탐지: 소스 간 충돌, 약한 근거, 실제 논쟁점 도출
  │  3. 원본 대조: 핵심 주장 최대 5개를 WebFetch로 원본 확인
  │
  │  검증 결과 처리:
  │  - VERIFIED → 그대로 사용
  │  - PARTIALLY VERIFIED → "단일 소스 기반" 주석
  │  - INCORRECT → 원본 수치로 교정
  │  - UNVERIFIED → "미확인" 표기 또는 제거
  │
  │  최종 검증률 목표: 핵심 주장의 80% 이상 VERIFIED+PARTIALLY
  ▼
Phase 5: Generate — DOCX/PPTX 생성 (바이너리 산출물 필수)
  │  ⛔ 절대 규칙: "보고서 작성"의 최종 산출물은 렌더된 .docx 또는 .pptx 바이너리다.
  │     raw .md(마크다운 텍스트)를 최종 보고서로 배포 금지. .md는 중간 산출물일 뿐.
  │     마크다운만 올리고 링크 주는 것 = 보고서 미완성 = 실패.
  │
  │  ⛔ 모델이 generate_report.py를 매번 작성하지 않는다 — 데이터 JSON만 방출,
  │     커밋된 렌더러/템플릿이 포맷 소유([[docx-readability]]·[[sonnet-format-determinism]]).
  │
  │  보고서 유형별 라우팅 (커밋된 렌더러 사용):
  │
  │  ┌─────────────────────────────────────────────────────────────────────────────┐
  │  │ 유형                │ 모델 산출물                │ 렌더러 (커밋된 코드)     │
  │  ├─────────────────────────────────────────────────────────────────────────────┤
  │  │ 차트 없는 일반/리서치│ thaki-report-v1 슬롯 JSON  │ docx-template-engine     │
  │  │ (기업/전략 포함)    │                            │ (하단 호출법 참조)        │
  │  ├─────────────────────────────────────────────────────────────────────────────┤
  │  │ 차트 포함 보고서    │ report-data.json           │ scripts/skills/           │
  │  │ (일반/리서치)       │ (하단 스키마 참조)          │ jarvis_report_render.py  │
  │  │                     │                            │ (v2: 표지+목차+차트 자동) │
  │  ├─────────────────────────────────────────────────────────────────────────────┤
  │  │ 금융/투자 분석      │ analyst-report-docx 스키마 │ Skill: analyst-report-docx│
  │  ├─────────────────────────────────────────────────────────────────────────────┤
  │  │ 프레젠테이션        │ PPT 데이터                 │ references/deck-routing.md│
  │  │ ("PPT/덱/슬라이드") │                            │ 결정 트리로 스킬 선택     │
  │  └─────────────────────────────────────────────────────────────────────────────┘
  │
  │  ※ 마크다운 초안 → docx 직행 경로(파이프라인 밖 일반 요청)는
  │    scripts/md_to_branded_docx.py v2 (표지·목차·헤더/푸터·```chart 펜스 기본 지원,
  │    [[docx-readability]] 기본 경로).
  │
  │  --- 차트 없는 일반/리서치/기업/전략 → docx-template-engine ---
  │  모델이 방출할 JSON (thaki-report-v1 슬롯):
  │    { "template_id":"thaki-report-v1", "document_title":"...",
  │      "metadata":{"author":"ThakiCloud","department":"AI Platform","subtitle":"..."},
  │      "sections":[{"slot":"EXEC_SUMMARY","content":"..."},
  │                  {"slot":"SECTION_1_BODY","content":"..."},
  │                  {"slot":"SECTION_2_BODY","content":"..."}],
  │      "tables":[{"slot":"RISKS_TABLE","headers":[...],"rows":[[...]]}] }
  │  렌더 호출 (경로는 repo root 기준):
  │    python3 praxis/skills/anthropic/docx-template-engine/scripts/generate_docx.py \
  │      praxis/skills/anthropic/docx-template-engine/assets/templates/thaki-report-v1.docx \
  │      <spec.json> <output.docx>
  │    python3 praxis/skills/anthropic/docx-template-engine/scripts/validate_docx.py \
  │      <output.docx> \
  │      praxis/skills/anthropic/docx-template-engine/assets/placeholder-maps/thaki-report-v1.json
  │
  │  --- 차트 포함 보고서 → jarvis_report_render.py ---
  │  모델이 방출할 JSON (report-data.json 스키마):
  │    { "title":"...", "subtitle":"...", "date":"YYYY-MM-DD",
  │      "exec_summary":"...",
  │      "sections":[{"heading":"...","body":"...","bullets":["..."],
  │                   "table":{"headers":[...],"rows":[[...]]},
  │                   "chart":{...차트 스펙, 선택 — 섹션 인라인 배치...}}],
  │      "charts":[{"title":"...","kind":"bar|barh|line|area|pie","labels":[...],
  │                 "values":[...] 또는 "series":[{"name":"..","values":[..]}]}],
  │      "sources":[{"title":"...","url":"...","date":"..."}] }
  │  렌더 호출 (v2: 표지+목차+헤더/푸터+페이지번호 자동, 게이트 exit≠0 = 미완성):
  │    .venv/bin/python scripts/skills/jarvis_report_render.py report-data.json \
  │      --out outputs/{topic-slug}/{YYYY-MM-DD}-{title}.docx
  │
  │  - [OPTIONAL] 요약 영상 요청("영상으로", "요약 비디오", "MP4", "Shorts") → content-repurposing-engine-pro 채널 11
  │       (보고서 Executive Summary → 스크립트 → 한국어 ko_tts.sh 나레이션 → hyperframes render 9:16/16:9 MP4)
  │       ⚠️ 영상은 .docx 보고서를 대체하지 않는다. 항상 .docx 먼저 산출 후 추가 채널로만 생성.
  │
  │  보고서 필수 구성:
  │  - Executive Summary (1페이지)
  │  - 핵심 발견 사항 (bullet points)
  │  - 본문 분석 (섹션별)
  │  - 출처 및 참고자료 목록
  │  - (권장) 데이터 테이블 + matplotlib 차트 (analyst-report-docx 패턴)
  │
  │  출력: outputs/{topic-slug}/{YYYY-MM-DD}-{title}.docx  (+ charts/*.png)
  │  ✅ 게이트: ls -la 로 .docx 존재 + 파일크기 > 20KB 확인 후에만 Phase 6 진입
  ▼
Phase 6: Distribute — Drive 바이너리 업로드 + Slack 배포
  │  ⛔ 절대 규칙: Drive에는 .docx/.pptx 바이너리를 업로드한다.
  │     textContent로 마크다운 올리기 금지 (MCP create_file의 textContent는 .md/.txt용).
  │     → 바이너리는 googleapiclient(MediaFileUpload)로 직접 업로드해야 한다.
  │
  │  1. Google Drive 업로드 + 누구나 열람 공개 (검증된 우선 경로 = gws CLI, 2026-06-18 배선):
  │     # (a) 업로드 → file id 추출 (gws stdout "Using keyring backend" 헤더는 첫 '{'부터 파싱)
  │     gws drive +upload "<abs>.docx" --format json 2>/dev/null \
  │       | .venv/bin/python -c "import json,sys; t=sys.stdin.read(); i=t.find('{'); print(json.loads(t[i:])['id'])"
  │     # (b) 누구나(anyone) reader 권한 부여 — 접근 해제(공개) 필수
  │     gws drive permissions create --params '{"fileId":"<FID>"}' \
  │       --json '{"role":"reader","type":"anyone"}' --format json 2>/dev/null
  │     # (c) 링크 = https://drive.google.com/file/d/<FID>/view
  │     ✅ 게이트: permissions list에 {type:anyone,role:reader} 존재 확인. 업로드 mimeType이
  │        ...wordprocessingml.document(docx)인지 확인 — text/markdown·plain이면 실패로 간주, 재업로드.
  │     fallback 1: python3 .claude/skills/weekly-market-events-briefing/assets/upload_drive.py "<path>.docx"
  │        (env GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE 필요 — credentials.json 없으면 실패하니 gws 우선)
  │     fallback 2: MCP Google_Drive__create_file + base64Content(절대 textContent 아님) +
  │        contentMimeType=application/vnd.openxmlformats-officedocument.wordprocessingml.document
  │  2. Slack #h-report (C0AKHQWJBLZ) 포스트 — scripts/slack_post_message.py 사용(SLACK_USER_TOKEN, 본인 신원):
  │     - mrkdwn 포맷([[slack-post-formatting]]): *볼드* 1개별, <url|라벨> 링크, • 불릿, # 헤더 금지
  │     - 구성: 제목 + 날짜 / Executive Summary(3-5 bullet) / 핵심 시사점 / <Drive링크|열기>(누구나 열람)
  │  3. [OPTIONAL — 영상 요청 시] 요약 MP4 배포:
  │     - upload_drive.py "<path>.mp4" → Drive 링크 (mimeType video/mp4 확인)
  │     - Slack #h-report 같은 스레드에 "📹 요약 영상" 레이블 + Drive 링크 첨부
  │     - 영상 실패 시 graceful: .docx 배포는 그대로 완료, 영상만 누락 보고
  ▼
Phase 7: Confirm — 완료 보고 (산출물이 .docx 바이너리인지 최종 확인)
  │
  │  [OPTIONAL — "협업 품질 평가해줘" or "material passport" 요청 시]
  │  collaboration-quality-evaluator 스킬 호출:
  │  - 이번 보고서 생성 과정에서 사용자의 6차원 기여도 평가
  │  - Material Passport JSON 생성 → outputs/collaboration/ 저장
  │  - Slack #h-report 스레드에 품질 레이블 (HUMAN-LED/COLLABORATIVE/AI-GENERATED) 첨부

---

persona — 페르소나/관점 분석 파이프라인 (보고서와 별도)

항목	값
트리거	"페르소나 분석", "관점 분석해줘", "직무별 관점", "크로스롤 분석", "12개 관점으로 분석", "multi-perspective"
스킬 체인	role-dispatcher --mode=executive (경영진 12) 또는 agency-roster 인덱스에서 도메인 역할 선별 → 병렬 Agent 디스패치 → (선택) executive-briefing → Slack #효정-할일
출력	관점별 분석 마크다운 + CEO 종합 브리핑 + Slack 포스트

이 파이프라인은 보고서 생성 없이 분석만 수행한다. 보고서가 필요하면 report 파이프라인 사용.

역할 풀 선택 (멀티 관점 팀플의 핵심):

• 경영진 관점(CEO/CTO/CSO/PM/Sales/Security/UX/Dev/Finance/HR/DataSci/Trading) → role-dispatcher --mode=executive (Tier 2A, 12개)
• 세분 도메인 전문가(growth-hacker, brand-guardian, reality-checker, accessibility-auditor 등) → agency-roster 읽고 관련 agency-* 3-5개 선별 (Tier 2D, 69개)
• 병렬 실행: 1 메시지에 여러 Agent 호출, 각 subagent가 Skill: agency-{name} 페르소나 적용 후 구조화 마크다운 반환 (subagent-model-routing: 분석=sonnet)

---

deep-research — 딥 리서치 파이프라인 (보고서 없이 리서치만)

항목	값
트리거	"딥 리서치", "deep research", "종합 리서치", "깊이 조사해줘"
스킬 체인	199-deep-research or deep-research-pipeline (+ last30days로 최근 30일 소셜 여론 보강)
출력	인용 기반 리서치 결과 (마크다운, 배포 없음)

배포가 필요하면 "리서치해서 보고서로 만들어줘" → report 파이프라인으로 라우팅.

---

research-report — 리서치 보고서 (리서치 + 배포)

항목	값
트리거	"리서치해서 보고서로", "조사해서 보고서로 만들어줘", "research report 작성"
스킬 체인	report 파이프라인과 동일 (Phase 2에서 199-deep-research 급 깊이 적용)
출력	인용 기반 DOCX + Google Drive + Slack #h-report

report 파이프라인의 변형. Phase 2 Research에서 최대 깊이 적용.

---

video — 영상 제작 파이프라인 (6개 로컬 영상 스킬 라우터)

항목	값
트리거	"영상 만들어줘", "영상 제작", "비디오 생성", "make a video", "explainer 영상", "모션그래픽", "수학 애니메이션", "멀티신 영상", "소재 편집해서 영상"
스킬 체인	video-producer(라우터) → intent별 1개 선택: manim-video / hyperframes(+cli/media) / remotion-motion-forge / video-use / openmontage / ffmpeg-toolkit → 무거운 렌더는 서브에이전트 위임 → ffprobe verify gate
출력	검증된 .mp4 (outputs/video/{slug}/) + 사용 툴 체인 요약

라우팅 규칙은 video-producer SKILL.md Step 1 표가 정본. 사용자가 툴명을 지정("manim으로")하면 라우터 건너뛰고 해당 스킬 직접 호출. 격리 실행이 필요하면 서브에이전트 subagent_type=video-producer로 dispatch(동일 라우터 로직). 단발 사용자-완전지정 ffmpeg 1줄은 native([[token-diet-hygiene]]).

---

fin-desk — 금융 워크플로 데스크 (anthropics/financial-services 통합)

항목	값
트리거	"어닝 리뷰", "실적 분석", "DCF", "LBO", "재무 모델", "피치 덱", "comps", "밸류에이션 리뷰", "GL 대사", "월말 결산", "KYC", "마켓 리서치", "earnings review", "financial model", "pitch deck"
에이전트 DAG	각 fin-* 에이전트의 Output Contract next_agent 핸드오프를 따름
출력	에이전트별 산출물 (모델/노트/덱/리포트) — 사람 검토용 draft

claude-for-financial-services 마켓플레이스(7 vertical + 10 agent, 66 skill) 위에서 동작하는 10개 fin-* 서브에이전트. 실제 upstream skill 호출 + fallback-first 데이터(yfinance/pykrx/EDGAR/QuantDinger). 상세: .claude/agents/references/fin-connector-fallback.md.

에이전트 라우팅 + 핸드오프 DAG:

fin-market-researcher  → fin-model-builder | fin-pitch-agent
fin-earnings-reviewer  → fin-model-builder | fin-pitch-agent
fin-model-builder      → fin-valuation-reviewer | fin-pitch-agent
fin-pitch-agent        → fin-model-builder | fin-valuation-reviewer
fin-valuation-reviewer → fin-model-builder | fin-statement-auditor
fin-statement-auditor  → fin-valuation-reviewer | fin-month-end-closer
fin-month-end-closer   → fin-gl-reconciler | fin-statement-auditor
fin-gl-reconciler      → fin-month-end-closer | fin-statement-auditor
fin-kyc-screener       → fin-statement-auditor
fin-meeting-prep       → fin-market-researcher

실행: 트리거 매칭 시 진입 에이전트를 Agent 도구로 디스패치(subagent_type=fin-<role>) → 반환된 Output Contract의 next_agent가 non-null이면 사용자 확인 후 다음 에이전트로 체이닝. 서브에이전트는 MCP 불가이므로 메인이 필요 데이터를 파일로 떨궈 전달.

---

paper — 학술 논문 작성 파이프라인 (Research → Write → Review → Publish)

항목	값
트리거	"논문 작성해줘", "paper writing", "학술 논문", "컨퍼런스 논문", "research paper 작성", "LaTeX 논문 써줘", "논문 전체 파이프라인", "research to paper", "systematic review"
스킬 체인	academic-pipeline v3.11.1 (10-stage: Research → Integrity → Write → Cite → Integrity2 → Review → Revise → Re-review → Final-integrity → Finalize)
출력	LaTeX/APA7 원고 + PDF + 검증된 BibTeX + 인용 감사 보고서 + 피어리뷰 보고서

실행: academic-pipeline 스킬로 위임 (ARS v3.11.1). 내부적으로:

• deep-research (13-agent, PRISMA 지원) — 리서치 단계
• academic-paper (12-agent, Style Calibration) — 집필 단계
• academic-paper-reviewer (7-agent: EIC + 3 리뷰어 + Devil's Advocate) — 심사 단계
• 2중 Integrity Gate (Stage 2.5 + Stage 4.5): 인용 날조·통계 오류 차단

nature-skills 보강 (Yuan1z0825/nature-skills 포팅, 저널 투고급):

• nature-figure — Write 단계 figure 생성부. Nature 규격 matplotlib/ggplot2 멀티패널(호출 시 "Python or R?" 먼저 물음). 일반 차트/덱 아님(→ data-visualization/keynote-architect). preset: scripts/skills/nature_figure_preset.py
• nature-polishing — Finalize 직전 영문 교열(Nature-leaning, 중→영). academic-paper Style Calibration과 부분 중복 — 투고 직전 최종 폴리시에만
• nature-response — Re-review 이후 신규 stage. 리뷰어 코멘트 → point-by-point 반박편지(Quote→Response→Revision→Location)
• nature-academic-search — 리서치 보강(CrossRef/PubMed/arXiv keyless; Scopus/ScienceDirect=Elsevier 키). deep-research와 중복 — 구조화 RIS/BibTeX 필요 시만

모드 선택:

• 처음부터: deep-research + academic-paper + academic-pipeline 풀 체인
• 논문만 심사: academic-paper-reviewer 직접 호출
• 문헌 리뷰만: deep-research systematic-review 모드
• PRISMA 메타분석: deep-research meta-analysis 모드

핵심 차별화: Integrity Gate (Stage 2.5/4.5) + 0-100 품질 루브릭 + Devil's Advocate + Material Passport(협업 이력 자동 기록).

비용: $6-15/편 (깊이에 따라). academic-paper-pipeline(레거시 7-phase)도 계속 사용 가능.

---

dev-loop — 반복 개발 루프 (단일 진입점: 10개 루프 스킬 통합 라우터)

항목	값
트리거	"루프 돌려", "반복 개발", "자동으로 기능 구현", "PGE 루프", "랄프 루프", "AFK 코딩", "Goal Mode 시작", "자율 배치 개발", "loop으로 개발해줘"
스킬 체인	(아래 결정 트리로 정확히 1개 선택 — 직접 ralph/pge를 찾지 말 것)
출력	선택된 루프의 산출물 (구현 코드 + 테스트 + 커밋)

분산된 루프 스킬 10개(ralph-loop, omc-ralplan, ralplan-execute-bridge, pge-loop, autoagent-loop, ecc-autonomous-loops, ecc-verification-loop, reflection-loop, autonomous-decision-agent, agent-daemon-protocol)의 단일 라우터. 선택 마비를 막기 위해 항상 여기서 분기한다.

결정 트리:

1. 대상이 ai-suite(JS/TS 프론트, 빠른 테스트) repo인가?
   └ YES → ralph-loop (Docker sandbox, AFK 다회 iteration)
            ※ heavy/external → 사용자 명시 호출만 (disable-model-invocation)
2. 이 Go/K8s 백엔드 repo에서 기능을 1개씩 구현하나?
   └ YES → pge-loop (Planner→Generator→Evaluator→Feedback, 세션 내, Docker 불요) ★기본값
3. 다회 turn에 걸쳐 목표를 추적/누적하나?
   └ YES → jarvis Goal Mode (state/goals/*.json)
            + runtime/verify_gate.py --check "make test-short" 를 exit gate로
4. 계획(ADR/consensus)을 배치 실행으로 옮기나?
   └ YES → omc-ralplan → ralplan-execute-bridge → sp-executing-plans
5. 진짜 24/7 무인 자율인가?
   └ YES → 세션 루프 금지. runtime/daemon_tick.py + launchd cron화 ([[loop-monitor-cost-guard]])

cost guard 준수 (세션 내 루프 필수 조건): 모델 Sonnet 고정, exit gate는 make test-short(deps 불요)만, 50턴 전 분할. Opus 루프·/loop+ScheduleWakeup 24h 누적 금지.

나머지 루프 스킬은 위 5분기에 안 맞을 때만 직접: autoagent-loop(하니스 자가최적화), ecc-autonomous-loops(아키텍처 패턴 설계), ecc-verification-loop(검증 전용), reflection-loop(post-task 회고).

---

트리거 라우팅 테이블

사용자 입력 → 파이프라인 매핑 (모호성 해소):

사용자 입력 예시	매칭 파이프라인	이유
"AI 시장 보고서 작성해줘"	report	"보고서 작성" 키워드
"경쟁사 분석 보고서 만들어줘"	report	"보고서" + 분석 주제
"이것에 대해 페르소나 분석해줘"	persona	"페르소나 분석" 정확 매칭
"12개 관점으로 분석해줘"	persona	"관점 분석" 매칭
"이거 딥 리서치해줘"	deep-research	"딥 리서치" 정확 매칭 (보고서 아님)
"리서치해서 보고서로 만들어줘"	research-report	"리서치" + "보고서" 복합
"이 주제 좀 조사해줘"	deep-research	"조사" (배포 없음)
"분석해서 슬랙에 공유해줘"	report	"슬랙에 공유" → 배포 포함
"ICML 논문 써줘"	paper	"논문" + 컨퍼런스명
"이 아이디어로 논문 작성해줘"	paper	"논문 작성" 정확 매칭
"이 주제로 영상 만들어줘"	video	"영상 만들어줘" → video-producer 라우터
"수식 애니메이션 영상"	video → manim-video	수학 의도 → manim 라우팅
"이 클립들 편집해서 영상"	video → video-use	소재 편집 의도
"manim으로 만들어줘"	manim-video 직접	툴 명시 → 라우터 우회
"research paper 만들어줘"	paper	"research paper" 매칭
"기능 루프 돌려서 구현해줘"	dev-loop → pge-loop	Go 백엔드 세션 내 반복 개발 (기본값)
"랄프 루프 돌려줘"	dev-loop → ralph-loop	ai-suite JS 프론트 AFK (명시 호출)
"이 목표 Goal Mode로 추적해줘"	dev-loop → Goal Mode	다회 turn 목표 누적 + verify_gate
"24시간 자동으로 돌려줘"	dev-loop → cron화	무인 자율 = 세션 루프 금지, daemon_tick+launchd
"논문 심사해줘"	paper → academic-paper-reviewer 직접	"심사" 키워드 → reviewer 직접
"systematic review 해줘"	paper → deep-research 직접	PRISMA 리뷰 모드
"메타분석해줘"	paper → deep-research 직접	meta-analysis 모드
"오늘 매매 전략"	trade-plan (kr)	시간대 06~14 KST → KR
"한국장 전략 만들어줘"	trade-plan (kr)	"한국장" 명시
"미장 전략"	trade-plan (us)	"미장" 명시
"미국장 전 전략"	trade-plan (us)	"미국장" 명시
"tonight trading strategy"	trade-plan (us)	"tonight" → US
"daily trade plan"	trade-plan (시간 자동)	시간대 기반 세션 선택

파이프라인에서 사용하는 스킬 전체 목록

카테고리	스킬	용도
리서치	WebSearch, WebFetch	웹 검색, 페이지 수집
리서치	unified-knowledge-search	내부 KB 통합 검색
리서치	naver-news-search	국내 뉴스
리서치	hf-papers, alphaxiv-paper-lookup	논문 검색
리서치	kb-search	인텔리전스 KB
리서치	199-deep-research	초정밀 인용 기반 리서치
리서치	last30days	최근 30일 소셜 여론(Reddit/HN/YouTube/GitHub/Polymarket, 무키), 트렌드·VoC
분석	financial-report-analyzer	재무 분석
분석	competitive-analyst	경쟁사 분석
분석	pm-market-research	시장 조사
분석	equity-research-agent	투자 분석
분석	first-principles-analysis	원리 기반 분석
분석	second-order-thinker	2차 효과 분석
검증	fact-checker	소스 신뢰도 + 모순 탐지 + 원본 대조
검증	source-ranker	출처 신뢰도/관련성 순위 (fact-checker 내부)
검증	contradiction-finder	소스 간 모순/불일치 탐지 (fact-checker 내부)
품질	collaboration-quality-evaluator	인간-AI 협업 품질 6차원 평가 + Material Passport 생성
관점	role-dispatcher	12개 직무 관점
관점	role-ceo, role-cto, etc.	개별 페르소나
문서	analyst-report-docx	금융 보고서 DOCX
문서	docx-template-engine	템플릿 기반 DOCX
문서	anthropic-docx	범용 DOCX
배포	report-to-slack-pipeline	Drive 업로드 + Slack
논문	academic-pipeline	ARS v3.11.1 10-stage 풀 파이프라인 오케스트레이터 (권장)
논문	deep-research	ARS 13-agent PRISMA 지원 리서치 (systematic/meta-analysis)
논문	academic-paper	ARS 12-agent 집필 (Style Calibration, APA7/LaTeX)
논문	academic-paper-reviewer	ARS 7-agent 심사 (EIC + 3리뷰어 + Devil's Advocate)
논문	academic-paper-pipeline	레거시 7-phase 오케스트레이터 (호환용)
논문	related-papers-scout	선행연구 발굴 (Semantic Scholar)
논문	feynman-peer-review	동료 심사 시뮬레이션 (경량)
논문	pandoc	LaTeX/PDF 변환 (fallback)
논문	nature-figure	저널 규격 figure (Py/R, 멀티패널 SVG/PDF/TIFF); preset scripts/skills/nature_figure_preset.py
논문	nature-polishing	Nature-leaning 영문 교열 + 중→영 (투고 직전 최종 폴리시)
논문	nature-response	리뷰어 point-by-point 반박편지 (Re-review 후)
논문	nature-academic-search	CrossRef/PubMed/arXiv/Scopus 구조화 검색 + RIS/BibTeX

파이프라인 확장

새 파이프라인 등록 시 아래 형식 준수:

#### `{pipeline-id}` — {한 줄 설명}

| 항목 | 값 |
|------|-----|
| **트리거** | "{trigger1}", "{trigger2}", ... |
| **스킬 체인** | `skill-1` → `skill-2` → ... |
| **출력** | {최종 산출물 설명} |

---

Agent Registry

기계 판독 카탈로그 (전 에이전트): .claude/agents/references/agents-catalog.json — 54개 subagent의 name→model·tools·category·triggers·handoffs 구조화 인덱스. 스킬/Jarvis가 런타임에 전문가를 열거·라우팅할 때 이 파일을 읽는다. (fin-* 서브셋은 더 상세한 fin-services-catalog.json 참조.) 재생성: python3 scripts/build_agents_catalog.py. 매 턴 자동 노출: skill-router-gate.py가 skill 풀과 별도로 --agents 풀(top-3)을 주입한다 → 전문 에이전트가 skill 1600개에 묻히지 않고 동등하게 후보로 뜬다.

Tier 1 — Hermes (Self-Improvement & Safety)

Agent	Skill Path	Purpose
Checkpoint	hermes-checkpoint-rollback	Shadow git snapshots
Skill Guard	hermes-skills-guard	Security scan
Skill Evolver	hermes-skill-evolver	Population-based optimization
MoA	hermes-mixture-of-agents	Multi-model consensus

Tier 2A — Executive Perspectives

CEO, CTO, CSO, PM, Sales, Security, UX, Developer, Finance, HR, Data Sci, Trading → Dispatch via role-dispatcher --mode=executive

Tier 2B — Founder Pipeline (Sequential)

Researcher → Strategist → Copywriter → Builder → Marketer → Dispatch via role-dispatcher --mode=founder

Tier 2C — Financial Services Desk (fin-desk 파이프라인)

claude-for-financial-services 마켓플레이스 위에서 동작하는 10개 FSI 서브에이전트. 실제 upstream skill 호출 + fallback-first 데이터. isolation: true → MCP 불가.

Agent (subagent_type)	실제 skills	용도
fin-market-researcher	sector-overview, competitive-analysis, comps-analysis, idea-generation	섹터/경쟁/타겟 리서치
fin-earnings-reviewer	earnings-analysis, model-update, audit-xls, morning-note	실적 리뷰·노트
fin-model-builder	dcf-model, lbo-model, 3-statement-model, comps-analysis	DCF/LBO/3-statement 모델
fin-pitch-agent	sector-overview, comps-analysis, lbo-model, pitch-deck, ib-check-deck	피치 덱
fin-valuation-reviewer	returns-analysis, portfolio-monitoring, ic-memo	밸류에이션·LP 리포트
fin-statement-auditor	nav-tieout, audit-xls	재무제표 감사
fin-month-end-closer	accrual-schedule, roll-forward, variance-commentary	월말 결산
fin-gl-reconciler	gl-recon, break-trace, audit-xls	GL 대사
fin-kyc-screener	kyc-doc-parse, kyc-rules	KYC/AML
fin-meeting-prep	client-review, client-report, investment-proposal	미팅 브리핑

핸드오프 DAG는 fin-desk Pipeline Registry 항목 참조. 데이터 fallback: .claude/agents/references/fin-connector-fallback.md.

기계 판독 카탈로그 (스킬·에이전트가 FSI 역량 검색 시 읽음):

• .claude/agents/references/fin-services-catalog.json — 66 skill + 10 agent + 7 vertical 구조화 인덱스 (skill→owner, triggers, next_agent DAG, enabled 플래그)
• .claude/agents/references/fin-services-index.md — 사람·스킬용 라우팅 테이블
• 재생성: python3 scripts/build_fin_services_catalog.py (plugin update 후)

Tier 2D — Agency Specialist Suite (69 도메인 역할)

msitarzewski/agency-agents (upstream 220, 로컬 69 설치) 포팅 역할 라이브러리. Tier 2A(role-* 12 경영진)보다 세분화된 도메인 전문가가 필요할 때 사용.

용도	진입점	비고
역할 인덱스 (8 부서, 69개)	agency-roster	role→agency-{name} 스킬 경로 매핑
단일 역할 페르소나	Skill: agency-{name}	예: agency-growth-hacker, agency-security-engineer
소프트웨어 빌드 팀플	agency-agents-orchestrator	PM→Arch→Dev↔QA→Integration 순차 파이프라인 (멀티 관점 동시 아님)
멀티 관점 동시 분석	persona 파이프라인 (아래)	role-* 12 + agency-* 69 풀에서 병렬 디스패치

부서: Engineering(10), Design(8), Marketing(11), Product(3), PM(5), Testing(8), Support(6), Spatial(6) 외. 주의: 다수 upstream 역할이 기존 스킬군과 중복(china-, paid-media-, sales-, academic-, kwp-*) → 블라인드 동기화 금지, 큐레이션 필수.

Tier 2E — Archetype Orchestration Personas (5 lifecycle 모드)

Claude Code 팀 5원형(Prototyper/Builder/Sweeper/Grower/Maintainer)을 이식한 일하는-모드 페르소나. Tier 2A/2C/2D가 "무슨 도메인이냐"(직교축)라면, 이건 "같은 작업을 어떤 기질·완료기준으로 몰고 갈 것이냐"다. 도메인 스페셜리스트를 재구현하지 않고 지휘한다 — 스킬은 직접 호출(Skill 도구), 도메인 에이전트는 핸드오프로 jarvis 메인이 체이닝. 각 페르소나는 무드가 아니라 하드 산출 계약 + 완료 정의를 가진다(아니면 theater — [[evaluator-must-act]]).

페르소나 (subagent_type)	모드	트리거 신호	핸드오프
archetype-prototyper	발산·학습·POC (하드닝 금지)	아이디어/실험/POC/새 방향/빠르게 뭐가 되나	→ builder
archetype-builder	프로토타입→프로덕션	제대로 구현/출시/프로덕션화	backend/frontend-builder·tester → sweeper·maintainer
archetype-sweeper	삭제·단순화·통합·성능 (동작 불변)	정리/단순화/죽은코드/기술부채/느리다	→ maintainer
archetype-grower	PMF 반복·지표·실험·VoC	전환율/리텐션/PMF/성장/사용자 반응	→ builder
archetype-maintainer	보안·안정·속도·효율 (신규기능 0)	보안/안정성/스케일/장애/SLO/의존성	security-engineer·sre → sweeper·builder

호출: 의도 신호 매칭 시 Agent 도구로 dispatch(subagent_type=archetype-<name>). 흐름 DAG는 원문 그대로 prototyper → builder → sweeper, grower ↔ maintainer. 여러 원형 병렬 dispatch도 가능하되 결과는 verify로 닫는다([[close-the-agent-loop]]).

Advisory 라우팅 (하드 라우터 아님): 원형은 per-turn 하드 게이트가 아니다. 태스크 의도 + 대상 제품의 PMF 단계(pre-PMF=1+2+3 / growth=2+3+4+5 / strong-PMF=3+4+5+2)로 추천만 한다. 신호가 약하거나 단발 Q&A·단일 편집이면 억지 매칭 금지 → 도메인 에이전트 직접 또는 native ([[sra-incorporation-guard]] Anti-Hallucination). 카탈로그: agents-catalog.json category=archetype.

Tier 3 — Orchestrators

Mission Control, Engineering, Content, Research, Incident, Strategic Intel, Sales Deal, Meeting Intel, Knowledge Builder

Tier 4 — Specialists

Use skill-recommender or skill-guide to find the right specialist.

---

Workflow (5 Phases)

Phase 1: Decompose

Break goal into 2-7 sub-goals with success criteria, complexity, dependencies.

Phase 2: Search (Retrieve → Triage → Route)

이 단계가 Jarvis의 find-skill/skill-router 본체다. 매 작업마다 실행한다.

1. Retrieve — 1262+ skill 노이즈에서 후보를 좁힌다 (SRA, arXiv:2604.24594):

python3 .claude/skills/jarvis/scripts/sra/retrieve.py --top-k 8 "<task keywords>"

• --json (tooling 파싱), --kind skill|agent|plugin-skill|fin-agent (필터), --reindex (강제 재색인)
• 인덱스는 scripts/sra/index.json에 캐시, skill 수 변동 시 자동 재색인
• 색인 대상: 로컬 skill(.claude/skills) + subagent(.claude/agents) + fin-services 카탈로그

2. Triage (.claude/rules/sra-incorporation-guard.md 준수):

• Native (파일 편집, git, 단순 Q&A, grep, 코드 수정) → skill 건너뜀, 직접 실행
• Skill-worthy (구조화 워크플로·체크리스트·도메인 분석·오케스트레이션·문서 생성) → Route로

3. Route — 상위 후보를 진입점에 연결:

• 후보가 Agent Registry Tier 매칭 (예: fin-* → Tier 2C) → 해당 dispatch 방식
• Pipeline Registry 트리거 매칭 → Pipeline Mode 진입
• 단일 skill → Skill 도구로 호출 / subagent → Agent 도구 (subagent_type)
• 무매칭 (retrieve 0건) → 억지 매칭 금지. native 처리 또는 명시적 지시의 새 subagent

retrieve.py가 없거나 실패하면(예: 환경 차이) 인-컨텍스트 skill 목록으로 mental 매칭 fallback. 단, 1000+ 코퍼스에서 mental-only는 noise에 취약하므로 retrieve 우선.

0. Route (실행 전략 자동 판단) — retrieve.py가 '어떤 스킬'을 고르듯, scripts/sra/route.py가 '어떤 방식으로 처리할지'를 결정론 코드로 판단한다 (native / single_skill / pipeline / dev_loop / goal_mode / ultracode_workflow). skill-router-gate.py 훅이 매 턴 자동 실행 → conf≥0.55 & 비-native/단일스킬이면 🗺️ 실행 전략 추천 블록을 컨텍스트에 주입(스킬 후보 없는 dev_loop/pipeline도 발화). 사용자가 ultracode/jarvis goal을 명시 안 해도 신호로 모드를 추천 = 사용자 요구 "시스템화된 판단". 단 advisory일 뿐 — 강제 아님(억지 라우팅 금지, [[sra-incorporation-guard]] Anti-Hallucination과 동일). 천장 정직: 모드 분류만, 하위작업 분해는 메인 LLM 몫.

python3 scripts/sra/route.py "<task>"                 # JSON: strategy/confidence/strength/suggested_pipeline
python3 evals/route_bench_run.py        # 게이트 벤치(keyword-only 18케이스, ≥80%)
python3 evals/route_bench_run.py --live # production 스모크(BM25 켜짐, non-gating)

Phase 3: Classify

Complexity (S/M/L/XL), Risk (Low/Med/High), Model tier, Parallelism.

Phase 4: Plan

Output numbered dispatch plan with phases, dependencies, verification criteria.

Phase 5: Validate

Present to user. Goal Mode → proceed. Plan Mode → stop.

---

Workflow Templates

목표 유형별 최적 실행 패턴 사전 정의. Phase 2(Search)에서 매칭되면 해당 템플릿의 phase 순서를 자동 적용.

Feature Development

Phase: Research → Spec → Implement → Test → Ship
Skills: parallel-deep-research → pm-execution → build-with-tests → qa-test-expert → ship
Gate: Spec 승인 후 구현 진입 (사용자 확인 필수)

Research & Report

Phase: Gather → Analyze → Write → Review → Distribute
Skills: parallel-deep-research → role-dispatcher → anthropic-docx → doc-quality-gate → md-to-notion
Gate: 분석 결과 확인 후 리포트 작성 진입

Bug Investigation & Fix

Phase: Reproduce → Diagnose → Fix → Verify → Document
Skills: sp-debugging → diagnose → build-with-tests → omc-ultraqa → technical-writer
Gate: 근본 원인 확인 후 수정 진입

Document & Publish

Phase: Draft → Review → Format → Publish → Notify
Skills: anthropic-docx → doc-quality-gate → pandoc → md-to-notion → kwp-slack-slack-messaging
Gate: 품질 게이트 통과 후 퍼블리시

Template Selection Rules

1. 사용자가 템플릿을 명시하면 즉시 적용
2. Goal 키워드 매칭: "구현" → Feature Dev, "리서치/분석" → Research, "버그/에러" → Bug Fix, "문서/보고서" → Document
3. 매칭 실패 시 일반 5-Phase 워크플로우 사용
4. 사용자가 커스텀 phase 순서를 지정하면 템플릿보다 우선

Goal Mode

Lifecycle States

[created] → [pursuing] → [achieved]
                ↓
           [paused] → [budget-limited] → [unmet] → [cleared]

State File: .claude/skills/jarvis/state/goals/<goal-id>.json

Phase Gate (구현 전 승인)

Goal Mode에서 Research/Analysis 단계 완료 후 Implementation으로 진입하기 전 반드시 사용자 승인을 받는다.

[Research Phase] → Phase Gate 🔒 → [Implementation Phase]
                    ↓
              사용자에게 보고:
              - 조사 결과 요약
              - 제안하는 구현 방향
              - 예상 영향 범위
              - "진행할까요?" 확인 요청

Phase Gate 적용 조건:

• Goal의 complexity가 medium 이상일 때
• 구현이 5개 이상 파일을 변경할 것으로 예상될 때
• 비가역적 변경 (DB 마이그레이션, API 변경 등)이 포함될 때

Phase Gate 면제 조건:

• 사용자가 --auto-approve 플래그를 명시한 경우
• complexity가 low이고 변경 파일이 3개 이하인 경우

Iteration Loop (Claude Code)

1. Run python3 .claude/skills/jarvis/hooks/goal-continuation.py [goal-id]
2. If pursuing: execute smallest useful action
3. Update state JSON
4. Report progress
5. If terminal: report final status and stop

Claude Code /loop 명령으로 multi-turn 자동 진행 가능.

Budget Defaults

Parameter	Default
max_iters	10
max_tokens	500,000
max_cost_usd	5.00

---

Ambient Layer (2026-07-03 배선 — Goal Mode의 후계)

Goal Mode는 명시 호출 유지비 때문에 사실상 미사용(마지막 goal 2026-05-24)이었다. 별도 모드 대신 상주 레이어 + 아침 결재판으로 강등·재설계됨:

• HOT_MEMORY Open Loops: hot_memory_assemble.py가 active goal + open TODO를 매 세션 브리프에 상주시킨다 — 목표 추적이 "명령"이 아니라 "배경 인식".
• 결재판 (Decision Queue): scripts/skills/jarvis_decision_queue.py가 신호버스 pending + active goal + open TODO + outcome 미리뷰 계획을 D1..Dn 결정 단위로 집계, sod-ship(06:00)이 #효정-할일(C0AA8NT4T8T)에 게시. 사용자는 "D1, D3 실행"으로만 답한다. 그 답을 받은 세션은 승인 래치 불변식대로 즉시 디스패치한다.
• Outcome Backfill: scripts/skills/jarvis_outcome_backfill.py(ensure/set/report)를 eod-ship이 매일 구동 — 계획 실행률 실측이 jarvis-plan-outcomes 신호로 흐른다. outcome 기록은 반드시 set 서브커맨드로(YAML 손편집 금지, enum 코드 정규화).
• Consolidation 입력: jarvis consolidate는 jarvis_outcome_backfill.py report --days 30을 읽어 "승인만 받고 방치된 계획 패턴"을 회고에 포함한다.

---

TODO Mode

Path: .claude/skills/jarvis/state/todos/

Command	Action
jarvis todo add <task>	Create {date}-{slug}.md
jarvis todo list	Show all open items
jarvis todo done <id>	Mark complete
jarvis todo drop <id>	Archive
jarvis todo promote <id>	Convert to Goal

---

Plan Output Persistence

Path: outputs/jarvis-plans/{YYYY-MM-DD}/{HH}_{MM}-{slug}.md

All plans auto-saved with YAML frontmatter (goal, generated, complexity, risk, status, execution_tier, outcome).

Execution Tier (판단을 모델 재량이 아니라 필드가 소유 — [[sonnet-format-determinism]])

계획 생성 시 아래 규칙으로 execution_tier를 결정론적으로 채운다:

tier	조건 (모두 충족)	행동
auto	수정 파일 ≤ 3 · 비가역 변경 없음(DB 마이그레이션·prod 배포·외부 게시·git push 없음) · complexity=low	계획 저장 직후 즉시 실행, 승인 대기 없음
confirm	auto 미달이지만 비가역 변경 없음	계획 제시 → 승인 1회 → 즉시 실행
manual	비가역 변경 포함	비가역 단계만 개별 승인, 나머지는 연속 실행

승인 래치 불변식 (2026-05-10 "실행해줘 18회" 사고의 구조적 재발 방지):

• 승인 신호("웅", "실행해줘", "해줘", "고", "ㄱㄱ", "진행", "ok")를 받으면 같은 턴에 실행을 시작한다. 재확인·계획 재요약·"진행할까요?" 반복 금지.
• 승인은 계획 전체에 대한 승인이다. 단계마다 다시 묻지 않는다 (manual tier의 비가역 단계만 예외).
• 수정 요청을 받으면 수정본 제시 후 동일 규칙을 적용한다.

Outcome Field (계획 실측 루프)

outcome: 필드는 계획의 실제 결말을 기록한다: unreviewed(기본) → executed | partial | abandoned | superseded. eod-ship이 매일 scripts/skills/jarvis_outcome_backfill.py로 누락 필드를 삽입·표면화하고 증거 기반으로 채운다. 주간 consolidate는 --report 출력으로 승인율·실행률을 실측한다 — Success 지표(≥80%)의 측정 메커니즘.

---

Safety Gates

• Scope discipline: dispatch only what the user asked for — do NOT add unrequested pipeline stages, extra agents, or bonus deliverables (YAGNI).
• Input filter: semantic-guard for injection detection
• Output check: skill existence verification, stub detection
• Human gate: NEVER auto-execute in Plan Mode (jarvis plan 명령 = 항상 계획만)
• Approval latch: 승인 신호 수신 후 재확인 금지 — execution_tier 계약(Plan Output Persistence 절)을 따른다
• Circuit breaker: 3 consecutive failures → disable skill + suggest alternative
• Goal Mode: mandatory check_cmd, checkpoint every 3 iterations
• External services (Slack, email, git push): explicit approval required
• Close the loop ([[close-the-agent-loop]]): 멀티에이전트 fan-out(Workflow·병렬 Agent·persona/report 파이프라인)은 결과를 합치기 전 verify 스테이지로 닫는다. 코드 산출=verify_gate.py, 콘텐츠/판단=adversarial refute + verify_fanout.py. 검증 없는 fan-out 금지 — 환각 누적.

---

Observability

Trace: Plan, Dispatch, Execution, Result layers

Metrics: Plan Latency, Skill Hit Rate, Token Cost, Error Rate, Goal Velocity

Circuit Breaker: 3 failures → pause, 80% budget → warn, stall → user intervention

---

Claude Code 환경 특이사항

도구 매핑

Cursor	Claude Code
Shell	Bash
Task (subagent)	claude --model <tier> "prompt"
Glob	Bash + find / fd
Grep	Bash + rg
Read, Write, TodoWrite, WebSearch, WebFetch	동일

State 경로

Item	Path
Goals	.claude/skills/jarvis/state/goals/*.json
TODOs	.claude/skills/jarvis/state/todos/*.md
Hooks	.claude/skills/jarvis/hooks/
Evals	.claude/skills/jarvis/evals/
Plans	outputs/jarvis-plans/ (공유)

Subagent 규칙

• MCP 서버 접근 불가 — 단, 외부 액션은 Runtime Layer로 우회한다 (아래 참조)
• 파일 읽기/쓰기, Bash 명령, 검색, 분석만 위임
• --model haiku: 탐색 / --model opus: 아키텍처 / 미지정: 세션 기본

---

Runtime Layer (G1-G4 갭 클로저)

오케스트레이터(계획)와 런타임(실행) 사이 4개 구조 갭을 메우는 stdlib-only 스크립트. 경로: .claude/skills/jarvis/runtime/. 전체 문서: runtime/README.md. 출력은 항상 JSON 1줄. exit 0 ok · 2 graceful-skip(토큰 없음) · 1 error.

도구	갭	언제 쓰나
runtime/action.py	G2	서브에이전트가 MCP 없이 Slack/Notion/Discord/Telegram 게시. python3 .../action.py slack --channel C.. --message ".."
runtime/queue.py	G2	병렬 서브에이전트가 enqueue → 메인이 한 번에 drain. 외부 액션 fan-out
runtime/verify_gate.py	G4	--auto-approve 시 사람 Phase Gate 대체. --check "make test-short" 통과해야 다음 단계 (코드 전용)
runtime/verify_fanout.py	G4	fan-out 콘텐츠 닫힘([[close-the-agent-loop]]). adversarial skeptic verdict(JSON) → majority-refute로 keep/kill, 표결은 코드 소유. --verdicts -
runtime/daemon_tick.py	G1	cron/schedule//loop 재진입점. goals/todos/queue 상태 읽고 "다음 행동" 보고
runtime/runpod_headless.sh	G1	진짜 24/7 — 외부 호스트(claude -p 루프) 템플릿. 검토 후 수동 실행

서브에이전트 외부 액션 레시피 (MCP 차단 우회):

Bash: python3 .claude/skills/jarvis/runtime/action.py slack --channel <ID> --message "<결과>"
# 또는 레이스 회피: queue.py enqueue → 메인이 마지막에 drain

차단(정직한 스코프): 미디어/음성 생성(G3, 키 없음), 안티봇 우회(G3, ToS/합법성) — 미구현.

---

Pipeline Mode 실행 절차

Pipeline Mode가 트리거되면 아래 절차를 따른다. Plan Mode와 달리 즉시 실행한다.

진입 조건

사용자 입력이 Pipeline Registry의 트리거 패턴에 매칭될 때 자동 진입. 매칭 우선순위: 정확 키워드 > 의미 유사도 > 부분 매칭.

실행 프로토콜 (report 파이프라인 기준)

1. [Announce] "📋 report 파이프라인 실행합니다. 주제: {topic}"
2. [Context] 주제/범위/깊이/타겟 독자 추출
   - 필수 정보 부족 시: 1회 질문 후 진행
3. [Research] 병렬 리서치 (Agent tool × 3-5개)
   - 각 subagent가 다른 소스 담당
   - WebSearch, KB 검색, 뉴스, 논문 등 병렬 수집
4. [Analysis] 수집 데이터 종합 분석
   - 메인 에이전트에서 패턴 도출 + 인사이트 추출
   - 필요 시 전문 분석 스킬 추가 호출
5. [Fact-Check] 핵심 주장 교차 검증
   - WebFetch로 원본 확인, 수치 대조
   - 미확인 항목 표기 또는 제거
6. [Generate] DOCX/PPTX 바이너리 생성 (raw .md 배포 금지)
   - ⛔ generate_report.py 작성 금지 — 데이터 JSON 방출 → 커밋된 렌더러 실행
   - 차트 없음: thaki-report-v1 슬롯 JSON → docx-template-engine (generate_docx.py)
   - 차트 포함: report-data.json → scripts/skills/jarvis_report_render.py
   - 금융/투자: analyst-report-docx 스키마 → Skill: analyst-report-docx
   - 차트(matplotlib) + 출처 목록은 렌더러가 자동 처리 (모델이 포맷 결정 금지)
   - 게이트: ls -la 로 .docx 존재 & >20KB 확인
7. [Distribute] Drive 바이너리 업로드(누구나 열람 공개) + Slack 배포
   - `gws drive +upload "<abs>.docx" --format json` → file id (검증된 우선 경로)
   - `gws drive permissions create --params '{"fileId":"<FID>"}' --json '{"role":"reader","type":"anyone"}'` → 접근 공개(해제)
   - 링크 = https://drive.google.com/file/d/<FID>/view  (textContent 마크다운 업로드 금지 — 보고서 아님)
   - 게이트: permissions에 {anyone,reader} 존재 + mimeType=docx 확인
   - Slack #h-report (C0AKHQWJBLZ)에 scripts/slack_post_message.py로 요약+링크 포스트(mrkdwn)
8. [Confirm] 결과 보고 + Post-Action Skill Summary (산출물=.docx 재확인)

Research Subagent 패턴

리서치 단계에서 Agent tool 병렬 호출:

// 동시에 3-5개 Agent 호출 (1 메시지)
Agent({
  description: "Web research on {topic}",
  subagent_type: "researcher",
  model: "sonnet",
  prompt: "Research '{topic}' via WebSearch and WebFetch. Find: latest news (last 3 months), key players, market data, notable events. Return structured Korean markdown with source URLs. Max 800 words."
})

Agent({
  description: "Internal KB search for {topic}",
  subagent_type: "general-purpose",
  model: "haiku",
  prompt: "Search internal knowledge bases for '{topic}'. Check: knowledge-bases/ directory, outputs/ directory for prior reports. Return relevant findings with file paths. Max 500 words."
})

Agent({
  description: "News + competitive intel on {topic}",
  subagent_type: "general-purpose",
  model: "sonnet",
  prompt: "Find Korean news and competitive intelligence about '{topic}'. Use naver-news-search patterns (WebSearch site:naver.com). Return key articles with dates and summaries. Max 600 words."
})

Persona Dispatch (별도 persona 파이프라인)

Persona 분석이 필요할 때 (report와 별도):

Agent({
  description: "{role} perspective analysis",
  subagent_type: "general-purpose",
  prompt: "Read .claude/skills/role-{role}/SKILL.md. Analyze '{topic}' from {role} perspective. Output Korean markdown with: relevance score, key findings, risks, recommendations. Max 500 words."
})

복수 persona는 병렬 실행 (1 메시지에 여러 Agent tool 호출).

파이프라인 실패 처리

단계	실패 시	대체 동작
Research	일부 소스 실패	성공한 소스만으로 진행 (최소 1개 필요)
Analysis	분석 스킬 불가	메인 에이전트가 직접 분석
Fact-Check	검증 불가 항목 발생	"미확인" 표기 후 진행
Generate (DOCX)	python-docx/matplotlib 에러	에러 수정 후 재생성. .docx 산출 전엔 완료 아님 — raw .md를 최종 보고서로 대체 금지
Upload (Drive)	upload_drive.py 실패	MCP create_file + base64Content(바이너리, textContent 아님) fallback → 그래도 실패 시 로컬 .docx 경로 제공
Post (Slack)	토큰 만료	메시지 텍스트 직접 출력

어떤 단계가 실패해도 파이프라인 전체가 중단되지 않는다 (graceful degradation). 단, Generate/Distribute의 "바이너리 .docx" 게이트는 graceful degradation 예외다 — 마크다운 텍스트를 보고서랍시고 배포하느니 차라리 로컬 .docx 경로를 주는 게 낫다.

---

Post-Action Summary

모든 Jarvis 동작 완료 후 응답 마지막에 출력:

## Jarvis 실행 요약
| # | Phase | Status | Skills Used |
|---|-------|--------|-------------|
| 1 | Research | ✅ completed | pm-execution, code-to-spec |
| 2 | Architecture | ✅ completed | backend-expert, sp-writing-plans |
| 3 | Implementation | ⏳ in_progress | fsd-development |
| ... | ... | ... | ... |

- **총 스킬**: N개
- **실행 패턴**: Sequential / Parallel / Mixed
- **다음 단계**: [next action or "완료"]
- **Phase Gate**: [통과 / 대기 중 / 해당없음]

Phase Status 표기:

• ✅ completed — 완료
• ⏳ in_progress — 진행 중
• ⏭️ skipped — 건너뜀
• ❌ failed — 실패 (사유 명시)
• 🔜 pending — 대기

Agent Feedback (전문 에이전트를 dispatch한 턴에만)

Agent 도구로 named 전문 에이전트(backend-builder, reviewer, security-engineer, fin-* 등 generalPurpose가 아닌 것)를 dispatch했고 그 결과를 판정했다면, 응답 끝에 1줄 기록한다 — 이게 없으면 에이전트 eval 루프(agent_retro.py)가 비어 theater가 된다.

python3 scripts/skills/agent_retro.py record <agent> good|bad|unused "한줄 사유"
# good=결과 그대로 사용 · bad=틀려서 고치거나 폐기 · unused=후보였으나 미사용

연속 bad가 max_fail_streak(기본 3) 도달 시 해당 에이전트 모델 자동 승격 + needs_prompt_review 플래그 + Slack #h-report 알림. 함대 상태: python3 scripts/skills/agent_retro.py stats. 패턴 상세: .claude/agents/references/agent-evolution-pattern.md.