Concetti fondamentali

Beadbox visualizza il modello dati dietro il CLI bd. Questi sei concetti coprono tutto ciò che vedi nella dashboard.

Workspace

Un workspace è una directory di progetto che contiene una cartella .beads/. Il backend del database può essere SQLite (legacy) o Dolt. Ogni workspace gestisce il proprio set di issue, indipendentemente dagli altri progetti.

Beadbox rileva i workspace dal registro in ~/.beadbox/registry.json, da un cookie che traccia l'ultimo workspace attivo e dalla scansione della directory di lavoro corrente alla ricerca di cartelle .beads/. Passa da un workspace all'altro con il selettore nell'intestazione.

In modalità integrata, tutti i dati restano in locale senza account o dipendenze dal cloud. Un workspace può opzionalmente connettersi a un server Dolt remoto per accesso multi-scrittura, abilitando la sincronizzazione push e pull.

Bead

Un bead è l'unità fondamentale di lavoro: un issue, un'attività o un ticket. Ogni bead ha:

Un ID univoco (es. bb-a3f2) assegnato dal CLI bd, composto da un prefisso del workspace e un suffisso codificato in base32
Un titolo e una descrizione opzionale (markdown supportato)
Stato: open, in_progress, blocked, deferred, ready_for_qa, qa_passed, ready_to_ship o closed
Priorità: P0 (critica) fino a P4 (backlog)
Tipo: task, bug, feature, epic, chore o decision (tipi principali). Tipi personalizzati come molecule e gate possono essere configurati per workspace.
Un assegnatario opzionale

Crea bead con bd create e visualizzali con bd show. In Beadbox, clicca su qualsiasi bead nell'albero per aprire il suo pannello dei dettagli.

Epic

Un epic è un bead con figli. Raggruppa lavoro correlato e traccia il progresso aggregato. Nella vista ad albero, gli epic mostrano una barra di avanzamento basata su quanti figli sono chiusi.

Crea un figlio passando --parent:

bd create --title="Subtask" --type=task --parent=EPIC-ID

Gli epic possono annidarsi. Un figlio di un epic può essere a sua volta un epic con i propri figli. La vista ad albero rappresenta questa gerarchia con controlli di espansione/compressione.

Dipendenza

Un bead può bloccare altri bead. Quando il bead A blocca il bead B, B non può procedere finché A non è chiuso. Le dipendenze appaiono come badge di blocco nella vista ad albero e come lista di dipendenze nel pannello dei dettagli.

Imposta una dipendenza con bd dep:

bd dep BEAD-A --blocks BEAD-B

Beadbox disegna il grafo delle dipendenze per farti vedere a colpo d'occhio quali bead stanno bloccando il progresso.

Commento

Ogni bead ha un thread di commenti. I commenti sono il modo in cui agenti e persone comunicano su un bead: pubblicano piani prima dell'implementazione, segnalano il completamento, evidenziano blocchi e forniscono i passi di verifica per il QA.

Aggiungi un commento dal CLI:

bd comments add BEAD-ID --author agent-name "PLAN: ..."
bd comments add BEAD-ID --author agent-name "DONE: ..."

In Beadbox, i commenti vengono renderizzati come markdown nel pannello dei dettagli, ordinati cronologicamente.

Ciclo di vita degli stati

Ogni bead segue questo ciclo di vita:

`open`	Creato, non ancora iniziato
`in_progress`	Qualcuno ci sta lavorando
`blocked`	In attesa che una dipendenza venga risolta
`deferred`	Posticipato a una data futura
`ready_for_qa`	Implementazione completata, in attesa di validazione
`qa_passed`	QA superato, pronto per la distribuzione
`ready_to_ship`	Approvato e in attesa del prossimo rilascio
`closed`	Completato

Ogni stato ha un badge colorato distinto in Beadbox. La barra dei filtri ti permette di mostrare o nascondere i bead per stato. La Dashboard di Attività raggruppa i bead per fase della pipeline usando questi stati.