Beads guide: skeleton

Companion to How we use AI. Target: guides/beads.md, linked from the AI guide's manifesto point 4 and its Beads glossary entry. Method as for the AI guide (chapter 1 drafting plan): skeleton → critique → draft page → critique → Rufus review. v1 skeleton critiqued by subagent; changes listed at the end.

Audience and stance

• Reader: a team member (often not a developer) who works through Claude Code, has heard "Beads", never typed bd.
• One message: Beads is a task tracker built for your AI to use, not for you. You use it by talking to your AI.
• Shape: short opening that lands that point → one compact "what and why" section (~⅓ of page) → how-to (~½ of page) → what goes wrong → setup.
• Complements, doesn't repeat, the AI guide: the loop, planning out loud and landing the plane stay there; this guide adds only what Beads specifically does in each. Our conventions (labels, pointer epics, which tracker for what) stay in Beads conventions and workflow.
• Running example throughout: the team retreat (as in AI guide chapter 1): venue, invites, catering.

Skeleton

Opening (~8 lines + Diagram B)

• First sentence: Beads is a small task tracker that lives next to our files, built so AI agents can read and write tasks quickly. You don't use it directly; your AI does.

• Contrast story (3 lines). Old way: open Asana, click "new task", fill fields, drag a card. New way: "File these as tasks for the retreat: the venue has to be booked before invites go out." The AI creates them, links them, and shows you the list.

• One routing sentence: some teams' tasks live in GitHub or Asana; workflow says which.

• Diagram B — who reads the tracker. Right after the contrast story. Two straight columns. Adds a contrast to the AI guide's two-layer picture (cite it, don't re-explain layers).

   Most trackers                  Beads
   ─────────────                  ─────
       You                            You
        │  you click, you read         │  you talk; it shows you a view
        ▼                              ▼
   App screens                     Your AI
        │                              │  runs bd (fast, on your machine)
        ▼                              ▼
   Tasks (in the cloud)            Tasks (in the project folder)
                                       ┊
                                       ┊ you can look too: bd show, bd ready
  

1. What Beads is, and why it was built (~8–10 bullets + Diagram A)

• Trackers in three lines. A shared list of things to do, so work isn't in someone's head. Each task has a status (open, in progress, closed). Some tasks wait on others: "this waits on that". Familiar: to-do lists, Trello, Asana, GitHub issues.

• Diagram A — the one idea that matters: ready. Two task cards joined by "blocks"; caption line shows what bd ready returns.

   ┌───────────────────────┐            ┌───────────────────────┐
   │ lip-x7k.1             │   blocks   │ lip-x7k.2             │
   │ Book venue            │ ─────────▶ │ Send invites          │
   │ in progress           │            │ waiting               │
   └───────────────────────┘            └───────────────────────┘
  
   "What's ready?"  →  Book venue   (Send invites waits until it's closed)
  

• What it is. Made by Steve Yegge, announced 13 October 2025 as "a coding agent memory system"; open source; command bd. Name: issues "chained together like beads"; a single task is sometimes called a bead. Widely used by people working with AI agents (~28k GitHub stars, Oct 2026).

• The problem it solves. AI agents forget everything between sessions: "all they know is what's on disk" (Yegge). Plans kept as Markdown files multiply, go stale and contradict each other; work the agent spots along the way gets lost.

• What it is not. Yegge: "not a planning tool, a PRD generator, or Jira". Fits our two layers: the plan (reasoning, decisions) lives in Markdown reference docs; Beads holds the tasks that come out of it.

• Built for the AI, so:

  • It lives in the project folder and runs on your machine: the AI can check and update tasks constantly, fast and cheaply.
  • "What's ready?" is one command, worked out from the dependencies, so the AI can tell what's next by itself.
  • New work found mid-task gets filed and linked to where it was found, without losing the thread.
  • Each new AI session is told how to use Beads at the start, so it picks up where the last left off.

• Honest framing. Other trackers can be driven from AI too (via their APIs); Beads is built for it. The trade: almost no screens for people. That's the AI guide's point: the AI builds the views. (Community viewers exist: web boards, a Mac app, VS Code and Obsidian plugins; we don't rely on them.)

2. How to use it: talk to your AI (~half the page)

• Framing: you rarely type bd. Say what you want; the AI runs the commands and shows the result. Refer to tasks by title; let the AI find the ID (dictation mangles IDs), and ask it to show IDs so you can check.
• A real exchange (replaces old Diagram C). 5–6 turns on the retreat, showing what you say and what comes back:
  • "What's ready on the retreat?" → short table: Book venue (Sylvie, in progress), Draft agenda (unassigned, ready); Send invites waiting on venue.
  • "I'll take the agenda." → "Claimed lip-x7k.3, Draft agenda."
  • "Venue's booked: Hawkwood, 14–16 Nov. The cheaper place fell through, note that." → closes venue with a reason, adds the note; "Send invites is now ready."
  • "We still don't know about dietary needs, file that." → new task, linked as found while booking the venue.
  • "Show me what you changed in Beads this session." → list of four changes with IDs.
• Then short subsections, each: what you say → what Beads adds (link AI guide for the general routine):
  • 2.1 What's ready / what's stuck. "What's ready for me?", "What's blocked, and on whom?", "Show the retreat as a table by owner."
  • 2.2 Filing a plan as tasks. Planning itself happens in conversation and in the plan doc (AI guide §2). Beads adds: "File these under the retreat epic; venue blocks invites." Then "Show me the tree" to check structure and dependencies before agreeing.
  • 2.3 Updating as you go. Claim, close with a reason, add notes, file what you discover. One sentence each.
  • 2.4 Landing the plane: the Beads part. Routine is in the AI guide; here: close with reasons, note where to start next, file follow-ups, sync so others see it.
  • 2.5 Handing over (example, not policy). A task someone else could pick up: description, what "done" looks like, notes so far. Labelled an example; links to the AI guide's open §4.
  • 2.6 Asking about the past. "What did we close on content last week?", "Why does this task exist?"
• Phrases to copy box: 6–8, written as natural speech (voice-friendly).

3. What goes wrong, and how to check (~6 lines)

• Duplicates: "Check for an existing task before creating one."
• Wrong or missing dependencies: "Show me the tree for the retreat."
• Closed without evidence: "What's the reason on that close?"
• Colleague can't see your tasks: "Sync Beads." (sync is a step; the AI should do it at session end)
• AI refuses to close your task: your identity isn't set (see setup).
• Main check, any session: "Show me what you changed in Beads."

4. Looking yourself, and getting set up (~8 lines)

• Look yourself: bd ready, bd show <id>, bd list, bd human (short command list for people). Or ask the AI for a view: table, HTML page, graph.
• Setup, as something to say: "Install bd and set me up for Beads in this repo." Covers: install bd, set BEADS_ACTOR=<your id> (conventions), and the session-start hook that tells the AI about Beads. Note: that hook is currently in Rufus's own Claude settings, not the repo, so teammates don't get it automatically. Either add it to the repo or keep the "set me up" instruction.
• If something looks off: "Run bd doctor and explain."

Glossary (short)

• Task (also issue, bead), epic, child, dependency / blocks, ready, claim, close (with reason), note, priority (P0–P4), sync.

Sources

• Yegge, Introducing Beads (13 Oct 2025); Beads repository and docs; community tools; the AI guide; our conventions.
• Quotes were taken from search excerpts and a mirror; verify against the original post before publishing. Unverified, don't use: "50 first dates" framing; claim that Beads inspired Claude Code's task tool.

Diagram summary

Changes from v1 after critique

• Background (old §§1–4) merged into one section; how-to now ~half the page; "built for AI" plus Diagram B moved to the opening.
• Fixed the "not a planning tool" vs "planning into tasks" clash: plan in Markdown, tasks in Beads; 5.2 renamed "Filing a plan as tasks".
• Dropped overstated claims: "GitHub has no dependency graph" (GitHub added issue dependencies in 2025), "without burning tokens"; star count dated.
• Diagram A now teaches "ready", not fields; Diagram C replaced with a worked exchange.
• Cut repetition of the AI guide (landing the plane, planning out loud); kept only the Beads-specific part.
• Added "what goes wrong" section; IDs tip; name origin; routing sentence; flagged the setup-hook gap; cut storage history (JSONL → Dolt) as detail readers don't need.

Open questions for Rufus

1. Separate guides/beads.md (recommended: the AI guide aims to be tool-agnostic) or a chapter of the AI guide?
2. Setup: keep a short "say this to your AI" section here (recommended), or leave it to conventions?
3. Session-start hook: add bd prime to the repo's .claude/settings.json so teammates get it automatically?