workbench

The home for the Go agentic-infra family — one repo, one Go module. Tools live side by side and share contracts, not call stacks: they compose at runtime through artifacts (exit codes + JSONL on disk), never by importing each other's decision code.

go install github.com/itsHabib/workbench/cmd/<tool>@latest

A taste — the local primitive classifying a CI log line on a local model (needs Ollama running), and flare's one-shot catch-up pass:

$ echo "Error: connect ETIMEDOUT registry.npmjs.org:443" | \
    env local -prompt "Classify this CI line: flake, infra, or real-break." \
              -schema '{"type":"object","properties":{"class":{"type":"string"}},"required":["class"]}'
{"source":"local","result":{"class":"infra"}}   # output varies by model; verified on qwen2.5:7b

$ flare sweep        # tail the artifact logs once, notify on anything that blocked

(env sidesteps the local builtin in bash/zsh, which otherwise shadows the binary at a top-level prompt.) Each tool's README carries its full surface — see the layout below.

Layout

• contracts/ — the shared vocabulary: the verdict schema + Go types every verifier emits, and the artifact envelope every producer writes. A leaf package that imports nothing else in the module. This is the debt payment: one source of truth instead of a hand-rolled parser per tool.
• local/ — the shared local-model mechanism: structured Ollama calls + an escalate-on-uncertainty gate. A top-level mechanism package (it carries no tool's decision logic), leaf-checked like contracts. Its faces are cmd/local (agent co-processor) and cmd/eval (the local-exportability oracle).
• cmd/<tool>/ — one binary per tool; its guts stay private under cmd/<tool>/internal/. Twelve today: console, custody, dispatch, driverstate, eval, flare, gate, local, runway, tracelens, triage (two binaries — triage-floor, triage-advisory), workbench-mcp.
• docs/DESIGN.md — the repo's charter: the single-module decision and why, what's in and out, the boundary law, the lazy-migration policy, and the triggers that would later split contracts into its own module.

Where to read, by question

The full table of contents: docs/README.md. The short version:

• What is this whole system? docs/workbench-101.md — the teaching doc: the loop, the five planes, gate as the flagship.
• Same picture, no jargon: docs/plain-language-overview.md.
• What did building it teach? docs/lessons.md — 28 rules, each with the failure that earned it, where it's enforced, and Monday bullets you can run as-is.
• How does the daily work actually run? docs/workflow-mechanics.md — the instruction stack, /drive vs the work-driver chain, review machinery, prose→code, hooks.
• How far may an agent act unattended? docs/auto-mode-defaults.md — the doctrine — and docs/auto-mode-rulebook.md, the copy-able settings + hooks that implement it.
• What do the words mean? docs/glossary.md.
• Why one module, and what's out of scope? docs/DESIGN.md — the charter.
• What else exists around this repo? docs/projects.md — the public project family (ship, dossier, rooms, tower, …).
• The skills that drive the workflow: github.com/itsHabib/skills — public, installable; this repo is what they compose against.

The one rule

A tool may share types and schemas through contracts. A tool may not import another tool's decision logic — gate importing flare's routing, a classifier importing the gate reducer. When a tool needs another tool's output, it reads an artifact. CI enforces this (hygiene job); it is not a convention.

Develop

gofmt -l . && go vet ./...
golangci-lint run ./...
go test ./...

Third-party Go dependencies are allowed.

Tenants

Each binary under cmd/<tool>/ is a tenant with its own docs. A couple worth pointing at directly:

• gate — the merge-authorization boundary: scoped, tiered, time-boxed grants, a verifier ladder, and a hash-chained decision log. Exit codes (0 pass / 1 blocked / 2 parked / 3 refused / 4 error) are the seam callers branch on.
• custody — a localhost credential broker. It holds a real vendor secret in the OS credential store and forwards a narrowly-scoped set of requests to one upstream, injecting the secret on the way out — so an agent can call an API it is never handed the credential for. Every request is a pass (injected, forwarded, logged) or a fail-closed refusal that names the command to unstick it. Wire your first key end to end with cmd/custody/docs/runbook.md.