From 65843e0557b911d11cebbbbbf977f1a2c9da7886 Mon Sep 17 00:00:00 2001 From: Godopu Date: Sun, 12 Jul 2026 13:50:30 +0900 Subject: [PATCH] docs(rules): update multi-agent rules with job-centric structure pointers - Document automated job brief path under .mam/jobs//brief.md - Document automated report redirection under .mam/jobs//-reports/report-final.md - Correct stop_session.sh report cleanup claim to reflect manual cleanup - Clarify onboarding brief mechanism under onboarding handshake protocol --- .agents/MULTI_AGENT_RULES.ko.md | 19 +++++++++++-------- .agents/MULTI_AGENT_RULES.md | 17 ++++++++++------- 2 files changed, 21 insertions(+), 15 deletions(-) diff --git a/.agents/MULTI_AGENT_RULES.ko.md b/.agents/MULTI_AGENT_RULES.ko.md index 55349e7..8f40267 100644 --- a/.agents/MULTI_AGENT_RULES.ko.md +++ b/.agents/MULTI_AGENT_RULES.ko.md @@ -121,13 +121,15 @@ TMUX 환경에서 실행되는 에이전트가 화면 스크롤 한계로 인해 ### 📄 마크다운 기반 협업 및 결과 전달 (Markdown-Based Workflow & Communication) - **핵심 원칙**: TMUX `send-keys`나 입력 버퍼를 통해 긴 지시사항을 직렬로 입력하는 과정에서 문자 누락이나 레이아웃 유실이 발생하는 것을 방지하기 위해, 에이전트 간의 모든 주요 협업 소통은 파일 기반 마크다운 문서 생성을 원칙으로 합니다. - **세부 규칙 및 규약**: - - **예외 사항**: 1~2줄 내외의 매우 단순한 재평가 요청, 상태 확인, 수락 진행 등의 단발성 프롬프트는 기존처럼 tmux 입력을 통해 직접 보낼 수 있습니다. - - **작업 위임**: 상세 사양과 계획 수립 등의 복잡한 작업 지시는 먼저 로컬 마크다운 파일(예: `.mam/reports/brief-.md` 또는 지정된 워크스페이스 경로)로 작성한 후, 에이전트에게 `"Read <파일경로> and execute."` 라는 단순화된 실행 명령만 전달하십시오. - - **결과 안내 및 피드백**: 상세 리뷰 결과, 설계 제안서, 구현 완료 리포트 및 감사 주석 등은 반드시 마크다운 파일로 영속화하여 제공해야 합니다. 기계 전용인 잡 레지스트리 평면(`.mam/jobs/`)과의 물리적 분리를 위해, 모든 에이전트는 `.mam/reports//` 아래에 전용 디렉터리를 형성하고 결과 보고 마크다운 파일을 저장해야 합니다 (여기서 ``은 `.mam/agent-sessions.yaml`의 `name` 필드와 완전히 일치해야 합니다. 예: `.mam/reports/-creator-/report-.md`). 수신 에이전트는 잘린 터미널 화면 캡처에 의존하는 대신 디스크에서 해당 파일을 직접 로드하여 확인합니다. - - **디스크 정리 및 보존 정책 계약 (Cleanup & Retention)**: - - `.mam/reports/` 폴더 아래의 파일들은 감사 이력(audit-trail) 산출물로 보존됩니다. - - 해당 격리 디렉터리들은 `stop_session.sh` 등을 통해 세션이 정상적으로 종료되거나 파기(`--purge-conversation`)될 때 자동으로 함께 정리되어야 합니다. - - 버전 관리가 필요한 영구 보존용 주요 산출물(최종 설계 계획, 최종 리뷰 보고서, 보안 감사 리포트 등)은 gitignore 대상인 `.mam/` 하위가 아닌, 버전 관리 대상 경로(구체적으로 `.agents/reports//` 또는 `docs/reports/` 등)로 명시적으로 복사하여 기록을 이관 보존해야 합니다. + - **예외 사항**: 1~2줄 내외의 매우 단순한 요청, 상태 확인, 수락 진행 등의 단발성 프롬프트는 tmux 입력을 통해 직접 보낼 수 있습니다. + - **작업 위임**: + - *수동 경로*: 상세 사양과 계획 수립 등의 복잡한 작업 지시는 먼저 로컬 마크다운 파일(예: `.mam/reports/brief-.md` 또는 지정된 워크스페이스 경로)로 작성한 후, 에이전트에게 `"Read <파일경로> and execute."` 라는 실행 명령만 전달하십시오. + - *자동 경로*: 자동화 잡 런너(`multi-agent-mux-delegate-job submit`)는 잡 등록 시 `.mam/jobs//brief.md` 디렉터리에 지시서를 자동 집필하고 단일 라인 포인터 프롬프트만 에이전트 세션에 인가합니다. + - **결과 안내 및 피드백**: + - *수동/영구 리뷰*: 상세 리뷰 결과, 설계 제안서 등은 `.mam/reports//report-.md` 경로에 저장합니다. + - *자동화 잡 보고서*: 자동 위임된 비동기 작업의 완료 결과는 잡 디렉터리 하위인 `.mam/jobs//-reports/report-final.md` 경로에 기록해야 합니다. + - *버전 관리 이관*: 버전 관리가 필요한 주요 산출물(최종 설계 계획, 최종 리뷰 보고서, 보안 감사 리포트 등)은 gitignore 대상인 `.mam/` 하위가 아닌, 버전 관리 대상 경로(구체적으로 `.agents/reports//` 또는 `docs/reports/` 등)로 명시적으로 복사하여 이관 보존해야 합니다. + - **디스크 정리 및 보존 정책 계약 (Cleanup & Retention)**: `.mam/jobs//` 및 `.mam/reports/` 폴더 아래의 파일들은 휘발성 감사 이력(audit-trail) 산출물입니다. 버전 관리가 필요한 문서들은 `.agents/reports/` 하위로 수동 복사하여 커밋해야 하며, `stop_session.sh` 세션 종료 스크립트는 이들 보고서 디렉터리를 자동으로 삭제하지 않으므로 수동 또는 주기적 클린업이 권장됩니다. ### ⏱️ 타임아웃 구성 및 정렬 규칙 - **잡 실행 제한 (`timeout_sec` & `idle_timeout_sec`)**: 각 잡은 전체 실행 만료 시간(`timeout_sec`, 기본 3600s)과 메세지 미수신 유휴 시간(`idle_timeout_sec`, 기본 120s)을 독립적으로 가집니다. @@ -157,7 +159,8 @@ TMUX 환경에서 실행되는 에이전트가 화면 스크롤 한계로 인해 ```bash bash .agents/skills/multi-agent-mux-create/scripts/create_session.sh --workspace "$(pwd)" --agent --role --onboard ``` -2. **에이전트 맥락 동기화**: 에이전트가 시작되면 아래 지시사항이 담긴 잡이 자동으로 인가됩니다: + 이 자동화된 온보딩 워크플로우는 백그라운드 잡을 등록하여 `.mam/jobs//brief.md` 에 온보딩 지시서를 작성하고 에이전트 세션에 지시서 포인터만 입력합니다. +2. **에이전트 맥락 동기화**: 에이전트가 시작되면 아래 지시사항이 담긴 온보딩 brief를 자동으로 수임하여 확인합니다: - `README.md` 및 `.agents/MULTI_AGENT_RULES.md`를 필독하여 설계 규약과 제약사항을 인지한다. - `git status` 및 `git diff`를 실행하여 레포지토리의 활성 수정 내역을 분석한다. - `.mam/agent-sessions.yaml`을 읽어 현재 러닝 상태인 타 에이전트 목록을 확인하고, 자신의 지정된 `role`을 검증한다. diff --git a/.agents/MULTI_AGENT_RULES.md b/.agents/MULTI_AGENT_RULES.md index 23b7af6..e9b83cd 100644 --- a/.agents/MULTI_AGENT_RULES.md +++ b/.agents/MULTI_AGENT_RULES.md @@ -122,12 +122,14 @@ To ensure that agents running in TMUX environments do not lose debug logs or pre - **Core Principle**: To prevent TUI character loss, truncation, and layout breakage during sequential input typing, all collaborative workflows must favor file-based markdown communication. - **Rules & Protocols**: - **Exception**: Extremely simple prompts (e.g., "Re-evaluate", "Check status", "Proceed") of 1 or 2 lines may be sent directly via tmux input buffers. - - **Task Delegation**: All detailed task briefs, specifications, and instructions must be written to a local Markdown file (e.g., `.mam/reports/brief-.md` or a workspace path) first. The sender then issues a simple trigger command: `"Read and execute."` - - **Result Reporting & Feedback**: All detailed review results, design proposals, implementation reports, and audit comments must be saved as Markdown files. To separate human-readable documents from the machine job registry (`.mam/jobs/`), every agent must save its outputs under `.mam/reports//` (using the full tmux session name matching the `name` field in `.mam/agent-sessions.yaml`, e.g., `.mam/reports/-creator-/report-.md`) to ensure strict isolation across multiple roles/instances. - - **Cleanup & Retention Contract**: - - Files under `.mam/reports/` are audit-trail artifacts. - - These folders should be cleaned up automatically during `stop_session.sh` when a session is gracefully stopped or purged (`--purge-conversation`). - - Durable outcomes (such as final design plans, review verdicts, or security audit reports) that require version control must be explicitly copied to tracked directory paths (specifically under `.agents/reports//` or `docs/reports/`) to preserve collaborative audit trails in version history, instead of remaining in the gitignored `.mam/` runtime tree. + - **Task Delegation**: + - *Manual path*: Detailed task briefs may be written to a local Markdown file (e.g., `.mam/reports/brief-.md` or a workspace path) first. The sender then issues a simple trigger command: `"Read and execute."` + - *Automated path*: The automated job runner (`multi-agent-mux-delegate-job submit`) automatically provisions the brief at `.mam/jobs//brief.md` and sends a short pointer instruction to the agent. + - **Result Reporting & Feedback**: + - *Manual/Durable reviews*: Detailed reviews, design proposals, or audit reports must be saved under `.mam/reports//report-.md`. + - *Automated job reports*: Automated execution results are saved directly to `.mam/jobs//-reports/report-final.md` as transient files. + - *Versioned promotions*: Any final design plans, review verdicts, or security audit reports that require version control must be explicitly copied to tracked directory paths (specifically under `.agents/reports//` or `docs/reports/`). + - **Cleanup & Retention Contract**: Files under `.mam/jobs//` and `.mam/reports/` are transient audit-trail artifacts. While durable outcomes are committed to version control under `.agents/reports/`, ephemeral directory trees can be cleaned up manually as needed; `stop_session.sh` does not automatically purge these report trees during session exit. ### ⏱️ Timeout Configuration & Alignment Rules - **Job Execution Limits (`timeout_sec` & `idle_timeout_sec`)**: Each job independently manages its overall execution timeout (`timeout_sec`, default 3600s) and idle timeout without receiving messages (`idle_timeout_sec`, default 120s). @@ -157,7 +159,8 @@ Newly spawned Team Leader agents must align their context using the `--onboard` ```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: + This automated onboarding workflow registers a job, provisioning the brief under `.mam/jobs//brief.md` and sending a short pointer to the agent session. +2. **Orienting the Agent**: The agent session starts up and automatically receives the registered onboarding brief instructing it to: - Read `README.md` and `.agents/MULTI_AGENT_RULES.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`.