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*
|
||||
253
docs/protocols/operative-protocol-v1.md
Normal file
253
docs/protocols/operative-protocol-v1.md
Normal file
|
|
@ -0,0 +1,253 @@
|
|||
# Operative Protocol v1 (Session Constitution)
|
||||
|
||||
Date: 2026-02-14
|
||||
Status: Approved for implementation
|
||||
Scope: `bb-u6f.6.1`
|
||||
Applies to: `bb-u6f.6.2`, `bb-u6f.6.3`, `bb-u6f.6.4`, `bb-u6f.6.5`
|
||||
|
||||
## 1. Purpose and Boundaries
|
||||
|
||||
This protocol defines non-negotiable coordination behavior for multi-agent work in BeadBoard Sessions.
|
||||
|
||||
Boundaries:
|
||||
1. Work lifecycle state remains Beads-native (`bd` commands only).
|
||||
2. Agent coordination state lives in `bb agent` surfaces and supporting local stores.
|
||||
3. No direct writes to `.beads/issues.jsonl`.
|
||||
4. User-facing labels must stay plain language.
|
||||
|
||||
## 2. Normative Language
|
||||
|
||||
1. MUST: required behavior.
|
||||
2. SHOULD: recommended unless explicit exception is justified.
|
||||
3. MAY: optional behavior.
|
||||
|
||||
## 3. Identity Trust Model
|
||||
|
||||
### 3.1 Identity primitives
|
||||
|
||||
Every active session has:
|
||||
1. `session_agent_id`: unique working identity for the current runtime.
|
||||
2. `logical_agent_id`: persistent persona name used in coordination records.
|
||||
|
||||
For v1 implementation, both map to the same field (`agent_id`), but contract keeps room for split in future.
|
||||
|
||||
### 3.2 Adoption policy (resume prior identity)
|
||||
|
||||
Identity adoption is allowed only when at least one condition is true:
|
||||
1. Uncommitted changes exist in target scope (`git status --porcelain` contains files in claimed scope).
|
||||
2. Target identity owns at least one `in_progress` bead relevant to current scope.
|
||||
|
||||
If neither condition is true, adoption MUST be rejected in non-interactive mode and SHOULD require explicit confirmation in interactive mode.
|
||||
|
||||
### 3.3 Session uniqueness policy
|
||||
|
||||
1. Each runtime session MUST start with a unique identity name for that session, unless valid adoption is selected.
|
||||
2. Reusing previous identity without adoption checks is forbidden.
|
||||
3. Recommended naming style is adjective-noun (for example, `amber-otter`, `cobalt-harbor`).
|
||||
|
||||
### 3.4 Mandatory resume audit signal
|
||||
|
||||
Any successful identity adoption MUST emit a `RESUME` protocol event with:
|
||||
1. prior owner identity,
|
||||
2. adoption reason (`uncommitted_scope` or `in_progress_ownership`),
|
||||
3. linked bead id(s) when known.
|
||||
|
||||
Event must be persisted in coordination history exposed to Sessions APIs.
|
||||
|
||||
## 4. Heartbeat and Liveness Contract
|
||||
|
||||
### 4.1 Environment and defaults
|
||||
|
||||
1. `BB_AGENT_STALE_MINUTES` default: `15`.
|
||||
2. Stale threshold: `T_last_seen + stale_minutes`.
|
||||
3. Eviction threshold: `T_last_seen + (2 * stale_minutes)`; default `30` minutes.
|
||||
|
||||
### 4.2 Heartbeat behavior
|
||||
|
||||
1. `bb agent heartbeat --agent <id>` MUST update `last_seen_at` in UTC ISO-8601.
|
||||
2. Heartbeat command MUST be idempotent and safe to run repeatedly.
|
||||
3. Heartbeat command MUST support JSON envelope output (`ok`, `command`, `data`, `error`).
|
||||
|
||||
### 4.3 Liveness states
|
||||
|
||||
Derived states:
|
||||
1. `active`: now < stale threshold.
|
||||
2. `stale`: stale threshold <= now < eviction threshold.
|
||||
3. `evicted`: now >= eviction threshold.
|
||||
|
||||
### 4.4 Reservation interaction rules
|
||||
|
||||
For scope takeover:
|
||||
1. If reservation owner is `active`: takeover MUST fail.
|
||||
2. If owner is `stale`: takeover MAY succeed only when `--takeover-stale` is supplied.
|
||||
3. If owner is `evicted`: takeover SHOULD succeed with `--takeover-stale`; prior reservation must be archived as expired.
|
||||
|
||||
## 5. Path Overlap Canonicalization Contract
|
||||
|
||||
### 5.1 Normalization pipeline
|
||||
|
||||
All scope comparisons MUST use the same normalization pipeline:
|
||||
1. Resolve to absolute path (`path.resolve`).
|
||||
2. Normalize separators to `/`.
|
||||
3. On Windows, lowercase normalized path for comparisons.
|
||||
4. Remove trailing slash except root.
|
||||
|
||||
### 5.2 Scope classes
|
||||
|
||||
Given normalized `A` and `B`:
|
||||
1. `exact`: `A === B`.
|
||||
2. `partial`: `A` is parent of `B` or `B` is parent of `A`.
|
||||
3. `disjoint`: neither exact nor parent-child.
|
||||
|
||||
Wildcards:
|
||||
1. Prefix wildcard (`src/*`) is treated as directory prefix match for overlap checks.
|
||||
2. Glob semantics beyond suffix `*` are out of scope for v1.
|
||||
|
||||
### 5.3 Required examples
|
||||
|
||||
1. `src/*` vs `src/lib/parser.ts` => `partial`.
|
||||
2. `src/lib` vs `src/lib/parser.ts` => `partial`.
|
||||
3. `src/lib/parser.ts` vs `src/lib/parser.ts` => `exact`.
|
||||
4. `src/lib` vs `src/components` => `disjoint`.
|
||||
|
||||
## 6. Protocol Event Schema (Stable JSON Contract)
|
||||
|
||||
### 6.1 Envelope (all protocol events)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "proto_20260214_001",
|
||||
"version": "v1",
|
||||
"event_type": "HANDOFF",
|
||||
"project_root": "C:/Users/Zenchant/codex/beadboard",
|
||||
"bead_id": "bb-u6f.6.3",
|
||||
"from_agent": "amber-otter",
|
||||
"to_agent": "cobalt-harbor",
|
||||
"scope": "src/components/sessions/*",
|
||||
"created_at": "2026-02-14T18:05:11.000Z",
|
||||
"payload": {}
|
||||
}
|
||||
```
|
||||
|
||||
Required fields:
|
||||
1. `id`
|
||||
2. `version` (must be `v1` for this protocol)
|
||||
3. `event_type`
|
||||
4. `project_root`
|
||||
5. `bead_id`
|
||||
6. `from_agent` (nullable for system-originated events only)
|
||||
7. `to_agent` (nullable for system-originated events only)
|
||||
8. `scope` (nullable where not applicable)
|
||||
9. `created_at`
|
||||
10. `payload`
|
||||
|
||||
### 6.2 Event-specific payloads
|
||||
|
||||
`HANDOFF` payload:
|
||||
1. `subject` (required)
|
||||
2. `summary` (required)
|
||||
3. `next_action` (required)
|
||||
4. `requires_ack` (required, true by default)
|
||||
|
||||
`BLOCKED` payload:
|
||||
1. `subject` (required)
|
||||
2. `blocker` (required)
|
||||
3. `requested_action` (required)
|
||||
4. `urgency` (required: `low|medium|high`)
|
||||
5. `requires_ack` (required, true)
|
||||
|
||||
`INCURSION` payload:
|
||||
1. `incursion_kind` (required: `exact|partial`)
|
||||
2. `owner_agent` (required)
|
||||
3. `incoming_agent` (required)
|
||||
4. `owner_liveness` (required: `active|stale|evicted`)
|
||||
5. `resolution_hint` (required)
|
||||
|
||||
`RESUME` payload:
|
||||
1. `resume_reason` (required: `uncommitted_scope|in_progress_ownership`)
|
||||
2. `prior_session_agent` (required)
|
||||
3. `adopted_agent` (required)
|
||||
4. `evidence` (required string summary of why adoption passed)
|
||||
|
||||
### 6.3 UI mapping requirements
|
||||
|
||||
Sessions UI mapping contract:
|
||||
1. `HANDOFF` label: `Passed to`
|
||||
2. `BLOCKED` label: `Needs input`
|
||||
3. Read action label: `Seen`
|
||||
4. Ack action label: `Accepted`
|
||||
|
||||
`INCURSION` and `RESUME` MUST render as first-class protocol rows in the conversation timeline, not hidden diagnostics.
|
||||
|
||||
## 7. CLI Contract Requirements for Implementers
|
||||
|
||||
Required commands for v1 rollout:
|
||||
1. `bb agent heartbeat --agent <id> [--json]`
|
||||
2. `node scripts/bb-init.mjs --non-interactive --json`
|
||||
3. `node scripts/bb-init.mjs --adopt <agentId> --json`
|
||||
4. `node scripts/bb-init.mjs --register <name> --json`
|
||||
|
||||
Non-interactive requirements:
|
||||
1. MUST not prompt.
|
||||
2. MUST fail with structured error when decision cannot be made safely.
|
||||
3. MUST include deterministic recommendation reason in output.
|
||||
|
||||
## 8. Mapping to Existing Code Modules
|
||||
|
||||
### 8.1 Backend
|
||||
|
||||
1. `src/lib/agent-registry.ts`
|
||||
2. `src/lib/agent-reservations.ts`
|
||||
3. `src/lib/realtime.ts`
|
||||
4. `src/lib/agent-sessions.ts`
|
||||
|
||||
### 8.2 API
|
||||
|
||||
1. `src/app/api/sessions/route.ts`
|
||||
2. `src/app/api/sessions/[beadId]/conversation/route.ts`
|
||||
|
||||
### 8.3 UI
|
||||
|
||||
1. `src/components/sessions/session-feed-card.tsx`
|
||||
2. `src/components/sessions/session-task-feed.tsx`
|
||||
3. `src/components/sessions/conversation-drawer.tsx`
|
||||
4. `src/components/sessions/sessions-page.tsx`
|
||||
5. `src/hooks/use-session-feed.ts`
|
||||
6. `src/hooks/use-beads-subscription.ts`
|
||||
|
||||
### 8.4 CLI and skill
|
||||
|
||||
1. `tools/bb.ts`
|
||||
2. `scripts/bb-init.mjs` (new)
|
||||
3. `skills/beadboard-driver/SKILL.md`
|
||||
|
||||
## 9. Acceptance Checklist for Downstream Beads
|
||||
|
||||
`bb-u6f.6.2` MUST implement:
|
||||
1. heartbeat mutation,
|
||||
2. stale/evicted derivation,
|
||||
3. overlap classification,
|
||||
4. protocol event emission.
|
||||
|
||||
`bb-u6f.6.3` MUST implement:
|
||||
1. heartbeat command,
|
||||
2. non-interactive `bb-init` contract and flags.
|
||||
|
||||
`bb-u6f.6.4` MUST implement:
|
||||
1. protocol event rendering in Sessions,
|
||||
2. incursion/stale visibility,
|
||||
3. no-refresh-required update behavior.
|
||||
|
||||
`bb-u6f.6.5` MUST implement:
|
||||
1. updated skill flow matching this protocol exactly.
|
||||
|
||||
## 10. Rejected Alternatives
|
||||
|
||||
1. Interactive-only bootstrap prompts.
|
||||
Reason: automation sessions require deterministic non-blocking behavior.
|
||||
|
||||
2. Implicit overlap inference without normalization contract.
|
||||
Reason: inconsistent behavior across Windows paths.
|
||||
|
||||
3. UI-first implementation before protocol schema.
|
||||
Reason: high risk of repeated API/UI contract churn.
|
||||
Loading…
Add table
Add a link
Reference in a new issue