viktor/beadboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
beadboard/skills/beadboard-driver/references/failure-modes.md

78 lines
3.5 KiB
Markdown
Raw Normal View History

feat(skills): formalize agent coordination via beadboard-driver We moved from ad-hoc task claims to a strictly defined 'Skill' system. Triumphs: - Implemented the 'beadboard-driver' skill, which encodes our project-specific coordination protocols (claim, reservation, handoff). - This ensures that any AI operative (or human supervisor) can participate in the project lifecycle using a unified CLI-driven state machine. - Decoupled high-level mission logic from low-level file mutations, allowing for easier agent skill composition in the future. Raw Honest Moment: Initially, we were just 'winging it' with manual status updates. Formalizing this into a skill was a necessary step to ensure our collaboration is repeatable and resilient to agent context swaps.
2026-02-14 00:23:41 -08:00
# Failure Modes
docs(skill): refresh command matrix and failure modes
2026-03-03 19:08:58 -08:00
This document tracks high-impact coordination and environment failures for the BeadBoard driver skill.
feat(skills): formalize agent coordination via beadboard-driver We moved from ad-hoc task claims to a strictly defined 'Skill' system. Triumphs: - Implemented the 'beadboard-driver' skill, which encodes our project-specific coordination protocols (claim, reservation, handoff). - This ensures that any AI operative (or human supervisor) can participate in the project lifecycle using a unified CLI-driven state machine. - Decoupled high-level mission logic from low-level file mutations, allowing for easier agent skill composition in the future. Raw Honest Moment: Initially, we were just 'winging it' with manual status updates. Formalizing this into a skill was a necessary step to ensure our collaboration is repeatable and resilient to agent context swaps.
2026-02-14 00:23:41 -08:00
## `BD_NOT_FOUND`
docs(skill): refresh command matrix and failure modes
2026-03-03 19:08:58 -08:00
- Signal: preflight or scripts fail with `BD_NOT_FOUND`.
- Cause: `bd` is not installed or not on `PATH`.
- Recovery:
- Install beads CLI.
- Re-open shell so `PATH` updates apply.
- Re-run `node skills/beadboard-driver/scripts/session-preflight.mjs`.
feat(skills): formalize agent coordination via beadboard-driver We moved from ad-hoc task claims to a strictly defined 'Skill' system. Triumphs: - Implemented the 'beadboard-driver' skill, which encodes our project-specific coordination protocols (claim, reservation, handoff). - This ensures that any AI operative (or human supervisor) can participate in the project lifecycle using a unified CLI-driven state machine. - Decoupled high-level mission logic from low-level file mutations, allowing for easier agent skill composition in the future. Raw Honest Moment: Initially, we were just 'winging it' with manual status updates. Formalizing this into a skill was a necessary step to ensure our collaboration is repeatable and resilient to agent context swaps.
2026-02-14 00:23:41 -08:00
## `BB_NOT_FOUND`
refactor: extract agent bounded context + fix SSE comments + cleanup unused - Extract src/lib/agent/ bounded context with types, registry, messaging - Add comments_count to BeadIssue for SSE comment detection - Create batch endpoints for mail/reservations APIs - Add memory validation to session-preflight - Remove unused empty dirs (mockup, sessions, timeline) - Move stashes to docs/references, gitignore them
2026-03-04 22:06:40 -08:00
- Signal: `session-preflight.mjs` or `bb-mail-shim.mjs` reports bb command missing.
docs(skill): refresh command matrix and failure modes
2026-03-03 19:08:58 -08:00
- Cause: global BeadBoard CLI not installed, or not discoverable.
- Recovery:
refactor: extract agent bounded context + fix SSE comments + cleanup unused - Extract src/lib/agent/ bounded context with types, registry, messaging - Add comments_count to BeadIssue for SSE comment detection - Create batch endpoints for mail/reservations APIs - Add memory validation to session-preflight - Remove unused empty dirs (mockup, sessions, timeline) - Move stashes to docs/references, gitignore them
2026-03-04 22:06:40 -08:00
- Install BeadBoard globally (`bb`/`beadboard` on `PATH`) — see Bootstrap Step C in SKILL.md.
- Run `node {baseDir}/scripts/setup-mail-delegate.mjs` to reconfigure the mail delegate after `bb` is installed.
- Re-run preflight: `node {baseDir}/scripts/session-preflight.mjs`.
docs(skill): refresh command matrix and failure modes
2026-03-03 19:08:58 -08:00
## `MAIL_DELEGATE_MISSING` / `BD_MAIL_DELEGATE_NOT_SET`
- Signal: `bd mail ...` returns delegate-not-configured or shim not invoked.
- Cause: neither env delegate (`BEADS_MAIL_DELEGATE`/`BD_MAIL_DELEGATE`) nor `mail.delegate` config is set.
- Recovery:
- `bd config set mail.delegate "node <abs-path>/skills/beadboard-driver/scripts/bb-mail-shim.mjs"`
- `export BB_AGENT=<agent-id>`
- `node skills/beadboard-driver/scripts/ensure-bb-mail-configured.mjs`
## `BB_MAIL_NOT_CONFIGURED`
- Signal: `ensure-bb-mail-configured.mjs` fails contract checks.
- Cause: delegate points to wrong command, missing shim path, or invalid `BB_AGENT` context.
refactor: extract agent bounded context + fix SSE comments + cleanup unused - Extract src/lib/agent/ bounded context with types, registry, messaging - Add comments_count to BeadIssue for SSE comment detection - Create batch endpoints for mail/reservations APIs - Add memory validation to session-preflight - Remove unused empty dirs (mockup, sessions, timeline) - Move stashes to docs/references, gitignore them
2026-03-04 22:06:40 -08:00
- Recovery (in order):
1. Check delegate is set: `bd config get mail.delegate`
2. Verify shim path: the path shown must be absolute and the `bb-mail-shim.mjs` file must exist on disk
3. Reconfigure if wrong/missing: `node {baseDir}/scripts/setup-mail-delegate.mjs`
4. Verify `BB_AGENT` is set: `echo $BB_AGENT` (must be non-empty)
5. Re-run verification: `node {baseDir}/scripts/ensure-bb-mail-configured.mjs` — expected: `ok: true`
feat(skills): formalize agent coordination via beadboard-driver We moved from ad-hoc task claims to a strictly defined 'Skill' system. Triumphs: - Implemented the 'beadboard-driver' skill, which encodes our project-specific coordination protocols (claim, reservation, handoff). - This ensures that any AI operative (or human supervisor) can participate in the project lifecycle using a unified CLI-driven state machine. - Decoupled high-level mission logic from low-level file mutations, allowing for easier agent skill composition in the future. Raw Honest Moment: Initially, we were just 'winging it' with manual status updates. Formalizing this into a skill was a necessary step to ensure our collaboration is repeatable and resilient to agent context swaps.
2026-02-14 00:23:41 -08:00
docs(skill): refresh command matrix and failure modes
2026-03-03 19:08:58 -08:00
## `DOLT_NOT_RUNNING`
feat(skills): formalize agent coordination via beadboard-driver We moved from ad-hoc task claims to a strictly defined 'Skill' system. Triumphs: - Implemented the 'beadboard-driver' skill, which encodes our project-specific coordination protocols (claim, reservation, handoff). - This ensures that any AI operative (or human supervisor) can participate in the project lifecycle using a unified CLI-driven state machine. - Decoupled high-level mission logic from low-level file mutations, allowing for easier agent skill composition in the future. Raw Honest Moment: Initially, we were just 'winging it' with manual status updates. Formalizing this into a skill was a necessary step to ensure our collaboration is repeatable and resilient to agent context swaps.
2026-02-14 00:23:41 -08:00
docs(skill): refresh command matrix and failure modes
2026-03-03 19:08:58 -08:00
- Signal: `bd` reads stale/fallback data, API routes return Dolt connection failures, or status checks report backend unavailable.
- Cause: Dolt SQL server not started for this workspace.
feat(skills): formalize agent coordination via beadboard-driver We moved from ad-hoc task claims to a strictly defined 'Skill' system. Triumphs: - Implemented the 'beadboard-driver' skill, which encodes our project-specific coordination protocols (claim, reservation, handoff). - This ensures that any AI operative (or human supervisor) can participate in the project lifecycle using a unified CLI-driven state machine. - Decoupled high-level mission logic from low-level file mutations, allowing for easier agent skill composition in the future. Raw Honest Moment: Initially, we were just 'winging it' with manual status updates. Formalizing this into a skill was a necessary step to ensure our collaboration is repeatable and resilient to agent context swaps.
2026-02-14 00:23:41 -08:00
- Recovery:
docs(skill): refresh command matrix and failure modes
2026-03-03 19:08:58 -08:00
- From repo root: `bd dolt start`
- Verify backend health before proceeding (`beadboard status --json` or project-specific health checks).
feat(skills): formalize agent coordination via beadboard-driver We moved from ad-hoc task claims to a strictly defined 'Skill' system. Triumphs: - Implemented the 'beadboard-driver' skill, which encodes our project-specific coordination protocols (claim, reservation, handoff). - This ensures that any AI operative (or human supervisor) can participate in the project lifecycle using a unified CLI-driven state machine. - Decoupled high-level mission logic from low-level file mutations, allowing for easier agent skill composition in the future. Raw Honest Moment: Initially, we were just 'winging it' with manual status updates. Formalizing this into a skill was a necessary step to ensure our collaboration is repeatable and resilient to agent context swaps.
2026-02-14 00:23:41 -08:00
docs(skill): refresh command matrix and failure modes
2026-03-03 19:08:58 -08:00
## `AGENT_HEARTBEAT_MISSED` (Witness liveness degradation)
feat(skills): formalize agent coordination via beadboard-driver We moved from ad-hoc task claims to a strictly defined 'Skill' system. Triumphs: - Implemented the 'beadboard-driver' skill, which encodes our project-specific coordination protocols (claim, reservation, handoff). - This ensures that any AI operative (or human supervisor) can participate in the project lifecycle using a unified CLI-driven state machine. - Decoupled high-level mission logic from low-level file mutations, allowing for easier agent skill composition in the future. Raw Honest Moment: Initially, we were just 'winging it' with manual status updates. Formalizing this into a skill was a necessary step to ensure our collaboration is repeatable and resilient to agent context swaps.
2026-02-14 00:23:41 -08:00
docs(skill): refresh command matrix and failure modes
2026-03-03 19:08:58 -08:00
- Signal: agent appears stale/dead in liveness surfaces after inactivity window.
- Cause: agent is not sending `bd agent heartbeat <agent-bead-id>` during active work.
- Recovery:
- Resume periodic heartbeat (typically every 30-120 seconds while active).
- Set explicit state transitions: `running` -> `working` -> `stuck|done|stopped`.
- If work was interrupted, post a coordination note/message before resuming.
feat(skills): formalize agent coordination via beadboard-driver We moved from ad-hoc task claims to a strictly defined 'Skill' system. Triumphs: - Implemented the 'beadboard-driver' skill, which encodes our project-specific coordination protocols (claim, reservation, handoff). - This ensures that any AI operative (or human supervisor) can participate in the project lifecycle using a unified CLI-driven state machine. - Decoupled high-level mission logic from low-level file mutations, allowing for easier agent skill composition in the future. Raw Honest Moment: Initially, we were just 'winging it' with manual status updates. Formalizing this into a skill was a necessary step to ensure our collaboration is repeatable and resilient to agent context swaps.
2026-02-14 00:23:41 -08:00
## Mail Lifecycle Errors
docs(skill): refresh command matrix and failure modes
2026-03-03 19:08:58 -08:00
- `UNKNOWN_SENDER` / `UNKNOWN_RECIPIENT`: register agent identities before sending.
- `MESSAGE_NOT_FOUND`: incorrect message id or wrong inbox context.
- `ACK_FORBIDDEN`: only the message recipient can acknowledge.
feat(skills): formalize agent coordination via beadboard-driver We moved from ad-hoc task claims to a strictly defined 'Skill' system. Triumphs: - Implemented the 'beadboard-driver' skill, which encodes our project-specific coordination protocols (claim, reservation, handoff). - This ensures that any AI operative (or human supervisor) can participate in the project lifecycle using a unified CLI-driven state machine. - Decoupled high-level mission logic from low-level file mutations, allowing for easier agent skill composition in the future. Raw Honest Moment: Initially, we were just 'winging it' with manual status updates. Formalizing this into a skill was a necessary step to ensure our collaboration is repeatable and resilient to agent context swaps.
2026-02-14 00:23:41 -08:00
docs(skill): refresh command matrix and failure modes
2026-03-03 19:08:58 -08:00
## Local Workspace Repair Signals
feat(skills): formalize agent coordination via beadboard-driver We moved from ad-hoc task claims to a strictly defined 'Skill' system. Triumphs: - Implemented the 'beadboard-driver' skill, which encodes our project-specific coordination protocols (claim, reservation, handoff). - This ensures that any AI operative (or human supervisor) can participate in the project lifecycle using a unified CLI-driven state machine. - Decoupled high-level mission logic from low-level file mutations, allowing for easier agent skill composition in the future. Raw Honest Moment: Initially, we were just 'winging it' with manual status updates. Formalizing this into a skill was a necessary step to ensure our collaboration is repeatable and resilient to agent context swaps.
2026-02-14 00:23:41 -08:00
docs(skill): refresh command matrix and failure modes
2026-03-03 19:08:58 -08:00
- `GIT_INDEX_LOCK_PRESENT`: stale git lock blocks writes.
- Recovery:
- Confirm no active git process is still using the repo.
- Run `node skills/beadboard-driver/scripts/heal-common-issues.mjs --project-root <repo> --apply --fix-git-index-lock`.
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
docs(skill): refresh command matrix and failure modes
2026-03-03 19:08:58 -08:00
## Policy Guardrails
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
docs(skill): refresh command matrix and failure modes
2026-03-03 19:08:58 -08:00
- Do not write `.beads/issues.jsonl` directly.
- Do not close beads without fresh evidence.
refactor: extract agent bounded context + fix SSE comments + cleanup unused - Extract src/lib/agent/ bounded context with types, registry, messaging - Add comments_count to BeadIssue for SSE comment detection - Create batch endpoints for mail/reservations APIs - Add memory validation to session-preflight - Remove unused empty dirs (mockup, sessions, timeline) - Move stashes to docs/references, gitignore them
2026-03-04 22:06:40 -08:00
- Do not bypass a misconfigured mail delegate; fix configuration with `{baseDir}/scripts/setup-mail-delegate.mjs` first.
Reference in a new issue Copy permalink