Skip to content

docs: add missing workflow features and regenerate llms-full.txt#3250

Open
seanmartinsmith wants to merge 1 commit intogastownhall:mainfrom
seanmartinsmith:fix/3244-workflow-docs-gaps
Open

docs: add missing workflow features and regenerate llms-full.txt#3250
seanmartinsmith wants to merge 1 commit intogastownhall:mainfrom
seanmartinsmith:fix/3244-workflow-docs-gaps

Conversation

@seanmartinsmith
Copy link
Copy Markdown
Contributor

Problem

website/static/llms-full.txt is generated from the versioned docs, but the source docs in website/versioned_docs/version-1.0.0/workflows/ are missing documentation for features that are fully implemented in the Go source. Agents relying on llms-full.txt for context conclude these features do not exist.

Verified 0 hits in llms-full.txt for: swarm, convoy, cook, extends, condition, loop, squash, burn, promote, for_each.

Root Cause

The generation script (scripts/generate-llms-full.sh) works correctly - it picks up all files. The gap is in the source markdown files themselves, which were written for an earlier version of the workflow system and never updated as features shipped.

Fix

Updated 3 workflow docs and regenerated llms-full.txt:

formulas.md (+205 lines of content):

  • Convoy formula type (multi-agent coordination) - from internal/formula/types.go TypeConvoy
  • Formula inheritance (extends field) - from Formula.Extends in types.go
  • Conditional steps (condition field) - from Step.Condition and FilterStepsByCondition
  • Loop/iteration (count, range, until) - from LoopSpec struct in types.go
  • Runtime expansion (on_complete with for_each) - from OnCompleteSpec in types.go
  • bd cook command (compile-time vs runtime modes) - from cmd/bd/cook.go
  • Expanded gate types and aspect composition

wisps.md (rewritten):

  • Squash lifecycle (bd mol squash - promote to persistent) - from cmd/bd/wisp.go lines 56, 532
  • Burn lifecycle (bd mol burn - delete without trace) - from wisp.go line 57, 305
  • Garbage collection (bd mol wisp gc) - from wisp.go GC subcommand
  • Corrected storage model: wisps use Ephemeral=true in main DB, not separate .beads-wisp/ directory
  • Updated commands to match actual CLI surface (bd mol wisp not bd wisp)

index.md (expanded command table):

  • Added swarm commands (validate, create, status, list) - from cmd/bd/swarm.go
  • Added cook, squash, burn, gc, bond, formula list commands

llms-full.txt: Regenerated via scripts/generate-llms-full.sh (6070 -> 6275 lines).

Test Plan

  • All new terms searchable in regenerated llms-full.txt: swarm (8), convoy (4), cook (14), extends (2), condition (16), loop (12), squash (9), burn (9), promote (6), for_each (2)
  • scripts/generate-llms-full.sh runs cleanly (verified)
  • No broken internal links in updated docs
  • Docusaurus build succeeds

Context

Closes #3244. Source of truth for all additions is internal/formula/types.go (848 lines), cmd/bd/swarm.go (1192 lines), cmd/bd/cook.go (1047 lines), and cmd/bd/wisp.go (832 lines).

@codecov-commenter
Copy link
Copy Markdown

codecov-commenter commented Apr 13, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

@seanmartinsmith seanmartinsmith force-pushed the fix/3244-workflow-docs-gaps branch from 6e5dc72 to fe68884 Compare April 15, 2026 13:33
Add documentation for features implemented in Go source but missing
from the website docs:

formulas.md:
- Convoy formula type (multi-agent coordination)
- Formula inheritance (extends field)
- Conditional steps (condition field with truthy/negated/equality)
- Loop/iteration (count, range, until with max)
- Runtime expansion (on_complete with for_each)
- bd cook command (compile-time vs runtime modes)
- Expanded gate types and aspect composition

wisps.md:
- Squash lifecycle (bd mol squash - promote to persistent)
- Burn lifecycle (bd mol burn - delete without trace)
- Garbage collection (bd mol wisp gc)
- Corrected storage model (Ephemeral=true in main DB)
- Updated commands to match actual CLI surface

index.md:
- Added swarm commands (validate, create, status, list)
- Added cook command
- Added wisp lifecycle commands (squash, burn, gc)
- Added bond and formula list commands

Regenerated website/static/llms-full.txt via scripts/generate-llms-full.sh.

Before: 0 hits for swarm, convoy, cook, extends, condition, loop,
squash, burn, promote, for_each in llms-full.txt.
After: all terms present with substantive documentation.

Closes gastownhall#3244
@seanmartinsmith seanmartinsmith force-pushed the fix/3244-workflow-docs-gaps branch from fe68884 to 0b5e5b2 Compare April 17, 2026 15:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

llms-full.txt missing post-1.0 features: swarm, convoy, cook, MEOW, NDI, formula inheritance, wisp lifecycle

2 participants