# Best Practices ## Start simple Begin with a single agent and omit the `orchestrator` field. Add explicit auto orchestration only once the work needs model-selected chaining or parallelisation. ## Inspect before tuning Before running, inspect exactly what the agent will receive: ```bash bento trigger inspect --prompt # the user prompt bento trigger inspect --system-prompt # the assembled system prompt bento trigger inspect --size # token breakdown ``` Most output quality problems are prompt problems, visible before the agent runs. Once a trigger exists in the store, re-run it anytime without waiting for a real event: ```bash bento trigger replay ``` When a pipeline produces poor output, read the trace: ```bash bento trace ``` The trace shows each phase — trigger, invocation, spawn — with timing and status. Agent messages are extracted from the run log. ## Invest in the knowledge base before skills Before adding a skill, verify the agent has the domain context it needs in `wiki/`, `blueprints/`, or `recipes/`. See [Knowledge Base](/knowledge-base). ## One skill per procedure A skill that does one specific thing is easier to tune, review, and reuse than one that branches across multiple cases. If a pipeline needs to do two different things depending on the trigger, write two pipelines — each with its own narrow skill. See [Context Engineering](/context-engineering). ## Start read-only, then enable write-back Before enabling a pipeline to post comments, push commits, or open PRs, run it without write credentials and review the output via `bento trace`. Add the credential mounts once you trust what the agent produces. ```yaml # start here — agent runs but cannot write back sandbox: mounts: [] # add mounts once output is verified sandbox: mounts: - host: ~/.config/gh container: /home/node/.config/gh ``` ## Always set a timeout Unbounded agent runs consume resources and can block queue slots. Every pipeline should declare a timeout: ```yaml guardrails: timeout: 300 # seconds ``` 300 s is a reasonable starting point for most pipelines. ## Scope credentials to the minimum Mount only what the pipeline actually needs. A review pipeline that posts comments does not need push access. A read-only analysis pipeline does not need any external credentials. See [Identity](/identity). ## Be intentional about workspace notes Agents can write to `notes.jsonl` during a run to pass state to the next invocation on the same target. This accumulates — stale notes from a prior run will influence future runs on the same workspace. Prune notes when a target's context has changed significantly (a PR was rebased, a ticket was reprioritised). Stale notes are worse than no notes. ## Review before you automate Run a new pipeline manually a few times via `bento trigger replay` and review each trace before letting it run unattended on real events. Verify: * The prompt contains the context you expect. * The agent's output is in scope. * Write-back (if any) produces the right artefact.