diff --git a/docs/hq/11-HQ-IMPROVEMENTS-PLAN.md b/docs/hq/11-HQ-IMPROVEMENTS-PLAN.md new file mode 100644 index 00000000..e6fdaab2 --- /dev/null +++ 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*