Claude Code Build System

Build System

*A deterministic issue-to-PR controller with bounded AI workers and two human gates.*

This project began as the companion to [Claude Code Is a Build System, Not a Chatbot](https://vinny.dev/blog/2026-04-25-claude-code-build-system/). Version 3 keeps the useful harness workflows, but moves authority out of model prompts and into a provider-neutral controller.

**Version:** 3.0.0 · **Platforms:** macOS and Linux · **License:** MIT

**Explore the system:** [Open the interactive Signal Ledger explainer](https://static.vinny.dev/build-system-explainer.html) to trace the seven custody handoffs, switch harness profiles, inject failure scenarios, and inspect the evidence chain.

[Getting started](docs/getting-started.md) · [Choose a tier](docs/adoption.md) · [GitHub setup](docs/github-setup.md) · [Customize](docs/customizing.md) · [Architecture](docs/architecture.md) · [Harness compatibility](docs/harness-compatibility.md)

What the system guarantees

A GitHub issue becomes a versioned work contract. A bounded Claude or Codex worker may propose a plan or edit ordinary files inside a unique worktree. The controller—and only the controller—claims work, validates Gate 1, checks paths and Git state, runs configured verification, commits, pushes, opens the PR, confirms the platform postcondition, moves labels, and writes evidence.

Three rules shape the design:

1. The model proposes; the controller disposes. Workers receive no GitHub token and no Git/GitHub delivery tools.
2. Approval binds exact bytes. Contract, plan, base commit, and delivery commit are connected by digests and immutable SHAs.
3. Unknown is unsafe. Missing branch protection, ambiguous state, stale approval, failed verification, or provenance drift stops delivery.

Gate 1 approves the plan. Gate 2 is the protected merge, kept human and enforced by repository rules. Atomic remote Git-ref leases prevent local and hosted schedulers from claiming the same issue. Crash reconciliati