zenchantlive 812b6cf8c5 docs: add planning documents for buff epic and unified UX

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.

2026-02-15 21:19:14 -08:00

2.6 KiB

Raw Blame History

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.

2.6 KiB Raw Blame History