From 20b1014717f2d8491a78a9722d11f49501a78153 Mon Sep 17 00:00:00 2001 From: Godopu Date: Tue, 13 Oct 2026 10:41:54 +0900 Subject: [PATCH] docs(readme): bring README.md up to date with v4.9.1 Rewritten against the current code: the per-workspace shim is .mam/shim/herdr routing with --session (not /tmp/multi-agent-herdr-shim with -L), registry writes run in the workspace .venv (no dual-interpreter split), and the missing pieces are added - the delegation contract (ack, heartbeat, budget, busy wait, remote transport, exit codes), the review loop (strict verdicts, review identity, sub-jobs, report promotion), create --onboard exits 44/45, the per-server pane claim, restore-off servers, worktree helpers and the test isolation rules. Layout and quick start follow the tree. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01VCgu9Fa9iT7TbJUSzdq4Ff --- README.md | 333 +++++++++++++++++++++++++++--------------------------- 1 file changed, 168 insertions(+), 165 deletions(-) diff --git a/README.md b/README.md index fa09584..be5a8cf 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # herdr-agent-orchestration -An advanced, high-reliability **Multi-Agent Orchestration & Messaging Backplane** framework built on Herdr and MQTT. It is designed to coordinate, isolate, and audit long-running agent tasks (such as code generation, refactoring, and security reviews) across multiple LLM backend clients (`claude`, `agy`, `hermes`, `grok`, `opencode`, `codex`). +A **Multi-Agent Orchestration & Messaging Backplane** built on [herdr](https://herdr.dev) and MQTT. It runs long-lived coding agents (`claude`, `agy`, `hermes`, `grok`, `opencode`, `codex`) in isolated herdr panes, delegates work to them as tracked jobs, and drives planner / creator / reviewer loops until every reviewer passes the change. [![Version: v4.9.1](https://img.shields.io/badge/version-v4.9.1-blue.svg)](VERSIONS.md) @@ -8,230 +8,233 @@ An advanced, high-reliability **Multi-Agent Orchestration & Messaging Backplane* ## ๐Ÿš€ Overview -Modern agentic workflows often suffer from session timeout, lack of process isolation, terminal viewport truncation (scrollback limits), and complex concurrency issues. - -**herdr-agent-orchestration** addresses these problems by providing: -1. **Herdr-based Process Isolation:** Spawning LLM client sessions inside dedicated, isolated herdr environments to support persistent background runs. Background daemon servers detach into their own OS session/process group (`start_new_session=True`), ensuring they survive signal broadcasts to the parent shell. -2. **Asynchronous Event-Driven Architecture:** Leveraging an MQTT broker as a message backplane to coordinate state transitions (`started`, `progress`, `completed`, `error`) between collaborating agents. -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, Hermes, Grok, OpenCode, Codex) before merging code. +Long agent runs break in predictable ways: a session dies with its terminal, two jobs land in one pane, the orchestrator cannot tell a busy agent from a dead one, and a review approves code that changed after it was read. Multi-Agent Mux (MAM) addresses these with: +1. **Isolated, resumable agent sessions.** Each agent runs in its own herdr pane, usually on a herdr server dedicated to the workspace. Sessions are recorded in `.mam/agent-sessions.yaml` (backed by SQLite) with their conversation ids, so a stopped agent resumes the same conversation later. +2. **Jobs decided by events, not by the screen.** A delegated job is a registry record plus an MQTT event stream (`started`, `progress`, `completed`, `error`). The agent must acknowledge the prompt within a deadline and heartbeat while it works. A job is closed only by a protocol event or a timeout, never by reading the terminal. +3. **One job per session at a time.** Before injecting a prompt, the dispatcher waits by the registry for the session's earlier jobs (onboarding included) to end. Pane placement is serialised per herdr server, so concurrent `create` calls do not take the same pane. +4. **Reviewed loops with pinned evidence.** `multi-agent-mux-loop` sends a change to every registered reviewer and requires a unanimous `PASS`. With `--worktree`/`--base`, each review round is bound to a snapshot of the source. If the source changes during the round, its approvals are discarded and the round is reviewed again. --- ## ๐Ÿ“ฆ Installation & Setup -You can bootstrap the Multi-Agent Mux (MAM) framework in any workspace directory with a single command: +Bootstrap MAM in any workspace directory: ```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: +or, from a local clone: + ```bash bash deploy/install.sh ``` -The idempotent installer automatically validates system dependencies (herdr, python3, and PyYAML), creates the python virtual environment (`.venv`), installs dependencies, copies `.mam.env.example` as `.mam.env`, and initializes the `.agents/` scaffolding. +The installer is idempotent. It does the following: +- checks the dependencies (herdr, `python3` with PyYAML and sqlite3, rsync, uuidgen); +- copies `.agents/` and the templates; +- creates `.venv` and installs `paho-mqtt` and PyYAML into it; +- writes `.mam.env` from `.mam.env.example`; +- adds `.venv`, `.mam/` and `.mam.env` to `.gitignore`. + +Configure the broker in `.mam.env`. The default is the public `broker.hivemq.com`, which is fine for a trial but not for real work. See [MESSAGING.md](MESSAGING.md) for a private broker. `deploy/update.sh` and `deploy/remove.sh` update and uninstall. --- -## ๐Ÿ› ๏ธ Core Skills & Scaffolding +## ๐Ÿ› ๏ธ Core Skills -All orchestration functionalities are structured under the `.agents/skills/` directory: +Every skill lives under `.agents/skills/` with a `SKILL.md` that documents its options and exit codes. -* **`multi-agent-mux-create`**: Spawns isolated herdr sessions running specified agent CLI wrappers. It captures system processes, updates metadata registries, and enforces authentication checks. -* **`multi-agent-mux-stop`**: Gracefully terminates agent CLI sessions (using key macros like `/exit` or `Exit`) and handles disk purge operations (removing conversation JSON files and SQLite logs for deleted workspaces). -* **`multi-agent-mux-resume`**: Restores stopped sessions by resolving workspace UUIDs from disk or cache, and invokes the underlying agent using session-resume parameters (e.g., `claude -r `, `agy --conversation `, `hermes --resume `, `grok --resume `, `opencode --session `, or `codex resume `). -* **`multi-agent-mux-status`**: Queries the running states of all active sessions, detecting PID mismatches, command signatures, and drifts between actual herdr instances and the registry database. -* **`multi-agent-mux-monitor`**: A long-running reconcile worker that dynamically monitors herdr sessions and synchronizes states to `.mam/agent-sessions.yaml`. -* **`multi-agent-mux-delegate-job`**: The core asynchronous task distribution module (core implementation in `.agents/skills/lib_py/delegation/`; `scripts/*.py` serves as compatibility shims): - * `registry.py`: Atomically registers and claims jobs using file advisory locks (`fcntl`). - * `job_subscriber.py`: Connects to the MQTT backplane, captures live events, and appends them to audit trails. - * `publish_event.py`: Emits execution status transitions and error details from workspace scripts. - * `mqtt_common.py`: Manages connection policies, authentication, and HMAC signing. -* **`multi-agent-mux-loop`**: Autonomous planning-execution-review orchestration loop across Planner, Creator, and Reviewers until unanimous consensus (driven by Python loop runtime in `lib_py.loop`, eager-import immutable runtime, strict verdict parser). -* **`multi-agent-mux-orc-onboard`**: Helper to register and isolate orchestrator session UUIDs to prevent sub-agent discovery capture. +| Skill | What it does | +|---|---| +| **`multi-agent-mux-create`** | Starts an agent in a herdr pane and registers the session. `--onboard` waits until the onboarding job ends (exit 44 if it failed, 45 if it did not end in time; the session is kept). `scripts/worktree_prepare.sh` prepares an issue worktree for a creator. | +| **`multi-agent-mux-stop`** | Stops a session gracefully. The conversation id is saved on the row (`status: stopped`, `resumable: true`). `--purge-conversation --yes` deletes the conversation instead. `scripts/worktree_remove.sh` removes an issue worktree only after checking it is clean, including its submodules. | +| **`multi-agent-mux-resume`** | Brings a stopped session back with its saved conversation (`claude -r`, `agy --conversation`, `hermes --resume`, `grok --resume`, `opencode --session`, `codex resume`), in the directory it ran in. | +| **`multi-agent-mux-status`** | Read-only snapshot of every session: registry status, herdr liveness, pane command and cwd, resume id, drift. | +| **`multi-agent-mux-monitor`** | Long-running reconciler (`reconcile.sh --subscribe`). It reacts to job events, falls back to polling when the broker is down, and fixes registry drift. For example, it marks dead sessions `terminated` and registers live sessions the registry does not know. | +| **`multi-agent-mux-delegate-job`** | Delegates a job to a session (`herdr:`) or to a runner on another host (`remote:`) and waits for its result. See [Delegation contract](#-delegation-contract). | +| **`multi-agent-mux-loop`** | Plan, implement, review: an optional planner and a creator, then one or all reviewers until a unanimous `PASS` or `--max-loop`. It also supports `--review-only` for work finished outside the loop. Passing reports are promoted to `.agents/reports//`. | +| **`multi-agent-mux-orc-onboard`** | Registers the orchestrator's own session id, so session discovery never mistakes it for a sub-agent. | --- -## ๐Ÿ“ Big-Picture Architecture +## ๐Ÿ“ Architecture -The system coordinates LLM agents across multiple workspaces through two core layers: +MAM has two layers that share one registry: -1. **Layer A โ€” Herdr Orchestration (lib.sh + status/resume/stop/create)**: Runs the agents (one herdr session per agent-workspace combination) and maintains an authoritative registry in `.mam/agent-sessions.yaml` (+ `.mam/agent-sessions.db`). -2. **Layer B โ€” Async Job Delegation (delegate-job)**: Dispatches a task to an agent and observes progress and completion via an event channel. - -These two layers share one lock-guarded chokepoint for file I/O: `lib.sh::atomic_dump_yaml`. Every write is protected by an exclusive SQLite database transaction lock and schema validation. - -### Data Flow Overview +1. **Sessions (herdr)**: `lib.sh` and the create/stop/resume/status/monitor scripts run the agents and keep `.mam/agent-sessions.yaml` (+ `.mam/agent-sessions.db`) authoritative. +2. **Jobs (delegation)**: `lib_py/delegation/` registers a job in `.mam/jobs/.json`, injects the brief, and follows the job's events over MQTT. Every event is also appended to the job's audit log `.mam/delegate_job_logs//`. ```text - +-----------+ register_job +-------------------+ - | delegator | ---------------> | .mam/jobs/.json| <-- live record - +-----------+ +---------+---------+ - | - | atomic rename + fsync - v - +-----------------+ - | audit log | <-- append-only - | .mam/delegate_ | events.ndjson - | job_logs// | - +--------+--------+ - ^ - | (best-effort mirrors) - | - +-----------+ publish_event +-----+-----+ +---------+ - | agent | ---------------> | MQTT broker | <--- | monitor | - | (claude) | +-------------+ +----+----+ - +-----------+ | - ^ v - | subscriber atomic_dump_yaml - | (job_subscriber.py) (.mam/agent-sessions.yaml) - | ^ - +-------- delegator waits here ----------+ | - +---+---+ - | reconcil| - | e.sh | - +--------+ + +--------------+ register / pick +----------------------+ + | orchestrator | -----------------> | .mam/jobs/.json | live record + | (wrapper) | +----------+-----------+ + +------+-------+ | every transition + | inject brief v + v +----------------------+ + +--------------+ publish_event | .mam/delegate_job_ | append-only + | agent pane | --------+ | logs// | audit log + +--------------+ | +----------------------+ + v + +-------------+ events + retained state + | MQTT broker | -------------------------> job_subscriber (orchestrator) + +-------------+ -------------------------> monitor (reconcile.sh) + | + v + .mam/agent-sessions.yaml / .db ``` -### ๐Ÿ”’ Herdr Server Isolation +### ๐Ÿ”’ Herdr server isolation -To prevent workspace herdr processes from interfering with each other or with system herdr servers, the framework enforces isolated herdr environments: -* **Per-Workspace Shim:** `_init_herdr_isolation` and `_resolve_real_herdr_path` instantiate a per-workspace shim directory under `/tmp/multi-agent-herdr-shim//herdr` that intercepts herdr commands and wraps them in `herdr -L `. -* **PATH Rewriting:** The `PATH` environment variable is dynamically prepended with the shim path in all child processes. This ensures any `herdr` invocation within the agent's process tree is restricted to its isolated socket server. -* **Environment Restoration:** If `HERDR_SERVER_NAME` is set to `default`, the PATH override is removed, reverting to the default global herdr server. +- **Dedicated server per workspace (opt-in).** `create --herdr-session ` (or `HERDR_SESSION_NAME`) runs the agents on their own herdr server and socket, separate from your default herdr. The server name is recorded on the session row, and every later command routes to it. +- **The shim.** Sourcing `lib.sh` writes `/.mam/shim/herdr` and puts it first on `PATH`. The shim provides the tmux-style commands the scripts use (`new-session`, `has-session`, โ€ฆ) on top of herdr's agent API. It routes each call with `--session `, and it starts the server headless if the server is not running. +- **No surprise relaunches.** A server MAM starts uses your herdr config with `resume_agents_on_restore = false`. A herdr restart therefore does not relaunch saved agents without their permission flags. +- **One pane claim at a time.** Pane placement holds a per-server lock (`lib_py/pane_lock.py`, `flock` on macOS and Linux). Concurrent `create` calls in one folder each get their own pane. -### ๐Ÿ›ก๏ธ Concurrency Design & Write Serialization +### ๐Ÿ›ก๏ธ Registry writes and concurrency -The framework implements lock-guarded execution pathways to prevent race conditions during parallel agent operations: -* **SQLite Database Locks (`BEGIN IMMEDIATE`):** Every mutation of `agent-sessions.yaml` and the SQLite registry runs through `atomic_dump_yaml` inside `lib.sh`, which serializes writes via an exclusive `BEGIN IMMEDIATE` transaction lock on the SQLite database `.mam/agent-sessions.db`. -* **Dual-Interpreter Strategy:** To minimize dependency bloat and guarantee stability, the backplane splits execution environments: the virtual environment `.venv` handles MQTT communication and async jobs (requiring `paho-mqtt`), while the system `python3` executes `atomic_dump_yaml` (relying on system-wide `PyYAML`). -* **NFS and Network FS Safeguards:** Since file locking (`flock`) and SQLite WAL behave unreliably over network protocols (NFS, CIFS, SSHFS), `lib.sh` performs filesystem detection. If a network mount is identified, it outputs a safety warning and SQLite automatically switches its journaling mode from `WAL` to `DELETE`. +- **Serialised writes.** Every change to `agent-sessions.yaml` goes through `lib.sh::atomic_dump_yaml`. It runs under an exclusive SQLite transaction (`BEGIN IMMEDIATE`) on `.mam/agent-sessions.db` and is validated before the YAML is rewritten atomically. Job records use their own registry lock. +- **One interpreter.** The scripts run their Python in the workspace `.venv` (`AGENT_PYTHON_BIN`, else the active or nearest `.venv`). +- **Network filesystems.** If `.mam/` is on NFS/CIFS/SSHFS, `lib.sh` warns, and SQLite switches its journal from `WAL` to `DELETE`. +- **One loop per checkout.** A loop lock refuses a second `run_loop.sh` in the same control plane. --- -## ๐Ÿ“ Architecture & Coordination Loop +## ๐Ÿ“จ Delegation contract -The interaction between roles (Project Manager, Worker, and Reviewer) is structured as a strict iterative loop: +The full specification is in [MESSAGING.md ยง2.5](MESSAGING.md). + +- **Delivery**: after the prompt is handed over, the agent must publish `started` within **T** s (default 180). If it doesn't, the job fails closed (`agent_blocked`, exit 1), and the prompt is never injected twice. +- **Liveness**: `started --heartbeat N` starts an automatic heartbeat (default every 30 s). After **Kร—N** s of silence (default 120 s) the job counts as unresponsive. herdr status and pane text are logged for diagnosis only. +- **Budget**: each job has a wall-clock budget (`--timeout` / `MAM_JOB_TIMEOUT_S`, default 3600 s). A job that runs out is closed as `wall_clock_timeout`. +- **Busy sessions**: the wrapper waits up to `MAM_DISPATCH_WAIT_S` for the session's earlier open jobs to end. If they don't, it ends as `cancelled` (`session_busy`, exit 5), and the prompt is never delivered. +- **Remote agents**: `remote:` sends the brief as a signed, retained broker message to a `remote.py run` runner on another host. Use this only with a private broker. + +| Exit | Meaning | +|:---:|---| +| `0` | `completed` | +| `1` | failure, or no `started` within T | +| `2` | no event for Kร—N (`deadline_timeout`) or budget spent (`wall_clock_timeout`) | +| `3` | broker unavailable, and no terminal status on disk | +| `5` | session busy, or the record was taken over while waiting (never delivered) | + +--- + +## ๐Ÿ” Review loop ```mermaid sequenceDiagram autonumber - actor User as User - participant PM as Project Manager - participant W as Worker + actor User + participant L as run_loop.sh + participant P as Planner (optional) + participant C as Creator participant R as Reviewers - participant M as MQTT Backplane - User->>PM: Hand over requirements - Note over PM: Plan tasks & register jobs - PM->>M: Register Job & start Subscriber - PM->>W: Delegate task (Provide Job ID & Brief) - W->>M: Publish 'started' event - Note over W: Implement & verify code - W->>M: Publish 'completed' (or 'error') - PM->>R: Request parallel reviews (Provide Diff) - Note over R: Parallel analysis (Claude, Hermes, Grok, OpenCode, Codex) - alt Review Feedback (NOT PASS) - R->>PM: NOT PASS (Feedback with code blocks) - Note over PM: Apply fixes or re-delegate - PM->>W: Re-delegate with comments - else Verification PASS - R->>PM: PASS + User->>L: --task, --creator, --reviewer / --all-reviewer + opt --plan + L->>P: write the plan (Creator challenges it for --plan-talk turns) end - PM->>User: Commit changes & Report completion + L->>C: implement and commit (skipped with --review-only) + loop up to --max-loop + L->>R: review the snapshot diff (base..head) + alt every reviewer PASS and the source unchanged + R-->>L: [VERDICT: PASS] + else NOT PASS + R-->>L: [VERDICT: NOT PASS] + findings + L->>C: fix (or [REBUT:] up to --max-rebut) + end + end + L->>User: reports promoted to .agents/reports// ``` ---- - -## ๐Ÿ”’ Security & Replay Attack Defense - -To ensure communication integrity across public MQTT brokers, the backplane integrates an **HMAC-SHA256 signature protocol**: -* **PoC Mode (Unauthenticated):** Default mode where `auth_token` is `null`, skipping cryptographic validations for quick setups. -* **Production Mode (Authenticated):** A unique cryptographic token is issued per job. Event payloads must include an `hmac_sig` computed with the token. -* **Replay Attack Mitigation:** Each event carries a monotonically increasing integer sequence counter (`seq`). The subscriber (`job_subscriber.py`) drops any payload whose sequence number is not strictly greater than the highest sequence number it has already accepted for that job. Combined with the HMAC signature on the payload body, this rejects both re-injected and out-of-order packets without relying on clock synchronization. The wire-format timestamp field is advisory metadata only; the backplane does not enforce a clock-skew window. +- **Verdicts are strict**: the verdict token must stand alone on the last line of the report. A missing verdict counts as `NOT PASS`. +- **Review identity** (`--worktree` / `--base`): each round reviews a snapshot that includes uncommitted files. If the source changes during the round, its approvals are discarded. A promoted report gets a `report-.identity.json` sidecar that records the base, head, tree and reviewer. +- **Sub-jobs**: if the creator delegates part of its work (`--parent-job`), the loop waits for those jobs before the review and shows their status to the reviewers. --- -## ๐Ÿ“ Repository Layout +## ๐Ÿ” Security + +- **Signed events**: every job gets its own token (`auth_token`). Each event and each retained state message carries an HMAC-SHA256 signature made with it, and the subscriber drops anything that fails verification. The token itself never goes over the wire. +- **Replay and ordering**: each event carries an increasing `seq`. The subscriber accepts only sequence numbers higher than any it has seen and records gaps as `seq_gap`. Timestamps are informational only. +- **Credentials**: broker credentials live only in `.mam.env` (never in a job record). Remote dispatch is signed with `MAM_DISPATCH_SECRET`. + +--- + +## ๐Ÿงช Tests + +```bash +.venv/bin/python -m pytest -q -p no:cacheprovider tests +``` + +- The suite has about 1,900 tests, and a full run takes over an hour. +- It runs its own in-process MQTT broker, so it never needs `.mam.env`. Don't export `.mam.env` for tests. +- Tests run in sandboxes: + - they never write to the checkout's `.mam/`, your agent homes (`~/.claude/projects`, `~/.codex`, `~/.gemini`, โ€ฆ) or your herdr config; + - a test that does not use the mock herdr starts its own throwaway herdr server; + - session-level guards fail the run if a test leaves files behind in the real control plane or in an agent home. +- Some tests are platform-specific. A few need Python 3.11+ (`tomllib`), Linux (`/proc`) or the `nats-docker` submodule; elsewhere they are skipped. + +--- + +## ๐Ÿ“ Repository layout ```text . โ”œโ”€โ”€ .agents/ -โ”‚ โ”œโ”€โ”€ 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 -โ”‚ โ”œโ”€โ”€ lib_py/ # Python core orchestration engine -โ”‚ โ”‚ โ”œโ”€โ”€ agents/ # Multi-agent CLI lifecycle adapters -โ”‚ โ”‚ โ”œโ”€โ”€ delegation/ # Asynchronous delegation & CAS state engine -โ”‚ โ”‚ โ””โ”€โ”€ loop/ # Autonomous planning-execution-review loop runtime -โ”‚ โ”œโ”€โ”€ multi-agent-mux-create/ -โ”‚ โ”œโ”€โ”€ multi-agent-mux-stop/ -โ”‚ โ”œโ”€โ”€ multi-agent-mux-resume/ -โ”‚ โ”œโ”€โ”€ multi-agent-mux-status/ -โ”‚ โ”œโ”€โ”€ multi-agent-mux-monitor/ -โ”‚ โ”œโ”€โ”€ multi-agent-mux-delegate-job/ -โ”‚ โ”‚ โ”œโ”€โ”€ requirements.txt # Python dependency declaration -โ”‚ โ”‚ โ””โ”€โ”€ scripts/ # Wire-compatibility shims (Python) -โ”‚ โ”œโ”€โ”€ multi-agent-mux-loop/ -โ”‚ โ””โ”€โ”€ multi-agent-mux-orc-onboard/ -โ”œโ”€โ”€ .mam/ # Multi-Agent Mux metadata (git-ignored) -โ”‚ โ”œโ”€โ”€ agent-sessions.db # SQLite WAL session database -โ”‚ โ”œโ”€โ”€ agent-sessions.yaml # Human-readable session registry -โ”‚ โ””โ”€โ”€ jobs/ # Asynchronous job metadata files -โ”œโ”€โ”€ deploy/ # Distribution and installation package -โ”‚ โ”œโ”€โ”€ INSTALL.md # User manual for installation and quick-start -โ”‚ โ”œโ”€โ”€ install_mam.sh # Local/Clone installer script -โ”‚ โ”œโ”€โ”€ generate-env.sh # Environment bootstrap helper -โ”‚ โ”œโ”€โ”€ install.sh # Remote/Network installer script -โ”‚ โ”œโ”€โ”€ update.sh # Updater script -โ”‚ โ””โ”€โ”€ remove.sh # Uninstaller script -โ”œโ”€โ”€ docs/ # Specifications, guides, and architectural contracts -โ”‚ โ”œโ”€โ”€ contracts/ # Issue/backplane contracts and migration roadmaps -โ”‚ โ”œโ”€โ”€ MAM_WEB_PTY_BRIDGE_PLAN.md # Web PTY terminal bridge design plan -โ”‚ โ”œโ”€โ”€ NEW_AGENT_INTEGRATION_GUIDE.md # Guide for integrating new AI coding agents -โ”‚ โ””โ”€โ”€ OPENCODE_OLLAMA_GUIDE.md # OpenCode interpreter + Ollama integration guide -โ”œโ”€โ”€ nats-docker/ # Private NATS broker deployment submodule -โ”œโ”€โ”€ tests/ # Comprehensive test suite (32 modules) -โ”œโ”€โ”€ AGENTS.md # Behavioral guidelines and orchestrator scope guards -โ”œโ”€โ”€ BOOTSTRAP.ko.md # Installation and verification guide (Korean) -โ”œโ”€โ”€ BOOTSTRAP.md # Detailed installation and verification guide -โ”œโ”€โ”€ IMPROVEMENTS.md # Backlog tracking issues and completed architectural tasks -โ”œโ”€โ”€ MESSAGING.md # MQTT wire protocol specification and internals -โ”œโ”€โ”€ README.ko.md # Project introduction and overview (Korean) -โ”œโ”€โ”€ README.md # Project introduction and overview (this file) -โ””โ”€โ”€ VERSIONS.md # Release notes and 4-way lockstep version ledger +โ”‚ โ”œโ”€โ”€ MULTI_AGENT_RULES.md / .ko.md # Roles, workflow and collaboration rules +โ”‚ โ”œโ”€โ”€ reports/ # Promoted review reports (+ identity sidecars) +โ”‚ โ””โ”€โ”€ skills/ +โ”‚ โ”œโ”€โ”€ lib.sh # Shared shell library (herdr shim, registry writes) +โ”‚ โ”œโ”€โ”€ lib_py/ # Python core +โ”‚ โ”‚ โ”œโ”€โ”€ agents/ # Per-agent CLI adapters (spawn/resume/discover) +โ”‚ โ”‚ โ”œโ”€โ”€ delegation/ # Job registry, wrapper, MQTT publish/subscribe, remote runner +โ”‚ โ”‚ โ”œโ”€โ”€ loop/ # Review-loop runtime +โ”‚ โ”‚ โ””โ”€โ”€ *.py # pane_lock, stall_watch, worktree, herdr_config, ... +โ”‚ โ””โ”€โ”€ multi-agent-mux-*/ # One directory per skill (SKILL.md + scripts/) +โ”œโ”€โ”€ .mam/ # Runtime state (git-ignored): sessions, jobs, audit logs, shim +โ”œโ”€โ”€ deploy/ # install.sh, install_mam.sh, update.sh, remove.sh, generate-env.sh +โ”œโ”€โ”€ docs/ # contracts/, design/, agent integration and bridge guides +โ”œโ”€โ”€ nats-docker/ # Private NATS broker deployment (submodule) +โ”œโ”€โ”€ tests/ # pytest suite +โ”œโ”€โ”€ AGENTS.md # Behavioural guidelines for agents +โ”œโ”€โ”€ BOOTSTRAP.md / BOOTSTRAP.ko.md # Step-by-step setup and verification +โ”œโ”€โ”€ IMPROVEMENTS.md # Backlog +โ”œโ”€โ”€ MESSAGING.md # MQTT wire protocol and delegation contract +โ”œโ”€โ”€ README.ko.md # Korean README +โ””โ”€โ”€ VERSIONS.md # Release notes (lockstep version ledger) ``` --- ## ๐Ÿšฆ Quick Start -For detailed setup instructions, please consult the **[BOOTSTRAP.md](./BOOTSTRAP.md)** file. Below is a quick summary: +See [BOOTSTRAP.md](BOOTSTRAP.md) for the full walkthrough. In short: -1. **Initialize Environment Config:** - ```bash - ./deploy/generate-env.sh - ``` -2. **Create Virtual Environment and Install Dependencies:** - ```bash - python3 -m venv .venv - source .venv/bin/activate - pip install -r .agents/skills/multi-agent-mux-delegate-job/requirements.txt - ``` -3. **Run Registry Diagnostics:** - ```bash - .venv/bin/python3 .agents/skills/multi-agent-mux-delegate-job/scripts/registry.py list - ``` +```bash +# 1. Install into the workspace, then set the broker in .mam.env +bash deploy/install.sh + +# 2. Start a creator and a reviewer on a dedicated herdr server +bash .agents/skills/multi-agent-mux-create/scripts/create_session.sh \ + --workspace "$PWD" --agent claude --role developer --herdr-session my-project --onboard +bash .agents/skills/multi-agent-mux-create/scripts/create_session.sh \ + --workspace "$PWD" --agent codex --role reviewer --herdr-session my-project --onboard + +# 3. Check the sessions +bash .agents/skills/multi-agent-mux-status/scripts/status.sh + +# 4. Run a task through the loop +bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \ + --creator --all-reviewer --task "Fix the typo in docs/guide.md" +``` --- -## ๐Ÿ“ Guidelines for Collaborating Agents +## ๐Ÿ“ For agents joining the project -If you are an AI agent newly onboarded to this project: -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 +1. Read [AGENTS.md](AGENTS.md) and [MULTI_AGENT_RULES.md](.agents/MULTI_AGENT_RULES.md) for roles and rules. +2. Follow the snapshotting rules in `MULTI_AGENT_RULES.md` ยง4, so long outputs are not lost to the pane's scrollback. +3. Publish your job's events as your brief instructs (`started --heartbeat`, then `completed` or `error`). Don't change core logic without a reviewed diff.