Backlog & workflow cheat sheet¶

The Blackrim Vox backlog is tracked locally per-developer in bd (beads). The .beads/ directory is gitignored — issues are not synced via the repo. This doc captures the queries and recipes we actually use day-to-day so we never have to reinvent them.

If you're new to the repo, run bd ready to see what's available to claim. If you want to know what the project is shaping toward, scroll to "Current epics" below.

Most-used queries (copy/paste)¶

# Everything I can work on right now
bd ready

# All open items, by priority
bd list --status open --json \
  | jq -r '.[] | "P\(.priority) \(.id) — \(.title)"' \
  | sort

# P2 only — the "next-up-to-smash" tier
bd list --status open --json \
  | jq -r '.[] | select(.priority==2) | "\(.id) — \(.title)"'

# By epic prefix (e.g., all TTS sub-features)
bd list --status open --json \
  | jq -r '.[] | select(.title | startswith("tts")) | "\(.id) — \(.title)"'

# Other prefixes that work today: hotkey:, indicator:, wake-word:,
# subscription-auth:, mobile:
bd list --status open --json \
  | jq -r '.[] | select(.title | startswith("subscription-auth")) | "\(.id) — \(.title)"'

# Full body of one bead
bd show <bead-id>

# Find by title substring
bd list --status open --json \
  | jq -r '.[] | select(.title | test("menubar"; "i")) | "\(.id) — \(.title)"'

Claiming and closing¶

# Atomically claim work (prevents two parallel agents grabbing the same bead)
bd update <bead-id> --claim

# Close finished work
bd close <bead-id> --reason "Shipped in commit <sha>"

# Record an insight worth keeping (persisted; survives session resets)
bd remember "Voice gain on built-in mic typically -50 to -55 dBFS at idle"

Filing new work¶

# Short body inline
bd create --title "Short, action-shaped title" \
  --type feature --priority 2 \
  --description "What and why."

# Long body from a file (preferred for proposals)
bd create --title "..." --type epic --priority 2 \
  --body-file /tmp/spec.md

--type options used so far: feature, epic, task, bug. --priority 1 = critical, 2 = next-up, 3 = later, 4 = nice-to-have.

Current epics (parent beads)¶

Each epic owns a body in its bd show output with full design space. Sub-features filed as separate beads link back via the ## Parent epic trailer in their body.

Epic	What it adds	Sub-features filed
`blackrim-vox-lqx`	TTS engine (`tts/v1` contract + Piper / macOS say / ElevenLabs / OpenAI TTS); closes the voice-out loop	10
`blackrim-vox-nh1`	Recording-state indicators — menubar icon, screen overlay, audible dings, wake-word	8
`blackrim-vox-2cm`	Hotkey activation — burst-mode capture (per-platform global hotkeys)	6
`blackrim-vox-bx9`	Subscription-auth — use Claude Code / Codex / Cursor / Copilot subscriptions instead of API keys	7
`blackrim-vox-boq`	Mobile clients — iOS + Android, gomobile path	8

To list all sub-features for one epic:

bd list --status open --json \
  | jq -r --arg epic "blackrim-vox-lqx" '
      .[] | select(.body? // "" | contains($epic)) | "\(.id) — \(.title)"
    '

"What should I work on next?" recipes¶

Closing the voice→voice conversational loop (TTS)¶

Ship in this order; each unblocks the next:

blackrim-vox-di9 — Lock tts/v1 contract via grilling round
blackrim-vox-v1e — tts-say macOS shell-out backend (~1-2 days)
blackrim-vox-40r — Audio playback path via miniaudio (~2-3 days)
blackrim-vox-38t — TTS sink type routing llm_response envelopes (~2-3 days)
blackrim-vox-rec — Half-duplex pause during playback (~2-3 days)

Total: ~8 days of focused work. Outcome: dictate a question → hear Claude's answer.

Closing the "vox transcribe" trust loop¶

For users who want explicit recording state:

blackrim-vox-86o — Transcript-based wake-word ("vox" / "vox off") — ~3 days
blackrim-vox-pge — Audible activation/deactivation dings — ~2 days (depends on 40r)
blackrim-vox-uwd — macOS menubar icon (gray idle / red recording) — ~1 week

Unlocking subscription-auth (eliminate API-key friction)¶

Research-heavy; needs upstream coordination:

blackrim-vox-daz — Design auth-source/v1 contract — 1 session
blackrim-vox-92f — CLI onboarding (vox auth list-sources, vox auth select) — ~3 days
Then per-provider passthroughs based on what's actually exposed by Claude Code / Codex / Cursor / etc.

Mobile (slow burn)¶

Architecture ADR (blackrim-vox-7g0) is complete — see docs/architecture/mobile-adr.md. Decision: thin client (server-side pipeline). Sub-beads 3cm, 3n9, and the server-side network adapter are now unblocked. Mobile is 3-4 months of dedicated work; not a one-session arc.

Conventions for filing new sub-features¶

Title prefix matches parent epic theme (tts:, hotkey:, indicator:, etc.) so the bd list | jq | startswith(...) queries work.
Body opens with one paragraph of scope, then sections for Acceptance criteria, Depends on, Effort, Parent epic.
Effort estimates use days/weeks, not story points. Be honest — 1-2 weeks is more useful than "5 points".
Acceptance criteria are testable / observable conditions, not implementation hints.

When `bd` is unavailable¶

bd is gitignored, so a fresh clone has no backlog. To rebuild:

bd init — initializes a local .beads/ directory
Pick up where you left off from this doc's "Current epics" table — the parent-epic descriptions in git log are authoritative for what's meant by each ID
Cross-reference docs/extensions/*.md for contract design that informs the sub-feature scoping

Why this lives in the repo even though `bd` data doesn't¶

The commands are universal; the data is per-developer. This doc captures the commands. If you want to know what's actively being worked on, ask the person who has the .beads/ directory checked out (currently: [email protected]'s machine).

Future option: enable bd's git-sync (bd dolt push) so issues sync via a Dolt remote alongside the repo. Deliberately not enabled today — keeps the repo's history clean and decoupled from per-machine tooling.