Bbs

BBS (Bulletin Board System) Skill

Overview

BBS is The Fold's CAS-native issue tracker built on block primitives. All issues are content-addressed, with full history preserved in the store.

Use BBS for:

• Creating and tracking issues (bugs, features, tasks, epics)
• Finding available work (unblocked issues)
• Managing dependencies between issues
• Reviewing issue history and status

Quick Reference

Instructions

Listing Issues

# List open issues (default)
./fold "(bbs-list)"

# List closed issues
./fold "(bbs-list 'status 'closed)"

# List all issues regardless of status
./fold "(bbs-list 'status 'all)"

Viewing Issues

# View issue details
./fold "(bbs-show 'fold-001)"

# Search issue titles
./fold "(bbs-find \"auth\")"

# Search titles AND descriptions (more comprehensive)
./fold "(bbs-search \"authentication\")"

# Show unblocked work (ready to start)
./fold "(bbs-ready)"

# Show blocked issues
./fold "(bbs-blocked)"

Filtering Issues

# Filter by label
./fold "(bbs-list-by-label 'topology)"

# Filter by type (task, bug, feature, epic)
./fold "(bbs-list-by-type 'epic)"

# Get programmatic list of IDs with label (not displayed)
./fold "(bbs-by-label 'refactor)"

# Show all labels in use
./fold "(bbs-label-report)"

Creating Issues

# Basic create (just title)
./fold "(bbs-create \"Fix authentication bug\")"

# With priority (0=critical, 2=medium, 4=backlog)
./fold "(bbs-create \"Urgent fix\" 'priority 0)"

# With type (task, bug, feature, epic)
./fold "(bbs-create \"Add dark mode\" 'type 'feature)"

# Full creation with all options
./fold "(bbs-create \"Refactor auth\" 'description \"Detailed description here\" 'priority 1 'type 'task 'labels '(core security))"

Updating Issues

# Update status
./fold "(bbs-update 'fold-001 'status 'in_progress)"

# Change priority
./fold "(bbs-update 'fold-001 'priority 0)"

# Add labels
./fold "(bbs-update 'fold-001 'labels '(urgent core))"

# Update description
./fold "(bbs-update 'fold-001 'description \"New description\")"

Closing Issues

# Simple close
./fold "(bbs-close 'fold-001)"

# Close with reason
./fold "(bbs-close 'fold-001 'reason \"Fixed in commit abc123\")"

Managing Dependencies

# fold-001 blocks fold-002 (fold-002 depends on fold-001)
./fold "(bbs-dep 'fold-001 'fold-002)"

# What blocks this issue?
./fold "(bbs-blockers 'fold-002)"

# What does this issue block?
./fold "(bbs-blocking 'fold-001)"

# All unblocked open issues (ready for work)
./fold "(bbs-ready)"

History & Statistics

# Show version history for an issue
./fold "(bbs-history 'fold-001)"

# Database statistics
./fold "(bbs-stats)"

Field Reference

Priority Levels

Issue Types

Status Values

Examples

Example 1: Typical Bug Fix Workflow

# Find the bug
./fold "(bbs-find \"auth\")"

# Check details
./fold "(bbs-show 'fold-042)"

# Start working on it
./fold "(bbs-update 'fold-042 'status 'in_progress)"

# ... fix the bug ...

# Close it
./fold "(bbs-close 'fold-042 'reason \"Fixed token refresh logic\")"

Example 2: Creating a Feature with Dependencies

# Create the main feature
./fold "(bbs-create \"Add export functionality\" 'type 'feature 'priority 1)"
# Returns: fold-100

# Create sub-tasks
./fold "(bbs-create \"Design export API\" 'type 'task)"
# Returns: fold-101

./fold "(bbs-create \"Implement CSV export\" 'type 'task)"
# Returns: fold-102

# Set up dependencies (design must complete before implementation)
./fold "(bbs-dep 'fold-101 'fold-102)"

# Main feature blocked by implementation
./fold "(bbs-dep 'fold-102 'fold-100)"

Example 3: Finding Available Work

# What's ready to work on?
./fold "(bbs-ready)"

# Get stats overview
./fold "(bbs-stats)"

# See what's currently blocked
./fold "(bbs-blocked)"

Example 4: Triaging Issues

# List all open issues
./fold "(bbs-list)"

# Bump priority on critical item
./fold "(bbs-update 'fold-050 'priority 0)"

# Add labels for categorization
./fold "(bbs-update 'fold-050 'labels '(security urgent))"

Example 5: Finding Related Work by Label

# See what labels exist
./fold "(bbs-label-report)"

# Find all topology-related issues
./fold "(bbs-list-by-label 'topology)"

# Find all epics to see big-picture work
./fold "(bbs-list-by-type 'epic)"

# Deep search in descriptions
./fold "(bbs-search \"homology\")"

Notes

• Issue IDs: Can be symbols ('fold-001) or strings ("fold-001")
• Auto-initialization: BBS initializes automatically when the REPL starts
• CAS Storage: All issues are content-addressed in .store/
• Head files: Current issue state tracked in .store/heads/bbs/
• Counter: Issue counter in .bbs/counter

Pipeline Integration

BBS effects are available in agent pipelines (lattice/pipeline/effects.ss):

(bbs-create "title")              ; Create issue, return ID
(bbs-create-full title desc type priority)
(bbs-update id updates-alist)     ; Update issue fields
(bbs-close id)                    ; Close issue
(bbs-ready)                       ; Get unblocked issues
(bbs-show id)                     ; Get issue details

File Locations