구현 계획서 — deploy/ 배포 설정 tmux→herdr 전환 (Job baa15c96)
- Planner: claude (planner-reviewer)
- 입력:
.mam/deploy_brief.md + deploy/ 전수 분석 + 현행 스킬 구현(단일 진실 소스) 대조
- 핵심 원칙: 문서·스크립트가 브리프의 추정 어휘가 아니라 현행 스킬이 실제 소비하는 어휘와 일치해야 한다. 실측 결과 브리프의 제안 중 2건은 실제 구현과 다르므로 아래와 같이 교정한다:
HERDR_SESSION_NAMEHERDR_SERVER_NAME (스킬 전체가 이 이름만 소비, TMUX_SERVER_NAME 소비처는 0곳)--herdr-session--herdr-server (create_session.sh:63이 수용하는 유일한 플래그, --tmux-server는 이미 제거되어 미지원)
0. 실측 현황 (전수 스윕: grep -in "tmux" deploy/ + 스킬 대조)
| 파일 |
행 |
현재 내용 |
판정 |
| install_mam.sh |
224 |
--tmux-server multi-agent-mux (Quick Start 예시) |
🔴 기능 파손 — create_session.sh가 이 플래그를 거부(unknown arg, exit 2). 사용자가 복붙 시 즉시 실패 |
| install_mam.sh |
227 |
$ tmux -L multi-agent-mux attach -t <session_name> |
🔴 죽은 명령 |
| install.sh |
31 |
check_cmd tmux |
🟠 잘못된 의존성 진단(herdr 미검사) |
| install.sh |
249 |
.env에 TMUX_SERVER_NAME=default 기록 |
🟠 죽은 설정(소비처 0) |
| README.md |
9 |
requirements "(tmux, python3)" |
🟡 문서 불일치 |
| INSTALL.md |
21, 37 |
진단 목록에 tmux |
🟡 문서 불일치(install_mam.sh:86 실제 DEPS는 이미 herdr python3 rsync uuidgen) |
| INSTALL.md |
69 |
"호스트 재기동으로 tmux가 소멸한 경우" |
🟡 문서 불일치 |
| plugin.json |
3 |
"... Backplane on Tmux & MQTT." |
🟡 메타데이터 불일치 |
| remove.sh / update.sh |
— |
tmux/kill 로직 없음(파일 삭제·venv·문서 갱신뿐) |
✅ 수정 불요(브리프 검토 항목 종결) |
| generate-env.sh / gitea-ci.yml |
— |
tmux 참조 없음 |
✅ 수정 불요 |
1. 파일별 수정 계획 (변경 대비표)
1-1. deploy/install_mam.sh (우선순위 1 — 기능 파손 수정)
| 행 |
변경 전 |
변경 후 |
| 224 |
--tmux-server multi-agent-mux |
--herdr-server multi-agent-mux |
| 227 |
$ tmux -L multi-agent-mux attach -t <session_name> |
$ HERDR_SERVER_NAME=multi-agent-mux herdr agent attach <session_name> |
근거: 224는 create_session.sh:63의 실제 플래그. 227은 create_session.sh:328이 YAML attach_command로 방출하는 canonical 형식(HERDR_SERVER_NAME=<server> herdr agent attach <name>)과 동일하게 맞춘다(개별 에이전트 pane attach). 전체 서버 화면이 필요하면 herdr session attach multi-agent-mux도 각주로 병기 가능.
1-2. deploy/install.sh
| 행 |
변경 전 |
변경 후 |
| 31 |
check_cmd tmux |
check_cmd herdr |
| 249 |
TMUX_SERVER_NAME=default |
HERDR_SERVER_NAME=default |
권장 추가(선택): check_cmd herdr 실패 시 install_mam.sh:96–98과 동일한 설치 안내(curl -fsSL https://herdr.dev/install.sh \| sh)를 출력하도록 check_cmd 호출부 뒤에 힌트 블록 추가 — 두 인스톨러의 UX 일관성 확보.
마이그레이션 노트: 기존 설치본 .env의 TMUX_SERVER_NAME은 소비처가 없어 잔존해도 무해하므로 자동 치환 로직은 불요(계획서 기록으로 갈음).
1-3. deploy/README.md
| 행 |
변경 전 |
변경 후 |
| 9 |
checks system requirements (`tmux`, `python3`) |
checks system requirements (`herdr`, `python3`) |
1-4. deploy/INSTALL.md
| 행 |
변경 전 |
변경 후 |
| 21 |
시스템의 `tmux`, `python3`, `rsync`, `uuidgen` …을 진단 |
시스템의 `herdr`, `python3`, `rsync`, `uuidgen` …을 진단 |
| 37 |
**의존성 진단**: … `tmux`, `python3`, … |
**의존성 진단**: … `herdr`, `python3`, … |
| 69 |
호스트 재기동으로 tmux가 소멸한 경우에도 |
호스트 재기동으로 herdr 서버가 소멸한 경우에도 |
1-5. deploy/plugin.json
| 행 |
변경 전 |
변경 후 |
| 3 |
"… Backplane on Tmux & MQTT." |
"… Backplane on Herdr & MQTT." |
1-6. deploy/remove.sh, deploy/update.sh — 수정 없음 (분석 결과 기록)
두 스크립트 모두 세션 킬링 로직 자체가 존재하지 않고 파일 자산 삭제/갱신만 수행하므로 tmux→herdr 마이그레이션 대상이 아니다. (선택적 후속 개선: remove.sh가 스킬 제거 전 실행 중인 herdr 에이전트 세션을 multi-agent-mux-stop으로 정리하도록 권고하는 안내 문구 추가 — 본 브리프 범위 밖이므로 별도 결정.)
2. 구현 순서
- install_mam.sh (기능 파손 우선) → 2. install.sh → 3. 문서 3종(README/INSTALL/plugin.json) → 4. 검증 → 5. 커밋(예:
fix(deploy): migrate deployment scripts and docs from tmux to herdr).
3. 검증 계획 (Reviewer/Creator 공용 DoD)
- 잔존 스윕:
grep -rin "tmux" deploy/ → 0건 (대소문자 무시 필수 — Tmux 표기가 plugin.json에 존재했음).
- 정적: 수정된 .sh에
bash -n + shellcheck -S warning, 변경 전 대비 신규 경고 0건. plugin.json은 python3 -m json.tool로 유효성 확인.
- 기능(핵심): Quick Start 예시를 그대로 복붙 실행 — 스크래치 워크스페이스에서
create_session.sh --workspace <scratch> --agent claude --role developer --isolate --herdr-server <scratch서버명> --dry-run 이 exit 0. (--dry-run이 spawn 전에 종료하므로 라이브 무접촉. --isolate 플래그는 create_session.sh:66에서 여전히 수용됨을 확인 완료.)
- attach 명령 실증: 문서의 attach 형식이 실제 YAML
attach_command(예: .mam/agent-sessions.yaml:18)와 동일 형식인지 대조.
- 회귀:
.env 신규 생성 경로에서 HERDR_SERVER_NAME=default 기록 확인, TMUX_SERVER_NAME 소비처 0곳 재확인(grep -rn TMUX_SERVER_NAME .agents/skills = 0).
4. 완료 기준
- deploy/ 내 tmux 참조(대소문자 무관) 0건, Quick Start 예시 실행 가능, 정적 검사 클린, 문서 어휘가 현행 스킬 구현(
--herdr-server/HERDR_SERVER_NAME/herdr agent attach)과 1:1 일치.
