From 954c95323f62ad7a94541c3f1dd88c5750c00e28 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 29 Apr 2026 15:34:07 +0300 Subject: [PATCH 1/2] docs: enrich core canon docs with local improvements (English) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Merge best-of-both between GitHub canonical English versions and local Russian versions that accumulated richer content across 20+ tasks. - README.md: add Why GitHub, Token Economics, Three Layers, Read-Order, Automation Report Coverage, Non-Goals sections - MANIFEST.md: add working cycle diagram, task model, target integration contract, success definition, evolution rule sections; align canon list - ARCHITECTURE.md: add explicit file lists per layer, Why Bash+Files+tmux rationale, GitHub-Native Layer (Layer 5), Boundary section - PRINCIPLES.md: enrich P-08/P-09/P-10 wording; add Refusal With A Route Closes #3 (batch 1: core canon — README, MANIFEST, ARCHITECTURE, PRINCIPLES) Co-authored-by: Claude (coordinator agent) --- ARCHITECTURE.md | 87 ++++++++++++++++++++++++++++++--- MANIFEST.md | 127 ++++++++++++++++++++++++++++++++++++++++-------- PRINCIPLES.md | 46 ++++++++++++++---- README.md | 63 +++++++++++++++++++++--- 4 files changed, 280 insertions(+), 43 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 32f9242..7dd9a19 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -2,29 +2,58 @@ ## Design Goal -Build a self-contained framework that separates agent operating rules from target-project code. +Build a self-contained framework that separates agent operating rules from target-project code, providing simultaneously: + +- a working runtime; +- coherent canonical docs; +- durable continuity; +- generic target integration. ## Layer Model -### Canonical Control Plane +### 1. Canonical Control Plane Docs define roles, read order, lifecycle, dispute process and evidence rules. -### Runtime Layer +Files: + +- `AGENTS.md` +- `MANIFEST.md` +- `ARCHITECTURE.md` +- `OPERATIONS.md` +- `PRINCIPLES.md` +- `DISPATCH_SPEC.md` +- `DISPUTE.md` +- `STATE.md` + +Role: + +- defines canon; +- sets read-order; +- records rules and the working model. + +### 2. Runtime Layer Portable bash scripts maintain local file-based IPC: - `lib/runtime.sh` - `start.sh` -- `stop.sh` - `watchdog.sh` - `coordinator.sh` +- `stop.sh` - `ws-status.sh` - `new-task.sh` - `set-target.sh` - `smoke-runtime.sh` -### Continuity Layer +Role: + +- creates and maintains the live IPC loop; +- delivers dispatch; +- updates state and queue; +- leaves a runtime trail. + +### 3. Continuity Layer Local ignored files store live state: @@ -36,10 +65,56 @@ Local ignored files store live state: - `auditor_logs/*.log` - `memory/` -### GitHub-Native Layer +Role: + +- stores task history; +- records audit evidence; +- provides recovery points after failures. + +### 4. Target Layer + +Files: + +- `targets/README.md` +- `targets/TARGET_TEMPLATE.md` +- `targets/*.md` + +Role: + +- connects any external repository without copying old conversations; +- describes the active path, baseline, read-order and canon rules for a specific repo. + +### 5. GitHub-Native Layer GitHub issues, pull requests, labels and actions govern changes to this framework. They do not replace the local runtime for target work. +## Runtime Flow + +```text +orchestrator + -> creates TASK-XXX + -> coordinator extracts dispatch and writes inbox/for-executor.md + -> watchdog prepends executor role pack and delivers message into tmux + -> executor writes signals into outbox/for-orchestrator.md + -> coordinator updates state/task and routes to auditor when needed + -> watchdog delivers audit dispatch + -> auditor writes AUDIT PASS or AUDIT FAIL + -> coordinator closes, retries or escalates +``` + +## Why Bash + Files + tmux + +- routing and retry logic is deterministic, so it should not burn tokens; +- file-based continuity survives crashes better than hidden in-chat state; +- tmux keeps long-lived agent sessions inspectable; +- target-packs separate "how agents work" from "what product they currently touch". + ## Boundary Target repositories do not receive this runtime unless a human explicitly installs it there. A target product can have its own UI, issues and automation; this framework can later have a management UI, but those UIs must not be mixed. + +## Non-Goals + +- Do not store the full history of a target product inside the control plane. +- Do not create a target-specific runtime for each repository. +- Do not replace repository docs with old chat memory. diff --git a/MANIFEST.md b/MANIFEST.md index f5c7161..be10961 100644 --- a/MANIFEST.md +++ b/MANIFEST.md @@ -1,15 +1,27 @@ # MANIFEST — MultiAgentSystem -## Purpose +## 1. Purpose `multiagentsystem` is a portable Agentic OS for: -- coordinating AI agents through explicit roles and artifacts; -- preserving continuity without hidden chat state; -- connecting any external repository through a target-pack; -- developing the framework itself through GitHub-native workflow. +- coordinating AI agents through file-based IPC and explicit roles; +- preserving live task and audit continuity; +- continuing work on any target repository through the target-pack mechanism; +- developing the framework itself through a GitHub-native workflow; +- evolving the system itself without fragmenting into inconsistent documents and scripts. -## Canon +## 2. Three-Layer Assembly + +The system is deliberately assembled from three layers: + +1. `continuity layer` + Live memory, task history, audit evidence and recovery anchors. +2. `runtime/spec layer` + Formal rules, dispatch, watchdog, coordinator and task contract. +3. `target layer` + Connecting external repositories through target-packs without copying old chat history. + +## 3. Canon Committed canon: @@ -39,24 +51,101 @@ Local canon during a run: Local canon is ignored by git unless a human explicitly promotes an artifact into the framework. -## Working Cycle +## 4. Roles and Responsibility + +### orchestrator + +Responsible for: + +- decomposing and creating tasks; +- selecting and activating the target-pack; +- updating `STATE.md`; +- escalations, retries and `DISPUTE`; +- preserving continuity so that a fresh agent can recover from files alone. + +### executor + +Responsible for: + +- completing the task; +- local verification before handoff; +- correct signal contract in `outbox/metrics.log` and `outbox/for-orchestrator.md`; +- reading task artifacts and target context instead of waiting for hidden chat. + +### auditor + +Responsible for: + +- a verifiable audit; +- PASS only on confirmed evidence; +- FAIL only with a specific reason; +- no unauthorized fixing in place of auditing. + +## 5. Working Cycle ```text orchestrator - -> creates task - -> coordinator dispatches to executor - -> watchdog delivers the message to a live session - -> executor works and emits DONE, NEEDS_REVIEW or BLOCKED - -> coordinator routes review or closes/escalates - -> auditor emits AUDIT PASS or AUDIT FAIL + -> creates TASK-XXX + -> coordinator dispatches envelope to inbox/for-executor.md + -> watchdog delivers it into executor tmux session + -> executor works and writes NEEDS_REVIEW / DONE / BLOCKED + -> coordinator updates task/state and routes to auditor when needed + -> watchdog delivers review context into auditor session + -> auditor writes AUDIT PASS / AUDIT FAIL + -> coordinator closes, retries or escalates ``` -## Success Definition +## 6. Task Model + +Each task: + +- lives as a separate file `tasks/TASK-XXX.md`; +- has a machine-readable metadata line `STATUS ...`; +- contains a typed dispatch envelope; +- contains enough human context for manual recovery after a failure. + +The task file must be simultaneously: + +- usable by an agent; +- parseable by the coordinator; +- sufficient for the next attempt without hidden chat memory. + +## 7. Target Integration Contract + +The system does not store the full history of a target repository internally. + +Instead, for each target the following must exist: + +- target name; +- active repo path; +- baseline/reference repo path if needed; +- read-order for a fresh agent; +- recovery anchors; +- canon rules for that specific repo. + +The contract template is described in `targets/TARGET_TEMPLATE.md`. + +## 8. Success Definition The system works when: -1. a fresh clone can create its missing local runtime files; -2. scripts run without product-specific paths; -3. a local target-pack can connect an external repository; -4. a task can be created, dispatched and inspected from files; -5. a fresh agent can recover by reading docs, local state, target-pack and task artifacts. +1. `start.sh` brings up the runtime or correctly shows a dry-run; +2. `watchdog.sh` delivers dispatch into live sessions; +3. `coordinator.sh` can route, retry and leave an audit trail; +4. `ws-status.sh` shows the health of the loop; +5. a fresh agent can continue work from canonical system files and a target-pack without old chat history; +6. a fresh clone can create its missing local runtime files; +7. scripts run without product-specific paths; +8. a task can be created, dispatched and inspected from files. + +## 9. Evolution Rule + +The following changes must not disappear into chat without an artifact. + +Permitted forms: + +- a new task; +- an entry in `ROADMAP.md`; +- an entry in `auditor_logs/events.log`; +- a new `DISPUTE-XXX.md`; +- a GitHub Issue or Pull Request for framework-level changes. diff --git a/PRINCIPLES.md b/PRINCIPLES.md index 3aad5bc..e1c1889 100644 --- a/PRINCIPLES.md +++ b/PRINCIPLES.md @@ -1,4 +1,4 @@ -# PRINCIPLES +# PRINCIPLES — Constitutional Rules ## P-01 Data Honesty @@ -6,36 +6,62 @@ Do not present unverified assumptions as facts. ## P-02 Credentials From Environment Only -Tokens, keys and passwords must not appear in tasks, dispatch envelopes, logs or committed docs. +Tokens, keys and passwords must not appear in task files, dispatch envelopes, logs or committed docs. ## P-03 Irreversible Actions Need Review -Deletes, deploys, sends, price changes and other irreversible actions require a safety gate. +Deletes, deploys, sends, price changes and any other irreversible actions require explicit approval and a safety gate. ## P-04 Build Only For Real Pain -Do not add components because they are interesting. Add them because a real workflow needs them. +Do not add a new component unless it is a response to a real workflow need. ## P-05 Simple And Inspectable First -Files, bash, tmux and explicit contracts are preferred until scale proves otherwise. +Files, bash, tmux and explicit contracts are preferred over "smart" magic until scale proves otherwise. ## P-06 Dispute As Artifact -A conceptual disagreement is formal only when recorded as a dispute artifact. +A conceptual disagreement is formal only when recorded as a dispute artifact in `DISPUTE-XXX.md` or another explicit artifact. ## P-07 Speak Only For Your Role -Do not invent another role's position or approval. +Do not invent another agent's position or attribute a stance to them without an explicit artifact. ## P-08 Fresh-Agent Continuity -A new agent must be able to continue from committed docs plus local runtime artifacts. If hidden chat is required, the process is broken. +A new agent must be able to continue work by reading only the canonical docs, `STATE.md`, a target-pack and task files. + +If hidden chat history is required to continue, the system is not well assembled. ## P-09 Target-Pack Over Chat History -For target projects, store paths, read order, anchors and rules, not old conversations. +For target projects, store: + +- the active path; +- baseline/reference; +- read-order; +- recovery anchors; +- canon criteria for the target project. + +Do not store old conversations. ## P-10 System Decisions Leave A Trace -Changes to roles, lifecycle, runtime or policy must leave a task, issue, PR, dispute or roadmap entry. +Changes to architecture, rules, roles or runtime must result in one of: + +- `TASK-XXX` +- `DISPUTE-XXX.md` +- an entry in `ROADMAP.md` +- an audit event +- a GitHub Issue or Pull Request for framework-level changes + +## Refusal With A Route + +An agent may refuse a useless or dangerous attempt, but may not disappear silently. + +Permitted outcomes: + +- `TASK-XXX BLOCKED: ...` +- `TASK-XXX NEEDS_REVIEW: ...` +- decomposition of the task into an achievable part diff --git a/README.md b/README.md index 9b507f5..f14b7a1 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# MultiAgentSystem +# Multi-Agent Operating System `multiagentsystem` is a portable Agentic OS for coordinating AI agents across software projects. @@ -9,9 +9,22 @@ It keeps the operating model separate from any target product: - live operational state is local by default and is not committed; - GitHub is used for development of this framework through issues, pull requests, process changes, disputes and checks. +It is assembled from three evolutionary sources: + +- live continuity and institutional memory from the root workspace; +- a formalized runtime/spec layer; +- a target-oriented product overlay layer. + +## Goals + +- run a real working loop, not a collection of disconnected rules; +- give a fresh agent a clear read-order and a reproducible runtime; +- allow any new target repository to be connected through a target-pack; +- preserve continuity without depending on old chat history. + ## Why GitHub Is Part Of The OS -The local v4 runtime proved that agent work needs explicit state, roles, tasks, audit trails and disputes. The problem is that a purely local control plane makes every fresh agent spend tokens rediscovering the same context: which tasks exist, what changed, what was reviewed, which dispute was resolved and what the current policy is. +The local runtime proved that agent work needs explicit state, roles, tasks, audit trails and disputes. The problem is that a purely local control plane makes every fresh agent spend tokens rediscovering the same context: which tasks exist, what changed, what was reviewed, which dispute was resolved and what the current policy is. GitHub is used here as the durable shared control plane for developing this framework. It gives us native IDs, timelines, review surfaces, status checks, permissions and project views without asking an agent to rebuild those structures from chat history or local logs. @@ -51,6 +64,15 @@ The split saves tokens by moving deterministic coordination out of the model's c The expected economy is simple: humans and agents spend tokens on judgment, design, code and audit; GitHub spends ordinary compute on indexing, status, routing, checks and durable timelines. +## Three Layers + +1. `runtime` + `start.sh`, `watchdog.sh`, `coordinator.sh`, `ws-status.sh`, `stop.sh`. +2. `canonical control plane` + `AGENTS.md`, `MANIFEST.md`, `ARCHITECTURE.md`, `OPERATIONS.md`, `PRINCIPLES.md`, `DISPATCH_SPEC.md`, `DISPUTE.md`, `STATE.md`. +3. `continuity and targets` + `tasks/`, `auditor_logs/`, `memory/`, `targets/`. + ## Quick Start 1. Read `AGENTS.md`. @@ -63,16 +85,41 @@ The expected economy is simple: humans and agents spend tokens on judgment, desi Agents must create missing runtime files themselves from templates or runtime scripts. Do not ask the user to create `STATE.md`, `inbox/`, `outbox/`, `tasks/`, `targets/`, `auditor_logs/`, or `memory/` when the framework can create them safely. -## Layers +## Automation Report Coverage -- `canonical control plane`: rules, roles, lifecycle and continuity docs. -- `runtime`: bash/tmux/file IPC scripts for local execution. -- `target layer`: local target-packs that connect external repositories. -- `GitHub-native layer`: issue forms, PR template and hygiene checks for framework development. +The autonomous loop writes timestamped reports under `automation_reports/`: -## Non-Goals +- `execution/` records concrete target-repo work. +- `audit/` records review of execution reports. +- `improvements/` records fixes or no-op decisions made after reading audits. +Use `./automation-report-status.sh` to check whether the streams are aligned. It exits 0 by default for dashboards and human inspection, and `./automation-report-status.sh --strict` exits non-zero when audit or improvement coverage is stale. Automation prompts can use `./automation-report-status.sh --json` for machine-readable routing. + +## Read-Order For Fresh Agent + +1. `AGENTS.md` +2. `MANIFEST.md` +3. `ARCHITECTURE.md` +4. `OPERATIONS.md` +5. `STATE.md` +6. `targets/README.md` if work touches an external repo +7. active `targets/.md` if one is selected +8. `tasks/TASK-XXX.md` + +## What This Project Intentionally Does Not Do + +- It does not copy old chat history into itself. +- It does not hardwire one product as the meaning of the system. +- It does not treat legacy docs outside this folder as automatic canon. - Do not store target-product chat history here. - Do not commit product-specific live state. - Do not make target project UI part of this framework UI. - Do not treat GitHub Pages as required for v1. + +Instead it keeps: + +- a working runtime; +- coherent constitutional rules; +- a generic target-pack contract; +- durable task and audit continuity; +- a place where future evolution leaves artifacts instead of disappearing into chat. From 8f2802e3d51a73f14575489315c2203ae2e03789 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 29 Apr 2026 15:55:55 +0300 Subject: [PATCH 2/2] fix: STATE.md -> STATE.template.md in canonical control plane lists STATE.md is machine-local runtime state (not committed). STATE.template.md is the committed canonical artifact. Fix addresses review comment on PR #6. Co-authored-by: Claude (coordinator agent) --- ARCHITECTURE.md | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 7dd9a19..4101c05 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -24,7 +24,7 @@ Files: - `PRINCIPLES.md` - `DISPATCH_SPEC.md` - `DISPUTE.md` -- `STATE.md` +- `STATE.template.md` Role: diff --git a/README.md b/README.md index f14b7a1..d0f7bb9 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ The expected economy is simple: humans and agents spend tokens on judgment, desi 1. `runtime` `start.sh`, `watchdog.sh`, `coordinator.sh`, `ws-status.sh`, `stop.sh`. 2. `canonical control plane` - `AGENTS.md`, `MANIFEST.md`, `ARCHITECTURE.md`, `OPERATIONS.md`, `PRINCIPLES.md`, `DISPATCH_SPEC.md`, `DISPUTE.md`, `STATE.md`. + `AGENTS.md`, `MANIFEST.md`, `ARCHITECTURE.md`, `OPERATIONS.md`, `PRINCIPLES.md`, `DISPATCH_SPEC.md`, `DISPUTE.md`, `STATE.template.md`. 3. `continuity and targets` `tasks/`, `auditor_logs/`, `memory/`, `targets/`.