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.
This commit is contained in:
zenchantlive
parent
b905d21526
commit
812b6cf8c5
4 changed files with 640 additions and 0 deletions
112
docs/plans/2026-02-14-operative-protocol-design.md
Normal file
112
docs/plans/2026-02-14-operative-protocol-design.md
Normal file
|
|
@ -0,0 +1,112 @@
|
|||
# Operative Protocol Implementation Plan
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Implement a robust agent coordination protocol that leverages the "Social-Dense" Hub for supervision and enables "Optimistic Concurrency" (traceable incursions) between agents.
|
||||
|
||||
**Architecture:** We use a "Codebase as Reality" model where physical file changes trigger contextual lookups in the Agent Inbox. A new `bb-init` tool handles session bootstrapping and identity adoption, while a heartbeat mechanism provides real-time supervisor observability.
|
||||
|
||||
**Tech Stack:** Next.js 15, TypeScript, PowerShell (bb.ps1), Node.js (scripts), SSE (real-time).
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Infrastructure - Agent Heartbeat & Stale Logic
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/lib/agent-registry.ts`
|
||||
- Modify: `src/lib/agent-reservations.ts`
|
||||
- Test: `tests/lib/agent-heartbeat.test.ts`
|
||||
|
||||
**Step 1: Implement Heartbeat update logic**
|
||||
Add `heartbeatAgent(agentId: string)` to `agent-registry.ts` to update `last_seen_at`.
|
||||
|
||||
**Step 2: Implement Stale Detection**
|
||||
In `agent-reservations.ts`, add logic to `reserveAgentScope` that allows `takeoverStale: true` if the current owner's `last_seen_at` is > 15 minutes old.
|
||||
|
||||
**Step 3: Test Heartbeat and Takeover**
|
||||
Write a test verifying that an agent can take over a scope if the owner is stale, but is blocked if the owner is active.
|
||||
|
||||
**Step 4: Commit**
|
||||
```bash
|
||||
git add src/lib/agent-registry.ts src/lib/agent-reservations.ts tests/lib/agent-heartbeat.test.ts
|
||||
git commit -m "feat(infra): implement agent heartbeat and stale reservation takeover"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Bootstrapping - The `bb-init` Tool
|
||||
|
||||
**Files:**
|
||||
- Create: `scripts/bb-init.mjs`
|
||||
- Modify: `beadboard/tools/bb.ts` (add heartbeat command)
|
||||
- Test: `tests/scripts/bb-init.test.ts`
|
||||
|
||||
**Step 1: Create `bb-init.mjs`**
|
||||
Implement logic to:
|
||||
1. Resolve `bb.ps1` path.
|
||||
2. Check for uncommitted changes (`git status`).
|
||||
3. If changes exist, query `bb agent status --scope <changed-path>` to find previous owner.
|
||||
4. Prompt for identity adoption or new registration.
|
||||
|
||||
**Step 2: Add `bb agent heartbeat` CLI command**
|
||||
Expose the heartbeat logic in `tools/bb.ts` so agents can call it.
|
||||
|
||||
**Step 3: Test Bootstrap Flow**
|
||||
Verify `bb-init` correctly identifies uncommitted changes and suggests the right previous agent.
|
||||
|
||||
**Step 4: Commit**
|
||||
```bash
|
||||
git add scripts/bb-init.mjs beadboard/tools/bb.ts
|
||||
git commit -m "feat(infra): add bb-init bootstrapping and heartbeat CLI command"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Frontend - Incursion & Overlap Visualization
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/components/sessions/AgentScorecard.tsx`
|
||||
- Modify: `src/components/sessions/AuditFeed.tsx`
|
||||
- Modify: `src/hooks/useSSE.ts`
|
||||
|
||||
**Step 1: Update Agent Scorecard**
|
||||
Add visual states for `INVADING` (Shared Scope) and `STALE` (Heartbeat lost).
|
||||
|
||||
**Step 2: Implement Incursion Alert**
|
||||
In the Sessions Hub, show a connection line or alert banner when two agents have active reservations in overlapping scopes.
|
||||
|
||||
**Step 3: Stream Protocol Messages**
|
||||
Ensure `INFO`, `HANDOFF`, and `BLOCKED` messages appear prominently in the `AuditFeed` with bead-link icons.
|
||||
|
||||
**Step 4: Commit**
|
||||
```bash
|
||||
git add src/components/sessions/ src/hooks/useSSE.ts
|
||||
git commit -m "feat(ui): visualize agent incursions and protocol messages in Hub"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Education - Refactor Agent Skill
|
||||
|
||||
**Files:**
|
||||
- Modify: `beadboard/skills/beadboard-driver/SKILL.md`
|
||||
|
||||
**Step 1: Rewrite for "Operative Protocol"**
|
||||
Replace the old workflow with the new "Good Citizen" loop:
|
||||
1. `node scripts/bb-init.mjs` (Boot/Adopt).
|
||||
2. `bb agent reserve` (Claim Territory).
|
||||
3. **Physical Change -> Contextual Lookup** (Check inbox if you see unexpected changes).
|
||||
4. `bb agent send --category INFO` (Explain incursions/milestones).
|
||||
5. `bb agent heartbeat` (Keep your light green).
|
||||
|
||||
**Step 2: Add Rationalization Table**
|
||||
Add the "Excuse vs Reality" table to stop agents from skipping protocol.
|
||||
|
||||
**Step 3: Add Red Flags**
|
||||
Define "Silent Incursion" and "Mocking" as red flags.
|
||||
|
||||
**Step 4: Commit**
|
||||
```bash
|
||||
git add beadboard/skills/beadboard-driver/SKILL.md
|
||||
git commit -m "docs(skill): refactor beadboard-driver to the Operative Protocol"
|
||||
```
|
||||
64
docs/plans/2026-02-14-super-agent-buff-roadmap.md
Normal file
64
docs/plans/2026-02-14-super-agent-buff-roadmap.md
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
# 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.
|
||||
211
docs/plans/2026-02-15-unified-ux-prd.md
Normal file
211
docs/plans/2026-02-15-unified-ux-prd.md
Normal file
|
|
@ -0,0 +1,211 @@
|
|||
# Unified UX PRD - Swimlane Social Hub
|
||||
|
||||
> **Version**: 1.0
|
||||
> **Date**: 2026-02-15
|
||||
> **Status**: Planning Complete - Ready for Bead Creation
|
||||
> **Supersedes**: bb-u6f.7 (Unified Cross-Surface Navigation)
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
### Problem
|
||||
BeadBoard has 4 fragmented pages with:
|
||||
- No shared navigation or state
|
||||
- Inconsistent design language (Aero Chrome glass-morphism feels dated)
|
||||
- /sessions has good tech but missed the UX mark
|
||||
- Users cannot supervise multi-agent teams in one cohesive experience
|
||||
|
||||
### Solution
|
||||
Single unified shell at `/` with 3 views:
|
||||
- **Social** - Task activity feed with blocks/unlocks
|
||||
- **Graph** - Dependency visualization
|
||||
- **Swarm** - Team health dashboard
|
||||
|
||||
---
|
||||
|
||||
## Key Decisions (Immutable)
|
||||
|
||||
| # | Decision | Choice | Rationale |
|
||||
|---|----------|--------|-----------|
|
||||
| 1 | Routing | Single page at `/` with client tabs | Preserves selection state |
|
||||
| 2 | Views | 3 tabs: Social, Graph, Swarm | Sessions replaced by Social |
|
||||
| 3 | Detail pattern | Right sidebar (desktop), drawer (mobile) | Best use of screens |
|
||||
| 4 | Visual style | shadcn/ui + earthy-dark tokens | Replace Aero Chrome |
|
||||
| 5 | Tailwind | Stay on v3, use shadcn/ui patterns | v4 has migration risks |
|
||||
| 6 | Old pages | Copy page.tsx to page-old.tsx | Safe rollback |
|
||||
| 7 | Card pattern | Same base for Social and Swarm | Reusable components |
|
||||
| 8 | Threads | In detail strip for both views | Comments + events |
|
||||
| 9 | Agent presence | Embedded in swarm cards | Agents primary in Swarm |
|
||||
| 10 | Swarm sorting | Health (default), Activity, Progress | Auto-surface attention |
|
||||
|
||||
---
|
||||
|
||||
## Skills Required (Non-Negotiable)
|
||||
|
||||
1. **verification-before-completion** - Never claim done without proving commands
|
||||
2. **test-driven-development** - Write failing tests first
|
||||
3. **beadboard-driver** - Use bd commands for all bead operations
|
||||
4. **linus-beads-discipline** - Single source of truth, evidence before assertion
|
||||
|
||||
---
|
||||
|
||||
## Design System Specification
|
||||
|
||||
### Color Palette (Earthy-Dark)
|
||||
|
||||
Backgrounds:
|
||||
- --color-bg-base: #2D2D2D
|
||||
- --color-bg-card: #363636
|
||||
- --color-bg-input: #404040
|
||||
|
||||
Accents:
|
||||
- --color-accent-green: #7CB97A (primary CTA)
|
||||
- --color-accent-amber: #D4A574 (warning)
|
||||
- --color-accent-teal: #5BA8A0 (secondary)
|
||||
|
||||
Text:
|
||||
- --color-text-primary: #FFFFFF
|
||||
- --color-text-secondary: #B8B8B8
|
||||
- --color-text-muted: #888888
|
||||
|
||||
Status:
|
||||
- ready: teal #5BA8A0
|
||||
- in_progress: green #7CB97A
|
||||
- blocked: amber #D4A574
|
||||
- closed: muted #888888
|
||||
|
||||
Liveness:
|
||||
- active: #7CB97A
|
||||
- stale: #D4A574
|
||||
- stuck: #E57373
|
||||
- dead: #9E4244
|
||||
|
||||
---
|
||||
|
||||
## Layout Architecture
|
||||
|
||||
Shell Structure (CSS Grid):
|
||||
- TOP BAR: 3rem fixed
|
||||
- LEFT: 13rem (channel tree)
|
||||
- MIDDLE: flex-1 (card grid)
|
||||
- RIGHT: 17rem (detail strip)
|
||||
|
||||
Responsive:
|
||||
- < 768px: Full width, drawer overlay
|
||||
- 768-1024px: Left collapses, slide-over
|
||||
- >= 1024px: Full 3-panel
|
||||
|
||||
URL State:
|
||||
- view: social | graph | swarm
|
||||
- task: selected task ID
|
||||
- swarm: selected swarm ID
|
||||
- panel: open | closed
|
||||
|
||||
---
|
||||
|
||||
## View Specifications
|
||||
|
||||
### Social View
|
||||
Card: Task ID (teal), Title (bold), UNLOCKS (rose), BLOCKS (amber), Agents, View-jump icons
|
||||
|
||||
### Graph View
|
||||
Keep ReactFlow + Dagre, add fitView() on tab activation
|
||||
|
||||
### Swarm View
|
||||
Card: Swarm ID, Epic title, AGENTS roster with status glow, ATTENTION items, Progress bar, Last activity
|
||||
|
||||
Sorting: Health (default), Activity, Progress, Name
|
||||
|
||||
---
|
||||
|
||||
## Dependency Graph (Bead Flow)
|
||||
|
||||
PHASE 0: Design Foundation
|
||||
[0.1] Token System
|
||||
[0.2] shadcn/ui Setup
|
||||
[0.3] Base Primitives
|
||||
|
||||
PHASE 1: Shell Layout
|
||||
[1.1] URL State Hook
|
||||
[1.2] UnifiedShell Component <- [0.*][1.1]
|
||||
[1.3] TopBar Component <- [1.2]
|
||||
[1.4] LeftPanel Component <- [1.2]
|
||||
[1.5] RightPanel Component <- [1.2]
|
||||
[1.6] Responsive Behavior <- [1.3-1.5]
|
||||
|
||||
PHASE 2: Social View
|
||||
[2.1] Social Card Data Builder
|
||||
[2.2] SocialCard Component <- [0.3][2.1]
|
||||
[2.3] Social Detail Strip <- [1.5][2.1]
|
||||
[2.4] Thread View Component <- [2.3]
|
||||
[2.5] Social View Integration <- [1.2][2.2-2.4]
|
||||
|
||||
PHASE 3: Swarm View
|
||||
[3.1] Swarm Card Data Builder
|
||||
[3.2] SwarmCard Component <- [0.3][3.1]
|
||||
[3.3] Swarm Detail Strip <- [1.5][3.1]
|
||||
[3.4] Swarm View Integration <- [1.2][3.2-3.3]
|
||||
|
||||
PHASE 4: Graph Migration
|
||||
[4.1] Graph Component Extraction
|
||||
[4.2] Graph Tab Integration <- [1.2][4.1]
|
||||
[4.3] fitView Fix <- [4.2]
|
||||
|
||||
PHASE 5: Polish
|
||||
[5.1] Deep Link Verification <- [all above]
|
||||
[5.2] Mobile Responsive Polish
|
||||
[5.3] Screenshot Evidence
|
||||
[5.4] Final Quality Gates
|
||||
|
||||
---
|
||||
|
||||
## Verification Gates (Required)
|
||||
|
||||
Every bead MUST pass before closing:
|
||||
- npm run typecheck
|
||||
- npm run lint
|
||||
- npm run test
|
||||
- Screenshots for UI changes
|
||||
|
||||
---
|
||||
|
||||
## Risk Register
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| ReactFlow resize | Use visibility:hidden + fitView() |
|
||||
| shadcn + Tailwind v3 | Follow shadcn v3 docs |
|
||||
| Mobile keyboard | Full-screen drawer on mobile |
|
||||
| URL race conditions | URL is single source of truth |
|
||||
|
||||
---
|
||||
|
||||
## Migration Checklist
|
||||
|
||||
Pre:
|
||||
- [ ] Copy page.tsx to page-old.tsx
|
||||
- [ ] Verify tests pass
|
||||
|
||||
During:
|
||||
- [ ] Install shadcn/ui
|
||||
- [ ] Create globals.css with earthy-dark tokens
|
||||
- [ ] Build phases in order
|
||||
|
||||
Post:
|
||||
- [ ] All 3 views functional
|
||||
- [ ] Deep links work
|
||||
- [ ] Mobile verified
|
||||
- [ ] Screenshots captured
|
||||
|
||||
---
|
||||
|
||||
## Appendix: shadcn/ui Setup
|
||||
|
||||
bash:
|
||||
npx shadcn@latest init
|
||||
npx shadcn@latest add button card badge avatar input scroll-area separator tooltip dropdown-menu
|
||||
|
||||
---
|
||||
|
||||
*End of PRD - Ready for Bead Creation*
|
||||
Loading…
Add table
Add a link
Reference in a new issue