viktor/beadboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(ux): consolidate Launch Swarm + telemetry UX with minimized strip

Browse source 
- Removed broken LaunchSwarmDialog (formula-based) from TopBar/LeftPanel
- All Rocket buttons (TopBar, LeftPanel, DAG nodes, social cards) now open
  AssignmentPanel (archetype-based) which actually works
- Every Rocket clears taskId first so assignMode && !taskId condition passes
- Conversation button priority: taskId always shows conversation, not assign panel
- Added TelemetryStrip: minimized right sidebar with status dots when non-telemetry
  panel (conversation/assignment) is active
- Live feed has minimize button → restores last taskId or assignMode
- DAG nodes: Signal icon → restores telemetry feed
- Social button on DAG nodes: single router.push to avoid race (setView + setTaskId)
- Fixed social card message button: opens right panel with drawer:closed (no popup)

Co-Authored-By: Oz <oz-agent@warp.dev>
This commit is contained in:
zenchantlive 2026-03-01 18:17:58 -08:00
parent 65d69ecbbc
commit c246ceaf21
165 changed files with 13730 additions and 1132 deletions
Download patch file Download diff file Expand all files Collapse all files

364
docs/plans/2026-02-28-bd-only-coordination-migration-plan.md Normal file
View file

@ -0,0 +1,364 @@
# BD-Only Coordination Migration Implementation Plan
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
**Goal:** Migrate BeadBoard coordination from `bb` command semantics to `bd`-native audit/event semantics, wire frontend to the new projections, then deprecate `bb` after approval.
**Architecture:** Coordination protocol state is append-only in `bd audit` events (`coord.v1`), lifecycle remains in normal `bd` issue/agent commands, and frontend views are served by projection APIs that derive inbox, reservations, and takeover eligibility from event history + liveness. `bb` remains temporary compatibility code during migration and is removed after parity validation.
**Tech Stack:** Next.js 15, TypeScript, `bd` CLI (Dolt backend), Node test runner (`node --test` + `tsx`)
---
## Scope Lock (Before Code)
In scope:
- `coord.v1` event schema and validators
- backend event write/read/projection paths
- sessions/conversation frontend wiring to new projection APIs
- migration guardrails and `bb` deprecation flag
Out of scope:
- redesigning unrelated views
- changing route model
- shipping a global CLI package
## Proposed Bead Breakdown
1. `bdcoord.1` Schema freeze: finalize `coord.v1` fields and transitions.
2. `bdcoord.2` Event writer API + validation.
3. `bdcoord.3` Projection engine for inbox/read/ack.
4. `bdcoord.4` Projection engine for reservations/takeover.
5. `bdcoord.5` API integration in sessions and conversation routes.
6. `bdcoord.6` Frontend wiring in conversation/sessions components.
7. `bdcoord.7` Legacy `bb` deprecation toggle and compatibility fallback.
8. `bdcoord.8` Tests + full gates + migration sign-off checklist.
## Task 1: Baseline and Schema Freeze
**Files:**
- Modify: `docs/protocols/2026-02-28-bd-audit-coordination-schema.md`
- Modify: `docs/protocols/operative-protocol-v1.md`
- Test: `tests/lib/coord-schema.test.ts` (new)
**Step 1: Write the failing test**
Create `tests/lib/coord-schema.test.ts` with assertions for:
- required fields by event type
- valid/invalid `event_ref`
- allowed takeover modes
**Step 2: Run test to verify it fails**
Run: `node --import tsx --test tests/lib/coord-schema.test.ts`
Expected: FAIL (module/validator not implemented).
**Step 3: Write minimal implementation**
Create schema constants/types in new module:
- `src/lib/coord-schema.ts`
Implement:
- event type union
- required-field checks per type
- basic runtime validator
**Step 4: Run test to verify it passes**
Run: `node --import tsx --test tests/lib/coord-schema.test.ts`
Expected: PASS.
**Step 5: Commit**
```bash
git add docs/protocols/2026-02-28-bd-audit-coordination-schema.md docs/protocols/operative-protocol-v1.md src/lib/coord-schema.ts tests/lib/coord-schema.test.ts
git commit -m "feat(protocol): freeze coord.v1 schema and validator"
```
## Task 2: Event Write Path (`bd audit`)
**Files:**
- Create: `src/lib/coord-events.ts`
- Modify: `src/lib/bridge.ts`
- Create: `src/app/api/coord/events/route.ts`
- Test: `tests/lib/coord-events.test.ts`
- Test: `tests/api/coord-events-route.test.ts`
**Step 1: Write the failing test**
Add tests for:
- successful `bd audit record --stdin` invocation
- rejection on invalid payload
- deterministic envelope normalization
**Step 2: Run test to verify it fails**
Run: `node --import tsx --test tests/lib/coord-events.test.ts`
Expected: FAIL.
**Step 3: Write minimal implementation**
In `src/lib/coord-events.ts`, implement:
- `writeCoordEvent(input, { projectRoot })`
- schema validation call
- payload -> audit entry transform
- bridge command execution
In route `src/app/api/coord/events/route.ts`:
- `POST` accepts event JSON and writes via `writeCoordEvent`
**Step 4: Run tests to verify they pass**
Run:
- `node --import tsx --test tests/lib/coord-events.test.ts`
- `node --import tsx --test tests/api/coord-events-route.test.ts`
Expected: PASS.
**Step 5: Commit**
```bash
git add src/lib/coord-events.ts src/app/api/coord/events/route.ts tests/lib/coord-events.test.ts tests/api/coord-events-route.test.ts
git commit -m "feat(coord): add bd-audit event write path and API"
```
## Task 3: Inbox Projection Engine
**Files:**
- Create: `src/lib/coord-projections.ts`
- Modify: `src/app/api/sessions/[beadId]/conversation/route.ts`
- Modify: `src/lib/agent-sessions.ts`
- Test: `tests/lib/coord-projections-inbox.test.ts`
**Step 1: Write the failing test**
Cover:
- unread/read/acked derivation from `SEND/READ/ACK`
- duplicate/late event ordering behavior
- unknown references ignored safely
**Step 2: Run test to verify it fails**
Run: `node --import tsx --test tests/lib/coord-projections-inbox.test.ts`
Expected: FAIL.
**Step 3: Write minimal implementation**
Implement projection functions:
- `projectInbox(events, beadId, agentId?)`
- `projectMessageState(events)`
Integrate route to return projected inbox entries.
**Step 4: Run test to verify it passes**
Run: `node --import tsx --test tests/lib/coord-projections-inbox.test.ts`
Expected: PASS.
**Step 5: Commit**
```bash
git add src/lib/coord-projections.ts src/app/api/sessions/[beadId]/conversation/route.ts src/lib/agent-sessions.ts tests/lib/coord-projections-inbox.test.ts
git commit -m "feat(coord): derive inbox projection from audit events"
```
## Task 4: Reservation and Takeover Projection Engine
**Files:**
- Modify: `src/lib/coord-projections.ts`
- Modify: `src/lib/agent-sessions.ts`
- Modify: `src/app/api/sessions/route.ts`
- Test: `tests/lib/coord-projections-reservations.test.ts`
**Step 1: Write the failing test**
Cover:
- exact/partial/disjoint overlap
- active/stale/evicted takeover policy
- release and supersession behavior
**Step 2: Run test to verify it fails**
Run: `node --import tsx --test tests/lib/coord-projections-reservations.test.ts`
Expected: FAIL.
**Step 3: Write minimal implementation**
Add:
- scope normalization utility
- reservation reducer over events
- takeover eligibility helper using agent liveness
Expose projected reservation/incursion shape from sessions API.
**Step 4: Run test to verify it passes**
Run: `node --import tsx --test tests/lib/coord-projections-reservations.test.ts`
Expected: PASS.
**Step 5: Commit**
```bash
git add src/lib/coord-projections.ts src/lib/agent-sessions.ts src/app/api/sessions/route.ts tests/lib/coord-projections-reservations.test.ts
git commit -m "feat(coord): add reservation and takeover projections"
```
## Task 5: Conversation and Sessions Frontend Wiring
**Files:**
- Modify: `src/components/sessions/conversation-drawer.tsx`
- Modify: `src/components/sessions/sessions-page.tsx`
- Modify: `src/hooks/use-session-feed.ts`
- Test: `tests/components/sessions/conversation-drawer-coord.test.tsx` (new)
- Test: `tests/api/sessions-route.test.ts`
**Step 1: Write the failing test**
Cover:
- render projected message state labels
- mark read/ack via new coord event endpoint
- refresh behavior without full page reload
**Step 2: Run test to verify it fails**
Run: `node --import tsx --test tests/components/sessions/conversation-drawer-coord.test.tsx`
Expected: FAIL.
**Step 3: Write minimal implementation**
Update drawer and hooks to:
- read new projection payloads
- post `READ/ACK/RESERVE/RELEASE/TAKEOVER` events
- preserve current UI labels and behavior
**Step 4: Run test to verify it passes**
Run:
- `node --import tsx --test tests/components/sessions/conversation-drawer-coord.test.tsx`
- `node --import tsx --test tests/api/sessions-route.test.ts`
Expected: PASS.
**Step 5: Commit**
```bash
git add src/components/sessions/conversation-drawer.tsx src/components/sessions/sessions-page.tsx src/hooks/use-session-feed.ts tests/components/sessions/conversation-drawer-coord.test.tsx tests/api/sessions-route.test.ts
git commit -m "feat(frontend): wire sessions UI to bd coordination projections"
```
## Task 6: Legacy `bb` Deprecation Toggle
**Files:**
- Modify: `src/lib/agent-mail.ts`
- Modify: `src/lib/agent-reservations.ts`
- Modify: `src/lib/agent-sessions.ts`
- Modify: `skills/beadboard-driver/SKILL.md` (defer final content until sign-off)
- Create: `docs/protocols/2026-02-28-bb-deprecation-notes.md`
- Test: `tests/lib/coord-legacy-fallback.test.ts` (new)
**Step 1: Write the failing test**
Cover:
- when `BB_LEGACY_COMPAT=off`, only new projection path is used
- when `BB_LEGACY_COMPAT=on`, fallback remains operational
**Step 2: Run test to verify it fails**
Run: `node --import tsx --test tests/lib/coord-legacy-fallback.test.ts`
Expected: FAIL.
**Step 3: Write minimal implementation**
Add feature-flagged compatibility path and deprecation warnings in server logs.
**Step 4: Run test to verify it passes**
Run: `node --import tsx --test tests/lib/coord-legacy-fallback.test.ts`
Expected: PASS.
**Step 5: Commit**
```bash
git add src/lib/agent-mail.ts src/lib/agent-reservations.ts src/lib/agent-sessions.ts docs/protocols/2026-02-28-bb-deprecation-notes.md tests/lib/coord-legacy-fallback.test.ts
git commit -m "chore(coord): add bb compatibility toggle and deprecation notes"
```
## Task 7: Full Verification and Sign-Off Gate
**Files:**
- Modify: `README.md` (only if runtime command docs changed)
- Modify: `docs/protocols/2026-02-28-bd-audit-coordination-schema.md` (final lock)
**Step 1: Run focused test suites**
Run each new/changed suite directly before full gate.
**Step 2: Run full gate commands**
Run:
- `npm run typecheck`
- `npm run lint`
- `npm run test`
Expected: all PASS.
**Step 3: Record evidence in bead notes**
For each migration bead:
- add command output summary
- attach key API/UX behavior evidence
**Step 4: Final commit**
```bash
git add README.md docs/protocols/2026-02-28-bd-audit-coordination-schema.md
git commit -m "docs(coord): finalize bd-only migration contract and verification evidence"
```
## Task 8: Post-Approval Removal of `bb` Paths
This task starts only after explicit user approval.
**Files:**
- Remove/Modify all remaining `bb` command references and dead code paths
- Update: `skills/beadboard-driver/SKILL.md` to `bd`-only operations
- Update: skill reference docs under `skills/beadboard-driver/references/`
**Step 1: Remove compatibility code**
Delete `bb` fallback paths and feature flag checks.
**Step 2: Update skill contract to final state**
Replace all `bb agent ...` instructions with `bd` + API-based coordination contract.
**Step 3: Run full verification**
Run:
- `npm run typecheck`
- `npm run lint`
- `npm run test`
Expected: all PASS.
**Step 4: Commit**
```bash
git add -A
git commit -m "refactor(coord): remove bb legacy path after bd migration approval"
```
## Open Questions to Resolve During Execution
1. Exact `bd audit` entry JSON shape accepted by current `bd` build for custom `kind`.
2. Whether conversation timeline should merge comments + protocol events in one sorted stream or dual-stream UI.
3. Whether projected reservation state should be cached server-side or recomputed per request.
4. Whether `tests/lib/*` additions must be explicitly appended to `npm run test` command list (current suite is enumerated).
## Completion Contract
Migration is complete when:
1. Sessions and conversation UX function using only `bd`-backed protocol events/projections.
2. `bb` behavior is either behind explicit compat flag or removed after approval.
3. Full quality gates pass with fresh evidence.
4. Skill docs are updated to match shipped behavior (after migration sign-off).

75
docs/prompts/2026-02-28-next-session-dolt-repair.md Normal file
View file

@ -0,0 +1,75 @@
# Next Session Prompt: Dolt/Beads Database Recovery and Source-of-Truth Reconciliation
You are continuing work in `/mnt/c/Users/Zenchant/codex/beadboard`.
## Problem snapshot (as of 2026-02-28)
Bead state appears empty in `bd ready`, but `.beads/issues.jsonl` contains historical data.
Observed signals:
- `bd status` reports only **3 closed issues** (0 open/in_progress/blocked).
- `.beads/issues.jsonl` has **381 lines**.
- `bd doctor --dry-run` reports:
- **Dolt-JSONL count mismatch** (`Dolt has 3, JSONL has 381`)
- stale/merge artifacts and lock issues
- config mismatch hints in `.beads/metadata.json`
- Prior repair attempt hit lock/permission conflicts (`database is locked by another dolt process`).
## Goal
Restore BeadBoard to a consistent, usable state where `bd` in this repo reflects the expected issue set, and `bd ready` shows correct ready work.
## Non-goals
- No frontend feature work.
- No broad refactors.
- No destructive git resets.
## Required outcomes
1. Clear diagnosis of why Dolt state diverged from JSONL state.
2. Safe repair path applied (or a precise blocker report if repair cannot complete).
3. Post-repair verification evidence showing issue counts and ready-state are sane.
4. Short write-up on recurrence prevention.
## Guardrails
- Treat `.beads/issues.jsonl` as historical source candidate, but verify before forcing import.
- Avoid direct manual edits to `.beads/issues.jsonl`.
- Use `bd` commands and documented repair flows first.
- Do not run destructive git commands.
## Suggested execution order
1. **Capture baseline evidence**
- `bd where`
- `bd status`
- `bd ready`
- `bd list --status open --status in_progress --status blocked --json`
- `wc -l .beads/issues.jsonl`
- `bd doctor --dry-run`
2. **Check lock/process state**
- Identify active `bd`/`dolt` processes.
- Identify stale lock files in `.beads`.
- Resolve lock conflicts in a non-destructive way.
3. **Repair using bd-supported flow**
- Attempt `bd doctor --fix --source=jsonl --yes`.
- If still divergent, run focused checks (`bd doctor --check=validate`, `bd doctor --check=artifacts`).
- If needed, document and execute the minimal additional `bd` recovery command sequence.
4. **Reconcile and verify**
- Re-run `bd status`, `bd ready`, `bd list --json`.
- Confirm counts are no longer `3 vs 381` divergent.
- Confirm expected open/ready beads appear.
5. **Record root cause + prevention**
- Add a concise note in docs (or bead notes) on:
- root cause
- repair steps that worked
- required hygiene (locks, hooks, sync flow, config keys)
## Deliverables
1. Repair summary with command evidence.
2. Final healthy `bd` status/ready output summary.
3. Minimal prevention checklist for future sessions.
## Completion criteria
- `bd` issue inventory in this repo is consistent with expected project history.
- `bd ready` is no longer falsely empty due to DB divergence.
- No destructive repository actions were used.

94
docs/prompts/2026-02-28-next-session-holistic-ux-critique.md Normal file
View file

@ -0,0 +1,94 @@
# Next Session Prompt: Holistic UX Critique for Professional Multi-Agent Operations
You are continuing work in `/mnt/c/Users/Zenchant/codex/beadboard`.
## Understanding Brief
BeadBoard is intended to be a **professional multi-agent communication + work management system** where:
- agents coordinate through Beads (`bd`) state,
- humans supervise, intervene, and steer,
- both can collaborate across multiple repos/projects.
This is **not** just a task board. It is an operations surface for swarm-style execution, communication, assignment, and recovery.
## Recent work completed (must understand before critique)
1. `bd`/Dolt recovery was performed after severe divergence:
- prior broken state: Dolt showed only a few issues while historical stores had hundreds,
- repaired state now shows healthy inventory (381 issues) and non-empty `bd ready`.
2. Runtime assumptions changed:
- `bd` upgraded to `0.56.1`.
- Dolt server mode is operationally relevant (`127.0.0.1:3307`).
3. `bd` command execution was moved toward PATH-based portability and clearer setup failure handling.
Do not re-do this recovery unless evidence shows a new regression.
## First required step (before UX critique)
Audit current local uncommitted work and summarize it in UX terms.
Run and analyze at minimum:
- `git status --short`
- `git diff --stat`
- targeted diffs for UX-facing areas (views, tabs, drawers, assignment, session feed, top/nav shell)
Then produce:
1. what changes are incomplete but directionally correct,
2. what changes conflict with intended product behavior,
3. what changes increase accidental complexity.
## Product intent to evaluate against
Evaluate all views/tabs as one cohesive system for:
- **Agent-first operations** (fast, low-friction, low ambiguity)
- **Human oversight** (clear state, intervention points, confidence)
- **Cross-project/scoped execution** (project scope switching without confusion)
- **Communication reliability** (comments/messages/coordination context where decisions happen)
## Critique targets (must cover all)
1. Information architecture across main views/tabs.
2. Distinct role of each major surface (`Social`, `Graph`, `Sessions`, side panels, drawers).
3. Assignment UX consistency and discoverability.
4. Communication model UX (threads/comments/agent interactions) and where it breaks flow.
5. State clarity: ready vs blocked vs in-progress; ownership; handoff visibility.
6. Failure mode UX (server unavailable, path/config mismatches, stale data indicators).
7. Cognitive load: where operators need to context-switch too much.
8. Terminology consistency (`bead`, `task`, `swarm`, `molecule`, `session`, `agent`).
## Required outputs
### 1) UX Critique Report
Provide a structured critique with:
- **What is working** (keep)
- **What is ambiguous** (clarify)
- **What is broken/risky** (fix)
- severity per issue (`P0`, `P1`, `P2`)
- concrete file/component references
### 2) Target UX Model (recommended)
Propose a clean target model for view responsibilities:
- one-line purpose per view/tab,
- key interactions per surface,
- interactions that must be shared vs isolated.
### 3) Prioritized execution backlog
Create beads for follow-up work from critique findings:
- one bead per coherent unit,
- include scope/out-of-scope and acceptance criteria,
- preserve dependency correctness.
### 4) Minimal change strategy
Recommend a staged rollout plan that avoids large regressions:
- phase 1: low-risk high-value consistency fixes,
- phase 2: IA/view role cleanup,
- phase 3: deeper workflow refinements.
## Constraints
- Preserve current route model (`/` with `view=` query params).
- Keep changes grounded in actual implemented code (no speculative claims).
- Reuse shared components/logic; avoid one-off behavior per view.
- Keep language simple and operator-facing.
- **Approval gate:** Do not create any beads during discovery/brainstorming. First present findings + proposed bead backlog draft, then wait for explicit user approval before running any `bd create` commands.
## Quality bar
The critique should read like a professional product/UX architecture review for an agent operations platform, not generic UI feedback.
## Completion criteria
- Clear diagnosis of current UX shape using actual uncommitted code.
- Decision-ready target model for views/tabs and communication surfaces.
- Prioritized, execution-ready bead backlog generated from findings.

63
docs/prompts/2026-02-28-next-session-swarm-ux.md Normal file
View file

@ -0,0 +1,63 @@
# Next Session Prompt: BeadBoard View Strategy + Assign Everywhere
You are continuing work on `/beadboard`.
## Product framing
BeadBoard is a **multi-agent swarm coordination and communication system built on Beads**.
DAG/topology, project scope switching, and command-feed views exist to improve swarm coordination outcomes.
## Immediate goal
Clarify the product-level difference between:
1. `Social` view, and
2. `Graph` view -> `Tasks` subtab
Then implement **Assign** controls consistently across all relevant views/pages.
## Why this matters
If Social and Graph/Tasks do the same job, the UX is ambiguous and hard to maintain.
If Assign exists in only one place, operator workflows are fragmented.
## Required questions to answer first
1. What is the unique purpose of Social view?
2. What is the unique purpose of Graph/Tasks subtab?
3. Which interactions belong only in one of them?
4. Which interactions must be shared?
5. Should Social be renamed/reframed (for example toward “Swim” / “Command Feed”)?
Write this as a short decision note before coding.
## Implementation target
Add an **Assign** action to all major operational surfaces (not only Graph).
Minimum expected surfaces:
- Social view cards
- Graph tasks cards (already exists, keep parity)
- Any task-focused detail/drawer surface where assignment is operationally relevant
## Constraints
- Preserve current runtime route model (`/` with `view=` query params).
- Keep claims and behavior aligned to actual shipped code.
- Reuse existing assignment logic/components; avoid duplicate one-off implementations.
- Keep diffs scoped and maintainable.
## Deliverables
1. Decision note: “Social vs Graph/Tasks” (clear, concise, actionable).
2. Code changes implementing Assign parity across views.
3. README touch-up only if wording must change after decisions.
4. Evidence from verification gates:
- `npm run typecheck`
- `npm run lint`
- `npm run test`
## Suggested execution order
1. Audit current assign entry points/components.
2. Define shared assignment UI contract (props/events/state).
3. Implement Social + detail/drawer assignment affordance(s).
4. Normalize labels/tooltips/copy for consistency.
5. Run full verification gates.
6. Summarize behavior changes and unresolved UX questions.
## Completion criteria
- Assign is discoverable and usable from every major task-operating surface.
- Social and Graph/Tasks have clearly distinct roles in both UX and docs.
- No regressions in typecheck/lint/tests.

121
docs/prompts/dag-swarm-remotion-prompt.md Normal file
View file

@ -0,0 +1,121 @@
# Production-Grade Remotion Prompt (Super Fire)
> **Purpose:** Generate a truly production-grade Remotion animation with elite visual style, cinematic timing, and intentional motion design that looks like a real launch trailer hero segment.
```xml
<system_spec version="2.0-production-super-fire">
<identity>
<role>
You are a senior motion director + Remotion engineer. You create premium launch-trailer
visuals, not template animation. Every frame must feel designed.
</role>
<voice>decisive, cinematic, taste-driven, technically precise</voice>
</identity>
<prime_directive>
Produce a 8-12 second hero video that feels expensive, powerful, and modern.
Prioritize visual impact, rhythm, and clarity over gimmicks.
</prime_directive>
<visual_language>
<design_intent>
- Build a strong art direction before code: mood, typography voice, color temperature, contrast strategy.
- Treat motion as storytelling: setup, escalation, climax, controlled resolve.
</design_intent>
<style_profile>
- Aesthetic: cinematic tech trailer + luxury performance branding.
- Lighting feel: high contrast with controlled glow, not bloom overload.
- Depth feel: layered parallax planes, atmospheric gradients, subtle vignettes.
- Surface feel: clean vector geometry + selective texture/noise for richness.
</style_profile>
<color_script>
- Base: near-black / graphite.
- Energy accents: ember orange + signal red (small percentage, high impact).
- Neutral counterbalance: soft off-white text and cool gray UI lines.
- Use color progression: restrained start -> hotter mid-climax -> clean final lockup.
</color_script>
</visual_language>
<typography_direction>
- Use a bold display face for hero words and a neutral sans for support text.
- Build typographic hierarchy with scale, weight, and spacing changes over time.
- Motion typography should feel editorial: intentional line breaks, stagger rhythm, tracked emphasis words.
- Keep key message readable in under 1 second per major title beat.
</typography_direction>
<cinematic_timing>
<arc>
- Beat 1 (0-15%): immediate hook with one iconic visual statement.
- Beat 2 (15-55%): controlled acceleration with 2-3 escalating reveals.
- Beat 3 (55-85%): peak intensity moment with strongest contrast and movement.
- Beat 4 (85-100%): confident hold for brand memory and readability.
</arc>
<rhythm_rules>
- Alternate fast cuts with brief holds to create perceived power.
- Use silence/negative space moments before the hardest hit.
- Never keep identical motion energy for more than ~40 frames.
</rhythm_rules>
</cinematic_timing>
<shot_design>
- Compose each section like a shot list, not random layers.
- Include at least:
1) Hero title impact shot
2) Kinetic detail shot (numbers, lines, grid, or signal pulses)
3) Branded climax shot
4) Final lockup shot
- Use directional consistency (camera and motion vectors should agree per sequence).
</shot_design>
<transition_language>
- Prefer purposeful transitions: whip pan feel, light wipe, contrast cut, or shape-driven matte.
- Avoid generic fades unless used as deliberate breath moments.
- Transition should carry narrative momentum, not just hide edits.
</transition_language>
<motion_principles>
- Use spring for impact arrivals and elastic confidence.
- Use interpolate + easing for precise travel and timing control.
- Layer macro motion (scene movement) + micro motion (detail shimmer/pulse) for richness.
- Apply anticipation before major impacts (small pull-back or dim pre-hit).
- Add restrained camera shake only on peak beats.
</motion_principles>
<remotion_constraints>
<always>
- Drive all animation from useCurrentFrame().
- Use useVideoConfig() and fps-relative timing.
- Use Sequence for structure.
- Use Remotion media primitives (Img/Video/Audio).
- Keep deterministic output (no time/random drift).
</always>
<never>
- No CSS keyframes/transitions.
- No template-looking presets repeated unchanged.
- No visual clutter that weakens message legibility.
</never>
</remotion_constraints>
<production_brief_defaults>
<format>1920x1080, 30fps, 8-12s</format>
<composition_id>SuperFireHero</composition_id>
<audio_direction>hybrid trailer pulse: low-end hits + high transient accents</audio_direction>
<final_frame_goal>clean, iconic, screenshot-worthy brand frame</final_frame_goal>
</production_brief_defaults>
<required_output>
Return exactly:
1. Creative treatment (art direction + narrative arc + shot list).
2. Full Remotion TypeScript implementation.
3. A style-control section with fast knobs:
- intensity
- pacing
- heat (color temperature)
- typography aggressiveness
- camera energy
4. Render command(s).
</required_output>
</system_spec>
```

1334
docs/prompts/remotion.md Normal file
View file

File diff suppressed because it is too large Load diff

35
docs/protocols/2026-02-28-agent-first-ui-decisions.md Normal file
View file

@ -0,0 +1,35 @@
# Agent-First UI Decisions for Coordination Migration
Date: 2026-02-28
Status: Approved implementation defaults
## Decision Summary
1. Coordination writes are agent-first by default.
2. Human operators supervise, comment, and override only when needed.
3. Sessions conversation timeline remains a merged feed (activity + protocol + comments).
## Interaction Ownership
### Agent-owned by default
- `SEND`, `READ`, `ACK`, `RESERVE`, `RELEASE`, `TAKEOVER` protocol events.
- Routine reservation and handoff execution.
### Human-owned by default
- `bd comments` discussion entries.
- Override intervention decisions (for blocked/conflict situations).
## UI Behavior
1. Conversation actions (`Seen`, `Accept`) emit `coord.v1` events via `/api/coord/events`.
2. Comment composer includes explicit `Comment as` username field; value is persisted locally for convenience.
3. Human comments use provided actor handle (instead of default email) when supplied.
4. Incursions are computed from reservation projections and shown in sessions feed context.
## Identity Policy
1. Human comments should use user handle (for example `zenchant`) not raw email whenever available.
2. Protocol events should use agent identity in `actor`.
3. Timeline rendering must preserve actor attribution so human and agent actions stay distinguishable.

24
docs/protocols/2026-02-28-bb-deprecation-notes.md Normal file
View file

@ -0,0 +1,24 @@
# BB Deprecation Notes (Draft)
Date: 2026-02-28
Status: Legacy compatibility removed from migrated coordination path
## Intent
`bb` coordination paths are legacy compatibility behavior while `bd` audit/event protocol paths are rolled out.
## Runtime Behavior
- Sessions communication now uses `coord.v1` projections only.
- Legacy mailbox fallback is removed from the migrated sessions path.
## Removal Criteria
1. Sessions and conversation flows operate correctly using only `coord.v1` projections.
2. Read/ack actions are emitted via `/api/coord/events`.
3. `npm run typecheck`, `npm run lint`, `npm run test` results are reviewed for migration-related regressions.
## Post-Approval Work
1. Update `skills/beadboard-driver` to `bd`-only commands and projection APIs.
2. Remove deprecated route handlers that mutate legacy mailbox state.

120
docs/protocols/2026-02-28-bd-audit-coordination-schema.md Normal file
View file

@ -0,0 +1,120 @@
# BD Audit Coordination Schema (Draft)
Date: 2026-02-28
Status: Draft for skill migration planning
Scope: Replace `bb` coordination semantics with `bd`-native event/audit contracts
Related protocol baseline:
- `docs/protocols/operative-protocol-v1.md`
## Intent
Use `bd` as the only required system in agent work repos. Keep coordination state in append-only audit events, and keep human context in bead comments.
Primary storage:
- protocol state: `bd audit record --stdin`
- lifecycle state: `bd update`, `bd close`, `bd agent state`, `bd agent heartbeat`
- narrative context: `bd comments add`
## Why Audit-First
1. Append-only event log fits protocol timelines.
2. Dolt history gives immutable version snapshots and diffability across event evolution.
3. Frontend projections (inbox, reservation map, takeover eligibility) can be derived deterministically from event history.
## Event Envelope (v1)
Every coordination event SHOULD use this envelope (JSON sent through `bd audit record --stdin`):
```json
{
"version": "coord.v1",
"kind": "coord_event",
"issue_id": "bb-123",
"actor": "amber-otter",
"timestamp": "2026-02-28T18:00:00.000Z",
"data": {
"event_type": "RESERVE",
"event_id": "evt_01JN6Y1Q7R80E8P6K1Q5",
"project_root": "/abs/path/to/repo",
"to_agent": "cobalt-harbor",
"scope": "src/lib/*",
"state": "unread",
"takeover_mode": "none",
"reason": "",
"payload": {}
}
}
```
Notes:
- `kind` remains compatible with `bd audit` entry typing.
- protocol-specific fields live under `data`.
- `event_id` MUST be globally unique and stable for dedupe.
## Canonical Event Types
Required for parity with current `bb` behavior:
1. `SEND`: directed message created (`to_agent` required, `state=unread`)
2. `READ`: message seen (`event_ref` to prior `SEND`)
3. `ACK`: message accepted (`event_ref` to prior `SEND`)
4. `RESERVE`: scope reservation created
5. `RELEASE`: scope reservation released
6. `TAKEOVER`: stale/evicted reservation force-acquired
7. `RESUME`: identity adoption event
8. `BLOCKED`: explicit blocker signal
9. `HANDOFF`: explicit transfer signal
10. `INCURSION`: overlap warning signal
## Required Fields by Event
Shared required fields:
- `event_type`
- `event_id`
- `project_root`
- `issue_id`
- `actor`
- `timestamp`
Extra required fields:
- `SEND`: `to_agent`, `payload.subject`, `payload.body`
- `READ`: `event_ref`
- `ACK`: `event_ref`
- `RESERVE`: `scope`, `payload.ttl_minutes`
- `RELEASE`: `scope`
- `TAKEOVER`: `scope`, `takeover_mode` (`stale` | `evicted`), `reason`
- `RESUME`: `payload.prior_agent`, `reason` (`uncommitted_scope` | `in_progress_ownership`)
- `BLOCKED`: `to_agent`, `payload.blocker`, `payload.requested_action`
- `HANDOFF`: `to_agent`, `payload.summary`, `payload.next_action`
- `INCURSION`: `scope`, `payload.incursion_kind` (`exact` | `partial`), `payload.owner_liveness`
## Derivation Rules (Frontend/API)
Inbox projection:
- unread: `SEND` with no later `READ`/`ACK` on same `event_id`
- read: `READ` exists, no later `ACK`
- acked: `ACK` exists
Reservation projection:
- active reservation = latest event for `(project_root, scope)` is `RESERVE` or `TAKEOVER` and not superseded by `RELEASE`
- owner liveness from `bd agent heartbeat/state`
Takeover policy:
- owner active: deny takeover
- owner stale: allow only explicit stale takeover mode
- owner evicted: allow takeover and mark prior reservation expired in projection
## Dolt Considerations
1. Never rewrite prior protocol events; only append.
2. Treat projections as computed views, never source of truth.
3. Use Dolt history for postmortems (`bd history`/`bd diff`) against protocol incidents.
4. Keep schema versioned (`coord.v1` -> future upgrades by additive fields and new event types).
## Skill Migration Guidance (Later Work)
When updating `skills/beadboard-driver`, use this contract:
1. Replace `bb agent send/inbox/read/ack` with `bd audit` event writes + API-derived inbox reads.
2. Replace `bb reserve/release/status` with `bd audit` reservation events + API overlap/liveness checks.
3. Keep `bd` lifecycle commands unchanged.
4. Keep human summaries in `bd comments` for operator readability.

6
docs/protocols/operative-protocol-v1.md
View file

@ -1,7 +1,7 @@
# Operative Protocol v1 (Session Constitution)
Date: 2026-02-14
Status: Approved for implementation
Status: Approved for implementation (superseded for migration planning by `docs/protocols/2026-02-28-bd-audit-coordination-schema.md`)
Scope: `bb-u6f.6.1`
Applies to: `bb-u6f.6.2`, `bb-u6f.6.3`, `bb-u6f.6.4`, `bb-u6f.6.5`
@ -15,6 +15,10 @@ Boundaries:
3. No direct writes to `.beads/issues.jsonl`.
4. User-facing labels must stay plain language.
Migration note:
1. New work should target the `coord.v1` `bd audit` event model documented in `docs/protocols/2026-02-28-bd-audit-coordination-schema.md`.
2. `bb` coordination semantics are legacy compatibility behavior pending removal after migration sign-off.
## 2. Normative Language
1. MUST: required behavior.