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.
This commit is contained in:
parent
bfe4f853f0
commit
c7c3a25457
27 changed files with 2376 additions and 137 deletions
122
docs/adr/2026-02-14-beadboard-driver-skill-and-bb-resolution.md
Normal file
122
docs/adr/2026-02-14-beadboard-driver-skill-and-bb-resolution.md
Normal file
|
|
@ -0,0 +1,122 @@
|
|||
# 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.
|
||||
|
||||
2. 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`.
|
||||
|
||||
3. 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`.
|
||||
|
||||
4. 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`
|
||||
Loading…
Add table
Add a link
Reference in a new issue