builder

README

builder

The day-0 agentic development harness for togo — and a blueprint you scaffold new projects from.

One command gives you a running Go + TanStack app with a public landing page, JWT/RBAC auth and a seeded admin, an empty dashboard, and — floating over every page — a draggable feedback button. A report becomes an issue on a kanban board. A triage agent classifies it. An orchestrator claims it under a fenced database lease and delegates it to a specialist from a fleet you generated by handing over a plan. That agent runs as a real Claude Code session in an isolated workspace and writes a verdict; the runner, never the agent, derives the facts, runs the gates and opens the PR.

npx create-togo-builder@latest acme     # no Go, no togo installed
togo builder new acme                   # via togo's external command dispatch
togo-builder new acme                   # standalone binary

Status

Phase 0 — foundation. What is real today:

db/migrations/0001_builder_init.sql	30 tables, 9 enums, 70 indexes. Verified against Postgres 14
internal/authz	Wildcard-aware permission checks. togo's Can() is an exact match, so permissions=["*"] denies everything
internal/db/seeders	Idempotent admin seeder — togo ships no way to get a first admin
internal/runner	20 preflight probes; gh auth, claude auth and a live claude -p execution probe are non-skippable
internal/vault	AES-256-GCM with AAD bound to the row identity, so a copied ciphertext fails to decrypt
blueprint/_claude	The shipped agent operating system — rules, agents, skills, guard hooks

Later phases: the issue plane and feedback widget (1), the orchestrator and fleet (2), memory drivers (3), notifications and human-in-the-loop (4).

togo-builder doctor          # run the 20 preflight probes
togo-builder doctor --json   # the same report the setup wizard consumes

The claim mechanism

The concurrency control is one SQL statement — no queue, no broker, no advisory lock. Two runners racing for the same issue cannot both win, because the outer AND status='ready' is a compare-and-swap and RowsAffected() != 1 means you lost.

Three exclusions are enforced by the database rather than by convention:

• human_only = true — agents never claim it
• attempt_count >= max_attempts — a failing issue stops burning budget
• a pending decision on the issue — the human-in-the-loop gate is a NOT EXISTS join, so an agent waiting on an answer is structurally unclaimable

builder_decisions additionally carries CREATE UNIQUE INDEX … WHERE state = 'pending', so an issue can never accumulate two open questions.

Six providers, one install target

togo install togo-framework/builder resolves exactly one togo.plugin.yaml, so builder ships as one repo and one module — but registers six independent kernel providers (vault, brain, notify, issues, fleet, orchestrator). Each is disableable today:

BUILDER_DISABLE=vault,brain togo serve

and extractable to its own repo tomorrow. That property is the point; six repos on day one would mean six release pipelines and a cross-repo version graph before anything runs.

Configuration

Variable	Meaning
DATABASE_URL	Postgres 16+. Falls back to the SQLite dev DSN
BUILDER_VAULT_KEY	32 bytes, base64 or hex. openssl rand -base64 32. Required — a missing key is fatal at boot rather than at first secret read
BUILDER_ADMIN_EMAIL	Seeded administrator
BUILDER_ADMIN_PASSWORD	Non-interactive seeding. There is deliberately no default and no generated-and-printed password
BUILDER_EXEC	local | coder. local is refused outside local development
BUILDER_CLAUDE_BIN	Path to the claude binary
BUILDER_DISABLE	Comma-separated provider short names

Development

go build ./...
go test ./internal/...

# The seeder test needs a real database; it skips without one.
createdb builder_dev
psql -d builder_dev -f db/migrations/0001_builder_init.sql
TEST_DATABASE_URL="postgres://$USER@localhost:5432/builder_dev?sslmode=disable" go test ./internal/db/seeders/

Two things worth knowing before you extend this

Never pass --bare to Claude Code here. It refuses OAuth entirely and accepts only an API key, so it is incompatible with the subscription auth the preflight verifies.

A client-side hook is not a merge gate. guard-merge-gate.sh constrains the agent's own shell, not the GitHub API. The real control is branch protection with required review and required status checks — the hook is defence in depth.

License

MIT

Building from a clone

The plugin module builds normally:

go build ./...

builderd/ — the standalone daemon — does not yet. Its go.mod carries replace directives pointing at sibling checkouts, because the togo plugins it depends on (auth, auth-dev, db-postgres, realtime) are not published yet. It builds inside a workspace that has those repositories side by side, and will build from a clone once they are tagged.

The in-process plugin build has no such dependency and is unaffected.

Documentation

Overview

Package builder is the togo day-0 agentic development harness: a feedback widget, an issue plane, an orchestrator that claims issues under a fenced database lease and delegates them to a fleet of Claude Code agents, per-agent memory, and an audited secret vault.

On `togo install togo-framework/builder` this package is blank-imported into the host app, so init() registers the providers with the kernel.

Six providers register independently so each can be disabled at boot (BUILDER_DISABLE=vault,brain) and extracted to its own repo later without touching the others. That property — independently disableable today, independently extractable tomorrow — is why they are separate providers rather than one monolithic Provide().

Index

• Constants
• Variables
• func AssetFiles() (fs.FS, error)
• func SDKFiles() (fs.FS, error)

Constants

const (
	ProviderVault        = "builder.vault"        // no deps; secrets other providers read
	ProviderBrain        = "builder.brain"        // reads vault for driver tokens
	ProviderIssues       = "builder.issues"       // the issue plane + HTTP surface
	ProviderFleet        = "builder.fleet"        // agent registry + .claude/ sync
	ProviderOrchestrator = "builder.orchestrator" // claim/lease/route/triage
	ProviderNotify       = "builder.notify"       // realtime + push + sound
	ProviderSources      = "builder.sources"      // scheduled ingestion into the brain
)

Provider names. Each is a separate kernel provider with its own priority so boot order is explicit rather than emergent.

const BlueprintVersion = "0.1.0"

BlueprintVersion is stamped into a generated project's togo.yaml so `togo-builder blueprint upgrade` knows which template the project came from and which migrations it has already seen.

It is deliberately separate from Version: the plugin can be patched without changing what a fresh scaffold produces, and a blueprint can change without forcing every installed app to upgrade the plugin.

const Name = "builder"

Name is the plugin's stable identifier.

Variables

var Version = "dev"

Version is the plugin module version. Set by the release build via -ldflags "-X github.com/togo-framework/builder.Version=$TAG"; "dev" locally.

Functions

func AssetFiles

func AssetFiles() (fs.FS, error)

AssetFiles returns the asset tree rooted at "/", ready for http.FileServer.

func SDKFiles

func SDKFiles() (fs.FS, error)

SDKFiles returns the bundle rooted at "/", ready for http.FileServer.