jarvis

name

jarvis

description

Meta-orchestrator that decomposes user goals into agent execution plans and (optionally) pursues them across turns via Goal Mode. Maintains a persistent wiki-style TODO backlog under state/todos/. Searches available skills, classifies task complexity, selects optimal agent composition, produces a numbered dispatch plan with model routing and dependency ordering, and persists multi-turn objectives with pursuing/paused/achieved/unmet/budget-limited lifecycle states. Use when the user asks to "plan how to do X", "jarvis", "decompose this goal", "자비스", "goal mode", "pursue this until done", "jarvis goal", "jarvis plan", "자비스 계획", "자비스 목표", "long-running objective", "multi-turn goal", "자비스 TODO", "jarvis todo", "보고서 작성해줘", "리포트 만들어줘", "보고서 생성", "분석 보고서", "페르소나 분석", "관점 분석해줘", "딥 리서치", "리서치해서 보고서로", or wants intelligent skill composition planning with optional persistent goal pursuit. Pipeline Mode auto-triggers for registered pipelines (report, persona, deep-research, research-report) and executes immediately without plan output. Do NOT use for executing a single known skill (invoke it directly). Do NOT use for simple file edits or one-shot tasks. Do NOT use for the daily pipeline (use today). Do NOT use for "딥 리서치" without "보고서" — route to deep-research-pipeline directly. Korean triggers: "자비스", "목표 모드", "계획 세워줘", "장기 목표", "멀티턴 목표", "자비스 계획", "자비스 TODO", "보고서 작성해줘", "리포트 만들어줘", "페르소나 분석", "관점 분석"

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 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
출력	DOCX 파일 + Google Drive 링크 + Slack #h-report 포스트

실행 단계:

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: 축적된 인텔리전스 검색
  │  [선택] 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 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는 중간 산출물일 뿐.
  │     마크다운만 올리고 링크 주는 것 = 보고서 미완성 = 실패.
  │
  │  보고서 유형에 따라 스킬 선택:
  │  - 금융/투자 분석 → Skill: analyst-report-docx (차트+테이블 임베드, 권장)
  │  - 기업/전략 보고서 → Skill: docx-template-engine (thaki-report-v1)
  │  - 일반/리서치 → Skill: anthropic-docx (자유 형식, 출처 목록 포함)
  │  - 프레젠테이션 요청("PPT/덱/슬라이드") → Skill: anthropic-pptx / ppt-template-engine
  │  생성 방식: self-contained generate_report.py 작성 → 실행 → .docx + charts/ 산출
  │
  │  보고서 필수 구성:
  │  - 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 업로드 (바이너리 우선 경로):
  │     python3 .claude/skills/weekly-market-events-briefing/assets/upload_drive.py "<path>.docx"
  │     (env GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE 사용, anyone-reader 권한, webViewLink 출력)
  │     → 반환 링크가 docs.google.com/document/... 형태인지 확인.
  │     ✅ 게이트: 반환 mimeType/URL이 text/markdown·text/plain·/file/d/...md 이면 실패로 간주, 재업로드.
  │     fallback: MCP Google_Drive__create_file + base64Content(절대 textContent 아님) +
  │               contentMimeType=application/vnd.openxmlformats-officedocument.wordprocessingml.document
  │  2. Slack #h-report (C0AKHQWJBLZ) 포스트:
  │     - 제목 + 날짜 / Google Docs(.docx) 링크 / Executive Summary(3-5 bullet) / 검증률
  ▼
Phase 7: Confirm — 완료 보고 (산출물이 .docx 바이너리인지 최종 확인)

---

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

항목	값
트리거	"페르소나 분석", "관점 분석해줘", "직무별 관점", "크로스롤 분석", "12개 관점으로 분석", "multi-perspective"
스킬 체인	role-dispatcher --mode=executive → (선택) executive-briefing → Slack #효정-할일
출력	관점별 분석 마크다운 + CEO 종합 브리핑 + Slack 포스트

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

---

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

항목	값
트리거	"딥 리서치", "deep research", "종합 리서치", "깊이 조사해줘"
스킬 체인	199-deep-research or deep-research-pipeline
출력	인용 기반 리서치 결과 (마크다운, 배포 없음)

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

---

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

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

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

---

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 → LaTeX → Compile)

항목	값
트리거	"논문 작성해줘", "paper writing", "학술 논문", "컨퍼런스 논문", "research paper 작성", "LaTeX 논문 써줘"
스킬 체인	academic-paper-pipeline (7-phase: Research → Outline → Draft → Cite → Audit → Compile → Distribute)
출력	LaTeX 원고 + PDF + 검증된 BibTeX + 인용 감사 보고서

실행: academic-paper-pipeline 스킬로 위임. 기존 리서치 스킬(199-deep-research, related-papers-scout) + 검증 스킬(fact-checker, source-ranker) + 컨퍼런스 LaTeX 템플릿(ICML/ICLR/NeurIPS/ACL/AAAI/COLM) 통합.

핵심 차별화: 2계층 인용 검증 (실존 확인 + 주장 지지 여부).

비용: $2-8/편 (깊이에 따라).

---

트리거 라우팅 테이블

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

사용자 입력 예시	매칭 파이프라인	이유
"AI 시장 보고서 작성해줘"	report	"보고서 작성" 키워드
"경쟁사 분석 보고서 만들어줘"	report	"보고서" + 분석 주제
"이것에 대해 페르소나 분석해줘"	persona	"페르소나 분석" 정확 매칭
"12개 관점으로 분석해줘"	persona	"관점 분석" 매칭
"이거 딥 리서치해줘"	deep-research	"딥 리서치" 정확 매칭 (보고서 아님)
"리서치해서 보고서로 만들어줘"	research-report	"리서치" + "보고서" 복합
"이 주제 좀 조사해줘"	deep-research	"조사" (배포 없음)
"분석해서 슬랙에 공유해줘"	report	"슬랙에 공유" → 배포 포함
"ICML 논문 써줘"	paper	"논문" + 컨퍼런스명
"이 아이디어로 논문 작성해줘"	paper	"논문 작성" 정확 매칭
"research paper 만들어줘"	paper	"research paper" 매칭
"오늘 매매 전략"	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	초정밀 인용 기반 리서치
분석	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 내부)
관점	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-paper-pipeline	학술 논문 7-phase 오케스트레이터
논문	related-papers-scout	선행연구 발굴 (Semantic Scholar)
논문	feynman-peer-review	동료 심사 시뮬레이션
논문	pandoc	LaTeX/PDF 변환 (fallback)

파이프라인 확장

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

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

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

---

Agent Registry

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 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 우선.

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

---

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).

---

Safety Gates

• Input filter: semantic-guard for injection detection
• Output check: skill existence verification, stub detection
• Human gate: NEVER auto-execute in Plan Mode
• 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

---

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/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 배포 금지)
   - analyst-report-docx 등 document skill로 generate_report.py 작성+실행
   - 차트(matplotlib) + 출처 목록 필수 포함
   - 게이트: ls -la 로 .docx 존재 & >20KB 확인
7. [Distribute] Drive 바이너리 업로드 + Slack 배포
   - upload_drive.py(googleapiclient/MediaFileUpload)로 .docx 직접 업로드
     (textContent로 마크다운 올리기 금지 — 그건 보고서 아님)
   - 게이트: 반환 URL이 docs.google.com/document 형태인지 확인
   - Slack #h-report (C0AKHQWJBLZ) 포스트
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 — 대기