Loremaster

English | 한국어

모든 팀에는 lore(전승)가 있다. 대부분은 사라진다. Loremaster는 그것을 살아있게 한다.

Hermes Agent용 AI 스크럼마스터 / PM 스킬팩입니다. 11개의 스킬이 lore vault — 단일 진실 원천(single source of truth)으로 유지되는 프로젝트별 위키 저장소 — 를 중심으로 소규모 팀의 기획 루프를 돌립니다. AI는 제안하고, 탐지하고, 정제하며, 결정은 사람이 합니다.

데모용으로 쓴 게 아니라, 실제 멀티 프로젝트 팀(Slack + Jira + GitHub)을 운영 중인 프로덕션 시스템에서 추출했습니다. 제약이 곧 제품입니다:

• 탐지하되, 결정하지 않는다. AI는 충돌·공백·표류를 표면화할 뿐, 판정은 사람의 몫. 한쪽 편을 들지 않고, 담당자를 자동 지정하지 않고, 마음대로 확정하지 않습니다.
• 승인 게이트. 외부 시스템에 대한 모든 쓰기(Jira, 위키 커밋, 결정 폐기)는 건별로 명시적인 사람 승인을 거칩니다.
• 창작 금지. 원본(raw) 문서로 추적되지 않는 내용은 위키에 들어갈 수 없습니다 — 모든 위키 항목은 sources를 달고, 빈칸은 채우지 않고 표시만 합니다.
• 단방향 파생. raw/ → wiki/ → 지식 그래프 → [[위키링크]]. 사람은 파생 레이어를 직접 고치지 않습니다.
• 채널 = 프로젝트. 메모리·프롬프트·그래프가 프로젝트별로 격리됩니다.

아키텍처

flowchart TD
    subgraph PLAN["기획 루프 — Slack"]
        DEV(("개발자"))
        LM["Loremaster<br/>(Hermes Agent)"]
    end
    subgraph VAULT["Lore vault — git 저장소"]
        RAW["raw/ — PRD + 결정 로그<br/><b>유일한 진실</b>"]
        WIKI["wiki/ — 정제된 개념"]
        KG["graphify-out/ — 지식 그래프"]
    end
    subgraph BUILD["개발 루프 — 각 개발자의 로컬"]
        CA["코딩 에이전트<br/>(Claude Code, Cursor, …)"]
        REPO["제품 repo"]
    end
    JIRA["Jira"]
    OBS["Obsidian<br/>(사람이 위키를 열람)"]

    DEV -- "기획 수정 요청 / 질문" --> LM
    LM -- "제안 + Allow/Deny 버튼" --> DEV
    LM -- "승인된 수정만" --> RAW
    RAW -- "refine-wiki (단방향)" --> WIKI
    WIKI -- "의미 추출" --> KG
    KG -- "파생 위키링크" --> WIKI
    LM -- "백로그 제안<br/>(건별 승인)" --> JIRA
    DEV -- "구현 위임" --> CA
    VAULT -. "진실 원천, git으로" .-> CA
    CA -- "backlog-kickoff / backlog-complete<br/>(푸시 전 충돌 검사)" --> REPO
    CA -- "완료 시 이슈 전환" --> JIRA
    VAULT -. "git pull (Obsidian Git)" .-> OBS

루프는 둘, 진실은 하나: 기획 루프(Slack)는 사람 승인을 거쳐서만 raw/를 바꿀 수 있고, raw/ 아래는 전부 기계가 파생합니다. 개발 루프(각자의 코딩 에이전트)는 그 진실을 읽고 푸시 전에 기획 충돌을 검사합니다. Jira는 두 루프 모두에서 쓰이지만 — 사람 결정 없이는 절대 쓰이지 않습니다.

스킬

빠른 시작

전제조건: Hermes Agent v0.17+ 와 연결된 채팅 플랫폼(Slack 권장).

hermes skills tap add loremaster-ai/loremaster
hermes skills install loremaster-ai/loremaster/skills/loremaster-setup --yes

그 다음, 에이전트와의 채팅에서:

run loremaster-setup

셋업 스킬이 전 과정을 대화형으로 안내합니다 — 나머지 스킬 설치, 헬퍼 스크립트 다운로드, 첫 lore vault 생성, 프로젝트 채널 프롬프트 연결(설정 파일을 건드리기 전에 반드시 승인을 받음), 마지막 스모크 테스트까지. 모든 쓰기는 먼저 제안되고, 하나하나 여러분이 승인합니다.

설치는 신뢰 등급 community로 처리됩니다: Hermes가 각 스킬을 격리(quarantine)하고 보안 스캐너를 돌린 뒤 서드파티 위험 안내를 보여줍니다. 비인증 GitHub API 요청 제한을 피하려면 GITHUB_TOKEN을 설정하거나 gh auth login을 해두세요.

hermes skills browse --source github        # 주의: 그냥 `browse`는 GitHub tap을 건너뛸 수 있음
for s in backlog-proposal backlog-update conflict-detection daily-scrum impact-analysis \
         meeting-agenda refine-wiki resolve-conflicts sprint-planning sprint-retro wiki-qa; do
  hermes skills install "loremaster-ai/loremaster/skills/$s" --yes
done

구동 비용

Loremaster는 MIT이고 자체 유료 요소를 추가하지 않습니다 — Hermes가 원래 필요로 하는 것만 있으면 됩니다:

• LLM 두뇌 — Hermes가 지원하는 아무 모델. 우리 프로덕션은 구독 OAuth 프로바이더로 돌립니다(이미 내던 구독 위에 토큰 종량 과금 추가 없음). API 키 프로바이더와 OpenAI 호환 엔드포인트(로컬/자체 호스팅 모델)도 Hermes에서 설정 가능합니다 — 단, 소형 로컬 모델에서 이 스킬들을 검증하진 않았습니다.
• 지식 그래프 — 추가 비용 없음: 동봉된 파이프라인은 일부러 graphify의 keyless 경로를 씁니다(의미 추출은 세션 모델이 수행 — 별도 graphify API 키 불필요).
• Slack — 무료 플랜으로 충분. 승인 버튼은 게이트웨이 자체 큐를 재사용(두 번째 앱 불필요).
• Jira — 선택 사항. 무료 티어면 됩니다.

승인 버튼 플러그인

plugins/loremaster-approval은 스킬들이 모든 외부 쓰기 전에 호출하는 request_approval 도구를 제공합니다 — 진짜 Slack Block Kit [Allow]/[Deny] 버튼을 게시하고 사람이 클릭할 때까지 블로킹합니다. 게이트웨이 자체의 exec-approval 큐를 재사용하므로 두 번째 Slack 앱도, 코어 패치도 필요 없고, 어떤 Slack 요금제에서든 동작합니다:

hermes plugins install loremaster-ai/loremaster/plugins/loremaster-approval --enable
hermes gateway restart

업데이트는 --force를 붙여 설치를 다시 실행하세요(서브디렉토리 설치는 hermes plugins update를 쓸 수 없습니다).

⚠️ 이 플러그인은 Hermes 비공개 내부(tools.approval._await_gateway_decision 등)를 import합니다 — Hermes Agent v0.17.0에서 테스트됨. Hermes 업그레이드 후 깨지면 hermes 버전을 고정하세요. Hermes ≥ v2026.7.7에는 공개 승인 API(pre_tool_call → request_tool_approval, 업스트림 #66927에서 확인)가 있으며, 마이그레이션은 #1에서 추적합니다.

개발자 사이드 (Claude Code 등)

서버 에이전트는 제안하고 정제합니다 — 하지만 이슈의 마지막 구간은 각 개발자의 로컬 코딩 에이전트에서 일어납니다. client-template/에는 제품 repo의 .claude/skills/에 들어가는 스킬 4종이 있습니다(agentskills.io 표준이라 Claude Code, Cursor 등 호환 클라이언트가 전부 인식):

설치는 커밋 한 번입니다(셋업 스킬이 이 단계를 제안합니다):

cp -r client-template/.claude your-product-repo/

팀원들은 다음 git pull에서 자동으로 받게 됩니다 — 개인별 설치 없음. 이게 충돌 처리 이야기의 나머지 절반이에요: 충돌은 푸시 전에 로컬에서 backlog-complete가 잡고, 서버의 conflict-detection은 안전망입니다.

헬퍼 스크립트

scripts/에는 일부 스킬이 호출하는 결정적(LLM 미사용) 헬퍼 4종이 있습니다:

cp scripts/*.py ~/.hermes/scripts/

• loremaster-poker.py — Slack 플래닝 포커 카드 + 투표 집계 (sprint-planning이 사용)
• loremaster-graphify-plan.py / loremaster-graphify-build.py — graphify 위의 증분 지식 그래프 파이프라인: 의미 추출은 에이전트의 세션 모델이(별도 API 키 불필요), 캐시/병합/빌드는 스크립트가 결정적으로 수행
• loremaster-derive-wikilinks.py — 그래프 엣지에서 [[위키링크]] 파생(단방향)

설정

• Jira: examples/jira.env.example → ~/.hermes/keys/jira.env, examples/jira-projects.tsv.example → ~/.hermes/keys/jira-projects.tsv로 복사.
• 타임존: 스킬들은 산출물에 TZ="$TEAM_TZ"로 날짜를 찍습니다 — TEAM_TZ를 팀의 IANA 타임존(예: Asia/Seoul, America/New_York)으로 설정하세요.
• Lore vault: 각 프로젝트의 Slack 채널 프롬프트가 에이전트에게 vault 경로를 알려줍니다. vault는 raw/PRD.md + raw/decisions/*.md(진실) → wiki/concepts/*.md + wiki/index.md(파생) → graphify-out/(그래프 산출물) 구조의 git 저장소입니다.

Obsidian으로 lore 보기 (권장)

lore vault는 평범한 마크다운 저장소입니다 — Obsidian vault로 열면 팀이 탐색 가능한 링크드 위키를 공짜로 얻습니다:

• 위키 페이지들은 **지식 그래프에서 파생된 related [[위키링크]]**를 달고 있어서, Obsidian의 그래프 뷰가 팀의 lore를 시각화합니다 — 클러스터, 허브, 그리고 하나의 결정이 어디까지 파급되는지.
• 커뮤니티 플러그인 Obsidian Git(타이머 자동 pull)을 설치하면 에이전트가 위키를 정제할 때마다 모두의 Obsidian이 따라옵니다. 사람은 wiki/를 읽고 raw/를 편집합니다 — 파생 레이어는 기계가 씁니다.
• vault의 .gitignore에 .obsidian/을 추가하세요 — 에디터 상태는 개인별입니다.

vault의 lore가 이런 모습이 됩니다 — 노드 하나가 위키 개념 페이지 하나, 엣지 하나가 출하된 파이프라인이 파생한 링크 하나입니다 (이 그래프는 examples/demo-vault — 지금 바로 Obsidian으로 열어볼 수 있는 가상 제품의 완전한 vault — 에서 생성됐습니다):

로드맵

• v0.1 — 서버 스킬 11종 + 헬퍼 스크립트
• v0.2 (진행 중) — loremaster-setup 온보딩 스킬, Slack 승인 버튼 플러그인 (진짜 Block Kit Allow/Deny 버튼의 request_approval), 개발자 로컬 스킬 (client-template/: backlog-kickoff, backlog-complete, backlog-recall, project-onboard)
• 다음 — webhook → refine 워커 파이프라인(GitHub push → vault raw → wiki), lore-vault 템플릿 저장소

라이선스

MIT