feat: add Atomizer HQ multi-agent cluster infrastructure
- 8-agent OpenClaw cluster (Manager, Tech-Lead, Secretary, Auditor, Optimizer, Study-Builder, NX-Expert, Webster) - Orchestration engine: orchestrate.py (sync delegation + handoffs) - Workflow engine: YAML-defined multi-step pipelines - Agent workspaces: SOUL.md, AGENTS.md, MEMORY.md per agent - Shared skills: delegate, orchestrate, atomizer-protocols - Capability registry (AGENTS_REGISTRY.json) - Cluster management: cluster.sh, systemd template - All secrets replaced with env var references
This commit is contained in:
@@ -0,0 +1,236 @@
|
||||
# 📊 Atomizer Dashboard & Reporting System — Master Plan
|
||||
|
||||
> **Status:** PROPOSAL | **Date:** 2026-02-14 | **Author:** Manager Agent | **For:** Antoine (CEO)
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
A file-based, agent-native dashboard and reporting system that gives Antoine real-time project visibility without leaving the existing Atomizer stack. No new infrastructure—just structured markdown, automated aggregation, and agent-generated reports.
|
||||
|
||||
---
|
||||
|
||||
## 1. Information Architecture
|
||||
|
||||
```
|
||||
shared/
|
||||
├── PROJECT_STATUS.md ← Single source of truth (Manager-owned)
|
||||
├── project_log.md ← Append-only agent activity log
|
||||
├── dashboards/
|
||||
│ ├── exec-summary.md ← CEO dashboard (auto-generated)
|
||||
│ ├── technical.md ← FEA/optimization status
|
||||
│ └── operations.md ← Agent health, queue, throughput
|
||||
├── reports/
|
||||
│ ├── weekly/ ← YYYY-WXX-report.md
|
||||
│ ├── project/ ← Per-project closeout reports
|
||||
│ └── templates/ ← Report templates (markdown)
|
||||
├── data-contracts/
|
||||
│ └── schemas.md ← Field definitions for all status files
|
||||
└── kpi/
|
||||
└── metrics.md ← Rolling KPI tracker
|
||||
```
|
||||
|
||||
**Principle:** Everything is markdown. Agents read/write natively. No database, no web server, no maintenance burden.
|
||||
|
||||
---
|
||||
|
||||
## 2. Dashboard Modules
|
||||
|
||||
### 2A. Executive Summary (`dashboards/exec-summary.md`)
|
||||
**Audience:** Antoine | **Update frequency:** On every PROJECT_STATUS.md change
|
||||
|
||||
| Section | Content |
|
||||
|---------|---------|
|
||||
| 🚦 Project RAG | Red/Amber/Green per active project, one line each |
|
||||
| 📌 Decisions Needed | Items blocked on CEO approval |
|
||||
| 💰 Resource Burn | Agent token usage / cost estimate (daily/weekly) |
|
||||
| 🏆 Wins This Week | Completed milestones, delivered studies |
|
||||
| ⚠️ Top 3 Risks | Highest-impact risks across all projects |
|
||||
|
||||
**Format:** ≤30 lines. Scannable in 60 seconds.
|
||||
|
||||
### 2B. Technical Dashboard (`dashboards/technical.md`)
|
||||
**Audience:** Technical Lead, Optimizer | **Update frequency:** Per study cycle
|
||||
|
||||
| Section | Content |
|
||||
|---------|---------|
|
||||
| Active Studies | Study name, iteration count, best objective, convergence % |
|
||||
| FEA Queue | Jobs pending / running / completed / failed |
|
||||
| Model Registry | Active NX models, mesh stats, last validated date |
|
||||
| Optimization Curves | Tabular: iteration vs objective vs constraint satisfaction |
|
||||
| Knowledge Base Delta | New entries since last report |
|
||||
|
||||
### 2C. Operations Dashboard (`dashboards/operations.md`)
|
||||
**Audience:** Manager (self-monitoring), Mario (infra) | **Update frequency:** Hourly via cron or on-demand
|
||||
|
||||
| Section | Content |
|
||||
|---------|---------|
|
||||
| Agent Health | Last active timestamp per agent, error count (24h) |
|
||||
| Message Throughput | Messages processed per agent per day |
|
||||
| Queue Depth | Pending delegations, blocked tasks |
|
||||
| Token Budget | Usage vs budget per agent, projected monthly |
|
||||
| System Alerts | Disk, memory, process status flags |
|
||||
|
||||
---
|
||||
|
||||
## 3. Data Contracts
|
||||
|
||||
Every agent writing to `project_log.md` MUST use this format:
|
||||
|
||||
```markdown
|
||||
## [YYYY-MM-DD HH:MM] agent-id | project-slug | event-type
|
||||
|
||||
**Status:** in-progress | completed | blocked | failed
|
||||
**Summary:** One-line description
|
||||
**Detail:** (optional) Multi-line context
|
||||
**Metrics:** (optional) key=value pairs
|
||||
**Blockers:** (optional) What's blocking and who can unblock
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
### Event Types (enumerated)
|
||||
| Type | Meaning |
|
||||
|------|---------|
|
||||
| `study-start` | New optimization study launched |
|
||||
| `study-iteration` | Iteration completed with results |
|
||||
| `study-complete` | Study converged or terminated |
|
||||
| `review-request` | Deliverable ready for review |
|
||||
| `decision-needed` | CEO/human input required |
|
||||
| `task-delegated` | Work handed to another agent |
|
||||
| `task-completed` | Delegated work finished |
|
||||
| `error` | Something failed |
|
||||
| `milestone` | Phase/gate achieved |
|
||||
|
||||
### Dashboard Field Schema
|
||||
Each dashboard section maps to specific log event types. Manager agent aggregates—no other agent touches dashboard files directly.
|
||||
|
||||
---
|
||||
|
||||
## 4. Report System
|
||||
|
||||
### 4A. Weekly Report (auto-generated every Friday or on-demand)
|
||||
**Template:** `reports/templates/weekly-template.md`
|
||||
|
||||
```markdown
|
||||
# Atomizer Weekly Report — YYYY-WXX
|
||||
|
||||
## Highlights
|
||||
- (auto: completed milestones from log)
|
||||
|
||||
## Projects
|
||||
### [Project Name]
|
||||
- Status: RAG
|
||||
- This week: (auto: summary of log entries)
|
||||
- Next week: (auto: from PROJECT_STATUS.md planned items)
|
||||
- Blockers: (auto: open blockers)
|
||||
|
||||
## KPIs
|
||||
| Metric | This Week | Last Week | Trend |
|
||||
|--------|-----------|-----------|-------|
|
||||
|
||||
## Agent Performance
|
||||
| Agent | Messages | Tasks Done | Errors | Avg Response |
|
||||
|-------|----------|------------|--------|-------------|
|
||||
|
||||
## Decisions Log
|
||||
- (auto: from decision-needed events + resolutions)
|
||||
```
|
||||
|
||||
### 4B. Project Closeout Report
|
||||
Generated when a project reaches `completed` status. Includes full decision trail, final results, lessons learned, KB entries created.
|
||||
|
||||
### 4C. On-Demand Reports
|
||||
Antoine can request via Discord: "Give me a status report on [project]" → Manager generates from log + status files instantly.
|
||||
|
||||
### 4D. PDF Generation
|
||||
Use existing `atomaste-reports` skill for client-facing PDF output when needed.
|
||||
|
||||
---
|
||||
|
||||
## 5. Documentation Governance
|
||||
|
||||
### Two-Tier System
|
||||
|
||||
| Tier | Location | Owner | Mutability |
|
||||
|------|----------|-------|------------|
|
||||
| **Foundational** | `context-docs/` | Mario + Antoine | Immutable by agents. Amended only via CEO-approved change request. |
|
||||
| **Project-Specific** | `shared/`, `memory/projects/` | Manager (gatekeeper), agents (contributors) | Living documents. Agents write, Manager curates. |
|
||||
|
||||
### Rules
|
||||
1. **Foundational docs** (00-05, SOUL.md, protocols) = constitution. Agents reference, never edit.
|
||||
2. **Project docs** = operational. Agents append to log; Manager synthesizes into status files.
|
||||
3. **Dashboards** = derived. Auto-generated from project docs. Never manually edited.
|
||||
4. **Reports** = snapshots. Immutable once generated. Stored chronologically.
|
||||
5. **Knowledge Base** = accumulative. Grows per project via `cad_kb.py`. Never pruned without review.
|
||||
|
||||
### Change Control
|
||||
- Protocol changes → Antoine approval → Mario implements → agents reload
|
||||
- Dashboard schema changes → Manager proposes → Antoine approves → Manager implements
|
||||
- New event types → Manager adds to `schemas.md` → notifies all agents via cluster message
|
||||
|
||||
---
|
||||
|
||||
## 6. Rollout Phases
|
||||
|
||||
| Phase | When | What | Gate |
|
||||
|-------|------|------|------|
|
||||
| **R0: Schema** | Week 1 | Create `data-contracts/schemas.md`, `reports/templates/`, directory structure | Manager reviews, Antoine approves structure |
|
||||
| **R1: Logging** | Week 1-2 | All active agents adopt structured log format in `project_log.md` | 48h of clean structured logs from all agents |
|
||||
| **R2: Exec Dashboard** | Week 2 | Manager auto-generates `exec-summary.md` from logs | Antoine confirms it's useful and accurate |
|
||||
| **R3: Tech + Ops Dashboards** | Week 3 | Technical and operations dashboards go live | Tech Lead validates technical dashboard accuracy |
|
||||
| **R4: Weekly Reports** | Week 3-4 | Automated weekly report generation | First 2 weekly reports reviewed by Antoine |
|
||||
| **R5: KPI Tracking** | Week 4 | Rolling metrics in `kpi/metrics.md` | KPIs match reality for 2 consecutive weeks |
|
||||
| **R6: PDF Reports** | Week 5+ | Client-facing report generation via atomaste-reports | First PDF passes Auditor review |
|
||||
|
||||
**Each phase has a go/no-go gate. No skipping.**
|
||||
|
||||
---
|
||||
|
||||
## 7. Risks & Mitigations
|
||||
|
||||
| # | Risk | Impact | Likelihood | Mitigation |
|
||||
|---|------|--------|------------|------------|
|
||||
| 1 | **Log format drift** — agents write inconsistent entries | Dashboards break | Medium | Auditor spot-checks weekly; Manager rejects malformed entries |
|
||||
| 2 | **Information overload** — exec dashboard becomes too long | Antoine stops reading it | Medium | Hard cap: 30 lines. Ruthless prioritization. |
|
||||
| 3 | **Stale data** — dashboards not updated after agent activity | False confidence | High | Manager updates dashboards on every log synthesis cycle |
|
||||
| 4 | **Token cost explosion** — dashboard generation burns budget | Budget overrun | Low | Dashboard gen is cheap (small files). Monitor via ops dashboard. |
|
||||
| 5 | **Single point of failure** — Manager agent owns all dashboards | Manager down = no visibility | Medium | Raw `project_log.md` always available; any agent can read it |
|
||||
| 6 | **Scope creep** — adding features before basics work | Delayed delivery | High | Strict phase gates. No R3 until R2 is validated. |
|
||||
| 7 | **File conflicts** — multiple agents writing simultaneously | Data corruption | Low | Only Manager writes dashboards; log is append-only with timestamps |
|
||||
|
||||
---
|
||||
|
||||
## 8. KPIs & Gate Rules
|
||||
|
||||
### KPI List
|
||||
|
||||
| # | KPI | Target | Measurement |
|
||||
|---|-----|--------|-------------|
|
||||
| K1 | Dashboard freshness | ≤1h stale | Time since last exec-summary update |
|
||||
| K2 | Log compliance rate | ≥95% | % of log entries matching schema |
|
||||
| K3 | Weekly report delivery | 100% on-time | Generated by Friday 17:00 EST |
|
||||
| K4 | CEO read-time | ≤60 seconds | Exec summary length ≤30 lines |
|
||||
| K5 | Decision backlog age | ≤48h | Max age of unresolved `decision-needed` events |
|
||||
| K6 | Project status accuracy | No surprises | Zero cases where dashboard says green but reality is red |
|
||||
| K7 | Agent error rate | ≤5% | Failed tasks / total tasks per agent per week |
|
||||
| K8 | Report generation cost | ≤$2/week | Token cost for all dashboard + report generation |
|
||||
|
||||
### Gate Rules
|
||||
|
||||
| Gate | Criteria | Evaluator |
|
||||
|------|----------|-----------|
|
||||
| **G1: Schema Approved** | Antoine signs off on data contracts + directory structure | Antoine |
|
||||
| **G2: Logging Stable** | 48h of compliant logs from all active agents, ≥95% schema compliance | Auditor |
|
||||
| **G3: Exec Dashboard Valid** | Antoine confirms dashboard matches his understanding of project state | Antoine |
|
||||
| **G4: Full Dashboards Live** | All 3 dashboards updating correctly for 1 week | Manager + Tech Lead |
|
||||
| **G5: Reports Automated** | 2 consecutive weekly reports generated without manual intervention | Manager |
|
||||
| **G6: System Mature** | All KPIs met for 2 consecutive weeks | Antoine (final sign-off) |
|
||||
|
||||
---
|
||||
|
||||
## Decision Required
|
||||
|
||||
**Antoine:** Approve this plan to begin R0 (schema creation) immediately, or flag sections needing revision.
|
||||
|
||||
**Estimated total effort:** ~15 agent-hours across 5 weeks. Zero new infrastructure. Zero new dependencies.
|
||||
Reference in New Issue
Block a user