viktor/beadboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
beadboard/docs/adr/2026-02-14-beadboard-driver-skill-and-bb-resolution.md
zenchantlive c7c3a25457 docs(beads): etch project history into memory bank and finalize skill-bb 
We completed the 'Deep Metadata Etch' today, transforming our Beads issues from simple trackers into a permanent narrative of our collaboration.

Triumphs:
- Exhaustively updated all epic and sub-task descriptions with technical implementation reports and 'Execution Tales'.
- Finalized the 'bb' agent CLI skill (bb.ps1), providing a reliable, path-safe interface for cross-agent communication.
- Published ADR-001 and RFC-001 to document our coordination protocols.
- Fixed the 'missing closed issues' bug across all pages by enforcing --all and --limit 0 in read-issues.ts.

Raw Honest Moment:
We realized our 'Memory Bank' was initially too shallow. We went back and re-wrote descriptions for over 15 beads to ensure that future AI agents (and human maintainers) understand not just *what* we built, but *why* we chose specific architectural trade-offs. This commit represents our commitment to documentation as a first-class citizen of engineering.
2026-02-14 00:21:25 -08:00

4.3 KiB
Raw Blame History

ADR: Beadboard Driver Skill and bb Resolution Model

  • Date: 2026-02-14
  • Status: Accepted
  • Scope: bb-dcv closeout (bb-dcv.8, bb-dcv.3)

Context

Agent coordination required a reusable skill that works across sessions and environments, with deterministic behavior and verification evidence. Existing constraints:

  • bd is the source of truth for task lifecycle (ready, update, close, deps).
  • bb is the coordination layer (identity, mail, reservations).
  • No direct writes to .beads/issues.jsonl.
  • Evidence before completion claims.

Operational issue discovered during verification:

  • bb.ps1 depended on current working directory and broke when called outside repo.
  • PowerShell argument forwarding through wrapper was unreliable.

Decision

We implemented a new skill package skills/beadboard-driver with a strict policy:

  1. Path resolution
  • BB_REPO is authoritative when set.
  • Resolution order: BB_REPO -> global bb -> user cache -> bounded discovery.
  • If BB_REPO is set but invalid, fail fast with remediation.
  • Never mutate shell profile or environment variables automatically.
  • Cache path only after successful verification.
  1. Identity policy
  • One unique identity per session.
  • Adjective-noun naming with collision retry.
  • Register identity before coordination commands.
  • Keep bead claim authority in bd, not bb.
  1. Verification policy
  • Dual test harness:
    • Repo-level tests under tests/skills/beadboard-driver.
    • Skill-local runner under skills/beadboard-driver/tests.
  • Skill quick validation required.
  • Full repo gates required: typecheck, lint, test.
  1. Wrapper reliability
  • Fixed bb.ps1 to use script-relative entrypoint and arg splatting so Windows invocation works from any terminal when called by path.

Implementation

New skill artifacts

  • skills/beadboard-driver/SKILL.md
  • skills/beadboard-driver/agents/openai.yaml
  • skills/beadboard-driver/scripts/lib/driver-lib.mjs
  • skills/beadboard-driver/scripts/resolve-bb.mjs
  • skills/beadboard-driver/scripts/session-preflight.mjs
  • skills/beadboard-driver/scripts/generate-agent-name.mjs
  • skills/beadboard-driver/scripts/readiness-report.mjs
  • skills/beadboard-driver/references/command-matrix.md
  • skills/beadboard-driver/references/failure-modes.md
  • skills/beadboard-driver/references/session-lifecycle.md
  • skills/beadboard-driver/tests/run-tests.mjs
  • skills/beadboard-driver/tests/*.contract.test.mjs

Repo-level test enforcement

  • tests/skills/beadboard-driver/resolve-bb.test.ts
  • tests/skills/beadboard-driver/generate-agent-name.test.ts
  • tests/skills/beadboard-driver/session-preflight.test.ts
  • tests/skills/beadboard-driver/readiness-report.test.ts
  • tests/skills/beadboard-driver/skill-local-runner.test.ts
  • package.json test script updated to include all above.

CLI wrapper fix

  • bb.ps1 updated to:
    • resolve tools/bb.ts via $MyInvocation script directory
    • forward args via @args

Type safety remediation

  • tools/bb.ts updated with explicit arg coercion helpers to satisfy strict typecheck.

Verification Evidence

Skill-specific:

  • quick_validate.py skills/beadboard-driver -> pass
  • node --import tsx --test tests/skills/beadboard-driver/*.test.ts -> pass
  • node skills/beadboard-driver/tests/run-tests.mjs -> pass

Full repo gates:

  • npm run typecheck -> pass
  • npm run lint -> pass (0 errors)
  • npm run test -> pass (full suite including new skill tests)

Windows bb execution:

  • & "C:\Users\Zenchant\codex\beadboard\bb.ps1" agent list --json -> pass
  • & "$env:BB_REPO\bb.ps1" agent list --json (with valid BB_REPO in same shell) -> pass

Consequences

Positive:

  • Agents can run a deterministic coordination workflow with explicit recovery behavior.
  • Skill behavior is testable and enforced by CI path.
  • Windows path invocation of bb is reliable by absolute or BB_REPO path.

Tradeoffs:

  • No global bb package installation is provided by this ADR; direct bb command still requires user alias/install.
  • Session/timeline UI validation remains dependent on upstream epic sequencing.

Follow-up

bb-dcv is closed. bb-u6f remains open and depends on open bb-xhm (timeline/event model).
Next required order for frontend visibility of agent sessions:

  1. complete bb-xhm
  2. implement bb-u6f