checkpoint: pre-split branch cleanup
This commit is contained in:
ZenchantLive
parent
4c2ae2e5b7
commit
b5db7a7753
276 changed files with 35912 additions and 60119 deletions
|
|
@ -0,0 +1,96 @@
|
|||
# Archetypes, Templates, and Swarms
|
||||
|
||||
## Purpose
|
||||
|
||||
Define reusable team structure for multi-agent work so assignments are predictable, auditable, and easy for users to orchestrate from BeadBoard.
|
||||
|
||||
## Core Principle
|
||||
|
||||
Archetypes and templates define team composition. Missions define task execution.
|
||||
|
||||
Keep these concerns separate.
|
||||
|
||||
## Archetypes (Role Contracts)
|
||||
|
||||
An archetype is a role with clear responsibilities and deliverable expectations.
|
||||
|
||||
Baseline archetypes:
|
||||
|
||||
- `coder`: implements scoped changes and provides evidence.
|
||||
- `reviewer`: validates quality, regressions, and acceptance criteria.
|
||||
- `writer`: maintains user-facing docs, memory docs, and operator notes.
|
||||
|
||||
Optional archetypes may exist per project, but every archetype should specify:
|
||||
|
||||
- primary responsibilities,
|
||||
- quality gates,
|
||||
- handoff inputs/outputs,
|
||||
- escalation triggers.
|
||||
|
||||
## Team Templates (Composition Contracts)
|
||||
|
||||
A template is a named role composition for repeatable work patterns.
|
||||
|
||||
Examples:
|
||||
|
||||
- Fast lane: `coder + reviewer`
|
||||
- Documentation lane: `writer + reviewer`
|
||||
- Parallel lane: `orchestrator + coder + reviewer + writer`
|
||||
|
||||
Template quality rules:
|
||||
|
||||
- keep composition minimal,
|
||||
- avoid duplicate authority,
|
||||
- define ownership boundaries,
|
||||
- define expected handoff order.
|
||||
|
||||
## Swarms (Runtime Team Instances)
|
||||
|
||||
A swarm is a live team instance operating on specific beads/epics.
|
||||
|
||||
Lifecycle:
|
||||
|
||||
1. Create swarm instance from a template or manual composition.
|
||||
2. Join agents into explicit roles.
|
||||
3. Assign beads with ownership.
|
||||
4. Coordinate via events and inbox.
|
||||
5. Leave or close swarm cleanly when complete.
|
||||
|
||||
## Command Surface (Representative)
|
||||
|
||||
Use your environment's swarm commands to manage lifecycle.
|
||||
|
||||
Expected operations:
|
||||
|
||||
- create swarm
|
||||
- list/show swarm
|
||||
- join swarm with role
|
||||
- leave swarm
|
||||
- close swarm
|
||||
|
||||
All swarm actions should produce observable state changes in BeadBoard views.
|
||||
|
||||
## Ownership Rules
|
||||
|
||||
- Every in-progress bead should have one clear assignee.
|
||||
- Swarms may collaborate on an epic, but each bead needs an explicit owner.
|
||||
- Multi-agent edits require reservation and coordination signals.
|
||||
|
||||
## User Orchestration Relationship
|
||||
|
||||
Users control orchestration from BeadBoard UI:
|
||||
|
||||
- choose team shape/template,
|
||||
- assign or reassign roles,
|
||||
- intervene on blockers,
|
||||
- monitor throughput and liveness.
|
||||
|
||||
Agents execute according to assigned role and bead ownership.
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- Role ambiguity (multiple agents assuming same responsibility).
|
||||
- Oversized swarms with no clear ownership boundaries.
|
||||
- Using templates as mission definitions.
|
||||
- Running unassigned parallel work with no bead claim.
|
||||
- Treating swarm closure as optional housekeeping.
|
||||
|
|
@ -1,38 +1,41 @@
|
|||
# Command Matrix
|
||||
|
||||
## Bootstrapping and Handshake
|
||||
|
||||
- `node scripts/bb-init.mjs --register <name> --role <role> --json`
|
||||
- Output: `{ ok, agent_id, mode, lease, timestamp }`
|
||||
- `node scripts/bb-init.mjs --adopt <id> [--non-interactive] --json`
|
||||
- Output: `{ ok, agent_id, mode, lease, timestamp }` or `{ ok:false, error }`
|
||||
|
||||
## Coordination Commands (`bb`)
|
||||
|
||||
- `bb agent register --name <agent> --role <role>`
|
||||
- `bb agent activity-lease --agent <agent> [--json]`
|
||||
- Output: `{ ok, command, data: AgentRecord }`
|
||||
- `bb agent list [--role <role>] [--status <status>]`
|
||||
- `bb agent show --agent <agent>`
|
||||
- `bb agent send --from <agent> --to <agent> --bead <id> --category <HANDOFF|BLOCKED|DECISION|INFO> --subject <text> --body <text>`
|
||||
- `bb agent inbox --agent <agent> [--state unread|read|acked] [--bead <id>]`
|
||||
- `bb agent read --agent <agent> --message <message-id>`
|
||||
- `bb agent ack --agent <agent> --message <message-id>`
|
||||
- `bb agent reserve --agent <agent> --scope <path> --bead <id> [--ttl <minutes>] [--takeover-stale]`
|
||||
- `bb agent release --agent <agent> --scope <path>`
|
||||
- `bb agent status [--bead <id>] [--agent <agent>]`
|
||||
|
||||
## Lifecycle Commands (`bd`)
|
||||
|
||||
- `bd ready`
|
||||
- `bd show <bead-id>`
|
||||
- `bd update <bead-id> --status in_progress --claim`
|
||||
- `bd update <bead-id> --notes "<evidence>"`
|
||||
- `bd close <bead-id> --reason "<summary>"`
|
||||
|
||||
## Legacy/Internal Scripts
|
||||
|
||||
# Command Matrix
|
||||
|
||||
## Bootstrapping and Handshake
|
||||
|
||||
- `node scripts/bb-init.mjs --register <name> --role <role> --json`
|
||||
- Output: `{ ok, agent_id, mode, lease, timestamp }`
|
||||
- `node scripts/bb-init.mjs --adopt <id> [--non-interactive] --json`
|
||||
- Output: `{ ok, agent_id, mode, lease, timestamp }` or `{ ok:false, error }`
|
||||
|
||||
## Coordination Commands (`bb`)
|
||||
|
||||
- `bb agent register --name <agent> --role <role>`
|
||||
- `bb agent activity-lease --agent <agent> [--json]`
|
||||
- Output: `{ ok, command, data: AgentRecord }`
|
||||
- `bb agent list [--role <role>] [--status <status>]`
|
||||
- `bb agent show --agent <agent>`
|
||||
- `bb agent send --from <agent> --to <agent> --bead <id> --category <HANDOFF|BLOCKED|DECISION|INFO> --subject <text> --body <text>`
|
||||
- `bb agent inbox --agent <agent> [--state unread|read|acked] [--bead <id>]`
|
||||
- `bb agent read --agent <agent> --message <message-id>`
|
||||
- `bb agent ack --agent <agent> --message <message-id>`
|
||||
- `bb agent reserve --agent <agent> --scope <path> --bead <id> [--ttl <minutes>] [--takeover-stale]`
|
||||
- `bb agent release --agent <agent> --scope <path>`
|
||||
- `bb agent status [--bead <id>] [--agent <agent>]`
|
||||
|
||||
## Lifecycle Commands (`bd`)
|
||||
|
||||
- `bd ready`
|
||||
- `bd show <bead-id>`
|
||||
- `bd update <bead-id> --status in_progress --claim`
|
||||
- `bd update <bead-id> --notes "<evidence>"`
|
||||
- `bd close <bead-id> --reason "<summary>"`
|
||||
|
||||
## Legacy/Internal Scripts
|
||||
|
||||
- `node skills/beadboard-driver/scripts/resolve-bb.mjs`
|
||||
- `node skills/beadboard-driver/scripts/session-preflight.mjs`
|
||||
- `node skills/beadboard-driver/scripts/generate-agent-name.mjs`
|
||||
- `node skills/beadboard-driver/scripts/readiness-report.mjs --checks <json> --artifacts <json>`
|
||||
- `node skills/beadboard-driver/scripts/readiness-report.mjs --checks <json> --artifacts <json>`
|
||||
- `node skills/beadboard-driver/scripts/diagnose-env.mjs`
|
||||
- `node skills/beadboard-driver/scripts/heal-common-issues.mjs [--project-root <path>] [--apply] [--fix-git-index-lock]`
|
||||
- `node skills/beadboard-driver/scripts/ensure-project-context.mjs [--project-root <path>]`
|
||||
|
|
|
|||
121
skills/beadboard-driver/references/coord-events-sessions-ack.md
Normal file
121
skills/beadboard-driver/references/coord-events-sessions-ack.md
Normal file
|
|
@ -0,0 +1,121 @@
|
|||
# Coordination Events, Sessions, and Acknowledgment
|
||||
|
||||
## Purpose
|
||||
|
||||
Define how agents communicate status, blockers, incursions, and handoffs in a machine-readable way that BeadBoard can render and users can act on.
|
||||
|
||||
## Operating Model
|
||||
|
||||
- Agent works in a target repository.
|
||||
- User watches and orchestrates from BeadBoard UI.
|
||||
- Agent communication must flow through coordination events and inbox state transitions, not ad-hoc notes.
|
||||
|
||||
## Event Categories
|
||||
|
||||
Use explicit categories with clear intent:
|
||||
|
||||
- `HANDOFF`: transfer ownership or next action.
|
||||
- `BLOCKED`: explicit dependency or missing input.
|
||||
- `RESUME`: adoption/resumption event.
|
||||
- `INFO`: milestone or important context.
|
||||
- `INCURSION`: overlap/collision signal for reserved scope.
|
||||
|
||||
## Session Stream Expectations
|
||||
|
||||
Session feeds should be audit-friendly:
|
||||
|
||||
- Every coordination event has sender, recipient/system target, bead id, and timestamp.
|
||||
- `INCURSION` and `RESUME` are first-class timeline rows, not hidden diagnostics.
|
||||
- Events should be understandable by humans without reading implementation code.
|
||||
|
||||
## Message Lifecycle
|
||||
|
||||
Inbox state machine:
|
||||
|
||||
1. `unread` when message is delivered.
|
||||
2. `read` when recipient opens/reads message.
|
||||
3. `acked` when recipient explicitly acknowledges.
|
||||
|
||||
Required behavior:
|
||||
|
||||
- Only recipient may ack.
|
||||
- Acks are explicit, not implied by read.
|
||||
- Blocker and handoff flows should request ack when coordination certainty is required.
|
||||
|
||||
## Recommended Command Patterns
|
||||
|
||||
Send structured coordination event:
|
||||
|
||||
```bash
|
||||
bb agent send \
|
||||
--from <agent-id> \
|
||||
--to <peer-agent-id> \
|
||||
--bead <bead-id> \
|
||||
--category <HANDOFF|BLOCKED|RESUME|INFO|INCURSION> \
|
||||
--subject "<short summary>" \
|
||||
--body "<actionable details>"
|
||||
```
|
||||
|
||||
Read inbox for current bead/session work:
|
||||
|
||||
```bash
|
||||
bb agent inbox --agent <agent-id> --state unread --bead <bead-id>
|
||||
bb agent read --agent <agent-id> --message <message-id>
|
||||
bb agent ack --agent <agent-id> --message <message-id>
|
||||
```
|
||||
|
||||
## Coordination Contracts
|
||||
|
||||
### Handoff
|
||||
|
||||
A `HANDOFF` should include:
|
||||
|
||||
- what is done,
|
||||
- what remains,
|
||||
- concrete next action,
|
||||
- whether ack is required.
|
||||
|
||||
### Blocked
|
||||
|
||||
A `BLOCKED` should include:
|
||||
|
||||
- blocker description,
|
||||
- requested action,
|
||||
- urgency,
|
||||
- ack requirement.
|
||||
|
||||
### Incursion
|
||||
|
||||
An `INCURSION` should include:
|
||||
|
||||
- overlap kind (`exact` or `partial`),
|
||||
- owner identity,
|
||||
- incoming identity,
|
||||
- owner liveness,
|
||||
- resolution hint.
|
||||
|
||||
### Resume
|
||||
|
||||
A `RESUME` should include:
|
||||
|
||||
- resume reason,
|
||||
- prior session identity,
|
||||
- adopted identity,
|
||||
- evidence summary for safe adoption.
|
||||
|
||||
## UX Alignment
|
||||
|
||||
Session UI should map event semantics to plain-language actions:
|
||||
|
||||
- Handoff label: "Passed to"
|
||||
- Blocked label: "Needs input"
|
||||
- Read action: "Seen"
|
||||
- Ack action: "Accepted"
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- Using comments instead of coordination events for handoffs.
|
||||
- Silent reservation collisions with no `INCURSION`/`INFO` signal.
|
||||
- Treating read as ack.
|
||||
- Sending vague events with no actionable payload.
|
||||
- Closing a blocked bead without tracking unblock communication.
|
||||
|
|
@ -38,3 +38,10 @@
|
|||
- Do not write `.beads/issues.jsonl` directly.
|
||||
- Do not close beads without verification evidence.
|
||||
- Do not bypass `BB_REPO` when it is set but invalid; fix it explicitly.
|
||||
|
||||
## Local Environment Repair Signals
|
||||
|
||||
- `GIT_INDEX_LOCK_PRESENT`: stale git lock can block local operations.
|
||||
- Recovery:
|
||||
- confirm no active git process is using the repository,
|
||||
- run `node skills/beadboard-driver/scripts/heal-common-issues.mjs --project-root <repo> --apply --fix-git-index-lock`.
|
||||
|
|
|
|||
110
skills/beadboard-driver/references/memory-system.md
Normal file
110
skills/beadboard-driver/references/memory-system.md
Normal file
|
|
@ -0,0 +1,110 @@
|
|||
# Memory System
|
||||
|
||||
## Purpose
|
||||
|
||||
Use BeadBoard memory to preserve reusable operating rules across sessions.
|
||||
|
||||
Memory is tracked in `bd` decision beads, not markdown notes. Task notes are for local execution context; canonical memory is for reusable rules.
|
||||
|
||||
## Execution Context
|
||||
|
||||
- Agents usually run in a target project repository, not the BeadBoard repository.
|
||||
- Project scope is controlled by the user in the BeadBoard UI.
|
||||
- Agents do not select or mutate project scope.
|
||||
|
||||
## Core Objects
|
||||
|
||||
- Anchor: domain parent bead (for example architecture, workflow, agent ops, reliability).
|
||||
- Canonical memory: `type=decision` bead with memory labels.
|
||||
- Provenance links: relations from memory to source evidence beads.
|
||||
|
||||
## Canonical Memory Contract
|
||||
|
||||
Create canonical memory only when the rule is reusable.
|
||||
|
||||
Required labels:
|
||||
|
||||
- `mem-canonical`
|
||||
- `mem-hard` or `mem-soft`
|
||||
- `memory`
|
||||
- domain label such as `memory-agent`, `memory-arch`, `memory-workflow`, `memory-reliability`, `memory-ui`
|
||||
|
||||
Required description sections:
|
||||
|
||||
- `Scope:`
|
||||
- `Out of Scope:`
|
||||
- `Rule:`
|
||||
- `Rationale:`
|
||||
- `Failure Mode:`
|
||||
|
||||
Required acceptance style:
|
||||
|
||||
- Given/When/Then invariant
|
||||
- Verification commands
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Query existing memory first.
|
||||
2. Validate the memory provenance before relying on it.
|
||||
3. Apply existing canonical memory to current task design.
|
||||
4. If a new reusable rule appears, create canonical memory.
|
||||
5. Link anchor, evidence, and related work with `bd dep relate`.
|
||||
6. Ratify by closing the memory bead once complete.
|
||||
7. For changes to an existing rule, supersede; do not rewrite history.
|
||||
|
||||
## Query and Validation Commands
|
||||
|
||||
```bash
|
||||
bd query "type=decision label:mem-canonical"
|
||||
bd show <memory-id>
|
||||
bd dep list <memory-id>
|
||||
```
|
||||
|
||||
Interpretation checklist:
|
||||
|
||||
- Is the memory closed and canonical?
|
||||
- Are provenance links present (2-5 evidence beads preferred)?
|
||||
- Is the domain anchor relationship present?
|
||||
|
||||
## Create and Index Canonical Memory
|
||||
|
||||
```bash
|
||||
bd create --title="[MEMORY][<DOMAIN>][HARD|SOFT] <rule sentence>" \
|
||||
--description="Scope: ...\nOut of Scope: ...\nRule: ...\nRationale: ...\nFailure Mode: ..." \
|
||||
--type=decision --priority=1 \
|
||||
--label="mem-canonical,mem-hard,memory,memory-<domain>"
|
||||
|
||||
bd dep relate <anchor-id> <memory-id>
|
||||
bd dep relate <memory-id> <source-bead-id>
|
||||
```
|
||||
|
||||
Use `mem-soft` when the rule is guidance and `mem-hard` when it is non-negotiable.
|
||||
|
||||
## Evolve Memory Safely
|
||||
|
||||
Use supersession when changing canonical rules:
|
||||
|
||||
```bash
|
||||
bd supersede <old-memory-id> --with <new-memory-id>
|
||||
```
|
||||
|
||||
Do not edit historical memory beads to represent new policy.
|
||||
|
||||
## Noise Budget
|
||||
|
||||
Apply memory sparingly per active task:
|
||||
|
||||
- 3-7 related memory nodes
|
||||
- 0-2 blocker contracts
|
||||
- 1 primary anchor domain per canonical memory
|
||||
- 2-5 source-bead provenance links
|
||||
|
||||
If the lesson is not reusable, record it in task notes instead of creating memory.
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- Writing policy in ad-hoc markdown only.
|
||||
- Using blocker edges for memory indexing.
|
||||
- Creating duplicate canonical memory for the same rule.
|
||||
- Creating memory for one-off incidents without recurrence.
|
||||
- Claiming memory-backed completion without verification evidence.
|
||||
96
skills/beadboard-driver/references/missions-realtime.md
Normal file
96
skills/beadboard-driver/references/missions-realtime.md
Normal file
|
|
@ -0,0 +1,96 @@
|
|||
# Missions and Realtime
|
||||
|
||||
## Purpose
|
||||
|
||||
Define how work assignments (missions) and realtime updates should behave so users can orchestrate external-repo execution from BeadBoard with confidence.
|
||||
|
||||
## Mission Model
|
||||
|
||||
A mission is an execution assignment bound to clear ownership and expected outputs.
|
||||
|
||||
Mission essentials:
|
||||
|
||||
- bead/epic scope,
|
||||
- assigned owner,
|
||||
- expected deliverable,
|
||||
- dependency awareness,
|
||||
- handoff path.
|
||||
|
||||
## Assignment Rules
|
||||
|
||||
- One active owner per bead-level mission.
|
||||
- Multi-agent support is achieved through parallel missions, not shared ambiguous ownership.
|
||||
- Mission assignment must be visible in BeadBoard and reflected in bead assignee/status fields.
|
||||
|
||||
## Mission Topology
|
||||
|
||||
Missions should align with dependency graph semantics:
|
||||
|
||||
- dependencies model execution order,
|
||||
- independent missions can run in parallel,
|
||||
- blocked missions must not be represented as ready work.
|
||||
|
||||
When topology changes, update bead dependency links first, then assignment communication.
|
||||
|
||||
## Realtime Contract
|
||||
|
||||
Realtime is the user visibility layer.
|
||||
|
||||
Expected sources:
|
||||
|
||||
- bead status updates,
|
||||
- coordination events,
|
||||
- reservation/lease changes,
|
||||
- watcher/SSE refresh signals.
|
||||
|
||||
Expected outcomes:
|
||||
|
||||
- UI updates without manual refresh,
|
||||
- consistent state across social/graph/session surfaces,
|
||||
- event timeline continuity for audits.
|
||||
|
||||
## SSE/Event Behavior
|
||||
|
||||
Realtime streams should provide:
|
||||
|
||||
- monotonic event ids where supported,
|
||||
- heartbeat behavior for long-lived connections,
|
||||
- resilience to brief write bursts and file-watch jitter,
|
||||
- eventual consistency with bead source of truth.
|
||||
|
||||
If stale-state is suspected, triage in this order:
|
||||
|
||||
1. Source-of-truth parity.
|
||||
2. Read-path validation.
|
||||
3. Watcher input coverage.
|
||||
4. Event emission/subscription path.
|
||||
|
||||
## Agent Responsibilities
|
||||
|
||||
Agents must:
|
||||
|
||||
- emit meaningful coordination events during mission lifecycle,
|
||||
- keep bead status and assignee current,
|
||||
- provide verification evidence before close,
|
||||
- avoid implicit/unlogged handoffs.
|
||||
|
||||
Agents must not:
|
||||
|
||||
- change BeadBoard UI project scope,
|
||||
- rely on local assumptions not visible in event/state outputs.
|
||||
|
||||
## User Responsibilities
|
||||
|
||||
Users orchestrate control-plane actions in BeadBoard UI:
|
||||
|
||||
- scope selection,
|
||||
- priority/assignment changes,
|
||||
- intervention on blocked missions,
|
||||
- monitoring mission and realtime health.
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- Mission start without bead claim/assignee update.
|
||||
- Hidden handoffs outside coordination events.
|
||||
- Treating stale UI as resolved without parity checks.
|
||||
- Closing missions without verification evidence.
|
||||
|
|
@ -2,10 +2,13 @@
|
|||
|
||||
## 1) Start Session
|
||||
|
||||
1. Run preflight.
|
||||
2. Resolve bb path and confirm `bd` availability.
|
||||
3. Generate unique session agent name.
|
||||
4. Register agent identity.
|
||||
1. Run environment diagnosis.
|
||||
2. Run preflight.
|
||||
3. Resolve bb path and confirm `bd` availability.
|
||||
4. Generate unique session agent name.
|
||||
5. Register agent identity.
|
||||
6. Confirm you are operating in the assigned target repository.
|
||||
7. Do not change project scope (scope is user-controlled in BeadBoard UI).
|
||||
|
||||
## 2) Pick and Claim Work
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue