Concepts fondamentaux

Workspace

Un workspace est un repertoire de projet contenant un dossier .beads/. Le backend de base de donnees peut etre SQLite (ancien) ou Dolt. Chaque workspace gere son propre ensemble d'issues, independamment des autres projets.

Beadbox detecte les workspaces depuis le registre dans ~/.beadbox/registry.json, un cookie qui suit ton dernier workspace actif, et en scannant le repertoire de travail actuel a la recherche de dossiers .beads/. Bascule entre les workspaces grace au selecteur dans l'en-tete.

En mode embarque, toutes les donnees restent locales sans dependance a un compte ou au cloud. Un workspace peut optionnellement se connecter a un serveur Dolt distant pour un acces multi-ecrivain, ce qui permet la synchronisation push et pull.

Bead

Un bead est l'unité de travail fondamentale : un issue, une tâche ou un ticket. Chaque bead possède :

• Un ID unique (par ex., bb-a3f2) attribue par le CLI bd, utilisant un prefixe de workspace et un suffixe encode en base32
• Un titre et une description optionnelle (markdown supporté)
• Statut : open, in_progress, blocked, deferred, ready_for_qa, qa_passed, ready_to_ship ou closed
• Une priorité : P0 (critique) à P4 (backlog)
• Type : task, bug, feature, epic, chore ou decision (types principaux). Les types personnalises comme molecule et gate peuvent etre configures par workspace.
• Un responsable optionnel

Crée des beads avec bd create et consulte-les avec bd show. Dans Beadbox, clique sur n'importe quel bead dans l'arbre pour ouvrir son panneau de détails.

Epic

Un epic est un bead avec des enfants. Il regroupe du travail lié et suit la progression globale. Dans la vue en arbre, les epics affichent une barre de progression basée sur le nombre d'enfants fermés.

Crée un enfant en passant --parent :

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

Les epics peuvent s'imbriquer. Un enfant d'un epic peut lui-même être un epic avec ses propres enfants. La vue en arbre rend cette hiérarchie avec des contrôles de développement/repli.

Dépendance

Un bead peut bloquer d'autres beads. Quand le bead A bloque le bead B, B ne peut pas avancer tant que A n'est pas fermé. Les dépendances apparaissent sous forme de badges de blocage dans la vue en arbre et comme liste de dépendances dans le panneau de détails.

Definis une dependance avec bd dep :

bd dep BEAD-A --blocks BEAD-B

Beadbox dessine le graphe de dépendances pour que tu puisses voir d'un coup d'oeil quels beads bloquent la progression.

Commentaire

Chaque bead possède un fil de commentaires. Les commentaires sont le moyen par lequel agents et humains communiquent sur un bead : poster des plans avant l'implémentation, signaler l'achèvement, remonter des blocages et fournir des étapes de vérification QA.

Ajoute un commentaire depuis le CLI :

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

Dans Beadbox, les commentaires sont rendus en markdown dans le panneau de détails, classés par ordre chronologique.

Cycle de vie des statuts

Chaque bead suit ce cycle de vie :

Chaque statut a un badge de couleur distinct dans Beadbox. La barre de filtres te permet d'afficher ou de masquer les beads par statut. Le Dashboard d'Activité regroupe les beads par étape du pipeline en utilisant ces statuts.