diff --git a/BOOTSTRAP.ko.md b/BOOTSTRAP.ko.md index cc6c3f4..1ca3b52 100644 --- a/BOOTSTRAP.ko.md +++ b/BOOTSTRAP.ko.md @@ -31,11 +31,29 @@ --- -## 2. 환경 설정 파일 생성 (.env) +## 2. 워크스페이스 프로비저닝 (단계 0 — 참고용) + +에이전트가 이 안내서를 읽기 전에 워크스페이스 설치가 선행되어야 합니다. 이 단계는 이미 개발자(사람)가 설치기를 통해 수행 완료한 상태입니다. 에이전트가 환경 검증 작업을 수행할 때 파일들이 어떤 경로로 복사되고 설치되었는지에 대한 기초 사실(Reference)을 제공하기 위해 여기에 기록해 둡니다. + +### 단계 0.1: 설치 스크립트 실행 (이미 기수행됨) +인스톨러를 통해 워크스페이스를 기동하기 위해 사람이 다음 명령을 구동하였습니다: + +```bash +curl -fsSL https://git.godopu.com/tmpl/multi-agent-mux/raw/branch/main/deploy/install.sh | bash +``` + +인스톨러는 시스템 의존성 유효성을 검증하고 리포지토리를 불러와 오케스트레이션을 위한 `.agents/` 스켈레톤 및 관련 문서 파일(본 `BOOTSTRAP.ko.md` 포함)을 복사하고 `.env` 및 `.venv` 가상환경 설정을 자동으로 수행했습니다. + +> [!NOTE] +> **검증 전용 경고**: 본 가이드를 읽고 있는 AI 에이전트는 인스톨러 스크립트를 스스로 **다시 실행해서는 안 됩니다.** 즉시 환경 변수 설정 및 검증 테스트 단계로 넘어가십시오. + +--- + +## 3. 환경 설정 파일 생성 (.env) 메시징 브로커 설정 및 실행 경로를 설정하기 위해 로컬 환경 설정 파일(`.env`)을 생성하고 수정해야 합니다. -### 단계 2.1: 자동 생성 스크립트 실행 +### 단계 3.1: 자동 생성 스크립트 실행 프로젝트 루트에서 제공되는 환경 설정 템플릿 복사 스크립트를 실행합니다. ```bash @@ -46,7 +64,7 @@ ./scripts/generate-env.sh --force ``` -### 단계 2.2: 환경 변수 수정 및 설정 +### 단계 3.2: 환경 변수 수정 및 설정 생성된 `.env` 파일을 열어 설정을 필요에 따라 구성합니다. > [!NOTE] @@ -66,11 +84,11 @@ --- -## 3. 의존성 및 가상환경 설정 (Venv Setup) +## 4. 의존성 및 가상환경 설정 (Venv Setup) 오케스트레이션 및 MQTT 메시징을 구동하기 위한 Python 3 의존성을 설정합니다. -### 단계 3.1: Python 가상환경 구축 +### 단계 4.1: Python 가상환경 구축 프로젝트 루트에서 `.venv` 가상환경을 생성하고 활성화합니다. ```bash @@ -81,7 +99,7 @@ python3 -m venv .venv source .venv/bin/activate ``` -### 단계 3.2: 의존성 패키지 설치 +### 단계 4.2: 의존성 패키지 설치 `multi-agent-mux-delegate-job` 디렉터리에 기재된 `requirements.txt` 의존성 목록을 가상환경에 설치합니다. ```bash @@ -91,7 +109,7 @@ pip install -r .agents/skills/multi-agent-mux-delegate-job/requirements.txt --- -## 4. 디렉터리 준비 및 보안 감시 가이드 +## 5. 디렉터리 준비 및 보안 감시 가이드 에이전트 제어 상태 및 잡 기록을 위해 로컬 레지스트리 디렉터리가 정상적으로 생성되었는지 확인합니다. @@ -112,7 +130,7 @@ pip install -r .agents/skills/multi-agent-mux-delegate-job/requirements.txt --- -## 5. 실행 환경 검증 및 부트스트랩 테스트 +## 6. 실행 환경 검증 및 부트스트랩 테스트 환경 구축이 오작동 없이 안전하게 완료되었는지 아래의 체크리스트를 실행해 검증합니다. @@ -160,7 +178,7 @@ rm -f ".mam/jobs/$JID.json" ".mam/jobs/$JID.lock" --- -## 6. 에이전트 온보딩 가이드 (New Agent Onboarding) +## 7. 에이전트 온보딩 가이드 (New Agent Onboarding) 본 환경 구축을 무사히 마쳤다면, 협업하는 에이전트는 즉시 .agents/ 디렉터리에 있는 **[AGENT.ko.md](.agents/AGENT.ko.md)** 문서를 읽어야 합니다. diff --git a/BOOTSTRAP.md b/BOOTSTRAP.md index 4c7bede..9d78a09 100644 --- a/BOOTSTRAP.md +++ b/BOOTSTRAP.md @@ -31,11 +31,29 @@ Before cloning this project into a new environment, you must first understand th --- -## 2. Environment Configuration (.env) +## 2. Workspace Provisioning (Step 0 — Reference Only) + +Before any agent can read this guide, the workspace must be provisioned. This step has already been performed by the human developer using the installer. It is documented here strictly as a reference for verifying agents to understand how the assets arrived. + +### Step 0.1: Run the Installer One-Liner (Pre-Cloned/Provisioned) +The human developer bootstrapped the workspace by running: + +```bash +curl -fsSL https://git.godopu.com/tmpl/multi-agent-mux/raw/branch/main/deploy/install.sh | bash +``` + +The installer verified system dependencies, staged the repository, copied the runtime `.agents/` scaffolding and documentation files (including this `BOOTSTRAP.md`), and set up the default `.env` and `.venv` environments. + +> [!NOTE] +> **Verify Only**: AI agents reading this guide must **not** attempt to run the installation script again. Proceed directly to configuration and verification steps. + +--- + +## 3. Environment Configuration (.env) To set up the messaging broker and execution paths, you must create and modify a local environment configuration file (`.env`). -### Step 2.1: Run the Generation Script +### Step 3.1: Run the Generation Script Run the environment template copy script provided in the project root: ```bash @@ -46,7 +64,7 @@ Run the environment template copy script provided in the project root: ./scripts/generate-env.sh --force ``` -### Step 2.2: Modify Environment Variables +### Step 3.2: Modify Environment Variables Open the generated `.env` file to configure settings as needed. > [!NOTE] @@ -66,11 +84,11 @@ Open the generated `.env` file to configure settings as needed. --- -## 3. Dependency and Virtualenv Setup +## 4. Dependency and Virtualenv Setup Set up the Python 3 dependencies required to run the orchestration and MQTT messaging backplane. -### Step 3.1: Build Python Virtual Environment +### Step 4.1: Build Python Virtual Environment Create and activate a `.venv` virtual environment in the project root: ```bash @@ -81,7 +99,7 @@ python3 -m venv .venv source .venv/bin/activate ``` -### Step 3.2: Install Dependency Packages +### Step 4.2: Install Dependency Packages Install the required packages listed in `requirements.txt` under `multi-agent-mux-delegate-job`: ```bash @@ -91,7 +109,7 @@ pip install -r .agents/skills/multi-agent-mux-delegate-job/requirements.txt --- -## 4. Directory Structure and Security Audit Guide +## 5. Directory Structure and Security Audit Guide Ensure that the local registry directories required to track agent states and jobs are successfully created: @@ -112,7 +130,7 @@ Ensure that the local registry directories required to track agent states and jo --- -## 5. Execution Verification and Bootstrap Tests +## 6. Execution Verification and Bootstrap Tests To verify that the environment has been successfully built without runtime errors, run the following verification checklist. @@ -161,7 +179,7 @@ rm -f ".mam/jobs/$JID.json" ".mam/jobs/$JID.lock" --- -## 6. Onboarding Collaborating Agents (New Agent Onboarding) +## 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. diff --git a/README.md b/README.md index e8aab9a..0ea9cfb 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,24 @@ Modern agentic workflows often suffer from session timeout, lack of process isol 3. **Multi-Agent Mux (MAM):** Combining local file-based locks (fcntl) and an ACID-compliant SQLite WAL database (`.mam/agent-sessions.db`) to manage concurrent job claims and track running agent sessions without drift. 4. **Automated Review & Quality Loop:** Implementing parallel reviewer loops where worker agents must receive a `PASS` rating from various specialized verification agents (e.g., Claude for high-level logic, Hermes for shell syntax/safety) before merging code. + +--- + +## 📦 Installation & Setup + +You can bootstrap the Multi-Agent Mux (MAM) framework in any workspace directory with a single command: + +```bash +curl -fsSL https://git.godopu.com/tmpl/multi-agent-mux/raw/branch/main/deploy/install.sh | bash +``` + +Alternatively, if you have already cloned the repository locally, run the installer directly: +```bash +bash deploy/install.sh +``` + +The idempotent installer automatically validates system dependencies (tmux, python3, and PyYAML), creates the python virtual environment (`.venv`), installs dependencies, copies `.env.example` as `.env`, and initializes the `.agents/` scaffolding. + --- ## 🛠️ Core Skills & Scaffolding