812b6cf8c5
STORY: Major epics require upfront planning documentation. These docs capture the design decisions, architecture, and rollout maps for the Agent System Overhaul (bb-buff) and Unified UX (bb-ui2) epics. COLLABORATION: - 2026-02-14-operative-protocol-design.md: ZFC state machine design - 2026-02-14-super-agent-buff-roadmap.md: buff epic architecture - 2026-02-15-unified-ux-prd.md: UI epic product requirements - docs/protocols/: protocol specifications These documents serve as the source of truth for implementation decisions and help future contributors understand the design rationale.
64 lines
2.6 KiB
Markdown
64 lines
2.6 KiB
Markdown
# Super-Agent Buff Implementation Plan
|
|
|
|
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
|
|
|
**Goal:** Comprehensive overhaul of the agent system to use native `bd` primitives: Molecules (swarming), Wisps (clean telemetry), and the ZFC State Machine (resiliency).
|
|
|
|
**Architecture:** We move from a simulated coordination layer to a native orchestration layer. Telemetry is offloaded to auto-compacting Wisps, while agent identities become environment-aware (Rig/Role). The UI evolves into a swarm-aware Command Center.
|
|
|
|
**Tech Stack:** Next.js 15, TypeScript, bd CLI (v0.49.6), ZFC State Machine.
|
|
|
|
---
|
|
|
|
### Bead 1: Resiliency Engine (bb-6bx)
|
|
**Files:** `src/lib/agent-registry.ts`, `src/lib/agent-sessions.ts`, `tools/bb.ts`
|
|
|
|
**Step 1: Implement Wisp-Native Heartbeats**
|
|
Refactor `extendActivityLease` to call `bd create --type event --wisp-type heartbeat --ephemeral`.
|
|
Verify with `bd list --wisp-type heartbeat`.
|
|
|
|
**Step 2: Implement ZFC State Wrapper**
|
|
Add `setAgentState(agentId, state)` to the registry. Support: `idle`, `working`, `stuck`, `dead`.
|
|
Expose via `bb agent state --id <id> --status <status>`.
|
|
|
|
**Step 3: Refactor Liveness Derivation**
|
|
Update `deriveLiveness` to query the latest `heartbeat` wisp instead of the agent bead's `updated_at`.
|
|
|
|
---
|
|
|
|
### Bead 2: Orchestration Layer
|
|
**Files:** `src/lib/agent-registry.ts`, `scripts/bb-init.mjs`, `src/lib/agent-protocol.ts`
|
|
|
|
**Step 1: Rig/Role Identity Fingerprint**
|
|
Add `rig` and `role_type` to `AgentRecord`.
|
|
Update `bb-init.mjs` to auto-populate `rig` (e.g., `os.platform() + os.hostname()`).
|
|
|
|
**Step 2: Swarm Molecule Formation**
|
|
Implement `autoJoinSwarm(beadId)` in the registry. If a task belongs to an Epic, the agent joins that Epic's Swarm Molecule.
|
|
|
|
**Step 3: Role-Based Protocol Routing**
|
|
Update `sendAgentMessage` to allow `to_agent` to be a role (e.g., `role:ui`).
|
|
|
|
---
|
|
|
|
### Bead 3: Command Center v2 (UI)
|
|
**Files:** `src/components/sessions/*`, `src/hooks/use-session-feed.ts`
|
|
|
|
**Step 1: Swarm-Grouped Header**
|
|
Refactor `SessionsHeader` to group AgentStations by their `molecule_id`.
|
|
|
|
**Step 2: Environment-Aware Agent Cards**
|
|
Add Rig icons and Role badges to `AgentStation`.
|
|
Implement **FLASHING RED** style for agents in `stuck` state.
|
|
|
|
**Step 3: Live Task-Agent Linkage**
|
|
Visualize the "Active Mission" by highlighting the specific task card currently being worked on by the selected agent.
|
|
|
|
---
|
|
|
|
### Bead 4: Skill Update (Handbook v3)
|
|
**Files:** `skills/beadboard-driver/SKILL.md`
|
|
|
|
**Step 1: Codify Signal Discipline**
|
|
Rewrite the handbook to mandate `setAgentState` usage and Wisp-telemetry etiquette.
|
|
Add "Stuck-Signaling" as a required recovery pattern.
|