BOI v2

Single-binary Rust harness for orchestrating LLM-powered software-engineering tasks.

✅ CANONICAL BOI (cutover complete 2026-05-24). This repo is the canonical BOI engine — TOML specs ([contract] + [[tasks]]), control-socket daemon, ~/.boi/v2/boi.db. The deployed ~/.boi/bin/boi symlinks to target/release/boi inside the machine-owned, tag-pinned clone ~/.boi/src/boi (NOT this checkout — see Deploying below) and is the supported dispatch path. Version: boi --version / Cargo.toml. v1 (YAML specs) is decommissioned — no v1 binary or checkout survives (history: docs/cutover-runbook.md).

Status: canonical engine, post-cutover. Agent entry point: AGENTS.md.

Build

Requires Rust 1.85+ (pinned via rust-toolchain.toml to floating stable, MSRV enforced via Cargo.toml's rust-version) and a C compiler (for bundled DuckDB).

cargo build --locked

For a fast dev loop without DuckDB compile cost:

cargo check --no-default-features

Dev workflow

brew install just                # if not installed
just                             # list recipes
just check                       # fmt + clippy + test + doc (the gate)
just lint-scripts                # the architecture/guardrail check suite (scripts/checks/)
just ci                          # full local CI suite
just smoke                       # build + run binary

Run

The daemon shells out to goose for LLM phases — install it and put it on PATH. Provider credentials live in ~/.boi/v2/secrets/*.env, loaded at daemon startup.

boi daemon serve                 # the boot loop (LaunchAgent rides this); start|stop|status|restart also exist
boi dispatch <spec.toml>         # parse, validate, persist, start
boi dashboard                    # watch it run

Full operator quickstart: docs/getting-started.md.

SQLx offline cache (required for the repo layer)

The repo layer uses sqlx::query! macros, which are verified against a live database at compile time. CI runs with SQLX_OFFLINE=true and reads a committed query cache in .sqlx/ — so a fresh clone builds without a database.

Regenerating that cache (only needed when a sqlx::query! macro changes) is a one-time dev-tool install plus a just recipe:

cargo install sqlx-cli --no-default-features --features sqlite,rustls
just prep-sqlx                    # creates .dev.db, migrates, writes .sqlx/

just prep-sqlx reads DATABASE_URL from a gitignored .env (DATABASE_URL=sqlite://.dev.db). Commit the resulting .sqlx/ delta in the same commit as the query change.

Deploying (release → live daemon)

This repo is GitFlow: work merges to develop; releases are cut only by the hex release cut ceremony (boi profile), which gates, bumps Cargo.toml, merges to main, tags vX.Y.Z, and back-merges to develop. Deployment is tag-pinned: the live daemon binary lives in the machine-owned clone ~/.boi/src/boi, checked out detached at the pinned tag. The chain, after a tag exists:

1. Bump BOI_VERSION to the new tag in the hex-foundation repo's VERSIONS file (this rides hex-foundation's own GitFlow/release flow).
2. Run hex-foundation's install.sh — it fetches tags, runs git checkout -f --detach vX.Y.Z in ~/.boi/src/boi, builds cargo build --release, and re-links ~/.boi/bin/boi.
3. boi daemon restart — manual, nothing automates it. Check the queue is empty first (boi dashboard); restarting mid-merge strands half-merged integration state.
4. Verify: boi --version reports the new version and git -C ~/.boi/src/boi describe --tags shows the tag.

Rollback runbook (break-glass)

If a deployed version misbehaves, downgrade immediately — do not wait on any release ceremony:

git -C ~/.boi/src/boi fetch --tags origin
git -C ~/.boi/src/boi checkout -f --detach v3.2.5   # the last known-good tag
(cd ~/.boi/src/boi && cargo build --release)
boi daemon restart

The manual checkout is the sanctioned break-glass; the hex-foundation VERSIONS re-pin is reconciliation and follows after the fact through that repo's normal release flow.

Mandatory dispatch freeze while rolled back: pre-gate tags (v3.2.5 and earlier) have neither the branch-policy gates nor the dirty-checkout merge guard — rolling back silently re-arms both hazards. While the deployed daemon is on a pre-gate tag, dispatches against GitFlow workspaces are frozen except base_branch = "develop" or feature/* targets, exactly as during the original migration window.

Architecture

Single Rust crate. Layered Domain Architecture via module structure:

src/types → src/config → src/repo → src/service → src/runtime → src/cli

Forward-only deps; enforced by scripts/checks/module-dep-audit.sh. LLM phases route through runtime::goose::GooseRuntime (invokes goose run --recipe X.yaml); deterministic phases (workspace verify, validate, commit, merge, teardown) are native Rust functions in runtime::deterministic (DETERMINISTIC_PHASES + resolve()).

Design source of truth

• docs/design/2026-05-16-design.md — main design (locked; dated amendments at top)
• docs/design/2026-05-17-goose-as-runtime-adapter.md — Goose amendment (Adopted)
• docs/research/frameworks-survey-2026-05-16.md — validates greenfield direction
• docs/plans/2026-05-19-boi-v2-implementation-plan.md — this implementation plan
• docs/plans/phase-0-team-review/99-consensus.md — 4-lens Phase-0 review consensus

License

MIT.