feat: implement --onboard flag in multi-agent-mux-create and update AGENT.md onboarding handshake protocol

.agents/AGENT.ko.md

@@ -138,4 +138,23 @@ TMUX 환경에서 실행되는 에이전트가 화면 스크롤 한계로 인해
 
 ---
 
+## 6. 온보딩 핸드셰이크 프로토콜 (Onboarding Handshake)
+
+새롭게 기동되는 팀장 에이전트는 실무 작업을 수임하기 전에 반드시 `--onboard` 메커니즘을 통해 맥락을 파악하고 동기화(Alignment)해야 합니다. 이를 통해 올바른 설계 규칙과 저장소 이력을 숙지한 상태에서 안전하게 협업에 참여할 수 있습니다.
+
+### 🔄 온보딩 핸드셰이크 흐름 (Onboarding Handshake Sequence)
+1. **온보딩 플래그와 함께 생성**: 총괄 매니저가 다음 명령을 통해 새 세션을 생성합니다:
+   ```bash
+   bash .agents/skills/multi-agent-mux-create/scripts/create_session.sh --workspace "$(pwd)" --agent <agent> --role <role> --onboard
+   ```
+2. **에이전트 맥락 동기화**: 에이전트가 시작되면 아래 지시사항이 담긴 잡이 자동으로 인가됩니다:
+   - `README.md` 및 `.agents/AGENT.md`를 필독하여 설계 규약과 제약사항을 인지한다.
+   - `git status` 및 `git diff`를 실행하여 레포지토리의 활성 수정 내역을 분석한다.
+   - `.mam/agent-sessions.yaml`을 읽어 현재 러닝 상태인 타 에이전트 목록을 확인하고, 자신의 지정된 `role`을 검증한다.
+3. **핸드셰이크 완료 발행**: 에이전트는 위의 맥락 파악 작업을 완료한 후, `publish_event.py`를 호출하여 다음과 같은 단말 완료 이벤트를 발행합니다:
+   - Detail: `"Onboarding complete; aligned with role <role>"`
+4. **총괄 매니저 승인 게이트**: 총괄 매니저는 이 `completed` 핸드셰이크 신호가 오디팅 로그에 수렴될 때까지 대기(gating)해야 하며, 핸드셰이크가 통과된 것이 검증된 이후에야 해당 세션에 실무 또는 검수 작업을 위임합니다.
+
+---
+
 *본 가이드는 협업 효율성과 코드 보안의 엄격한 균형을 유지하기 위한 규범입니다. 변경 사항이 필요한 경우 총괄 매니저 및 전체 팀장의 합의를 거쳐 본 문서를 업데이트해야 합니다.*

.agents/AGENT.md

@@ -138,4 +138,23 @@ Use this checklist when deploying this agent orchestration model to a new projec
 
 ---
 
+## 6. Onboarding Handshake Protocol (Onboarding Handshake)
+
+Newly spawned Team Leader agents must align their context using the `--onboard` mechanism before receiving any real work. This ensures they operate with the correct design rules and repository history.
+
+### 🔄 The Onboarding Handshake Sequence
+1. **Creation with Onboard flag**: The General Manager spawns a new session with:
+   ```bash
+   bash .agents/skills/multi-agent-mux-create/scripts/create_session.sh --workspace "$(pwd)" --agent <agent> --role <role> --onboard
+   ```
+2. **Orienting the Agent**: The agent session starts up and automatically receives a registered job instructing it to:
+   - Read `README.md` and `.agents/AGENT.md` to align with design principles and constraints.
+   - Run `git status` and `git diff` to analyze active modifications.
+   - Read `.mam/agent-sessions.yaml` to identify other running agents and verify its own assigned `role`.
+3. **Handshake Publication**: The agent executes these orientation tasks and publishes a `completed` event to the broker (using `publish_event.py`) with:
+   - Detail: `"Onboarding complete; aligned with role <role>"`
+4. **GM Gating Check**: The General Manager polls or subscribes to this `completed` event. The GM **must** wait for this onboarding handshake to succeed before delegating any implementation or review jobs to the new session.
+
+---
+
 *This guide balances collaboration efficiency with strict code security. Any required changes must be discussed and agreed upon by the General Manager and all Team Leaders before updating this document.*

.agents/skills/lib.sh

@@ -826,4 +826,67 @@ start_watchdog() {
   echo "$pid"
 }
 
+# wait_for_tui_ready <session_name> <agent>
+# Gated wait to ensure that the agent's TUI is fully loaded and responsive
+# before injecting any keyboard instructions.
+wait_for_tui_ready() {
+  local sess="$1" agent="$2"
+  local local_tmux="tmux"
+  if [ -n "${TMUX_SERVER_NAME:-}" ] && [ "$TMUX_SERVER_NAME" != "default" ]; then
+    local_tmux="tmux -L $TMUX_SERVER_NAME"
+  fi
+  
+  echo "🔍 Waiting for $agent TUI to become ready..."
+  for i in {1..15}; do
+    local content
+    content=$($local_tmux capture-pane -p -t "$sess" 2>/dev/null || echo "")
+    if [ -n "$content" ]; then
+      case "$agent" in
+        claude)
+          if echo "$content" | grep -E -q "Anthropic|Assistant|Chat|Dangerously|dangerously|Enter|Welcome|projects" 2>/dev/null; then
+            echo "✅ Claude TUI detected ready."
+            return 0
+          fi
+          ;;
+        agy)
+          if echo "$content" | grep -q "Antigravity" 2>/dev/null; then
+            echo "✅ Antigravity TUI detected ready."
+            return 0
+          fi
+          ;;
+        hermes)
+          if echo "$content" | grep -q "Hermes" 2>/dev/null; then
+            echo "✅ Hermes TUI detected ready."
+            return 0
+          fi
+          ;;
+        cline)
+          if echo "$content" | grep -E -q "Cline|history|Chat" 2>/dev/null; then
+            echo "✅ Cline TUI detected ready."
+            return 0
+          fi
+          ;;
+      esac
+    fi
+    sleep 1
+  done
+  echo "⚠️ Warning: TUI readiness check timed out. Proceeding anyway..."
+}
+
+# inject_instructions <session_name> <instructions> [job_id]
+# Injects instructions into the tmux session using paste-buffer and C-m.
+inject_instructions() {
+  local sess="$1" instructions="$2" job_id="${3:-onboard}"
+  local local_tmux="tmux"
+  if [ -n "${TMUX_SERVER_NAME:-}" ] && [ "$TMUX_SERVER_NAME" != "default" ]; then
+    local_tmux="tmux -L $TMUX_SERVER_NAME"
+  fi
+  
+  $local_tmux set-buffer -b "job_buf_$job_id" "$instructions"
+  $local_tmux paste-buffer -b "job_buf_$job_id" -t "$sess"
+  sleep 0.5
+  $local_tmux send-keys -t "$sess" C-m
+  $local_tmux delete-buffer -b "job_buf_$job_id"
+}
+
 

.agents/skills/multi-agent-mux-create/SKILL.md

@@ -81,6 +81,11 @@ To prevent this, you can run this skill inside an **isolated tmux server** using
    ```bash
    bash scripts/create_session.sh --workspace /path/to/project --agent claude --role developer --submit-job "Task prompt here"
    ```
+4. **Onboard Integration**:
+   You can automatically submit a project alignment/orientation job to the new agent when creating a session:
+   ```bash
+   bash scripts/create_session.sh --workspace /path/to/project --agent claude --role developer --onboard
+   ```
 
 ### Recommended Alias
 You can set an alias in your shell to easily query sessions on the isolated server:

.agents/skills/multi-agent-mux-create/scripts/create_session.sh

@@ -34,6 +34,7 @@ Options:
   --dry-run           print commands without executing
   --tmux-server NAME  specify isolated tmux server name
   --submit-job PROMPT submit a job to multi-agent-mux-delegate-job registry with the given prompt
+  --onboard           automatically submit a project alignment/orientation job to the new agent
   -h, --help          this help
 EOF
 }
@@ -46,6 +47,7 @@ USE_WRAPPER=0
 DRY_RUN=0
 TMUX_SERVER_OPT=""
 SUBMIT_JOB_PROMPT=""
+ONBOARD=0
 
 while [ $# -gt 0 ]; do
   case "$1" in
@@ -57,6 +59,7 @@ while [ $# -gt 0 ]; do
     --dry-run)   DRY_RUN=1; shift ;;
     --tmux-server) TMUX_SERVER_OPT="$2"; shift 2 ;;
     --submit-job) SUBMIT_JOB_PROMPT="$2"; shift 2 ;;
+    --onboard)   ONBOARD=1; shift ;;
     -h|--help)   usage; exit 0 ;;
     *) echo "ERROR: unknown arg: $1" >&2; usage; exit 2 ;;
   esac
@@ -143,7 +146,7 @@ fi
 spawn
 
 # TUI 준비 대기
-sleep 6
+wait_for_tui_ready "$SESSION_NAME" "$AGENT"
 
 # pane 메타 캡처
 PANE_PID=$(_tmux list-panes -t "$SESSION_NAME" -F '#{pane_pid}' 2>/dev/null || echo "")
@@ -179,6 +182,15 @@ case "$AGENT" in
     ;;
 esac
 
+# If --onboard is specified, automatically build the onboarding prompt
+if [ "$ONBOARD" = "1" ] && [ -z "$SUBMIT_JOB_PROMPT" ]; then
+  SUBMIT_JOB_PROMPT="You are a newly spawned $ROLE Team Leader agent in this workspace. To align yourself with the project context, perform the following tasks:
+1. Read the project documentation at README.md and the multi-agent protocol guidelines at .agents/AGENT.md to understand the design rules.
+2. Run 'git status' and 'git diff' to analyze the current modifications and active work in the repository.
+3. Read .mam/agent-sessions.yaml to see other running agent sessions, their roles, and confirm your own assigned role: $ROLE.
+4. Once you have fully comprehended the project state, publish a completed event (using publish_event.py) with the detail 'Onboarding complete; aligned with role $ROLE'."
+fi
+
 # agent-sessions.yaml 에 append
 DELEGATE_JOB_ID=""
 if [ -n "$SUBMIT_JOB_PROMPT" ]; then
@@ -301,7 +313,22 @@ echo "=== created ==="
 echo "tmux session: $SESSION_NAME (pane pid $PANE_PID, cmd $PANE_CMD, cwd $PANE_CWD)"
 if [ -n "$DELEGATE_JOB_ID" ]; then
   echo "delegate job: $DELEGATE_JOB_ID"
-  delegate_publish_event "$DELEGATE_JOB_ID" started "multi-agent-mux session created"
+  
+  # Construct instructions matching multi-agent-mux-delegate-job format
+  pub="python3 .agents/skills/multi-agent-mux-delegate-job/scripts/publish_event.py --job $DELEGATE_JOB_ID"
+  instructions="Your job_id is \"$DELEGATE_JOB_ID\" (the one just registered for THIS delegation).
+
+On start run:        $pub --event started.
+On progress (optional): $pub --event progress --detail '<short status>'.
+On success run:      $pub --event completed --detail '<one-line summary>'.
+On failure run:      $pub --event error     --detail '<one-line reason>'.
+
+Task: $SUBMIT_JOB_PROMPT"
+
+  # Inject instructions into the tmux pane
+  inject_instructions "$SESSION_NAME" "$instructions" "$DELEGATE_JOB_ID"
+  
+  delegate_publish_event "$DELEGATE_JOB_ID" started "multi-agent-mux session created and instructions injected"
   WD_PID=$(start_watchdog "$DELEGATE_JOB_ID" "$WORKSPACE")
   echo "watchdog PID: $WD_PID"
 fi