Conceitos fundamentais

Workspace

Um workspace é um diretório de projeto que contém uma pasta .beads/. O backend do banco de dados pode ser SQLite (legado) ou Dolt. Cada workspace gerencia seu próprio conjunto de issues, independente de outros projetos.

O Beadbox detecta workspaces a partir do registro em ~/.beadbox/registry.json, de um cookie que rastreia o último workspace ativo e da varredura do diretório de trabalho atual em busca de pastas .beads/. Alterne entre workspaces usando o seletor no cabeçalho.

No modo integrado, todos os dados permanecem locais sem conta ou dependência de nuvem. Um workspace pode opcionalmente se conectar a um servidor Dolt remoto para acesso multi-escritor, habilitando sincronização push e pull.

Bead

Um bead é a unidade fundamental de trabalho: um issue, tarefa ou ticket. Cada bead tem:

• Um ID único (ex: bb-a3f2) atribuído pelo CLI bd, composto por um prefixo do workspace e um sufixo codificado em base32
• Um título e descrição opcional (suporta markdown)
• Status: open, in_progress, blocked, deferred, ready_for_qa, qa_passed, ready_to_ship ou closed
• Prioridade: P0 (crítica) até P4 (backlog)
• Tipo: task, bug, feature, epic, chore ou decision (tipos principais). Tipos personalizados como molecule e gate podem ser configurados por workspace.
• Um responsável opcional

Crie beads com bd create e visualize com bd show. No Beadbox, clique em qualquer bead na árvore para abrir seu painel de detalhes.

Epic

Um epic é um bead com filhos. Agrupa trabalho relacionado e acompanha o progresso geral. Na visualização em árvore, epics mostram uma barra de progresso baseada em quantos filhos estão fechados.

Crie um filho passando --parent:

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

Epics podem ser aninhados. Um filho de um epic pode ser ele mesmo um epic com seus próprios filhos. A visualização em árvore renderiza essa hierarquia com controles de expandir/recolher.

Dependência

Um bead pode bloquear outros beads. Quando o bead A bloqueia o bead B, B não pode prosseguir até que A seja fechado. Dependências aparecem como badges de bloqueio na visualização em árvore e como lista de dependências no painel de detalhes.

Defina uma dependência com bd dep:

bd dep BEAD-A --blocks BEAD-B

O Beadbox desenha o grafo de dependências para que você veja de relance quais beads estão bloqueando o progresso.

Comentário

Cada bead tem um thread de comentários. Comentários são a forma como agentes e pessoas se comunicam sobre um bead: publicam planos antes de implementar, reportam conclusão, sinalizam bloqueios e fornecem passos de verificação para QA.

Adicione um comentário pelo CLI:

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

No Beadbox, os comentários são renderizados como markdown no painel de detalhes, ordenados cronologicamente.

Ciclo de vida dos status

Cada bead segue este ciclo de vida:

Cada status tem um badge de cor distinto no Beadbox. A barra de filtros permite mostrar ou ocultar beads por status. O Dashboard de Atividade agrupa os beads por estágio do pipeline usando esses status.