From 0fa09b4d90bd59e5bb96621ef4fec3063f90095a Mon Sep 17 00:00:00 2001 From: Godopu Date: Thu, 9 Jul 2026 12:04:25 +0900 Subject: [PATCH] refactor: rename AGENT.md to MULTI_AGENT_RULES.md and consolidate INSTRUCTION.md into AGENTS.md - .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) --- .agents/{AGENT.ko.md => MULTI_AGENT_RULES.ko.md} | 9 ++++++--- .agents/{AGENT.md => MULTI_AGENT_RULES.md} | 9 ++++++--- .../multi-agent-mux-create/scripts/create_session.sh | 2 +- INSTRUCTION.md => AGENTS.md | 7 +++++-- BOOTSTRAP.ko.md | 8 ++++---- BOOTSTRAP.md | 8 ++++---- README.ko.md | 8 ++++---- README.md | 8 ++++---- SKILL_FEATURES.md | 2 +- deploy/install.sh | 2 +- 10 files changed, 36 insertions(+), 27 deletions(-) rename .agents/{AGENT.ko.md => MULTI_AGENT_RULES.ko.md} (95%) rename .agents/{AGENT.md => MULTI_AGENT_RULES.md} (95%) rename INSTRUCTION.md => AGENTS.md (81%) diff --git a/.agents/AGENT.ko.md b/.agents/MULTI_AGENT_RULES.ko.md similarity index 95% rename from .agents/AGENT.ko.md rename to .agents/MULTI_AGENT_RULES.ko.md index 660e437..1713457 100644 --- a/.agents/AGENT.ko.md +++ b/.agents/MULTI_AGENT_RULES.ko.md @@ -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 --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`를 호출하여 다음과 같은 단말 완료 이벤트를 발행합니다: diff --git a/.agents/AGENT.md b/.agents/MULTI_AGENT_RULES.md similarity index 95% rename from .agents/AGENT.md rename to .agents/MULTI_AGENT_RULES.md index aa9b70f..28730c3 100644 --- a/.agents/AGENT.md +++ b/.agents/MULTI_AGENT_RULES.md @@ -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 --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: 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 2096b37..ebac352 100755 --- a/.agents/skills/multi-agent-mux-create/scripts/create_session.sh +++ b/.agents/skills/multi-agent-mux-create/scripts/create_session.sh @@ -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'." diff --git a/INSTRUCTION.md b/AGENTS.md similarity index 81% rename from INSTRUCTION.md rename to AGENTS.md index 87269c7..f239e30 100644 --- a/INSTRUCTION.md +++ b/AGENTS.md @@ -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. \ No newline at end of file +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. \ No newline at end of file diff --git a/BOOTSTRAP.ko.md b/BOOTSTRAP.ko.md index 1ca3b52..326c999 100644 --- a/BOOTSTRAP.ko.md +++ b/BOOTSTRAP.ko.md @@ -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 뷰포트 유실 방지를 위한 스냅샷 패턴** 등이 서술되어 있어 안정적인 멀티 에이전트 워크플로우에 즉시 기여할 수 있도록 돕습니다. diff --git a/BOOTSTRAP.md b/BOOTSTRAP.md index 9d78a09..7934155 100644 --- a/BOOTSTRAP.md +++ b/BOOTSTRAP.md @@ -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. diff --git a/README.ko.md b/README.ko.md index e84771a..a920c36 100644 --- a/README.ko.md +++ b/README.ko.md @@ -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 검증을 요청하기 전에는 어떠한 코어 파일의 임의 수정도 프로덕션 브랜치에 승인 없이 머지할 수 없습니다. diff --git a/README.md b/README.md index 0ea9cfb..267d149 100644 --- a/README.md +++ b/README.md @@ -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. \ No newline at end of file diff --git a/SKILL_FEATURES.md b/SKILL_FEATURES.md index 8096b37..99af5d8 100644 --- a/SKILL_FEATURES.md +++ b/SKILL_FEATURES.md @@ -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` (재개 스킬) diff --git a/deploy/install.sh b/deploy/install.sh index e9de81d..c22b170 100644 --- a/deploy/install.sh +++ b/deploy/install.sh @@ -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"