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".