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

bash
1# List open issues (default)
2./fold "(bbs-list)"
3
4# List closed issues
5./fold "(bbs-list 'status 'closed)"
6
7# List all issues regardless of status
8./fold "(bbs-list 'status 'all)"

Viewing Issues

bash
1# View issue details
2./fold "(bbs-show 'fold-001)"
3
4# Search issue titles
5./fold "(bbs-find \"auth\")"
6
7# Search titles AND descriptions (more comprehensive)
8./fold "(bbs-search \"authentication\")"
9
10# Show unblocked work (ready to start)
11./fold "(bbs-ready)"
12
13# Show blocked issues
14./fold "(bbs-blocked)"

Filtering Issues

bash
1# Filter by label
2./fold "(bbs-list-by-label 'topology)"
3
4# Filter by type (task, bug, feature, epic)
5./fold "(bbs-list-by-type 'epic)"
6
7# Get programmatic list of IDs with label (not displayed)
8./fold "(bbs-by-label 'refactor)"
9
10# Show all labels in use
11./fold "(bbs-label-report)"

Creating Issues

bash
1# Basic create (just title)
2./fold "(bbs-create \"Fix authentication bug\")"
3
4# With priority (0=critical, 2=medium, 4=backlog)
5./fold "(bbs-create \"Urgent fix\" 'priority 0)"
6
7# With type (task, bug, feature, epic)
8./fold "(bbs-create \"Add dark mode\" 'type 'feature)"
9
10# Full creation with all options
11./fold "(bbs-create \"Refactor auth\" 'description \"Detailed description here\" 'priority 1 'type 'task 'labels '(core security))"

Updating Issues

bash
1# Update status
2./fold "(bbs-update 'fold-001 'status 'in_progress)"
3
4# Change priority
5./fold "(bbs-update 'fold-001 'priority 0)"
6
7# Add labels
8./fold "(bbs-update 'fold-001 'labels '(urgent core))"
9
10# Update description
11./fold "(bbs-update 'fold-001 'description \"New description\")"

Closing Issues

bash
1# Simple close
2./fold "(bbs-close 'fold-001)"
3
4# Close with reason
5./fold "(bbs-close 'fold-001 'reason \"Fixed in commit abc123\")"

Managing Dependencies

bash
1# fold-001 blocks fold-002 (fold-002 depends on fold-001)
2./fold "(bbs-dep 'fold-001 'fold-002)"
3
4# What blocks this issue?
5./fold "(bbs-blockers 'fold-002)"
6
7# What does this issue block?
8./fold "(bbs-blocking 'fold-001)"
9
10# All unblocked open issues (ready for work)
11./fold "(bbs-ready)"

History & Statistics

bash
1# Show version history for an issue
2./fold "(bbs-history 'fold-001)"
3
4# Database statistics
5./fold "(bbs-stats)"

Field Reference

Priority Levels

Issue Types

Status Values

Examples

Example 1: Typical Bug Fix Workflow

bash
1# Find the bug
2./fold "(bbs-find \"auth\")"
3
4# Check details
5./fold "(bbs-show 'fold-042)"
6
7# Start working on it
8./fold "(bbs-update 'fold-042 'status 'in_progress)"
9
10# ... fix the bug ...
11
12# Close it
13./fold "(bbs-close 'fold-042 'reason \"Fixed token refresh logic\")"

Example 2: Creating a Feature with Dependencies

bash
1# Create the main feature
2./fold "(bbs-create \"Add export functionality\" 'type 'feature 'priority 1)"
3# Returns: fold-100
4
5# Create sub-tasks
6./fold "(bbs-create \"Design export API\" 'type 'task)"
7# Returns: fold-101
8
9./fold "(bbs-create \"Implement CSV export\" 'type 'task)"
10# Returns: fold-102
11
12# Set up dependencies (design must complete before implementation)
13./fold "(bbs-dep 'fold-101 'fold-102)"
14
15# Main feature blocked by implementation
16./fold "(bbs-dep 'fold-102 'fold-100)"

Example 3: Finding Available Work

bash
1# What's ready to work on?
2./fold "(bbs-ready)"
3
4# Get stats overview
5./fold "(bbs-stats)"
6
7# See what's currently blocked
8./fold "(bbs-blocked)"

Example 4: Triaging Issues

bash
1# List all open issues
2./fold "(bbs-list)"
3
4# Bump priority on critical item
5./fold "(bbs-update 'fold-050 'priority 0)"
6
7# Add labels for categorization
8./fold "(bbs-update 'fold-050 'labels '(security urgent))"

Example 5: Finding Related Work by Label

bash
1# See what labels exist
2./fold "(bbs-label-report)"
3
4# Find all topology-related issues
5./fold "(bbs-list-by-label 'topology)"
6
7# Find all epics to see big-picture work
8./fold "(bbs-list-by-type 'epic)"
9
10# Deep search in descriptions
11./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):

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

File Locations