tmpl/multi-agent-mux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: rename AGENT.md to MULTI_AGENT_RULES.md and consolidate INSTRUCTION.md into AGENTS.md

Browse Source 
- .agents/AGENT.md -> .agents/MULTI_AGENT_RULES.md
- .agents/AGENT.ko.md -> .agents/MULTI_AGENT_RULES.ko.md
- INSTRUCTION.md -> AGENTS.md (root-level)
- Update create_session.sh onboarding prompt to reference new path
- All cross-references in BOOTSTRAP.md/.ko.md, README.md/.ko.md, SKILL_FEATURES.md updated
- Fix document title headers (# AGENT.md -> # MULTI_AGENT_RULES.md, # CLAUDE.md -> # AGENTS.md)
This commit is contained in:
Godopu
2026-07-09 12:04:25 +09:00
parent 2b9bb39d6f
commit 0fa09b4d90
10 changed files with 36 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/AGENT.ko.md → .agents/MULTI_AGENT_RULES.ko.md
+6 -3
View File
@@ -1,9 +1,12 @@
# AGENT.md
# MULTI_AGENT_RULES.md
본 문서는 새로운 프로젝트에 **MQTT 메시징 백플레인 및 Tmux 기반 멀티 에이전트 오케스트레이션 워크플로우**를 도입하고, 협업하는 에이전트들이 일관된 규칙과 아키텍처에 따라 안전하고 견고하게 작업을 수행할 수 있도록 정의한 공통 지침 및 규약입니다.
새로운 프로젝트에서 작업하는 모든 에이전트는 작업을 시작하기 전 이 문서를 반드시 정독하고 규약을 준수해야 합니다.
> [!NOTE]
> 이 저장소는 두 가지 별도의 지침을 사용합니다: 범용 LLM 행동 지침([AGENTS.md](../AGENTS.md)) 및 프로젝트 고유의 멀티 에이전트 오케스트레이션 규약([.agents/MULTI_AGENT_RULES.md](MULTI_AGENT_RULES.md)).
---
## 1. 에이전트의 역할 정의 (Agent Roles)
@@ -134,7 +137,7 @@ TMUX 환경에서 실행되는 에이전트가 화면 스크롤 한계로 인해
- [ ] **디렉토리 규약**: 레지스트리 경로(`.mam/jobs/`) 및 로깅 경로(`.mam/delegate_job_logs/`)가 `.gitignore`에 등록되었는가?
- [ ] **스크립트 구비**: `mqtt_common.py`, `publish_event.py`, `job_subscriber.py`, `registry.py` 등의 핵심 모듈이 배치되었는가?
- [ ] **HMAC 활성화**: 새로운 레지스트리 잡 발급 시 난수 기반의 `auth_token`이 정상적으로 주입되고, 서명 기반의 상호 인증이 활성화되는가?
- [ ] **운영 헌장 배치**: 본 규약 파일(`AGENT.md`)이 새 프로젝트의 **.agents/ 디렉터리**에 배치되었는가? (프로젝트 루트를 깔끔하게 유지하면서도 온보딩하는 에이전트들이 규칙을 이해할 수 있도록 `.agents/` 경로 배치가 권장됩니다.)
- [ ] **운영 헌장 배치**: 본 규약 파일(`MULTI_AGENT_RULES.md`)이 새 프로젝트의 **.agents/ 디렉터리**에 배치되었는가? (프로젝트 루트를 깔끔하게 유지하면서도 온보딩하는 에이전트들이 규칙을 이해할 수 있도록 `.agents/` 경로 배치가 권장됩니다.)
---
@@ -148,7 +151,7 @@ TMUX 환경에서 실행되는 에이전트가 화면 스크롤 한계로 인해
bash .agents/skills/multi-agent-mux-create/scripts/create_session.sh --workspace "$(pwd)" --agent <agent> --role <role> --onboard
```
2. **에이전트 맥락 동기화**: 에이전트가 시작되면 아래 지시사항이 담긴 잡이 자동으로 인가됩니다:
- `README.md` 및 `.agents/AGENT.md`를 필독하여 설계 규약과 제약사항을 인지한다.
- `README.md` 및 `.agents/MULTI_AGENT_RULES.md`를 필독하여 설계 규약과 제약사항을 인지한다.
- `git status` 및 `git diff`를 실행하여 레포지토리의 활성 수정 내역을 분석한다.
- `.mam/agent-sessions.yaml`을 읽어 현재 러닝 상태인 타 에이전트 목록을 확인하고, 자신의 지정된 `role`을 검증한다.
3. **핸드셰이크 완료 발행**: 에이전트는 위의 맥락 파악 작업을 완료한 후, `publish_event.py`를 호출하여 다음과 같은 단말 완료 이벤트를 발행합니다:
.agents/AGENT.md → .agents/MULTI_AGENT_RULES.md
+6 -3
View File
@@ -1,9 +1,12 @@
# AGENT.md
# MULTI_AGENT_RULES.md
This document serves as the common guidelines and protocol for introducing the **MQTT messaging backplane and Tmux-based multi-agent orchestration workflow** to a new project. It defines the rules and architecture to ensure collaborating agents perform tasks safely, robustly, and consistently.
All agents working on a new project must read this document thoroughly and comply with the defined protocols before starting any tasks.
> [!NOTE]
> This repository uses two separate guides: the general LLM behavioral guidelines ([AGENTS.md](../AGENTS.md)) and the project-specific multi-agent orchestration guidelines ([.agents/MULTI_AGENT_RULES.md](MULTI_AGENT_RULES.md)).
---
## 1. Agent Roles Definition (Agent Roles)
@@ -134,7 +137,7 @@ Use this checklist when deploying this agent orchestration model to a new projec
- [ ] **Directory Convention**: Are the registry path (`.mam/jobs/`) and logging path (`.mam/delegate_job_logs/`) added to `.gitignore`?
- [ ] **Core Scripts**: Are the core scripts (`mqtt_common.py`, `publish_event.py`, `job_subscriber.py`, and `registry.py`) in place?
- [ ] **HMAC Enablement**: When a new registry job is created, is a random `auth_token` correctly injected, and is signature-based mutual authentication active?
- [ ] **Charter Placement**: Is this protocol file (`AGENT.md`) placed in the **.agents/ directory** of the new project? (Placing it in `.agents/` is essential to keep the project root clean while allowing onboarding agents to align on the rules.)
- [ ] **Charter Placement**: Is this protocol file (`MULTI_AGENT_RULES.md`) placed in the **.agents/ directory** of the new project? (Placing it in `.agents/` is essential to keep the project root clean while allowing onboarding agents to align on the rules.)
---
@@ -148,7 +151,7 @@ Newly spawned Team Leader agents must align their context using the `--onboard`
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.
- 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`.
3. **Handshake Publication**: The agent executes these orientation tasks and publishes a `completed` event to the broker (using `publish_event.py`) with:
.agents/skills/multi-agent-mux-create/scripts/create_session.sh
+1 -1
View File
@@ -185,7 +185,7 @@ 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.
1. Read the project documentation at README.md and the multi-agent protocol guidelines at .agents/MULTI_AGENT_RULES.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'."
INSTRUCTION.md → AGENTS.md
+5 -2
View File
@@ -1,7 +1,10 @@
# CLAUDE.md
# AGENTS.md
Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
> [!NOTE]
> This repository uses two separate guides: the general LLM behavioral guidelines ([AGENTS.md](AGENTS.md)) and the project-specific multi-agent orchestration guidelines ([.agents/MULTI_AGENT_RULES.md](.agents/MULTI_AGENT_RULES.md)).
**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
## 1. Think Before Coding
@@ -64,4 +67,4 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
Read .agents/AGENT.md first before working and follow the instructions for orchestration.
Read [MULTI_AGENT_RULES.md](.agents/MULTI_AGENT_RULES.md) (or [Korean version](.agents/MULTI_AGENT_RULES.ko.md)) and [multi_agent_workflow.md](.agents/multi_agent_workflow.md) first before working and follow the instructions for orchestration and collaboration.
BOOTSTRAP.ko.md
+4 -4
View File
@@ -11,8 +11,8 @@
본 프로젝트를 새로운 환경에 복제(Clone)한 후, 핵심 구성 요소들의 위치와 역할을 먼저 파악해야 합니다.
* `.agents/`: 오케스트레이션 및 에이전트 커스텀 스킬 디렉터리
* `AGENT.md`: 에이전트 간의 역할 분담(PM, Worker, Reviewer) 및 이벤트 발행 규약 정의
* `AGENT.ko.md`: 에이전트 간의 역할 분담(PM, Worker, Reviewer) 및 이벤트 발행 규약 정의 (한국어)
* `MULTI_AGENT_RULES.md`: 에이전트 간의 역할 분담(PM, Worker, Reviewer) 및 이벤트 발행 규약 정의
* `MULTI_AGENT_RULES.ko.md`: 에이전트 간의 역할 분담(PM, Worker, Reviewer) 및 이벤트 발행 규약 정의 (한국어)
* `skills/`: 멀티 에이전트 구동 및 비동기 잡 처리를 수행하는 셸 스크립트 모음
* `lib.sh`: 오케스트레이션의 핵심 셸 함수 및 가상환경(venv) 자동 연동 라이브러리
* `multi-agent-mux-create/`: 격리된 tmux 에이전트 세션을 시작하는 스크립트
@@ -80,7 +80,7 @@ curl -fsSL https://git.godopu.com/tmpl/multi-agent-mux/raw/branch/main/deploy/in
> [!WARNING]
> **보안 모드 기본값 안내**:
> 시스템의 기본 설정은 **무인증 PoC 모드**입니다. 잡 등록 시 `auth_token`이 명시적으로 주입되지 않으면(또는 `null`인 경우) HMAC 서명 검증이 생략됩니다.
> 공개 브로커 사용 환경이나 실제 프로덕션 단계에서는 잡 등록 시 `auth_token`을 고유 난수값으로 생성 및 주입하여 HMAC 보안 서명을 활성화해야 합니다. (자세한 보안 규약은 [MESSAGING.md](./MESSAGING.md) 및 [AGENT.ko.md](.agents/AGENT.ko.md)의 `2.3 보안 프로토콜` 섹션을 참조하십시오. 현재 CLI를 통한 자동 토큰 생성/주입 기능 지원은 향후 로드맵의 `FW-N6` 과제로 처리 예정입니다.)
> 공개 브로커 사용 환경이나 실제 프로덕션 단계에서는 잡 등록 시 `auth_token`을 고유 난수값으로 생성 및 주입하여 HMAC 보안 서명을 활성화해야 합니다. (자세한 보안 규약은 [MESSAGING.md](./MESSAGING.md) 및 [MULTI_AGENT_RULES.ko.md](.agents/MULTI_AGENT_RULES.ko.md)의 `2.3 보안 프로토콜` 섹션을 참조하십시오. 현재 CLI를 통한 자동 토큰 생성/주입 기능 지원은 향후 로드맵의 `FW-N6` 과제로 처리 예정입니다.)
---
@@ -180,6 +180,6 @@ rm -f ".mam/jobs/$JID.json" ".mam/jobs/$JID.lock"
## 7. 에이전트 온보딩 가이드 (New Agent Onboarding)
본 환경 구축을 무사히 마쳤다면, 협업하는 에이전트는 즉시 .agents/ 디렉터리에 있는 **[AGENT.ko.md](.agents/AGENT.ko.md)** 문서를 읽어야 합니다.
본 환경 구축을 무사히 마쳤다면, 협업하는 에이전트는 즉시 .agents/ 디렉터리에 있는 **[MULTI_AGENT_RULES.ko.md](.agents/MULTI_AGENT_RULES.ko.md)** 문서를 읽어야 합니다.
해당 문서에는 에이전트가 각 역할(PM, Worker, Reviewer)로 구동될 때 지켜야 할 **수술적 변경 규칙, 교차 검증 통과 규약, Tmux 뷰포트 유실 방지를 위한 스냅샷 패턴** 등이 서술되어 있어 안정적인 멀티 에이전트 워크플로우에 즉시 기여할 수 있도록 돕습니다.
BOOTSTRAP.md
+4 -4
View File
@@ -11,8 +11,8 @@ A new agent can follow the steps in this guide sequentially to establish a stabl
Before cloning this project into a new environment, you must first understand the locations and roles of its core components:
* `.agents/`: Orchestration and custom agent skills root.
* `AGENT.md`: Definition of agent roles (PM, Worker, Reviewer) and event publication rules.
* `AGENT.ko.md`: Definition of agent roles (PM, Worker, Reviewer) and event publication rules (Korean).
* `MULTI_AGENT_RULES.md`: Definition of agent roles (PM, Worker, Reviewer) and event publication rules.
* `MULTI_AGENT_RULES.ko.md`: Definition of agent roles (PM, Worker, Reviewer) and event publication rules (Korean).
* `skills/`: A collection of shell scripts that execute multi-agent coordination and asynchronous job processing.
* `lib.sh`: The core orchestration shell functions and virtual environment (venv) auto-loading library.
* `multi-agent-mux-create/`: Script to launch isolated tmux agent sessions.
@@ -80,7 +80,7 @@ Open the generated `.env` file to configure settings as needed.
> [!WARNING]
> **Security Mode Default Warning**:
> The system's default setting is the **unauthenticated PoC mode**. If an `auth_token` is not explicitly provided (or is `null`) during job registration, HMAC signature verification is skipped.
> In a public broker environment or production phase, you must generate and inject a unique random `auth_token` during job registration to enable HMAC signature security. (For detailed security protocols, refer to section `2.3 Security Protocol` in [MESSAGING.md](./MESSAGING.md) and [AGENT.md](.agents/AGENT.md). Automated token generation and injection via CLI is on the roadmap under task `FW-N6`.)
> In a public broker environment or production phase, you must generate and inject a unique random `auth_token` during job registration to enable HMAC signature security. (For detailed security protocols, refer to section `2.3 Security Protocol` in [MESSAGING.md](./MESSAGING.md) and [MULTI_AGENT_RULES.md](.agents/MULTI_AGENT_RULES.md). Automated token generation and injection via CLI is on the roadmap under task `FW-N6`.)
---
@@ -181,6 +181,6 @@ rm -f ".mam/jobs/$JID.json" ".mam/jobs/$JID.lock"
## 7. Onboarding Collaborating Agents (New Agent Onboarding)
Once the setup is verified, onboarding agents should immediately read the **[AGENT.md](.agents/AGENT.md)** guidelines in the .agents/ directory.
Once the setup is verified, onboarding agents should immediately read the **[MULTI_AGENT_RULES.md](.agents/MULTI_AGENT_RULES.md)** guidelines in the .agents/ directory.
The guidelines describe essential workflows—such as **surgical change constraints, cross-verification review loops, and pane snapshotting to prevent viewport truncation**—allowing new agents to quickly and safely integrate with the multi-agent workflow.
README.ko.md
+4 -4
View File
@@ -138,8 +138,8 @@ sequenceDiagram
```text
.
├── .agents/
│ ├── AGENT.md # 에이전트 역할 행동 강령 및 뷰포트 스냅샷 규칙
│ ├── AGENT.ko.md # 에이전트 역할 행동 강령 (한국어 백업)
│ ├── MULTI_AGENT_RULES.md # 에이전트 역할 행동 강령 및 뷰포트 스냅샷 규칙
│ ├── MULTI_AGENT_RULES.ko.md # 에이전트 역할 행동 강령 (한국어 백업)
│ └── skills/ # 코어 오케스트레이션 셸 스크립트 및 라이브러리
│ ├── lib.sh # 공통 오케스트레이션 셸 함수 라이브러리
│ ├── multi-agent-mux-create/
@@ -188,6 +188,6 @@ sequenceDiagram
## 📝 협업 에이전트 준수 사항
이 프로젝트에 새로 합류한 에이전트는 다음 규칙을 준수해야 합니다:
1. **[AGENT.md](.agents/AGENT.md)** 문서를 정독하여 프로젝트 매니저(PM), 작업자(Worker), 리뷰어(Reviewer) 간의 역할 및 개발 제약조건을 인지하십시오.
2. 장시간 명령을 실행하는 경우 터미널 스크롤백 로그 유실을 방지하기 위해 `AGENT.md` (제4장)에 기재된 **뷰포트 스냅샷 규칙(Pane Snapshotting Rules)**을 반드시 적용하십시오.
1. **[MULTI_AGENT_RULES.md](.agents/MULTI_AGENT_RULES.md)** 문서를 정독하여 프로젝트 매니저(PM), 작업자(Worker), 리뷰어(Reviewer) 간의 역할 및 개발 제약조건을 인지하십시오.
2. 장시간 명령을 실행하는 경우 터미널 스크롤백 로그 유실을 방지하기 위해 `MULTI_AGENT_RULES.md` (제4장)에 기재된 **뷰포트 스냅샷 규칙(Pane Snapshotting Rules)**을 반드시 적용하십시오.
3. 리뷰어 세션에 diff 검증을 요청하기 전에는 어떠한 코어 파일의 임의 수정도 프로덕션 브랜치에 승인 없이 머지할 수 없습니다.
README.md
+4 -4
View File
@@ -156,8 +156,8 @@ To ensure communication integrity across public MQTT brokers, the backplane inte
```text
.
├── .agents/
│ ├── AGENT.md # Agent roles, snapshottings, and execution charter
│ ├── AGENT.ko.md # Agent roles, snapshottings, and execution charter (Korean)
│ ├── MULTI_AGENT_RULES.md # Agent roles, snapshottings, and execution charter
│ ├── MULTI_AGENT_RULES.ko.md # Agent roles, snapshottings, and execution charter (Korean)
│ └── skills/ # Core orchestration shell wrappers & libraries
│ ├── lib.sh # Shared orchestration library
│ ├── multi-agent-mux-create/
@@ -205,6 +205,6 @@ For detailed setup instructions, please consult the **[BOOTSTRAP.md](./BOOTSTRAP
## 📝 Guidelines for Collaborating Agents
If you are an AI agent newly onboarded to this project:
1. Read **[AGENT.md](.agents/AGENT.md)** to align on development constraints and roles (PM, Worker, Reviewer).
2. Adhere to the **Pane Snapshotting Rules** in `AGENT.md` (Section 4) to prevent scrollback data loss during long execution steps.
1. Read **[MULTI_AGENT_RULES.md](.agents/MULTI_AGENT_RULES.md)** to align on development constraints and roles (PM, Worker, Reviewer).
2. Adhere to the **Pane Snapshotting Rules** in `MULTI_AGENT_RULES.md` (Section 4) to prevent scrollback data loss during long execution steps.
3. Never modify core logic without submitting a diff to the reviewer sessions for evaluation.
SKILL_FEATURES.md
+1 -1
View File
@@ -48,7 +48,7 @@
* **역할 불변성 보장**: 에이전트 생성 시 부여된 역할(`role`)은 사후 수정이 불가하며, 임의 변경 시도 시 데이터 검증(`atomic_dump_yaml`) 단계에서 예외 처리되어 방어됨.
* **TUI 로딩 동적 감지 (Readiness Gating)**: 고정 지연(`sleep 6`)을 탈피하여 각 에이전트별 시작 화면 출력 문자열(예: `Antigravity`, `Hermes`, `Claude`, `Cline`)을 실시간으로 감지(`capture-pane` 폴링)하여 로딩 완료 시점을 동적으로 감지함.
* **자동 온보딩 및 지시사항 주입 (Auto Onboarding & Instruction Injection)**:
* `--onboard` 플래그를 통해 신규 팀장 에이전트 구동 직후 워크스페이스 맥락(README.md, AGENT.md, git status/diff, 타 세션 역할 분석)을 자율적으로 파악하도록 표준 온보딩 지시서 잡을 자동 생성 및 인젝션함.
* `--onboard` 플래그를 통해 신규 팀장 에이전트 구동 직후 워크스페이스 맥락(README.md, MULTI_AGENT_RULES.md, git status/diff, 타 세션 역할 분석)을 자율적으로 파악하도록 표준 온보딩 지시서 잡을 자동 생성 및 인젝션함.
* `--submit-job` 및 `--onboard` 지시서 입력을 `tmux` 페이스트 버퍼 및 엔터 키스트로크(`inject_instructions`)를 통해 에이전트 TUI 스트림에 자동 전달함.
### 3.2. `multi-agent-mux-resume` (재개 스킬)
deploy/install.sh
+1 -1
View File
@@ -128,7 +128,7 @@ if ! check_assets_present "."; then
# Copy non-dev documents if they don't already exist.
# We skip dev-specific docs like README.md, DONE.md, and FUTURE_WORKS.md.
for doc in MESSAGING.md BOOTSTRAP.md BOOTSTRAP.ko.md INSTRUCTION.md; do
for doc in MESSAGING.md BOOTSTRAP.md BOOTSTRAP.ko.md AGENTS.md; do
if [ -f "$STAGE_DIR/$doc" ] && [ ! -e "$doc" ]; then
cp "$STAGE_DIR/$doc" . || { echo "❌ Error: Failed to copy $doc" >&2; exit 1; }
echo "$doc" >> "$MANIFEST_FILE"