diff --git a/docs/plans/2026-02-14-operative-protocol-design.md b/docs/plans/2026-02-14-operative-protocol-design.md new file mode 100644 index 0000000..c026c52 --- /dev/null +++ b/docs/plans/2026-02-14-operative-protocol-design.md @@ -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 ` 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" +``` diff --git a/docs/plans/2026-02-14-super-agent-buff-roadmap.md b/docs/plans/2026-02-14-super-agent-buff-roadmap.md new file mode 100644 index 0000000..a7b75e2 --- /dev/null +++ b/docs/plans/2026-02-14-super-agent-buff-roadmap.md @@ -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 --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. diff --git a/docs/plans/2026-02-15-unified-ux-prd.md b/docs/plans/2026-02-15-unified-ux-prd.md new file mode 100644 index 0000000..8370d3a --- /dev/null +++ b/docs/plans/2026-02-15-unified-ux-prd.md @@ -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* diff --git a/docs/protocols/operative-protocol-v1.md b/docs/protocols/operative-protocol-v1.md new file mode 100644 index 0000000..73b0c23 --- /dev/null +++ b/docs/protocols/operative-protocol-v1.md @@ -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 ` 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 [--json]` +2. `node scripts/bb-init.mjs --non-interactive --json` +3. `node scripts/bb-init.mjs --adopt --json` +4. `node scripts/bb-init.mjs --register --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.