Beans (Citum)

Citum Overlay

The beans prime guide is already injected into every session — no need to call it again. Use these project-specific rules on top of it:

• Before starting work: search for an existing bean with beans list --json -S "<terms>".
• When choosing what to start next: run bash .claude/skills/beans/bin/citum-bean next, then inspect the candidate with beans show --json <id>.
• Always create beans with an explicit type (-t bug | feature | task | epic | milestone).
• Keep bean checklists current while work is in progress (- [ ] → - [x]).
• Mark completed only when all checklist items are checked.
• When completing, append a ## Summary of Changes section.
• When scrapping, append a ## Reasons for Scrapping section.
• Use upstream bean lifecycle names consistently: draft, todo, in-progress, completed, scrapped.
• When work lands on main, complete the bean in the same change series or immediate follow-up.
• Archive terminal beans promptly so completed and scrapped beans do not remain at .beans/ root.
• When bean state changes, run bash .claude/skills/beans/bin/citum-bean hygiene before push.
• If hygiene reports a stale bean, fix the bean metadata first, then rerun hygiene.

Commit Rule

Always include the bean file in commits. Use git add -A (not selective adds) so .beans/ changes are never left out. Code changes and bean state must be committed together.

Common Patterns

Check off a checklist item (exact match required — copy text verbatim):

beans update <id> \
  --body-replace-old "- [ ] Do the thing" \
  --body-replace-new "- [x] Do the thing"

Append summary and mark complete in one shot:

beans update <id> \
  --body-replace-old "- [ ] Final step" --body-replace-new "- [x] Final step" \
  --body-append "## Summary of Changes\n\nWhat was done and why." \
  -s completed

Multiple checkbox updates atomically (use GraphQL to avoid multiple etag conflicts):

beans graphql 'mutation {
  updateBean(id: "<id>", input: {
    bodyMod: {
      replace: [
        { old: "- [ ] Step A", new: "- [x] Step A" }
        { old: "- [ ] Step B", new: "- [x] Step B" }
      ]
    }
  }) { id etag }
}'

/beans next Helper

/beans next ranks ready options using the full dependency graph and shows what is currently in progress, so you can pick without manual analysis.

Ranking: priority → leverage (how many open beans this unblocks) desc → type (bug > feature > task) → oldest first. Epics/milestones appear only when concrete work is insufficient to fill the limit.

Output includes:

• In-progress context header (what's already running)
• · unblocks N badge when completing a bean would unblock other work

bash .claude/skills/beans/bin/citum-bean next           # top 3
bash .claude/skills/beans/bin/citum-bean next --limit 5
bash .claude/skills/beans/bin/citum-bean next --json
bash .claude/skills/beans/bin/citum-bean audit --scope open
bash .claude/skills/beans/bin/citum-bean hygiene

Always run via the wrapper for recommendation and hygiene tasks. Do not use raw beans list --json --ready as the primary selector, because it skips leverage scoring, in-progress context, and stale-bean collision checks. Output the script result as plain text with no preamble or commentary.

Command Policy

• Canonical command behaviour comes from beans itself.
• Do not duplicate CLI flag docs here; use beans <cmd> --help.
• If this file conflicts with beans prime, beans prime wins.

See Also

• beans prime
• beans help
• .beans.yml
• .beans/*.md