From ef57749e9fced07349f3a3319bd3d35397330bb1 Mon Sep 17 00:00:00 2001 From: Godopu Date: Sun, 28 Jun 2026 10:42:23 +0900 Subject: [PATCH] feat: implement --onboard flag in multi-agent-mux-create and update AGENT.md onboarding handshake protocol --- .agents/AGENT.ko.md | 19 ++++++ .agents/AGENT.md | 19 ++++++ .agents/skills/lib.sh | 63 +++++++++++++++++++ .../skills/multi-agent-mux-create/SKILL.md | 5 ++ .../scripts/create_session.sh | 31 ++++++++- 5 files changed, 135 insertions(+), 2 deletions(-) diff --git a/.agents/AGENT.ko.md b/.agents/AGENT.ko.md index d7b5d67..660e437 100644 --- a/.agents/AGENT.ko.md +++ b/.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 --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 "` +4. **총괄 매니저 승인 게이트**: 총괄 매니저는 이 `completed` 핸드셰이크 신호가 오디팅 로그에 수렴될 때까지 대기(gating)해야 하며, 핸드셰이크가 통과된 것이 검증된 이후에야 해당 세션에 실무 또는 검수 작업을 위임합니다. + +--- + *본 가이드는 협업 효율성과 코드 보안의 엄격한 균형을 유지하기 위한 규범입니다. 변경 사항이 필요한 경우 총괄 매니저 및 전체 팀장의 합의를 거쳐 본 문서를 업데이트해야 합니다.* \ No newline at end of file diff --git a/.agents/AGENT.md b/.agents/AGENT.md index ed68ac9..aa9b70f 100644 --- a/.agents/AGENT.md +++ b/.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 --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 "` +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.* \ No newline at end of file diff --git a/.agents/skills/lib.sh b/.agents/skills/lib.sh index f4fb789..4330a6b 100644 --- a/.agents/skills/lib.sh +++ b/.agents/skills/lib.sh @@ -826,4 +826,67 @@ start_watchdog() { echo "$pid" } +# wait_for_tui_ready +# 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 [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" +} + diff --git a/.agents/skills/multi-agent-mux-create/SKILL.md b/.agents/skills/multi-agent-mux-create/SKILL.md index 76cacfb..0d99483 100644 --- a/.agents/skills/multi-agent-mux-create/SKILL.md +++ b/.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: diff --git a/.agents/skills/multi-agent-mux-create/scripts/create_session.sh b/.agents/skills/multi-agent-mux-create/scripts/create_session.sh index f8a2261..02b37c2 100755 --- a/.agents/skills/multi-agent-mux-create/scripts/create_session.sh +++ b/.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 ''. +On success run: $pub --event completed --detail ''. +On failure run: $pub --event error --detail ''. + +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