Beads

When to use

• A .beads/ directory exists.
  • If unsure: rg --files -g '.beads/**' --hidden --no-ignore.
• The user asks for bd commands (bd ready, bd create, bd close, bd sync, …).
• The user wants beads to act as a work ledger (plan/progress/decisions recorded during implementation).

Principle: bead as work ledger

• The active bead is the canonical place for plan, progress, decisions, and verification.
• Prefer recording facts into the bead over long chat narration; the bead must survive session resets.

Molecules (workflow steps as beads)

A molecule is how beads turns “do this work” into a durable, stepwise workflow.

• Formula: workflow source file (discover via bd formula list).
• Proto: cooked template epic (solid phase).
• Mol: persistent instantiation of a proto (liquid phase) created by bd mol pour.
• Wisp: ephemeral instantiation (vapor phase) created by bd mol wisp.

In a mol, each step is a real bead, so “log per step” becomes natural.

Per-step ledger contract (mol step beads)

For each step bead you complete:

1. Ensure notes has current Now/Next/Blockers/Verify.
2. Add exactly one Markdown ChangeLog comment (template below).
3. Close the step with an outcome-focused reason.

Recommended close reason:

• bd close <step-id> --reason "Implemented: <one-line behavioral outcome>"

Workflow loop (implementation-aware)

1. Prime context: bd prime.
2. Pick the work:
   • bd ready (general)
   • bd ready --mol <mol-id> (within a molecule)
   • bd mol current <mol-id> (where am I in this molecule?) Then bd show <id>.
3. Start/claim: bd update <id> --claim (or bd update <id> --status in_progress).
4. Seed a mini-plan (rolling):
   • `bd update --notes "$(cat <<'EOF'

Status

• Now: …
• Next: …
• Blockers: …

Verification

• # expected: EOF )"`

5. Implement in small slices; after each slice, add a durable log entry:
   • bd comments add <id> "…"
   • Update --design when you make a real decision.
   • Update --acceptance when you learn/clarify verification.
6. Close with an outcome-focused reason: bd close <id> --reason "…".
7. Sync when appropriate: bd sync.

What to record during implementation

notes (rolling status board)

• Keep short and current; overwrite freely.
• Best for: Now/Next/Done, blockers, the current verification command(s).

Comments (append-only timeline)

• Use comments for incremental planning and “what changed” snapshots.
• Recommended comment types:
  • Checkpoint: what you just did + next.
  • Decision: decision + rationale + alternatives.
  • Patch summary: paths changed + the behavioral delta.
  • Verification: command(s) run + success/failure signal.
  • Handoff: current state + what to do next.

Example:

bd comments add bd-123 "$(cat <<'EOF'
Checkpoint: tighten parser guardrails
- Changed: src/foo.rs (parse), src/foo_test.rs (cases)
- Decision: reject empty input early
- Verify: cargo test -p foo  # pass
EOF
)"

design (durable decisions)

• Keep longer-lived architecture notes here so they don’t get lost in the scrollback.
• Update when a decision is made:
  • `bd update --design "$(cat <<'EOF'

Decisions

• …

Alternatives

• …

Invariants / gotchas

• … EOF )"`

Discoveries (scope control)

• File newly discovered work as new beads, don’t silently expand scope.
  • bd create "..." --type=task --priority=2
• Link it back so it’s traceable:
  • bd dep add <new-issue> <current-issue> -t discovered-from

Alternate uses (beyond tickets)

Encode “what changed” without pasting diffs

• After any meaningful slice (or before handoff/close), add a ChangeLog comment.
• Goal: a new session can answer “what changed?” and “what’s left?” in 30 seconds.

Template (Markdown-only, high-signal, no diffs):

bd comments add <id> "$(cat <<'EOF'
ChangeLog
- Intent: <what this step was trying to accomplish>
- Files: <paths, short list>
- Behavior: <what is now true / user-visible change>
- Risk: <regressions to watch>
- Verify: <exact command>  # <pass/fail>
- Next: <next concrete action>
EOF
)"

Optional add-ons when they exist:

• Commit: <sha>
• PR: <url>

Beads as agents (first-class workers)

Gas Town treats agents as beads so liveness/state is queryable and durable. You can adopt this pattern in any repo that uses beads.

Conventions (so you can find these across repos):

• Create one agent bead per durable identity.
• Always set labels that make lookup easy:
  • agent (broad)
  • agent:<name> (stable lookup key)
  • role:<role> (polecat/crew/witness/refinery/mayor/deacon)

Create:

bd create --type=agent --role-type=polecat --agent-rig <rig> \
  --labels agent,agent:<name>,role:polecat \
  --title "<name>"

Find later:

• bd list --label agent:<name> --all
• bd search "agent:<name>"

As the agent works, keep its state current:

• bd agent state <agent-id> working|stuck|done
• bd agent heartbeat <agent-id>

Track orthogonal operational dimensions (creates an event + caches label):

• bd set-state <agent-id> health=healthy|failing --reason "..."
• bd set-state <agent-id> mode=normal|degraded --reason "..."

Monitor progress across agents/issues in real time:

• bd activity --follow (add --town if you use routing)

Command quick reference

• bd prime — load AI-optimized workflow context.
• bd ready — list unblocked work.
• bd show <id> — inspect issue details.
• bd create "Title" --type=task --priority=2 — create a new issue.
• bd update <id> --claim — atomically claim and start work.
• bd update <id> --notes ... — update rolling status/plan.
• bd comments add <id> ... — append progress log entries.
• bd update <id> --design ... — update durable decisions.
• bd update <id> --acceptance ... — keep verification criteria correct.
• bd dep add <id> <depends-on> -t discovered-from|blocks|tracks|related|... — link issues.
• bd lint [id...] — check missing template sections.
• bd set-state <id> <dimension>=<value> --reason "..." — event + cached label state.
• bd agent state <agent-id> <state> — update agent state + last_activity.
• bd agent heartbeat <agent-id> — update last_activity only.
• bd activity --follow — watch live progress.
• bd close <id> --reason "..." — close with outcome + signal.
• bd sync — sync beads with git remote (typically end of session).

Safety notes

• bd hooks install, bd init, bd config set ..., and bd sync mutate the repo (and/or git history); ask first unless explicitly requested.