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.
The API has two layers:
- Data functions return values (alists, lists, booleans) — use these programmatically
- Print functions (suffixed with
!) display formatted output — use these at the REPL
Quick Reference
Data API (returns values)
| Function |
Returns |
Example |
bbs-get |
Issue alist or #f |
(bbs-get "fold-001") |
bbs-ready |
List of unblocked IDs |
(bbs-ready) |
bbs-blocked |
List of blocked IDs |
(bbs-blocked) |
bbs-blockers |
(id . status) pairs |
(bbs-blockers "fold-001") |
bbs-blocker-ids |
List of blocker IDs |
(bbs-blocker-ids "fold-001") |
bbs-blocking |
List of IDs this blocks |
(bbs-blocking "fold-001") |
bbs-is-blocked? |
Boolean |
(bbs-is-blocked? "fold-001") |
bbs-by-status |
List of IDs |
(bbs-by-status 'open) |
bbs-by-priority |
List of IDs |
(bbs-by-priority 0) |
bbs-by-label |
List of IDs |
(bbs-by-label 'sft) |
bbs-by-type |
List of IDs |
(bbs-by-type 'epic) |
bbs-all-ids |
All issue IDs |
(bbs-all-ids) |
bbs-labels |
All unique labels |
(bbs-labels) |
bbs-stats |
Statistics alist |
(bbs-stats) |
bbs-get-history |
List of version alists |
(bbs-get-history "fold-001") |
bbs-get-block |
Raw issue Block or #f |
(bbs-get-block "fold-001") |
bbs-issue-count |
Integer |
(bbs-issue-count) |
bbs-issue-exists? |
Boolean |
(bbs-issue-exists? "fold-001") |
Mutations (return hashes/IDs)
| Function |
Returns |
Example |
bbs-create |
Issue ID string |
(bbs-create "Title" 'priority 2 'type 'task) |
bbs-update |
New hash |
(bbs-update 'fold-001 'status 'in_progress) |
bbs-close |
Hash or #f |
(bbs-close 'fold-001 'reason "Done") |
bbs-reopen |
Hash or #f |
(bbs-reopen 'fold-001) |
bbs-comment |
Hash |
(bbs-comment "fold-001" "Note text") |
bbs-dep |
Void |
(bbs-dep 'blocker 'blocked) |
bbs-undep |
Void |
(bbs-undep 'blocker 'blocked) |
Display (print to stdout, return void)
| Function |
Example |
bbs-show! |
(bbs-show! 'fold-001) |
bbs-list! |
(bbs-list! 'status 'closed) |
bbs-ready! |
(bbs-ready!) |
bbs-blocked! |
(bbs-blocked!) |
bbs-history! |
(bbs-history! 'fold-001) |
bbs-blockers! |
(bbs-blockers! 'fold-001) |
bbs-find! |
(bbs-find! "query") |
bbs-search! |
(bbs-search! "query") |
bbs-list-by-label! |
(bbs-list-by-label! 'topology) |
bbs-list-by-type! |
(bbs-list-by-type! 'epic) |
bbs-label-report! |
(bbs-label-report!) |
bbs-gc! |
(bbs-gc!) |
Instructions
Getting Issue Data
# Get issue as alist (programmatic access)
./fold "(bbs-get \"fold-001\")"
# Returns: ((id . "fold-001") (title . "...") (status . open) (priority . 2) ...)
# Get unblocked issue IDs
./fold "(bbs-ready)"
# Get blockers with their status
./fold "(bbs-blockers \"fold-002\")"
# Returns: (("fold-001" . open) ("fold-003" . closed))
Displaying Issues (REPL)
# Display formatted issue
./fold "(bbs-show! 'fold-001)"
# List open issues
./fold "(bbs-list!)"
# List closed issues
./fold "(bbs-list! 'status 'closed)"
# Search titles + descriptions
./fold "(bbs-search! \"authentication\")"
# Show unblocked work
./fold "(bbs-ready!)"
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 and Closing Issues
# Update status
./fold "(bbs-update 'fold-001 'status 'in_progress)"
# Change priority
./fold "(bbs-update 'fold-001 'priority 0)"
# Close with reason
./fold "(bbs-close 'fold-001 'reason \"Fixed in commit abc123\")"
Managing Dependencies
# fold-001 blocks fold-002
./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)"
Field Reference
Priority Levels
| Priority |
Meaning |
| 0 |
Critical - drop everything |
| 1 |
High - do soon |
| 2 |
Medium (default) |
| 3 |
Low - when time permits |
| 4 |
Backlog - someday maybe |
Issue Types
| Type |
Use For |
task |
General work items |
bug |
Defects to fix |
feature |
New functionality |
epic |
Large multi-issue efforts |
Status Values
| Status |
Meaning |
open |
Not yet started |
in_progress |
Currently being worked |
closed |
Completed or won't fix |
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
Note: Pipeline effect names match the data API, not the display API.
File Locations
| Path |
Purpose |
.store/heads/bbs/ |
Issue head files (current hash per issue) |
.bbs/counter |
Next issue number |
.bbs/deps |
Dependency relationships |
boundary/bbs/bbs.ss |
Entry point and display functions |
boundary/bbs/store.ss |
Data accessors (bbs-get, bbs-get-history) |
boundary/bbs/ops.ss |
Mutations (create, update, close) |
boundary/bbs/index.ss |
Query index (by-status, ready, blocked) |