Skip to main content

Engine Overview

Broski has two task modes:

  • Graph mode: staged, cached, deterministic, output-validated.
  • Interactive mode: direct workspace execution with inherited TTY.

Determinism Contract​

Graph tasks must declare inputs and outputs. The runner fingerprints relevant execution state, including:

  • command
  • resolved variables and parameters
  • explicit environment keys
  • input file content hashes
  • mode/isolation metadata

What is validated before execution​

  • dependency graph must be resolvable
  • task names cannot collide with reserved CLI command names
  • required tools can be checked via @requires
  • graph-mode tasks rely on declared contracts (@in, @out) for deterministic reuse

Operational trade-offs​

  • interactive mode gives terminal-first UX, but bypasses graph caching
  • graph mode gives deterministic reuse, but requires explicit contracts
  • strict isolation may require host capabilities not available in every local environment

Use: