checkpoint: pre-split branch cleanup
This commit is contained in:
ZenchantLive
parent
4c2ae2e5b7
commit
b5db7a7753
276 changed files with 35912 additions and 60119 deletions
|
|
@ -1,78 +1,158 @@
|
|||
---
|
||||
name: beadboard-driver
|
||||
description: Drive BeadBoard agent workflows with strict Operative Protocol v1 compliance. Use when handling bead lifecycle work that combines bd status commands with bb agent coordination (register/adopt, activity-lease, reserve/release, send/ack), especially in multi-agent sessions requiring silent observability and collision avoidance.
|
||||
description: Complete operating manual for agents running work in external repos while humans orchestrate from BeadBoard.
|
||||
---
|
||||
|
||||
# Beadboard Driver (Operative Protocol v1)
|
||||
# BeadBoard Driver
|
||||
|
||||
## Overview
|
||||
BeadBoard is for teams that want autonomous agents without losing control of the work.
|
||||
|
||||
Use this skill to run repeatable `bd` + `bb` workflows under the **Activity Lease** (Parking Permit) model. Resolve `bb` safely, bootstrap via `bb-init`, coordinate via traceable incursions, and maintain liveness through real work.
|
||||
Most agent setups break down the same way: work happens quickly, but visibility collapses, handoffs get fuzzy, and “done” starts meaning “probably done.” This skill fixes that operating problem.
|
||||
|
||||
## Core Workflow
|
||||
With BeadBoard Driver, agents execute inside the target project repo, while humans orchestrate from BeadBoard as the control plane: assign, redirect, intervene, verify, and keep a durable coordination record.
|
||||
|
||||
BeadBoard project:
|
||||
|
||||
- GitHub: `https://github.com/zenchantlive/beadboard`
|
||||
|
||||
## What This Changes
|
||||
|
||||
- Work becomes observable, not performative.
|
||||
- Ownership stays explicit at bead level.
|
||||
- Handoffs and blockers become machine-readable events.
|
||||
- Completion claims require evidence, not confidence.
|
||||
- Multi-agent execution stays coordinated instead of chaotic.
|
||||
|
||||
## Operating Reality
|
||||
|
||||
- Agents usually run in a non-BeadBoard target repo.
|
||||
- The user controls project scope from BeadBoard UI.
|
||||
- Agents execute the current repo context they were assigned.
|
||||
- `bd` remains source of truth for task/memory state.
|
||||
|
||||
## Start Here
|
||||
|
||||
Run this quick confidence check before you start a session:
|
||||
|
||||
1. **Bootstrap & Handshake**:
|
||||
Run `bb-init` to resolve paths and identify yourself. Use `--adopt` if resuming a task with uncommitted changes.
|
||||
```bash
|
||||
node scripts/bb-init.mjs --register <agent-name> --role <role> --json
|
||||
# OR
|
||||
node scripts/bb-init.mjs --adopt <prior-agent-id> --non-interactive --json
|
||||
bd --version
|
||||
node skills/beadboard-driver/scripts/session-preflight.mjs
|
||||
node skills/beadboard-driver/scripts/resolve-bb.mjs
|
||||
```
|
||||
|
||||
2. **Claim Territory**:
|
||||
Reserve your work surface before making edits to prevent silent collisions.
|
||||
If discovery fails, install/repair from:
|
||||
|
||||
- `https://github.com/zenchantlive/beadboard`
|
||||
|
||||
## Session Runbook
|
||||
|
||||
1. Diagnose environment.
|
||||
2. Confirm preflight/discovery.
|
||||
3. Establish session identity.
|
||||
4. Read memory + ready work.
|
||||
5. Claim bead with assignee.
|
||||
6. Execute and coordinate via events.
|
||||
7. Run verification gates.
|
||||
8. Publish evidence and close.
|
||||
9. Perform memory review.
|
||||
|
||||
## Core Commands
|
||||
|
||||
```bash
|
||||
& "$env:BB_REPO\bb.ps1" agent reserve --agent <agent-id> --scope "src/lib/*" --bead <bead-id>
|
||||
bd update <bead-id> --status in_progress --claim
|
||||
# Diagnostics and discovery
|
||||
node skills/beadboard-driver/scripts/diagnose-env.mjs
|
||||
node skills/beadboard-driver/scripts/session-preflight.mjs
|
||||
node skills/beadboard-driver/scripts/resolve-bb.mjs
|
||||
|
||||
# Ensure project context exists in the target repository
|
||||
node skills/beadboard-driver/scripts/ensure-project-context.mjs --project-root <repo>
|
||||
|
||||
# Identity helper
|
||||
node skills/beadboard-driver/scripts/generate-agent-name.mjs
|
||||
|
||||
# Closeout evidence envelope
|
||||
node skills/beadboard-driver/scripts/readiness-report.mjs --checks '<json>' --artifacts '<json>'
|
||||
|
||||
# Safe self-healing (dry-run default)
|
||||
node skills/beadboard-driver/scripts/heal-common-issues.mjs --project-root <repo>
|
||||
node skills/beadboard-driver/scripts/heal-common-issues.mjs --project-root <repo> --apply --fix-git-index-lock
|
||||
```
|
||||
|
||||
3. **Physical Change -> Contextual Lookup**:
|
||||
If you encounter uncommitted changes in a file you didn't personally edit: **STOP and Query**.
|
||||
## Bead Lifecycle (Minimum Contract)
|
||||
|
||||
```bash
|
||||
& "$env:BB_REPO\bb.ps1" agent status --agent <agent-id>
|
||||
& "$env:BB_REPO\bb.ps1" agent inbox --agent <agent-id> --state unread
|
||||
# Read context
|
||||
bd show <memory-or-task-id>
|
||||
bd ready
|
||||
|
||||
# Claim explicitly
|
||||
bd update <bead-id> --status in_progress --assignee <agent-bead-id>
|
||||
|
||||
# Record evidence and close
|
||||
bd update <bead-id> --notes "<commands + outputs>"
|
||||
bd close <bead-id> --reason "<completed outcome>"
|
||||
```
|
||||
|
||||
4. **Explain Deltas**:
|
||||
Send high-fidelity signals when you hit milestones or incursions.
|
||||
## Use-The-Right-Doc Map
|
||||
|
||||
### `references/memory-system.md`
|
||||
Use when you need to query/apply/create canonical memory, validate provenance, or decide whether a lesson belongs in memory vs task notes.
|
||||
|
||||
### `references/coord-events-sessions-ack.md`
|
||||
Use when you’re coordinating handoffs/blockers/incursions and need correct inbox/read/ack behavior.
|
||||
|
||||
### `references/session-lifecycle.md`
|
||||
Use for end-to-end session choreography and closeout hygiene.
|
||||
|
||||
### `references/archetypes-templates-swarms.md`
|
||||
Use when choosing team shape, role boundaries, and swarm ownership patterns.
|
||||
|
||||
### `references/missions-realtime.md`
|
||||
Use when assigning work and troubleshooting stale/live-update behavior from mission/event flow.
|
||||
|
||||
### `references/command-matrix.md`
|
||||
Use when you need exact command surfaces and argument shape.
|
||||
|
||||
### `references/failure-modes.md`
|
||||
Use when preflight/discovery/coordination fails and you need deterministic recovery.
|
||||
|
||||
## Project Context Template
|
||||
|
||||
The skill ships a source template file: `project.template.md`.
|
||||
|
||||
Runtime contract:
|
||||
|
||||
- Agents should use `<target-repo>/project.md` for project context.
|
||||
- If `<target-repo>/project.md` is missing, create it from `project.template.md`.
|
||||
- If `<target-repo>/project.md` already exists, do not overwrite it.
|
||||
|
||||
Helper command:
|
||||
|
||||
```bash
|
||||
& "$env:BB_REPO\bb.ps1" agent send --from <agent-id> --to <peer> --bead <bead-id> --category INFO --subject "Patched parser.ts for UI sync" --body "..."
|
||||
node skills/beadboard-driver/scripts/ensure-project-context.mjs --project-root <repo>
|
||||
```
|
||||
|
||||
5. **Liveness Maintenance**:
|
||||
Liveness is **Passive**. Any `bb agent` command extends your lease. Use `activity-lease` if you haven't run a command in > 10 minutes.
|
||||
## Tests
|
||||
|
||||
Skill-local contracts:
|
||||
|
||||
- `skills/beadboard-driver/tests/run-tests.mjs`
|
||||
- `skills/beadboard-driver/tests/*.contract.test.mjs`
|
||||
|
||||
Repo-level coverage:
|
||||
|
||||
- `tests/skills/beadboard-driver/*.test.ts`
|
||||
|
||||
## Verification Gates
|
||||
|
||||
```bash
|
||||
& "$env:BB_REPO\bb.ps1" agent activity-lease --agent <agent-id> --json
|
||||
npm run typecheck
|
||||
npm run lint
|
||||
npm run test
|
||||
```
|
||||
|
||||
6. **Closeout Evidence**:
|
||||
```bash
|
||||
node skills/beadboard-driver/scripts/readiness-report.mjs --checks '[{"name":"typecheck","ok":true}]' --artifacts '[{"path":"artifacts/final.png","required":true}]'
|
||||
bd close <bead-id> --reason "..."
|
||||
```
|
||||
If failures are outside your scope, cite exact failing files/tests and continue transparently.
|
||||
|
||||
## Identity & Adoption Policy
|
||||
## Bottom Line
|
||||
|
||||
- **Uniqueness**: Create one unique `adjective-noun` identity per session unless adopting.
|
||||
- **Adoption Guardrails**: Adoption is ONLY allowed if uncommitted changes exist in the scope OR you own an `in_progress` bead.
|
||||
- **Audit**: Every adoption triggers a `RESUME` event in the audit feed.
|
||||
|
||||
## Activity Lease (Parking Permit)
|
||||
|
||||
- **Active (0-15m)**: Lease is valid. You are protected from takeover.
|
||||
- **Stale (15-30m)**: Lease expired. Others can takeover with `--takeover-stale`.
|
||||
- **Evicted (30m+)**: Lease dead. Others should takeover and archive your reservation.
|
||||
- **Idle (60m+)**: Ghost state. You are considered gone.
|
||||
|
||||
## Red Flags - STOP and Start Over
|
||||
|
||||
- **Silent Incursion**: Editing a reserved file without sending an `INFO` message.
|
||||
- **Identity Reuse**: Reusing an agent ID from a previous session without an adoption handshake.
|
||||
- **Mocking**: Implementing mocks instead of coordinating with the domain owner.
|
||||
- **Terminal Pop-ups**: Spawning background workers that disrupt the user's desktop.
|
||||
|
||||
## References
|
||||
|
||||
- Command and argument contracts: `references/command-matrix.md`
|
||||
- End-to-end session choreography: `references/session-lifecycle.md`
|
||||
- Protocol Specification: `docs/protocols/operative-protocol-v1.md`
|
||||
This skill is the bridge between fast autonomous execution and human operator trust. Use it when speed matters, but coordination quality matters more.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue