Conceptos fundamentales

Workspace

Un workspace es un directorio de proyecto que contiene una carpeta .beads/. El backend de base de datos puede ser SQLite (legado) o Dolt. Cada workspace gestiona su propio conjunto de issues, independiente de otros proyectos.

Beadbox detecta workspaces desde el registro en ~/.beadbox/registry.json, una cookie que rastrea tu ultimo workspace activo, y escaneando el directorio de trabajo actual en busca de carpetas .beads/. Cambia entre workspaces usando el selector en el encabezado.

En modo embebido, todos los datos permanecen locales sin dependencia de cuentas ni de la nube. Un workspace puede conectarse opcionalmente a un servidor Dolt remoto para acceso multi-escritor, lo que habilita la sincronizacion push y pull.

Bead

Un bead es la unidad fundamental de trabajo: un issue, tarea o ticket. Cada bead tiene:

• Un ID unico (p. ej., bb-a3f2) asignado por el CLI bd, usando un prefijo de workspace y un sufijo codificado en base32
• Un título y descripción opcional (soporta markdown)
• Estado: open, in_progress, blocked, deferred, ready_for_qa, qa_passed, ready_to_ship o closed
• Prioridad: P0 (crítica) a P4 (backlog)
• Tipo: task, bug, feature, epic, chore o decision (tipos principales). Los tipos personalizados como molecule y gate se pueden configurar por workspace.
• Un asignado opcional

Crea beads con bd create y consúltalos con bd show. En Beadbox, haz clic en cualquier bead del árbol para abrir su panel de detalles.

Epic

Un epic es un bead con hijos. Agrupa trabajo relacionado y rastrea el progreso agregado. En la vista de árbol, los epics muestran una barra de progreso basada en cuántos hijos están cerrados.

Crea un hijo pasando --parent:

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

Los epics pueden anidarse. Un hijo de un epic puede ser a su vez un epic con sus propios hijos. La vista de árbol renderiza esta jerarquía con controles de expandir/contraer.

Dependencia

Un bead puede bloquear a otros beads. Cuando el bead A bloquea al bead B, B no puede avanzar hasta que A esté cerrado. Las dependencias aparecen como insignias de bloqueo en la vista de árbol y como lista de dependencias en el panel de detalles.

Establece una dependencia con bd dep:

bd dep BEAD-A --blocks BEAD-B

Beadbox dibuja el grafo de dependencias para que puedas ver de un vistazo qué beads están bloqueando el progreso.

Comentario

Cada bead tiene un hilo de comentarios. Los comentarios son la forma en que agentes y humanos se comunican sobre un bead: publican planes antes de implementar, reportan completado, señalan bloqueos y proporcionan pasos de verificación para QA.

Agrega un comentario desde el CLI:

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

En Beadbox, los comentarios se renderizan como markdown en el panel de detalles, ordenados cronológicamente.

Ciclo de vida de estados

Cada bead sigue este ciclo de vida:

Cada estado tiene una insignia de color distinta en Beadbox. La barra de filtros te permite mostrar u ocultar beads por estado. El Dashboard de Actividad agrupa los beads por etapa del pipeline usando estos estados.