multi-agent-mux/BOOTSTRAP.md

# BOOTSTRAP.md

본 문서는 `advanced_multi_agent` 오케스트레이션 및 메시징 백플레인 워크플로우를 새로운 프로젝트에 도입하여 이식하고, 새로운 개발자/에이전트가 초기 가동을 시작할 때 수행해야 하는 환경 설정 및 구축 절차를 안내합니다.

새로운 에이전트는 이 안내서에 기술된 절차를 순차적으로 실행하여 초기 환경을 안정적으로 설정할 수 있습니다.

---

## 1. 프로젝트 구조 이해 (Scaffolding Overview)

본 프로젝트를 새로운 환경에 복제(Clone)한 후, 핵심 구성 요소들의 위치와 역할을 먼저 파악해야 합니다.

*   `skills/`: 멀티 에이전트 구동 및 비동기 잡 처리를 수행하는 셸 스크립트 모음
    *   `lib.sh`: 오케스트레이션의 핵심 셸 함수 및 가상환경(venv) 자동 연동 라이브러리
    *   `tmux-agent-orchestrate-create/`: 격리된 tmux 에이전트 세션을 시작하는 스크립트
    *   `tmux-agent-orchestrate-stop/`: 세션을 정상적으로 중지하고 상태를 업데이트하는 스크립트
    *   `tmux-agent-orchestrate-resume/`: 중지된 에이전트 세션을 이전 대화 상태 그대로 복원하는 스크립트
    *   `tmux-agent-orchestrate-status/`: 전체 에이전트 세션의 현재 구동 상태를 조회하는 스크립트
    *   `tmux-agent-orchestrate-monitor/`: tmux 상태와 레지스트리 상태를 동기화하는 모니터 스크립트
    *   `tmux-agent-orchestrate-delegate-job/`: 비동기 잡 분할 실행 모듈
        *   `requirements.txt`: Python 의존성 목록 (paho-mqtt, pyyaml)
        *   `scripts/`: 핵심 비즈니스 로직을 구동하는 Python 스크립트 디렉터리
            *   `registry.py`: 잡의 등록, 클레임 및 원자적 파일 락 제어 (CLI 지원)
            *   `job_subscriber.py`: 백그라운드 이벤트 구독기 및 오디팅 로그 생성기
            *   `publish_event.py`: 실행 상태 및 에러 트랩 시 이벤트 퍼블리셔
            *   `mqtt_common.py`: 공통 MQTT 브로커 연결 유틸리티
*   `AGENT.md`: 에이전트 간의 역할 분담(PM, Worker, Reviewer) 및 이벤트 발행 규약 정의
*   `MESSAGING.md`: 에이전트 간 주고받는 MQTT 메시지 와이어 스킴 가이드라인

---

## 2. 환경 설정 파일 생성 (.env)

메시징 브로커 설정 및 실행 경로를 설정하기 위해 로컬 환경 설정 파일(`.env`)을 생성하고 수정해야 합니다.

### 단계 2.1: 자동 생성 스크립트 실행
프로젝트 루트에서 제공되는 환경 설정 템플릿 복사 스크립트를 실행합니다.

```bash
# .env.example를 .env로 자동 복제 (이미 존재하면 덮어쓰지 않고 보호됨)
./scripts/generate-env.sh

# 만약 강제로 덮어쓰고 백업을 생성하고 싶은 경우:
./scripts/generate-env.sh --force
```

### 단계 2.2: 환경 변수 수정 및 설정
생성된 `.env` 파일을 열어 설정을 필요에 따라 구성합니다.

> [!NOTE]
> `generate-env.sh`로 생성된 기본 `.env` 파일은 모든 환경 변수 항목이 주석 처리되어 있습니다. 주석 처리된 상태로 둘 경우 로컬 프로젝트 루트를 기준으로 한 상대 경로(`.hermes/` 등) 및 기본 공개 브로커 주소가 자동 지정되므로 그대로 사용하셔도 무방합니다.

1.  **MQTT Broker 설정 (`MQTT_BROKER`)**:
    *   기본값은 HiveMQ 공개 브로커(`broker.hivemq.com`)로 잡혀 있으나, 보안 및 프라이버시가 중요한 프로덕션 작업 시에는 개인/사설 브로커 주소로 변경할 것을 강력히 권장합니다.
2.  **인증 정보 (`MQTT_USERNAME`, `MQTT_PASSWORD`)**:
    *   보안 브로커를 사용하는 경우 `replace_me`로 명시된 곳을 실제 브로커 계정 정보로 변경해 주십시오.
3.  **경로 관련 변수 (선택 사항)**:
    *   특정 빌드 시스템이나 호스트 폴더 구조에 맞추어 `AGENT_SESSIONS_YAML` 및 `DELEGATE_JOB_LOGS_DIR` 등의 경로 값을 절대 경로로 오버라이드해야 하는 경우에만 주석을 풀고 기입하십시오.

> [!WARNING]
> **보안 모드 기본값 안내**:
> 시스템의 기본 설정은 **무인증 PoC 모드**입니다. 잡 등록 시 `auth_token`이 명시적으로 주입되지 않으면(또는 `null`인 경우) HMAC 서명 검증이 생략됩니다.
> 공개 브로커 사용 환경이나 실제 프로덕션 단계에서는 잡 등록 시 `auth_token`을 고유 난수값으로 생성 및 주입하여 HMAC 보안 서명을 활성화해야 합니다. (자세한 보안 규약은 [MESSAGING.md](./MESSAGING.md) 및 [AGENT.md](./AGENT.md)의 `2.3 보안 프로토콜` 섹션을 참조하십시오. 현재 CLI를 통한 자동 토큰 생성/주입 기능 지원은 향후 로드맵의 `FW-N6` 과제로 처리 예정입니다.)

---

## 3. 의존성 및 가상환경 설정 (Venv Setup)

오케스트레이션 및 MQTT 메시징을 구동하기 위한 Python 3 의존성을 설정합니다.

### 단계 3.1: Python 가상환경 구축
프로젝트 루트에서 `.venv` 가상환경을 생성하고 활성화합니다.

```bash
# 가상환경 생성
python3 -m venv .venv

# 가상환경 활성화
source .venv/bin/activate
```

### 단계 3.2: 의존성 패키지 설치
`tmux-agent-orchestrate-delegate-job` 디렉터리에 기재된 `requirements.txt` 의존성 목록을 가상환경에 설치합니다.

```bash
# 의존성 패키지(pyyaml, paho-mqtt 등) 설치
pip install -r skills/tmux-agent-orchestrate-delegate-job/requirements.txt
```

---

## 4. 디렉터리 준비 및 보안 감시 가이드

에이전트 제어 상태 및 잡 기록을 위해 로컬 레지스트리 디렉터리가 정상적으로 생성되었는지 확인합니다.

1.  **필수 로컬 디렉터리 구조**:
    *   `.hermes/jobs/`: 등록된 비동기 잡의 세부 메타데이터가 파일 형태로 저장되는 디렉터리
    *   `.hermes/delegate_job_logs/`: 에이전트가 발행하는 모든 백플레인 이벤트 흐름이 기록되는 audit log (`events.ndjson`) 보존 디렉터리
2.  **Git 커밋 제어 (.gitignore)**:
    *   새 프로젝트 초기화 시 아래 파일들이 절대 리포지토리에 커밋되지 않도록 `.gitignore` 상태를 점검합니다. `!.env.example` 예외 처리가 유지되어야 템플릿이 보존됩니다:
        ```text
        .env
        .env.*
        !.env.example
        .hermes/
        .venv/
        __pycache__/
        *.pyc
        ```

---

## 5. 실행 환경 검증 및 부트스트랩 테스트

환경 구축이 오작동 없이 안전하게 완료되었는지 아래의 체크리스트를 실행해 검증합니다.

> [!IMPORTANT]
> 아래의 모든 검증 명령은 반드시 **프로젝트 루트 디렉터리**(`.hermes/` 디렉터리가 직접 보이는 위치)에서 실행해야 합니다. 잡 레지스트리 디렉터리 기본 경로가 프로젝트 루트 하위의 `./.hermes/jobs` 상대 경로를 기준으로 탐색되기 때문입니다.

### 검증 테스트 1: 잡 레지스트리 정상 구동 여부
Python 스크립트 및 venv 라이브러리가 올바르게 로드되는지 확인하기 위해 잡 목록을 조회합니다.

```bash
# 가상환경(.venv) 파이썬 인터프리터를 사용하여 실행
.venv/bin/python3 skills/tmux-agent-orchestrate-delegate-job/scripts/registry.py list
```
*   **출력 기대 결과**: 에러 메시지 없이 빈 JSON 배열 `[]` 또는 현재 등록된 pending/running 잡 목록이 성공적으로 출력되어야 합니다.

### 검증 테스트 2: MQTT 연결 브로커 핸드셰이크 테스트
브로커와의 송수신 통신망 상태를 확인하고, 이벤트 생명주기 및 멱등성이 온전히 작동하는지 실측 검증합니다.

```bash
# 1. 테스트용 임시 잡 등록 및 발급된 8자리 Hex 잡 ID 획득
JID=$(.venv/bin/python3 skills/tmux-agent-orchestrate-delegate-job/scripts/registry.py register \
  --agent "test-agent" \
  --prompt "Bootstrap check command" \
  --timeout 120)
echo "Generated Job ID: $JID"

# 2. 획득한 잡 ID에 대해 백그라운드 이벤트 구독기(Subscriber) 구동
.venv/bin/python3 skills/tmux-agent-orchestrate-delegate-job/scripts/job_subscriber.py --job "$JID" &

# 3. 구독자의 MQTT Broker 소켓 연결 및 수신부 초기화 완료를 보장하기 위해 2초 대기
sleep 2

# 4. 테스트 시작 이벤트 발행 (Subscribe-before-Publish 원칙 준수)
.venv/bin/python3 skills/tmux-agent-orchestrate-delegate-job/scripts/publish_event.py \
  --job "$JID" \
  --event started \
  --detail "Bootstrap MQTT verification connection check"

# 5. 이벤트 수신이 터미널(stdout) 및 .hermes/delegate_job_logs/events.ndjson 로그 파일에 정상 기록되는지 확인

# 6. 검증 완료 후 백그라운드 프로세스 종료 및 테스트 잡 레코드 수동 정리
kill %1
rm -f ".hermes/jobs/$JID.json" ".hermes/jobs/$JID.lock"
```

---

## 6. 에이전트 온보딩 가이드 (New Agent Onboarding)

본 환경 구축을 무사히 마쳤다면, 협업하는 에이전트는 즉시 프로젝트 루트에 있는 **[AGENT.md](./AGENT.md)** 문서를 읽어야 합니다.

해당 문서에는 에이전트가 각 역할(PM, Worker, Reviewer)로 구동될 때 지켜야 할 **수술적 변경 규칙, 교차 검증 통과 규약, Tmux 뷰포트 유실 방지를 위한 스냅샷 패턴** 등이 서술되어 있어 안정적인 멀티 에이전트 워크플로우에 즉시 기여할 수 있도록 돕습니다.