Bee Box documentation · directory: https://beebox.run/docs/reference/cards/ · index: https://beebox.run/docs/reference/cards/index.md · root: https://beebox.run/llms.txt

# procedure Card

# Handling Procedure Definitions

Procedure cards are declarative definitions — they describe WHAT should happen, not track execution. Execution state lives in a separate procedure-run card.

Don't modify a procedure card while a run is active. The engine reads the definition at run start. Changes during execution won't be picked up and may cause confusion.

Each entry in `steps` has optional phases: `precheck` (should this step run?), `run` (the main action), `validate` (did it work?). Each phase groups its actions by kind:

- `shells:` — a list of bash commands run in the box root. Gates a `validate`
  on a non-zero exit (objective check).
- `agents:` — a list of `{ prompt, model?, max-turns? }` invocations through the box's configured agent engine.
- `instructions:` — a list of natural-language success criteria, **model-judged**
  in a `validate` phase against the step's git diff. A failing verdict gates by
  the phase `severity` exactly like a failing `shells:` check. Put objective,
  cheap checks in `shells:`; use `instructions:` for judgment a shell can't make.
- `whys:` — a list of explanations (for humans, fixing agents, and review models);
  also handed to the instruction judge and to a `review` retry as context.

Use YAML block scalars (`|`) for multi-line shell scripts and agent prompts so indentation is preserved. `precheck.pass-output: true` passes precheck stdout into the run phase. `validate.severity` is warn (log a completed check's negative result and continue) / abort (fail the step) / review (re-invoke the run agent with the failure context to self-heal, then fail the step if it still doesn't pass — needs exactly one run agent). If the agent engine cannot produce a usable response or judge verdict at all, the step fails regardless of severity and records the engine error. `model` is a portable tier: `efficient`, `balanced`, `strong`, or `strongest`; the engine maps it to its own model family. Existing `haiku`/`sonnet`/`opus`/`fable` values remain aliases. `validate.model` defaults to `balanced`.

Optional `run-expiry` / `failed-run-expiry` override how long this procedure's finished run dirs are kept before `bbx procedure gc` deletes them (defaults: 30d completed, 90d failed). Value is a duration ("60d", "12w") or "never".