2buildDocumentationGitHub
2build / DocumentationRead Markdown (.md) View source

Foreman execution

Team now has a shared project evaluator behind its CLI and the dashboard's Project tab. It checks the accepted scope, child verification, integrated product, delivery and cleanup before issuing a completion receipt. A heartbeat or a worker's DONE message cannot issue that receipt.

Start and resume

Use /bbs:team for a project. The existing parent design checkpoint remains; --auto delegates that review. Team writes project.json before approval, binds each accepted seed to a child, and uses Autopilot gate evidence for code work. Changes to the accepted contract invalidate its approval and integrated evidence.

sh
bbs team snapshot PARENT --json
bbs team readiness PARENT --action dispatch --json
bbs team readiness PARENT --action finish --json

Read data.ready and the reasons in the response. A zero exit status means the read succeeded; it does not mean the project is ready. Snapshot reads do not change ticket state. Open the parent ticket in bbs dashboard --server to see the same criteria, blockers, worker progress and delivery observations.

The full contract, evidence and progress formats are in the execution reference. Workers use the verification producer to capture the current revision before a check and archive its actual results. Do not convert old verdict prose into typed evidence: a child checkpoint from before schema_version: 2 is refused until bbs autopilot checkpoint --refresh --ticket <id> migrates it; then rerun its gates.

Delivery and recovery

  • A code child's succeeded bbs team task done snapshots its uncommitted tree on a hidden ref; there is no seal step. bbs team integrate snapshots any edit made after it (a QA fix), and removed worktrees do not erase the snapshot. Nothing recorded goes stale.
  • One code child owns one repository. Split cross-repository work into dependent children; final verification names every affected repository surface.
  • Each phase is composed into one commit (bbs team integrate) and QA'd on exactly that commit; bbs team land then fast-forwards local base to it. The last phase's run is the final integration. Product review uses a separate evaluator identity. Capture the tested runtime revision for preview links.
  • bbs team complete PARENT --foreman ID checks readiness and cleanup again, then writes the receipt and <parent>/recap.html — a self-contained page of the team lead's report.md (its ## Recap first) plus phases, phase commits and changed files, releases, acceptance coverage and tickets. The team lead's terminal stays open afterwards; bbs team recap PARENT re-renders the page. Landing on local base, push and release are reported separately.
  • For documentation/research projects, explicitly approve artifacts_only; the child reports its workflow's durable outputs with task done --artifacts. Production commits cannot use this shortcut.

Structured progress advances when recorded evidence changes. Wait reports need a reason and an expiry within 15 minutes. Terminal output, a recent heartbeat and a reported wait are separate observations; none proves that an agent is alive or authorizes reclaiming its resources. A project deadline stops new starts while allowing already verified work to finish.

Evidence and limits

Regression fixtures exercise false completion, stale scope/revisions/logs, missing coverage, failed checks, crash retries, cleaned worktrees, artifacts-only delivery, watcher behavior and API parity. Browser QA covers the actual dashboard with deterministic local ticket data, including failure/retry and mobile layout.

These checks establish the execution contract. They do not establish a live model quality or cost improvement. The independent product evaluator is a Builder pilot; compare representative projects before expanding it. Track accepted completion, escaped defects, interventions, repeated work, recovery, time to the first usable journey and provider usage coverage. Missing usage remains unknown. Orca continues to own agent dispatch; no new scheduler or service is introduced.