Add doc 11: HQ improvements plan from Bhanu video analysis

2026-02-16 01:19:27 +00:00
parent e4651c9a40
commit 7086f9fbdf
1 changed files with 323 additions and 0 deletions
--- a/docs/hq/11-HQ-IMPROVEMENTS-PLAN.md
+++ b/docs/hq/11-HQ-IMPROVEMENTS-PLAN.md
@@ -0,0 +1,323 @@
+# 11 — HQ Improvements Plan: Lessons from Bhanu's Multi-Agent System
+
+> **Status:** PLAN — Ready for execution
+> **Author:** Mario Lavoie
+> **Date:** 2026-02-16
+> **Source:** [Bhanu's Multi-Clawdbot Video](https://youtu.be/_ISs5FavbJ4) + Antoine's feedback
+> **Scope:** Improvements to Atomizer HQ orchestration — not feature dev or project optimization dashboards
+
+---
+
+## Context
+
+Bhanu (founder of SiteGPT) runs 14 OpenClaw agents doing marketing. Key things that work well in his setup and how they map to ours:
+
+| Bhanu's Pattern | Our Equivalent | Status |
+|----------------|----------------|--------|
+| Single entry point (Jarvis) | Manager orchestrates | ✅ Have it |
+| Custom-built task dashboard | — | ❌ **Need this** |
+| 15-min polling (agents check for new work) | Heartbeat system | 🔶 Need adaptation |
+| Enforced deliverables per task | Handoff JSON schema | 🔶 Need enforcement |
+| Squad chat (agents talk freely) | Discord channels | ✅ Have it better |
+| Broadcast to all agents | delegate.sh / hooks | ✅ Have it |
+| Escalation to Telegram on @mentions | Slack notifications | ✅ Have it |
+| Vacation mode (Jarvis auto-approves) | — | 🔶 Nice to have |
+
+**Key insight from Antoine:** We keep Discord as the backbone. Topic-based channels managed by Manager give us *more* visibility than Bhanu's single-dashboard approach. The dashboard supplements Discord — it doesn't replace it.
+
+---
+
+## Improvement 1: HQ Orchestration Dashboard
+
+### What It Is
+
+A lightweight web UI that shows the state of all active work across the Atomizer HQ cluster. Think: a Kanban board + agent status panel. Antoine opens it from any device and sees the full picture.
+
+**This is NOT:**
+- The existing Atomizer study/optimization dashboard (that stays separate)
+- A feature development tracker (that lives in Discord + roadmap docs)
+
+**This IS:**
+- A collaboration/orchestration view for the agent cluster
+- Real-time visibility into who's doing what
+
+### Views
+
+#### 1. Task Board (Kanban)
+
+```
+┌─────────────┬──────────────┬──────────────┬─────────────┐
+│   BACKLOG   │ IN PROGRESS  │   REVIEW     │    DONE     │
+├─────────────┼──────────────┼──────────────┼─────────────┤
+│ Research    │ 🔧 Tech Lead │ 📋 Secretary │ ✅ Homepage  │
+│ CTE data   │ Material     │ Report v2    │   redesign  │
+│ [webster]   │ trade study  │ needs CEO    │   [friday]  │
+│             │              │ approval     │             │
+│ Write test  │ ⚡ Optimizer  │              │ ✅ CTE study │
+│ protocol    │ Pareto front │              │   [webster] │
+│ [auditor]   │ exploration  │              │             │
+└─────────────┴──────────────┴──────────────┴─────────────┘
+```
+
+Each card shows:
+- Task title + short description
+- Assigned agent (emoji + name)
+- Time elapsed since assignment
+- Status (from handoff JSON: complete/partial/blocked/failed)
+- Deliverables attached (if any)
+- Blockers (highlighted in red)
+
+#### 2. Agent Status Panel
+
+```
+┌──────────────────────────────────────────────┐
+│ AGENTS                                        │
+│ 🎯 Manager      ● online   3 tasks active    │
+│ 📋 Secretary     ● online   1 task active     │
+│ 🔧 Tech Lead    ● online   2 tasks active    │
+│ 🔍 Auditor      ● online   idle              │
+│ ⚡ Optimizer     ● online   1 task active     │
+│ 🏗️ Study Builder ○ offline  —                 │
+│ 🖥️ NX Expert     ○ offline  —                 │
+│ 🌐 Webster      ● online   1 task active     │
+└──────────────────────────────────────────────┘
+```
+
+Health from `/hooks/health` endpoint per instance. Shows active task count, last activity timestamp.
+
+#### 3. Recent Activity Feed
+
+Chronological log of handoffs, completions, escalations. Like a simplified Discord activity stream but structured:
+
+```
+[14:32] 🎯 Manager → 🌐 Webster: "Research CTE of Clearceram-Z HS"
+[14:33] 🌐 Webster: accepted task
+[14:45] 🌐 Webster: STATUS: complete, CONFIDENCE: high
+[14:45] 🎯 Manager → 🔍 Auditor: "Validate Webster's CTE findings"
+[14:46] 📋 Secretary → Antoine: "Review needed: Homepage redesign deliverable"
+```
+
+#### 4. Escalations & Blockers (Top Bar)
+
+Items waiting for Antoine's input — surfaced prominently so he doesn't need to dig.
+
+### Tech Stack
+
+- **Frontend:** React + Vite + TailwindCSS (same as existing Atomizer dashboard)
+- **Backend:** FastAPI endpoint that reads handoff files from `/home/papa/atomizer/handoffs/`
+- **Data source:** The handoff JSON from orchestration engine (doc 10) — already structured
+- **Refresh:** WebSocket or 10-second polling
+- **Auth:** Basic auth or none (local network only)
+
+### Implementation
+
+| Step | Work | Effort |
+|------|------|--------|
+| 1 | Define task state machine (backlog→active→review→done) | 1h |
+| 2 | Add task creation/tracking to orchestrate.sh | 2h |
+| 3 | FastAPI endpoints: GET /tasks, GET /agents/status, GET /activity | 3h |
+| 4 | React Kanban board component | 4h |
+| 5 | Agent status panel + activity feed | 3h |
+| 6 | WebSocket live updates | 2h |
+| **Total** | | **~15h** |
+
+---
+
+## Improvement 2: Agent Polling for Collaborative Work
+
+### What Bhanu Does
+
+Every 15 minutes, each agent checks the dashboard for new items and adds input if relevant. This creates organic cross-pollination — the SEO agent sees a UX task and adds keyword data without being asked.
+
+### Our Adaptation
+
+**Normal workflow:** Agents poll every **15 minutes** (existing heartbeat cadence). During a poll, agents check:
+1. Dashboard task board for tasks in their domain
+2. Discord channels they're subscribed to for new context
+3. Any handoffs waiting for their input
+
+**Sprint mode:** During active sprints, polling increases to **5 minutes**. Manager activates sprint mode for specific agents working on a deliverable. Sprint mode auto-expires after a configurable duration (default: 2 hours).
+
+### Usage Impact
+
+| Mode | Agents Polled | Frequency | Calls/Hour | Model | Est. Cost/Hour |
+|------|--------------|-----------|------------|-------|---------------|
+| Normal | 8 | 15 min | 32 | Gemini Flash | ~$0.10 |
+| Sprint (3 agents) | 3 | 5 min | 36 | Gemini Flash | ~$0.12 |
+| Sprint (all 8) | 8 | 5 min | 96 | Gemini Flash | ~$0.30 |
+
+**Mitigation strategies:**
+- Use Gemini Flash for all polling (cheapest model)
+- Keep polling context minimal (just task board state, not full history)
+- Only sprint-poll *involved* agents, not the whole cluster
+- Auto-expire sprint mode to prevent runaway costs
+
+### Implementation
+
+| Step | Work | Effort |
+|------|------|--------|
+| 1 | Add `sprint-mode.json` config (active agents, frequency, expiry) | 1h |
+| 2 | Update agent HEARTBEAT.md templates to check task board | 1h |
+| 3 | Manager command: "start sprint [agents] [duration]" | 2h |
+| 4 | Dashboard toggle for sprint mode | 1h |
+| **Total** | | **~5h** |
+
+---
+
+## Improvement 3: Enforced Deliverables
+
+### What Bhanu Does
+
+Every task requires a deliverable to be marked done. No deliverable = task stays open. This prevents agents from saying "I worked on it" without producing anything.
+
+### Our Adaptation
+
+This is **gold** and we partially have it (handoff JSON has `artifacts` field). We need to make it mandatory and visible.
+
+**Rules:**
+1. Every task MUST have a `deliverable_type` defined at creation:
+   - `document` — markdown/PDF report
+   - `code` — script, config, or code change
+   - `analysis` — structured findings with data
+   - `recommendation` — decision brief with options
+   - `review` — audit/validation report
+2. Task cannot move to "done" without an artifact path in the handoff JSON
+3. Dashboard shows deliverable status: 📎 attached / ⚠️ missing
+4. Manager enforces this — rejects handoffs without deliverables
+
+### Changes to Handoff Schema
+
+```json
+{
+  "schemaVersion": "1.1",
+  "runId": "...",
+  "agent": "webster",
+  "status": "complete",
+  "result": "...",
+  "deliverable": {
+    "type": "analysis",
+    "title": "Clearceram-Z HS CTE Comparison",
+    "path": "/home/papa/atomizer/deliverables/2026-02-16-cte-comparison.md",
+    "summary": "CCZ HS matches Zerodur Class 0 CTE spec at 0 ± 0.02 ppm/K (20-300K)"
+  },
+  "confidence": "high",
+  "timestamp": "2026-02-16T03:00:00Z"
+}
+```
+
+### Implementation
+
+| Step | Work | Effort |
+|------|------|--------|
+| 1 | Update handoff schema (v1.1) with mandatory deliverable block | 1h |
+| 2 | Update agent SOUL.md instructions re: deliverables | 1h |
+| 3 | Add validation in orchestrate.sh (reject if no deliverable) | 1h |
+| 4 | Dashboard: show deliverable status on task cards | 1h |
+| **Total** | | **~4h** |
+
+---
+
+## Improvement 4: Discord as the Backbone (Not the Dashboard)
+
+### Why We're Different from Bhanu
+
+Bhanu channels everything through one agent (Jarvis) and uses a custom dashboard as the shared workspace. We have something better: **Discord with topic-based channels**.
+
+**Advantages of our approach:**
+- **Visibility** — Antoine sees all agent work in real-time across channels
+- **Context** — each channel is a focused workspace, not a noisy firehose
+- **Showcase** — looks like a real engineering team (video-worthy, client-facing potential)
+- **Direct access** — Antoine can jump into any channel and talk to any agent
+- **History** — Discord retains full conversation history per topic
+- **Manager still orchestrates** — creates channels, assigns work, enforces deliverables
+
+### What the Dashboard Adds on Top
+
+The dashboard doesn't replace Discord — it's the **bird's eye view**:
+- Discord = the workspace (where work happens)
+- Dashboard = the control panel (where you see the big picture)
+
+Agents work in Discord channels. The dashboard aggregates their status.
+
+### Manager's Channel Management Role
+
+Manager should actively manage Discord channels:
+- Create project channels when new work starts (`#proj-starspec-wfe`)
+- Archive channels when work completes
+- Pin key deliverables in channels
+- Post daily summaries in `#all-atomizer-hq`
+- Route new tasks to appropriate channels
+
+### Implementation
+
+| Step | Work | Effort |
+|------|------|--------|
+| 1 | Update Manager SOUL.md with channel management duties | 1h |
+| 2 | Channel naming convention doc | 0.5h |
+| 3 | Manager creates channels via Discord API on task creation | 2h |
+| **Total** | | **~3.5h** |
+
+---
+
+## Improvement 5: Vacation / Autonomous Mode
+
+### What Bhanu Does
+
+Tells Jarvis "don't wait on me, you be the final call" — Jarvis auto-approves everything for days. Comes back to find 97 items completed.
+
+### Our Adaptation
+
+A "trust level" setting for Manager:
+
+| Level | Behavior |
+|-------|----------|
+| **Normal** | Escalate decisions, wait for Antoine on approvals |
+| **Autonomous** | Manager auto-approves routine work, only escalates high-risk items |
+| **Full auto** | Manager approves everything, Antoine reviews async when back |
+
+Activated via: message Manager in Discord or Slack: "Going offline for 3 days, autonomous mode"
+
+### Implementation
+
+| Step | Work | Effort |
+|------|------|--------|
+| 1 | Add trust-level config to Manager's workspace | 1h |
+| 2 | Update Manager SOUL.md with approval logic per level | 1h |
+| 3 | Dashboard indicator showing current mode | 0.5h |
+| **Total** | | **~2.5h** |
+
+---
+
+## Execution Priority
+
+| # | Improvement | Effort | Impact | Priority |
+|---|------------|--------|--------|----------|
+| 3 | Enforced Deliverables | 4h | 🔴 High — changes agent behavior now | **Do first** |
+| 1 | HQ Orchestration Dashboard | 15h | 🔴 High — visibility into everything | **Do second** |
+| 2 | Agent Polling / Sprint Mode | 5h | 🟡 Medium — enables collaboration | **Do third** |
+| 4 | Discord Channel Management | 3.5h | 🟡 Medium — better organization | **Do fourth** |
+| 5 | Vacation / Autonomous Mode | 2.5h | 🟢 Nice to have | **Do last** |
+
+**Total estimated effort: ~30 hours**
+
+---
+
+## What We're NOT Doing (Intentionally)
+
+- **Single-agent entry point** — We keep Discord multi-channel. More visibility > more control.
+- **Custom project management app** — Dashboard is lightweight. Discord is the workspace.
+- **Feature development dashboard** — Tracked in Discord + roadmap docs.
+- **Project optimization dashboard** — The existing Atomizer dashboard handles study monitoring.
+- **Squad chat** — We already have this via Discord channels, and it's better.
+
+---
+
+## Dependencies
+
+- **Orchestration engine (doc 10)** — Handoff JSON schema is the data backbone for the dashboard
+- **orchestrate.sh** — Must be working for task tracking
+- **Agent cluster** — All 8 instances need to be stable
+
+---
+
+*Prepared by Mario — 2026-02-16*