multi-agent-mux/deploy/INSTALL.md

# 🛠️ Multi-Agent Mux (MAM) 설치 및 적용 가이드

MAM은 단일 워크스페이스 상에서 복수의 에이전트(Claude, Cline, Agy, Hermes 등)들이 서로의 상태를 오염시키지 않고 협업할 수 있도록 프로세스 격리 및 라이프사이클 관리를 제공하는 프레임워크입니다.

이 가이드는 기존의 다른 프로젝트/레포지토리에 MAM을 신속하게 도입하고 적용하는 절차를 설명합니다.

---

## 1. ⚙️ 사전 요구사항
MAM 스킬 및 스크립트들은 호스트 시스템의 다음 도구들에 의존합니다. 설치 전에 확인해 주세요.
*   **herdr**: 에이전트를 백그라운드 격리 Pane/Workspace에서 구동 및 관제하기 위한 프로세스 컨테이너
*   **python3**: 세션 레지스트리(YAML/SQLite DB) 파싱 및 유효성 검사 (내장 `sqlite3` 모듈 필수)
*   **uuidgen**: 격리 세션 생성 시 고유의 UUID 할당
*   **rsync**: 인스톨러(`deploy/install_mam.sh`)가 `.agents/` 오케스트레이터 및 스킬 폴더를 타겟 프로젝트에 복제하는 데 사용 (설치 시 필요)
*   **python3-yaml (pyyaml)**: 세션 데이터 YAML 저장 및 로드 의존성 (`pip install pyyaml`)

---

## 2. 🚀 자동 설치 방법

MAM의 자동 설치 스크립트(`deploy/install_mam.sh`)를 사용하여 10초 만에 필요한 규칙과 라이프사이클 툴킷을 타겟 프로젝트에 이식할 수 있습니다. 스크립트는 실행 시 자동으로 시스템의 `herdr`, `python3`, `rsync`, `uuidgen` 및 필수 파이썬 모듈들을 진단합니다.

> [!IMPORTANT]
> **설치 전제조건**: MAM 스킬을 타겟 프로젝트에 설치하려면 **먼저 MAM 레포지토리가 로컬 머신에 clone 되어 있어야 합니다.**

### 설치 스크립트 실행
MAM 레포지토리 루트 디렉토리로 이동한 후 다음 명령어를 실행합니다.
```bash
# 기본 사용법 (타겟 프로젝트 경로 지정)
$ bash deploy/install_mam.sh --target /path/to/your/project

# 만약 이미 타겟에 AGENTS.md 가 존재하여 강제로 덮어쓰고 싶다면:
$ bash deploy/install_mam.sh --target /path/to/your/project --force
```

### 설치 스크립트가 수행하는 작업:
1.  **의존성 진단**: 시스템에 `herdr`, `python3`, `rsync`, `uuidgen` CLI 바이너리와 파이썬 `pyyaml`/`sqlite3` 모듈이 설치되어 있는지 확인합니다.
2.  **규칙 및 스킬 복제**: 오케스트레이션 가이드(`.agents/` 하위 전체)를 타겟 프로젝트 하위로 이식합니다.
3.  **지침 전파**: 에이전트가 로드하고 복종할 행동 지침 문서(`AGENTS.md`)를 프로젝트 루트에 복사합니다.
4.  **형상 제외 설정**: 세션 DB 및 격리 캐시 저장소인 `.mam/` 디렉토리를 타겟 프로젝트의 `.gitignore` 에 자동 주입하여 불필요한 형상 관리를 방지합니다.

---

## 3. 🎯 핵심 사용 워크플로우 (Quick Start)

설치가 완료되면, 타겟 프로젝트 루트에서 에이전트들을 기동 및 관리할 수 있습니다.

### 1) 에이전트 격리 세션 생성 (Create)
새로운 에이전트를 독립된 격리 가상 디렉토리에서 띄웁니다.
```bash
$ bash .agents/skills/multi-agent-mux-create/scripts/create_session.sh \
    --workspace "/path/to/your/project" \
    --agent claude \
    --role developer \
    --session my-project-dev-claude \
    --herdr-server multi-agent-mux
```
*   모든 세션은 사용자의 전역 에이전트 설정(Global Config)을 공유하며, herdr 프로세스 격리 및 대화 UUID 단위로 독립 구동됩니다.

### 2) 세션 접속 (Attach)
백그라운드에서 구동된 에이전트 TUI 화면에 들어갑니다.
```bash
$ herdr session attach my-project-dev-claude
```
*   **화면 탈출**: 대화 중 세션을 유지한 채 터미널로 돌아오려면 `Ctrl + B`를 누른 뒤 `D` 키를 차례로 입력합니다.

### 3) 에이전트 상태 복원 (Resume)
세션이 중지되었거나, 호스트 재기동으로 herdr 서버가 소멸한 경우에도 이전 대화 ID를 원자적으로 이어받아 다시 기동할 수 있습니다.
```bash
# 1단계: 복원 대상 세션의 UUID 자동 조회 (DB/YAML 레지스트리 기반)
$ WORKSPACE="/path/to/your/project"
$ AGENT="claude"
$ SESSION_NAME="my-project-dev-claude"

$ UUID=$(bash .agents/skills/multi-agent-mux-resume/scripts/resolve_session_id.sh \
    --workspace "$WORKSPACE" --agent "$AGENT" --session "$SESSION_NAME")
 
# 복원 대상 세션의 유효성 검사 (M-1)
$ [ -n "$UUID" ] || { echo "[ERROR] 매칭되는 활성 세션 이력이 없습니다. create_session.sh를 통해 먼저 세션을 생성해 주세요."; exit 1; }
 
# 2단계: 세션 재기동 (이전 대화 컨텍스트 복원 기동)
$ herdr run -d --name "$SESSION_NAME" --workspace "$WORKSPACE" -- \
    "claude --dangerously-skip-permissions -r $UUID"
 
# 3단계: 레지스트리 세션 상태를 running 으로 동기화 갱신
$ bash .agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh \
    --session "$SESSION_NAME" --uuid "$UUID" --agent "$AGENT"
```

### 4) 세션 종료 및 정리 (Stop / Purge)
세션을 정지시키고 대화 컨텍스트를 동결하거나(default), 완전히 소멸시킵니다(`--purge-conversation`).
```bash
# 대화 메타데이터를 백업 및 영속화하고, 안전하게 종료 (status=stopped)
$ bash .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh \
    --session my-project-dev-claude --agent claude

# 대화 내용 및 격리 홈 디렉토리를 완전히 청소하고 종료 (status=terminated, resumable=false)
$ bash .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh \
    --session my-project-dev-claude --agent claude --purge-conversation --yes
```

### 5) 자율 반복 정제 루프 기동 (Mux-Loop)
계획 수립(Planner) ➜ 코드 수정(Creator) ➜ 교차 검증(Reviewer) ➜ 수정 정제 피드백을 단일 명령으로 자동 순환하는 반복 정밀 관제 루프를 기동합니다.
```bash
# 플래너 협력 계획 단계를 활성화하고, 리뷰어의 PASS 합의 하에 자율 루프 구동 (최대 3회 교정)
$ bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \
    --plan \
    --plan-talk 1 \
    --reviewer "reviewer-a,reviewer-b" \
    --max-loop 3 \
    --target-agent my-project-dev-claude \
    --task "구현할 명확한 개발 작업 목표"
```
*   `--max-loop`는 코드 오류 발견 시 최대 교정(반복 수정) 횟수 제한 가드레일 역할을 합니다.
*   **참고**: 리뷰 단계에서 코드 변경분을 정확하게 추적하기 위해, 타겟 프로젝트 디렉토리는 `git` 저장소로 기동 및 관리되고 있는 것을 권장합니다.

### 6) 오케스트레이터 온보딩 (Orc-Onboard)
오케스트레이터 에이전트의 대화 UUID를 레지스트리에 등록하여, 서브에이전트 탐지 루프에서 오케스트레이터 대화가 서브에이전트로 오탐 capture되는 것을 방지합니다.
```bash
# 오케스트레이터 대화 UUID 온보딩 (자동 탐지 또는 명시적 지정)
$ bash .agents/skills/multi-agent-mux-orc-onboard/scripts/orc_onboard.sh --uuid <orchestrator_uuid>

# 등록된 오케스트레이터 UUID 목록 확인
$ bash .agents/skills/multi-agent-mux-orc-onboard/scripts/orc_onboard.sh --list

# 등록된 오케스트레이터 UUID 제거 (오프보딩)
$ bash .agents/skills/multi-agent-mux-orc-onboard/scripts/orc_onboard.sh --remove <orchestrator_uuid>
```

### 7) 전용 NATS 메시징 브로커 설정 (.mam.env)
MAM은 비동기 작업 위임(`multi-agent-mux-delegate-job`) 및 이벤트 스트림 중계를 위해 MQTT 3.1.1 및 JetStream 기반의 사설 NATS 브로커(`nats-docker`)를 표준으로 지원합니다.
*   **환경 설정 생성**: `bash deploy/generate-env.sh` (또는 `cp .mam.env.example .mam.env`)를 실행하여 로컬 `.mam.env`를 생성합니다.
*   **서브모듈 동기화**: `git submodule update --init --recursive` 명령어로 `nats-docker/` 배포 자산을 초기화합니다. (사내 비공개 저장소 `laa/nats-docker` 접근 권한이 없는 경우 서브모듈 동기화를 생략해도 표준 MQTT 브로커를 통해 기본 프레임워크 기능이 완비됩니다.)
*   **사설 서버 배포 가이드**: 자세한 도커 배포 및 Tailscale 연동 절차는 [`nats-docker/PRIVATE_SERVER.md`](../nats-docker/PRIVATE_SERVER.md) 및 [`MESSAGING.md`](../MESSAGING.md)를 참조하십시오.

---

## 🛡️ 협업 및 보안 가이드라인
*   MAM을 사용할 때 모든 에이전트(개발자, 리뷰어)들은 루트의 `AGENTS.md` 지침을 우선 숙지하도록 설계해야 오탐과 무분별한 리팩토링 범람을 방지할 수 있습니다.
*   각 에이전트 역할별로 리뷰 프로세스를 돌릴 시, 최종 승인 결과 보고서(.md)는 형상 관리가 추적할 수 있도록 버전 관리 대상 경로(구체적으로 `.agents/reports/<session_name>/` 또는 `docs/reports/` 등) 하위로 이관 복사하여 커밋하는 규약(`.agents/MULTI_AGENT_RULES.md`)을 준수해 주세요.