Manage agent behavior

Use this guide when a convention is relevant to only part of a project or an enabled rule seems absent. Prerequisites: an initialized Bee profile, reachable MongoDB, the intended repository, and a supported hook integration. The service-backed examples below are verified against help and source; they were not executed against a live shared store.

1 · Select a persona locally

Choose an existing persona after reviewing its definition:

bee soul list
bee soul show reviewer
bee soul use reviewer
bee soul show

Replace reviewer with a name from list. use writes this machine profile’s choice; definitions remain shared. show reports the selection source. clear removes the local selection and may expose the legacy shared soul.active fallback again; it does not mean “disable all persona context.” A missing name returns 1; an unknown verb returns 4 in an initialized profile. claim additionally claims the shared definition for the machine, so it is not needed merely to choose a persona.

2 · Give a rule the narrowest useful delivery

This example creates a project rule for Vue component work:

bee hook rule add "Review keyboard navigation when changing a component" --path 'src/**/*.vue'
bee hook rule list --json

The add command prints a short ID and scope; the JSON list gives the full ID for later operations. The path keeps the rule out of ordinary per-prompt blocks and selects it for matching file guidance. A saved rule does not install a hook. session, prompt and always apply at different hook surfaces; --global changes project selection, not delivery timing. See rule scope and globs.

3 · Preview a change before applying it

For an existing rule, replace <id> with its full ID. Copy the preview’s before.revision into the apply command:

bee hook rule rescope <id> --scope file --path 'src/**/*.vue' --dry-run --json
bee hook rule rescope <id> --scope file --path 'src/**/*.vue' --revision <before-revision> --json

A dry run exits 0 when valid and reports wouldChange; changed and applied remain false. The after value is proposed, not saved. Applying with a stale revision exits 8. Re-read a preview and decide again; do not blindly remove the revision guard. File paths replace the previous list. Moving back to prompt requires --clear-paths. Invalid input exits 4; ambiguous IDs exit 7; an unknown write outcome exits 5 and needs read-back.

4 · Archive a rule, then restore it deliberately

Use current IDs and revisions from the list/preview; <revision> is a value to replace, not a constant:

bee hook rule archive <id> --revision <revision> --reason "Convention replaced" --json
bee hook rule list --archived --json
bee hook rule restore <id> --revision <revision> --json

Archive suppresses delivery while retaining text, scope, paths and attribution. Restore preserves the original enabled state; restoring a disabled rule does not enable it. The archived list omits rule text. rm is permanent deletion. Archive, restore and rescope select this project by default; use --global only for an existing global rule.

5 · Explain missing guidance

bee budget "Review component keyboard navigation" --path src/App.vue --by-item --json
bee steering --surface pre-tool --since 1h --limit 20 --json

The budget preview attributes UTF-16 characters and estimates tokens; it is not a delivery receipt. Steering reads local observations of shortened/excluded instructions, with lower-bound counts. An empty ledger does not prove delivery, and a rendered hook block does not prove model adherence. If the rule is absent, check archive/enabled state, project, path match, hook installation and omission counts in that order. File rules need a harness surface that actually asks Bee for file guidance.

Rules reference · Steering filters and limits · Context size · Collaboration delivery evidence