Builder Garage
← Learn

Install and build from source

View source ↗

An Agentic Engineering System for Builders

Builder Garage is an open-source, project-embedded, extensible agentic engineering framework: a system of engineering practices, standards, architecture, roles, contracts, and workflows for responsible software construction with AI agents.

Project status

Builder Garage is at its foundation stage.

What exists today is the initial garage command-line foundation and the project's engineering documentation: the reusable engineering skills, the operating model and review contract they implement, the engineering principles and history behind them, and governance and contribution process.

The CLI can display help and version information, initialize, upgrade, validate, show, and change a project's .garage/config.yaml, record private developer-local workflow events, install and verify the canonical skills and the manuals a project adopts at a project's harness targets, and show the read-only workflow status of an issue or pull request from GitHub. It does not execute workflows, configure agents, connect to AI providers, load plugins, or provide remote services. No library, adapter, SDK, release automation, or runtime for the conceptual components has been implemented.

Architectural direction

The approved direction is recorded in docs/architecture.md. In summary:

  • Project-embedded. Builder Garage is meant to operate from inside the project it serves, alongside that project's repository, issues, and pull requests, rather than as a separate hosted service.
  • CLI-first. The garage command-line interface is the primary interface. Libraries, adapters, and potentially independent or distributed execution may follow.
  • Extensible. Projects that adopt it are expected to adapt and extend it.
  • Single repository, initially.
  • Evolutionary. Detailed design decisions are made through discovery within the lifecycle of the change that needs them, not in advance.

The garage CLI

Capabilities

The initial executable provides these entry points:

Command Behavior
garage --help Describes Builder Garage and lists the available commands.
garage version Reports the build version. install.sh and make build derive it from Git tags, for example v0.1.0; a plain go build reports dev. See Versions.
garage init Creates or upgrades .garage/config.yaml in the current project directory. See Project configuration.
garage config validate Checks .garage/config.yaml against the configuration schema, read-only, and reports every problem.
garage config show, get Show every setting in plain language, or print one setting's value.
garage config set, unset, add, remove Change one setting, validated against the complete configuration, confirmed, and written atomically.
garage record Records a private workflow event, such as an implementation handoff or a review verdict, in this developer's local history. See Local workflow history.
garage skills install, garage skills verify Install or update the canonical skills embedded in the binary, and the manuals the project adopts, at the project's declared harness targets, and check them read-only. See Skill installation.
garage status Shows the workflow status of one issue or pull request, read once from GitHub. See Workflow status.

Project configuration

.garage/config.yaml is the sole canonical source of a project's configured choices. Its project section holds the project's values at the extension points the extension-point registry declares. Its tooling section holds Garage tooling settings, which grant no workflow authority. The format and lifecycle are in Project configuration.

  • Required values. Some choices have no default: discovery applicability, and the Workflow Owner, change acceptor, and product-intent acceptor. Otherwise each must be given as a flag, and init fails and writes nothing if one is missing. garage init --help lists every flag.
  • Guided setup. In an interactive terminal, garage init walks through each choice in plain language when it creates a configuration, with numbered menus and each default shown. It asks only about choices that no flag supplies. It explains the human responsibilities, lets you reuse an authority you already named, and rejects placeholder answers such as ROLE. When upgrading an existing configuration, it asks only for missing required values. Either way it shows a summary and writes only after you confirm.
  • Upgrade in place. Running garage init again keeps every existing value and comment, adds only missing settings, and migrates a schema version 1 file to version 2. It never overwrites a configured value, and there is no --force. If the existing file is invalid, init stops without changing it and explains the correction required.
  • Validation. garage config validate checks the schema and every mechanically checkable value. It does not certify that a configured authority is human, or anything about agents or workflow state.
  • Reading and changing settings. garage config show lists every setting in plain language with its name, and garage config get prints one value. set, unset, add, and remove change one setting, using init's flag names and formats, for example garage config set integration-branch main or garage config add manual go. Each change is validated against the complete configuration and shown for confirmation; outside a terminal it needs --yes. A change that would leave the configuration invalid is refused, and comments on untouched settings are kept. The commands never commit, push, or open pull requests. Details are in Project configuration.

Builder Garage's own configuration is generated by garage init and validated in CI; see its skill-adoption profile.

Local workflow history

garage record keeps a private, best-effort annotation of what a developer's agents did:

garage record --issue 39 --type implementation --outcome ready \
  --url https://github.com/OWNER/REPO/issues/39#issuecomment-123
  • Private and local. Events are stored in the user cache directory, keyed to the repository, and are never written inside the repository or sent anywhere. The command works without GitHub access.
  • Bounded. At most 500 events are kept per repository.
  • Minimal. Only a timestamp, the repository key, the issue or pull request number, the event type, the outcome, an optional link to the durable GitHub record, and an optional artifact identity are stored. Branch names, prompts, conversation text, diffs, file contents, environment values, and tokens are not.
  • Not evidence. GitHub Issue and pull request records are authoritative. Local history never authorizes, blocks, or advances work, and losing it loses nothing that matters.
  • Best effort. If an event cannot be recorded, garage record prints a warning and still exits successfully.
  • Safe to run concurrently. Recordings to the same repository's history, from separate processes, clones, or worktrees, take turns through an operating-system lock on a file beside the history, so each keeps its event. If the history stays locked for 5 seconds, the event is not recorded and a warning is printed. The lock serializes only these local writes; it never coordinates agents or workflow.

Run garage record --help for the accepted event types and outcomes. The design is recorded in the #19 decision.

Workflow status

garage status 48 shows the workflow status of issue or pull request #48 in the repository's GitHub repository, including closed and merged ones:

  • GitHub is the authority. Status reads GitHub once, through the gh command, and writes nothing. Garage never stores a token. It never polls or waits, and it never assigns, invokes, or advances an agent. The next eligible action it shows is information only.
  • Evidence, labeled. Each line names its source and basis. A fact read from GitHub, or a comparison of recorded values, is checked. A verdict or a claim of separate execution contexts is asserted. A pull request head's artifact identity is recomputed only when the commit is already local. Nothing is fetched. In a partial clone, where git fetches missing objects on demand, status does not recompute and says so.
  • Whose records count. A workflow record counts only when its author's GitHub association is owner, member, or collaborator. A record edited after posting is flagged. Human acceptance is evidenced only by an approving GitHub review. These rules are recorded in the #40 decision.
  • Degrades clearly. Without gh, or without gh authentication, status says that GitHub was not consulted, reports no workflow state, and exits with an error. Local history is shown as a separate annotation, and is never used for any gate.

Build from source

Source builds require Go 1.27.4, the version declared in go.mod. Compiled executables are standalone and do not require a Go installation at run time.

Versions

garage follows Semantic Versioning, starting at v0.1.0. Versions are Git tags; no release artifacts are published yet (ADR 0002).

install.sh and make build derive the version garage version reports from the checkout:

Checkout Reported version
Exactly at a version tag, with no local changes The tag, for example v0.1.0
Commits after the tag Git's descriptive form, for example v0.1.0-3-gabc1234
No version tag reachable, for example a shallow clone without tags The abbreviated commit, for example abc1234
Local changes, untracked files included Any of the above with -dirty appended
No Git metadata, for example an extracted source archive dev

Set VERSION to override it, for example make build VERSION=1.2.3 or VERSION=1.2.3 ./install.sh. A plain go build derives nothing and reports dev, unless a version is supplied at link time, as in Build by hand.

Install from source

On macOS and Linux, the supported way to install garage is to build it from a checkout with install.sh:

git clone https://github.com/bdonaldharris/builder-garage.git
cd builder-garage
./install.sh
garage version

The installer builds garage with the same flags as make build, and installs it in ~/.local/bin. To install it somewhere else, use --install-dir PATH. It reports the version derived from the checkout, as described under Versions; set VERSION to override it, as with make build. Running it again, for example after git pull, upgrades the installed binary in place.

  • It may create the install directory. It never edits shell startup files or PATH. When the install directory isn't on PATH, it says what to add.
  • It stops, and installs nothing, when the Go version in go.mod isn't available. It never lets Go download a toolchain.
  • Apart from Go's own build and module caches, and a temporary build directory it removes, it writes nothing outside the install directory: not the checkout, and not any project.
  • It does not install skills. Skills are installed separately, per project, with garage skills install.

Installing a published release is deferred until release automation exists (#69). A Windows installer is a separate follow-up; on Windows, build with go build as below.

Build by hand

Clone the repository, then build from its root:

go build ./cmd/garage
./garage --help
./garage version

A plain go build reports dev. To supply a version without adding a metadata framework:

go build -ldflags "-X main.version=1.2.3" ./cmd/garage
./garage version

The Makefile provides the same build, and derives the version from Git tags as described under Versions unless VERSION is set:

make build
make build VERSION=1.2.3

Initialize another project

Run the compiled executable from the root of the project you want to initialize:

cd /path/to/project
/path/to/garage init

In a terminal, init guides you through each choice and asks you to confirm a summary before writing. To supply the values noninteractively instead:

/path/to/garage init --discovery implementer-judgment \
  --workflow-owner "lead maintainer" --change-acceptor maintainer \
  --product-intent-acceptor "Workflow Owner"
/path/to/garage config validate

This creates /path/to/project/.garage/config.yaml. Running init again leaves a complete configuration unchanged.

Develop and validate

The repository uses Go's standard testing package. The focused checks are:

go test ./...
go vet ./...
make fmt-check

Run the full local validation, including a native build and cross-compilation:

make check

Exercise the source installer, which installs only into temporary directories:

sh .github/scripts/test-install.sh

make cross writes executables for macOS, Linux, and Windows on amd64 and arm64 to dist/. On environments without make, the underlying commands are standard go test, go vet, gofmt, and go build commands; see Makefile for the exact cross-compilation matrix. Pull requests run the same categories of validation in GitHub Actions, with tests on Linux, macOS, and Windows.

Current limitations

  • There are no published releases or installation packages yet. Versions are Git tags only (Versions). garage installs from source with install.sh, on macOS and Linux only; installing a published release is deferred until release automation exists.
  • GoReleaser is an approved future direction, but it is not configured.
  • The CLI initializes, shows, and changes configuration, records local workflow history, installs and verifies skills and the manuals a project adopts, and shows read-only workflow status only. It does not implement Workbench, Crew, Inspection, or Shipping capabilities, and its only Manuals capability is delivering adopted manuals to agents as skills.
  • garage status needs the gh command, installed and authenticated, to read GitHub.
  • The canonical skills read .garage/config.yaml only through garage config validate, so an agent needs a garage binary on its PATH to resolve a configured value; install.sh puts one there. The configuration configures no agents, plugins, providers, or remote services.

An engineering discovery journey, built in public

This repository documents an ongoing effort to discover, test, and refine practical engineering standards for building software with AI agents. It is being shared publicly so the journey is visible—not just its eventual conclusions.

The practices here emerge from real software construction: investigating systems, implementing changes, independently reviewing work, correcting defects, preparing releases, and examining where the process succeeds or fails. Lessons become candidate standards; candidate standards are tested against subsequent work and revised when the evidence warrants it.

This is working engineering material, not a finished framework or a claim that every question has been settled. Expect ideas to evolve, decisions to be revisited, and gaps to be documented. The repository captures both what the current operating model requires and why it has developed that way.

The central question is not simply how to generate software faster with AI. It is how builders can retain engineering judgment, accountability, and reliable control of the software they construct while working with AI agents.

The repository contains reusable engineering skills, operating contracts, documented standards, engineering principles, and project history. Those artifacts are shared to make the reasoning and evolution of the practices inspectable and useful to other builders. They are not a substitute for evaluating the needs, constraints, and risks of a particular system.

Inside the Garage

Builder Garage is the home for an evolving, builder-centered engineering system. Its shop vocabulary organizes responsibilities without replacing precise technical terminology or existing engineering contracts. The five shop areas are the framework's conceptual components.

Shop area Responsibility
Workbench Reusable engineering skills, workflows, procedures, and tools.
Crew Distinct engineering agents with explicit responsibilities and handoff boundaries.
Inspection Independent reviews, tests, acceptance verification, and quality gates.
Shipping Pull request integration, release readiness, deployment requirements, and promotion.
Manuals Maintained technical guidance for designing and building with a particular technology, beginning with the Go Manual.

This is a conceptual map, not a required directory hierarchy or a new orchestration mechanism. Existing skill names, paths, invocation aliases, role boundaries, durable Issue/PR records, review contracts, and approval gates remain authoritative. The Garage can adopt automation selectively as practical needs and resources allow.

Each shop area's directory currently contains documentation of its responsibility and boundary. The Manuals directory also contains the baseline manuals themselves, which are guidance, not configuration, and embed.go, which embeds them in the garage binary so that garage skills install can deliver the ones a project adopts. No other shop area contains an implementation. Builder Garage's own adoption of the Go Manual is recorded in docs/go-manual.md.

Operating model

The engineering system separates responsibilities deliberately:

  • Issue/PR = what + durable workflow history/state — change-specific requirements, acceptance criteria, scope, constraints, implementation/discovery context, and the structured execution record produced by the agents.
  • Skill = how — reusable workflow rules, role responsibilities, review boundaries, correction flow, reporting requirements, scope control, and recurring DO NOT instructions.
  • Prompt = action/location — identify what should happen, where, and which skill to use.
  • Agent comments = structured execution state and historical record — concise workflow-state comments make later agent invocations resumable without reconstructing context from chat history.

The current repository/PR artifact remains authoritative for what actually exists. Workflow-state comments record what agents did, found, and decided; they do not override source state.

When an agent is already operating in the correct repository workspace, ordinary prompts should stay extremely concise and should not duplicate issue content, prior workflow history, or workflow rules.

Examples:

Implement FE #1510 using application-implementation-workflow
Review FE #1510 using indep-review
Correct FE #1510 using application-implementation-workflow
Re-review FE #1510 using indep-review
Assess FE #1510 using readiness-workflow
Discover FE #1510 using eng-discovery
Review PR #1501 using pr-review

Structured workflow-state comments use recognizable markers so agents can identify the latest relevant state without assuming the newest GitHub comment is the one that matters:

[AGENT #1 — IMPLEMENTATION]
[AGENT #1 — CORRECTION]
[AGENT #2 — INDEPENDENT REVIEW]

Agents should read the governing Issue/PR, identify the latest relevant workflow-state comment for the current phase, inspect the current artifact, perform the skill-defined work, and write the resulting state back to the governing artifact.

For Agent #2 review, the durable record is mandatory. Agent #2 performs two distinct review sequences:

  • Implementation review → write [AGENT #2 — INDEPENDENT REVIEW] to the originating Issue. Agent #2 reviews the complete implementation before it is proposed as a pull request: the uncommitted working tree by default, or a pushed commit under commit-stage review. The issue record is the authoritative record of that review, and it governs whether the implementation may advance.
  • PR review, when a PR-review trigger applies → write [AGENT #2 — INDEPENDENT REVIEW] to the PR itself. The PR record is supplemental. It never replaces the issue-recorded implementation review. The canonical skills define two minimum PR-review triggers: the PR cannot be shown to be artifact-equivalent to the latest Agent #2-approved artifact, or an optional automated reviewer has reported findings on the current head. A project may record additional triggers. Approvals rest on recorded artifact equivalence, not on head-SHA identity. When no trigger applies, the PR proceeds on the issue-recorded review and the remaining merge gates.

The Agent #2 invocation is not complete until that durable comment has been successfully written and verified. A review returned only in the agent response does not satisfy the workflow. If the durable write fails, Agent #2 must report the failure rather than claim the review state was recorded.

Agent identity and role boundaries

The Crew describes who does the work:

  • Human authorities make accountable decisions.
  • Technicians perform bounded work: discovery, readiness, planner, implementer, and reviewer.
  • Agent #1 and Agent #2 are workflow positions in the implementation and review sequence. Today the implementer fills Agent #1 and the reviewer fills Agent #2.

Whichever Technicians fill the positions, the same execution context never both implements and independently reviews the same artifact.

Agent #1 and Agent #2 are distinct agents.

They are not personas, modes, phases, or interchangeable responsibilities of one agent.

A skill invocation establishes the executing agent's identity for that execution, and that identity remains fixed until the invocation ends.

  • Agent #1 — Implementation Agent owns implementation, correction, implementation validation, artifact preparation, PR creation/finalization, and other implementation-side integration work assigned by the workflow.
  • Agent #2 — Independent Review Agent owns independent complete-artifact review, disposition of implementation findings and of any automated-review findings, and approval/rejection under the governing three-question contract.

A transition between Agent #1 and Agent #2 requires a separate agent invocation. Agent #2 runs in its own execution context, such as a separate session or thread. It may use the same tool or model as Agent #1, but it never shares Agent #1's implementation context.

Reaching another agent's responsibility is a terminal handoff boundary, not permission for the current agent to assume that role. The current invocation ends at that boundary; it must not wait, poll, monitor, sleep/retry, or autonomously continue when the future state appears.

The role-specific workflow-state markers are owned by their corresponding agent:

  • Agent #1 may write [AGENT #1 — IMPLEMENTATION].
  • Agent #1 may write [AGENT #1 — CORRECTION].
  • Agent #2 may write [AGENT #2 — INDEPENDENT REVIEW].

An agent must never create a workflow-state comment representing the other agent.

The normal stop/handoff model is:

Agent #1
→ implementation
→ READY FOR AGENT #2 REVIEW
→ STOP

separate Agent #2 invocation
→ independent complete-artifact review
→ write [AGENT #2 — INDEPENDENT REVIEW] to governing Issue/PR
→ verify durable record exists
→ APPROVED or CHANGES REQUIRED
→ STOP

if correction is required:

separate Agent #1 invocation
→ correction
→ READY FOR AGENT #2 RE-REVIEW
→ STOP

Review authority comes from the Agent #2 role and its durable record, not from tool choice. Codex or any other automated reviewer is optional review input where a project uses one. Implementation review requires no GitHub-hosted agent reviewer and no particular vendor integration.

An automated reviewer, such as Codex, is a review input, not Agent #2. Its review does not constitute independent Agent #2 review, its severity does not control disposition, and its returning no findings does not authorize Agent #1 to declare approval. When it reports findings, they trigger an Agent #2 PR review. Posting an Agent #2 PR Review Request is a terminal Agent #1 handoff: Agent #1 stops immediately and does not wait or poll. Only a separately invoked Agent #2 using independent-implementation-review may produce an Agent #2 disposition.

When automated findings exist, Agent #2's durable review comment explicitly accounts for every material finding with a concise identification, independent disposition, and reason tied to the three-question contract. Not applicable is used only when no applicable automated findings exist.

If Agent #2 requires correction, Agent #1 corrects and Agent #2 re-reviews the complete corrected artifact. Yes -> No -> Yes = APPROVED — MERGE is the final substantive correction approval for a PR review. Agent #1 may then commit/push only the exact reviewed artifact, verify artifact equivalence, and proceed to merge when the remaining gates pass. No further review is requested unless implementation code changes after Agent #2 approval; in that case, the changed artifact returns to Agent #2 review.

Skill shorthand

Shorthand is an invocation alias only. The canonical skill remains the single source of workflow truth.

Shorthand Canonical skill
implement-workflow application-implementation-workflow
indep-review independent-implementation-review
readiness-workflow implementation-readiness-workflow
eng-discovery engineering-discovery-workflow
pr-review integration-pr-review
author-issue issue-authoring-workflow

Skills

Canonical reusable engineering procedures live under skills/.

  • application-implementation-workflow (implement-workflow) — Executes as Agent #1 — Implementation Agent and governs scoped implementation/correction, durable Issue/PR workflow-state comments, environment/deployment requirement handoff, coherent issue-bound corrections, review handoff boundaries, the issue-recorded review as the authoritative review record, a supplemental Agent #2 PR review only when triggered, Agent #2-owned correction approval, artifact-equivalent finalization, and intentionally boring promotion.
  • engineering-discovery-workflow (eng-discovery) — Governs evidence-based investigation of existing software systems before implementation, including capability classification, cross-layer tracing, gap analysis, and durable discovery reporting. Discovery is not complete until the complete report is recorded in the originating GitHub issue or in an accessible durable artifact directly linked from that issue, and the documentation has been verified.
  • implementation-readiness-workflow (readiness-workflow) — Determines whether a defined change is sufficiently understood to implement responsibly by resolving material architectural, contract, data, authorization, integration, validation, and scope questions before coding begins.
  • independent-implementation-review (indep-review) — Executes as Agent #2 — Independent Review Agent and defines the narrow three-question review contract, complete-artifact review, required verified durable Issue/PR disposition comments, bounded sibling-state review, the supplemental PR-review procedure, and auditable independent disposition of every material automated-review finding. Agent #2 never performs implementation/correction work, and its invocation is not complete until the governing Issue/PR record has been successfully written and verified.
  • issue-authoring-workflow (author-issue) — Executes as the planner Technician. It authors a GitHub issue from durable evidence or a durable decision, and only with the Builder's explicit authorization. It checks for duplicates read-only, resolves the repository's template or Garage's fallback, confirms the full draft, and records the authoring role and evidence (Issue authoring). An authored issue never authorizes implementing it. The discovery, implementation, and review skills author their own follow-ups from their own records, under the same procedure.
  • integration-pr-review (pr-review) — Executes as Agent #1 — Implementation Agent for PR-side integration/finalization responsibilities. It governs durable PR workflow-state comments, artifact equivalence with the issue-approved change, the PR-review triggers and the role-based Agent #2 PR Review Request, hard Agent #2 disposition boundaries, required verified Agent #2 disposition on the PR itself when a PR review occurs, Agent #2-owned final correction approval, Environment / Deployment Requirements gating, and merge convergence without a post-correction review loop. Automated reviewers are optional input.

Engineering principles

docs/principles.md separates the principles the skills and governance already require from evidence-backed candidate principles, which are not requirements, and from unresolved hypotheses. docs/history.md records the engineering lineage those principles came from.

Review contract

Application implementation review asks:

  1. Was the issue acceptance criteria met?
  2. Did the implementation introduce a new bug or regression?
  3. Does the implemented behavior work?

Yes -> No -> Yes means approval. For an integration PR, it means merge once required CI and human approval are satisfied.

Non-blocking review observations belong in the application repository's persistent Application Improvement Suggestions backlog rather than automatically becoming standalone issues.

Application engineering should follow the relevant skill and durable GitHub workflow-state record rather than relying on conversational memory or ad hoc prompt reconstruction.

Contributing

Builder Garage is maintainer-led and community-contributed. Contributions are welcome.

A substantive change passes two distinct gates: independent engineering review before it is proposed as a pull request, and maintainer approval of the pull request before it is merged. Neither replaces the other.

Contributors

Builder Garage was founded by B Donald Harris and is built with its community. Everyone whose contribution is merged is a contributor and is recognized in the repository's contributors list.

License

Builder Garage is released under the MIT License, copyright © 2026 B Donald Harris. The license permits use, modification, and redistribution, including in proprietary derivative works.