Bead submission guidelines

Beads are the fleet's unit of work. A good bead is specific, routed, dependency-aware, and testable enough for an agent to complete without rediscovering the whole problem.

Minimum quality bar

Specific title: concise is fine; avoid vague placeholder phrases.
Substantive description: symptom, proposal, and acceptance criteria when available.
Valid dependencies: real bd-xxxxxx identifiers only; no placeholder dependency names.
Useful labels: area, surface, severity, or epic labels that help route the work.
Considered priority: P0 for outages, P1 for fleet-blocking work, P2 default, P3 polish, P4 nice-to-have.

Validator behavior

Class	Examples	Outcome
Hard error	Empty title, overlong title, malformed dependency, `<UNKNOWN>`	Always rejected
Soft warning	Vague title with no concrete identifier	Rejected unless `--force` is intentional

Useful description shape

## Symptom
What was observed, where, and why it matters.

## Proposal
One or more candidate fixes or implementation paths.

## Acceptance criteria
- [ ] Testable outcome
- [ ] Docs or operator-visible behavior updated
- [ ] Validation path named

Shell-safe CLI filing

For Markdown-heavy bead bodies, prefer --description-file, --description-stdin, or a quoted heredoc (<<'EOF') instead of inline shell quoting. Do not put text containing backticks, $variables, or $(...) into a double-quoted --description: the shell can perform command substitution before caco bd create receives the text, accidentally running expensive or destructive commands. If validation warns that a description looks shell-substitution damaged, for example reports but with the command evidence missing, re-file with file/stdin input or pass --force only after confirming the missing evidence is intentional.

cat <<'EOF' | caco bd create \
    --title "Fix flaky queue" \
    --description-stdin \
    --priority 2
## Symptom
Markdown examples like `cargo clippy` and $(literal text) stay literal here.
EOF

Quick-file surfaces

The webapp's quick-file modal (b shortcut), the TUI's quick-file popup (b, see), and the native macOS app's global plain b / Command-K “Quick-file bead” action route through the daemon's beads/expand LLM endpoint, which structures freeform text into one or more validated beads. The TUI popup uses Ctrl+Y to submit, Enter for newlines, Ctrl+K to clear, Ctrl+N to consolidate into exactly one bead, and Ctrl+S to ask for five varied suggested beads from available project context. The macOS sheet keeps optional expansion context collapsed by default and exposes Copy IDs / Copy show commands after creation. The validator runs on every API submission.