핵심 개념

Beadbox는 bd CLI의 데이터 모델을 시각화합니다. 대시보드에 표시되는 모든 것을 아래 여섯 가지 개념으로 설명합니다.

워크스페이스

워크스페이스는 .beads/ 폴더를 포함하는 프로젝트 디렉터리입니다. 데이터베이스 백엔드는 SQLite(레거시) 또는 Dolt를 사용할 수 있습니다. 각 워크스페이스는 다른 프로젝트와 독립적으로 자체 이슈 세트를 추적합니다.

Beadbox는 ~/.beadbox/registry.json의 레지스트리, 마지막 활성 워크스페이스를 추적하는 쿠키, 그리고 현재 작업 디렉터리에서 .beads/ 폴더 스캔을 통해 워크스페이스를 감지합니다. 헤더의 선택기로 워크스페이스를 전환할 수 있습니다.

임베디드 모드에서는 모든 데이터가 로컬에 저장되며, 계정이나 클라우드 의존성이 없습니다. 워크스페이스는 다중 쓰기 접근을 위해 원격 Dolt 서버에 선택적으로 연결할 수 있으며, 이를 통해 push 및 pull 동기화가 가능합니다.

bead는 작업의 기본 단위로, 이슈, 태스크 또는 티켓에 해당합니다. 모든 bead에는 다음이 포함됩니다:

bd CLI가 부여하는 고유 ID (예: bb-a3f2), 워크스페이스 접두사와 base32 인코딩 접미사로 구성
제목과 선택적 설명 (마크다운 지원)
상태: open, in_progress, blocked, deferred, ready_for_qa, qa_passed, ready_to_ship, closed
우선순위: P0 (긴급)부터 P4 (백로그)까지
유형: task, bug, feature, epic, chore, decision (기본 유형). molecule 및 gate 같은 커스텀 유형은 워크스페이스별로 설정할 수 있습니다.
선택적 담당자

bd create로 bead를 생성하고 bd show로 조회합니다. Beadbox에서는 트리의 bead를 클릭하면 상세 패널이 열립니다.

에픽은 자식을 가진 bead입니다. 관련 작업을 그룹화하고 전체 진행 상황을 추적합니다. 트리 뷰에서 에픽은 완료된 자식 수를 기반으로 진행 바를 표시합니다.

--parent를 전달하여 자식을 만듭니다:

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

에픽은 중첩될 수 있습니다. 에픽의 자식 자체가 자식을 가진 에픽일 수 있습니다. 트리 뷰는 이 계층 구조를 펼치기/접기 컨트롤과 함께 렌더링합니다.

bead는 다른 bead를 차단할 수 있습니다. bead A가 bead B를 차단하면 A가 닫힐 때까지 B를 진행할 수 없습니다. 의존성은 트리 뷰에 블로커 배지로, 상세 패널에 의존성 목록으로 표시됩니다.

bd dep로 의존성을 설정합니다:

bd dep BEAD-A --blocks BEAD-B

Beadbox는 의존성 그래프를 그려서 어떤 bead가 진행을 막고 있는지 한눈에 볼 수 있게 합니다.

모든 bead에는 코멘트 스레드가 있습니다. 코멘트는 에이전트와 사람이 bead에 대해 소통하는 수단입니다: 구현 전 계획 게시, 완료 보고, 블로커 신고, QA 검증 단계 제공에 사용됩니다.

CLI에서 코멘트를 추가합니다:

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

Beadbox에서 코멘트는 상세 패널에 마크다운으로 시간순 렌더링됩니다.

모든 bead는 다음 라이프사이클을 따릅니다:

각 상태에는 Beadbox에서 고유한 색상 배지가 있습니다. 필터 바에서 상태별로 bead를 표시하거나 숨길 수 있습니다. 활동 대시보드는 이 상태를 사용하여 파이프라인 단계별로 bead를 그룹화합니다.